Name: docker-dd-agent
Owner: Datadog, Inc.
Description: Datadog Agent Dockerfile for Trusted Builds.
Created: 2014-06-03 17:57:23.0
Updated: 2018-01-11 20:42:30.0
Pushed: 2018-01-11 20:26:26.0
Homepage: https://registry.hub.docker.com/u/datadog/docker-dd-agent/
Size: 2509
Language: Roff
GitHub Committers
| User | Most Recent Commit | # Commits |
|---|
Other Committers
| User | Most Recent Commit | # Commits |
|---|
This repository is meant to build the base image for a Datadog Agent container. You will have to use the resulting image to configure and run the Agent.
The default image is ready-to-go. You just need to set your API_KEY in the environment.
er run -d --name dd-agent \
/var/run/docker.sock:/var/run/docker.sock:ro \
/proc/:/host/proc/:ro \
/sys/fs/cgroup/:/host/sys/fs/cgroup:ro \
API_KEY={your_api_key_here} \
SD_BACKEND=docker \
NON_LOCAL_TRAFFIC=false \
tadog/docker-dd-agent:latest
If you are running on Amazon Linux, use the following instead:
er run -d --name dd-agent \
/var/run/docker.sock:/var/run/docker.sock:ro \
/proc/:/host/proc/:ro \
/cgroup/:/host/sys/fs/cgroup:ro \
API_KEY={your_api_key_here} \
SD_BACKEND=docker \
NON_LOCAL_TRAFFIC=false \
tadog/docker-dd-agent:latest
By default the agent container will use the Name field found in the docker info command from the host as a hostname. To change this behavior you can update the hostname field in /etc/dd-agent/datadog.conf. The easiest way for this is to use the DD_HOSTNAME environment variable (see below).
For the Docker check to succeed, memory management by cgroup must be enabled on the host as explained in the debian wiki.
On Debian Jessie or later for example you will need to add cgroup_enable=memory swapaccount=1 to your boot options, otherwise the agent won't be able to recognize your system. See this thread for details.
The commands in the Quick Start section enable Autodiscovery in auto-conf mode, meaning the Agent will automatically run checks against any containers running images listed in the default check templates.
To learn more about Autodiscovery, read the Autodiscovery guide on the Datadog Docs site. To disable it, omit the SD_BACKEND environment variable when starting docker-dd-agent.
Some configuration parameters can be changed with environment variables:
DD_HOSTNAME set the hostname (write it in datadog.conf)
TAGS set host tags. Add -e TAGS=simple-tag-0,tag-key-1:tag-value-1 to use [simple-tag-0, tag-key-1:tag-value-1] as host tags.
EC2_TAGS set EC2 host tags. Add -e EC2_TAGS=yes to use EC2 custom host tags. Requires an IAM role associated with the instance.
LOG_LEVEL set logging verbosity (CRITICAL, ERROR, WARNING, INFO, DEBUG). Add -e LOG_LEVEL=DEBUG to turn logs to debug mode.
DD_LOGS_STDOUT: set it to yes to send all logs to stdout and stderr, for them to be processed by Docker.
PROXY_HOST, PROXY_PORT, PROXY_USER and PROXY_PASSWORD set the proxy configuration.
DD_URL set the Datadog intake server to send Agent data to (used when using an agent as a proxy )
NON_LOCAL_TRAFFIC configures the non_local_traffic option in the agent which enables or disables statsd reporting from any external ip. You may find this useful to report metrics from your other containers. See network configuration for more details. This option is set to true by default in the image, and the docker run command we provide in the example above disables it. Remove the -e NON_LOCAL_TRAFFIC=false part to enable it back. WARNING if you allow non-local traffic, make sure your agent container is not accessible from the Internet or other untrusted networks as it would allow anyone to submit metrics to it.
SD_BACKEND, SD_CONFIG_BACKEND, SD_BACKEND_HOST, SD_BACKEND_PORT, SD_TEMPLATE_DIR, SD_CONSUL_TOKEN, SD_BACKEND_USER and SD_BACKEND_PASSWORD configure Autodiscovery (previously known as Service Discovery):
SD_BACKEND: set to docker (the only supported backend) to enable Autodiscovery.
SD_CONFIG_BACKEND: set to etcd, consul, or zk to use one of these key-value stores as a template source.
SD_BACKEND_HOST and SD_BACKEND_PORT: configure the connection to the key-value template source.
SD_TEMPLATE_DIR: when using SD_CONFIG_BACKEND, set the path where the check configuration templates are located in the key-value store (default is datadog/check_configs)
SD_CONSUL_TOKEN: when using Consul as a template source and the Consul cluster requires authentication, set a token so the Datadog Agent can connect.
SD_BACKEND_USER and SD_BACKEND_PASSWORD: when using etcd as a template source and it requires authentication, set a user and password so the Datadog Agent can connect.
DD_APM_ENABLED run the trace-agent along with the infrastructure agent, allowing the container to accept traces on 8126/tcp (This option is NOT available on Alpine Images)
DD_PROCESS_AGENT_ENABLED run the process-agent along with the infrastructure agent, feeding data to the Live Process View and Live Containers View (This option is NOT available on Alpine Images)
DD_COLLECT_LABELS_AS_TAGS Enables the collection of the listed labels as tags. Comma separated string, without spaces unless in quotes. Exemple: -e DD_COLLECT_LABELS_AS_TAGS='com.docker.label.foo, com.docker.label.bar' or -e DD_COLLECT_LABELS_AS_TAGS=com.docker.label.foo,com.docker.label.bar.
Note: Some of those have alternative names, but with the same impact: it is possible to use DD_TAGS instead of TAGS, DD_LOG_LEVEL instead of LOG_LEVEL and DD_API_KEY instead of API_KEY.
It is possible to enable some checks through the environment:
KUBERNETES enables the kubernetes check if set (KUBERNETES=yes works)KUBERNETES_COLLECT_EVENTS to true on one agent per cluster. Alternatively, you can enable the leader election mechanism by setting KUBERNETES_LEADER_CANDIDATE to true on candidate agents, and adjust the lease time (in seconds) with the KUBERNETES_LEADER_LEASE_DURATION variable.default namespace are collected. To change what namespaces are used, set the KUBERNETES_NAMESPACE_NAME_REGEX regexp to a valid regexp matching your relevant namespaces.kube_service tags, the agent needs to query the apiserver's events and services endpoints. If you need to disable that, you can pass KUBERNETES_COLLECT_SERVICE_TAGS=false.KUBERNETES_KUBELET_HOST (eg. when using CNI networking, the kubelet API may not listen on the default route address)MESOS_MASTER and MESOS_SLAVE respectively enable the mesos master and mesos slave checks if set (MESOS_MASTER=yes works).MARATHON_URL if set will be used to enable the Marathon check that will query the URL passed in this variable for metrics. It can usually be set to http://leader.mesos:8080.Another way to enable checks is through Autodiscovery. This is particularly useful in dynamic environments like Kubernetes, Amazon ECS, or Docker Swarm. Read more about Autodiscovery on the Datadog Docs site.
You can also mount YAML configuration files in the /conf.d folder, they will automatically be copied to /etc/dd-agent/conf.d/ when the container starts. The same can be done for the /checks.d folder. Any Python files in the /checks.d folder will automatically be copied to /etc/dd-agent/checks.d/ when the container starts.
Create a configuration folder on the host and write your YAML files in it. The examples below can be used for the /checks.d folder as well.
r /opt/dd-agent-conf.d
h /opt/dd-agent-conf.d/nginx.yaml
When creating the container, mount this new folder to /conf.d.
er run -d --name dd-agent \
/var/run/docker.sock:/var/run/docker.sock:ro \
/proc/:/host/proc/:ro \
/sys/fs/cgroup/:/host/sys/fs/cgroup:ro \
/opt/dd-agent-conf.d:/conf.d:ro \
API_KEY={your_api_key_here} \
tadog/docker-dd-agent
The important part here is -v /opt/dd-agent-conf.d:/conf.d:ro
Now when the container starts, all files in /opt/dd-agent-conf.d with a .yaml extension will be copied to /etc/dd-agent/conf.d/. Please note that to add new files you will need to restart the container.
If you need to run any JMX-based Agent checks, run a JMX image, e.g. datadog/docker-dd-agent:latest-jmx, datadog/docker-dd-agent:11.0.5150-jmx, etc. These images are based on the default images but add a JVM, which is needed for the Agent to run jmxfetch.
The default images (e.g. latest) run a DogStatsD server as well as the main Agent (i.e. the collector). If you want to run DogStatsD only, run a DogStatsD-only image, e.g. datadog/docker-dd-agent:latest-dogstatsd, datadog/docker-dd-agent:11.0.5141-dogstatsd-alpine, etc. These images don't run the collector process.
They also run the DogStatsD server as a non-root user, which is useful for platforms like OpenShift. They also don't need shared volumes from the host (/proc, /sys/fs and the Docker socket) like the default Agent image.
Note: Metrics submitted by this container will NOT get tagged with any global tags specified in datadog.conf. These tags are only read by the Agent's collector process, which these DogStatsD-only images do not run.
Note: Optionally, these images can run the the trace-agent process. Pass -e DD_APM_ENABLED=true to your docker run command to activate the trace-agent and allow your container to receive traces from Datadog's APM client libraries.
DogStatsD can be available on port 8125 from anywhere by adding the option -p 8125:8125/udp to the docker run command.
To make it available from your host only, use -p 127.0.0.1:8125:8125/udp instead.
DogStatsd can be disabled by setting USE_DOGSTATSD to no
To send data to DogStatsD from other containers, add a --link dogstatsd:dogstatsd option to your run command.
For example, run a container my_container with the image my_image.
er run --name my_container \
--all_your_flags \
--link dogstatsd:dogstatsd \
my_image
DogStatsD address and port will be available in my_container's environment variables DOGSTATSD_PORT_8125_UDP_ADDR and DOGSTATSD_PORT_8125_UDP_PORT.
Since the Agent container port 8125 should be linked to the host directly, you can connect to DogStatsD through the host. Usually the IP address of the host in a Docker container can be determined by looking at the address of the default route of this container with ip route for example. You can then configure your DogStatsD client to connect to 172.17.42.1:8125 for example.
Enable the datadog-trace-agent in the docker-dd-agent container by passing
DD_APM_ENABLED=true as an environment variable
Note: APM is NOT available on Alpine Images
Tracing can be available on port 8126/tcp from anywhere by adding the options -p 8126:8126/tcp to the docker run command
To make it available from your host only, use -p 127.0.0.1:8126:8126/tcp instead.
For example, the following command will allow the agent to receive traces from anywhere
er run -d --name dd-agent \
/var/run/docker.sock:/var/run/docker.sock:ro \
/proc/:/host/proc/:ro \
/sys/fs/cgroup/:/host/sys/fs/cgroup:ro \
API_KEY={your_api_key_here} \
DD_APM_ENABLED=true \
8126:8126/tcp \
tadog/docker-dd-agent
Previous instructions required binding to port 7777. This is a legacy port used by former client libraries and has been replaced by 8126.
As with DogStatsD, traces can be submitted to the agent from other containers either using the Docker host IP or with Docker links
er run --name my_container \
--all_your_flags \
--link dd-agent:dd-agent \
my_image
will expose DD_AGENT_PORT_8126_TCP_ADDR and DD_AGENT_PORT_8126_TCP_PORT as environment variables. Your application tracer can be configured to submit to this address.
An example in Python:
rt os
ddtrace import tracer
er.configure(
hostname=os.environ["DD_AGENT_PORT_8126_TCP_ADDR"],
port=os.environ["DD_AGENT_PORT_8126_TCP_PORT"]
Agent container port 8126 should be linked to the host directly, Having determined the address of the default route of this container, with ip route for example, you can configure your application tracer to report to it.
An example in python, assuming 172.17.0.1 is the default route:
ddtrace import tracer; tracer.configure(hostname="172.17.0.1", port=8126)
To configure specific settings of the agent directly in the image, you may need to build a Docker image on top of ours.
Create a Dockerfile to set your specific configuration or to install dependencies.
datadog/docker-dd-agent
ample: MySQL
conf.d/mysql.yaml /etc/dd-agent/conf.d/mysql.yaml
Build it.
docker build -t dd-agent-image .
Then run it like the datadog/docker-dd-agent image.
er run -d --name dd-agent \
/var/run/docker.sock:/var/run/docker.sock:ro \
/proc/:/host/proc/:ro \
/sys/fs/cgroup/:/host/sys/fs/cgroup:ro \
API_KEY={your_api_key_here} \
-agent-image
It's done!
You can find some examples in our Github repository.
Starting from Agent 5.7 we also provide an image based on Alpine Linux. This image is smaller (about 60% the size of the Debian based one), and benefits from Alpine's security-oriented design. It is compatible with all options described in this file (Autodiscovery, enabling specific integrations, etc.) with the exception of JMX and Tracing (the trace-agent does not ship with the Alpine images).
This image is available under tags with the following naming convention usual_tag_name-alpine. So for example to use the latest tag: datadog/docker-dd-agent:latest-alpine must be pulled. To use a specific version number, specify 11.2.583-alpine.
The Alpine version can be used this way:
```
docker run -d --name dd-agent \
-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 API_KEY={your_api_key_here} \
datadog/docker-dd-agent:latest-alpine
```
Note: In this version, check configuration files must be stored in /opt/datadog-agent/agent/conf.d/ instead of /etc/dd-agent/conf.d/.
Warning: This version is recent, and its behaviour may differ a little (namely, it is running a source-installed agent so commands need to be adapted). If you find a bug, don't hesitate to file an issue, feedback around it is appreciated.
The docker image is following a versioning pattern that allows us to release changes to the Docker image of the Datadog Agent but with the same version of the Agent.
The Docker image version follows the following pattern:
X.Y.Z where X is the major version of the Docker Image, Y is the minor version, Z will represent the Agent version.
e.g. the first version of the Docker image that bundled the Datadog Agent 5.5.0 was:
.550
To display information about the Agent's state with this command.
debian:
docker exec dd-agent service datadog-agent info
alpine:
docker exec dd-agent /opt/datadog-agent/bin/agent info
Warning: the docker exec command is available only with Docker 1.3 and above.
That's the simplest solution. It imports container's log to one's host directory.
docker cp dd-agent:/var/log/datadog /tmp/log-datadog-agent
Basic information about the Agent execution are available through the logs command.
docker logs dd-agent
Exec a shell on the container and tail logs (collector.log, forwarder.log and jmxfetch.log) for debugging. The supervisor.log is available there as well but you can get that from docker logs dd-agent from the host.
alpine:
cker exec -it dd-agent ash
/datadog-agent # tail -f /opt/datadog-agent/logs/dogstatsd.log
-07-22 23:09:09 | INFO | dd.dogstatsd | dogstatsd(dogstatsd.py:210) | Flush #8: flushed 1 metric, 0 events, and 0 service check runs
debian:
cker exec -it dd-agent bash
il -f /var/log/datadog/dogstatsd.log
-07-22 23:09:09 | INFO | dd.dogstatsd | dogstatsd(dogstatsd.py:210) | Flush #8: flushed 1 metric, 0 events, and 0 service check runs
The Agent won't be able to collect disk metrics from volumes that are not mounted to the Agent container. If you want to monitor additional partitions, make sure to share them to the container in your docker run command (e.g. -v /data:/data:ro)
Docker isolates containers from the host. As a result, the Agent won't have access to all host metrics.
Known missing/incorrect metrics:
Also, several integrations might be incomplete. See the “Contribute” section.
If you notice a limitation or a bug with this container, feel free to open a Github issue. If it concerns the Agent itself, please refer to its documentation or its wiki.