Referência da tabela OpenTelemetry para Ingest de Zerobus

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

Esquema da tabela

Quando chegam dados OTLP, o Zerobus Ingest converte cada registo da hierarquia aninhada de recurso/escopo/registo OTLP numa linha plana e desnormalizada. Os atributos dos recursos e a informação do âmbito da instrumentação estão incorporados diretamente em cada linha, tornando os dados imediatamente consultáveis sem joins.

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

Cada registo é complementado com campos específicos de Databricks:

Campo Descrição Fonte
record_id Um ID gerado pelo sistema para identificação única e ordenação temporal. Gerado com base no tempo
time Carimbo temporal em microssegundos da época Unix. Carimbo temporal (em microssegundos) derivado de start_time_unix_nano (spans) ou time_unix_nano (logs, métricas)
date Coluna de partição de datas, para filtragem eficiente por intervalo temporal. Derivado de time
service_name Coluna de topo para filtragem eficiente pelo nome do serviço, conforme definido na convenção semântica OTel. Extraído de resource.attributes["service.name"]

Precisão numérica e tipos de assinatura

Devido a algumas limitações do tipo Delta, por favor tenha em atenção o seguinte:

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

Mapeamento de esquema

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

Desnormalização

No protocolo OTLP, os dados de telemetria são aninhados assim.

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

O Zerobus Ingest achata esta hierarquia de modo que cada linha contém o contexto completo:

  • resource: Uma estrutura contendo os atributos de recurso (como VARIANT) e dropped_attributes_count.
  • resource_schema_url: A URL do esquema dos ResourceSpans, ResourceLogs ou ResourceMetrics que anexam.
  • instrumentation_scope: Uma estrutura contendo 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 dos ScopeSpans, ScopeLogs ou ScopeMetrics que os envolvem.

Codificação de ID

trace_id, span_id, e parent_span_id são armazenadas como cadeias minúsculas codificadas em hexadecimais:

  • trace_id: cadeia hexadecimal de 32 caracteres (16 bytes)
  • span_id: cadeia hexadecimal de 16 caracteres (8 bytes)

Codificação enum

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

Passos seguintes

  • Last updated on