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 referenciar a biblioteca de telemetria, bem como a biblioteca Snowpark (que é necessária para procedimentos armazenados escritos em Scala – para 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"
}

Adição de spans personalizados¶

É possível adicionar spans personalizados separados do span padrão criado pelo Snowflake. Para obter detalhes sobre spans personalizados, consulte Adição de spans personalizados a um rastreamento.

O código no exemplo a seguir usa a API OpenTelemetry e a API de propagação de contexto OpenTelemetry para criar um novo span my.span. Em seguida, ele adiciona um evento ao novo span. Por fim, o código encerra o span para que os dados do evento do span sejam capturados na tabela de evento. Se o código não chamar o método, os dados não serão capturados na tabela de evento Span.end.

CREATE OR REPLACE FUNCTION testScalaUserSpans(x varchar) RETURNS VARCHAR
LANGUAGE SCALA
RUNTIME_VERSION = 2.12
PACKAGES = ('com.snowflake:telemetry:latest')
HANDLER = 'TestScalaClass.run'
AS
$$
class TestScalaClass {
  import com.snowflake.telemetry.Telemetry
  import io.opentelemetry.api.GlobalOpenTelemetry
  import io.opentelemetry.api.trace.Tracer
  import io.opentelemetry.api.trace.Span
  import io.opentelemetry.context.Scope

  def run(x: String): String = {
    val tracer: Tracer = GlobalOpenTelemetry.getTracerProvider().get("my.tracer")
    val span: Span = tracer.spanBuilder("my.span").startSpan()
    span.addEvent("test event from scala")
    span.end()
    return x
  }
}
$$;

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