Pular para o conteúdo principal
Última atualização em

Tabela de referência OpenTelemetry para ingestão Zerobus

Esta página fornece informações de referência para os esquemas de tabelas e mapeamento de dados do OpenTelemetry (OTLP) usados pelo Zerobus Ingest OTLP.

Esquema da tabela​

Quando os dados OTLP chegam, o Zerobus Ingest converte cada registro da hierarquia aninhada de recursos/escopos/registros OTLP em uma linha plana e desnormalizada. Os atributos de recurso e as informações de escopo de instrumentação estão incorporados diretamente em cada linha, tornando os dados imediatamente consultáveis sem necessidade de junção.

Todos os campos de atributos (attributes, resource.attributes, instrumentation_scope.attributes, body para logs, metadata para métricas) são armazenados como colunas VARIANT . VARIANT é um tipo semiestruturado no Delta Lake que armazena dados JSON, preservando os tipos originais.

Cada registro é enriquecido com campos específicos do Databricks:

campo

Descrição

Origem

record_id

Um ID gerado pelo sistema para identificação única e classificação por ordem cronológica.

Gerado com base no tempo

time

Data e hora em microssegundos a partir da época Unix.

Timestamp (em microssegundos) derivado de start_time_unix_nano (spans) ou time_unix_nano (logs, métricas)

date

Coluna de partição de data, para filtragem eficiente por intervalo de tempo.

Derivado de time

service_name

Coluna de nível superior para filtragem eficiente por nome de serviço, conforme definido na convenção semântica OTel.

Extraído de resource.attributes["service.name"]

campo

Descrição

Origem

record_id

Um ID gerado pelo sistema para identificação única e classificação por ordem cronológica.

Gerado com base no tempo

time

Data e hora em microssegundos a partir da época Unix.

Timestamp (em microssegundos) derivado de start_time_unix_nano (spans) ou time_unix_nano (logs, métricas)

date

Coluna de partição de data, para filtragem eficiente por intervalo de tempo.

Derivado de time

service_name

Coluna de nível superior para filtragem eficiente por nome de serviço, conforme definido na convenção semântica OTel.

Extraído de resource.attributes["service.name"]

Precisão numérica e tipos assinados​

Devido a algumas limitações de tipo do Delta, esteja atento ao seguinte:

  • Valores de métricas inteiras perdem precisão acima de 2^53. Os pontos de dados Gauge, Sum e Exemplar que relatam seu valor como as_int, um número inteiro de 64 bits, são convertidos para DOUBLE, uma vez que o Zerobus Ingest armazena todos os valores de métricas em uma única coluna de ponto flutuante. DOUBLE representa apenas números inteiros exatamente até 2^53, cerca de 9 quatrilhões, portanto, valores as_int maiores perdem a precisão exata após a conversão. Isso é importante principalmente para contadores cumulativos muito grandes, como totais de bytes ou de solicitações durante todo o período.
  • Campos OTLP não assinados são armazenados como assinados. INT e BIGINT são sempre assinados no Delta, mas o OTLP define alguns campos numéricos como não assinados (uint32, uint64, fixed64) ou como contadores de largura fixa muito grandes. Campos como *_time_unix_nano, flags, dropped_attributes_count, etc., são armazenados como estão em uma coluna INT ou BIGINT assinada. Um valor acima do máximo assinado (i32::MAX para INT, i64::MAX para BIGINT) é convertido para um número negativo em vez de gerar um erro.

Mapeamento de esquema​

O Zerobus Ingest mapeia os dados OTLP para as colunas da tabela Delta conforme descrito abaixo.

Desnormalização​

No protocolo OTLP, os dados de telemetria são aninhados da seguinte forma.

ResourceSpans (or ResourceLogs, ResourceMetrics)
  └── Resource (attributes, schema_url)
       └── ScopeSpans (or ScopeLogs, ScopeMetrics)
            └── InstrumentationScope (name, version, attributes)
                 └── Span (or LogRecord, Metric)

O Zerobus Ingest simplifica essa hierarquia, de forma que cada linha contenha o contexto completo:

  • resource: Uma estrutura contendo os atributos do recurso (como VARIANT) e dropped_attributes_count.
  • resource_schema_url: O URL do esquema dos ResourceSpans, ResourceLogs ou ResourceMetrics que os contêm.
  • instrumentation_scope: Uma estrutura contendo o nome do escopo, versão, atributos (como VARIANT) e dropped_attributes_count.
  • span_schema_url / log_schema_url / metric_schema_url: O URL do esquema dos ScopeSpans, ScopeLogs ou ScopeMetrics que o contêm.

Codificação de ID​

trace_id, span_id e parent_span_id são armazenados como strings codificadas em hexadecimal em letras minúsculas:

  • trace_idCadeias hexadecimais de 32 caracteres (16 bytes)
  • span_idCadeias hexadecimais de 16 caracteres (8 bytes)

Codificação Enum​

Os valores de enumeração (kind, status.code, aggregation_temporality, severity_number) são armazenados como seus nomes de string conforme definido na especificação OTLP. Por exemplo: SPAN_KIND_SERVER, STATUS_CODE_OK, AGGREGATION_TEMPORALITY_DELTA.

Próximos passos​

Nesta página