アプリのイベント定義の構成

このトピックでは、アプリのマニフェスト ファイルでイベント定義を定義する方法について説明します。イベント定義は、どのログメッセージとトレースイベントがプロバイダーと共有されるかを定義します。

イベント定義について

イベント定義は、アプリがプロバイダーとログメッセージやトレースイベントを共有する方法を指定します。イベント定義は、プロバイダーによって設定されたログメッセージおよびトレースイベントレベルのフィルターとして機能します。プロバイダーは、新しいアプリのバージョンやパッチが公開されたときのアプリのイベント定義を指定します。

イベント定義は、ログメッセージとトレースイベントに作用するフィルターです。これらは、イベント共有が有効になっているときに、プロバイダーイベントテーブルに挿入される情報を決定します。

イベントの定義は任意です。プロバイダーがアプリのイベント定義を指定しない場合、コンシューマは、プロバイダーがイベントトレースを有効にしたときにのみ、すべてのイベントに対してイベント共有を有効または無効にすることができます。

注意

イベント定義は、プロバイダーによって設定されたログおよびトレース・レベルとは異なります。ログおよびトレース・レベルは、コンシューマー・イベント・テーブルに挿入される情報を決定します。ログレベルもトレースレベルも設定されていない場合、アプリはイベントを発行しません。

アプリのログとトレースのレベルは、コンシューマによって有効化されたイベント定義に基づいて変更できます。Snowflake は、コンシューマが有効にしたイベント定義で許可される最も冗長なログおよびトレースレベルを使用します。

必須および任意のイベント定義

プロバイダーは、イベント定義を必須またはオプションに設定できます。

  • アプリがインストールされると、必要なイベント定義が自動的に有効になります。

    必要なイベント定義を含むアプリをインストールした後、コンシューマはイベント共有または必要なイベント定義を無効にできません。アプリがアップグレードされるとき、プロバイダーは、システム関数または Python Permission SDK を使用して、コンシューマが必要なイベント定義をすべて有効にしているかどうかを確認できます。

  • オプションのイベント定義は、必要に応じて、コンシューマが有効にしたり 無効にしたりできます。

サポートされるイベント定義

以下の表は、現在サポートされているイベント定義の一覧です。

名前

説明

フィルター

All

SNOWFLAKE$ALL

アプリが発行するすべてのログメッセージとトレースイベントを共有します。

*

Errors and warnings

SNOWFLAKE$ERRORS_AND_WARNINGS

エラー、警告、致命的なイベントに関連するログを共有します。

RECORD_TYPE = ‘LOG’ AND RECORD:severity_text in (‘FATAL’, ‘ERROR’, ‘WARN’)

Traces

SNOWFLAKE$TRACES

アプリケーション内のユーザーアクティビティと移動の詳細なトレースを共有します。

RECORD_TYPE in (‘SPAN’, ‘SPAN_EVENT’)

Usage logs

SNOWFLAKE$USAGE_LOGS

ユーザーアクションとアプリイベントに関連する高レベルのログを共有します。

RECORD_TYPE = LOG AND RECORD:severity_text = ‘INFO’

Debug logs

SNOWFLAKE$DEBUG_LOGS

アプリのトラブルシューティングに使用される技術ログを共有します。

RECORD_TYPE = ‘LOG’ AND RECORD:severity_text in (‘DEBUG’, ‘TRACE’)

Metrics

SNOWFLAKE$METRICS

コンシューマーがプロバイダーと指標を共有できるようにします。

RECORD_TYPE  in (‘METRIC’)

注釈

Snowsight は、プロバイダーがイベント定義を使用するようにアプリを構成していない場合、コンシューマにすべてのイベント All タイプを表示します。

コンテナ付きアプリにおけるイベント定義の限界

Snowflake Native Apps with Snowpark Container Services 現在のところ、 ALL イベント定義のみをサポートしています。追加イベント定義のサポートは、将来のリリースで追加される予定です。

アプリのログとトレースのレベルを設定する

アプリがイベントトレースを使用できるようにするには、プロバイダーはマニフェストファイルでログおよびトレースレベルを構成する必要があります。

アプリのログとトレース・レベルを設定するには、以下の例に示すように、 manifest.yml ファイルに configuration ブロックを追加します:

configuration:
  ...
  log_level: INFO
  trace_level: ALWAYS
  metric_level: ALL
  ...
Copy

この例では、アプリのログレベルとトレースレベルを以下のように設定しています:

  • log_level プロパティは INFO に設定されている。

  • trace_level プロパティは ALWAYS に設定されている。

  • metric_level プロパティは ALL に設定されている。

これらのパラメーターに有効な値については、 LOG_LEVELTRACE_LEVEL、および METRIC_LEVEL を参照してください。

注意

アプリを公開した後、ログとトレースのレベルを変更することはできません。マニフェスト ファイルでログおよびトレース レベルが設定されていない場合、アプリは情報を出力しません。

アプリにログとトレース・レベルが設定されると、コンシューマーは、アプリが発するログ・メッセージとトレース・イベントを見るために、自分のアカウントでイベント・テーブルを設定する必要があります。

アプリが生成するログ・メッセージやトレース・イベントをプロバイダーに見せるには、コンシューマーはイベント共有を有効にする必要があります。詳細については、 Enable event sharing for an app をご参照ください。

マニフェスト・ファイルにイベント定義を追加する

イベント定義を指定するには、プロバイダーは次の例に示すように、マニフェストファイルの configuration.telemetry_event_definitions ブロックにエントリを追加します:

configuration:
  telemetry_event_definitions:
    - type: ERRORS_AND_WARNINGS
      sharing: MANDATORY
    - type: DEBUG_LOGS
      sharing: OPTIONAL
Copy

この例では、以下のイベント定義を指定します:

  • ERRORS_AND_WARNINGS 型の必須イベント定義。

  • DEBUG_LOGS 型の任意イベント定義。

詳細は 対応イベント定義 をご参照ください。

コンシューマーがアプリをインストールすると、アプリの Security ページの Events and logs タブにイベント定義が表示されます。詳細については、 Enable logging and event sharing for an app をご参照ください。

特定のオブジェクトのログレベル、トレースレベル、メトリクスレベルのセット

プロバイダーは、アプリ内の特定のオブジェクトのログ、トレース、メトリクスレベルを微調整することができます。これによりプロバイダーは、アプリから送信される遠隔測定データをよりコントロールできるようになります。

プロバイダーは、アプリ内の以下のオブジェクトのログレベル、トレースレベル、メトリクスレベルをセットできます。

  • スキーマ

  • バージョンスキーマ

  • ストアドプロシージャ

  • ユーザー定義関数

次のテーブルは、これらのオブジェクトのログ、トレース、イベントレベルをセットするために使用される SQL コマンドのリストです。

オブジェクト

コマンド

スキーマ

ALTER SCHEMA

バージョンスキーマ

CREATE OR ALTER VERSIONED SCHEMA

ストアドプロシージャ

ALTER PROCEDURE

ユーザー定義関数

ALTER FUNCTION

スキーマ、ストアドプロシージャ、およびユーザー定義関数について、プロバイダーは ALTER コマンドの SET 句を使用して、以下のプロパティをセットできます:

  • LOG_LEVEL

  • TRACE_LEVEL

  • METRIC_LEVEL

バージョン管理されたスキーマの場合、プロバイダーはセットアップスクリプトの CREATE OR ALTER VERSIONED SCHEMA を使用してこれらのプロパティをセットできます。

ログ、トレース、メトリクスレベルの優先順位

アプリ内で、ログ、トレース、およびメトリクスレベルは、アプリのコンポーネントに対して異なる方法で構成できます。発せられるイベントを決定するために、 Snowflake Native App Framework は以下の優先順位を使用します。

  • ストアドプロシージャとユーザー定義関数

    特定のストアドプロシージャまたはユーザー定義関数にオーバーライドがセットされている場合は、そちらが優先されます。

  • スキーマとバージョンスキーマ

    ストアドプロシージャまたはユーザー定義関数にオーバーライドがセットされていない場合は、スキーマおよびバージョン・スキーマのオーバーライドが優先されます。

  • アプリレベルのセット

    オブジェクトレベルのオーバーライドが見つからない場合、通常はマニフェストファイルで定義されているアプリレベルの遠隔測定構成が使用されます。