Referência da tabela OpenTelemetry para Ingestão do Zerobus

Esta página fornece informações de referência para os esquemas de tabela opentelemetry (OTLP) e mapeamento de dados usados pelo OTLP de ingestão do Zerobus.

Esquema de tabela

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

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

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

Campo Descrição Fonte
record_id Uma ID gerada pelo sistema para identificação exclusiva e classificação ordenada por tempo. Gerado com base no tempo
time Carimbo de data/hora em microssegundos da época unix. Carimbo de data/hora (em microssegundos) derivado de start_time_unix_nano (intervalos) ou time_unix_nano (logs, métricas)
date Coluna de partição de data, para filtragem eficiente de 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 de sinais

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

  • Valores inteiros de métricas perdem precisão acima de 2^53.Gauge, Sum, e Exemplar pontos de dados que reportam seu valor como as_int, um inteiro de 64 bits, são convertidos para DOUBLE, já que o Zerobus Ingest armazena todos os valores da métrica em uma única coluna de ponto flutuante. DOUBLE representa apenas inteiros exatamente até 2^53, cerca de 9 quadrilhões, então valores maiores as_int perdem precisão exata uma vez convertidos. Isso importa principalmente para contadores cumulativos muito grandes, como totais de bytes ou requisições ao longo da vida.
  • Campos OTLP sem assinatura são armazenados como assinados. INT e BIGINT são sempre assinados em Delta, mas OTLP define alguns campos numéricos como não sinalizados (uint32, uint64, fixed64) ou como contadores de largura fixa muito grandes. Campos como , , , etc., são armazenados as-is em uma coluna assinada *_time_unix_nanoflags. dropped_attributes_countINTBIGINT Um valor acima do máximo assinado (i32::MAX para INT, i64::MAX para BIGINT) se torna um número negativo em vez de causar erro.

Mapeamento de esquemas

Zerobus Ingest mapeia dados OTLP para colunas de tabela Delta, conforme descrito abaixo.

Desnormalização

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

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

Zerobus Ingest nivela essa hierarquia para que cada linha contenha o contexto completo:

  • resource: um struct que contém os atributos de recurso (como VARIANT) e dropped_attributes_count.
  • resource_schema_url: a URL de esquema do ResourceSpans, ResourceLogs ou ResourceMetrics delimitando.
  • instrumentation_scope: um struct que contém o nome do escopo, a versão, os atributos (como VARIANT) e dropped_attributes_count.
  • span_schema_url / log_schema_url / metric_schema_url: a URL do esquema do EscopoSpans, ScopeLogs ou ScopeMetrics delimitador.

Codificação de ID

trace_id, span_ide parent_span_id são armazenados como cadeias de caracteres codificadas em hex minúsculas:

  • trace_id: cadeia de caracteres hexáxe de 32 caracteres (16 bytes)
  • span_id: cadeia de caracteres hexáxe de 16 caracteres (8 bytes)

Codificação de enumeração

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

Próximas Etapas 

  • Last updated on