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 Auflistung der unterstützten Handler-Sprachen finden Sie unter Unterstützte Sprachen.

Bemerkung

Bevor Sie Daten zu Ablaufverfolgungsereignissen sammeln können, müssen Sie die Telemetriedatenerfassung aktivieren. Wenn Sie Ihren Code instrumentieren, erzeugt Snowflake die Daten und sammelt sie in einer Ereignistabelle.

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. Eine Erklärung der Ereignistabellen finden Sie unter Überblick über die Ereignisse.

Sie können auf Daten zu Ablaufverfolgungsereignissen zugreifen und diese analysieren:

  • Führen Sie einen SELECT-Befehl auf der Ereignistabelle aus.

  • Ablaufverfolgungseinträge in Snowsight ansehen.

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.9
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, den Inhalt zur Ausgabe von Ablaufverfolgungsereignissen in Ihrer Sprache finden Sie unter <label-tracing_handler_code>.

  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 vor der Ablaufverfolgung diese Einstellung, um sicherzustellen, dass Sie den Schweregrad der Protokollmeldung festhalten. Wenn Sie feststellen, dass die Ereignisdaten nicht in die Tabelle geschrieben werden, überprüfen Sie den Protokolliergrad (Ablaufverfolgungsebene), um sicherzustellen, dass Snowflake die gewünschten Daten aufzeichnet.

Weitere Informationen dazu finden Sie unter Einstellung der Grade für Protokollierung, Metriken und Ablaufverfolgung.

Unterstützte Sprachen

Sie können Ereignisse über Code verfolgen, der in den folgenden Sprachen geschrieben wurde, auch wenn der Handler-Code mit Snowpark-APIs geschrieben wurde.

Sprache/Typ

Java

Python

JavaScript

Scala

Snowflake Scripting

Handler in gespeicherter Prozedur

✔

✔

✔

✔

✔

Streamlit-App

✔

UDF-Handler (Skalarfunktion)

✔

✔

✔

✔

UDTF-Handler (Tabellenfunktion)

✔

✔

✔

✔ *
*:

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

Ablaufverfolgung von SQL-Anweisungen

Wenn die Ablaufverfolgung aktiviert ist, verfolgt Snowflake standardmäßig SQL -Anweisungen, die in Verbindung mit anderem verfolgten Code ausgeführt werden, z. B. innerhalb des Handlers für eine gespeicherte Prozedur oder eine benutzerdefinierte Funktion.

Snowflake verfolgt SQL standardmäßig in den folgenden Kontexten:

  • SQL innerhalb einer gespeicherten Prozedur ausgeführt

  • SQL, die eine gespeicherte Prozedur ausführt

  • SQL, die eine oder mehrere benutzerdefinierte Funktionen ausführt

  • SQL ausgeführt von DBT

  • SQL ausgeführt von Streamlit

  • SQL ausgeführt von einem Notebook

  • SQL in Snowpark Container Services ausgeführt, wenn der Codekontext ein Python- oder Go-Konnektor ist

Folgende werden nicht unterstützt:

  • SQL -Anweisungen in einer Snowflake Native App

  • Direkte Ausführung von SQL in Arbeitsblättern oder Arbeitsbereichen

Bei einer verfolgten SQL-Anweisung finden Sie die ausgegebenen Daten in der Ereignistabelle, einschließlich in den folgenden Spalten:

  • In der RESOURCE_ATTRIBUTES-Spalte ist der Wert der snow.executable.type-Eigenschaft QUERY.

  • In der RECORD-Spalte ist der Wert der name-Eigenschaft der Typ von SQL-Anweisung, deren Ausführung verfolgt wurde, z. B. SELECT, CALL oder INSERT-

  • In der RECORD_ATTRIBUTES-Spalte enthalten die folgenden Eigenschaften Werte, die sich auf die SQL-Ablaufverfolgung beziehen:

    • db.query.table.names

    • db.query.view.names

    • db.query.executable.names

    • db.query.text (falls aktiviert)

Sie können festlegen, ob der SQL-Text selbst (bis zu 1024 Zeichen) in die Daten zur Ablaufverfolgung aufgenommen werden soll, die in einer Ereignistabelle erfasst werden. Möglicherweise möchten Sie den SQL-Text weglassen, wenn dieser sensible Informationen enthalten kann oder wenn dies nicht nützlich wäre.

  • Zum Erfassen von SQL-Text bei der Ablaufverfolgung setzen Sie den SQL_TRACE_QUERY_TEXT-Parameter auf "ON" (zum Festlegen dieses Parameters müssen Sie die ACCOUNTADMIN-Rolle verwenden).

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.

Gesammelte Ereignisdaten anzeigen

Sie können Ablaufverfolgungsdaten entweder über Snowsight oder durch Abfrage der Ereignistabelle, in der Ablaufverfolgungsdaten gespeichert sind, einsehen. Weitere Informationen dazu finden Sie unter Ablaufverfolgung anzeigen.

Sprache: Deutsch