Ausgeben von Ablaufverfolgungsereignissen in Snowflake Scripting¶

Sie können die SYSTEM-Funktionen von Snowflake verwenden, um Ablaufverfolgungsereignisse von einem in Snowflake Scripting geschriebenen Funktions- oder Prozedur-Handler auszugeben.

Stellen Sie vor dem Ausgeben von Ablaufverfolgungsereignissen sicher, dass der Protokolliergrad (Ablaufverfolgungsebene) so eingestellt ist, dass die gewünschten Meldungen in der Ereignistabelle gespeichert werden. Weitere Informationen dazu finden Sie unter Einstellung der Grade für Protokollierung, Metriken und Ablaufverfolgung.

Bemerkung

Bevor Sie mit der Ausgabe von Ablaufverfolgungsereignissen beginnen können, müssen Sie eine Ereignistabelle einrichten. Weitere Informationen dazu finden Sie unter Überblick über die Ereignisse.

Sie können auf die gespeicherten Daten zu den Ablaufverfolgungsereignissen zugreifen, indem Sie einen SELECT-Befehl auf der Ereignistabelle ausführen. Weitere Informationen dazu finden Sie unter Ablaufverfolgung anzeigen.

Allgemeine Informationen zur Einstellung der Protokollierung und zum Abrufen von Meldungen in Snowflake finden Sie unter Ablaufverfolgungsereignisse von Funktionen und Prozeduren.

Bemerkung

Richtlinien, die beim Hinzufügen von Ablaufverfolgungsereignissen berücksichtigt werden sollten, finden Sie unter Allgemeine Richtlinien für das Hinzufügen von Ablaufverfolgungsereignissen.

Hinzufügen von Ablaufverfolgungsereignissen¶

Sie können Ablaufverfolgungsereignisse hinzufügen, indem Sie die Funktion SYSTEM$ADD_EVENT aufrufen und dabei einen Namen für das Ereignis übergeben. Sie können einem Ereignis optional auch Attribute (Schlüssel-Wert-Paare) zuordnen.

Der Code im folgenden Beispiel fügt die Ereignisse SProcEmptyEvent und SProcEventWithAttributes hinzu. Mit SProcEventWithAttributes fügt der Code auch zwei Attribute hinzu: key1 und key2.

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

Copy

Das Hinzufügen dieser Ereignisse führt zu zwei Zeilen in der Ereignistabelle, die jeweils einen anderen Wert in der Spalte RECORD haben:

{
  "name": "SProcEmptyEvent"
}

Copy

{
  "name": "SProcEventWithAttributes"
}

Copy

Die Ereigniszeile SProcEventWithAttributes enthält in der Spalte RECORD_ATTRIBUTES die folgenden Attribute:

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

Copy

Hinzufügen von Bereichsattributen¶

Durch Aufruf der Funktion SYSTEM$SET_SPAN_ATTRIBUTES können Sie Attribute (Schlüssel-Wert-Paare) festlegen, die bestimmten Bereichen (Spans) zugeordnet sind.

Weitere Informationen zu Bereichen (Spans) finden Sie unter Darstellung von Ablaufverfolgungsereignissen in Snowflake.

Die Funktion SYSTEM$SET_SPAN_ATTRIBUTES ist in der folgenden Form verfügbar:

SYSTEM$SET_SPAN_ATTRIBUTES(<object>);

Copy

Wobei:

object ist ein Snowflake Scripting-Objekt mit Schlüssel-Wert-Paaren, die die Attribute für dieses Ablaufverfolgungsereignis angeben.

Der Code im folgenden Beispiel erstellt zwei Attribute und setzt deren Werte:

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

Copy

Das Einstellen dieser Attribute führt in der Spalte RECORD_ATTRIBUTES der Ereignistabelle zu folgendem Ergebnis:

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

Copy

Beispiele¶

Der Code im folgenden Beispiel verwendet die Funktion SYSTEM$ADD_EVENT, um ein Ereignis namens name_a und ein Ereignis namens name_b hinzuzufügen. name_b werden die beiden Attribute score und pass zugeordnet. Der Code verwendet auch SYSTEM$SET_SPAN_ATTRIBUTES, um die Attribute key1 und key2 für den Bereich (Span) festzulegen.

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

Automatische Ablaufverfolgung für untergeordnete Jobs und Ausnahmen¶

Sie können die folgenden zusätzlichen Arten von Ablaufverfolgungsereignissen für eine Snowflake Scripting Stored Procedure automatisch in der Ereignistabelle ausgeben:

Abfangen von Ausnahmen.
Informationen über die Ausführung von untergeordneten Jobs.
Statistiken über untergeordnete Jobs.
Statistiken zu gespeicherten Prozeduren, einschließlich Ausführungszeit und Eingabewerte.

Die automatische Ablaufverfolgung ist für die folgenden Anwendungsfälle gedacht:

Sie möchten vordefinierte Ablaufverfolgungsereignisse ausgeben, ohne den Body der gespeicherten Prozedur zu ändern.
Sie möchten Informationen über die Ausführung gespeicherter Prozeduren sammeln, die Sie später analysieren können, z. B:
- Informationen über die Ausführung von untergeordneten Jobs (wie childJobUUID, rowCount, exceptionCode usw.).
- Ausführungszeit des untergeordnete Jobs.
- Eingabeargumentwerte.
Sie möchten mehr Einblick in die Ausführung von gespeicherten Prozeduren haben, um die Entwicklung und das Debugging zu erleichtern, ohne manuell Ablaufverfolgungscode in die Prozedur einzufügen.

Um diese zusätzlichen Ablaufverfolgungsereignisse für eine gespeicherte Prozedur automatisch auszugeben, setzen Sie den Parameter AUTO_EVENT_LOGGING mit dem Befehl ALTER PROCEDURE auf TRACING oder ALL. Wenn Sie diesen Parameter auf ALL setzen, werden automatisch auch zusätzliche Protokollmeldungen für die gespeicherte Prozedur erzeugt.

Wichtig

Die zusätzlichen Informationen werden der Ereignistabelle nur hinzugefügt, wenn die effektive TRACE_LEVEL auf ALWAYS oder ON_EVENT eingestellt ist. Weitere Informationen dazu finden Sie unter Einstellung der Grade für Protokollierung, Metriken und Ablaufverfolgung.

Erstellen Sie zum Beispiel eine einfache Tabelle und fügen Sie Daten ein:

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

Als Nächstes erstellen Sie eine gespeicherte Prozedur namens auto_event_logging_sp. Dieses Beispiel für eine gespeicherte Prozedur aktualisiert eine Tabellenzeile und fragt dann die Tabelle ab:

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

Die folgenden Beispiele legen den Parameter AUTO_EVENT_LOGGING für die gespeicherte Prozedur fest:

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

Rufen Sie die gespeicherte Prozedur auf:

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

Copy

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

Abfragen der Ereignistabelle nach Ablaufverfolgungsdaten, die von der gespeicherten Prozedur namens auto_event_logging_sp aufgezeichnet wurden. Geben Sie für jedes Ablaufverfolgungsereignis den Zeitstempel, den Namen und die Attribute des Ereignisses aus.

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                                                                           |
|                         |                          | }                                                                                             |
+-------------------------+--------------------------+-----------------------------------------------------------------------------------------------+

Rufen Sie nun die gespeicherte Prozedur auf, aber geben Sie eine Tabelle an, die nicht existiert, um eine Ausnahme zu verursachen:

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. |           |
+----------+-----------------------------------------------------+-----------+

Führen Sie die Abfrage in der Ereignistabelle erneut aus, um die Informationen über die Ausnahme zu sehen:

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." |
|                         |                          | }                                                                                                   |
+-------------------------+--------------------------+-----------------------------------------------------------------------------------------------------+