Référence de table OpenTelemetry pour Zerobus Ingest
Cette page fournit des informations de référence sur les schémas de table OpenTelemetry (OTLP) et le mappage des données utilisés par Zerobus Ingest OTLP.
Schéma de table
Lorsque les données OTLP arrivent, Zerobus Ingest convertit chaque enregistrement de la hiérarchie imbriquée OTLP resource/scope/record en une ligne plate et dénormalisée. Les attributs des ressources et les informations de portée d’instrumentation sont intégrés directement dans chaque ligne, ce qui rend les données immédiatement interrogeables sans jointure.
Tous les champs d’attribut (attributes, resource.attributes, instrumentation_scope.attributes, body pour les logs, metadata pour les métriques) sont stockés dans des colonnes de type VARIANT. VARIANT est un type semi-structuré de Delta Lake qui stocke des données JSON tout en préservant les types d’origine. Pour savoir comment chaque type de valeur OTLP est stocké, consultez Valeurs des attributs.
Chaque enregistrement est augmenté de champs spécifiques à Databricks :
Champ | Description | Source |
|---|---|---|
| Un ID généré par le système pour une identification unique et un tri par ordre chronologique. | Généré en fonction du temps. |
| Timestamp en microsecondes à partir de l'époque Unix. | Timestamp (en microsecondes) dérivé de |
| Colonne de partition de date, pour un filtrage efficace par plage horaire. | Dérivé de |
| Colonne de niveau supérieur pour un filtrage efficace par nom de service, tel que défini dans la convention sémantique OTel. | Extrait de |
Précision numérique et types signés
Les types Delta diffèrent des types OTLP de la manière suivante :
- Les valeurs métriques entières perdent leur précision au-dessus de 2^53. Les points de données
Gauge,SumetExemplardont la valeur estas_int, un entier 64 bits, sont convertis enDOUBLE, car Zerobus Ingest stocke toutes les valeurs métriques dans une colonne à virgule flottante unique.DOUBLEne représente exactement que les entiers jusqu’à 2^53, soit environ 9 quadrillions ; les valeursas_intsupérieures perdent donc leur précision exacte après conversion. Cela concerne principalement les très grands compteurs cumulatifs, comme le nombre total d’octets ou de requêtes sur toute la durée de vie. - Les champs OTLP non signés sont stockés en tant que champs signés.
INTetBIGINTsont toujours signés dans Delta, mais OTLP définit certains champs numériques comme non signés (uint32,uint64,fixed64) ou comme des compteurs à largeur fixe très grands. Les champs tels que*_time_unix_nano,flags,dropped_attributes_count, etc., sont stockés tels quels dans une colonneINTouBIGINTsignée. Une valeur supérieure au maximum signé (i32::MAXpourINT,i64::MAXpourBIGINT) est convertie en nombre négatif au lieu de générer une erreur.
Mappage de schéma
Zerobus Ingest met en correspondance les données OTLP avec les colonnes de table Delta, comme décrit ci-dessous.
Dénormalisation
Dans le protocole OTLP, les données de télémétrie sont imbriquées comme suit.
ResourceSpans (or ResourceLogs, ResourceMetrics)
└── Resource (attributes, schema_url)
└── ScopeSpans (or ScopeLogs, ScopeMetrics)
└── InstrumentationScope (name, version, attributes)
└── Span (or LogRecord, Metric)
Zerobus Ingest aplanit cette hiérarchie afin que chaque ligne contienne le contexte complet :
resource: Une struct contenant les attributs de ressource (en tant queVARIANT) etdropped_attributes_count.resource_schema_url: L'URL du schéma des ResourceSpans, ResourceLogs ou ResourceMetrics englobants.instrumentation_scope: Une structure contenant le nom de la portée, la version, les attributs (commeVARIANT) etdropped_attributes_count.span_schema_url/log_schema_url/metric_schema_url: l'URL du schéma provenant des ScopeSpans, ScopeLogs ou ScopeMetrics englobants.
Points de données de mesure
Chaque point de données de métrique est stocké sur sa propre ligne. Les name, description, unit et metadata de la métrique sont répétés sur chaque ligne, et les start_time_unix_nano et time_unix_nano du point de données sont stockés dans les colonnes de premier niveau portant le même nom.
metric_type est gauge, sum, histogram, exponential_histogram ou summary. Le point de données est stocké dans la colonne struct avec ce nom, et les quatre autres colonnes struct sont NULL.
Valeurs d’attribut
Les valeurs d’attribut et les corps des logs sont des valeurs AnyValue OTLP, stockées comme suit :
Type de valeur OTLP | Stocké en tant que |
|---|---|
| Chaîne |
| Booléen |
| Entier |
| Double. |
| Tableau |
| Objet |
| Chaîne encodée en hexadécimal en minuscules. Par exemple, les octets |
Il est impossible de distinguer un bytes_value d'un string_value contenant le même texte. Pour obtenir les octets d'origine, décodez-le avec unhex, par exemple unhex(attributes:['payload']::string).
Si la même clé apparaît plus d'une fois dans une liste d'attributs ou un kvlist_value, la dernière valeur est stockée.
Encodage de l'ID
trace_id, span_id et parent_span_id sont stockés sous forme de chaînes hexadécimales encodées en minuscules :
trace_id: chaîne hexadécimale de 32 caractères (16 octets)span_idetparent_span_id: chaîne hexadécimale de 16 caractères (8 octets)
Un ID est invalide s'il a la mauvaise longueur ou s'il n'est composé que de zéros. Pour les trace_id et span_id d'un span, consultez Enregistrements rejetés. Les autres ID manquants et invalides sont traités comme suit :
- Un
parent_span_idmanquant ou non valide est stocké commeNULL, donc l'intervalle est stocké comme intervalle racine. - Un
trace_idou unspan_idmanquant ou invalide sur un enregistrement de log est stocké sous la formeNULL, et l'enregistrement de log est ingéré. - Les
trace_idetspan_iddes Link de span et des exemplaires sont stockés codés en hexadécimal tels qu’ils sont reçus, sans validation.
Encodage d'énumération
kind, status.code, et severity_number sont stockés sous forme de chaînes portant les noms qui leur sont attribués dans la spécification OTLP, par exemple SPAN_KIND_SERVER, STATUS_CODE_OK, et SEVERITY_NUMBER_INFO. Une valeur qui n’est pas définie par la spécification OTLP est stockée sous sa forme numérique, par exemple 42.
aggregation_temporality est stocké sans le préfixe AGGREGATION_TEMPORALITY_, sous la forme DELTA ou CUMULATIVE.
Enregistrements rejetés
Zerobus Ingest rejette un enregistrement qui échoue à l'une des vérifications suivantes. Pour savoir comment les enregistrements rejetés sont signalés, consultez Succès partiel.
Un span est rejeté lorsque :
trace_idouspan_idest manquant ou invalide.start_time_unix_nanoest manquant.
Un point de données de métrique est rejeté lorsque :
- Sa métrique n’a pas de
nameou a une valeuraggregation_temporalityque la spécification OTLP ne définit pas. Tous les points de données de la métrique sont rejetés. time_unix_nanoest manquant ou 0.- Un point de données de jauge ou de somme n'a aucune valeur.
- Un point de données d'histogramme a
explicit_boundsmais pasbucket_counts, a un nombre debucket_countsautre que le nombre deexplicit_boundsplus un, ou abucket_countsqui ne s'additionnent pas àcount. - Un point de données d’histogramme exponentiel a des nombres de compartiments positifs, des nombres de compartiments négatifs et
zero_countqui ne s’additionnent pas àcount. - Un point de données d'histogramme, d'histogramme exponentiel ou de résumé possède un
countde 0 et unsumdifférent de 0.
Les points de données avec l’indicateur NO_RECORDED_VALUE défini ignorent les vérifications de valeur, count, sum et de bucket.
Les enregistrements de log ne sont pas rejetés pour leur contenu. Pour savoir comment les ID manquants ou invalides d'un enregistrement de log sont stockés, consultez Codage d'ID.
Étapes suivantes
- Configurez les clients OpenTelemetry (OTLP) pour envoyer des données à Unity Catalog: Configurez un SDK ou un collecteur OpenTelemetry pour envoyer des traces, des Logs et des métriques à Zerobus Ingest.
- Query des données OpenTelemetry: exemples de queries SQL pour explorer vos données de télémétrie.
- Gestion des erreurs d'ingestion Zerobus: Dépannage des erreurs courantes et des codes d'erreur.
- Quotas Zerobus Ingest: examinez les limites de throughput et de rétention pour Zerobus Ingest.