Adição de spans personalizados a um rastreamento

É possível adicionar seus próprios spans personalizados aos rastreamentos para um rastreamento mais refinado dentro do manipulador para um procedimento ou função.

Por padrão, quando o rastreamento está habilitado, o Snowflake inicia um span para você (conforme descrito em Como o Snowflake representa eventos de rastreamento) e adiciona todos os eventos de rastreamento a esse span. (Isso é conhecido internamente como span “auto_instrumented”.) Usando APIs OpenTelemetry, você pode criar seus próprios spans. Para o novo span, é possível adicionar eventos e atributos usando API OpenTelemetry o ou a Snowflake API para sua linguagem.

Talvez você queira criar seu próprio span quando, por exemplo, quiser isolar os dados de rastreamento para ações computacionais pesadas que acontecem dentro de um procedimento, como quando você está usando o código para treinar um modelo de ML.

Os spans personalizados que você cria correspondem ao comportamento padrão dos spans criados por OpenTelemetry.

Linguagens compatíveis

É possível adicionar spans personalizados a partir do código escrito nas seguintes linguagens, inclusive quando o código do manipulador que é escrito com as APIs Snowpark.

Idioma/tipo

Java

Python

JavaScript

Scala

Script Snowflake

Manipulador de procedimento armazenado

✔

✔

✔

✔ [1]

Aplicativo Streamlit

✔

Manipulador de UDF (função escalar)

✔

✔

✔

✔ [1]

Manipulador de UDTF (função de tabela)

✔

✔

✔

✔ [1] [2]

Criando um span personalizado

Para adicionar um span personalizado com código de manipulador, use a API OpenTelemetry para a linguagem de seu manipulador no ambiente de telemetria Snowflake existente para criar um novo span, adicionar eventos e atributos conforme necessário e, em seguida, fechar o span.

  1. Use a API OpenTelemetry para criar um rastreador para gerenciar o contexto do span.

    A partir deste rastreador criado a partir do ambiente de telemetria Snowflake existente, é possível criar spans personalizados que usam a infraestrutura existente na qual os dados de rastreamento são capturados pela tabela de evento.

  2. A partir do novo rastreador, crie o span personalizado com uma API que garanta que o novo span seja o span atual.

    Ao criar o novo span no contexto existente gerenciado pelo Snowflake, você garante que as informações do contexto – incluindo os valores trace_id e parent_span_id – sejam passadas do span padrão do Snowflake para outros spans.

  3. Quando seu código termina com o span personalizado, ele deve fechar o span antes que o manipulador conclua a execução para que os dados de rastreamento sejam capturados pela tabela de evento.

    Esse comportamento de spans personalizados corresponde ao comportamento padrão de OpenTelemetry.

Para obter informações sobre como adicionar um span personalizado com uma linguagem compatível, consulte os seguintes tópicos:

Exemplo em Python

O código no exemplo a seguir usa a API Python OpenTelemetry para criar o span my.span como o span atual com start_as_current_span. Em seguida, ele adiciona um evento com atributos ao novo span usando a `API Python OpenTelemetry`_.

Os dados do evento não serão capturados pela tabela de evento, a menos que o span termine antes que o manipulador conclua a execução. Neste exemplo, o fechamento do span ocorre automaticamente quando a instrução with é concluída.

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"
$$;
Copy
Linguagem: Português