Emissão de eventos de rastreamento em Scala¶

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 Scala - para obter mais informações, consulte Como escrever procedimentos armazenados em Scala).

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

  Copy

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

  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)

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)

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

{
  "name": "testEvent"
}

{
  "name": "testEventWithAttributes"
}

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

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

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)

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

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¶

CREATE OR REPLACE PROCEDURE do_tracing()
RETURNS STRING
LANGUAGE SCALA
RUNTIME_VERSION = '2.12'
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;

class ProcedureHandler {

  def run(session: Session): String = {

    // 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.
    val eventAttributes: Attributes = Attributes.of(
      AttributeKey.stringKey("example.method.name"), "run")
    Telemetry.addEvent("event_with_attributes", eventAttributes);

    // Set span attribute.
    Telemetry.setSpanAttribute("example.proc.do_tracing", "complete");

    return "SUCCESS";
  }
}
$$;