Présentation

Dans un conteneur Linux Docker, utilisez l’instrumentation en une seule étape (SSI) pour APM afin d’installer le Datadog Agent et d’instrumenter vos applications en une seule étape, sans configuration supplémentaire requise.

Configurer APM avec un agent

Install the dd-apm skill in your AI coding agent for guided APM setup.
npx skills add https://github.com/datadog-labs/agent-skills --skill dd-apm --full-depth -y

Activez APM sur vos applications

Avant de continuer, confirmez que votre environnement est compatible en consultant le guide de compatibilité SSI.

Pour installer le Datadog Agent et activer SSI dans un environnement Docker Linux, exécutez les commandes suivantes sur votre host Docker (et non à l’intérieur d’un conteneur d’application).

  1. Installez les composants d’instrumentation Docker sans installer un Agent sur le host :

    DD_APM_INSTRUMENTATION_ENABLED=docker \
    DD_NO_AGENT_INSTALL=true \
    bash -c "$(curl -L https://install.datadoghq.com/scripts/install_script_agent7.sh)"
    
  2. Exécutez ou redéployez le conteneur Agent. Remplacez <YOUR_DD_API_KEY> par votre clé d’API Datadog :

    docker run -d --name dd-agent \
      -e DD_API_KEY=<YOUR_DD_API_KEY> \
      -e DD_SITE="" \
      -e DD_DOGSTATSD_NON_LOCAL_TRAFFIC=true \
      -e DD_APM_ENABLED=true \
      -e DD_APM_NON_LOCAL_TRAFFIC=true \
      -e DD_APM_RECEIVER_SOCKET=/var/run/datadog/apm.socket \
      -e DD_DOGSTATSD_SOCKET=/var/run/datadog/dsd.socket \
      -v /var/run/datadog:/var/run/datadog \
      -v /var/run/docker.sock:/var/run/docker.sock:ro \
      -v /proc/:/host/proc/:ro \
      -v /sys/fs/cgroup/:/host/sys/fs/cgroup:ro \
      -v /var/lib/docker/containers:/var/lib/docker/containers:ro \
      registry.datadoghq.com/agent:7
    

    Note: Run only one Datadog Agent per node. If a Datadog Agent container already exists, update its definition (or your Docker Compose file) with these settings and recreate it, rather than starting a second Agent. For rootless Docker, set the correct Docker socket in docker_config.yaml.

  3. Recreate your application containers.

    Instrumentation is applied when a container is created, so restarting an existing container with docker stop and docker start does not instrument it. Remove your application containers and run them again.

SSI adds a small amount of startup time to instrumented applications. If this overhead is not acceptable for your use case, contact Datadog Support.

Generate the command from Datadog

To get a command pre-filled with your API key and site, go to the Install the Datadog Agent on Docker page. In the Customize my agent install command section, go to Additional configuration > Application Observability, and turn on APM Instrumentation. Then copy and run the generated command.

La section « Personnalisez votre commande d'installation d'agent » des instructions intégrées à l'application pour l'installation du Datadog Agent sur Docker

Définir les versions du traceur SDK

Par défaut, l’instrumentation en une seule étape installe les dernières versions majeures des SDK Datadog et applique automatiquement les mises à jour mineures dès leur disponibilité.

Pour fixer des versions spécifiques, ajoutez la variable DD_APM_INSTRUMENTATION_LIBRARIES avec des paires language:major séparées par des virgules à la commande d’installation du composant. Les versions disponibles sont répertoriées dans les dépôts sources pour chaque langage :

Vous pouvez également sélectionner des versions dans les menus déroulants de Datadog : sur la page Install the Datadog Agent on Docker, après avoir activé APM Instrumentation, cliquez sur Customize library versions.

Le menu déroulant « Personnaliser les versions de la bibliothèque » dans les instructions d'installation du Datadog Agent sur Docker

Vérifiez l’installation

  1. Vérifiez que le démon Docker utilise le runtime Datadog :

    docker system info --format '{{.DefaultRuntime}}'
    

    The output must be dd-shim. If it is runc or anything else, the instrumentation components did not install successfully, and your applications are not instrumented regardless of whether the Agent is healthy. Re-run the installation command, and confirm that the Docker daemon was running when you ran it.

  2. Confirm the Agent container is running:

    docker ps --filter name=dd-agent
    
  3. Vérifiez que l’Agent est sain et que l’Agent APM est en cours d’exécution :

    docker exec dd-agent agent status
    

    Vérifiez la section APM Agent de la sortie.

  4. Vérifiez qu’un conteneur d’application utilise le runtime Datadog. Remplacez <CONTAINER_NAME> par le nom de l’un de vos conteneurs d’application :

    docker inspect <CONTAINER_NAME> --format '{{.HostConfig.Runtime}}'
    
  5. After your applications receive traffic, confirm your services appear on the APM Services page. If they don’t appear within a few minutes, follow the SSI troubleshooting guide.

Configure Unified Service Tags

Unified Service Tags (USTs) apply consistent tags across traces, metrics, and logs, making it easier to navigate and correlate your observability data. Learn how to set USTs for Docker services.

Enable SDK-dependent products and features

After SSI loads the Datadog SDK into your applications and enables distributed tracing, you can configure additional products that rely on the SDK:

ProductEnvironment variable
Runtime MetricsDD_RUNTIME_METRICS_ENABLED
Log InjectionDD_LOGS_INJECTION
Continuous ProfilerDD_PROFILING_ENABLED
Data Streams MonitoringDD_DATA_STREAMS_ENABLED
App and API ProtectionDD_APPSEC_ENABLED
Runtime Code Analysis (IAST)DD_IAST_ENABLED
Dynamic InstrumentationDD_DYNAMIC_INSTRUMENTATION_ENABLED
Data Jobs MonitoringDD_DATA_JOBS_ENABLED
Software Composition AnalysisDD_APPSEC_SCA_ENABLED

Note: All variables accept true or false. DD_PROFILING_ENABLED also accepts auto, which profiles only eligible processes and is recommended for SSI.

Pour activer des produits, définissez des variables d’environnement dans la configuration de votre application.

Supprimez l’instrumentation APM en une étape de votre Datadog Agent

Si vous ne souhaitez pas collecter de données de trace pour un service, un host, une VM ou un conteneur particulier, effectuez les étapes suivantes :

Supprimer l’instrumentation pour des services spécifiques

Pour supprimer l’instrumentation APM et arrêter l’envoi de traces depuis un service spécifique :

  1. Ajoutez la variable d’environnement DD_INSTRUMENT_SERVICE_WITH_APM à la commande de démarrage du service :
    docker run -e DD_INSTRUMENT_SERVICE_WITH_APM=false <service_start_command>
    
  2. Redémarrez le service.

Supprimer APM pour tous les services sur l’infrastructure

Pour arrêter la production de traces, désinstallez APM et redémarrez l’infrastructure :

  1. Exécutez :
    dd-container-install --uninstall
    
  2. Redémarrez Docker :
    systemctl restart docker
    
    Ou utilisez l’équivalent pour votre environnement.

Dépannage

Si vous rencontrez des problèmes lors de l’activation d’APM avec SSI, consultez le guide de dépannage SSI.

Pour aller plus loin

Documentation, liens et articles supplémentaires utiles: