Event Tables für strukturiertes Logging & Tracing in Snowflake

Event Tables sind seit Mai 2023 als Public Preview verfügbar. Es handelt sich um einen speziellen Snowflake-Tabellentyp, der sich in mehreren Punkten von Standardtabellen unterscheidet:

• Vordefinierte Spalten, die nicht verändert werden können
• Ausschließlich für das Erfassen von Logging- und Tracing-Daten gedacht
• Pro Account kann nur eine aktive Event Table existieren

Typische Einsatzszenarien sind das Erfassen von Logging-Informationen aus Code-Handlern in Stored Procedures oder UDFs sowie das Sammeln von Tracing-Daten aus Native Apps.

Das Aktivieren einer Event Table für Ihren Account erfolgt in mehreren Schritten, wie in der folgenden Abbildung dargestellt:

1. EVENT TABLE anlegen

Zunächst legen wir eine Event Table an. Das geschieht über eine spezielle CREATE TABLE-Anweisung:

CREATE EVENT TABLE my_db.logging.my_event_table;

Spalten müssen Sie nicht angeben – die Tabelle bringt eine vordefinierte Spaltenliste mit. Pro Account ist derzeit nur eine aktive Event Table möglich.

2. Event Table dem Account zuweisen

Damit die Event Table genutzt werden kann, verknüpfen wir sie mit unserem Account. Das geschieht per ALTER ACCOUNT-Anweisung und setzt entsprechend die Rolle ACCOUNTADMIN voraus. Zusätzlich werden OWNERSHIP- oder INSERT-Rechte auf die Event Table benötigt.

ALTER ACCOUNT SET EVENT_TABLE = my_db.logging.my_event_table;

3. Log-Events erfassen

Jetzt können wir die UDF/UDTF oder Stored Procedure um Logging-Code ergänzen. Je nach Sprache des Handlers stehen Ihnen die jeweils üblichen Logging-APIs und Libraries zur Verfügung.

Sprache	Logging-Library
Java	SLF4J API
JavaScript	Snowflake JavaScript API
Python	logging-Modul
Scala	SLF4J API
Snowflake Scripting	Snowflake-Funktion SYSTEM$LOG

Nehmen wir Python als Beispiel.

CREATE OR REPLACE FUNCTION my_UDF()
RETURNS VARCHAR
RUNTIME_VERSION = 3.8
HANDLER = 'run'
AS $$
import logging
logger = logging.getLogger("my_logger")

def run():
        logger.info("Processing start")
        ...
        ...
        logger.error("Some error in your code")
        return value

Für den Einstieg importieren wir das logging-Modul und instanziieren das Logger-Objekt. Danach lässt es sich wie in jeder anderen Python-Anwendung verwenden – mit den üblichen Log-Levels wie INFO, WARNING oder ERROR.

Sehen wir uns noch ein Beispiel für SQL-Scripting an: Wenn Ihr Handler-Code in SQL geschrieben ist, kommt bei Snowflake Scripting die Funktion SYSTEM$LOG zum Einsatz. Auch sie unterstützt verschiedene Log-Levels wie info, warning oder error.

Wir haben eine einfache Stored Procedure, die eine Tabelle zurückgibt. Wollen wir sie um Logging-Informationen erweitern, sieht das so aus:

create or replace procedure returning_table()
returns table(id number, name varchar)
language sql
as
declare
    result RESULTSET DEFAULT (SELECT 1 id, 'test value' name);
begin
    SYSTEM$LOG('info', 'Returning a table');
        return table(result);
end;

4. Die Event Table abfragen

Logging ist im Handler-Code integriert – jetzt wollen wir uns die protokollierten Events ansehen. Zeit also, die Event Table abzufragen. Jede protokollierte Nachricht enthält:

• Timestamp – wann das Event protokolliert wurde
• Scope – z. B. der Name der Klasse, in der das Log-Event entstanden ist
• Severity Level des Logs – z. B. info, warning, error
• Die Log-Nachricht selbst

Eine vollständige Liste der Spalten der Event Table finden Sie in der Dokumentation. Einige Spalten speichern mehrere Attribute als Key-Value-Paare. Auslesen lassen sie sich mit Queries wie diesen:

create or replace procedure returning_table()
returns table(id number, name varchar)
language sql
as
declare
    result RESULTSET DEFAULT (SELECT 1 id, 'test value' name);
begin
    SYSTEM$LOG('info', 'Returning a table');
        return table(result);
end;

Und so sieht die Ausgabe der Event Table aus:

Ein weiterer Anwendungsfall für Event Tables ist das Erfassen von Trace-Daten aus Ihrem Code. Trace-Daten sind strukturierte Logging-Informationen in Form von Key-Value-Paaren und liefern einen deutlich detaillierteren Einblick in das Verhalten des Codes als klassische Log-Daten. Schauen wir uns an einem Beispiel an, wie wir Trace-Daten aus einer in Python geschriebenen UDF sammeln:

select
    resource_attributes:"snow.database.id"::number,
    resource_attributes:"snow.database.name"::varchar,
    resource_attributes:"snow.executable.name"::varchar,
    resource_attributes:"snow.executable.type"::varchar,
    resource_attributes:"snow.owner.name"::varchar,
    resource_attributes:"snow.query.id"::varchar,
    resource_attributes:"snow.warehouse.name"::varchar,
    resource_attributes:"telemetry.sdk.language"::varchar,
    record,
    value
from my_event_table;

Dazu importieren wir das snowflake-telemetry-package, das die benötigten Methoden enthält.

Mit der Methode set_span_attribute setzen Sie Key-Value-Paare auf dem Span-Objekt. Span-Objekte halten Telemetriedaten, die nach erfolgreicher Ausführung einer Funktion oder Prozedur entstehen, und stehen für die Ausführungseinheit einer UDF oder Stored Procedure. Mit add_event hängen Sie an diese Ausführungseinheit beliebig viele Events an.

Wenn Sie tiefer einsteigen möchten, wie Snowflake Trace-Events abbildet, werfen Sie einen Blick in die Dokumentation.

Event Tables eignen sich auch dafür, Logging-Events und Telemetriedaten aus Ihren Native Apps zu sammeln. Da der Code der Native App im Consumer-Account läuft und dort die Events erfasst werden, ist etwas zusätzliche Konfiguration nötig – und zwar auf beiden Seiten, im Provider- wie im Consumer-Account.

Provider-Setup im Überblick:

1. Log- und Event-Level in der Manifest-Datei konfigurieren
2. Einen Account für die Speicherung der Events konfigurieren

Consumer-Setup im Überblick:

1. Event Table einrichten
2. Events in der Event Table prüfen
3. Logging aktivieren und Events mit dem Provider teilen

Sowohl Consumer als auch Provider haben Zugriff auf die Event Table und die protokollierten Einträge. Der Consumer sollte daher vor dem Aktivieren genau prüfen, welche Informationen protokolliert und an den Provider weitergegeben werden.

Snowflake stellt für beide Seiten – Provider wie Consumer – einen ausführlichen Überblick mit Schritt-für-Schritt-Anleitungen bereit. Wenn Sie das gesamte Setup im Detail nachvollziehen möchten, finden Sie alles in der Dokumentation.

Event Tables lassen sich problemlos mit Snowflake Alerts kombinieren, um Benachrichtigungen auf Basis protokollierter Events zu automatisieren. Bauen wir uns einen Alert, der einmal pro Stunde läuft und bei einem protokollierten Error eine E-Mail verschickt.

CREATE OR REPLACE ALERT alert_logged_errors
  WAREHOUSE = my_warehouse
  SCHEDULE = '60 MINUTE'
  IF (EXISTS (
      SELECT *
      FROM my_event_table
      WHERE record:"severity_text"::VARCHAR == 'ERROR' and timestamp BETWEEN                SNOWFLAKE.ALERT.LAST_SUCCESSFUL_SCHEDULED_TIME()
       AND SNOWFLAKE.ALERT.SCHEDULED_TIME()
  ))
  THEN CALL SYSTEM$SEND_EMAIL(...);

Für Log- und Trace-Payloads gilt eine Größenbeschränkung: 1 MB dürfen nicht überschritten werden.

Die Event Table taucht im View ACCOUNT_USAGE in der Liste aller Tabellen Ihres Accounts auf – erkennbar am Wert EVENT TABLE in der Spalte TABLE_TYPE.

select *
from snowflake.account_usage.tables
where table_name = 'MY_EVENT_TABLE'
;

Event Tables lassen sich nicht aktualisieren. Wenn Sie ein UPDATE-Statement absetzen, erhalten Sie die Fehlermeldung UPDATE statement's target must be a table. Unterstützt werden auf EVENT TABLES folgende Operationen:

• SHOW EVENT TABLE
• DESCRIBE EVENT TABLE
• DROP TABLE
• UNDROP TABLE
• TRUNCATE TABLE
• DELETE
• ALTER TABLE

Das Erfassen von Log-Events wird als Serverless-Feature abgerechnet. Snowflake greift dafür auf eigene, von Snowflake verwaltete Ressourcen zurück – eines Ihrer Virtual Warehouses ist also nicht nötig. Wie viel das Feature gekostet hat, lässt sich über den View EVENT_USAGE_HISTORY nachvollziehen:

select
    start_time,
    end_time,
    credits_used,
    bytes_ingested
from snowflake.account_usage.EVENT_USAGE_HISTORY
order by start_time desc;

Tomáš Sobotík·Senior Data Engineer & Snowflake SME bei Norlys

Tomas ist langjähriger Snowflake Data SuperHero und ausgewiesener Snowflake-Experte. Seit über einem Jahrzehnt ist er in der Datenwelt zu Hause – als Snowflake Data Engineer, Architect und Admin in Projekten quer durch unterschiedlichste Branchen und Technologien. Tomas ist festes Mitglied der Community, teilt sein Wissen aktiv und inspiriert andere. Darüber hinaus ist er O'Reilly-Instructor und leitet Live-Online-Trainings.