Emissão de eventos de rastreamento em Python¶

Adição de suporte ao pacote de telemetria¶

Para usar o pacote de telemetria, você deve disponibilizar o pacote de telemetria de código aberto Snowflake, que está incluído no Snowflake, para o seu código de manipulador. O pacote está disponível no canal Anaconda Snowflake.

• Na cláusula PACKAGES de sua instrução CREATE PROCEDURE ou CREATE FUNCTION, inclua o pacote snowflake-telemetry-python. A cláusula PACKAGES torna o pacote de telemetria do Snowflake incluído disponível para seu código.

  O código no exemplo a seguir usa a cláusula PACKAGES para fazer referência ao pacote de telemetria e à biblioteca Snowpark (que é necessária para procedimentos armazenados escritos em Python - para obter mais informações, consulte Como escrever procedimentos armazenados em Python).

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

  Copy

• Importe o pacote telemetry em seu código de manipulador.

  from snowflake import telemetry
  

  Copy

Adição de eventos de rastreamento¶

Você pode adicionar eventos de rastreamento chamando o método telemetry.add_event, passando um nome para o evento. Opcionalmente, você também pode associar atributos - pares chave-valor - a um evento.

O método add_event está disponível na seguinte forma:

telemetry.add_event(<name>, <attributes>)

onde

• name é uma cadeia de caracteres Python que especifica o nome do evento de rastreamento.

• attributes é um objeto de atributos de OpenTelemetry que especifica os atributos para esse evento de rastreamento. Este argumento é opcional. Omita o argumento se você não tiver nenhum atributo a ser especificado para esse evento de rastreamento.

O código do manipulador no exemplo a seguir adiciona dois eventos, FunctionEmptyEvent e FunctionEventWithAttributes. Com FunctionEventWithAttributes, o código também adiciona dois atributos: key1 e key2.

telemetry.add_event("FunctionEmptyEvent")
telemetry.add_event("FunctionEventWithAttributes", {"key1": "value1", "key2": "value2"})

A adição desses eventos resulta em duas linhas na tabela de eventos, cada uma com um valor diferente na coluna RECORD:

{
  "name": "FunctionEmptyEvent"
}

{
  "name": "FunctionEventWithAttributes"
}

A linha de evento FunctionEventWithAttributes inclui os seguintes atributos na coluna RECORD_ATTRIBUTES da linha:

{
  "key1": "value1",
  "key2": "value2"
}

Adição de atributos de span¶

Você pode definir atributos - pares chave-valor - associados aos spans chamando o método telemetry.set_span_attribute.

Para obter mais detalhes sobre spans, consulte Como o Snowflake representa eventos de rastreamento.

O método set_span_attribute está disponível na seguinte forma:

telemetry.set_span_attribute(<key>, <value>)

onde:

• key é uma cadeia de caracteres Python que especifica a chave de um atributo.

• value é um objeto de OpenTelemetry AttributeValue que especifica o valor do atributo.

O código no exemplo a seguir cria quatro atributos e define seus valores:

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

A configuração desses atributos resulta no seguinte na coluna RECORD_ATTRIBUTES da tabela de eventos:

{
  "example.boolean": true,
  "example.long": 2,
  "example.double": 2.5,
  "example.string": "testAttribute"
}

Exemplos Python¶

As próximas seções fornecem exemplos de adição de eventos de rastreamento em procedimentos armazenados e funções do Python.

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

CREATE OR REPLACE FUNCTION times_two(x number)
RETURNS NUMBER
LANGUAGE PYTHON
PACKAGES=('snowflake-telemetry-python')
RUNTIME_VERSION=3.8
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
PACKAGES=('snowflake-telemetry-python')
RUNTIME_VERSION=3.8
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;