---
title: Tracing Docker Applications
description: >-
  Configure APM trace collection for applications running in Docker containers
  using the Datadog Agent
breadcrumbs: >-
  Docs > Containers > Docker Agent for Docker, containerd, and Podman > Tracing
  Docker Applications
---

# Tracing Docker Applications

As of Agent 6.0.0, the Trace Agent is enabled by default. If it has been turned off, you can re-enable it in the `registry.datadoghq.com/agent` container by passing `DD_APM_ENABLED=true` as an environment variable.

The CLI commands on this page are for the Docker runtime. Replace `docker` with `nerdctl` for the containerd runtime, or `podman` for the Podman runtime.

{% alert level="info" %}
If you are collecting traces from a containerized app (your Agent and app running in separate containers), as an alternative to the following instructions, you can automatically inject the tracing library into your application. Read [Injecting Libraries](https://docs.datadoghq.com/tracing/trace_collection/library_injection_local/?tab=agentandappinseparatecontainers) for instructions.
{% /alert %}

## Tracing from the host{% #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:

{% tab title="Linux" %}

```shell
docker run -d --cgroupns host \
              --pid host \
              -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=<DATADOG_API_KEY> \
              -e DD_APM_ENABLED=true \
              -e DD_SITE=<DATADOG_SITE> \
              registry.datadoghq.com/agent:latest
```

Where your `<DATADOG_SITE>` is  (defaults to `datadoghq.com`).
{% /tab %}

{% tab title="Windows" %}

```shell
docker run -d -p 127.0.0.1:8126:8126/tcp \
              -e DD_API_KEY=<DATADOG_API_KEY> \
              -e DD_APM_ENABLED=true \
              -e DD_SITE=<DATADOG_SITE> \
              registry.datadoghq.com/agent:latest
```

Where your `<DATADOG_SITE>` is  (defaults to `datadoghq.com`).
{% /tab %}

## Docker APM Agent environment variables{% #docker-apm-agent-environment-variables %}

Use the following environment variables to configure tracing for the Docker Agent. See the [sample `config_template.yaml` file](https://github.com/DataDog/datadog-agent/blob/master/pkg/config/config_template.yaml) for more details.

{% dl %}

{% dt %}
`DD_API_KEY`
{% /dt %}

{% dd %}
required - *string*Your [Datadog API key](https://app.datadoghq.com/organization-settings/api-keys).
{% /dd %}

{% dt %}
`DD_SITE`
{% /dt %}

{% dd %}
optional - *string*Your [Datadog site](https://docs.datadoghq.com/getting_started/site/). Set this to ``.**Default**: `datadoghq.com`
{% /dd %}

{% dt %}
`DD_APM_ENABLED`
{% /dt %}

{% dd %}
optional - *Boolean* - **default**: `true`When set to `true` (default), the Datadog Agent accepts traces and trace metrics.
{% /dd %}

{% dt %}
`DD_APM_RECEIVER_PORT`
{% /dt %}

{% dd %}
optional - *integer* - **default**: `8126`Sets the port on which the Datadog Agent's trace receiver listens. Set to `0` to disable the HTTP receiver.
{% /dd %}

{% dt %}
`DD_APM_RECEIVER_SOCKET`
{% /dt %}

{% dd %}
optional - *string*To collect your traces through UNIX Domain Sockets, provide the path to the UNIX socket. If set, this takes priority over hostname and port configuration, and must point to a valid socket file.
{% /dd %}

{% dt %}
`DD_APM_NON_LOCAL_TRAFFIC`
{% /dt %}

{% dd %}
optional - *Boolean* - **default**: `false`When set to `true`, the Datadog Agent listens to non-local traffic. If you are tracing from other containers, set this environment variable to `true`.
{% /dd %}

{% dt %}
`DD_APM_DD_URL`
{% /dt %}

{% dd %}
optional - *string*To use a proxy for APM, provide the endpoint and port as `<ENDPOINT>:<PORT>`. The proxy must be able to handle TCP connections.
{% /dd %}

{% dt %}
`DD_APM_CONNECTION_LIMIT`
{% /dt %}

{% dd %}
required - *integer* - **default**: `2000`Sets the maximum APM connections for a 30 second time window. See [Agent Rate Limits](https://docs.datadoghq.com/tracing/troubleshooting/agent_rate_limits) for more details.
{% /dd %}

{% dt %}
`DD_APM_IGNORE_RESOURCES`
{% /dt %}

{% dd %}
optional - *[string]*Provides an exclusion list of resources for the Datadog Agent to ignore. If a trace's resource name matches one or more of the regular expressions on this list, the trace is not sent to Datadog.Example: `"GET /ignore-me","(GET\|POST) and-also-me"`.
{% /dd %}

{% dt %}
`DD_APM_FILTER_TAGS_REQUIRE`
{% /dt %}

{% dd %}
optional - *object*Defines rules for tag-based trace filtering. To be sent to Datadog, traces must have these tags. See [Ignoring Unwanted Resources in APM](https://docs.datadoghq.com/tracing/guide/ignoring_apm_resources/).
{% /dd %}

{% dt %}
`DD_APM_FILTER_TAGS_REGEX_REQUIRE`
{% /dt %}

{% dd %}
optional - *object*Supported in Agent 7.49+. Defines rules for tag-based trace filtering with regular expressions. To be sent to Datadog, traces must have tags that match these regex patterns.
{% /dd %}

{% dt %}
`DD_APM_FILTER_TAGS_REJECT`
{% /dt %}

{% dd %}
optional - *object*Defines rules for tag-based trace filtering. If a trace has these tags, it is not sent to Datadog. See [Ignoring Unwanted Resources in APM](https://docs.datadoghq.com/tracing/guide/ignoring_apm_resources/) for more details.
{% /dd %}

{% dt %}
`DD_APM_FILTER_TAGS_REGEX_REJECT`
{% /dt %}

{% dd %}
optional - *object*Supported in Agent 7.49+. Defines rules for tag-based trace filtering with regular expressions. If a trace has tags that match these regex patterns, the trace is not sent to Datadog.
{% /dd %}

{% dt %}
`DD_APM_REPLACE_TAGS`
{% /dt %}

{% dd %}
optional - *[object]*Defines a set of rules to [replace or remove tags that contain potentially sensitive information](https://docs.datadoghq.com/tracing/configure_data_security/#replace-tags).
{% /dd %}

{% dt %}
`DD_HOSTNAME`
{% /dt %}

{% dd %}
optional - *string* - **default**: automatically detectedSets the hostname to use for metrics if automatic hostname detection fails, or when running the Datadog Cluster Agent.
{% /dd %}

{% dt %}
`DD_DOGSTATSD_PORT`
{% /dt %}

{% dd %}
optional - *integer* - **default**: `8125`Sets the DogStatsD port.
{% /dd %}

{% dt %}
`DD_PROXY_HTTPS`
{% /dt %}

{% dd %}
optional - *string*To use a [proxy](https://docs.datadoghq.com/agent/proxy) to connect to the internet, provide the URL.
{% /dd %}

{% dt %}
`DD_BIND_HOST`
{% /dt %}

{% dd %}
optional - *string* - **default**: `localhost`Sets the host to listen on for DogStatsD and traces.
{% /dd %}

{% dt %}
`DD_LOG_LEVEL`
{% /dt %}

{% dd %}
optional - *string* - **default**: `info`Sets the minimum logging level. Valid options: `trace`, `debug`, `info`, `warn`, `error`, `critical`, and `off`.
{% /dd %}

{% /dl %}

## Tracing from other containers{% #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{% #docker-network %}

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

```bash
docker network create <NETWORK_NAME>
```

The CLI commands on this page are for the Docker runtime. Replace `docker` with `nerdctl` for the containerd runtime, or `podman` for the Podman runtime.

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

{% tab title="Standard" %}

```bash
# Datadog Agent
docker run -d --name datadog-agent \
              --network <NETWORK_NAME> \
              --cgroupns host \
              --pid host \
              -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=<DATADOG_API_KEY> \
              -e DD_APM_ENABLED=true \
              -e DD_SITE=<DATADOG_SITE> \
              -e DD_APM_NON_LOCAL_TRAFFIC=true \
              registry.datadoghq.com/agent:latest
# Application
docker run -d --name app \
              --network <NETWORK_NAME> \
              -e DD_AGENT_HOST=datadog-agent \
              company/app:latest
```

Where your `<DATADOG_SITE>` is  (defaults to `datadoghq.com`).
{% /tab %}

{% tab title="Windows" %}

```bash
# Datadog Agent
docker run -d --name datadog-agent \
              --cgroupns host \
              --pid host \
              --network "<NETWORK_NAME>" \
              -e DD_API_KEY=<DATADOG_API_KEY> \
              -e DD_APM_ENABLED=true \
              -e DD_SITE=<DATADOG_SITE> \
              -e DD_APM_NON_LOCAL_TRAFFIC=true \
              registry.datadoghq.com/agent:latest
# Application
docker run -d --name app \
              --network "<NETWORK_NAME>" \
              -e DD_AGENT_HOST=datadog-agent \
              company/app:latest
```

Where your `<DATADOG_SITE>` is  (defaults to `datadoghq.com`).
{% /tab %}

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. The example above uses host `datadog-agent` and port `8126` (the default value so you don't have to set it).

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

{% tab title="Java" %}
Either update the Java Agent configuration with environment variables:

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

or through system properties:

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

{% /tab %}

{% tab title="Python" %}

```python
from ddtrace import tracer

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

{% /tab %}

{% tab title="Ruby" %}

```ruby
Datadog.configure do |c|
  c.agent.host = 'datadog-agent'
  c.agent.port = 8126
end
```

{% /tab %}

{% tab title="Go" %}
**Note**: This documentation uses v2 of the Go tracer, which Datadog recommends for all users. If you are using v1, see the [migration guide](https://docs.datadoghq.com/tracing/trace_collection/custom_instrumentation/go/migration) to upgrade to v2.

```go
package main

import (
  "github.com/DataDog/dd-trace-go/v2/ddtrace/tracer"
)

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

{% /tab %}

{% tab title="Node.js" %}

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

{% /tab %}

{% tab title=".NET" %}
Set the environment variables before running your instrumented app:

```bash
# Environment variables
export CORECLR_ENABLE_PROFILING=1
export CORECLR_PROFILER={846F5F1C-F9AE-4B07-969E-05C26BC060D8}
export CORECLR_PROFILER_PATH=<SYSTEM_DEPENDENT_PATH>
export DD_DOTNET_TRACER_HOME=/opt/datadog

# For containers
export DD_AGENT_HOST=datadog-agent
export DD_TRACE_AGENT_PORT=8126

# Start your application
dotnet example.dll
```

The value for the `CORECLR_PROFILER_PATH` environment variable varies based on the system where the application is running:

| Operating System and Process Architecture | CORECLR_PROFILER_PATH Value                                                  |
| ----------------------------------------- | ---------------------------------------------------------------------------- |
| Alpine Linux x64                          | `<APP_DIRECTORY>/datadog/linux-musl-x64/Datadog.Trace.ClrProfiler.Native.so` |
| Linux x64                                 | `<APP_DIRECTORY>/datadog/linux-x64/Datadog.Trace.ClrProfiler.Native.so`      |
| Linux ARM64                               | `<APP_DIRECTORY>/datadog/linux-arm64/Datadog.Trace.ClrProfiler.Native.so`    |
| Windows x64                               | `<APP_DIRECTORY>\datadog\win-x64\Datadog.Trace.ClrProfiler.Native.dll`       |
| Windows x86                               | `<APP_DIRECTORY>\datadog\win-x86\Datadog.Trace.ClrProfiler.Native.dll`       |

In the table above, `<APP_DIRECTORY>` refers to the directory containing the application's `.dll` files.
{% /tab %}

### Docker host IP{% #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:

```python
from ddtrace import tracer

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

### Unix Domain Socket (UDS){% #unix-domain-socket-uds %}

To submit traces via socket, the socket should be mounted to the Agent container and your application container.

```bash
# Datadog Agent
docker run -d --name datadog-agent \
              --network <NETWORK_NAME> \
              --cgroupns host \
              --pid host \
              -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/run/datadog/:/var/run/datadog/ \
              -e DD_API_KEY=<DATADOG_API_KEY> \
              -e DD_APM_ENABLED=true \
              -e DD_SITE=<DATADOG_SITE> \
              -e DD_APM_NON_LOCAL_TRAFFIC=true \
              -e DD_APM_RECEIVER_SOCKET=/var/run/datadog/apm.socket \
              registry.datadoghq.com/agent:latest
# Application
docker run -d --name app \
              --network <NETWORK_NAME> \
              -v /var/run/datadog/:/var/run/datadog/ \
              -e DD_TRACE_AGENT_URL=unix:///var/run/datadog/apm.socket \
              company/app:latest
```

Refer to the [language-specific APM instrumentation docs](https://docs.datadoghq.com/tracing/setup/) for tracer settings.

## Further Reading{% #further-reading %}

- [Source code](https://github.com/DataDog/datadog-agent/tree/main/pkg/trace)
- [Trace your ECS applications](https://docs.datadoghq.com/integrations/amazon_ecs/#trace-collection)
- [Collect your application logs](https://docs.datadoghq.com/agent/docker/log/)
- [Collect automatically your applications metrics and logs](https://docs.datadoghq.com/agent/docker/integrations/)
- [Limit data collection to a subset of containers only](https://docs.datadoghq.com/agent/guide/autodiscovery-management/)
- [Assign tags to all data emitted by a container](https://docs.datadoghq.com/agent/docker/tag/)