Ausgeben von Ablaufverfolgungsereignissen in Python¶
Sie können das telemetry
-Paket von Snowflake verwenden, um Ablaufverfolgungsereignisse von einem in Python geschriebenen Funktions- oder Prozedur-Handler auszugeben. Das Paket ist über den Anaconda-Snowflake-Kanal verfügbar.
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 Ablaufverfolgung anzeigen.
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 zur Einstellung 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 Überblick über die Ereignisse.
Sicherstellen, dass der Protokolliergrad (Ablaufverfolgungsebene) so eingestellt ist, dass die gewünschten Meldungen in der Ereignistabelle gespeichert werden.
Weitere Informationen dazu finden Sie unter Einstellung der Grade für Protokollierung, Metriken und Ablaufverfolgung.
Bemerkung
Richtlinien, die beim Hinzufügen von Ablaufverfolgungsereignissen berücksichtigt werden sollten, finden Sie unter Allgemeine Richtlinien für das Hinzufügen von Ablaufverfolgungsereignissen.
Hinzufügen von Unterstützung für das Telemetrie-Paket¶
Um das Telemetrie-Paket verwenden zu können, müssen Sie das Open-Source-Telemetrie-Paket von Snowflake, das in Snowflake enthalten ist, für Ihren Handler-Code zur Verfügung stellen. Das Paket ist über den Anaconda-Snowflake-Kanal verfügbar.
Bei einer Prozedur oder Funktion. Fügen Sie in der PACKAGES-Klausel Ihrer CREATE PROCEDURE- oder CREATE FUNCTION-Anweisung das Paket
snowflake-telemetry-python
ein. Die PACKAGES-Klausel stellt das darin enthaltene Snowflake-Telemetrie-Paket für Ihren Code zur Verfügung.Bei einer Streamlit-App. Sie können das
snowflake-telemetry-python
-Paket zu Ihrer App hinzufügen, indem Sie Snowsight oder eineenvironment.yml.
-Datei verwenden.Der Code im folgenden Beispiel verwendet die PACKAGES-Klausel, um auf das Telemetrie-Paket sowie auf die Snowpark-Bibliothek zu verweisen (die für in Python geschriebene gespeicherte Prozeduren erforderlich ist. Weitere Informationen dazu finden Sie unter Schreiben von gespeicherten Prozeduren in Python).
CREATE OR REPLACE FUNCTION my_function(...) RETURNS ... LANGUAGE PYTHON ... PACKAGES = ('snowflake-telemetry-python') ...
Importieren Sie das Paket
telemetry
in Ihren Code.from snowflake import telemetry
Hinzufügen von Ablaufverfolgungsereignissen¶
Sie können Ablaufverfolgungsereignisse hinzufügen, indem Sie die Methode telemetry.add_event
aufrufen und einen Namen für das Ereignis übergeben. Sie können einem Ereignis optional auch Attribute (Schlüssel-Wert-Paare) zuordnen.
Die Methode add_event
ist in der folgenden Form verfügbar:
telemetry.add_event(<name>, <attributes>)
Wobei:
name
ist eine Python-Zeichenfolge, die den Namen des Ablaufverfolgungsereignisses angibt.
attributes
ist ein OpenTelemetry Attributes-Objekt, das die Attribute für dieses Ablaufverfolgungsereignis angibt. Dieses Argument ist optional. Lassen Sie das Argument weg, wenn Sie keine Attribute für dieses Ablaufverfolgungsereignis angeben möchten.
Der Handler-Code im folgenden Beispiel fügt zwei Ereignisse hinzu: FunctionEmptyEvent
und FunctionEventWithAttributes
. Mit FunctionEventWithAttributes
fügt der Code auch zwei Attribute hinzu: key1
und key2
.
telemetry.add_event("FunctionEmptyEvent")
telemetry.add_event("FunctionEventWithAttributes", {"key1": "value1", "key2": "value2"})
Das Hinzufügen dieser Ereignisse führt zu zwei Zeilen in der Ereignistabelle, die jeweils einen anderen Wert in der Spalte RECORD haben:
{
"name": "FunctionEmptyEvent"
}
{
"name": "FunctionEventWithAttributes"
}
Die Ereigniszeile FunctionEventWithAttributes
enthält in der Spalte RECORD_ATTRIBUTES die folgenden Attribute:
{
"key1": "value1",
"key2": "value2"
}
Hinzufügen von Bereichsattributen¶
Durch Aufruf der Methode telemetry.set_span_attribute
können Sie Attribute (Schlüssel-Wert-Paare) festlegen, die bestimmten Bereichen (Spans) zugeordnet sind.
Weitere Informationen zu Bereichen (Spans) finden Sie unter Darstellung von Ablaufverfolgungsereignissen in Snowflake.
Die Methode set_span_attribute
ist in der folgenden Form verfügbar:
telemetry.set_span_attribute(<key>, <value>)
Wobei:
key
ist eine Python-Zeichenfolge, die den Schlüssel für ein Attribut angibt.
value
ist ein OpenTelemetry AttributeValue-Objekt, das den Wert des Attributs angibt.
Der Code im folgenden Beispiel erstellt vier Attribute und legt deren Werte fest:
// Setting span attributes.
telemetry.set_span_attribute("example.boolean", true);
telemetry.set_span_attribute("example.long", 2);
telemetry.set_span_attribute("example.double", 2.5);
telemetry.set_span_attribute("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)¶
Bemerkung
Die Unterstützung für benutzerdefinierte Zeiträume ist ein Vorschau-Feature, das für alle Konten verfügbar ist.
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 OpenTelemetry Python API, um den my.span
Bereich (Span) als aktuellen Bereich mit start_as_current_span
zu erstellen. Anschließend wird dem neuen Bereich (Span) unter Vetrwendung der OpenTelemetry Python API ein Ereignis mit Attributen hinzugefügt.
Ereignisdaten werden nur dann von der Ereignistabelle erfasst, wenn der Bereich (Span) endet, bevor Ihr Handler die Ausführung abgeschlossen hat. In diesem Beispiel wird der Bereich (Span) automatisch geschlossen, wenn die with
-Anweisung beendet ist.
CREATE OR REPLACE FUNCTION customSpansPythonExample() RETURNS STRING
LANGUAGE PYTHON
RUNTIME_VERSION = 3.9
PACKAGES = ('snowflake-telemetry-python', 'opentelemetry-api')
HANDLER = 'custom_spans_function'
AS $$
from snowflake import telemetry
from opentelemetry import trace
def custom_spans_function():
tracer = trace.get_tracer("my.tracer")
with tracer.start_as_current_span("my.span") as span:
span.add_event("Event2 in custom span", {"key1": "value1", "key2": "value2"})
return "success"
$$;
Python-Beispiele¶
In den folgenden Abschnitten finden Sie Beispiele für das Hinzufügen von Unterstützung für Ablaufverfolgungsereignisse aus Python-Code.
Beispiel einer gespeicherten Prozedur¶
CREATE OR REPLACE PROCEDURE do_tracing()
RETURNS VARIANT
LANGUAGE PYTHON
PACKAGES=('snowflake-snowpark-python', 'snowflake-telemetry-python')
RUNTIME_VERSION = 3.9
HANDLER='run'
AS $$
from snowflake import telemetry
def run(session):
telemetry.set_span_attribute("example.proc.do_tracing", "begin")
telemetry.add_event("event_with_attributes", {"example.key1": "value1", "example.key2": "value2"})
return "SUCCESS"
$$;
Streamlit-Beispiel¶
import streamlit as st
from snowflake import telemetry
st.title("Streamlit trace event example")
hifives_val = st.slider("Number of high-fives", min_value=0, max_value=90, value=60)
if st.button("Submit"):
telemetry.add_event("new_submission", {"high_fives": hifives_val})
UDF-Beispiel¶
CREATE OR REPLACE FUNCTION times_two(x number)
RETURNS NUMBER
LANGUAGE PYTHON
PACKAGES=('snowflake-telemetry-python')
RUNTIME_VERSION = 3.9
HANDLER = 'times_two'
AS $$
from snowflake import telemetry
def times_two(x):
telemetry.set_span_attribute("example.func.times_two", "begin")
telemetry.add_event("event_without_attributes")
telemetry.add_event("event_with_attributes", {"example.key1": "value1", "example.key2": "value2"})
response = 2 * x
telemetry.set_span_attribute("example.func.times_two.response", response)
return response
$$;
Wenn Sie die Ablaufverfolgungsereignis-API aus einer Python-Funktion aufrufen, die eine Eingabezeile verarbeitet, wird die API für jede Zeile aufgerufen, die von der UDF verarbeitet wird.
Die folgende Anweisung ruft beispielsweise die im vorherigen Beispiel definierte Python-Funktion für 50 Zeilen auf, was zu 100 Ablaufverfolgungsereignissen führt (zwei für jede Zeile):
select count(times_two(seq8())) from table(generator(rowcount => 50));
UDTF-Beispiel¶
CREATE OR REPLACE FUNCTION digits_of_number(input number)
RETURNS TABLE(result number)
LANGUAGE PYTHON
PACKAGES=('snowflake-telemetry-python')
RUNTIME_VERSION = 3.9
HANDLER = 'TableFunctionHandler'
AS $$
from snowflake import telemetry
class TableFunctionHandler:
def __init__(self):
telemetry.add_event("test_udtf_init")
def process(self, input):
telemetry.add_event("test_udtf_process", {"input": str(input)})
response = input
while input > 0:
response = input % 10
input /= 10
yield (response,)
def end_partition(self):
telemetry.add_event("test_udtf_end_partition")
$$;
Wenn Sie die Ablaufverfolgungsereignis-API in der process()
-Methode einer UDTF-Handler-Klasse aufrufen, wird die API für jede verarbeitete Zeile aufgerufen.
Die folgende Anweisung ruft beispielsweise die im vorherigen Beispiel definierte Methode process()
für 50 Zeilen auf, was zu 100 Ablaufverfolgungsereignissen (zwei für jede Zeile) führt, die von der Methode process()
hinzugefügt werden:
select * from table(generator(rowcount => 50)), table(digits_of_number(seq8())) order by 1;