Tracing Docker Applications

Enable the Trace Agent in the datadog/agent container by passing DD_APM_ENABLED=true as an environment variable.

Tracing from the host

Tracing is available on port 8126/tcp from your host only by adding the option -p 127.0.0.1:8126:8126/tcp to the docker run command.

To make it available from any host, use -p 8126:8126/tcp instead.

For example, the following command allows the Agent to receive traces from your host only:

docker run -d -v /var/run/docker.sock:/var/run/docker.sock:ro \
              -v /proc/:/host/proc/:ro \
              -v /sys/fs/cgroup/:/host/sys/fs/cgroup:ro \
              -p 127.0.0.1:8126:8126/tcp \
              -e DD_API_KEY=<YOUR_API_KEY> \
              -e DD_APM_ENABLED=true \
              datadog/agent:latest

Docker APM Agent Environment Variables

List of all environment variables available for tracing within the Docker Agent:

Environment variable	Description
`DD_API_KEY`	Datadog API Key
`DD_PROXY_HTTPS`	Set up the URL for the proxy to use.
`DD_HOSTNAME`	Manually set the hostname to use for metrics if autodection fails, or when running the Datadog Cluster Agent.
`DD_DOGSTATSD_PORT`	Set the DogStatsD port.
`DD_BIND_HOST`	Set the StatsD & receiver hostname.
`DD_LOG_LEVEL`	Set the logging level. (`trace`/`debug`/`info`/`warn`/`error`/`critical`/`off`)
`DD_APM_ENABLED`	When set to `true`, the Datadog Agent accepts trace metrics.
`DD_APM_CONNECTION_LIMIT`	Sets the maximum connection limit for a 30 second time window.
`DD_APM_DD_URL`	Datadog API endpoint where traces are sent. For Datadog EU site set `DD_APM_DD_URL` to `https://trace.agent.datadoghq.eu`
`DD_APM_RECEIVER_PORT`	Port that the Datadog Agent’s trace receiver listens on. Default value is `8126`.
`DD_APM_NON_LOCAL_TRAFFIC`	Allow non-local traffic when tracing from other containers.
`DD_APM_IGNORE_RESOURCES`	Configure resources for the Agent to ignore. Format should be comma separated, regular expressions. i.e. `“GET /ignore-me,(GET\|POST) /and-also-me”`.
`DD_APM_ANALYZED_SPANS`	Configure the spans to analyze for transactions. Format should be comma separated instances of `<SERVICE_NAME>\|<OPERATION_NAME>=1`. i.e. `my-express-app\|express.request=1,my-dotnet-app\|aspnet_core_mvc.request=1`. You can also enable it automatically with the configuration parameter in the Tracing Client.
`DD_APM_ENV`	Sets the default environment for your traces.
`DD_APM_MAX_EPS`	Sets the maximum APM events per second.
`DD_APM_MAX_TPS`	Sets the maximum traces per second.

Tracing from other containers

As with DogStatsD, traces can be submitted to the Agent from other containers either using Docker networks or with the Docker host IP.

Docker Network

As a first step, create a user-defined bridge network:

docker network create <NETWORK_NAME>

Then start the Agent and the application container, connected to the network previously created:

# Datadog Agent
docker run -d --name datadog-agent \
              --network <NETWORK_NAME> \
              -v /var/run/docker.sock:/var/run/docker.sock:ro \
              -v /proc/:/host/proc/:ro \
              -v /sys/fs/cgroup/:/host/sys/fs/cgroup:ro \
              -e DD_API_KEY=<YOUR_API_KEY> \
              -e DD_APM_ENABLED=true \
              -e DD_APM_NON_LOCAL_TRAFFIC=true \
              datadog/agent:latest

# Application
docker run -d --name app \
              --network <NETWORK_NAME> \
              company/app:latest

This exposes the hostname datadog-agent in your app container. If you’re using docker-compose, <NETWORK_NAME> parameters are the ones defined under the networks section of your docker-compose.yml.

Your application tracers must be configured to submit traces to this address. Set environment variables with the DD_AGENT_HOST as the Agent container name, and DD_TRACE_AGENT_PORT as the Agent Trace port in your application containers. (In this example case, datadog-agent and 8126, respectively.)

Alternately, see the examples below to set the Agent host manually in each supported language:

Dropdown

Either update the Java Agent configuration via environment variables:

DD_AGENT_HOST=datadog-agent \
DD_TRACE_AGENT_PORT=8126 \
java -javaagent:/path/to/the/dd-java-agent.jar -jar /your/app.jar

or via system properties:

java -javaagent:/path/to/the/dd-java-agent.jar \
     -Ddd.agent.host=datadog-agent \
     -Ddd.agent.port=8126 \
     -jar /your/app.jar

from ddtrace import tracer

tracer.configure(
    hostname='datadog-agent',
    port=8126,
)

Datadog.configure do |c|
  c.tracer hostname: 'datadog-agent',
           port: 8126
end

package main

import "gopkg.in/DataDog/dd-trace-go.v1/ddtrace/tracer"

func main() {
    tracer.Start(tracer.WithAgentAddr("datadog-agent:8126"))
    defer tracer.Stop()
}

const tracer = require('dd-trace').init({
  hostname: 'datadog-agent',
  port: 8126
})

Docker host IP

Agent container port 8126 should be linked to the host directly. Configure your application tracer to report to the default route of this container (determine this using the ip route command).

The following is an example for the Python Tracer, assuming 172.17.0.1 is the default route:

from ddtrace import tracer

tracer.configure(hostname='172.17.0.1', port=8126)