1. Pourquoi utiliser l'API Dynatrace ?
L'API permet de transformer Dynatrace d'un outil de visualisation en un moteur d'automatisation.
Automatisation et Monitoring as Code
L'utilisation de l'API Dynatrace répond à trois besoins majeurs :
- L'Industrialisation : Configurer des centaines d'alertes ou de tableaux de bord via des outils comme Monaco ou Terraform.
- L'Intégration CI/CD : Intégrer Dynatrace dans vos pipelines (Jenkins, GitLab CI, Azure DevOps, etc.) pour automatiser des actions comme la pose de fenêtres de maintenance, l'ingestion d'événements de déploiement (Custom Deployment) afin que Davis AI puisse corréler les changements avec d'éventuelles régressions, ou la validation de SLOs.
- L'Extraction de données : Alimenter des outils tiers (PowerBI, Splunk) ou exécuter des requêtes analytiques complexes sur Grail.
2. Sécurité : La notion de Scopes
Comprendre comment restreindre les accès aux jetons d'API.
Le principe du moindre privilège
Un Scope définit les permissions accordées à un jeton d'API (API Token). Dynatrace v2 segmente les droits de manière granulaire :
- Read Scopes : Permettent de lire les données (ex:
entities.read,metrics.read,logs.read). - Write Scopes : Permettent de modifier la configuration (ex:
settings.write). - Ingest Scopes : Permettent d'envoyer de la donnée (ex:
events.ingest,logs.ingest).
Bonne pratique : Ne créez jamais de token 'admin'. Un token de déploiement CI/CD ne doit posséder que les scopes qu'il utilise réellement exemple pour les events: events.ingest.
3. Architecture : Où envoyer vos requêtes ?
Le choix du point d'entrée de l'API est stratégique pour optimiser la gestion de vos flux réseau, garantir la conformité aux politiques de sécurité de votre infrastructure, et s'adapte à votre déploiement Dynatrace (SaaS ou Managed).
Serveur Dynatrace (SaaS) ou Cluster Dynatrace (Managed) - Accès Direct
Pour les environnements SaaS, c'est l'URL publique par défaut (https://{env-id}.live.dynatrace.com/api/v2/ ou https://{env-id}.apps.dynatrace.com/api/v2/) pour les outils ayant un accès Internet direct. Pour les déploiements Managed, il s'agit de l'URL de votre cluster Dynatrace (https://{votre-cluster-managed}/e/{env-id}/api/v2/), qui est généralement une adresse **interne** à votre réseau. C'est le point d'entrée direct pour les requêtes API qui ne transitent pas par un ActiveGate.
Environment ActiveGate (SaaS ou Managed)
L'ActiveGate d'environnement agit comme une passerelle sécurisée (Gateway) pour les communications entre votre réseau interne et le cluster Dynatrace (qu'il soit SaaS ou Managed). Il est indispensable pour centraliser les flux de sortie (Single point of egress) de vos serveurs internes, permettant de limiter drastiquement les ouvertures de pare-feu vers Internet en utilisant une IP pivot unique. L'API est alors accessible sur le port 9999 de l'ActiveGate.
Cluster ActiveGate (Managed)
Dans le cas d'une installation Dynatrace Managed (On-premise), le Cluster ActiveGate assure le routage intelligent des requêtes API vers les différents environnements (tenants) gérés par le cluster, tout en maintenant les données au sein de votre réseau privé. Il est le point d'entrée principal et **exclusivement interne** pour les interactions API avec un déploiement Managed.
Tableau récapitulatif des URLs d'API
Comprendre comment construire l'URL de base de vos requêtes API selon votre type de déploiement et le service ciblé.
Construction des URLs
| Type de déploiement | Point d'accès | Format d'URL | Exemple (SaaS) | Exemple (Managed) |
|---|---|---|---|---|
| SaaS | Direct (API Environnement) | https://{env-id}.live.dynatrace.com/api/v2/... | https://abc12345.live.dynatrace.com/api/v2/entities | N/A |
| SaaS | Direct (API Plateforme / Grail) | https://{env-id}.apps.dynatrace.com/api/v2/... | https://abc12345.apps.dynatrace.com/api/v2/dql/query | N/A |
| SaaS ou Managed | Environment ActiveGate | https://{ActiveGate-IP}:9999/e/{env-id}/api/v2/... | https://10.0.0.10:9999/e/abc12345/api/v2/metrics | https://10.0.0.10:9999/e/def67890/api/v2/metrics |
| Managed | Cluster Dynatrace | https://{votre-cluster-managed}/e/{env-id}/api/v2/... | N/A | https://moncluster.local/e/def67890/api/v2/problems |
Note : {env-id} est l'identifiant de votre environnement Dynatrace. {ActiveGate-IP} est l'adresse IP ou le nom d'hôte de votre ActiveGate. {votre-cluster-managed} est l'URL de base de votre déploiement Dynatrace Managed.
4. SaaS : apps.dynatrace.com vs live.dynatrace.com
Sur Dynatrace SaaS, le domaine change selon que vous ciblez les APIs d'environnement classiques ou les nouveaux services de la plateforme.La différence entre ces deux domaines correspond à l'évolution majeure de l'architecture de Dynatrace ces dernières années. Elle sépare l'environnement classique (Gen2) de la nouvelle plateforme moderne basée sur le lac de données Grail et la nouvelle expérience utilisateur (Gen3). Voici les détails pour bien comprendre la distinction :
live.dynatrace.com (L'architecture Classique / Gen2)
Ce domaine est associé aux environnements Dynatrace SaaS standards. C'est l'URL historique utilisée pour accéder à la console et interagir avec les APIs classiques de la plateforme.
- Stockage sous-jacent : Utilise l'ancienne architecture de stockage (Elasticsearch/Cassandra pour les métriques, traces et logs classiques).
- APIs : Héberge les APIs standard v1 et v2 (comme
/api/v2/events/ingest,/api/v2/metrics, etc.). - Interface : Donne accès aux tableaux de bord classiques et aux écrans de diagnostic traditionnels.
Format d'URL : https://{env-id}.live.dynatrace.com/api/v2/...
apps.dynatrace.com (La nouvelle plateforme / Gen3 & Grail)
Ce domaine représente le Dynatrace moderne. Il centralise les nouvelles applications de la plateforme, l'expérience utilisateur de nouvelle génération et l'exécution des workflows automatisés.
- Stockage sous-jacent : Entièrement propulsé par Grail, le lac de données massif, sans index, qui centralise les logs, métriques, traces et événements de manière unifiée.
- Fonctionnalités clés : C'est ici que tournent les nouvelles fonctionnalités comme Dashboards Apps, Notebooks, Workflows (automatisation) et le langage de requêtage DQL (Dynatrace Query Language).
- APIs : Héberge les points de terminaison spécifiques aux applications, à l'AppEngine et aux requêtes Grail.
Format d'URL : https://{env-id}.apps.dynatrace.com/api/v2/...
En résumé : Qui fait quoi ?
| Caractéristique | live.dynatrace.com | apps.dynatrace.com |
|---|---|---|
| Génération | Dynatrace Gen2 (Classique) | Dynatrace Gen3 (Moderne) |
| Moteur de données | Stockage classique (Indexé) | Grail (Data Lakehouse) |
| Langage de requêtage | USQL / Sélecteurs standards | DQL (Dynatrace Query Language) |
| Usage principal | Ingestion classique, APIs de configuration, monitoring Legacy | Visualisation avancée, Notebooks, Automatisation, Log Management moderne |
5. Exemples Pratiques
Exemples basés sur l'environnement https://demo.dynatrace.rousseltm.fr. Pour explorer et tester ces APIs, Dynatrace propose une interface Swagger UI (OpenAPI). Elle permet de parcourir la documentation technique et d'exécuter des requêtes directement depuis le navigateur.Accès au Swagger :
- SaaS :
https://{env-id}.apps.dynatrace.com/platform/swagger-ui/index.html - Managed :
https://{votre-cluster-managed}/e/{env-id}/swagger-ui/index.html
1. Ingestion d'un événement de déploiement
Permet à Davis AI de savoir qu'un changement a eu lieu. Cet exemple montre l'utilisation de variables shell pour définir les timestamps de début et de fin.
START_TIME=$(date +%s%3N)
END_TIME=$(($(date +%s) + 63))000
curl -X POST "https://{env-id}.live.dynatrace.com/api/v2/events/ingest" \
-H "Authorization: Api-Token {TOKEN}" \
-H "Content-Type: application/json" \
-d '{
"eventType": "CUSTOM_DEPLOYMENT",
"title": "Deploy v1.2.0 - E-learning Platform",
"entitySelector": "type(SERVICE),entityName(AuthenticationService)",
"startTime": '"$START_TIME"',
"endTime": '"$END_TIME"',
"properties": {
"git.commit": "a1b2c3d",
"ci.user": "martin.roussel",
"release.url": "https://gitlab.rousseltm.fr/test/repo/-/releases/v1.2.0",
"build.version": "1.2.0.45",
"stage": "production",
"product": "E-learning Platform"
}
}'2. Création d'une fenêtre de maintenance
Désactivez les alertes pendant une mise à jour via l'API Settings.
curl -X POST "https://demo.dynatrace.rousseltm.fr/api/v2/settings/objects" \
-H "Authorization: Api-Token {TOKEN}" \
-d '[{
"schemaId": "builtin:maintenance-window",
"value": {
"enabled": true,
"generalProperties": { "name": "Patching OS", "type": "PLANNED" },
"schedule": { "type": "ONCE", "start": "2024-12-01T01:00:00", "end": "2024-12-01T02:00:00" }
}
}]'3. Exécution d'une requête DQL (Grail)
Récupérez des logs bruts directement depuis Grail.
curl -X POST "https://demo.dynatrace.rousseltm.fr/api/v2/dql/query" \
-H "Authorization: Api-Token {TOKEN}" \
-d '{ "query": "fetch logs | filter matchesValue(log.level, \"ERROR\")", "defaultTimeframeStart": "now-15m" }'4. Récupération des Distributed Traces (PurePaths)
Récupérez le détail technique d'une trace via son ID.
curl -G "https://demo.dynatrace.rousseltm.fr/api/v2/distributedTracing/traces/{traceId}" \
-H "Authorization: Api-Token {TOKEN}"5. Liste des entités (Entity Selector)
Listez tous les hôtes Linux en production.
curl -G "https://demo.dynatrace.rousseltm.fr/api/v2/entities" \
--data-urlencode "entitySelector=type(HOST),osType(LINUX),tag(env:prod)" \
-H "Authorization: Api-Token {TOKEN}"6. Extraction de métriques
Récupérez l'utilisation CPU moyenne d'un service.
curl -G "https://demo.dynatrace.rousseltm.fr/api/v2/metrics/query" \
--data-urlencode "metricSelector=builtin:host.cpu.usage:avg" \
-H "Authorization: Api-Token {TOKEN}"7. Liste des problèmes actifs
Récupérez les incidents détectés par Davis AI.
curl -G "https://demo.dynatrace.rousseltm.fr/api/v2/problems" \
-H "Authorization: Api-Token {TOKEN}"8. Configuration du Synthetic Monitoring
Récupérez la configuration JSON d'un moniteur HTTP.
curl -G "https://demo.dynatrace.rousseltm.fr/api/v2/synthetic/monitors/{id}" \
-H "Authorization: Api-Token {TOKEN}"9. Audit Logs
Vérifiez qui a modifié la configuration de l'environnement.
curl -G "https://demo.dynatrace.rousseltm.fr/api/v2/auditlogs" \
-H "Authorization: Api-Token {TOKEN}"10. Ingestion de métriques OpenTelemetry
Envoyez des métriques personnalisées via le endpoint OTLP.
curl -X POST "https://demo.dynatrace.rousseltm.fr/api/v2/otlp/v1/metrics" \
-H "Authorization: Api-Token {TOKEN}" \
-H "Content-Type: application/x-protobuf" \
--data-binary @metrics.pb6. Multidimensional Analysis vs Waterfall
Deux types d'analyses, deux approches API différentes.
Multidimensional Analysis (Vue d'ensemble)
L'API Metrics est utilisée pour l'analyse multidimensionnelle. Elle permet d'agréger des données sur des milliers de requêtes (ex: latence moyenne par pays). C'est l'outil idéal pour le dashboarding.
Waterfall Analysis (Vue granulaire)
L'analyse Waterfall est accessible via l'API Sessions. Elle renvoie le détail milliseconde par milliseconde du chargement d'une page unique (DOM, images, scripts). Elle est utilisée pour le debugging profond d'une transaction spécifique.