Ausgeben von Ablaufverfolgungsereignissen in Java¶
Sie können die Klasse com.snowflake.telemetry.Telemetry
der Telemetrie-API-Bibliothek verwenden, um Ablaufverfolgungsereignisse von einem in Java 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 Protokollierung von Meldungen aus Funktionen und Prozeduren.
Bevor Sie die Protokollierung für Code nutzen können, müssen Sie Folgendes tun:
Einrichten einer Ereignistabelle, in der von Handler-Code protokollierte Meldungen gesammelt werden.
Weitere Informationen dazu finden Sie unter Einrichten einer Ereignistabelle.
Sicherstellen, dass der Protokolliergrad (Ablaufverfolgungsebene) so eingestellt ist, dass die gewünschten Meldungen in der Ereignistabelle gespeichert werden.
Weitere Informationen dazu finden Sie unter Einstellen des Protokolliergrads (Ablaufverfolgungsebene).
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 Java geschriebene gespeicherte Prozeduren erforderlich ist – weitere Informationen dazu finden Sie unter Schreiben von gespeicherten Prozeduren in Java).
CREATE OR REPLACE PROCEDURE MYPROC(...) RETURNS ... LANGUAGE JAVA ... PACKAGES = ('com.snowflake:snowpark:latest', 'com.snowflake:telemetry:latest') ...
Importieren Sie das Paket
com.snowflake.telemetry
in Ihren Java-Handler-Code.import com.snowflake.telemetry.Telemetry;
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"
}
Java-Beispiele¶
Beispiel einer gespeicherten Prozedur¶
CREATE OR REPLACE PROCEDURE do_tracing()
RETURNS STRING
LANGUAGE JAVA
RUNTIME_VERSION = '11'
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;
public class ProcedureHandler {
public String run(Session session) {
// 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.
Attributes eventAttributes = Attributes.of(
AttributeKey.stringKey("example.method.name"), "run",
AttributeKey.longKey("example.long"), Long.valueOf(123));
Telemetry.addEvent("event_with_attributes", eventAttributes);
// Set span attribute.
Telemetry.setSpanAttribute("example.proc.do_tracing", "complete");
return "SUCCESS";
}
}
$$;
UDF-Beispiel¶
CREATE OR REPLACE FUNCTION add_two_numbers(A FLOAT, B FLOAT) RETURNS FLOAT
LANGUAGE JAVA
PACKAGES=('com.snowflake:telemetry:latest')
HANDLER = 'ScalarFunctionHandler.run'
AS
$$
import com.snowflake.telemetry.Telemetry;
import io.opentelemetry.api.common.AttributeKey;
import io.opentelemetry.api.common.Attributes;
import io.opentelemetry.api.common.AttributesBuilder;
class ScalarFunctionHandler {
public static Double run(Double d0, Double d1) {
// Set span attribute.
Telemetry.setSpanAttribute("example.func.add_two_numbers", "begin");
// Add an event without attributes.
Telemetry.addEvent("run_method_start");
// Add an event with attributes.
Attributes eventAttributes = Attributes.of(
AttributeKey.stringKey("example.method.name"), "run",
AttributeKey.longKey("example.long"), Long.valueOf(123));
Telemetry.addEvent("event_with_attributes", eventAttributes);
Double response = d0 == null || d1 == null ? null : (d0 + d1);
// Set span attribute.
Telemetry.setSpanAttribute("example.func.add_two_numbers.response", response);
Telemetry.setSpanAttribute("example.func.add_two_numbers", "complete");
return response;
}
}
$$;
UDTF-Beispiel¶
CREATE OR REPLACE FUNCTION digits_of_number(x int)
RETURNS TABLE(result int)
LANGUAGE JAVA
PACKAGES=('com.snowflake:telemetry:latest')
HANDLER = 'TableFunctionHandler'
AS
$$
import com.snowflake.telemetry.Telemetry;
import io.opentelemetry.api.common.AttributeKey;
import io.opentelemetry.api.common.Attributes;
import io.opentelemetry.api.common.AttributesBuilder;
import java.util.stream.Stream;
public class TableFunctionHandler {
public TableFunctionHandler() {
// Set span attribute.
Telemetry.setSpanAttribute("example.func.digits_of_number", "begin");
}
static class OutputRow {
public int result;
public OutputRow(int result) {
this.result = result;
}
}
public static Class getOutputClass() {
return OutputRow.class;
}
public Stream<OutputRow> process(int input) {
// Add an event with attributes.
Attributes eventAttributes = Attributes.of(
AttributeKey.longKey("example.received.value"), Long.valueOf(input));
Telemetry.addEvent("digits_of_number", eventAttributes);
Stream.Builder<OutputRow> stream = Stream.builder();
while (input > 0) {
stream.add(new OutputRow(input %10));
input /= 10;
}
// Set span attribute.
Telemetry.setSpanAttribute("example.func.digits_of_number", "complete");
return stream.build();
}
}
$$;