Token API Dynatrace : dépanner les scopes et les erreurs 401 et 403 (OTLP, API v2)

Token API Dynatrace refusé ? Diagnostiquez 401, 403 et 404 en OTLP et API v2 : format d’en-tête, scopes, expiration et correction du Collector.
Token API Dynatrace : dépanner les scopes et les erreurs 401 et 403 (OTLP, API v2)

Votre Collector OpenTelemetry tourne, mais rien n’arrive dans Dynatrace. Dans ses logs, une seule ligne revient : 401 Unauthorized ou 403 Forbidden. Neuf fois sur dix, le coupable est le token API Dynatrace : mauvais format d’en-tête, scope manquant, token expiré ou envoyé au mauvais environnement.

Ce dépannage coûte cher en astreinte : pendant que l’on cherche, les traces, les métriques et les logs sont perdus, et les SLO calculés dessus deviennent faux. Un diagnostic méthodique ramène ce temps à quelques minutes et réduit le MTTR des incidents d’ingestion.

Objectif de ce tutoriel : identifier en moins de dix minutes pourquoi une requête est refusée, que ce soit pour l’ingestion OTLP ou pour l’API v2. Le contenu vaut pour Dynatrace SaaS et Dynatrace Managed ; les différences d’URL et de jetons sont signalées à chaque étape.

401 ou 403 : ce que dit vraiment le code

Les deux codes ne racontent pas la même histoire. Les distinguer évite de tourner en rond.

Code Signification Causes fréquentes
401 L’appelant n’est pas authentifié En-tête absent ou mal formé, token révoqué, expiré, mal copié, ou appartenant à un autre environnement
403 L’appelant est authentifié mais n’a pas le droit Scope manquant sur le token, token désactivé selon les cas, restriction côté environnement
404 L’URL ne correspond à rien Mauvais identifiant d’environnement, chemin /e/<env-id> oublié en Managed

Retenez la règle : un 401 se règle sur le token ou l’en-tête, un 403 se règle sur les scopes. Le contenu exact du message d’erreur renvoyé dans le corps de la réponse aide souvent à trancher : lisez-le toujours.

Prérequis

  • Un environnement Dynatrace SaaS ou Managed, et le droit de gérer les tokens (permission d’environnement adéquate).
  • curl et jq sur un poste qui atteint l’environnement (ou l’ActiveGate).
  • Le token à tester dans une variable d’environnement, jamais en clair dans un fichier versionné.
  • Un second token d’accès valide, pour l’étape de vérification : l’appel de lookup accepte un token classique de n’importe quel scope (ou un token de plateforme avec api-tokens:tokens:read).

Dépanner un token API Dynatrace pas à pas

Étape 1 : vérifier l’URL de l’environnement

Avant d’accuser le token, vérifiez l’adresse. Les formats diffèrent selon le déploiement :

# Dynatrace SaaS
export DT_URL="https://<env-id>.live.dynatrace.com"

# Dynatrace Managed (cluster)
export DT_URL="https://<votre-domaine>/e/<env-id>"

# Via un Environment ActiveGate (SaaS ou Managed)
export DT_URL="https://<activegate>:9999/e/<env-id>"

export DT_API_TOKEN="dt0c01.XXXX.YYYY"

Un token créé dans l’environnement A ne fonctionne pas dans l’environnement B. En Managed multi-environnements, c’est la première cause de 401 que nous rencontrons.

Étape 2 : contrôler le format de l’en-tête

L’API d’environnement attend le schéma Api-Token, pas Bearer :

curl -s -o /dev/null -w "%{http_code}\n" \
  -H "Authorization: Api-Token ${DT_API_TOKEN}" \
  "${DT_URL}/api/v2/metrics?pageSize=1"

Lignes critiques : le mot Api-Token suivi d’un espace, puis le token complet. Un token classique commence par dt0c01. et contient deux points de séparation. Si la chaîne est tronquée (copie depuis un terminal étroit, retour à la ligne dans un secret Kubernetes), vous obtenez un 401.

En SaaS, les tokens de plateforme et les clients OAuth utilisés par les applications et l’API de la plateforme s’envoient avec Bearer. L’API OTLP accepte les deux familles, chacune avec son schéma et ses scopes (openpipeline:traces:ingest etc. pour un token de plateforme). Ne les mélangez pas : un token de plateforme envoyé avec Api-Token sera refusé. Vérifiez quel type de jeton chaque API attend sur la page d’authentification de la documentation.

Étape 3 : lire les scopes réels du token

L’API v2 permet de consulter les métadonnées d’un token sans l’afficher dans l’interface. L’appel se fait avec le second token, et le token à inspecter part dans le corps :

curl -s -X POST "${DT_URL}/api/v2/apiTokens/lookup" \
  -H "Authorization: Api-Token ${DT_ADMIN_TOKEN}" \
  -H "Content-Type: application/json" \
  -d "{\"token\": \"${DT_API_TOKEN}\"}" | jq '{name, enabled, expirationDate, scopes}'

La réponse indique si le token est actif, sa date d’expiration et la liste de ses scopes. Trois cas fréquents :

  • enabled: false : quelqu’un l’a désactivé, souvent après une alerte de fuite de secret ;
  • expirationDate dépassée : le token a expiré, il faut en créer un nouveau ;
  • scope attendu absent : c’est l’explication de votre 403.

Étape 4 : faire correspondre scope et appel

Chaque point d’accès exige un scope précis. Voici les correspondances les plus courantes ; vérifiez le nom exact dans l’écran de création du token, qui affiche à la fois le libellé et l’identifiant technique :

Usage Point d’accès Scope
Traces OTLP /api/v2/otlp/v1/traces openTelemetryTrace.ingest
Métriques OTLP /api/v2/otlp/v1/metrics metrics.ingest
Logs OTLP /api/v2/otlp/v1/logs logs.ingest
Lecture des entités /api/v2/entities entities.read
Lecture des problèmes /api/v2/problems problems.read
Objets de configuration /api/v2/settings/objects settings.read / settings.write

Piège classique : un Collector qui envoie traces, métriques et logs avec un seul token ne possédant que openTelemetryTrace.ingest. Les traces passent, les deux autres pipelines renvoient 403. Le Collector exporte alors une partie de la télémétrie seulement, ce qui est plus difficile à repérer qu’une panne totale.

Étape 5 : corriger la configuration du Collector

Une configuration d’exporteur propre, avec le token injecté par variable d’environnement :

exporters:
  otlphttp/dynatrace:
    endpoint: "${env:DT_URL}/api/v2/otlp"
    headers:
      Authorization: "Api-Token ${env:DT_API_TOKEN}"

service:
  pipelines:
    traces:
      receivers: [otlp]
      processors: [batch]
      exporters: [otlphttp/dynatrace]
    metrics:
      receivers: [otlp]
      processors: [cumulativetodelta, batch]
      exporters: [otlphttp/dynatrace]
    logs:
      receivers: [otlp]
      processors: [batch]
      exporters: [otlphttp/dynatrace]

Lignes critiques : endpoint s’arrête à /api/v2/otlp (l’exporteur ajoute /v1/traces, /v1/metrics et /v1/logs) ; l’en-tête reprend le schéma Api-Token. Pour le détail du Collector, voir le guide d’installation du Collector OpenTelemetry pour Dynatrace.

En Kubernetes, créez le secret sans retour à la ligne parasite :

kubectl create secret generic dynatrace-otlp \
  --from-literal=DT_API_TOKEN="${DT_API_TOKEN}" \
  -n observability

Évitez echo "$TOKEN" | base64 dans un manifeste : echo ajoute un saut de ligne final, encodé avec le reste, et le token reçu devient invalide.

Comment vérifier que ça fonctionne

  1. Rejouez l’appel de l’étape 2 : le code attendu est 200.
  2. Envoyez une trace de test minimale sur le point d’accès OTLP ; l’API OTLP de Dynatrace n’accepte que le protobuf binaire (pas le JSON) ; un corps protobuf vide suffit pour tester l’authentification :
    curl -s -o /dev/null -w "%{http_code}\n" -X POST \
      -H "Authorization: Api-Token ${DT_API_TOKEN}" \
      -H "Content-Type: application/x-protobuf" \
      --data-binary "" \
      "${DT_URL}/api/v2/otlp/v1/traces"

    Un code de la famille 2xx confirme l’authentification et le scope ; un 401 ou un 403 renvoie aux étapes 2 à 4.

  3. Dans les logs du Collector, les erreurs d’export doivent disparaître : kubectl logs deploy/otel-collector -n observability | grep -iE "401|403" ne renvoie plus rien.
  4. En SaaS, une requête DQL confirme l’arrivée des données : fetch spans, from:now()-15m | summarize count(), by:{service.name}. En Managed, ouvrez la vue des services ou des traces distribuées et cherchez le service émetteur.

Si les données manquent alors que l’authentification passe, le problème est ailleurs : consultez traces OpenTelemetry absentes dans Dynatrace.

Bonnes pratiques

  • Un token par usage : un token d’ingestion pour le Collector, un autre pour l’automatisation. Une fuite n’expose alors qu’un périmètre réduit.
  • Le moindre privilège : n’ajoutez que les scopes nécessaires. Un token d’ingestion n’a aucune raison de pouvoir écrire des réglages.
  • Une date d’expiration et une rotation planifiée, avec une alerte avant l’échéance plutôt qu’une panne le jour J.
  • Un nom explicite : équipe, usage et date dans le nom du token. Le lookup devient immédiatement lisible.
  • Superviser l’ingestion : une alerte sur la chute du volume reçu repère un token expiré avant les utilisateurs. Voir superviser le Collector OpenTelemetry.
  • En Managed, gardez à l’esprit la séparation entre tokens d’environnement et tokens de l’API Cluster, détaillée dans l’automatisation avec l’API Cluster.

Questions fréquentes

Puis-je ajouter un scope à un token existant ?

Selon la version, l’interface permet de modifier certains tokens, mais la valeur secrète ne se réaffiche jamais. La pratique la plus sûre reste de créer un nouveau token avec les bons scopes, de le déployer, puis de révoquer l’ancien.

Pourquoi j’obtiens 401 avec un token qui fonctionne dans curl ?

Comparez la chaîne réellement reçue par l’application : guillemets en trop dans un fichier YAML, saut de ligne final dans un secret, variable d’environnement non résolue (le Collector envoie alors littéralement ${env:DT_API_TOKEN}). Activez temporairement les logs de debug du client pour vérifier l’en-tête, sans jamais les conserver en production.

Un token Managed fonctionne-t-il après une migration vers SaaS ?

Non. Les tokens sont liés à leur environnement. Après une migration, recréez les tokens dans l’environnement SaaS et mettez à jour chaque client qui les utilise.

Conclusion

Un 401 se résout côté token ou en-tête, un 403 côté scopes, un 404 côté URL. Avec l’appel de test et le lookup du token, le diagnostic tient en quelques commandes. Ajoutez une rotation planifiée et une alerte sur le volume ingéré : la prochaine expiration ne sera plus un incident.

span.observer est un blog indépendant de la communauté, non affilié à Dynatrace LLC. Dynatrace est une marque de son propriétaire. Les noms de scopes et d’écrans évoluent : vérifiez-les dans la documentation officielle de votre version.

Total
0
Shares
Laisser un commentaire

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

Previous Post
Réduire bruit, alertes et fatigue d'astreinte : régler Davis et les profils d'alerte

Réduire bruit, alertes et fatigue d’astreinte : régler Davis et les profils d’alerte

Next Post
Requêtes DQL exemples : 15 requêtes prêtes à copier avec DQL summarize, filter et timeseries

Requêtes DQL exemples : 15 requêtes prêtes à copier avec DQL summarize, filter et timeseries

Related Posts