Konfigurieren Sie Ereignisdefinitionen für eine App¶

In diesem Thema wird beschrieben, wie Sie in der Manifest-Date einer App Ereignisdefinitionen festlegen. Ereignisdefinitionen legen fest, welche Protokollmeldungen und Ablaufverfolgungsereignisse für einen Anbieter freigegeben werden.

Ü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 Ereignisdefinitionen für eine App fest, wenn eine neue Version oder ein Patch veröffentlicht wird.

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.

Ereignisdefinitionen sind optional. Wenn ein Anbieter keine Ereignisdefinitionen für eine App angibt, können Verbraucher die gemeinsame Nutzung von Ereignissen nur dann für alle Ereignisse aktivieren oder deaktivieren, wenn der Anbieter die Ablaufverfolgung von Ereignissen aktiviert.

Vorsicht

Die Ereignisdefinitionen unterscheiden sich von den vom Anbieter eingestellten Protokoll- und Ablaufverfolgungsebenen. Die Protokoll- und Ablaufverfolgungsstufen bestimmen die Informationen, die in die Ereignistabelle des Verbrauchers eingefügt werden. Wenn weder die Protokoll- noch die Ablaufverfolgung festgelegt sind, gibt die App keine Ereignisse aus.

Die Protokoll- und Ablaufverfolgungsstufen für eine Anwendung können sich je nach den vom Verbraucher aktivierten Ereignisdefinitionen ändern. Snowflake verwendet die ausführlichsten Protokoll- und Ablaufverfolgungsstufen, die die vom Verbraucher aktivierten Ereignisdefinitionen zulassen.

Obligatorische und optionale Ereignisdefinitionen¶

Anbieter können eine Ereignisdefinition als Anforderung oder optional festlegen:

Erforderliche Ereignisdefinitionen werden automatisch aktiviert, wenn die App installiert wird.

Nach der Installation einer App mit erforderlichen Ereignisdefinitionen können Verbraucher die gemeinsame Nutzung von Ereignissen oder die erforderlichen Ereignisdefinitionen nicht deaktivieren. Wenn eine App aktualisiert wird, können Anbieter mithilfe von Systemfunktionen oder der Python Permission SDK überprüfen, ob der Verbraucher alle erforderlichen Ereignisdefinitionen aktiviert hat.
Optionale Ereignisdefinitionen können vom Verbraucher je nach Bedarf aktiviert oder deaktiviert werden.

Unterstützte Ereignisdefinitionen¶

Die folgende Tabelle listet die derzeit unterstützten Ereignisdefinitionen auf.

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’)`
Metrics	SNOWFLAKE$METRICS	Verbrauchern die Freigabe von Metriken für Anbieter ermöglichen.	`RECORD_TYPE in (‘METRIC’)`

Bemerkung

Snowsight zeigt dem Verbraucher nur den Typ „Alle Ereignisse“ All an, wenn der Anbieter die App nicht für die Verwendung von Ereignisdefinitionen konfiguriert hat.

Beschränkungen bei Ereignisdefinitionen in Apps mit Containern¶

Snowflake Native Apps with Snowpark Container Services unterstützt derzeit nur die ALL-Ereignisdefinition. Die Unterstützung für weitere Ereignisdefinitionen wird in einem zukünftigen Release hinzugefügt.

Protokoll- und Ablaufverfolgungsstufen für eine App festlegen¶

Damit eine App die Ablaufverfolgung von Ereignissen nutzen kann, muss ein Anbieter die Protokoll- und Ablaufverfolgungsstufen in der Manifest-Datei konfigurieren.

Um die Protokoll- und Ablaufverfolgungsstufen für eine App festzulegen, fügen Sie einen configuration-Block in die Datei manifest.yml ein, wie im folgenden Beispiel gezeigt:

configuration:
  ...
  log_level: INFO
  trace_level: ALWAYS
  metric_level: ALL
  ...

Copy

In diesem Beispiel werden die Protokoll- und Ablaufverfolgungsstufen für die App wie folgt festgelegt:

Die log_level-Eigenschaft ist auf INFO eingestellt.
Die trace_level-Eigenschaft ist auf ALWAYS eingestellt.
Die metric_level-Eigenschaft ist auf ALL eingestellt.

Weitere Informationen zu den gültigen Werten für diese Parameter finden Sie unter LOG_LEVEL, TRACE_LEVEL und METRIC_LEVEL.

Vorsicht

Nachdem Sie eine App veröffentlicht haben, können die Protokoll- und Ablaufverfolgungsstufen nicht mehr geändert werden. Wenn die Protokoll- und Ablaufverfolgungsstufen nicht in der Manifest-Datei festgelegt sind, gibt die App keine Informationen aus.

Wenn die Protokoll- und Ablaufverfolgungsstufen für eine App festgelegt sind, müssen die Verbraucher in ihrem Konto eine Ereignistabelle einrichten, um die von der App ausgegebenen Protokollmeldungen und Ablaufverfolgungsereignisse zu sehen.

Damit der Anbieter die von einer App erzeugten Protokollmeldungen und Ablaufverfolgungen sehen kann, müssen die Verbraucher die Ereignisfreigabe aktivieren. Weitere Informationen finden Sie unter Über die Ereignisfreigabe für eine App.

Eine Ereignisdefinition der Manifest-Datei hinzufügen¶

Um eine Ereignisdefinition anzugeben, fügt ein Anbieter einen Eintrag in den Block configuration.telemetry_event_definitions der Manifest-Datei ein, wie im folgenden Beispiel gezeigt:

configuration:
  telemetry_event_definitions:
    - type: ERRORS_AND_WARNINGS
      sharing: MANDATORY
    - type: DEBUG_LOGS
      sharing: OPTIONAL

Copy

In diesem Beispiel werden die folgenden Ereignisdefinitionen angegeben:

Eine geforderte Ereignisdefinition mit dem ERRORS_AND_WARNINGS-Typ.
Eine optionale Ereignisdefinition mit dem DEBUG_LOGS-Typ.

Weitere Informationen dazu finden Sie unter Unterstützte Ereignisdefinitionen.

Nachdem ein Verbraucher eine App installiert hat, erscheinen die Ereignisdefinitionen auf der Events and logs-Registerkarte auf der Security-Seite der App. Weitere Informationen finden Sie unter Protokollierung und Ereignisfreigabe aktivieren.

Legen Sie die Protokoll-, Ablaufverfolgungs- und Metrik-Stufen für bestimmte Objekte fest¶

Anbieter können die Protokoll-, Ablaufverfolgungs- und Metrik-Stufen für bestimmte Objekte innerhalb einer Anwendung feinabstimmen. Dies gibt Anbietern mehr Kontrolle über die von der App ausgegebenen Telemetriedaten.

Anbieter können die Protokoll-, Ablaufverfolgungs- und Metrik-Stufen für die folgenden Objekte innerhalb einer App festlegen:

Schemas
Versionierte Schemas
Gespeicherte Prozeduren
Benutzerdefinierte Funktionen

In der folgenden Tabelle sind die SQL-Befehle aufgeführt, mit denen Sie die Protokoll-, Ablaufverfolgungs- und Ereignisstufen für diese Objekte einstellen können:

Objekt	Befehl
Schemas	ALTER SCHEMA
Versioniertes Schema	CREATE OR ALTER VERSIONED SCHEMA
Gespeicherte Prozeduren	ALTER PROCEDURE
Benutzerdefinierte Funktionen	ALTER FUNCTION

Für Schemas, gespeicherte Prozeduren und benutzerdefinierte Funktionen können Anbieter die SET-Klausel der ALTER-Befehle verwenden, um die folgenden Eigenschaften festzulegen:

LOG_LEVEL
TRACE_LEVEL
METRIC_LEVEL

Bei versionierten Schemas können Anbieter diese Eigenschaften mit CREATE OR ALTER VERSIONED SCHEMA im Setup-Skript festlegen.

Rangfolge der Protokoll-, Ablaufverfolgungs- und Metrik-Stufen¶

Innerhalb einer App können die Protokoll-, Ablaufverfolgungs- und Metrik-Stufen für die Komponenten der App unterschiedlich konfiguriert werden. Um die Ereignisse zu bestimmen, die ausgegeben werden, verwendet Snowflake Native App Framework die folgende Rangfolge:

Gespeicherte Prozeduren und benutzerdefinierte Funktionen

Wenn für eine bestimmte gespeicherte Prozedur oder benutzerdefinierte Funktion eine Überschreibung festgelegt ist, hat diese Vorrang.
Schemas und versionierte Schemas

Wenn keine Überschreibungen für gespeicherte Prozeduren oder benutzerdefinierte Funktionen festgelegt sind, haben Überschreibungen für Schemas und versionierte Schemas Vorrang.
Einstellungen auf App-Ebene

Wenn keine Überschreibungen auf Objektebene gefunden werden, wird die Telemetriekonfiguration auf Anwendungsebene verwendet, die normalerweise in der Manifestdatei definiert ist.