Ablaufverfolgungsereignisse von Funktionen und Prozeduren

Sie können Ablaufverfolgungsereignisse aus dem Handler-Code für eine Prozedur, UDF oder UDTF ausgeben, einschließlich derer, die Sie unter Verwendung der Snowpark-APIs schreiben. Eine Liste der unterstützten Handler-Sprachen finden Sie unter Unterstützte Sprachen.

Ablaufverfolgungsereignisse sind ein Typ von Telemetriedaten (wie Protokollmeldungen), die aufzeichnen können, wenn im System oder in der Anwendung etwas passiert ist. Im Gegensatz zu Protokollmeldungen haben Ablaufverfolgungsereignisse strukturierten Payload, was sie zu einer guten Wahl für die Datenanalyse macht. Sie können zum Beispiel Ablaufverfolgungsereignisse verwenden, um einige Zahlen zu erfassen, die während der Ausführung Ihrer Funktion berechnet werden, und diese Zahlen anschließend analysieren.

In einer Prozedur oder UDF können Sie Attribute (Schlüssel-Wert-Paare) zuordnen, die als Teil der Ablaufverfolgungsereignisse erfasst werden sollen. Wenn Sie zum Beispiel die Namen und Werte von Parametern in einem Ablaufverfolgungsereignis erfassen möchten, können Sie ein Ablaufverfolgungsereignis mit dem Namen parameters hinzufügen und die Namen und Werte der Parameter als Attribute des Ereignisses festlegen.

Wenn eine Prozedur oder Funktion erfolgreich ausgeführt wird, gibt Snowflake die hinzugefügten Ablaufverfolgungsereignisse aus. Snowflake stellt diese Ablaufverfolgungsereignisse in der dem Konto zugeordneten aktiven Ereignistabelle zur Verfügung. Weitere Informationen zu Ereignistabellen finden Sie unter Einrichten einer Ereignistabelle.

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

Beispiel für die Ablaufverfolgung

Der Python-Code im folgenden Beispiel setzt ein example.proc.do_tracing-Attribut auf den Bereich (Span) mit dem Wert begin. Außerdem wird innerhalb des Bereichs ein Ereignis event_with_attributes mit den Attributen example.key1 und example.key2 ausgegeben.

CREATE OR REPLACE PROCEDURE do_tracing()
RETURNS VARIANT
LANGUAGE PYTHON
PACKAGES=('snowflake-snowpark-python', 'snowflake-telemetry-python')
RUNTIME_VERSION=3.8
HANDLER='run'
AS $$
from snowflake import telemetry
def run(session):
  telemetry.set_span_attribute("example.proc.do_tracing", "begin")
  telemetry.add_event("event_with_attributes", {"example.key1": "value1", "example.key2": "value2"})
  return "SUCCESS"
$$;
Copy

Erste Schritte

Um mit der Ereignisverfolgung von Handler-Code zu beginnen, führen Sie die folgenden allgemeinen Schritte aus:

  1. Ereignistabelle einrichten.

    Snowflake verwendet Ihre Ereignistabelle, um die von Ihrem Handler-Code ausgegebenen Ereignisdaten zu speichern. Eine Ereignistabelle hat Spalten, die von Snowflake vorgegeben werden.

  2. Machen Sie sich mit der Ereignisverfolgungs-API für die von Ihnen verwendete Handler-Sprache vertraut.

    Eine Liste der Handler-Sprachen finden Sie unter Unterstützte Sprachen. Informieren Sie sich, wie die Ausgabe der Ablaufverfolgungsereignisse in Ihrer Sprache vorgenommen wird.

  3. Fügen Sie den Code für die Ereignisverfolgung zu Ihrem Handler hinzu.

  4. Erfahren Sie, wie Sie über die Ereignistabelle Daten zu Ablaufverfolgungsereignissen abrufen.

Ebene von Ablaufverfolgungsereignissen

Sie können die Ausführlichkeit der in der Ereignistabelle gespeicherten Daten zu Ablaufverfolgungsereignissen verwalten, indem Sie den Protokolliergrad (auch Ablaufverfolgungsebene genannt) einstellen. Verwenden Sie diese Einstellung, um vor der Ablaufverfolgung sicherzustellen, dass Sie den Schweregrad der Protokollmeldung erfassen. Wenn Sie feststellen, dass die Ereignisdaten nicht in die Tabelle geschrieben werden, überprüfen Sie den Protokolliergrad (Ablaufverfolgungsebene), um sicherzustellen, dass dieser das Erfassen der gewünschten Daten zulässt.

Weitere Informationen dazu finden Sie unter Einstellen des Protokolliergrads (Ablaufverfolgungsebene).

Unterstützte Sprachen

Sie können Ereignisse aus Handler-Code von Funktionen und Prozeduren verfolgen, der in den folgenden Sprachen geschrieben wurde, auch wenn der Handler-Code with Snowpark-APIs geschrieben wurde.

Sprache/Typ

Java

Python

JavaScript

Scala

Snowflake Scripting

Gespeicherte Prozeduren

Skalare UDFs

UDTFs

✔ *

*

Scala-UDTF-Handler geschrieben in Snowpark.

Ereignisablaufverfolgung aus Handler-Code

Zur Ablaufverfolgung von Ereignissen können Sie eine von Snowflake bereitgestellte Bibliothek verwenden, die für den von Ihnen verwendeten Handler-Code konzipiert ist. Snowflake fängt Ablaufverfolgungsereignisse ab und speichert sie in der von Ihnen erstellten Ereignistabelle.

In der folgenden Tabelle sind die für die Protokollierung unterstützten Handler-Sprachen aufgeführt, zusammen mit Links zu weiteren Informationen zur Protokollierung von Code.

Sprache

Telemetrie-Bibliothek

Dokumentation

Java

Snowflake-Telemetry-Klasse

Ausgeben von Ablaufverfolgungsereignissen in Java

JavaScript

Snowflake-JavaScript-API

Ausgeben von Ablaufverfolgungsereignissen in JavaScript

Python

Snowflake-telemetry-Paket

Ausgeben von Ablaufverfolgungsereignissen in Python

Scala

Snowflake-Telemetry-Klasse

Ausgeben von Ablaufverfolgungsereignissen in Scala

Snowflake Scripting

Snowflake-SQL-Funktionen

Ausgeben von Ablaufverfolgungsereignissen in Snowflake Scripting

Allgemeine Richtlinien für das Hinzufügen von Ablaufverfolgungsereignissen

Wenn Sie die Ablaufverfolgungsereignis-APIs aufrufen, um Ablaufverfolgungsereignisse hinzuzufügen und Attribute für Bereiche (Spans) festzulegen, beachten Sie Folgendes:

  • Ein Bereich (Span) kann eine maximale Anzahl von 128 Ablaufverfolgungsereignissen und eine maximale Anzahl von 128 Span-Attributen umfassen.

  • Wenn Sie ein Ablaufverfolgungsereignis hinzufügen, das denselben Namen hat wie ein Ereignis, das Sie zuvor hinzugefügt haben, wird ein neuer Ereignisdatensatz erstellt.

  • Wenn Sie ein Span-Attribut festlegen, das denselben Schlüssel hat wie ein zuvor festgelegtes Span-Attribut, wird der Wert für diesen Schlüssel überschrieben.

Zugriff auf Ereignisdaten

Sie können auf die Ereignisdaten zugreifen, indem Sie einen SELECT-Befehl auf der Ereignistabelle ausführen. Weitere Informationen dazu finden Sie unter Zugriff auf Ablaufverfolgungsdaten.