Emissão de eventos de rastreamento em Java

Você pode usar a classe com.snowflake.telemetry.Telemetry na biblioteca API de telemetria para emitir eventos de rastreamento de um manipulador de função ou procedimento escrito em Java. A classe Telemetry está incluída no Snowflake.

Nota

O uso da biblioteca de telemetria do Snowflake adiciona outras bibliotecas ao ambiente de execução de sua função ou procedimento. Para obter mais informações, consulte Dependências do pacote de telemetria do Snowflake.

Para obter mais informações sobre como incluir a biblioteca de telemetria ao empacotar seu código com Maven, consulte Configurando seu ambiente Java e Scala para usar a classe de telemetria.

Você pode acessar os dados de eventos de rastreamento armazenados executando um comando SELECT na tabela de eventos. Para obter mais informações, consulte Acesso a dados de rastreamento.

Nota

Para as diretrizes a serem consideradas ao adicionar eventos de rastreamento, consulte Diretrizes gerais para adicionar eventos de rastreamento.

Para obter informações gerais sobre a configuração de registro e recuperação de mensagens no Snowflake, consulte Registro de mensagens de funções e procedimentos.

Antes de fazer o registro a partir do código, você deve:

Adição de suporte à API de telemetria

Para usar os métodos Telemetry, você deve tornar a biblioteca de telemetria do Snowflake, que está incluída no Snowflake, disponível para o seu código manipulador.

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

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

    CREATE OR REPLACE PROCEDURE MYPROC(...)
  RETURNS ...
  LANGUAGE JAVA
  ...
  PACKAGES = ('com.snowflake:snowpark:latest', 'com.snowflake:telemetry:latest')
  ...
    Copy

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

    import com.snowflake.telemetry.Telemetry;
    Copy

Adição de eventos de rastreamento

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

O método addEvent tem as seguintes assinaturas:

public static void addEvent(String name)
public static void addEvent(String name, Attributes attributes)
Copy

O código no exemplo a seguir adiciona um evento chamado testEvent, associando dois atributos ao evento: key e 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);
Copy

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

{
  "name": "testEvent"
}
Copy
{
  "name": "testEventWithAttributes"
}
Copy

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

{
  "key": "run",
  "result": 123
}
Copy

Adição de atributos de span

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

O método setSpanAttribute tem as seguintes assinaturas:

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

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

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

// Setting span attributes.
Telemetry.setSpanAttribute("example.boolean", true);
Telemetry.setSpanAttribute("example.long", 2L);
Telemetry.setSpanAttribute("example.double", 2.5);
Telemetry.setSpanAttribute("example.string", "testAttribute");
Copy

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"
}
Copy

Exemplos de Java

Exemplo de procedimento armazenado

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";
  }
}
$$;
Copy

Exemplo de UDF

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;
  }
}
$$;
Copy

Exemplo de UDTF

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