Como o Snowflake representa eventos de rastreamento¶
Internamente, o Snowflake usa o modelo de dados OpenTelemetry para representar eventos de rastreamento em um objeto chamado span. Um span descreve uma operação, como a invocação de um procedimento armazenado ou a execução de uma UDF em um conjunto de linhas. Um span inclui a hora de início e a hora de término da operação.
Dica
Para as diretrizes a serem consideradas ao adicionar eventos de rastreamento, consulte Diretrizes gerais para adicionar eventos de rastreamento.
Como o Snowflake emite eventos de rastreamento¶
Quando um procedimento armazenado ou UDF é chamado, o Snowflake pode executá-lo em paralelo, onde cada unidade de execução paralela é executada em um conjunto diferente de linhas. Todos os eventos de rastreamento emitidos têm escopo para sua unidade de execução e são agrupados dentro do mesmo span.
Os eventos de rastreamento são emitidos somente após a conclusão de sua unidade de execução. Se a unidade de execução falhar antes da conclusão, não é garantido que os eventos de rastreamento dessa unidade de execução sejam emitidos.
Os eventos de rastreamento de diferentes unidades de execução são armazenados em linhas separadas da tabela de eventos (ou seja, em diferentes spans).
Nota
Como UDFs são aplicadas por linha da tabela de entrada, as chamadas para APIs do evento de rastreamento em sua UDF são executadas para cada linha da tabela de entrada. Adicionar um evento de rastreamento para cada linha não é aconselhável na maioria dos casos. Há um limite de 128 eventos por unidade de execução.
Exemplo: emissão de eventos de um procedimento Java¶
O exemplo a seguir ilustra como você pode emitir eventos a partir do código do manipulador. Ele também mostra como os dados de eventos gerados são armazenados em uma tabela de eventos.
Procedimento armazenado com manipulador Java¶
O código Java no exemplo a seguir ilustra como você pode adicionar eventos a um span, juntamente com dados de atributo. Para obter mais informações sobre APIs para linguagens do manipulador, consulte Rastreamento de eventos a partir do código do manipulador.
CREATE OR REPLACE PROCEDURE test_stored_proc()
RETURNS STRING
LANGUAGE JAVA
RUNTIME_VERSION = '11'
PACKAGES=('com.snowflake:snowpark:latest', 'com.snowflake:telemetry:latest')
HANDLER = 'MyClass.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;
import io.opentelemetry.api.common.AttributesBuilder;
public class MyClass {
public String run(Session session) {
// 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);
// Setting span attributes of different types.
Telemetry.setSpanAttribute("example.boolean", true);
Telemetry.setSpanAttribute("example.long", 2L);
Telemetry.setSpanAttribute("example.double", 2.5);
Telemetry.setSpanAttribute("example.string", "testAttribute");
return "SUCCESS";
}
}
$$;
Dados de span registrados¶
Após a execução bem-sucedida da função ou do procedimento, o Snowflake renderiza o objeto de span do OpenTelemetry como um objeto nas colunas da tabela de eventos, conforme mostrado nas tabelas a seguir.
Um span pode ter seus próprios atributos. Como um span representa um procedimento armazenado e uma unidade de execução da UDF, pode ser útil definir atributos em nível de extensão para análise de dados posterior. Para obter mais informações sobre como definir atributos de span, consulte o conteúdo específico da linguagem na qual você está escrevendo o código do manipulador. Para obter uma lista dessas linguagens, consulte Rastreamento de eventos a partir do código do manipulador.
Um span pode conter um número máximo de 128 eventos de rastreamento e um número máximo de 128 atributos de span.
Se o número de eventos de rastreamento exceder o limite, os eventos serão descartados da seguinte forma, dependendo da linguagem do manipulador:
Para os manipuladores Python, os eventos são descartados na ordem em que foram adicionados (em outras palavras, o primeiro a entrar será o primeiro a sair).
Para manipuladores escritos em Java, JavaScript, Scala e Script Snowflake, novos eventos são descartados quando o limite é atingido.
Se o número de atributos de span exceder o limite, não será possível adicionar mais atributos de span.
Nota
A partir de novembro de 2022, todas as chaves dropped_*_count não estão definidas para JavaScript porque o OpenTelemetry JavaScript Tracing SDK não informa sobre contagens descartadas.
Descrição |
Dados |
|---|---|
Span registrado pelo Snowflake para a execução do procedimento que contém o código do manipulador. |
|
Atributos adicionados pelo código do manipulador para o span. |
|
Dados de eventos registrados¶
O span contém uma lista de eventos de rastreamento com carimbos de data/hora que capturam quando os eventos de rastreamento foram adicionados. Não mostrado aqui: o span tem um trace_id que é o ID de consulta sem traços. O span também tem valores gerados pelo sistema para as chaves span_id e name. Os eventos que fazem parte do span compartilham o mesmo span_id.
Os dados a seguir foram registrados para o evento testEvent.
Descrição |
Dados |
|---|---|
Nome do evento |
|
Os seguintes dados foram registrados para o evento testEventWithAttributes.
Descrição |
Dados |
|---|---|
Nome do evento |
|
Atributos do evento |
|