Pular para o conteúdo principal

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 atributo (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. Para saber como cada tipo de valor OTLP é armazenado, consulte Valores de atributo.

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). Para um registro de log sem time_unix_nano, observed_time_unix_nano é usado.

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). Para um registro de log sem time_unix_nano, observed_time_unix_nano é usado.

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​

Os tipos Delta diferem dos tipos OTLP das seguintes maneiras:

  • Os valores de métrica inteiros perdem a precisão acima de 2^53. Os pontos de dados Gauge, Sum e Exemplar que relatam seu valor como as_int, um inteiro de 64 bits, são convertidos para DOUBLE, pois o Zerobus Ingest armazena todos os valores de métrica em uma única coluna de ponto flutuante. DOUBLE representa apenas inteiros exatamente até 2^53, cerca de 9 quadrilhões, portanto, valores de as_int maiores perdem a precisão exata após a conversão. Isso é importante principalmente para contadores cumulativos muito grandes, como o total de bytes ou de solicitações ao longo do tempo.
  • 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.

Pontos de dados de métricas​

Cada ponto de dados de métrica é armazenado como sua própria linha. name, description, unit e metadata da métrica são repetidos em cada linha, e start_time_unix_nano e time_unix_nano do ponto de dados são armazenados nas colunas de nível superior com o mesmo nome.

metric_type é gauge, sum, histogram, exponential_histogram ou summary. O ponto de dados é armazenado na coluna struct com esse nome, e as outras quatro colunas struct são NULL.

Valores de atributo​

Os valores de atributo e corpos de log são valores OTLP AnyValue, que são armazenados da seguinte forma:

Tipo de valor OTLP

Armazenado como

string_value

String

bool_value

Booleana

int_value

Integer

double_value

Double. NaN, infinito positivo e infinito negativo são armazenados como as strings "NaN", "Infinity" e "-Infinity".

array_value

matriz

kvlist_value

Objeto

bytes_value

String codificada em hexadecimal minúscula. Por exemplo, os bytes 0x01 0xFF são armazenados como "01ff".

Tipo de valor OTLP

Armazenado como

string_value

String

bool_value

Booleana

int_value

Integer

double_value

Double. NaN, infinito positivo e infinito negativo são armazenados como as strings "NaN", "Infinity" e "-Infinity".

array_value

matriz

kvlist_value

Objeto

bytes_value

String codificada em hexadecimal minúscula. Por exemplo, os bytes 0x01 0xFF são armazenados como "01ff".

Um bytes_value não pode ser diferenciado de um string_value que contém o mesmo texto. Para obter os bytes originais, decodifique-os com unhex, por exemplo, unhex(attributes:['payload']::string).

Se a mesma key aparecer mais de uma vez em uma lista de atributos ou kvlist_value, o último valor é armazenado.

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_id e parent_span_id: string hexadecimal de 16 caracteres (8 bytes)

Um ID é inválido se tiver o comprimento incorreto ou se for composto apenas por zeros. Para trace_id e span_id de um span, veja Registros rejeitados. Outros IDs ausentes e inválidos são tratados da seguinte forma:

  • Um parent_span_id ausente ou inválido é armazenado como NULL, portanto, o intervalo é armazenado como um intervalo raiz.
  • Um trace_id ou span_id ausente ou inválido em um registro de log é armazenado como NULL, e o registro de log é ingerido.
  • O trace_id e span_id de links de span e exemplares são armazenados codificados em hex como recebidos, sem validação.

Codificação Enum​

kind, status.code e severity_number são armazenados como seus nomes de string conforme definidos na especificação OTLP, por exemplo SPAN_KIND_SERVER, STATUS_CODE_OK e SEVERITY_NUMBER_INFO. Um valor que a especificação OTLP não define é armazenado como seu número, por exemplo 42.

aggregation_temporality é armazenado sem o prefixo AGGREGATION_TEMPORALITY_, como DELTA ou CUMULATIVE.

Registros rejeitados​

O Zerobus Ingest rejeita um registro que falha em qualquer uma das seguintes verificações. Para saber como os registros rejeitados são reportados, consulte Sucesso parcial.

Um span é rejeitado quando:

  • trace_id ou span_id está ausente ou inválido.
  • start_time_unix_nano está ausente.

Um ponto de dados de métrica é rejeitado quando:

  • Sua métrica não tem name ou tem um valor aggregation_temporality que a especificação OTLP não define. Todos os pontos de dados da métrica foram rejeitados.
  • time_unix_nano está ausente ou é 0.
  • Um ponto de dados de medidor ou soma não tem valor.
  • Um ponto de dados de histograma tem explicit_bounds mas não tem bucket_counts, tem um número de bucket_counts diferente do número de explicit_bounds mais um, ou tem bucket_counts que não totalizam count.
  • Um ponto de dados de histograma exponencial tem contagens de bucket positivas, contagens de bucket negativas e zero_count que não somam count.
  • Um histograma, um histograma exponencial ou um ponto de dados de resumo tem count igual a 0 e sum diferente de 0.

Os pontos de dados com a flag NO_RECORDED_VALUE definida ignoram as verificações de valor, count, sum e bucket.

Os registros de logs não são rejeitados pelo seu conteúdo. Para saber como IDs ausentes ou inválidos de um registro de log são armazenados, consulte codificação de ID.

Próximos passos​