Temporalité métriques OTLP vers Dynatrace : delta ou cumulative, l’erreur qui fait disparaître vos compteurs

Temporalité métriques OTLP : diagnostiquez les compteurs cumulatifs rejetés par Dynatrace et passez en delta dans le SDK ou le Collector, pas à pas.
Temporalité métriques OTLP vers Dynatrace : delta ou cumulative, l'erreur qui fait disparaître vos compteurs

Les traces OpenTelemetry arrivent dans Dynatrace, les logs aussi, mais les compteurs restent introuvables. Pas d’erreur côté application, rien d’évident côté Collector. Dans la majorité des cas, la cause tient à la temporalité métriques OTLP (delta ou cumulative) : l’application envoie des sommes cumulatives, alors que Dynatrace attend des deltas.

Objectif de ce tutoriel : comprendre en deux minutes la différence entre delta et cumulative, repérer le problème, puis le corriger dans le SDK (Java, Python, Go) ou dans le Collector, et vérifier que les métriques arrivent. Le contenu vaut pour Dynatrace SaaS et Dynatrace Managed, qui exposent la même API OTLP.

Si vous débutez avec l’export OTLP, commencez par configurer le Collector OpenTelemetry vers Dynatrace.

Temporalité métriques OTLP : delta ou cumulative

Un compteur de requêtes reçoit 10 requêtes par minute. L’exporteur peut l’envoyer de deux façons :

Minute Cumulative Delta
1 10 10
2 20 10
3 30 10

En cumulative, chaque point contient le total depuis le démarrage du processus. En delta, il contient seulement l’accroissement depuis le point précédent. La plupart des SDK OpenTelemetry exportent en cumulative par défaut, un choix pensé pour Prometheus. L’API OTLP de Dynatrace, elle, attend des compteurs et des histogrammes en delta. Les points cumulatifs concernés ne sont pas ingérés.

Les jauges (gauges) n’ont pas de temporalité et passent sans changement. Les UpDownCounter sont acceptés dans les deux temporalités : en delta ils deviennent des compteurs, en cumulative des jauges. Les histogrammes cumulatifs, eux, sont rejetés comme les compteurs cumulatifs. Détails dans la documentation d’ingestion des métriques OTLP (page « About OTLP metrics ingest »).

Prérequis

  • Un token API avec le scope metrics.ingest.
  • L’endpoint OTLP de votre environnement (https://<env-id>.live.dynatrace.com/api/v2/otlp en SaaS, https://<votre-domaine>/e/<env-id>/api/v2/otlp en Managed).
  • Un SDK OpenTelemetry récent, ou un Collector contrib (le processeur utilisé plus bas fait partie de la distribution contrib).

Étape 1 — Confirmer le diagnostic

Ajoutez temporairement l’exporteur debug au Collector pour voir la temporalité réellement envoyée :

exporters:
  debug:
    verbosity: detailed

service:
  pipelines:
    metrics:
      receivers: [otlp]
      exporters: [debug, otlphttp/dynatrace]

Dans les logs du Collector, cherchez la ligne AggregationTemporality de vos compteurs. La valeur Cumulative confirme le problème. Sans Collector, la réponse de l’API OTLP peut signaler des points rejetés (réponse de succès partiel) : activez les logs de l’exporteur du SDK pour la voir.

Étape 2 — Corriger dans le SDK

Java, Python, .NET, Node.js : une variable d’environnement

export OTEL_EXPORTER_OTLP_METRICS_TEMPORALITY_PREFERENCE=delta

Cette variable fait partie de la spécification OpenTelemetry et elle est lue par les SDK Java (et l’agent Java), Python, .NET et Node.js. Vérifiez sa prise en charge dans la version du SDK que vous utilisez. Pour Java, elle est déjà incluse dans la configuration de l’agent OpenTelemetry Java.

Java : en code, si vous construisez l’exporteur vous-même

import io.opentelemetry.exporter.otlp.http.metrics.OtlpHttpMetricExporter;
import io.opentelemetry.sdk.metrics.export.AggregationTemporalitySelector;

OtlpHttpMetricExporter exporter = OtlpHttpMetricExporter.builder()
    .setEndpoint("https://abc12345.live.dynatrace.com/api/v2/otlp/v1/metrics")
    .addHeader("Authorization", "Api-Token " + System.getenv("DT_API_TOKEN"))
    .setAggregationTemporalitySelector(AggregationTemporalitySelector.deltaPreferred())
    .build();

Ligne critique : deltaPreferred() passe en delta les compteurs et histogrammes. Notez que l’URL complète, avec /v1/metrics, est requise quand on configure l’exporteur en code.

Go : un sélecteur de temporalité

Les exporteurs OTLP métriques Go récents lisent aussi cette variable, mais les anciennes versions l’ignorent. Pour un comportement explicite, quelle que soit la version, déclarez le sélecteur :

import (
    "context"

    "go.opentelemetry.io/otel/exporters/otlp/otlpmetric/otlpmetrichttp"
    sdkmetric "go.opentelemetry.io/otel/sdk/metric"
    "go.opentelemetry.io/otel/sdk/metric/metricdata"
)

exp, err := otlpmetrichttp.New(ctx,
    otlpmetrichttp.WithTemporalitySelector(
        func(sdkmetric.InstrumentKind) metricdata.Temporality {
            return metricdata.DeltaTemporality
        }),
)

Cet exemple force le delta pour tous les instruments. Pour un UpDownCounter, le delta le fait apparaître comme compteur ; si vous préférez une jauge (valeur courante), laissez-le en cumulative dans le sélecteur.

Étape 3 — Ou corriger dans le Collector

Quand vous ne contrôlez pas les applications (bibliothèques tierces, récepteur Prometheus), convertissez dans le Collector avec le processeur cumulative_to_delta :

processors:
  cumulative_to_delta: {}
  batch: {}

exporters:
  otlphttp/dynatrace:
    endpoint: https://abc12345.live.dynatrace.com/api/v2/otlp
    headers:
      Authorization: "Api-Token ${env:DT_API_TOKEN}"

service:
  pipelines:
    metrics:
      receivers: [otlp, prometheus]
      processors: [cumulative_to_delta, batch]
      exporters: [otlphttp/dynatrace]

Lignes critiques : cumulative_to_delta (nouveau nom de l’ancien cumulativetodelta, conservé comme alias déprécié) est avec état. Il garde la dernière valeur de chaque série en mémoire. Conséquences :

  • toutes les données d’une même série doivent passer par la même instance de Collector (pas de répartition aléatoire entre plusieurs instances) ;
  • après un redémarrage, le premier point d’une série déjà existante sert de référence et n’est pas exporté (comportement par défaut initial_value: auto) ;
  • la mémoire croît avec le nombre de séries : surveillez la cardinalité.

Placez le processeur avant batch, comme ci-dessus.

Comment vérifier que ça fonctionne

  1. Dans les logs de l’exporteur debug, la temporalité affiche désormais Delta. Retirez ensuite l’exporteur debug.
  2. Dans Dynatrace SaaS, ouvrez un Notebook et exécutez (remplacez par le nom de votre métrique) :
timeseries requetes = sum(http.server.request.count), interval: 1m
| fieldsAdd total = arraySum(requetes)

La courbe doit être plate pour un trafic constant (10 par minute dans notre exemple), pas une rampe qui monte sans fin. Une rampe signalerait un cumulatif interprété comme delta. Le nom de la métrique dans Dynatrace peut différer légèrement du nom OpenTelemetry : cherchez-le dans la liste des métriques. En Managed, utilisez l’explorateur de données avec la même vérification visuelle.

Dépannage

  • Toujours rien après le passage en delta : vérifiez le scope metrics.ingest du token et l’URL de l’endpoint (un 404 signale souvent un /v1/metrics en double ou manquant).
  • Pics isolés après chaque redémarrage : un processeur cumulative_to_delta placé derrière un équilibreur de charge reçoit les points d’une même série sur plusieurs instances. Routez par série ou corrigez dans le SDK.
  • Une partie seulement des métriques arrive : certains instruments restent cumulatifs, par exemple des histogrammes, qui sont alors rejetés (un UpDownCounter cumulatif arrive, lui, comme jauge). Comparez la sortie de l’exporteur debug instrument par instrument.
  • Valeurs doublées : la même métrique part à la fois du SDK en direct et via le Collector. Gardez un seul chemin d’export.

Bonnes pratiques

  • Corrigez au plus près de la source : le SDK en delta évite l’état du Collector.
  • Gardez la même temporalité pour toutes les applications d’une plateforme, documentée dans vos standards.
  • Pour les SLO de latence, envoyez des histogrammes en delta : voir les métriques histogrammes avec OpenPipeline.
  • Une métrique perdue en silence est un SLI aveugle : ajoutez une alerte sur l’absence de données des métriques critiques.

Questions fréquentes

Pourquoi Dynatrace préfère-t-il le delta ?

Le delta est sans état côté réception : chaque point se suffit à lui-même, quel que soit le nombre d’instances qui envoient. Il n’y a pas à suivre les redémarrages de chaque processus.

Mes métriques Prometheus sont cumulatives : que faire ?

Scrapez-les avec le récepteur Prometheus du Collector, puis appliquez cumulative_to_delta comme à l’étape 3.

Les jauges sont-elles concernées ?

Non. Une jauge représente une valeur instantanée (mémoire utilisée, longueur de file) et n’a pas de temporalité d’agrégation.

Conclusion

La temporalité métriques OTLP se règle en une ligne, mais son oubli fait disparaître des compteurs entiers. Vérifiez la temporalité avec l’exporteur debug, passez le SDK en delta ou convertissez dans le Collector, puis contrôlez la forme des courbes. Vos SLI reposent alors sur des chiffres complets.

span.observer est un blog indépendant de la communauté, non affilié à Dynatrace LLC. Dynatrace est une marque de Dynatrace LLC. Les fonctionnalités évoluent vite : vérifiez leur disponibilité dans votre environnement et dans la documentation officielle.

Total
0
Shares
Laisser un commentaire

Votre adresse e-mail ne sera pas publiée. Les champs obligatoires sont indiqués avec *

Previous Post
Agent OpenTelemetry Java : instrumenter une application et l'envoyer à Dynatrace

Agent OpenTelemetry Java : instrumenter une application et l’envoyer à Dynatrace

Next Post
Collector OpenTelemetry Kubernetes vers Dynatrace : Helm, Operator et k8sattributes

Collector OpenTelemetry Kubernetes vers Dynatrace : Helm, Operator et k8sattributes

Related Posts