Overview

In a Docker Linux container, use Single Step Instrumentation (SSI) for APM to install the Datadog Agent and instrument your applications in one step, with no additional configuration required.

npx skills add https://github.com/datadog-labs/agent-skills --skill dd-apm --full-depth -y

Enable APM on your applications

To install the Datadog Agent and enable SSI in a Docker Linux environment, run the following commands on your Docker host (not inside an application container).

1. Install the Docker instrumentation components without installing a host Agent:

   DD_APM_INSTRUMENTATION_ENABLED=docker \
   DD_NO_AGENT_INSTALL=true \
   bash -c "$(curl -L https://install.datadoghq.com/scripts/install_script_agent7.sh)"
   

2. Run or redeploy the Agent container. Replace <YOUR_DD_API_KEY> with your Datadog API key:

   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.

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.

Set SDK tracer versions

By default, Single Step Instrumentation installs the latest major versions of the Datadog SDKs, and applies minor updates automatically when they become available.

To pin specific versions, add the DD_APM_INSTRUMENTATION_LIBRARIES variable with comma-separated language:major pairs to the component installation command. Available versions are listed in the source repositories for each language:

• Java (java)
• Node.js (js)
• Python (python)
• .NET (dotnet)
• Ruby (ruby)
• PHP (php)

You can also select versions from dropdowns in Datadog: on the Install the Datadog Agent on Docker page, after you turn on APM Instrumentation, click Customize library versions.

Verify the installation

1. Confirm the Docker daemon is using the Datadog runtime:

   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. Confirm the Agent is healthy and the APM Agent is running:

   docker exec dd-agent agent status
   

   Check the APM Agent section of the output.

4. Confirm that an application container is using the Datadog runtime. Replace <CONTAINER_NAME> with the name of one of your application containers:

   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:

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

To enable products, set environment variables in your application configuration.

Remove Single Step APM instrumentation from your Agent

If you don’t want to collect trace data for a particular service, host, VM, or container, complete the following steps:

Remove instrumentation for specific services

To remove APM instrumentation and stop sending traces from a specific service:

1. Add the DD_INSTRUMENT_SERVICE_WITH_APM environment variable to the service startup command:

   docker run -e DD_INSTRUMENT_SERVICE_WITH_APM=false <service_start_command>
   

2. Restart the service.

Remove APM for all services on the infrastructure

To stop producing traces, uninstall APM and restart the infrastructure:

1. Run:

   dd-container-install --uninstall
   

2. Restart Docker:

   systemctl restart docker
   

   Or use the equivalent for your environment.

Troubleshooting

If you encounter problems enabling APM with SSI, see the SSI troubleshooting guide.

Further reading

Additional helpful documentation, links, and articles:

Enable Runtime MetricsDOCUMENTATION