Dépanner APM SSI sur Linux

Déclencheurs

Invoquez cette compétence quand l'utilisateur exprime l'intention de :

• Déboguer pourquoi un processus Linux n'est pas instrumenté
• Enquêter pourquoi les traces n'apparaissent pas dans Datadog depuis un hôte Linux
• Diagnostiquer les échecs d'injection SSI sur Linux
• Faire un suivi sur les vérifications échouées de verify-ssi
• Signaler qu'un service ou un hôte spécifique n'a pas de traces

N'invoquez PAS cette compétence si :

• SSI n'a pas encore été activé — exécutez d'abord enable-ssi

Critique : pup d'abord, SSH en second

Vous n'avez PAS besoin d'accès SSH pour commencer le dépannage. La CLI pup interroge directement le backend de Datadog. Commencez immédiatement par des commandes pup en utilisant les informations que l'utilisateur vous a déjà fournies (hostname, nom du service, env). N'allez à SSH que si pup ne révèle pas la cause.

pup-cli : vérifier, installer et s'authentifier

Claude exécute

pup --version

Si non trouvé :

Claude exécute

brew tap datadog-labs/pack
brew install datadog-labs/pack/pup

Auth — vérifiez dans cet ordre :

1. Vérifiez le statut OAuth :

   pup auth status --site <DD_SITE>

Si authentifié — procédez directement à l'étape 1.

ERREUR : Non authentifié :

Claude exécute

pup auth login --site <DD_SITE>

Cela ouvre un onglet de navigateur pour OAuth. Terminez la connexion là — Claude continuera une fois que la commande se termine.

2. Si la connexion OAuth n'est pas possible (par ex., pas d'accès navigateur), revenez aux clés API :

   echo "DD_API_KEY configurée : $([ -n "${DD_API_KEY:-}" ] && echo oui || echo non)"
   echo "DD_APP_KEY configurée : $([ -n "${DD_APP_KEY:-}" ] && echo oui || echo non)"

Si DD_API_KEY et DD_APP_KEY sont toutes deux configurées — procédez à l'étape 1. pup les utilisera automatiquement même si pup auth status affiche non authentifié.

Contexte

Utilisez ce que l'utilisateur a déjà fourni. Ne demandez pas le contexte manquant à l'avance — résolvez les variables paresseusement, seulement quand une étape spécifique en a besoin.

Si l'utilisateur a déjà fourni DD_HOSTNAME et SERVICE_NAME, allez directement à l'étape 1. Ne demandez pas ENV ou les détails SSH d'abord.

Comment fonctionne SSI sur Linux — Connaissances du domaine

Lisez ceci avant d'enquêter. Cela vous donne le modèle mental pour raisonner sur les nouvelles défaillances.

Chaîne d'injection :

1. Le script d'installation (avec DD_APM_INSTRUMENTATION_ENABLED=host) installe datadog-apm-inject et les packages de bibliothèque de langage sous /opt/datadog-packages/
2. Le package d'injection écrit son chemin de lanceur dans /etc/ld.so.preload
3. L'éditeur de liens dynamique Linux pré-charge le lanceur dans chaque nouveau processus au démarrage
4. Le lanceur détecte la langue du processus et charge le fichier .so du traceur approprié à partir de /opt/datadog-packages/datadog-apm-library-<lang>/
5. Le traceur envoie les spans à l'Agent à localhost:8126
6. L'Agent transfère les traces à Datadog à intake.<DD_SITE>

Couches de diagnostic :

• pup — voit ce que le backend de Datadog a reçu + les erreurs d'injection signalées par le lanceur. Commencez ici.
• /proc/<pid>/maps — voit les bibliothèques partagées réellement chargées dans un processus en cours d'exécution. La vérification faisant autorité pour savoir si l'injection a réussi.
• datadog-agent status — voit si l'Agent local reçoit des traces.

Défaillances silencieuses connues :

• musl libc (Alpine) — le lanceur est compilé en glibc ; musl est incompatible au niveau ABI. L'éditeur de liens le charge mais l'injection s'arrête silencieusement
• ddtrace/OTel existant — le lanceur détecte le traceur installé par l'utilisateur et se désactive silencieusement (classe de résultat already_instrumented)
• Version runtime non supportée — ignorée silencieusement
• Processus démarré avant l'activation de SSI — /etc/ld.so.preload affecte seulement les nouveaux processus
• Binaire statique / Go — les programmes Go se lient statiquement et ignorent complètement LD_PRELOAD
• SELinux/AppArmor — peut bloquer les lectures /etc/ld.so.preload pour les processus confinés
• Répertoire de package vide/corrompu — datadog-installer status reflète l'enregistrement DB, pas les fichiers réels. Un package peut s'afficher comme installé alors que son répertoire est vide. Vérifiez toujours que les fichiers existent sous /opt/datadog-packages/<package>/

Identité du nom de service — important : Avec SSI, DD_SERVICE est souvent non configuré dans l'environnement du processus. Le traceur détecte automatiquement un nom de service. Le nom signalé par la télémétrie (ce que pup fleet tracers list et service-library-config get affichent) peut ne pas correspondre à ce que vous attendez dans l'interface APM :

• JVM : la télémétrie signale le nom d'artefact jar avec version (par ex. inventory-service-1.0.0), les spans utilisent le nom de base (inventory-service)
• Python : la télémétrie peut signaler fastapi ou django plutôt que le nom de l'app
• Node.js : les noms correspondent généralement

Si service-library-config get retourne vide, utilisez pup traces search --query "host:<DD_HOSTNAME>" --from 1h --limit 5 pour découvrir quels noms de service ont envoyé des traces, puis réessayez.

Étape 1 : Triage avec pup (pas de SSH requis)

Exécutez ceux-ci d'abord. Les réponses déterminent tout ce qui suit.

Claude exécute

# Vérifiez les erreurs d'injection (défaillances seulement — les injections réussies n'apparaissent pas ici)
pup apm troubleshooting list --hostname <DD_HOSTNAME>

# Vérifiez la config complète du traceur — regardez apm_enabled, trace_agent_url, site
pup apm service-library-config get --service-name <SERVICE_NAME> --env <ENV>

# Vérifiez quels services ont envoyé des traces (révèle les noms de service réels visibles au backend)
pup apm services list --from 1h

# Vérifiez si les traces existent du tout
pup traces search --query "service:<SERVICE_NAME>" --from 15m --limit 5

# Vérification de trace la plus rapide — les métriques arrivent avant les traces indexées
pup metrics query --query "sum:trace.*.request.hits{host:<DD_HOSTNAME>,service:<SERVICE_NAME>}.as_count()" --from 15m

ENV est requis pour service-library-config get. Si l'utilisateur ne l'a pas fourni, demandez-le avant d'exécuter cette commande.

Valeurs clés à vérifier dans la sortie de service-library-config get :

• apm_enabled — doit être true. Si false, le traceur n'enverra pas de traces indépendamment de l'injection.
• trace_agent_url — doit pointer vers http://localhost:8126 ou le socket de l'agent correct. Une valeur incorrecte = le traceur ne peut pas atteindre l'Agent.
• site — doit correspondre au site de votre organisation Datadog.

Étape 2 : Énoncez vos hypothèses

Avant d'enquêter, énoncez explicitement vos hypothèses classées en fonction de la sortie du triage. Ne sautez pas cette étape.

Énoncez explicitement vos 1-3 meilleures hypothèses : « D'après le triage, je pense que la cause la plus probable est X car Y. »

Étape 3 : Enquêter avec pup (plus approfondi)

Utilisez seulement les outils pertinents pour vos hypothèses.

Vérifiez la config du SDK en détail :

# Affiche toutes les valeurs de config avec leur source (env_var, remote_config, code, default)
pup apm service-library-config get --service-name <SERVICE_NAME> --env <ENV>

# Affiche seulement les configs où les instances ne s'accordent pas (dérive de config)
pup apm service-library-config get --service-name <SERVICE_NAME> --mixed

Valeurs clés à vérifier :

• apm_enabled — si false, le traceur n'enverra pas de traces. Vérifiez source pour voir qui l'a désactivé (code > env_var > remote_config > default)
• trace_agent_url — doit être http://localhost:8126 ou un socket Unix. Une valeur incorrecte = le traceur ne peut pas atteindre l'Agent
• site — doit correspondre au site de votre organisation Datadog. Incompatibilité = les traces vont à la mauvaise organisation
• service — avec SSI et sans DD_SERVICE configuré, source: default est attendu

Si service-library-config get retourne vide — le nom de service que vous utilisez ne correspond peut-être pas au nom réel dans les données de trace :

pup traces search --query "host:<DD_HOSTNAME>" --from 1h --limit 5

Utilisez le champ service des résultats de trace pour les recherches de config suivantes.

Vérifiez les détails des erreurs d'injection :

pup apm troubleshooting list --hostname <DD_HOSTNAME> --timeframe 4h

Étape 4 : Enquêter via SSH (si pup n'a pas révélé la cause)

Avant de demander les identifiants SSH, expliquez brièvement ce que vous devez vérifier et pourquoi, pour que l'utilisateur comprenne le plan de diagnostic avant de vous donner accès.

/etc/ld.so.preload est-il configuré ?

ssh -o StrictHostKeyChecking=no -i <SSH_KEY> <SSH_USER>@<SSH_HOST> "cat /etc/ld.so.preload"

S'il contient un chemin se terminant par launcher.preload.so ou libdatadog-apm-inject.so — le lanceur est armé pour les nouveaux processus. ERREUR : Vide ou manquant — SSI n'a pas été complètement configuré. Réexécutez le script d'installation avec DD_APM_INSTRUMENTATION_ENABLED=host.

Le traceur est-il réellement chargé dans le processus en cours d'exécution ?

C'est la vérification d'injection faisant autorité — utilisez /proc/<pid>/maps, pas environ :

ssh -o StrictHostKeyChecking=no -i <SSH_KEY> <SSH_USER>@<SSH_HOST> \
  "pgrep -a -f '<SERVICE_NAME>' | head -3"

Utilisez le PID :

ssh -o StrictHostKeyChecking=no -i <SSH_KEY> <SSH_USER>@<SSH_HOST> \
  "sudo cat /proc/<PID>/maps | grep -E 'launcher|apm-library|datadog'"

• Lanceur + bibliothèque de langage présents — l'injection a réussi pour ce processus
• Lanceur seulement, pas de bibliothèque de langage — le lanceur a fonctionné mais n'a pas pu injecter le traceur (vérifiez pup troubleshooting list pour la raison)
• Rien — /etc/ld.so.preload non configuré, processus démarré avant l'activation de SSI, ou binaire statique

Le processus a-t-il été démarré avant l'activation de SSI ?

ssh -o StrictHostKeyChecking=no -i <SSH_KEY> <SSH_USER>@<SSH_HOST> \
  "ps -p <PID> -o pid,lstart,cmd; stat /etc/ld.so.preload"

Si le processus a démarré avant que /etc/ld.so.preload soit écrit, redémarrez le service. Confirmez toujours avec l'utilisateur avant de redémarrer les services en production.

La libc de base est-elle musl ?

ssh -o StrictHostKeyChecking=no -i <SSH_KEY> <SSH_USER>@<SSH_HOST> \
  "ldd --version 2>&1 | head -1 && cat /etc/os-release | grep PRETTY_NAME"

ERREUR : musl — le lanceur de SSI nécessite glibc. Pas de contournement ; doit migrer vers Debian/Ubuntu/RHEL/Amazon Linux.

Est-ce un binaire statique ?

ssh -o StrictHostKeyChecking=no -i <SSH_KEY> <SSH_USER>@<SSH_HOST> \
  "file /proc/<PID>/exe; ldd /proc/<PID>/exe 2>&1"

ERREUR : statically linked — SSI ne peut pas instrumenter ce binaire. L'instrumentation manuelle est requise.

Les packages APM sont-ils réellement présents sur le disque ?

datadog-installer status reflète seulement l'enregistrement DB — un package peut s'afficher comme installé alors que son répertoire est vide. Vérifiez toujours :

ssh -o StrictHostKeyChecking=no -i <SSH_KEY> <SSH_USER>@<SSH_HOST> \
  "ls /opt/datadog-packages/ && ls /opt/datadog-packages/datadog-apm-library-<LANG>/ | head -5"

ERREUR : Répertoire vide ou manquant — le package est enregistré mais cassé sur le disque. Utilisez le flux de correction.

L'app a-t-elle une instrumentation manuelle existante ?

ssh -o StrictHostKeyChecking=no -i <SSH_KEY> <SSH_USER>@<SSH_HOST> "
sudo cat /proc/<PID>/maps | grep -E 'ddtrace|opentelemetry|dd-trace'
"

Vérifiez aussi les manifestes de dépendance : requirements.txt, package.json, Gemfile, pom.xml. ERREUR : Trouvé — SSI s'est désactivé silencieusement. Supprimez le traceur manuel, redémarrez le service.

Le récepteur APM de l'Agent écoute-t-il et reçoit-il des traces ?

ssh -o StrictHostKeyChecking=no -i <SSH_KEY> <SSH_USER>@<SSH_HOST> \
  "sudo datadog-agent status 2>&1 | grep -A 15 'APM Agent'"

• feature_auto_instrumentation_enabled: true — SSI est actif sur l'agent
• Receiver (previous minute) — nombre de traces reçues par l'agent
• Endpoints — où les traces sont transférées

ssh -o StrictHostKeyChecking=no -i <SSH_KEY> <SSH_USER>@<SSH_HOST> \
  "sudo ss -tlnp 2>/dev/null | grep 8126 || sudo netstat -tlnp 2>/dev/null | grep 8126"

ERREUR : Port 8126 n'écoute pas — récepteur APM désactivé. Vérifiez apm_config.enabled dans /etc/datadog-agent/datadog.yaml.

Quel nom de service le traceur a-t-il enregistré ?

Avec SSI, DD_SERVICE est souvent non configuré. Lisez la memfd du traceur pour trouver le vrai nom de service :

ssh -o StrictHostKeyChecking=no -i <SSH_KEY> <SSH_USER>@<SSH_HOST> "
sudo ls -la /proc/<PID>/fd/ | grep 'datadog-tracer-info'
"

Utilisez le numéro fd :

ssh -o StrictHostKeyChecking=no -i <SSH_KEY> <SSH_USER>@<SSH_HOST> \
  "sudo cat /proc/<PID>/fd/<FD_NUM> | python3 -c \"import sys,msgpack; d=msgpack.unpackb(sys.stdin.buffer.read()); print(d)\""

Retourne service_name, service_env, tracer_version.

SELinux/AppArmor bloque-t-il /etc/ld.so.preload ?

ssh -o StrictHostKeyChecking=no -i <SSH_KEY> <SSH_USER>@<SSH_HOST> "
getenforce 2>/dev/null
ausearch -m AVC -ts recent 2>/dev/null | grep 'ld.so.preload\|datadog' | tail -10
dmesg | grep -i 'apparmor.*denied.*datadog' | tail -5
"

Si SELinux/AppArmor refuse l'accès, travaillez avec l'équipe de sécurité de l'utilisateur. Ne désactivez pas SELinux à l'échelle du système.

Étape 5 : Réfléchissez avant de conclure

Avant d'appliquer une correction, répondez :

1. Quelles preuves confirment mon hypothèse ?
2. Quelles preuves la contrediraient — et les ai-je vérifiées ?
3. Y a-t-il une explication plus simple que je n'ai pas envisagée ?

Si la conclusion ne tient pas, retournez à l'étape 2 avec de nouvelles hypothèses.

Étape 6 : Corriger

Correction : Réinstaller un package APM cassé

datadog-installer status reflète l'enregistrement DB, pas la présence de fichiers réels. Si pup troubleshooting list affiche incorrect_installation mais l'installateur dit que le package est installé, l'enregistrement est périmé :

# Supprimez d'abord l'enregistrement périmé
ssh -o StrictHostKeyChecking=no -i <SSH_KEY> <SSH_USER>@<SSH_HOST> \
  "sudo datadog-installer remove datadog-apm-library-<LANG>"

# Réexécutez l'installation — maintenant il téléchargera et extraira réellement
ssh -o StrictHostKeyChecking=no -i <SSH_KEY> <SSH_USER>@<SSH_HOST> \
  "DD_API_KEY=${DD_API_KEY} DD_SITE=${DD_SITE} DD_APM_INSTRUMENTATION_ENABLED=host bash -c \"\$(curl -L https://install.datadoghq.com/scripts/install_script_agent7.sh)\""

Si réexécuter le script d'installation est suffisant (les fichiers du package sont intacts), utilisez remove d'abord seulement si le script signale le succès mais le problème persiste.

Après tout changement de config — redémarrez le service (confirmez d'abord avec l'utilisateur pour la production) :

L'utilisateur doit redémarrer le service affecté pour que SSI réinjecte. Identifiez le gestionnaire de services et présentez les instructions de redémarrage — ne redémarrez pas automatiquement sauf si l'utilisateur le demande explicitement.

Commandes de redémarrage courantes :

# systemd
sudo systemctl restart <SERVICE_NAME>
# supervisord
sudo supervisorctl restart <PROGRAM_NAME>
# pm2
pm2 reload <APP_NAME>

Étape 7 : Vérifier

Réexécutez les commandes de triage pup pour confirmer que la correction a fonctionné :

Claude exécute

pup apm troubleshooting list --hostname <DD_HOSTNAME> --timeframe 15m
pup traces search --query "service:<SERVICE_NAME>" --from 15m --limit 5
pup metrics query --query "sum:trace.*.request.hits{host:<DD_HOSTNAME>,service:<SERVICE_NAME>}.as_count()" --from 15m

S'il n'y a pas de nouvelles erreurs d'injection et que les traces arrivent — résolu. Procédez automatiquement à onboarding-summary maintenant — ne demandez pas la permission à l'utilisateur.

ERREUR : Toujours en échec — retournez à l'étape 2 avec des hypothèses mises à jour.

Contraintes de sécurité

• Ne jamais écrire une clé API brute dans un fichier ou un message de chat
• Ne jamais désactiver SELinux à l'échelle du système
• Confirmez toujours avant de redémarrer les services en production
• datadog-installer remove nécessite une confirmation explicite — confirmez avec l'utilisateur avant d'exécuter