Configurer SSI et les Unified Service Tags sur Linux

Avant toute chose : Résolvez complètement toutes les variables de ## Context to resolve before acting. Ne commencez pas l'Étape 0 tant que chaque variable n'a pas une valeur concrète.

Déclencheurs

Invoquez cette compétence quand :

• L'Agent Datadog est déjà installé avec SSI (DD_APM_INSTRUMENTATION_ENABLED=host a été utilisé) et vous devez configurer les Unified Service Tags sur le service applicatif
• L'utilisateur veut définir DD_SERVICE, DD_ENV, DD_VERSION sur un service en cours d'exécution
• SSI est installé mais /proc/<pid>/maps n'affiche pas le tracer de langage (injection launcher uniquement)

N'invoquez PAS cette compétence si :

• L'Agent Datadog n'est pas encore installé — exécutez agent-install d'abord
• Les packages SSI manquent de /opt/datadog-packages/ — réexécutez agent-install
• La cible est un cluster Kubernetes — utilisez dd-apm-k8s-enable-ssi à la place

Contexte

Quand le script d'installation s'exécute avec DD_APM_INSTRUMENTATION_ENABLED=host, il :

1. Installe datadog-apm-inject et les packages de bibliothèque de langage sous /opt/datadog-packages/
2. Écrit le chemin du launcher dans /etc/ld.so.preload
3. SSI est maintenant armé — chaque nouveau processus sur l'hôte reçoit le launcher injecté au démarrage

Ce que SSI ne configure PAS automatiquement :

• DD_SERVICE, DD_ENV, DD_VERSION — ces variables doivent être définies sur le processus applicatif pour que les traces soient taguées correctement
• Sans DD_SERVICE, le tracer auto-détecte un nom de service (souvent le nom du processus ou du framework), ce qui peut ne pas correspondre à ce que l'utilisateur attend

Prérequis

Vérifiez que SSI est armé :

Claude exécute

ssh -o StrictHostKeyChecking=no -i <SSH_KEY> <SSH_USER>@<SSH_HOST> \
  "cat /etc/ld.so.preload && ls /opt/datadog-packages/ | grep apm"

Si /etc/ld.so.preload contient un chemin vers le launcher, et /opt/datadog-packages/datadog-apm-inject existe — SSI est armé.

ERREUR : L'un des deux manque — exécutez agent-install d'abord.

Vérifiez la présence d'instrumentation manuelle existante :

Claude exécute

ssh -o StrictHostKeyChecking=no -i <SSH_KEY> <SSH_USER>@<SSH_HOST> "
grep -r 'import ddtrace\|from ddtrace\|require .dd-trace.\|opentelemetry' <SOURCE_DIR> 2>/dev/null | head -5 || echo 'No manual instrumentation found'
"

ERREUR : Instrumentation manuelle trouvée — SSI se désactive silencieusement quand il détecte un tracer existant. Supprimez l'import/package manuel avant de continuer.

Vérifiez la libc de base :

Claude exécute

ssh -o StrictHostKeyChecking=no -i <SSH_KEY> <SSH_USER>@<SSH_HOST> \
  "ldd --version 2>&1 | head -1"

ERREUR : musl — SSI nécessite glibc. Aucune solution ; vous devez utiliser un OS basé sur glibc.

Contexte à résoudre avant d'agir

Étape 0 (Seulement si instrumentation existante détectée) : Supprimer l'instrumentation manuelle

• Python : pip uninstall ddtrace, supprimez import ddtrace / ddtrace-run de CMD
• Node.js : npm uninstall dd-trace, supprimez require('dd-trace')
• Java : supprimez le flag JVM -javaagent:/path/to/dd-java-agent.jar
• Ruby : gem uninstall ddtrace, supprimez require 'ddtrace'
• .NET : supprimez le NuGet Datadog.Trace et les variables d'environnement du profiler

Après suppression, redémarrez le service. Confirmez avec l'utilisateur avant redémarrage. Dites à l'utilisateur : « Je dois redémarrer <SYSTEMD_SERVICE_NAME> pour supprimer l'ancienne instrumentation. Cela causera une brève indisponibilité. Prêt à continuer ? » Attendez la confirmation.

Étape 1 : Définir les Unified Service Tags sur le processus applicatif

Sans UST, les traces arrivent avec un nom de service auto-détecté qui peut ne pas correspondre aux attentes de l'utilisateur, et ne seront pas tagués avec l'env ou la version.

Pour les services gérés par systemd (le plus courant) :

Claude exécute

ssh -o StrictHostKeyChecking=no -i <SSH_KEY> <SSH_USER>@<SSH_HOST> \
  "sudo systemctl cat <SYSTEMD_SERVICE_NAME>"

Ajoutez un override drop-in (préserve le fichier d'unité original) :

Ce que vous devez faire dans un terminal

ssh -o StrictHostKeyChecking=no -i <SSH_KEY> <SSH_USER>@<SSH_HOST>
sudo systemctl edit <SYSTEMD_SERVICE_NAME>

Ajoutez à l'éditeur :

[Service]
Environment="DD_SERVICE=<SERVICE_NAME>"
Environment="DD_ENV=<ENV>"
Environment="DD_VERSION=<VERSION>"

Appliquez :

Claude exécute

ssh -o StrictHostKeyChecking=no -i <SSH_KEY> <SSH_USER>@<SSH_HOST> \
  "sudo systemctl daemon-reload && sudo systemctl show <SYSTEMD_SERVICE_NAME> | grep -E 'DD_SERVICE|DD_ENV|DD_VERSION'"

Si les variables UST apparaissent dans la sortie — la configuration est appliquée.

Pour supervisord :

# Dans la section [program:<name>] de supervisord.conf
environment=DD_SERVICE="<SERVICE_NAME>",DD_ENV="<ENV>",DD_VERSION="<VERSION>"

Rechargez : sudo supervisorctl reload

Pour pm2 :

// ecosystem.config.js
env: { DD_SERVICE: "<SERVICE_NAME>", DD_ENV: "<ENV>", DD_VERSION: "<VERSION>" }

Rechargez : pm2 reload <app>

Étape 2 : Redémarrer le service

Confirmez avec l'utilisateur avant redémarrage. Dites à l'utilisateur : « Je dois redémarrer <SYSTEMD_SERVICE_NAME> pour que SSI s'y injecte. Cela causera une brève indisponibilité. Prêt à continuer ? » Attendez la confirmation.

Claude exécute

ssh -o StrictHostKeyChecking=no -i <SSH_KEY> <SSH_USER>@<SSH_HOST> \
  "sudo systemctl restart <SYSTEMD_SERVICE_NAME> && sleep 3 && sudo systemctl is-active <SYSTEMD_SERVICE_NAME>"

Si active est retourné — le service est en cours d'exécution.

ERREUR : Retourne failed — vérifiez les logs :

ssh -o StrictHostKeyChecking=no -i <SSH_KEY> <SSH_USER>@<SSH_HOST> \
  "sudo journalctl -u <SYSTEMD_SERVICE_NAME> --since '1 minute ago' | tail -30"

Étape 3 : Confirmer l'injection et UST dans le processus en cours d'exécution

Claude exécute

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

Utilisez le PID :

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

# Variables UST dans l'environnement du processus
ssh -o StrictHostKeyChecking=no -i <SSH_KEY> <SSH_USER>@<SSH_HOST> \
  "sudo cat /proc/<PID>/environ | tr '\0' '\n' | grep -E 'DD_SERVICE|DD_ENV|DD_VERSION'"

Si le launcher et la bibliothèque de langage apparaissent dans maps, et les variables UST sont dans environ — SSI et le tagage sont entièrement configurés.

ERREUR : Launcher dans maps mais pas de bibliothèque de langage — injection tentée mais échouée. Exécutez :

pup apm troubleshooting list --hostname <DD_HOSTNAME> --timeframe 15m

Allez à troubleshoot-ssi s'il y a des erreurs.

Terminé

Quittez quand TOUS les éléments suivants sont vrais :

• [ ] Launcher et bibliothèque de langage visibles dans /proc/<PID>/maps
• [ ] DD_SERVICE, DD_ENV, DD_VERSION présents dans /proc/<PID>/environ
• [ ] Le service est en cours d'exécution et sain

Procédez automatiquement à verify-ssi maintenant — ne demandez pas la permission à l'utilisateur.

Contraintes de sécurité

• Ne jamais écrire une clé API brute dans un fichier ou message de chat
• Toujours confirmer avec l'utilisateur avant de redémarrer les services de production
• Ne modifiez pas le code source de l'application — configurez uniquement via les variables d'environnement dans l'unité de service