Snowflake Scriptingでのトレースイベントの出力¶

Snowflake SYSTEM 関数を使用すると、Snowflakeスクリプトで記述された関数またはプロシージャハンドラーからトレースイベントを出力できます。

トレースイベントを出力する前に、必要なデータがイベントテーブルに格納されるようにトレースレベルが設定されていることを確認してください。詳細については、ロギング、メトリクス、トレースのレベル設定をご参照ください。

注釈

トレースイベントの出力を開始する前に、イベントテーブルを設定する必要があります。詳細については、イベントテーブルの概要をご参照ください。

イベントテーブルで SELECT コマンドを実行すると、格納されたトレースイベントデータにアクセスできます。詳細については、トレースデータの表示をご参照ください。

Snowflakeでのログの設定とメッセージの取得に関する一般的な情報については、関数とプロシージャのイベントをトレースするをご参照ください。

注釈

トレースイベントを追加する際に留意すべきガイドラインについては、トレースイベントを追加するための一般的なガイドラインをご参照ください。

トレースイベントの追加¶

トレースイベントを追加するには、 SYSTEM$ADD_EVENT 関数を呼び出し、イベント名を渡します。オプションで、属性（キーと値のペア）をイベントに関連付けることもできます。

次の例のコードは、2つのイベント、 SProcEmptyEvent と SProcEventWithAttributes を追加します。 SProcEventWithAttributes を使用すると、コードは2つの属性、 key1 と key2 も追加します。

SYSTEM$ADD_EVENT('SProcEmptyEvent');
SYSTEM$ADD_EVENT('SProcEventWithAttributes', {'key1': 'value1', 'key2': 'value2'});

Copy

これらのイベントを追加すると、イベントテーブルに2つの行が作成され、それぞれの RECORD 列に異なる値が含まれます。

{
  "name": "SProcEmptyEvent"
}

Copy

{
  "name": "SProcEventWithAttributes"
}

Copy

SProcEventWithAttributes イベント行には、行の RECORD_ATTRIBUTES 列に次の属性が含まれています。

{
  "key1": "value1",
  "key2": "value2"
}

Copy

スパン属性の追加¶

SYSTEM$SET_SPAN_ATTRIBUTES 関数を呼び出すと、スパンに関連付けられた属性（キーと値のペア）を設定できます。

スパンの詳細については、 Snowflakeがトレースイベントを表す方法をご参照ください。

SYSTEM$SET_SPAN_ATTRIBUTES 関数の可用性は以下の通りです。

SYSTEM$SET_SPAN_ATTRIBUTES(<object>);

Copy

条件

object は、このトレースイベントの属性を指定するキーと値のペアを持つ Snowflake Scripting オブジェクトです。

次の例のコードは、2つの属性を作成し、その値をセットします。

SYSTEM$SET_SPAN_ATTRIBUTES('{'attr1':'value1', 'attr2':true}');

Copy

これらの属性を設定すると、イベントテーブルの RECORD_ATTRIBUTES 列が次のようになります。

{
  "attr1": "value1",
  "attr2": "value2"
}

Copy

例¶

次の例のコードでは、 SYSTEM$ADD_EVENT 関数を使用して、 name_a という名前のイベントと name_b という名前のイベントを追加します。 name_b では、2 つの属性 score と pass が関連付けられます。このコードは、 SYSTEM$SET_SPAN_ATTRIBUTES を使用して、スパンの2つの属性、 key1 と key2 を設定します。

CREATE OR REPLACE PROCEDURE pi_proc()
  RETURNS DOUBLE
  LANGUAGE SQL
  AS $$
  BEGIN
    -- Add an event without attributes
    SYSTEM$ADD_EVENT('name_a');

    -- Add an event with attributes
    LET attr := {'score': 89, 'pass': TRUE};
    SYSTEM$ADD_EVENT('name_b', attr);

    -- Set attributes for the span
    SYSTEM$SET_SPAN_ATTRIBUTES({'key1': 'value1', 'key2': TRUE});

    RETURN 3.14;
  END;
  $$;

Copy

CALL pi_proc();

Copy

子ジョブおよび例外のトレースイベントを自動的に発行します。¶

Snowflake Scriptingストアドプロシージャのトレースイベントは、イベントテーブルに以下の追加タイプを自動的に発行することができます。

例外のキャッチ。
子ジョブの実行情報。
子ジョブの統計。
実行時間や入力値などのストアドプロシージャの統計情報。

トレースの自動排出は、以下のような使用ケースを想定しています。

ストアドプロシージャの本文を変更することなく、定義済みのトレースイベントを発行したい場合があります。
ストアドプロシージャの実行について、後で分析できるような情報を収集したい場合があります。
- 子ジョブの実行情報（childJobUUID、 rowCount、 exceptionCode など）。
- 子ジョブの実行時間。
- 入力引数の値。
手動でプロシージャにトレースコードを追加することなく、開発やデバッグを容易にするために、ストアドプロシージャの実行をより可視化したい場合があります。

ストアドプロシージャに対してこれらの追加トレースイベントを自動的に発生させるには、 ALTER PROCEDURE コマンドを使用して、 AUTO_EVENT_LOGGING パラメーターを TRACING または ALL にセットします。このパラメーターを ALL にセットすると、追加のログメッセージもストアドプロシージャに対して自動的に生成されます。

重要

追加情報は、有効な TRACE_LEVEL が ALWAYS または ON_EVENT にセットされている場合のみ、イベントテーブルに追加されます。詳細については、ロギング、メトリクス、トレースのレベル設定をご参照ください。

例えば、簡単なテーブルを作成し、データを挿入します。

CREATE OR REPLACE TABLE test_auto_event_logging (id INTEGER, num NUMBER(12, 2));

INSERT INTO test_auto_event_logging (id, num) VALUES
  (1, 11.11),
  (2, 22.22);

Copy

次に、 auto_event_logging_sp というストアドプロシージャを作成します。このサンプルストアドプロシージャは、テーブルの行を更新し、テーブルにクエリします。

CREATE OR REPLACE PROCEDURE auto_event_logging_sp(
  table_name VARCHAR,
  id_val INTEGER,
  num_val NUMBER(12, 2))
RETURNS TABLE()
LANGUAGE SQL
AS
$$
BEGIN
  UPDATE IDENTIFIER(:table_name)
    SET num = :num_val
    WHERE id = :id_val;
  LET res RESULTSET := (SELECT * FROM IDENTIFIER(:table_name) ORDER BY id);
  RETURN TABLE(res);
EXCEPTION
  WHEN statement_error THEN
    res := (SELECT :sqlcode sql_code, :sqlerrm error_message, :sqlstate sql_state);
    RETURN TABLE(res);
END;
$$
;

Copy

以下の例では、ストアドプロシージャに AUTO_EVENT_LOGGING パラメーターをセットしています。

ALTER PROCEDURE auto_event_logging_sp(VARCHAR, INTEGER, NUMBER)
  SET AUTO_EVENT_LOGGING = 'TRACING';

Copy

ALTER PROCEDURE auto_event_logging_sp(VARCHAR, INTEGER, NUMBER)
  SET AUTO_EVENT_LOGGING = 'ALL';

Copy

ストアドプロシージャを呼び出します。

CALL auto_event_logging_sp('test_auto_event_logging', 2, 44.44);

Copy

+----+-------+
| ID |   NUM |
|----+-------|
|  1 | 11.11 |
|  2 | 44.44 |
+----+-------+

auto_event_logging_sp というストアドプロシージャによって記録されたトレースデータのイベントテーブルをクエリします。トレースイベントごとに、イベントのタイムスタンプ、名前、属性を出力します。

SELECT
    TIMESTAMP as time,
    RECORD['name'] as event_name,
    RECORD_ATTRIBUTES as attributes,
  FROM
    my_db.public.my_events
  WHERE
    RESOURCE_ATTRIBUTES['snow.executable.name'] LIKE '%AUTO_EVENT_LOGGING_SP%'
    AND RECORD_TYPE LIKE 'SPAN%';

Copy

+-------------------------+--------------------------+-----------------------------------------------------------------------------------------------+
| TIME                    | EVENT_NAME               | ATTRIBUTES                                                                                    |
|-------------------------+--------------------------+-----------------------------------------------------------------------------------------------|
| 2024-10-25 20:48:49.844 | "snow.auto_instrumented" | {                                                                                             |
|                         |                          |   "childJobTime": 474,                                                                        |
|                         |                          |   "executionTime": 2,                                                                         |
|                         |                          |   "inputArgumentValues": "{ ID_VAL: 2, TABLE_NAME: test_auto_event_logging, NUM_VAL: 44.44 }" |
|                         |                          | }                                                                                             |
| 2024-10-25 20:48:49.740 | "child_job"              | {                                                                                             |
|                         |                          |   "childJobUUID": "01b7ef00-0003-01d1-0000-a99501233092",                                     |
|                         |                          |   "rowCount": 1,                                                                              |
|                         |                          |   "rowsAffected": 1                                                                           |
|                         |                          | }                                                                                             |
| 2024-10-25 20:48:49.843 | "child_job"              | {                                                                                             |
|                         |                          |   "childJobUUID": "01b7ef00-0003-01d1-0000-a99501233096",                                     |
|                         |                          |   "rowCount": 2,                                                                              |
|                         |                          |   "rowsAffected": 0                                                                           |
|                         |                          | }                                                                                             |
+-------------------------+--------------------------+-----------------------------------------------------------------------------------------------+

ここで、ストアドプロシージャを呼び出しますが、例外を発生させるために存在しないテーブルを指定します。

CALL auto_event_logging_sp('no_table', 2, 82.44);

Copy

+----------+-----------------------------------------------------+-----------+
| SQL_CODE | ERROR_MESSAGE                                       | SQL_STATE |
|----------+-----------------------------------------------------+-----------|
|     2003 | SQL compilation error:                              | 42S02     |
|          | Object 'NO_TABLE' does not exist or not authorized. |           |
+----------+-----------------------------------------------------+-----------+

イベント・テーブルのクエリを再度実行して、例外に関する情報を確認します。

SELECT
    TIMESTAMP as time,
    RECORD['name'] as event_name,
    RECORD_ATTRIBUTES as attributes,
  FROM
    my_db.public.my_events
  WHERE
    RESOURCE_ATTRIBUTES['snow.executable.name'] LIKE '%AUTO_EVENT_LOGGING_SP%'
    AND RECORD_TYPE LIKE 'SPAN%';

Copy

+-------------------------+--------------------------+-----------------------------------------------------------------------------------------------------+
| TIME                    | EVENT_NAME               | ATTRIBUTES                                                                                          |
|-------------------------+--------------------------+-----------------------------------------------------------------------------------------------------|
| 2024-10-25 20:52:43.633 | "snow.auto_instrumented" | {                                                                                                   |
|                         |                          |   "childJobTime": 66,                                                                               |
|                         |                          |   "executionTime": 4,                                                                               |
|                         |                          |   "inputArgumentValues": "{ ID_VAL: 2, TABLE_NAME: no_table, NUM_VAL: 82.44 }"                      |
|                         |                          | }                                                                                                   |
| 2024-10-25 20:52:43.601 | "caught_exception"       | {                                                                                                   |
|                         |                          |   "exceptionCode": 2003,                                                                            |
|                         |                          |   "exceptionMessage": "SQL compilation error:\nObject 'NO_TABLE' does not exist or not authorized." |
|                         |                          | }                                                                                                   |
+-------------------------+--------------------------+-----------------------------------------------------------------------------------------------------+