Ausgeben von Ablaufverfolgungsereignissen in Scala¶

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 sowohl auf die Telemetrie-Bibliothek als auch auf die Snowpark-Bibliothek zu verweisen (die für in Scala geschriebene Prozeduren erforderlich ist. Weitere Informationen 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)

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)

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"
}

{
  "name": "testEventWithAttributes"
}

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

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

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)

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")

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"
}

Hinzufügen benutzerdefinierter Bereiche (Spans)¶

Sie können benutzerdefinierte Bereiche (Spans) hinzufügen, die sich von dem von Snowflake erstellten Standardbereich unterscheiden. Weitere Informationen zu benutzerdefinierten Bereichen (Spans) finden Sie unter Hinzufügen von benutzerdefinierten Bereichen zu einer Ablaufverfolgung.

Der Code im folgenden Beispiel verwendet die Kontextweitergabe OpenTelemetry API und OpenTelemetry API, um einen neuen Bereich (Span) my.span zu erstellen. Es fügt dann ein Ereignis zum neuen Bereich (Span) hinzu. Schließlich beendet der Code den Bereich (Span), damit die Ereignisdaten des Bereichs in der Ereignistabelle erfasst werden. Wenn der Code nicht die Span.end-Methode aufruft, werden die Daten nicht in der Ereignistabelle erfasst.

CREATE OR REPLACE FUNCTION testScalaUserSpans(x varchar) RETURNS VARCHAR
LANGUAGE SCALA
RUNTIME_VERSION = 2.12
PACKAGES = ('com.snowflake:telemetry:latest')
HANDLER = 'TestScalaClass.run'
AS
$$
class TestScalaClass {
  import com.snowflake.telemetry.Telemetry
  import io.opentelemetry.api.GlobalOpenTelemetry
  import io.opentelemetry.api.trace.Tracer
  import io.opentelemetry.api.trace.Span
  import io.opentelemetry.context.Scope

  def run(x: String): String = {
    val tracer: Tracer = GlobalOpenTelemetry.getTracerProvider().get("my.tracer")
    val span: Span = tracer.spanBuilder("my.span").startSpan()
    span.addEvent("test event from scala")
    span.end()
    return x
  }
}
$$;

Beispiele¶

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"
  }
}
$$;