Ausgeben von Ablaufverfolgungsereignissen in Scala

Sie können die Klasse com.snowflake.telemetry.Telemetry der Telemetrie-API-Bibliothek verwenden, um Ablaufverfolgungsereignisse von einem in Scala geschriebenen Funktions- oder Prozedur-Handler auszugeben. Die Klasse Telemetry wird von Snowflake bereitgestellt.

Bemerkung

Durch Verwendung der Snowflake-Telemetrie-Bibliothek werden der Ausführungsumgebung Ihrer Funktion oder Prozedur weitere Bibliotheken hinzugefügt. Weitere Informationen dazu finden Sie unter Abhängigkeiten des Snowflake-Telemetrie-Pakets.

Weitere Informationen zum Einbinden der Telemetrie-Bibliothek beim Packen Ihres Codes mit Maven finden Sie unter Einrichten Ihrer Java- und Scala-Umgebung für die Verwendung der Telemetrie-Klasse.

Sie können auf die gespeicherten Daten zu den Ablaufverfolgungsereignissen zugreifen, indem Sie einen SELECT-Befehl auf der Ereignistabelle ausführen. Weitere Informationen dazu finden Sie unter Zugriff auf Ablaufverfolgungsdaten.

Bemerkung

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

Allgemeine Informationen zum Einrichten der Protokollierung und zum Abrufen von Meldungen in Snowflake finden Sie unter Ablaufverfolgungsereignisse von Funktionen und Prozeduren.

Bevor Sie die Protokollierung für Code nutzen können, müssen Sie Folgendes tun:

Hinzufügen von Unterstützung für die Telemetrie-API

Um Telemetry-Methoden verwenden zu können, müssen Sie die Snowflake-Telemetrie-Bibliothek, die in Snowflake enthalten ist, Ihrem Handler-Code zur Verfügung stellen.

  • Fügen Sie in der PACKAGES-Klausel Ihrer CREATE PROCEDURE- oder CREATE FUNCTION-Anweisung das Paket com.snowflake:telemetry ein. Die PACKAGES-Klausel stellt die darin enthaltene Snowflake-Telemetrie-API für Ihren Code zur Verfügung.

    Der Code im folgenden Beispiel verwendet die PACKAGES-Klausel, um auf die Telemetrie-Bibliothek sowie auf die Snowpark-Bibliothek zu verweisen (die für in Scala geschriebene gespeicherte Prozeduren erforderlich ist – weitere Informationen dazu finden Sie unter Schreiben von gespeicherten Prozeduren in Scala).

    CREATE OR REPLACE PROCEDURE MYPROC(...)
  RETURNS ...
  LANGUAGE SCALA
  ...
  PACKAGES = ('com.snowflake:snowpark:latest', 'com.snowflake:telemetry:latest')
  ...
    Copy

  • Importieren Sie das Paket com.snowflake.telemetry in Ihren Handler-Code.

    import com.snowflake.telemetry.Telemetry
    Copy

Hinzufügen von Ablaufverfolgungsereignissen

Sie können Ablaufverfolgungsereignisse hinzufügen, indem Sie die Methode Telemetry.addEvent aufrufen und einen Namen für das Ereignis übergeben. Sie können einem Ereignis optional auch Attribute (Schlüssel-Wert-Paare) zuordnen.

Die Methode addEvent hat die folgenden Signaturen:

public static void addEvent(String name)
public static void addEvent(String name, Attributes attributes)
Copy

Der Code im folgenden Beispiel fügt ein Ereignis mit dem Namen testEvent hinzu und ordnet diesem zwei Attribute zu: key und result.

// 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)
Copy

Das Hinzufügen dieser Ereignisse führt zu zwei Zeilen in der Ereignistabelle, die jeweils einen anderen Wert in der Spalte RECORD haben:

{
  "name": "testEvent"
}
Copy
{
  "name": "testEventWithAttributes"
}
Copy

Die Ereigniszeile testEventWithAttributes enthält in der Spalte RECORD_ATTRIBUTES die folgenden Attribute:

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

Hinzufügen von Bereichsattributen

Durch Aufruf der Methode Telemetry.setSpanAttribute können Sie Attribute (Schlüssel-Wert-Paare) festlegen, die bestimmten Bereichen (Spans) zugeordnet sind.

Die Methode setSpanAttribute hat die folgenden Signaturen:

public static void setSpanAttribute(String key, boolean value)
public static void setSpanAttribute(String key, long value)
public static void setSpanAttribute(String key, double value)
public static void setSpanAttribute(String key, String value)
Copy

Weitere Informationen zu Bereichen (Spans) finden Sie unter Darstellung von Ablaufverfolgungsereignissen in Snowflake.

Der Code im folgenden Beispiel erstellt vier Attribute und legt deren Werte fest:

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

Das Einstellen dieser Attribute führt in der Spalte RECORD_ATTRIBUTES der Ereignistabelle zu folgendem Ergebnis:

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

Beispiele

Beispiel einer gespeicherten Prozedur

CREATE OR REPLACE PROCEDURE do_tracing()
RETURNS STRING
LANGUAGE SCALA
RUNTIME_VERSION = '2.12'
PACKAGES=('com.snowflake:snowpark:latest', 'com.snowflake:telemetry:latest')
HANDLER = 'ProcedureHandler.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;

class ProcedureHandler {

  def run(session: Session): String = {

    // Set span attribute.
    Telemetry.setSpanAttribute("example.proc.do_tracing", "begin");

    // Add an event without attributes.
    Telemetry.addEvent("run_method_start");

    // Add an event with attributes.
    val eventAttributes: Attributes = Attributes.of(
      AttributeKey.stringKey("example.method.name"), "run")
    Telemetry.addEvent("event_with_attributes", eventAttributes);

    // Set span attribute.
    Telemetry.setSpanAttribute("example.proc.do_tracing", "complete");

    return "SUCCESS";
  }
}
$$;
Copy
Sprache: Deutsch