Aller au contenu principal

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

record_id

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.

time

Timestamp en microsecondes à partir de l'époque Unix.

Timestamp (en microsecondes) dérivé de start_time_unix_nano (spans) ou de time_unix_nano (Logs, métriques). Pour un enregistrement de log sans time_unix_nano, observed_time_unix_nano est utilisé.

date

Colonne de partition de date, pour un filtrage efficace par plage horaire.

Dérivé de time

service_name

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 resource.attributes["service.name"]

Champ

Description

Source

record_id

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.

time

Timestamp en microsecondes à partir de l'époque Unix.

Timestamp (en microsecondes) dérivé de start_time_unix_nano (spans) ou de time_unix_nano (Logs, métriques). Pour un enregistrement de log sans time_unix_nano, observed_time_unix_nano est utilisé.

date

Colonne de partition de date, pour un filtrage efficace par plage horaire.

Dérivé de time

service_name

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 resource.attributes["service.name"]

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, Sum et Exemplar dont la valeur est as_int, un entier 64 bits, sont convertis en DOUBLE, car Zerobus Ingest stocke toutes les valeurs métriques dans une colonne à virgule flottante unique. DOUBLE ne représente exactement que les entiers jusqu’à 2^53, soit environ 9 quadrillions ; les valeurs as_int supé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. INT et BIGINT sont 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 colonne INT ou BIGINT signée. Une valeur supérieure au maximum signé (i32::MAX pour INT, i64::MAX pour BIGINT) 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 que VARIANT) et dropped_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 (comme VARIANT) et dropped_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

string_value

Chaîne

bool_value

Booléen

int_value

Entier

double_value

Double. NaN, l’infini positif et l’infini négatif sont stockés sous les chaînes "NaN", "Infinity" et "-Infinity".

array_value

Tableau

kvlist_value

Objet

bytes_value

Chaîne encodée en hexadécimal en minuscules. Par exemple, les octets 0x01 0xFF sont stockés sous la forme "01ff".

Type de valeur OTLP

Stocké en tant que

string_value

Chaîne

bool_value

Booléen

int_value

Entier

double_value

Double. NaN, l’infini positif et l’infini négatif sont stockés sous les chaînes "NaN", "Infinity" et "-Infinity".

array_value

Tableau

kvlist_value

Objet

bytes_value

Chaîne encodée en hexadécimal en minuscules. Par exemple, les octets 0x01 0xFF sont stockés sous la forme "01ff".

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_id et parent_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_id manquant ou non valide est stocké comme NULL, donc l'intervalle est stocké comme intervalle racine.
  • Un trace_id ou un span_id manquant ou invalide sur un enregistrement de log est stocké sous la forme NULL, et l'enregistrement de log est ingéré.
  • Les trace_id et span_id des 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_id ou span_id est manquant ou invalide.
  • start_time_unix_nano est manquant.

Un point de données de métrique est rejeté lorsque :

  • Sa métrique n’a pas de name ou a une valeur aggregation_temporality que la spécification OTLP ne définit pas. Tous les points de données de la métrique sont rejetés.
  • time_unix_nano est 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_bounds mais pas bucket_counts, a un nombre de bucket_counts autre que le nombre de explicit_bounds plus un, ou a bucket_counts qui 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_count qui ne s’additionnent pas à count.
  • Un point de données d'histogramme, d'histogramme exponentiel ou de résumé possède un count de 0 et un sum diffé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​