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).
curletjqsur 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 ;expirationDatedé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
- Rejouez l’appel de l’étape 2 : le code attendu est
200. - 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.
- 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. - 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.