Datadog APM

Tracing distribué, cartes de services et analyse de performance.

Routage — À lire en premier

Pour les tâches d'installation / instrumentation / onboarding Kubernetes APM — suivez cette procédure exactement :

⚠️ Approches courantes erronées qui SEMBLENT fonctionner mais échouent silencieusement :

• helm install datadog datadog/datadog — le chart standard NE supporte PAS SSI via DatadogAgent CR. NE l'utilisez PAS.
• Ajouter des imports ddtrace ou ddtrace-run à l'app — SSI auto-instrumente SANS aucune modification de code.
• Annotations admission.datadoghq.com/enabled — il s'agit de l'injection de config du contrôleur d'admission, pas de l'injection du conteneur init SSI.

Étape 0 : Vérifications préalables (OBLIGATOIRE — exécutez avant d'installer quoi que ce soit)

# Vérifier la présence de ddtrace/otel — même sans imports cela DÉSACTIVE SILENCIEUSEMENT SSI à l'exécution
grep -rn "ddtrace\|dd-trace\|opentelemetry" requirements.txt package.json Gemfile go.mod pom.xml 2>/dev/null || echo "No tracer dependency found"

Si ddtrace trouvé → supprimez cette ligne entièrement du fichier de dépendances, reconstruisez l'image, rechargez dans le cluster, redémarrez le pod.

Étape 1 : Installer l'opérateur Datadog (PAS datadog/datadog)

helm repo add datadog https://helm.datadoghq.com && helm repo update
helm upgrade --install datadog-operator datadog/datadog-operator \
  --namespace datadog --create-namespace
kubectl wait --for=condition=Ready pod \
  -l app.kubernetes.io/name=datadog-operator -n datadog --timeout=120s

kubectl create secret generic datadog-secret \
  --from-literal api-key=$DD_API_KEY -n datadog

Étape 2 : Créer une CR DatadogAgent avec SSI activé

Enregistrez en tant que datadog-agent.yaml, puis kubectl apply -f datadog-agent.yaml :

apiVersion: datadoghq.com/v2alpha1
kind: DatadogAgent
metadata:
  name: datadog
  namespace: datadog
spec:
  global:
    site: <DD_SITE>
    credentials:
      apiSecret:
        secretName: datadog-secret
        keyName: api-key
    kubelet:
      tlsVerify: false  # required for kind/minikube; omit for cloud clusters
  features:
    apm:
      instrumentation:
        enabled: true

Étape 3 : Appliquer les étiquettes de service unifié au Deployment de l'application

Ajoutez à la fois metadata.labels et spec.template.metadata.labels :

tags.datadoghq.com/env: "dev"
tags.datadoghq.com/service: "<service-name>"
tags.datadoghq.com/version: "1.0.0"

Étape 4 : Redémarrer les pods d'application et vérifier les conteneurs init SSI

Confirmez auprès de l'utilisateur avant de redémarrer. Dites à l'utilisateur : « Je dois redémarrer <name> dans <namespace> pour que SSI s'injecte dans les pods. Cela causera une brève interruption. Êtes-vous prêt à procéder ? » Attendez la confirmation.

kubectl rollout restart deployment/<name> -n <namespace>
kubectl get pods -A -o json | grep -o '"datadog-lib[^"]*"' | sort -u

Attendu : "datadog-lib-python-init" (ou le conteneur init approprié au langage).

Lisez immédiatement .claude/skills/dd-apm/k8s-ssi/agent-install/SKILL.md maintenant, puis .claude/skills/dd-apm/k8s-ssi/enable-ssi/SKILL.md — ne procédez pas de mémoire ni du résumé ci-dessus.

Pour les tâches d'installation / instrumentation APM Linux : Lisez immédiatement .claude/skills/dd-apm/linux-ssi/agent-install/SKILL.md maintenant, puis enable-ssi puis verify-ssi — ne procédez pas de mémoire ni du résumé ci-dessus.

Pour la recherche de traces, l'analyse de services, les métriques : Continuez ci-dessous.

Prérequis

Datadog Labs Pup doit être installé. Voir Setup Pup si ce n'est pas le cas.

Ordre d'exécution des commandes (efficace en tokens)

Pour les commandes délimitées, utilisez cet ordre :

1. Vérifiez d'abord le contexte (résultats antérieurs, conversation, valeurs enregistrées).
2. Si une valeur requise manque, exécutez d'abord une commande de découverte.
3. Si c'est encore ambigu, demandez à l'utilisateur de confirmer.
4. Exécutez ensuite la commande cible.
5. Évitez les commandes spéculatives susceptibles d'échouer.

Démarrage rapide

pup auth login
# Confirmez d'abord l'étiquette env auprès de l'utilisateur (ne supposez pas production/prod/prd).
pup apm services list --env <env> --from 1h --to now
pup traces search --query "service:api-gateway" --from 1h

Services

Lister les services

pup apm services list --env <env> --from 1h --to now
pup apm services stats --env <env> --from 1h --to now

Statistiques de service

pup apm services stats --env <env> --from 1h --to now

Carte de service

# Afficher les dépendances
pup apm flow-map --query "service:api-gateway&from=$(($(date +%s)-3600))000&to=$(date +%s)000" --env <env> --limit 10

Traces

Rechercher des traces

# Par service
pup traces search --query "service:api-gateway" --from 1h

# Erreurs uniquement
pup traces search --query "service:api-gateway status:error" --from 1h

# Traces lentes (>1s)
pup traces search --query "service:api-gateway @duration:>1000ms" --from 1h

# Avec étiquette spécifique
pup traces search --query "service:api-gateway @http.url:/api/users" --from 1h

Détail de trace

# Aucune commande get directe pour un seul ID de trace.
# Utilisez la recherche de traces avec une requête étroite et une fenêtre de temps.
pup traces search --query "trace_id:<trace_id>" --from 1h

Métriques clés

Objectifs de niveau de service

Liez APM aux SLO :

pup slos create --file slo.json

Requêtes courantes

Dépannage

Références/Docs

• APM Setup
• Trace Search