以前のログおよびイベント共有機能 --- 廃止予定

このトピックでは、イベント定義が導入される前の、ログとイベント共有をセットアップするための非推奨の方法について説明します。

ログおよびイベント共有を設定するプロバイダーは、 アプリのログとイベントトレースを使用する で説明されている方法を使用します。非推奨から新しいログおよびイベント共有機能への移行については、 以前のイベント共有機能から移行する際の注意点 をご参照ください。

警告

このトピックで説明されているログおよびイベント共有の設定プロセスは、将来のリリースでは廃止される予定です。

これまでのログおよびイベント共有機能

このトピックでは、プロバイダーとしてのログおよびイベント共有の設定に関する情報を提供します。この機能を構成するためのコンシューマーの要件については、 アプリケーションのログおよびイベント共有の有効化 をご参照ください。

ログとトレースイベントは、エラーをトラブルシューティングするための、アプリケーションに関する情報を収集することができます。ログとトレースイベントを使用すると、アプリケーションがどのように動作しているかをよりよく把握し、後でアプリケーションを改善することもできます。

プロバイダーとしてログおよびイベント共有を設定するワークフロー

プロバイダーとして、アプリケーションのログとイベント共有を設定するには、以下を実行します。

  1. ログとイベント共有を使用する際の考慮事項を確認 します。

  2. 関数とストアドプロシージャのログとトレースイベントを構成 します。

  3. マニフェストファイルでログレベルとトレースレベルを設定 します。

  4. 共有イベントを保存するアカウントを構成 します。

コンシューマーがアプリケーションをインストールし、ログとイベントの共有を有効にすると、インストールされたアプリケーションによって共有されるログとイベント情報を表示できます。

ログおよびイベント共有の使用に関する考慮事項

アプリケーションにログおよびイベント共有を使用する前に、プロバイダーは以下を考慮する必要があります。

  • プロバイダーは、データインジェスチョンやストレージなど、プロバイダー側でのイベント共有に関連するすべてのコストを負担します。

  • プロバイダーは、イベント共有をサポートする各リージョンで、 共有イベントを保存するためのアカウント を持っている必要があります。

  • プロバイダーは、マニフェストファイルで、アプリケーションのデフォルトのログレベルとトレースレベルを定義する必要があります。

注釈

イベント共有は、ベースとなるアプリケーションパッケージと同じアカウントにインストールされているアプリでは有効にできません。アプリのイベント共有をテストするには、プロバイダーは複数のアカウントを使用する必要があります。

関数およびプロシージャでログおよびトレースイベントを構成する

Native Apps Frameworkには、アプリケーション内の関数やストアドプロシージャから生成されるログメッセージやトレースイベントを格納するためにイベントテーブルが必要です。

注釈

アプリケーションのコンシューマーが、アプリケーションをインストールする前にイベントテーブルを設定してアクティブテーブルにしない場合は、イベントとログのデータが破棄されます。

アカウントは複数のイベントテーブルを持つことができますが、一度にSnowflakeアカウントのアクティブなイベントテーブルとして設定できるのは1つだけです。アクティブなイベントテーブルがないと、アプリケーションによって生成されたログメッセージやトレースイベントはキャプチャされません。これは、アプリケーションの関数やプロシージャがログやトレースイベント APIs を呼び出す場合でも同じです。

イベントテーブルを作成するには、 CREATE EVENT TABLE コマンドを使用します。詳細については、 イベントテーブルの概要 をご参照ください。

コードがログメッセージとトレースイベントを記録した後に、プロバイダーは記録されたデータをクエリできます。

ログとトレースデータの記録とクエリに関する情報については、以下をご参照ください。

マニフェストファイルでログレベルとトレースレベルを設定する

アプリケーションのバージョンに対してデフォルトのログおよびトレースイベントレベルを設定するには、次の例に示すように、マニフェストファイルで log_level および trace_level、 metric_level パラメーターを設定します。

artifacts:
  setup_script: setup.sql
configuration:
  trace_level: OFF
  log_level: DEBUG

プロバイダーがトレースを有効にすると、 Snowflake Native App はすべてのクエリとストアドプロシージャ呼び出しの開始時刻と終了時刻を自動的にキャプチャします。

注釈

trace_level プロパティが OFF 以外の値に設定された Snowflake Native App を公開すると、イベントテーブルを表示できるコンシューマーアカウントのすべてのユーザーに、非表示のストアドプロシージャへの呼び出しが公開される可能性があります。

trace_level、 log_level および metric_level でサポートされる値については、 ロギング、メトリクス、トレースのレベル設定 および ロギング、メトリクス、トレースのレベル設定 をご参照ください。

Snowflake Native App が最初にインストールされると、マニフェストファイルで定義されたログレベルが使用されます。その後のアップグレードでログレベルが変更された場合、新しいログレベルはアップグレード処理の完了後に有効になります。

ログレベルおよびトレースレベルは、マニフェストファイル内でのみ設定できます。コンシューマーは、 ALTER APPLICATION または ALTER DATABASE コマンドを使用してログレベルを変更することはできません。

同様に、ログレベルに対するセッションレベル設定は、アプリケーションによって無視されます。

共有イベントを保存するアカウントを構成する

共有ログやイベントを保存するには、プロバイダーはイベントテーブルを保持するアカウントを選択する必要があります。プロバイダーがアクセスできる任意のアカウントを選択できます。ただし、組織で複数のプロバイダーがアプリケーションパッケージを公開している場合は、コンシューマーからの共有イベントを保存する、専用のSnowflakeアカウントの使用を検討してください。

共有イベントを保存するために使用されるアカウントには、次の制限が適用されます。

  • イベントを保存するアカウントとしてアカウントをセットするには、 組織管理者ロール を使用する必要があります。

  • このアカウントには、 アクティブイベントテーブル が必要です。

  • 以下のいずれかに該当するアカウントは指定できません。

    • ロックまたは凍結アカウント。

    • リーダーアカウント。

    • 試用アカウント。

    • Snowflake管理アカウント。

注釈

プロバイダーは、コンシューマーがアプリケーションをインストールしたのと同じリージョンでのみ、ログと共有イベントを収集できます。プロバイダーは、コンシューマーがアプリケーションのイベント共有を構成するすべてのリージョンで共有イベントを保存するためのアカウントを設定する必要があります。

イベントアカウントとしてのアカウントを設定する

あるリージョンのイベントアカウントとしてアカウントを設定するには、 SYSTEM$SET_EVENT_SHARING_ACCOUNT_FOR_REGION システム関数を呼び出します。

CALL SYSTEM$SET_EVENT_SHARING_ACCOUNT_FOR_REGION('<snowflake_region>', '<region_group>', '<account_name>')

条件:

snowflake_region

アカウントがあるSnowflakeリージョンの名前（例: AWS_US_WEST_2, AWS_US_EAST_1）を指定します。

region_group

リージョングループ（例: PUBLIC）を指定します。詳細については、 リージョングループ をご参照ください。

account_name

アカウント名を指定します。指定したリージョンにイベントアカウントとして別のアカウントがすでに設定されている場合、このコマンドを実行すると、イベントアカウントはここで指定したアカウントに変更されます。Snowflakeのアカウント識別子ではなく、常にアカウント名を使用してください。

注釈

この関数を呼び出すには、 組織管理者ロール を使用する必要があります。

イベントアカウントとしてのアカウントを設定解除する

リージョンのイベントアカウントの設定を解除するには、 SYSTEM$UNSET_EVENT_SHARING_ACCOUNT_FOR_REGION システム関数を呼び出します。

CALL SYSTEM$UNSET_EVENT_SHARING_ACCOUNT_FOR_REGION('<snowflake_region>', '<region_group>', '<account_name>')

条件:

snowflake_region

アカウントがあるSnowflakeリージョンの名前（例: AWS_US_WEST_2, AWS_US_EAST_1）を指定します。

region_group

リージョングループ（例: PUBLIC）を指定します。

account_name

アカウント名を指定します。Snowflakeのアカウント識別子ではなく、常にアカウント名を使用してください。

注釈

この関数を呼び出すには、 組織管理者ロール を使用する必要があります。

プロバイダー組織のイベントアカウントを表示する

プロバイダー組織のイベントアカウントを表示するには、 SYSTEM$SHOW_EVENT_SHARING_ACCOUNTS システム関数を呼び出します。

CALL SYSTEM$SHOW_EVENT_SHARING_ACCOUNTS()

注釈

この関数を呼び出すには、 組織管理者ロール を使用する必要があります。

このシステム関数は、組織内にあるイベントアカウントのリストを含む JSON 形式の文字列を返します。メタデータがすべてのリージョンに伝搬されるには時間がかかるため、ユーザーが組織のイベントアカウントを設定/設定解除した後に最新のイベントアカウントを表示する場合、この関数には遅延が発生する可能性があります。

アプリケーションパッケージで定義されたログレベルおよびトレースイベントレベルを表示する

インストールされているアプリケーションのログレベルを表示するには、次のコマンドに示すように DESCRIBE APPLICATION コマンドを使用します。

DESC APPLICATION HelloSnowflake;

次の例に示すように、アプリケーションパッケージで定義されたアプリケーションバージョンのログレベルを表示するには、 SHOW VERSIONS IN APPLICATION PACKAGE コマンドを使用します。

SHOW VERSIONS
  IN APPLICATION PACKAGE HelloSnowflake;

イベントテーブルでログおよびイベントを表示する

イベントテーブルに格納されたログとイベントを表示するには、次の例に示すように、 SELECT コマンドを使用します。

SELECT * FROM EVENT_DB.EVENT_SCHEMA.MY_EVENT_TABLE

プロバイダーが利用できる共有イベント情報

次のセクションでは、Native Apps Frameworkがプロバイダーと共有する情報について説明します。

プロバイダーと共有するアプリケーション イベント コンテキスト

プロバイダーが共有イベントのソースを容易に識別できるように、プロバイダーと共有される際、以下のフィールドがイベントテーブルの RESOURCE_ATTRIBUTES 列に入力されます。

  • snow.application.package.name

  • snow.application.consumer.organization

  • snow.application.consumer.name

  • snow.listing.name

  • snow.listing.global_name

プロバイダーと共有されないフィールド

コンシューマー情報を保護するため、 RESOURCE_ATTRIBUTES 列の以下のフィールドはプロバイダーと共有されません。

  • snow.database.id

  • snow.database.name

  • snow.schema.id

  • snow.executable.id

  • snow.owner.name

  • snow.owner.id

  • snow.warehouse.name

  • snow.warehouse.id

  • snow.query.id

  • snow.session.id

  • snow.session.role.primary.name

  • snow.session.role.primary.id

  • snow.user.name

  • snow.user.id

  • db.user

snow.database.name および snow.query.id フィールドをプロバイダーと直接共有する代わりに、Snowflakeはこれら2つのフィールドのハッシュ値（SHA-1）を以下のフィールドとして共有します。

  • snow.database.hash

  • snow.query.hash

Snowflakeは、これらの属性をマスクするために使用される SHA-1関数 を提供します。コンシューマーは、データベース名とクエリIDのハッシュ値を計算し、プロバイダーに問い合わせる際の参照値として使用できます。

コンシューマーアカウントでイベント共有が有効になっているかどうかを確認する

状況によっては、プロバイダーは、コンシューマーアカウントでイベント共有が有効になっているかどうかを判断する必要があります。たとえば、イベントテーブルが利用できない場合、プロバイダーはアプリの機能を無効にする必要がある場合があります。

コンシューマーアカウントでイベント共有が有効になっているかどうかを判断するために、プロバイダーはアプリロジックを定義するときに次のシステム関数を呼び出すことができます。

  • IS_APPLICATION_SHARING_EVENTS_WITH_PROVIDER

    アプリがイベント共有を有効にし、アクティブなイベントテーブルがコンシューマーアカウントで利用可能な場合は TRUE を返します。それ以外の場合は FALSE を返します。

  • IS_APPLICATION_INSTALLED_FROM_SAME_ACCOUNT

    アプリが、そのベースとなるアプリケーションパッケージと同じアカウントにインストールされている場合は TRUE を返します。それ以外の場合は FALSE を返します。

注釈

これらのシステム関数はアプリ内からのみ呼び出すことができます。 Python Permission SDK を使用してイベント共有が有効になっているかどうかを確認する、および SQL を使用してイベント共有が有効になっているかどうかを確認する をご参照ください。

Python Permission SDK を使用してイベント共有が有効になっているかどうかを確認する

Python Permission SDK は、コンシューマーアカウントで共有が有効になっているかどうかを判断するために、次の機能を提供します。

  • is_event_sharing_enabled()

    SHARE_EVENTS_WITH_PROVIDER プロパティがtrueであり、コンシューマーアカウントにアクティブなイベントテーブルが構成されている場合は TRUE を返します。それ以外の場合は FALSE を返します。

  • is_application_local_to_package()

    アプリケーションがアプリケーションパッケージと同じアカウントにある場合は TRUE を返します。それ以外の場合は FALSE を返します。

SQL を使用してイベント共有が有効になっているかどうかを確認する

次の例は、コンシューマーアカウントでイベント共有が有効になっている場合にストアドプロシージャを呼び出す方法を示しています。

2つの数値の合計を計算する関数を作成する次の SQL ストアドプロシージャについて考えます。

CREATE OR ALTER VERSIONED SCHEMA app_schema;

CREATE OR REPLACE PROCEDURE app_schema.hidden_sum(num1 float, num2 float)
RETURNS FLOAT
LANGUAGE SQL
EXECUTE AS OWNER
AS $$
  DECLARE
    SUM FLOAT;
  BEGIN
    SYSTEM$LOG('INFO', 'CALCULATE THE SUM OF TWO NUMBERS');
    SUM := :NUM1 + :NUM2;
    RETURN SUM;
  END;
$$;

これらの SQL コマンドをアプリのセットアップスクリプトに追加すると、アプリのインストール時にコンシューマーアカウントに hidden_sum ストアドプロシージャが作成されます。ただし、このストアドプロシージャは、アプリケーションロールにストアドプロシージャに対する USAGE 権限が付与されていないため、コンシューマーには表示されません。

次の例は、 IS_APPLICATION_SHARING_EVENTS_WITH_PROVIDER および IS_APPLICATION_INSTALLED_FROM_SAME_ACCOUNT システム関数が返す値を使用して、 hidden_sum ストアドプロシージャを呼び出す方法を示しています。

CREATE OR REPLACE PROCEDURE app_schema.sum(num1 float, num2 float)
RETURNS STRING
LANGUAGE SQL
EXECUTE AS OWNER
AS $$
    BEGIN
      IF (SYSTEM$IS_APPLICATION_INSTALLED_FROM_SAME_ACCOUNT() or SYSTEM$IS_APPLICATION_SHARING_EVENTS_WITH_PROVIDER()) THEN
        CALL APP_SCHEMA.HIDDEN_SUM(:NUM1, :NUM2);
      ELSE
        -- notify consumers that they need to enable event sharing
        RETURN 'Sorry you can\'t access the API, please enable event sharing.';
      END IF;
    END;
$$;


CREATE APPLICATION ROLE IF NOT EXISTS ADMIN_ROLE;
GRANT USAGE ON SCHEMA APP_SCHEMA TO APPLICATION ROLE ADMIN_ROLE;

この例では、 sum ストアドプロシージャは、 IS_APPLICATION_SHARING_EVENTS_WITH_PROVIDER および IS_APPLICATION_INSTALLED_FROM_SAME_ACCOUNT ストアドプロシージャの値をテストします。それらの値の1つが true の場合、 sum ストアドプロシージャは hidden_sum ストアドプロシージャを呼び出します。

Python Permission SDK を使用してコンシューマーにイベント共有をリクエストする

プロバイダーは、 Python Permission SDK を使用してStreamlitアプリを作成し、コンシューマーに自分のアカウントでイベント共有を有効にするよう促すことができます。

SDK は、コンシューマーにアカウントでイベント共有を有効にするように求めるダイアログを Snowsight に表示する request_event_sharing() メソッドを提供します。コンシューマーアカウントにイベントテーブルが存在しない場合は、ダイアログで、コンシューマーが ACCOUNTADMIN ロールを使用している場合にイベントテーブルを設定できます。

例: Python Permission SDK とイベントテーブルを使用する

次のStreamlitの例では、 Python Permission SDK を使用して次の操作を実行する方法を示しています。

  • イベント共有が有効になっているかどうかを確認します。

  • イベント共有が有効な場合は、 critical_feature_that_requires_event_sharing() 関数を呼び出します。

  • イベント共有が有効になっていない場合は、 request_event_sharing() 関数を呼び出して、コンシューマーにイベント共有を有効にするように求めるダイアログを Snowsight に表示します。

import streamlit as st
import snowflake.permissions as permissions

def critical_feature_that_requires_event_sharing():
  st.write("critical_feature_that_requires_event_sharing")

def main():
  if permissions.is_event_sharing_enabled() or permissions.is_application_local_to_package():
     critical_feature_that_requires_event_sharing()
  else:
     permissions.request_event_sharing()

if __name__ == "__main__":
  main()

この例では、 critical_feature_that_requires_event_sharing() メソッドは次のいずれかが当てはまる場合にのみ呼び出されます。

  • イベント共有が有効になっており、イベントテーブルが存在する。

  • Snowflake Native App がアプリケーションパッケージと同じアカウントにインストールされている。

どちらの条件も真でない場合、Streamlitアプリは request_event_sharing() メソッドを呼び出し、コンシューマにイベントテーブルの選択を促します。

詳細については、 コンシューマーアカウントでイベント共有が有効になっているかどうかを確認する をご参照ください。