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 |
|---|---|---|
| Um ID gerado pelo sistema para identificação única e classificação por ordem cronológica. | Gerado com base no tempo |
| Data e hora em microssegundos a partir da época Unix. | Timestamp (em microssegundos) derivado de |
| Coluna de partição de data, para filtragem eficiente por intervalo de tempo. | Derivado de |
| Coluna de nível superior para filtragem eficiente por nome de serviço, conforme definido na convenção semântica OTel. | Extraído de |
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,SumeExemplarque relatam seu valor comoas_int, um inteiro de 64 bits, são convertidos paraDOUBLE, pois o Zerobus Ingest armazena todos os valores de métrica em uma única coluna de ponto flutuante.DOUBLErepresenta apenas inteiros exatamente até 2^53, cerca de 9 quadrilhões, portanto, valores deas_intmaiores 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.
INTeBIGINTsã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 colunaINTouBIGINTassinada. Um valor acima do máximo assinado (i32::MAXparaINT,i64::MAXparaBIGINT) é 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 (comoVARIANT) edropped_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 (comoVARIANT) edropped_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 |
| Booleana |
| Integer |
| Double. |
| matriz |
| Objeto |
| String codificada em hexadecimal minúscula. Por exemplo, os bytes |
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_ideparent_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_idausente ou inválido é armazenado comoNULL, portanto, o intervalo é armazenado como um intervalo raiz. - Um
trace_idouspan_idausente ou inválido em um registro de log é armazenado comoNULL, e o registro de log é ingerido. - O
trace_idespan_idde 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_idouspan_idestá ausente ou inválido.start_time_unix_nanoestá ausente.
Um ponto de dados de métrica é rejeitado quando:
- Sua métrica não tem
nameou tem um valoraggregation_temporalityque a especificação OTLP não define. Todos os pontos de dados da métrica foram rejeitados. time_unix_nanoestá ausente ou é 0.- Um ponto de dados de medidor ou soma não tem valor.
- Um ponto de dados de histograma tem
explicit_boundsmas não tembucket_counts, tem um número debucket_countsdiferente do número deexplicit_boundsmais um, ou tembucket_countsque não totalizamcount. - Um ponto de dados de histograma exponencial tem contagens de bucket positivas, contagens de bucket negativas e
zero_countque não somamcount. - Um histograma, um histograma exponencial ou um ponto de dados de resumo tem
countigual a 0 esumdiferente 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
- Configure os clientes OpenTelemetry (OTLP) para enviar dados ao Unity Catalog: Configure um SDK ou Collector do OpenTelemetry para enviar rastreamentos, logs e métricas ao Zerobus Ingest.
- Consultar dados do OpenTelemetry: Exemplos de consultas SQL para explorar seus dados de telemetria.
- Tratamento de erros do Zerobus Ingest: Solução de problemas e códigos de erro comuns.
- Cotas do Zerobus Ingest: analise os limites de throughput e retenção do Zerobus Ingest.