Einrichten der Ablaufverfolgung von Ereignissen für eine App¶
In diesem Thema wird beschrieben, wie Sie die Ablaufverfolgung von Ereignissen einrichten, um die von einer Anwendung ausgegebenen Meldungen und Ereignisse zu erfassen. Außerdem wird beschrieben, wie Sie die gemeinsame Nutzung von Ereignissen aktivieren, um Protokollmeldungen und Ablaufverfolgungen mit Anbietern auszutauschen.
Über die Ablaufverfolgung von Ereignissen in Snowflake Native App Framework¶
Die Ablaufverfolgung von Ereignissen ermöglicht es einer Anwendung, Informationen zu ihrer Leistung und Verhaltensweise auszugeben. Snowflake Native App Framework unterstützt die Funktionalität von Snowflake zur Protokollierung und Ablaufverfolgung, um diese Informationen zu sammeln. Eine App kann Folgendes aussenden:
Logmeldungen, die unabhängige, detaillierte Meldungen mit Informationen über den Zustand eines bestimmten Features innerhalb der App sind.
Verfolgen Sie Ereignisse mit strukturierten Daten, die Sie verwenden können, um Informationen zu erhalten, die mehrere Teile einer Anwendung umfassen und gruppieren.
Anzeigen der Protokollmeldungen und Ereignisse einer App¶
Um die von der App ausgegebenen Meldungen und Ereignisse anzuzeigen, müssen Verbraucher in ihrem Konto eine Ereignistabelle einrichten, um diese Informationen zu sammeln. Weitere Informationen finden Sie unter Einrichten einer Ereignistabelle.
Über die Freigabe von Ereignissen¶
Verbraucher können auch die Ereignisfreigabe aktivieren, um Ereignisdaten mit Anbietern zu teilen. Wenn ein Anbieter die Ereignisfreigabe aktiviert, werden die Protokollmeldungen und Ablaufverfolgungsereignisse, die in die Ereignistabelle im Verbraucherkonto eingefügt werden, auch in eine Ereignistabelle im Anbieterkonto eingefügt.
Die Ereignisfreigabe ermöglicht es dem Anbieter, Informationen über die Leistung und die Verhaltensweisen der App zu sammeln. Weitere Informationen finden Sie unter Über die Ereignisfreigabe für eine App.
Über Definitionen von Ereignissen¶
Ereignisdefinitionen legen fest, wie eine Anwendung Meldungen und Ereignisse mit dem Anbieter austauscht. Ereignisdefinitionen dienen als Filter für die vom Anbieter eingestellten Stufen für Protokollmeldungen und Ablaufverfolgungsereignisse. Ein Anbieter legt die Definitionen der Ereignisse für eine App fest, wenn eine neue Version oder ein Patch veröffentlicht wird.
Bemerkung
Ereignisdefinitionen sind nicht erforderlich. Wenn ein Anbieter keine Definitionen von Ereignissen für eine App angibt, können Verbraucher die Ereignisfreigabe je nach Anforderung aktivieren oder deaktivieren.
Anbieter können eine Ereignisdefinition als Anforderung oder optional festlegen:
Erforderliche Ereignisdefinitionen werden automatisch aktiviert, wenn die App installiert wird. Um die von einer App ausgegebenen Ereignisdefinitionen zu sammeln, sollte ein Verbraucher eine Ereignistabelle erstellen und diese als aktive Ereignistabelle für sein Konto einstellen.
Optionale Ereignisdefinitionen können vom Verbraucher je nach Bedarf aktiviert oder deaktiviert werden. Optionale Ereignisdefinitionen erfordern eine aktive Ereignistabelle, aber sie sind nicht erforderlich, um die App zu installieren oder zu verwenden.
Vorsicht
Ereignisdefinitionen sind nicht identisch mit den vom Anbieter eingestellten Protokolliergraden und Ablaufverfolgungsstufen. Protokolliergrade und Ablaufverfolgungsstufen bestimmen die Informationen, die in die Ereignistabelle des Verbrauchers eingefügt werden.
Ereignisdefinitionen sind Filter, die sich auf Protokollmeldungen und Ablaufverfolgungsereignisse auswirken. Sie bestimmen, welche Informationen in die Ereignistabelle des Anbieters eingefügt werden, wenn die Ereignisfreigabe aktiviert ist.
Unterstützte Ereignisdefinitionen¶
Die folgende Tabelle listet die Ereignisdefinitionen auf, die derzeit unterstützt werden:
Typ
Name
Beschreibung
Filter
All
SNOWFLAKE$ALL
Gibt alle Meldungen und Ereignisse frei, die die App ausgibt.
*Errors and warnings
SNOWFLAKE$ERRORS_AND_WARNINGS
Gibt Protokolle zu Fehlern, Warnungen und fatalen Ereignissen frei.
RECORD_TYPE = ‘LOG’ AND RECORD:severity_text in (‘FATAL’, ‘ERROR’, ‘WARN’)Traces
SNOWFLAKE$TRACES
Gibt detaillierte Ablaufverfolgungen von Aktivitäten und Reisen des Benutzers in der Anwendung frei.
RECORD_TYPE in (‘SPAN’, ‘SPAN_EVENT’)Usage logs
SNOWFLAKE$USAGE_LOGS
Gibt High-Level-Protokolle zu Benutzeraktionen und App-Ereignissen frei.
RECORD_TYPE = LOG AND RECORD:severity_text = ‘INFO’Debug logs
SNOWFLAKE$DEBUG_LOGS
Gibt technische Protokolle zur Fehlerbehebung in der App frei.
RECORD_TYPE = ‘LOG’ AND RECORD:severity_text in (‘DEBUG’, ‘TRACE’)
Bemerkung
Wenn ein Anbieter die App nicht für die Verwendung von Ereignisdefinitionen konfiguriert hat, zeigt Snowsight nur den Typ All an.
Hinweise für Verbraucher bei der Verwendung von Ereignisdefinitionen¶
Verbraucher können die bestehenden Eigenschaften von SHARE_EVENTS_WITH_PROVIDER weiterhin nutzen, allerdings gibt es Beschränkungen:
Wenn eine Anwendung nur die Ereignisdefinition OPTIONAL ALL verwendet, aktiviert die Einstellung der Eigenschaft SHARE_EVENTS_WITH_PROVIDER auf
truedie Ereignisfreigabe und die Einstellung auffalsedeaktiviert die Ereignisfreigabe.Dies gilt, wenn ein Anbieter die Ereignisdefinition OPTIONAL ALL explizit zur Manifest-Datei hinzufügt oder eine App von der bestehenden Funktionalität für die Ereignisfreigabe migriert wurde.
Wenn ein Anbieter der Manifest-Datei obligatorische und optionale Ereignisdefinitionen hinzufügt, aktiviert die Einstellung der Eigenschaft SHARE_EVENTS_WITH_PROVIDER auf
truealle Ereignisdefinitionen. Im Gegensatz dazu kann die Eigenschaft SHARE_EVENTS_WITH_PROVIDER nur auffalseeingestellt werden, wenn der Anbieter nur optionale Ereignisdefinitionen hinzufügt.SHARE_EVENTS_WITH_PROVIDER ist nur dann TRUE, wenn alle Ereignisdefinitionen aktiviert sind, andernfalls ist es FALSE.
Workflow zur Einstellung der Ereignisablaufverfolgung für eine App¶
Der folgende Arbeitsablauf beschreibt, wie Sie die Ereignisablaufverfolgung für eine App einstellen:
Hinweise zur Ablaufverfolgung von Ereignissen¶
Bevor Sie die Ereignisablaufverfolgung für eine Anwendung einstellen, müssen Sie Folgendes beachten:
Für dieses Feature müssen Sie in Ihrem Konto eine Ereignistabelle einrichten.
Nachdem Sie die Ereignisfreigabe aktiviert haben, wird automatisch eine maskierte und unkenntlich gemachte Kopie der Ablaufverfolgungsereignisse und Protokollmeldungen in die Ereignistabelle des Kontos des gewünschten Anbieters eingefügt.
Snowflake erhebt keine Gebühren für die Freigabe von Ereignissen. Sie tragen jedoch die Kosten für die Aufnahme von Ablaufverfolgungsereignissen und Protokollmeldungen in die Ereignistabelle sowie die Kosten für den Speicher der Ereignistabelle.
Nachdem Sie die gemeinsame Nutzung von Ereignissen mit einem Anbieter aktiviert haben, können Sie den Zugriff auf gemeinsame Ablaufverfolgungsereignisse und Protokollmeldungen nicht mehr widerrufen.
Die Freigabe historischer Ereignisse ist mit der Ereignisfreigabe nicht möglich.
Snowflake sendet die freigegebenen Ereignisse an ein festgelegtes Anbieterkonto, das sich in derselben Region wie Ihr Konto befindet. Bei diesem Feature werden keine Daten zwischen verschiedenen Regionen ausgetauscht.
Sie können die Protokolliergrade oder die Ablaufverfolgungsstufen für eine Anwendung nicht ändern. Der Anbieter der App stellt diese Stufen bei der Veröffentlichung der App ein.
Snowflake empfiehlt, die Ablaufverfolgungsereignisse und die Protokollmeldungen in der Ereignistabelle zu überprüfen, bevor Sie die Ereignisfreigabe aktivieren.
Snowflake empfiehlt, die Ereignisfreigabe zu deaktivieren, wenn Sie keine Fehlerbehebung in der App durchführen müssen.
Ereignistabelle einrichten¶
Um die von der Anwendung ausgegebenen Protokollmeldungen und Ablaufverfolgungsereignisse zu sammeln, müssen die Verbraucher eine Ereignistabelle erstellen, um die Informationen zu speichern.
Bemerkung
IF der Verbraucher vor der Installation der App keine Ereignistabelle einrichtet und diese nicht zur aktiven Ereignistabelle macht, werden die Ablaufverfolgungsereignisse und die Protokolldaten verworfen.
Wenn ein Anbieter erforderliche Definitionen für Ereignisse in die App aufnimmt, werden diese bei der Installation standardmäßig aktiviert. Wenn der Verbraucher jedoch keine aktive Ereignistabelle hat, werden die von der App ausgegebenen Protokollmeldungen und Ablaufverfolgungsereignisse verworfen.
Ein Konto kann mehrere Ereignistabellen haben, aber es kann immer nur eine von ihnen als aktive Ereignistabelle in einem Snowflake-Konto eingestellt werden. Ohne eine aktive Ereignistabelle werden Protokollmeldungen und Ablaufverfolgungsereignisse, die die App ausgibt, nicht erfasst. Dies gilt selbst dann, wenn die Funktionen und Prozeduren in einer App die Protokollierung und Ablaufverfolgung des Ereignisses APIs direkt aufrufen.
Um eine Ereignistabelle zu erstellen, führen Sie den Befehl CREATE EVENT TABLE wie im folgenden Beispiel gezeigt aus:
CREATE EVENT TABLE event_db.event_schema.my_event_table;
Beachten Sie, dass dieser Befehl die Datenbank und das Schema angibt, die die Ereignistabelle enthalten.
Nachdem Sie die Ereignistabelle erstellt haben, legen Sie mit dem Befehl ALTER ACCOUNT fest, dass die Ereignistabelle die aktive Tabelle für das Konto sein soll:
ALTER ACCOUNT SET EVENT_TABLE=event_db.event_schema.my_event_table;
Aktivieren Sie die Ereignisfreigabe für eine App¶
Snowflake Native App Framework unterstützt die gemeinsame Nutzung von Protokollmeldungen und Ablaufverfolgungsereignissen, die in der Tabelle der Verbraucherereignisse gespeichert sind, mit dem Anbieter der Anwendung. Um Protokolle und Ereignisinformationen mit einem Anbieter zu teilen, muss der Verbraucher die Ereignisfreigabe für eine App aktivieren.
Voraussetzungen für die Aktivierung der Ereignisfreigabe für eine App¶
Die folgenden Voraussetzungen müssen erfüllt sein, um die Ereignisfreigabe für eine Anwendungsinstanz zu aktivieren:
Verwenden Sie eine Rolle mit der globalen Berechtigung MANAGE EVENT SHARING. Die Rolle ACCOUNTADMIN verfügt standardmäßig über diese Berechtigung und kann sie anderen Rollen zuweisen.
Aktivieren Sie die Ereignisfreigabe mit Snowsight¶
Bemerkung
Wenn der Anbieter die erforderlichen Ereignisdefinitionen in die App einbindet, werden die Ereignisfreigabe und die erforderlichen Definitionen während der Installation aktiviert und können später nicht deaktiviert werden.
So aktivieren Sie die Ereignisfreigabe für eine App:
Melden Sie sich bei Snowsight an.
Wählen Sie im Navigationsmenü die Option Data Products » Apps aus.
Wählen Sie die App aus.
Wählen Sie auf der Symbolleiste das Symbol Security aus.
Wählen Sie die Registerkarte Events and logs aus.
Wählen Sie unter dem Bereich Events and logs sharing Enable
Wenn der Anbieter Ereignisdefinitionen für die App definiert hat:
Verwenden Sie den Schieberegler, um optionale Ereignisdefinitionen zu aktivieren.
Wählen Sie Review aus.
Wenn derzeit keine Ereignistabelle ausgewählt ist, wählen Sie die Ereignistabelle aus der Liste unter Event table location.
Vorsicht
Seien Sie vorsichtig, wenn Sie die Ereignistabelle in Snowsight ändern. Jedes Snowflake-Konto verwendet eine einzige Ereignistabelle für alle Ereignisse, die innerhalb des Kontos generiert werden. Wenn Sie die Ereignistabelle ändern, werden alle in dem Konto generierten Ereignisse an dem neuen Ort gespeichert.
Aktivieren Sie die Ereignisfreigabe mit SQL¶
Um die Ereignisfreigabe für eine App zu aktivieren, verwenden Sie SQL:
Verwenden Sie den Befehl SHOW TELEMETRY EVENT DEFINITIONS, um die Ereignisdefinitionen für die App zu ermitteln:
SHOW TELEMETRY EVENT DEFINITIONS IN APPLICATION hello_snowflake;
Wenn der Anbieter die App nicht für die Verwendung von Ereignisdefinitionen konfiguriert hat, wird in der Spalte
typeALLangezeigt. Andernfalls listet dieser Befehl die optionalen Ereignisdefinitionen auf, die für die App angegeben wurden.Wenn die App erforderliche Ereignisdefinitionen enthält, verwenden Sie den Befehl ALTER APPLICATION, um sie zu aktivieren:
ALTER APPLICATION hello_snowflake SET AUTHORIZE_TELEMETRY_EVENT_SHARING=true
Dieser Befehl aktiviert alle erforderlichen Ereignisdefinitionen, nicht aber die optionalen Ereignisdefinitionen.
Bemerkung
Nachdem Sie die erforderlichen Ereignisdefinitionen für eine Anwendung aktiviert haben, kann die Ereignisfreigabe nicht mehr deaktiviert werden.
Wenn die App Ereignisdefinitionen enthält, verwenden Sie die Option ALTER APPLICATION, um sie zu aktivieren, wie im folgenden Beispiel gezeigt:
ALTER APPLICATION hello_snowflake SET SHARED TELEMETRY EVENTS ('SNOWFLAKE$TRACES', 'SNOWFLAKE$DEBUG_LOGS');
In diesem Beispiel werden die Befehle
SNOWFLAKE$TRACESundSNOWFLAKE$DEBUG_LOGSbasierend auf der Ausgabe des Befehls SHOW TELEMETRY EVENT DEFINITIONS aktiviert.Um zu überprüfen, ob die Ablaufverfolgung und Protokollierung von Ereignissen aktiviert ist, verwenden Sie den Befehl DESC APPLICATION:
DESC APPLICATION hello_snowflake;
Die Zeilen
authorize_telemetry_event_sharingundshare_events_with_providerder Ausgabe zeigen an, ob die Ereignisfreigabe aktiviert ist.
Ereignisfreigabe über SQL (ältere Funktionalität)¶
Vorsicht
Die in diesem Abschnitt beschriebene Methode zur Ereignisfreigabe über SQL wird in einem zukünftigen Release veraltet sein. Snowflake empfiehlt die unter Protokollierung und Ereignisfreigabe mit SQL aktivieren beschriebene Methode, um die Ereignisfreigabe über SQL zu aktivieren.
Um die Ereignisfreigabe für eine App zu aktivieren, führen Sie den Befehl ALTER APPLICATION aus, um SHARE_EVENTS_WITH_PROVIDER auf TRUE einzustellen. Beispiel:
ALTER APPLICATION HelloSnowflake SET SHARE_EVENTS_WITH_PROVIDER = TRUE;
Um den Status der Ereignisfreigabe für eine App anzuzeigen, verwenden Sie den Befehl DESC APPLICATION, wie im folgenden Beispiel gezeigt:
DESC APPLICATION HelloSnowflake;
SHARE_EVENTS_WITH_PROVIDER zeigt den Status der Ereignisfreigabe für die App an.
Aktivieren Sie Ereignisdefinitionen während Upgrades¶
Bei Upgrades verhalten sich die Ereignisdefinitionen wie folgt:
Änderung an Ereignisdefinitionen
Verhaltensweise während des Upgrades
Keine Änderung an Ereignisdefinitionen
Die Ereignisdefinition behält den gleichen Status wie die vorherige Version oder der vorherige Patch.
Eine neue Ereignisdefinition
Nicht automatisch aktiviert. Dies gilt sowohl für erforderliche als auch für optionale Ereignisdefinitionen. Der Verbraucher muss neue Ereignisdefinitionen manuell aktivieren.
Änderungen von erforderlich zu optional oder optional zu erforderlich
Die Ereignisdefinition behält den gleichen Status wie die vorherige Version oder der vorherige Patch.
Gelöschte Ereignisdefinition
Die Ereignisfreigabe wird nach dem Upgrade für Protokollmeldungen oder Filter für Ablaufverfolgungsereignisse in der vorherigen Version oder im Patch gestoppt.
Während des Upgrades werden die Benutzer aufgefordert, die Änderungen an den Ereignisdefinitionen aus dem vorherigen Patch oder der vorherigen Version zu überprüfen.
Anzeigen der Protokollmeldungen und Ablaufverfolgungsereignisse in der Ereignistabelle¶
WHen eine Ereignistabelle aktiviert ist, können Verbraucher die Ereignistabelle abfragen, um die von der App ausgegebenen Meldungen und Ablaufverfolgungsereignisse anzuzeigen. Verwenden Sie den Befehl SELECT, um die Ereignistabelle abzufragen, zum Beispiel:
SELECT * FROM event_db.event_schema.my_event_table;
Dieser Befehl gibt alle in der Ereignistabelle gespeicherten Meldungen und Ablaufverfolgungsereignisse zurück.
Anzeigen der Protokolliergrade und Ablaufverfolgungsstufen für eine App¶
Protokollgrad und Ablaufverfolgungsstufe einer App werden vom Anbieter vor der Veröffentlichung einer App festgelegt. Verbraucher können Protokolliergrade und Ablaufverfolgungsstufen für eine App nicht ändern.
Bevor Sie jedoch die Ablaufverfolgung einstellen oder die Ereignisfreigabe für eine App aktivieren, empfiehlt Snowflake, den Protokolliergrad zu überprüfen, um zu verstehen, welche Art von Informationen gesammelt und an den Anbieter weitergegeben werden.
Um Protokolliergrad und Ablaufverfolgungsstufe einer Anwendung anzuzeigen, führen Sie den folgenden Befehl aus:
DESC APPLICATION HelloSnowflake;
Dieser Befehl zeigt Informationen über die App HelloSnowflake an, einschließlich der folgenden Informationen über den für die App eingestellten Protokolliergrad und die Ablaufverfolgungsstufe:
log_level: Der vom Anbieter in der Manifest-Datei definierte Protokolliergrad.
trace_level: Die vom Anbieter in der Manifest-Datei definierte Ablaufverfolgungsstufe.
effective_log_level: Der Protokolliergrad, der für die Anwendung aktiviert ist.
effective_trace_level: Die für die Anwendung aktivierte Ablaufverfolgungsstufe.
Die effektiven Protokolliergrade und Ablaufverfolgungsstufen werden durch die Ereignisdefinitionen bestimmt, die der Verbraucher für die App aktiviert.
Wenn der Anbieter beispielsweise den Protokolliergrad als OFF definiert, der Verbraucher jedoch die Ereignisdefinition ERROR_AND_WARNING aktiviert, ändert die App den Protokolliergrad dynamisch auf WARN, sodass ERROR_AND_WARNING-Ereignisse gesammelt werden können. Die App gibt Ereignisse aus, die weniger oder genauso ausführlich sind wie WARN, und teilt diese Fehler- und Warnereignisse mit dem Anbieter. Der Wert von log_level wäre OFF, und der Wert von effective_log_level wäre WARN.
Wenn der Anbieter dagegen den Protokolliergrad als TRACE definiert, der Verbraucher jedoch die Ereignisdefinition ERROR_AND_WARNING aktiviert, gibt die App Ereignisse aus, die weniger oder genauso ausführlich sind wie „TRACE“, aber nur Fehler- und Warnmeldungen werden an den Anbieter weitergegeben. Der Wert sowohl von log_level als auch von effective_log_level würde TRACE lauten.