Traces OpenTelemetry absentes de Dynatrace : checklist de dépannage OTLP en 8 étapes

Traces OpenTelemetry absentes de Dynatrace ? Suivez 8 vérifications OTLP : URL, token, protocole, réseau, Collector, sampling, en SaaS et Managed.
Traces OpenTelemetry absentes de Dynatrace : checklist de dépannage OTLP en 8 étapes

Vous avez instrumenté un service, le Collector tourne, et pourtant les traces OpenTelemetry absentes de Dynatrace laissent l’écran Distributed Tracing vide. Pendant ce temps, l’incident en cours n’a pas de contexte, le MTTR grimpe et l’équipe doute de toute la chaîne de télémétrie.

Objectif de ce tutoriel : suivre une checklist de dépannage OTLP en 8 étapes, de l’application jusqu’à Grail, et isoler en moins de 30 minutes le maillon qui perd les spans. Le contenu vaut pour Dynatrace SaaS et Dynatrace Managed ; les différences d’URL sont indiquées à chaque fois.

Si vous n’avez pas encore de Collector, commencez par installer et configurer le Collector OpenTelemetry pour Dynatrace, puis revenez ici.

Le principe : remonter la chaîne maillon par maillon

Une trace parcourt quatre maillons : le SDK dans l’application, l’export OTLP, le Collector (s’il existe), puis l’endpoint OTLP de Dynatrace. Chaque étape ci-dessous teste un seul maillon. Ne sautez pas d’étape : la cause la plus fréquente est souvent la plus banale (mauvais chemin d’URL, token sans le bon scope).

Prérequis

  • Un accès en lecture aux logs de l’application et du Collector.
  • Un token d’API Dynatrace avec le scope openTelemetryTrace.ingest (Ingest OpenTelemetry traces).
  • curl sur une machine du même réseau que l’application.
  • SaaS : accès à Notebooks ou à l’application Distributed Tracing. Managed : accès à l’écran Distributed traces de l’environnement.

Traces OpenTelemetry absentes : la checklist en 8 étapes

Étape 1 — Vérifier que le SDK produit des spans

Activez un exporter console à côté de l’exporter OTLP. Avec l’auto-instrumentation (Java, Python, Node.js), les variables d’environnement standard suffisent :

export OTEL_SERVICE_NAME=checkout
export OTEL_TRACES_EXPORTER=otlp,console
export OTEL_TRACES_SAMPLER=always_on

Si aucun span n’apparaît sur la sortie standard, le problème est dans l’application : agent non chargé, bibliothèque non instrumentée ou sampler à always_off. Le support de la valeur console dépend du langage : vérifiez la documentation de votre SDK.

Étape 2 — Vérifier le protocole et le port

L’endpoint OTLP de Dynatrace accepte OTLP sur HTTP (protobuf). Un SDK réglé sur gRPC (port 4317) vers Dynatrace en direct n’aboutira pas. Fixez le protocole explicitement :

export OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf

Si l’application envoie vers un Collector local, gRPC sur 4317 ou HTTP sur 4318 fonctionnent tous deux, à condition que le receiver correspondant soit activé dans le Collector.

Étape 3 — Vérifier l’URL exacte

C’est la cause numéro un. La variable générique OTEL_EXPORTER_OTLP_ENDPOINT reçoit la base, et le SDK ajoute /v1/traces. La variable spécifique OTEL_EXPORTER_OTLP_TRACES_ENDPOINT reçoit l’URL complète.

# SaaS
export OTEL_EXPORTER_OTLP_ENDPOINT=https://<env-id>.live.dynatrace.com/api/v2/otlp
# Managed
export OTEL_EXPORTER_OTLP_ENDPOINT=https://<votre-domaine>/e/<env-id>/api/v2/otlp
# ActiveGate d'environnement
export OTEL_EXPORTER_OTLP_ENDPOINT=https://<activegate>:9999/e/<env-id>/api/v2/otlp

Erreur classique : mettre /api/v2/otlp/v1/traces dans la variable générique, ce qui donne /v1/traces/v1/traces et une réponse 404. Vérifiez le format exact dans la documentation OTLP API de Dynatrace.

Étape 4 — Vérifier le token et son en-tête

export OTEL_EXPORTER_OTLP_HEADERS="Authorization=Api-Token%20dt0c01.XXXX"

Le préfixe Api-Token suivi d’un espace est obligatoire ; dans cette variable, l’espace s’écrit %20. Un 401 signale un token invalide ou mal formé, un 403 un scope manquant. Testez l’endpoint à la main pour trancher :

curl -s -o /dev/null -w "%{http_code}\n" -X POST \
  "https://<env-id>.live.dynatrace.com/api/v2/otlp/v1/traces" \
  -H "Authorization: Api-Token $DT_TOKEN" \
  -H "Content-Type: application/x-protobuf" \
  --data-binary @/dev/null

Un corps vide n’est pas une trace valide : retenez surtout la différence entre 401/403 (authentification), 404 (chemin) et une réponse 2xx ou 400 (l’endpoint est joignable et le token accepté). Le code exact pour un corps vide peut varier.

Étape 5 — Vérifier le réseau et le TLS

Depuis le pod ou l’hôte de l’application (pas depuis votre poste) :

curl -v https://<env-id>.live.dynatrace.com/api/v2/otlp/v1/traces 2>&1 | grep -E "Connected|SSL|HTTP/"

Un timeout désigne un pare-feu, un proxy sortant non configuré ou une NetworkPolicy Kubernetes. Une erreur de certificat en Managed signale souvent une autorité interne que le runtime de l’application ne connaît pas ; ajoutez-la au magasin de confiance du runtime.

Étape 6 — Lire les logs et les métriques du Collector

Si un Collector est dans la chaîne, ajoutez temporairement l’exporter debug au pipeline de traces :

exporters:
  debug:
    verbosity: detailed
  otlphttp:
    endpoint: https://<env-id>.live.dynatrace.com/api/v2/otlp
    headers:
      Authorization: "Api-Token ${env:DT_API_TOKEN}"
service:
  pipelines:
    traces:
      receivers: [otlp]
      processors: [batch]
      exporters: [otlphttp, debug]

Si les spans s’affichent dans le log debug mais pas dans Dynatrace, le problème est en sortie (étapes 3 à 5). S’ils n’apparaissent pas, le receiver ne reçoit rien (étapes 1 et 2). Les métriques internes du Collector, exposées par défaut sur le port 8888, confirment le diagnostic : comparez otelcol_receiver_accepted_spans, otelcol_exporter_sent_spans et otelcol_exporter_send_failed_spans (un suffixe _total peut s’ajouter selon la version).

Étape 7 — Vérifier l’échantillonnage et les filtres

Un processor filter ou tail_sampling trop strict peut écarter toutes les traces d’un service peu chargé. Un sampler parentbased_traceidratio à 0.01 sur un service de test à 10 requêtes par heure ne produit presque rien. Repassez temporairement à always_on et retirez les filtres pour confirmer.

Étape 8 — Chercher les spans au bon endroit dans Dynatrace

Les spans arrivent parfois, mais sous un autre nom de service, sur une autre période ou hors de votre zone de gestion. En SaaS, interrogez Grail directement :

fetch spans, from: now() - 30m
| filter contains(service.name, "checkout")
| summarize spans = count(), by: { service.name, k8s.namespace.name }

En Managed, ouvrez Distributed traces, filtrez sur la période récente et retirez la zone de gestion. Un horodatage faux (horloge du conteneur décalée) place aussi les spans hors de la fenêtre affichée : comparez l’heure du serveur avec un serveur NTP.

Comment vérifier que ça fonctionne

  1. Les logs du Collector ne montrent plus d’erreur d’export, et otelcol_exporter_send_failed_spans reste stable.
  2. La requête DQL de l’étape 8 renvoie un nombre de spans non nul pour votre service.
  3. Une trace de bout en bout s’ouvre et montre les spans de chaque service, avec un parent commun.

Pour aller plus loin sur la propagation entre services, lisez OpenTelemetry de bout en bout avec Dynatrace.

Bonnes pratiques

  • Gardez un pipeline de test minimal (receiver OTLP, batch, export) et documentez-le dans le runbook d’astreinte.
  • Supervisez le Collector lui-même : une alerte sur les échecs d’export évite de découvrir la panne pendant un incident.
  • Stockez le token dans un secret, jamais en clair dans un manifeste ou un dépôt.
  • Évitez la double instrumentation : si OneAgent instrumente déjà le processus, vérifiez dans la documentation comment il cohabite avec un SDK OpenTelemetry.
  • Une fois les traces revenues, transformez-les en indicateurs : voir créer un SLO sur des données OpenTelemetry.

Questions fréquentes

Dynatrace accepte-t-il OTLP en gRPC ?

L’endpoint OTLP de l’API Dynatrace est documenté pour OTLP sur HTTP. Pour envoyer du gRPC, placez un Collector qui reçoit en gRPC et exporte en HTTP vers Dynatrace.

Les métriques arrivent mais pas les traces : pourquoi ?

Chaque signal a son chemin (/v1/traces, /v1/metrics, /v1/logs) et son scope de token. Vérifiez que le token porte aussi openTelemetryTrace.ingest et que le pipeline traces existe dans le Collector.

Combien de temps attendre avant de voir les spans ?

En général quelques secondes à une minute, selon le processor batch et l’ingestion. Au-delà de quelques minutes, reprenez la checklist plutôt que d’attendre.

Conclusion

Huit vérifications suffisent presque toujours : production, protocole, URL, token, réseau, Collector, échantillonnage, recherche. Gardez cette checklist dans votre runbook : le prochain incident de télémétrie se réglera en minutes, pas en heures.

span.observer est un blog indépendant de la communauté, non affilié à Dynatrace LLC. Dynatrace est une marque de Dynatrace LLC. Les fonctionnalités SaaS é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
Alertes burn rate SLO dans Dynatrace : le tutoriel multi-fenêtres (SaaS et Managed)

Alertes burn rate SLO dans Dynatrace : le tutoriel multi-fenêtres (SaaS et Managed)

Next Post
SLO OpenTelemetry dans Dynatrace : disponibilité et latence en DQL

SLO OpenTelemetry dans Dynatrace : disponibilité et latence en DQL

Related Posts