Darstellung von Ablaufverfolgungsereignissen in Snowflake

Intern verwendet Snowflake das Datenmodell OpenTelemetry zur Darstellung von Ablaufverfolgungsereignissen in einem Objekt namens span. Ein span beschreibt eine Operation, z. B. den Aufruf einer gespeicherten Prozedur oder die Ausführung einer UDF über einer Menge von Zeilen. Ein solcher „span“ oder Bereich enthält die Start- und Endzeit der Operation.

Tipp

Richtlinien, die beim Hinzufügen von Ablaufverfolgungsereignissen berücksichtigt werden sollten, finden Sie unter Allgemeine Richtlinien für das Hinzufügen von Ablaufverfolgungsereignissen.

Ausgeben von Ablaufverfolgungsereignissen in Snowflake

Wenn eine gespeicherte Prozedur oder UDF aufgerufen wird, kann Snowflake diese parallel ausführen, wobei jede parallele Ausführungseinheit auf einer anderen Menge von Zeilen ausgeführt wird. Alle Ablaufverfolgungsereignisse, die ausgegeben werden, sind auf ihre Ausführungseinheit als Geltungsbereich beschränkt und in demselben Bereich (Span) eingeschlossen.

Ablaufverfolgungsereignisse werden erst nach Abschluss der jeweiligen Ausführungseinheit ausgegeben. Wenn die Ausführungseinheit vor der Beendigung fehlschlägt, ist nicht gewährleistet, dass die Ablaufverfolgungsereignisse von dieser Ausführungseinheit ausgegeben werden.

Ablaufverfolgungsereignisse aus verschiedenen Ausführungseinheiten werden in separaten Zeilen der Ereignistabelle gespeichert (d. h. in verschiedenen „spans“).

Bemerkung

Da UDFs pro Eingabetabellenzeile angewandt werden, werden Aufrufe der Ablaufverfolgungsereignis-APIs in Ihrer UDF für jede Eingabetabellenzeile ausgeführt. Das Hinzufügen eines Ablaufverfolgungsereignisses für jede Zeile ist in den meisten Fällen nicht ratsam. Es gibt eine Höchstzahl von 128 Ereignissen pro Ausführungseinheit.

Beispiel: Ausgeben von Ereignissen aus einer Java-Prozedur

Das folgende Beispiel veranschaulicht, wie Sie Ereignisse des Handler-Codes ausgeben können. Es zeigt auch, wie die generierten Ereignisdaten in einer Ereignistabelle gespeichert werden.

Gespeicherte Prozedur mit Java-Handler

Der Java-Code im folgenden Beispiel veranschaulicht, wie Sie Ereignisse zusammen mit Attributdaten zu einem Bereich (Span) hinzufügen können. Weitere Informationen zu APIs für Handler-Sprachen finden Sie unter Ereignisablaufverfolgung aus Handler-Code.

CREATE OR REPLACE PROCEDURE test_stored_proc()
RETURNS STRING
LANGUAGE JAVA
RUNTIME_VERSION = '11'
PACKAGES=('com.snowflake:snowpark:latest', 'com.snowflake:telemetry:latest')
HANDLER = 'MyClass.run'
AS
$$
  import com.snowflake.snowpark_java.Session;
  import com.snowflake.telemetry.Telemetry;
  import io.opentelemetry.api.common.AttributeKey;
  import io.opentelemetry.api.common.Attributes;
  import io.opentelemetry.api.common.AttributesBuilder;

  public class MyClass {

    public String run(Session session) {
        // Adding an event without attributes.
        Telemetry.addEvent("testEvent");

        // Adding an event with attributes.
        Attributes eventAttributes = Attributes.of(
            AttributeKey.stringKey("key"), "run",
            AttributeKey.longKey("result"), Long.valueOf(123));
        Telemetry.addEvent("testEventWithAttributes", eventAttributes);

        // Setting span attributes of different types.
        Telemetry.setSpanAttribute("example.boolean", true);
        Telemetry.setSpanAttribute("example.long", 2L);
        Telemetry.setSpanAttribute("example.double", 2.5);
        Telemetry.setSpanAttribute("example.string", "testAttribute");

        return "SUCCESS";
    }
  }
$$;
Copy

Erfasste Bereichsdaten

Nachdem die Funktion oder Prozedur erfolgreich ausgeführt wurde, verarbeitet Snowflake das OpenTelemetry-Bereichsobjekt („span“) als Objekte in Spalten der Ereignistabelle, wie in den folgenden Tabellen gezeigt.

Ein Bereich (Span) kann seine eigenen Attribute haben. Da ein Bereich (Span) die Ausführungseinheit einer gespeicherte Prozedur oder UDF darstellt, kann es nützlich sein, auf Bereichsebene Attribute für die spätere Datenanalyse festzulegen. Weitere Informationen zum Festlegen von Attributen für Bereiche (Spans) finden Sie in den Inhalten zur jeweiligen Sprache, in der Sie den Handler-Code schreiben. Eine Liste dieser Sprachen finden Sie unter Ereignisablaufverfolgung aus Handler-Code.

Ein Bereich (Span) kann eine maximale Anzahl von 128 Ablaufverfolgungsereignissen und eine maximale Anzahl von 128 Span-Attributen umfassen.

  • Wenn die Anzahl der Ablaufverfolgungsereignisse das Limit überschreitet, werden die Ereignisse je nach Sprache des Handlers wie folgt gelöscht:

    • Bei Python-Handlern werden die Ereignisse in der Reihenfolge gelöscht, in der sie hinzugefügt wurden (mit anderen Worten: in der Reihenfolge „first-in-first-out“).

    • Bei Handlern, die in Java, JavaScript, Scala und Snowflake Scripting geschrieben sind, werden nach Erreichen des Limits alle neuen Ereignisse gelöscht.

  • Übersteigt die Anzahl der Bereichsattribute das Limit, können keine weiteren Bereichsattribute hinzugefügt werden.

Bemerkung

Seit November 2022 sind alle dropped_*_count-Schlüssel nicht für JavaScript gesetzt, da das OpenTelemetry-JavaScript-Tracing-SDK keine Zählung von nicht erfassten Ereignissen ausgibt.

Beschreibung

Daten

Von Snowflake erfasster Bereich (Span) für die Ausführung der Prozedur, die den Handler-Code enthält.

  • Startzeitstempel aus der Spalte START_TIMESTAMP:

    2023-03-21 23:12:06.231

  • Endzeitstempel aus der Spalte TIMESTAMP:

    2023-03-21 23:12:06.944

  • Daten aus der Spalte RECORD:

    {
      "kind": "SPAN_KIND_INTERNAL",
      "name": "snow.auto_instrumented",
      "status": {
        "code": "STATUS_CODE_UNSET"
      }
    }
    
    Copy

Attribute, die durch den Handler-Code für den Bereich (Span) hinzugefügt werden.

  • Daten aus der Spalte RECORD_ATTRIBUTES:

    {
      "example.boolean": true,
      "example.double": 2.5,
      "example.long": 2,
      "example.string": "testAttribute"
    }
    
    Copy

Erfasste Ereignisdaten

Der Bereich (Span) enthält eine Liste von Ablaufverfolgungsereignissen mit Zeitstempeln, die angeben, wann die Ablaufverfolgungsereignisse hinzugefügt wurden. Hier nicht gezeigt: Der Bereich (Span) hat eine trace_id, die der Abfrage-ID ohne Bindestriche entspricht. Der Bereich (Span) hat auch systemgenerierte Werte für die Schlüssel span_id und name. Ereignisse, die Teil des Bereichs (Span) sind, haben dieselbe span_id.

Die folgenden Daten wurden für das Ereignis testEvent erfasst.

Beschreibung

Daten

Ereignisname

  • Zeitstempel aus der Spalte TIMESTAMP:

    2023-03-21 23:12:06.939

  • Daten aus der Spalte RECORD:

    {
      "dropped_attributes_count": 0,
      "name": "testEvent"
    }
    
    Copy

Die folgenden Daten wurden für das Ereignis testEventWithAttributes erfasst.

Beschreibung

Daten

Ereignisname

  • Zeitstempel aus der Spalte TIMESTAMP:

    2023-03-21 23:12:06.940

  • Daten aus der Spalte RECORD:

    {
      "dropped_attributes_count": 0,
      "name": "testEventWithAttributes"
    }
    
    Copy

Ereignisattribute

  • Daten aus der Spalte RECORD_ATTRIBUTES:

    {
      "key": "run",
      "result": 123
    }
    
    Copy