未処理の例外からのメッセージのキャプチャ

プロシージャや UDF ハンドラーで処理されなかった例外は、イベントテーブルのログやトレースメッセージとして自動的に記録されます。これらのメッセージをキャプチャするために、ログやトレースに特化したハンドラーコードを追加する必要はありません。

注釈

この機能は現在、Pythonのみで記述されたハンドラーコードに対してサポートされています。

重要

エラーメッセージには機密情報が含まれていることがあります。この機能を有効化する前に、潜在的な機密情報をイベントテーブルでキャプチャするかどうかを考慮します。詳細については、 機密データの保護 をご参照ください。

未処理の例外エントリのキャプチャを有効化する

未処理の例外からのメッセージのキャプチャを有効にするには、次を実行します。

  1. イベントテーブルの設定 の説明に従って、イベントテーブルを設定します。

  2. ENABLE_UNHANDLED_EXCEPTIONS_REPORTING パラメーターを true に設定します。

    パラメーターの設定の詳細については、 パラメーター管理 をご参照ください。

  3. Snowflakeが未処理の例外のエントリをキャプチャするように、ログまたはトレースレベルを設定します。エントリは、ログエントリ、トレースイベントエントリ、またはその両方としてキャプチャすることができます。

    1. メッセージをログエントリとしてキャプチャするには、 ログレベルERROR またはより詳細なレベルに設定します。

    2. メッセージをトレースイベントエントリとしてキャプチャするには、 トレースレベルALWAYS または ON_EVENT に設定します。

未処理の例外についてキャプチャされたデータ

未処理の例外エントリのキャプチャを有効化する に記載されたように、メッセージデータをログエントリ、トレースイベント、またはその両方としてキャプチャすることができます。キャプチャされたデータは、ログエントリとトレースイベントエントリの間で異なります。

ログエントリでキャプチャされたデータ

未処理の例外をログメッセージとしてキャプチャするように有効化 すると、Snowflake はイベントテーブルに次を記録します。

データ

RECORD 列

severity_text 属性で、その値は現在の言語ランタイムについて最も重大度が高いエラーレベルとなります。たとえば、Pythonで記述されたンドラーの場合、値は FATAL になります。

RECORD_ATTRIBUTES 列

次の属性が未処理の例外に対して記録されます。

  • exception.message -- エラーメッセージ。

  • exception.type -- 例外のクラスの名前。

  • exception.stacktrace -- 言語ランタイムによってフォーマットされた例外のスタックトレース。

  • exception.escaped -- このエントリが未処理の例外からのものである場合は、 true

VALUE 列

文字列 exception

次の例のコードは、 UDF ハンドラーからの未処理の例外に対して記録されたログデータをイベントテーブルにクエリします。

ログデータのイベントテーブルへのクエリの詳細については、 ログされたメッセージデータへのアクセス をご参照ください。

SET event_table_name = 'my_db.public.my_event_table';

SELECT
  RECORD['severity_text'] AS severity,
  RECORD_ATTRIBUTES['exception.message'] AS error_message,
  RECORD_ATTRIBUTES['exception.type'] AS exception_type,
  RECORD_ATTRIBUTES['exception.stacktrace'] AS stacktrace
FROM
  my_event_table
WHERE
  RECORD_TYPE = 'LOG';
Copy

クエリーからの可能な出力は次のようになります。

------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
| SEVERITY | ERROR_MESSAGE                                        | EXCEPTION_TYPE | STACKTRACE                                                                                                                                          |
------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
| "FATAL"  | "could not convert string to float: '$1,000,000.00'" | "ValueError"   | "Traceback (most recent call last):\n  File \"_udf_code.py\", line 6, in compute\nValueError: could not convert string to float: '$1,000,000.00'\n" |
------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

トレースイベントエントリでキャプチャされたデータ

未処理の例外をトレースイベントとしてキャプチャするように有効化 すると、Snowflake はイベントテーブルに次を記録します。

データ

RECORD 列

値が exception である name 属性と、値が STATUS_CODE_ERROR である status 属性。

RECORD_ATTRIBUTES 列

次の属性が未処理の例外に対して記録されます。

  • exception.message -- エラーメッセージ。

  • exception.type -- 例外のクラスの名前。

  • exception.stacktrace -- 言語ランタイムによってフォーマットされた例外のスタックトレース。

  • exception.escaped -- このエントリが未処理の例外からのものである場合は、 true

次の例のコードは、 UDF ハンドラーからの未処理の例外に対して記録されたトレースイベントをイベントテーブルにクエリします。

トレースイベントデータのイベントテーブルへのクエリの詳細については、 トレースデータへのアクセス をご参照ください。

スパンの例
SET event_table_name = 'my_db.public.my_event_table';

SELECT
  RECORD['status']['code'] AS span_status
FROM
  my_event_table
WHERE
  record_type = 'SPAN';
Copy

クエリーからの可能な出力は次のようになります。

-----------------------
| SPAN_STATUS         |
-----------------------
| "STATUS_CODE_ERROR" |
-----------------------
スパンイベントの例
SET event_table_name = 'my_db.public.my_event_table';

SELECT
  RECORD['name'] AS event_name,
  RECORD_ATTRIBUTES['exception.message'] AS error_message,
  RECORD_ATTRIBUTES['exception.type'] AS exception_type,
  RECORD_ATTRIBUTES['exception.stacktrace'] AS stacktrace
FROM
  my_event_table
WHERE
  RECORD_TYPE = 'SPAN_EVENT';
Copy

クエリーからの可能な出力は次のようになります。

-----------------------------------------------------------------------------------------------------------------------------------------
| EVENT_NAME  | ERROR_MESSAGE                                        | EXCEPTION_TYPE | STACKTRACE                                      |
-----------------------------------------------------------------------------------------------------------------------------------------
| "exception" | "could not convert string to float: '$1,000,000.00'" | "ValueError"   | "  File \"_udf_code.py\", line 6, in compute\n" |
-----------------------------------------------------------------------------------------------------------------------------------------

機密データの保護

処理されなかった例外のログやトレースメッセージには機密データが含まれる可能性があるため、そのデータを保護するために以下を実行することを検討します。

  • ENABLE_UNHANDLED_EXCEPTIONS_REPORTING パラメーターを false に設定することで、未処理の例外ロギングをオフにします。

  • 未処理の例外ログをオンのままにしておく場合は、次のような方法で機密データを保護します。

    • 例外処理コードを改善し、未処理の例外が発生するリスクを最小限に抑えましょう。

    • 行アクセス ポリシー をイベントテーブルに適用し、個人識別情報 (PII) を含む行へのアクセスを制限します。

    • イベントテーブルの上に ビューを作成し、 マスキングポリシー を適用して、個人を特定できる情報 (PII) をマスキングまたは削除します。