Ausgeben von Ablaufverfolgungsereignissen in Python¶

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.

Standardmäßig ist das Telemetrie-Paket enthalten, wenn Sie einen Python-Handler für eine gespeicherte Prozedur oder Funktion erstellen. Wenn Sie jedoch eine Paketrichtlinie angeben, um bestimmte Pakete explizit zuzulassen oder zu verbieten, fügt Snowflake das snowflake-telemetry-python-Paket nicht automatisch hinzu. In diesem Fall müssen Sie das Paket in der Klausel PACKAGES-Klausel angeben.

• Bei einer Streamlit-App. Sie können das snowflake-telemetry-python -Paket zu Ihrer App hinzufügen, indem Sie Snowsight oder eine environment.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 mit SQL und Python).

  CopyExpand

  CREATE OR REPLACE FUNCTION my_function(...)
    RETURNS ...
    LANGUAGE PYTHON
    ...
    PACKAGES = ('snowflake-telemetry-python')
    ...
  

  Show lessSee more

  Scroll to top

• Importieren Sie das Paket telemetry in Ihren Code.

  CopyExpand

  from snowflake import telemetry
  

  Show lessSee more

  Scroll to top

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

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.12
  PACKAGES = ('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.

CREATE OR REPLACE PROCEDURE do_tracing()
  RETURNS VARIANT
  LANGUAGE PYTHON
  PACKAGES = ('snowflake-snowpark-python', 'snowflake-telemetry-python')
  RUNTIME_VERSION = 3.12
  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"
  $$;

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

CREATE OR REPLACE FUNCTION times_two(x NUMBER)
  RETURNS NUMBER
  LANGUAGE PYTHON
  RUNTIME_VERSION = 3.12
  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
$$;

select count(times_two(seq8())) from table(generator(rowcount => 50));

CREATE OR REPLACE FUNCTION digits_of_number(input NUMBER)
  RETURNS TABLE(result NUMBER)
  LANGUAGE PYTHON
  RUNTIME_VERSION = 3.12
  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")
$$;

select * from table(generator(rowcount => 50)), table(digits_of_number(seq8())) order by 1;