Tutorial: Erste Schritte mit Protokollierung und Ablaufverfolgung

Einführung

Dieses Tutorial führt in die Grundlagen des Ausgebens, Sammelns und Abfragens von Protokoll- und Ablaufverfolgungsdaten aus Handler-Code von Funktionen und Prozeduren ein.

In dem Tutorial wird die Weboberfläche Snowsight verwendet, aber Sie können jeden Snowflake-Client verwenden, der die Ausführung von SQL unterstützt. Weitere Informationen zu Snowsight finden Sie unter Erste Schritte mit Arbeitsblättern und Verwalten und Verwenden von Arbeitsblättern in Snowsight.

Lerninhalte

In diesem Tutorial erfahren Sie Folgendes:

  • Erstellen einer Ereignistabelle zum Speichern von Protokoll- und Ablaufverfolgungsdaten.

    Snowflake sammelt Protokoll- und Ablaufverfolgungsdaten in der vordefinierten Struktur der Tabelle.

  • Ausgeben von Protokollmeldungen und Protokoll- und Ablaufverfolgungsdaten mit einer benutzerdefinierten Funktion (UDF).

    Sie können einen API verwenden, die für Ihre Handler-Sprache entwickelt wurde, um Protokollmeldungen und Ablaufverfolgungsdaten mit Handler-Code auszugeben.

  • Anzeigen der gesammelten Protokoll- und Ablaufverfolgungsdaten durch Abfragen der Ereignistabelle.

    Sie können die Tabelle mit einer SELECT-Anweisung abfragen, um die gesammelten Daten zu analysieren.

Voraussetzungen

  • Sie müssen alle SQL-Befehle in der gleichen SQL-Befehlssitzung ausführen, da der Sitzungskontext erforderlich ist.

    Bei Verwendung von Snowsight fügen Sie beispielsweise Ihren gesamten Code nach und nach in dasselbe Arbeitsblatt ein. Während Sie von Abschnitt zu Abschnitt vorankommen, baut jeder Abschnitt auf dem vorherigen auf.

  • Sie müssen die Rolle ACCOUNTADMIN verwenden können.

    In diesem Tutorial werden Sie alle Schritte mit der Rolle ACCOUNTADMIN durchführen. In der Regel sollten Sie jedoch Rollen verwenden, deren Berechtigungen speziell für die von Ihnen auszuführende Aktion definiert sind. So können Sie beispielsweise separate Rollen für Entwickler verwenden, die UDFs erstellen, für Analysten, die gesammelte Protokoll- und Ablaufverfolgungsdaten abfragen, und so weiter.

    Weitere Informationen zu Rollen finden Sie unter Aktive Rolle umschalten und Hinweise zur Zugriffssteuerung.

Einrichten von Datenbank, Warehouse und Zugriff

In diesem Abschnitt erstellen Sie ein Warehouse und eine Datenbank, die Sie für das Tutorial benötigen. Sie die Rolle ACCOUNTADMIN verwenden, die für das Ausführen einiger der Anweisungen in diesem Tutorial erforderlich ist.

Sie erstellen eine Datenbank, in der Sie später die Ereignistabelle und die benutzerdefinierte Funktion erstellen werden. Sie können alle im Tutorial erstellten Objekte, einschließlich Datenbank und Warehouse, löschen, wenn Sie diese nicht mehr benötigen.

So erstellen Sie eine Datenbank und ein Warehouse zur Verwendung im Tutorial:

  1. Melden Sie sich bei Snowsight an.

  2. Wechseln Sie zur Rolle ACCOUNTADMIN.

  3. Öffnen Sie Projects » Worksheets.

  4. Wählen Sie + » SQL Worksheet aus.

  5. Benennen Sie das neue Arbeitsblatt in Logging-tracing tutorial um.

  6. Fügen Sie in das neue Arbeitsblatt folgende Anweisung zum Erstellen einer Datenbank ein, und führen Sie die Anweisung aus. Die neue Datenbank ist nur zur Verwendung in diesem Tutorial vorgesehen.

    CREATE OR REPLACE DATABASE tutorial_log_trace_db;
    Copy

  7. Fügen Sie folgende Anweisung zum Erstellen eines Warehouses ein, und führen Sie die Anweisung aus. Das neue Warehouse ist nur zur Verwendung in diesem Tutorial vorgesehen.

    CREATE OR REPLACE WAREHOUSE tutorial_log_trace_wh
  WAREHOUSE_TYPE = STANDARD
  WAREHOUSE_SIZE = XSMALL;
    Copy

In diesem Abschnitt stellen Sie die Teile bereit, die Sie für das Tutorial benötigen. Im nächsten Abschnitt erstellen Sie eine Ereignistabelle zum Speichern von Protokoll- und Ablaufverfolgungsdaten.

Ereignistabelle erstellen

In diesem Abschnitt werden Sie eine Ereignistabelle erstellen. Wenn Ihr Handler-Code Protokollmeldungen und Ablaufverfolgungsdaten ausgibt, speichert Snowflake die ausgegebenen Daten in den Zeilen einer Ereignistabelle. Sie können die Ereignistabelle abfragen, um die Daten zu analysieren.

Sie müssen eine Ereignistabelle erstellen, um Protokoll- und Ablaufverfolgungsdaten zu sammeln. Eine Ereignistabelle verwendet immer die von Snowflake definierte vordefinierte Struktur.

Wichtig

Um diesen Abschnitt abzuschließen, müssen Sie in der Lage sein, die Rolle ACCOUNTADMIN zu verwenden, die erforderlich ist, um ein Konto so zu ändern, dass die neue Ereignistabelle die aktive Ereignistabelle des Kontos ist.

So erstellen Sie die Ereignistabelle und legen sie als aktive Ereignistabelle des Kontos fest:

  1. Fügen Sie die folgende Anweisung zum Erstellen einer Ereignistabelle ein, und führen Sie die Anweisung aus.

    CREATE OR REPLACE EVENT TABLE tutorial_event_table;
    Copy

    In dieser Tabelle wird Snowflake die Protokoll- und Ablaufverfolgungsdaten speichern.

  2. Fügen Sie die folgende Anweisung ein, mit der das Konto so geändert wird, dass die von Ihnen erstellte Ereignistabelle die aktive Tabelle des Kontos ist, und führen Sie die Anweisung aus.

    ALTER ACCOUNT SET EVENT_TABLE = tutorial_log_trace_db.public.tutorial_event_table;
    Copy

    Diese Anweisung legt die neue Ereignistabelle als die Tabelle fest, die Snowflake für das Speichern von Protokollmeldungen und Ablaufverfolgungsdaten von Handlern im aktuellen Konto verwenden soll. Ein Konto kann immer nur eine aktive Ereignistabelle haben.

In diesem Abschnitt haben Sie eine Ereignistabelle erstellt. Im nächsten Abschnitt beginnen Sie mit der Ausgabe von Protokollmeldungen, die Snowflake in der Tabelle speichert.

Protokollmeldungen ausgeben

In diesem Abschnitt werden Sie eine benutzerdefinierte Funktion (UDF) mit Python-Handler-Code erstellen, die Protokollmeldungen ausgibt. Wenn Ihr Code Protokollmeldungen ausgibt, sammelt Snowflake die Meldungsdaten und speichert sie in der von Ihnen erstellten Ereignistabelle.

Snowflake unterstützt APIs jeder unterstützten Handler-Sprache, um Meldungen zu protokollieren. Für Handler, die Sie in Python schreiben, können Sie das Modul logging der Standardbibliothek von Python verwenden.

So erstellen Sie einen UDF, die Protokollmeldungen ausgibt:

  1. Fügen Sie die folgende Anweisung ein, um den Protokolliergrad auf INFO festzulegen, und führen Sie die Anweisung aus.

    ALTER SESSION SET LOG_LEVEL = INFO;
    Copy

    Hier wird der Schweregrad der Protokollmeldungen angegeben, die Snowflake bei Ausführung der UDF erfassen soll. In diesem Fall lässt der Schweregrad alle Meldungen zu, von informativen (INFO) bis hin zu den schwerwiegendsten Ereignissen (FATAL).

  2. Fügen Sie folgende Anweisung zum Erstellen einer benutzerdefinierten Funktion ein, und führen Sie die Anweisung aus.

    CREATE OR REPLACE FUNCTION log_trace_data()
RETURNS VARCHAR
LANGUAGE PYTHON
RUNTIME_VERSION = 3.8
HANDLER = 'run'
AS $$
import logging
logger = logging.getLogger("tutorial_logger")

def run():
  logger.info("Logging from Python function.")
  return "SUCCESS"
$$;
    Copy

    Die hervorgehobenen Zeilen des Codes bewirken Folgendes:

    • Importieren des Python-Moduls logging, damit der Handler-Code es verwenden kann.

    • Erstellen eines Loggers, der die Schnittstelle darstellt, die Ihr Code zum Protokollieren von Meldungen verwenden wird.

    • Protokollieren einer Meldung mit Protokolliergrad INFO.

  3. Fügen Sie die folgende Anweisung zum Ausführen der soeben erstellten Funktion ein, und führen Sie die Anweisung aus.

    SELECT log_trace_data();
    Copy

    Folgende Ausgabe wird erstellt: Darüber hinaus wurde beim Ausführen der Funktion eine Protokollmeldung ausgegeben, die Snowflake in der Ereignistabelle gesammelt hat.

    --------------------
| LOG_TRACE_DATA() |
--------------------
| SUCCESS          |
--------------------

In diesem Abschnitt haben Sie eine Protokollmeldung von einer UDF ausgegeben. Im nächsten Abschnitt werden Sie die Ereignistabelle abfragen, um Daten zu dieser Meldung abzurufen.

Protokollmeldungen abfragen

In diesem Abschnitt werden Sie die Ereignistabelle auf Protokollmeldungsdaten abfragen, die von der im vorherigen Abschnitt ausgeführten UDF ausgegeben wurden.

Bemerkung

Es kann einige Sekunden dauern, bis die vom Handler-Code ausgegebenen Protokoll- oder Ablaufverfolgungsdaten in der Ereignistabelle erfasst werden. Wenn Sie nicht sofort ein Ergebnis sehen, versuchen Sie es nach ein paar Sekunden erneut.

Snowflake verwendet vordefinierte Ereignistabellenspalten zum Sammeln und Speichern von Protokoll- und Ablaufverfolgungsdaten der folgenden Arten:

  • Daten, die Sie von Handler-Code ausgeben: Diese umfassen Protokollmeldungen und Ablaufverfolgungsdaten zu Ereignissen.

    Sie finden diese Daten in Spalten wie RECORD_TYPE, RECORD, RECORD_ATTRIBUTES usw.

  • Daten zum Kontext: Diese umfassen kontextspezifische Daten zur Ausgabe der Protokoll- oder Ablaufverfolgungsdaten, wie Zeitstempel, Name der Handler-Methode, von der aus die Daten gesendet wurden, usw.

    Sie finden diese Daten in Spalten wie RESOURCE_ATTRIBUTES, TIMESTAMP und SCOPE.

So fragen Sie die Ereignistabelle nach Protokollmeldungsdaten ab:

  1. Fügen Sie die folgende Anweisung zum Abfragen der Ereignistabelle ein, und führen Sie die Anweisung aus.

    SELECT
  TIMESTAMP AS time,
  RESOURCE_ATTRIBUTES['snow.executable.name'] as executable,
  RECORD['severity_text'] AS severity,
  VALUE AS message
FROM
  tutorial_log_trace_db.public.tutorial_event_table
WHERE
  RECORD_TYPE = 'LOG'
  AND SCOPE['name'] = 'tutorial_logger';
    Copy

    Einige Spalten enthalten strukturierte Daten, die als Schlüssel-Wert-Paare ausgedrückt werden. In dieser Abfrage geben Sie Attributschlüssel innerhalb einer Spalte an, indem Sie die Klammernotation wie z. B. RECORD['severity_text'] verwenden.

    Sie verwenden auch die Klammernotation (SCOPE['name']), um anzugeben, dass Sie nur Spaltenwerte auswählen möchten, bei denen die Protokolleinträge mit dem Python-Logger tutorial_logger ausgegeben werden, den Sie im Handler-Code erstellt haben.

  2. Zeigen Sie die Ausgabe an.

    -----------------------------------------------------------------------------------------------------------
| TIME                | EXECUTABLE                           | SEVERITY | MESSAGE                         |
-----------------------------------------------------------------------------------------------------------
| 2023-04-19 22:00:49 | "LOG_TRACE_DATA():VARCHAR(16777216)" | "INFO"   | "Logging from Python function." |
-----------------------------------------------------------------------------------------------------------

    Die Ausgabe veranschaulicht, wie die vordefinierten Spalten der Ereignistabelle jeweils Teile der gesammelten Daten enthalten. Für die Werte von EXECUTABLE und SEVERITY haben Sie die Klammernotation zur Angabe der Attribute verwendet, deren Werte Sie benötigen.

    Ausgabespalte

    Beschreibung

    TIME

    Zeitpunkt der Erstellung des Eintrags (aus der Spalte TIMESTAMP).

    EXECUTABLE

    Name und Parameter der UDF (aus dem Attribut snow.executable.name der Spalte RESOURCE_ATTRIBUTES).

    SEVERITY

    Schweregrad des Protokolleintrags (aus dem Attribut severity_text der Spalte RECORD).

    MESSAGE

    Protokollmeldung (aus der Spalte VALUE).

In diesem Abschnitt haben Sie eine SELECT-Anweisung zur Abfrage von Protokolldaten verwendet. Im nächsten Abschnitt werden Sie die UDF so aktualisieren, dass sie Ablaufverfolgungsdaten ausgibt.

Ablaufverfolgungsdaten ausgeben

In diesem Abschnitt aktualisieren Sie den UDF-Handler-Code so, dass auch Ablaufverfolgungsdaten ausgegeben werden. Wenn Ihr Code Ablaufverfolgungsdaten ausgibt, sammelt Snowflake die Daten und speichert sie in der von Ihnen erstellten Ereignistabelle.

Ablaufverfolgungsdaten haben strukturelle Eigenschaften, wie in Bereiche (Spans) gruppierte Ereignisdaten und als Schlüssel-Wert-Paare erfasste Daten, die es Ihnen ermöglichen, ein detaillierteres Bild der Aktivität Ihres Codes zu erstellen, als es Protokolldaten normalerweise erlauben.

Snowflake unterstützt APIs jeder unterstützten Handler-Sprache, um Ablaufverfolgungsdaten auszugeben. Für Handler, die Sie in Python schreiben, können Sie das Snowflake-Paket telemetry verwenden.

So aktualisieren Sie die UDF, um Ablaufverfolgungsdaten auszugeben:

  1. Fügen Sie die folgende Anweisung ein, um festzulegen, welche Ablaufverfolgungsdaten erfasst werden sollen, und führen Sie die Anweisung aus.

    ALTER SESSION SET TRACE_LEVEL = ON_EVENT;
    Copy

    Damit wird der Protokolliergrad (Ablaufverfolgungsebene) auf ON_EVENT gesetzt. Das bedeutet, dass nur Ablaufverfolgungsdaten erfasst werden sollen, die explizit von Ihrem eigenen Code ausgegeben werden.

  2. Fügen Sie die folgende Anweisung ein, um eine UDF zu erstellen, die Ablaufverfolgungsdaten ausgibt, und führen Sie diese Anweisung aus.

    CREATE OR REPLACE FUNCTION log_trace_data()
RETURNS VARCHAR
LANGUAGE PYTHON
PACKAGES = ('snowflake-telemetry-python')
RUNTIME_VERSION = 3.8
HANDLER = 'run'
AS $$
import logging
logger = logging.getLogger("tutorial_logger")
from snowflake import telemetry

def run():
  telemetry.set_span_attribute("example.proc.run", "begin")
  telemetry.add_event("event_with_attributes", {"example.key1": "value1", "example.key2": "value2"})
  logger.info("Logging from Python function.")
  return "SUCCESS"
$$;
    Copy

    Wenn Sie diesen Code ausführen, ersetzen Sie die Funktion, die Sie zuvor erstellt haben, durch eine Funktion, die Code für die Ausgabe von Ablaufverfolgungsdaten hinzufügt. Die hervorgehobenen Zeilen bewirken Folgendes:

    • Hinzufügen von snowflake-telemetry-python (enthält das telemetry-Paket) zur Ausführungsumgebung der UDF.

    • Importieren des telemetry-Pakets, damit Sie dessen Funktionen aufrufen können.

    • Erstellen eines Attributs und Festlegen eines Attributwerts für den Bereich (Span), der von Snowflake bei Ausführung des Codes erstellt wird.

      Ein Bereich (Span) repräsentiert die Ausführungseinheit einer Prozedur oder UDF, innerhalb derer Sie mehrere Ereignisse hinzufügen können.

    • Fügen Sie ein Ereignis (mit seinen eigenen Attributen) hinzu, das als Teil des Bereichs (Span) erfasst werden soll.

  3. Fügen Sie die folgende Anweisung zum Ausführen der soeben erstellten Funktion ein, und führen Sie die Anweisung aus.

    SELECT log_trace_data();
    Copy

    Folgende Ausgabe wird erstellt: Außerdem gab die Funktion bei ihrer Ausführung Ablaufverfolgungsdaten aus, die von Snowflake in der Ereignistabelle gesammelt wurden.

    --------------------
| LOG_TRACE_DATA() |
--------------------
| SUCCESS          |
--------------------

In diesem Abschnitt haben Sie Ablaufverfolgungsdaten von einer UDF ausgegeben. Im nächsten Abschnitt werden Sie die Ereignistabelle abfragen, um Daten zur Ablaufverfolgung abzurufen.

Ablaufverfolgungsmeldungen abfragen

In diesem Abschnitt werden Sie die Ereignistabelle nach Ablaufverfolgungsdaten abfragen, die von der im vorherigen Abschnitt ausgeführten UDF ausgegeben wurden.

Bemerkung

Es kann einige Sekunden dauern, bis die vom Handler-Code ausgegebenen Protokoll- oder Ablaufverfolgungsdaten in der Ereignistabelle erfasst werden. Wenn Sie nicht sofort ein Ergebnis sehen, versuchen Sie es nach ein paar Sekunden erneut.

Mit der von Ihnen geschriebenen Abfrage werden Kontextinformationen zu Ereignissen abgerufen, die von der Funktion ausgegeben wurden. Zu diesem Kontext gehört auch der Name der Funktion, die für die Ausgabe verantwortlich ist.

So fragen Sie die Ereignistabelle nach Ablaufverfolgungsdaten ab:

  1. Fügen Sie die folgende Anweisung zum Abfragen der Ereignistabelle nach Ablaufverfolgungsdaten ein, und führen Sie die Anweisung aus.

    SELECT
  TIMESTAMP AS time,
  RESOURCE_ATTRIBUTES['snow.executable.name'] AS handler_name,
  RECORD['name'] AS event_name,
  RECORD_ATTRIBUTES AS attributes
FROM
  tutorial_log_trace_db.public.tutorial_event_table
WHERE
  RECORD_TYPE = 'SPAN_EVENT'
  AND HANDLER_NAME LIKE 'LOG_TRACE_DATA%';
    Copy

    Einige Spalten enthalten strukturierte Daten, die als Schlüssel-Wert-Paare ausgedrückt werden. Für diese können Sie Attributwerte innerhalb einer Spalte mit der Klammernotation auswählen, wie im Code gezeigt.

  2. Zeigen Sie die Ausgabe an.

    -----------------------------------------------------------------------------------------------------------------------------------------------------
| TIME                    | HANDLER_NAME                         | EVENT_NAME              | ATTRIBUTES                                             |
-----------------------------------------------------------------------------------------------------------------------------------------------------
| 2023-05-10 20:49:35.080 | "LOG_TRACE_DATA():VARCHAR(16777216)" | "event_with_attributes" | { "example.key1": "value1", "example.key2": "value2" } |
-----------------------------------------------------------------------------------------------------------------------------------------------------

    Die Ausgabe veranschaulicht, wie die vordefinierten Spalten der Ereignistabelle jeweils Teile der gesammelten Daten enthalten. Für die Werte von EXECUTABLE und SEVERITY haben Sie die Klammernotation zur Angabe des Attributs verwendet, dessen Wert Sie benötigen.

    Ausgabespalte

    Beschreibung

    TIME

    Zeitpunkt der Erstellung des Eintrags (aus der Spalte TIMESTAMP).

    HANDLER_NAME

    Name und Parameter der UDF (aus dem Attribut snow.executable.name der Spalte RESOURCE_ATTRIBUTES).

    EVENT_NAME

    Name des Ereignisses, das mit der Funktion add_event hinzugefügt wurde (aus dem Attribut name der Spalte RECORD).

    ATTRIBUTES

    Attribute, die dem Ereignis hinzugefügt wurden (aus der Spalte RECORD_ATTRIBUTES).

In diesem Abschnitt haben Sie die Ereignistabelle nach Ablaufverfolgungsdaten abgefragt, die von der von Ihnen geschriebenen UDF ausgegeben wurden. Im letzten Abschnitt finden Sie Links zu Informationen, die sich auf die Aspekte beziehen, die Sie während des Tutorials getan haben.

Mehr erfahren

Geschafft! Sehr gut gemacht.

In diesem Tutorial haben Sie einen umfassenden Überblick darüber erhalten, wie Sie Protokoll- und Ablaufverfolgungsdaten über Handler-Code ausgeben und speichern und anschließend die gespeicherten Daten abfragen können. Auf dem Weg dorthin, haben Sie folgende Aufgaben ausgeführt:

Sprache: Deutsch