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:

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.
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.
Fügen Sie den Code für die Ereignisverfolgung zu Ihrem Handler hinzu.
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.