datadog/docker-dd-agent

Datadog Agent 5.x Docker镜像文档

镜像概述和主要用途

本镜像为Datadog Agent 5.x版本提供容器化部署方案，用于在Docker环境中快速部署Datadog Agent。Datadog Agent是一款轻量级监控代理，可收集主机、容器、应用的系统指标、日志、 traces 等数据，并发送至Datadog平台进行可视化和分析。适用于容器化环境下的基础设施监控、应用性能追踪及日志管理。

核心功能和特性

• 容器监控：通过挂载Docker Socket，自动发现并监控容器生命周期、资源使用率（CPU、内存、网络、磁盘）。
• 自动发现（Autodiscovery）：支持基于Docker标签的服务自动发现，无需手动配置监控检查。
• 多环境适配：兼容Docker、Kubernetes、Mesos等容器编排平台，支持EC2等云环境标签采集。
• 指标与日志收集：集成DogStatsD（UDP指标收集）、APM追踪（8126端口），支持日志转发至stdout/stderr。
• 灵活配置：通过环境变量快速配置主机名、标签、代理、日志级别等参数。
• 轻量级变体：提供Alpine基础镜像（体积减少约60%）和独立DogStatsD镜像，满足不同部署需求。

使用场景和适用范围

• Docker环境监控：监控单机或集群Docker主机及容器的资源和性能指标。
• Kubernetes/Mesos集群：启用集成后监控集群节点、Pod、服务及事件。
• 云环境监控：配合EC2 IAM角色采集AWS资源标签，监控云主机和容器。
• 微服务架构：通过DogStatsD和APM追踪，收集分布式应用的指标和调用链数据。
• 日志集中管理：配置日志转发至Docker，结合Datadog Logs平台实现日志聚合分析。

快速开始

默认启动命令

通过以下命令快速启动Agent容器，需替换{your_api_key_here}为实际Datadog API密钥：

bash
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} \
  -e SD_BACKEND=docker \
  -e NON_LOCAL_TRAFFIC=false \
  datadog/docker-dd-agent:latest

Amazon Linux <2 适配

在Amazon Linux版本低于2的系统上，使用以下命令（cgroup路径不同）：

bash
docker run -d --name dd-agent \
  -v /var/run/docker.sock:/var/run/docker.sock:ro \
  -v /proc/:/host/proc/:ro \
  -v /cgroup/:/host/sys/fs/cgroup:ro \
  -e API_KEY={your_api_key_here} \
  -e SD_BACKEND=docker \
  -e NON_LOCAL_TRAFFIC=false \
  datadog/docker-dd-agent:latest

配置说明

主机名配置

默认情况下，Agent容器使用主机docker info命令返回的Name字段作为主机名。如需自定义，可通过以下方式：

• 环境变量：设置DD_HOSTNAME，例如-e DD_HOSTNAME=my-custom-host，Agent会自动将其写入/etc/dd-agent/datadog.conf。
• 配置文件：手动挂载datadog.conf并修改hostname字段（不推荐，优先使用环境变量）。

cgroups配置

为确保Docker监控检查正常运行，主机需启用cgroup内存管理。例如在Debian Jessie及以上系统中，需在启动参数中添加cgroup_enable=memory swapaccount=1，步骤如下：

1. 编辑/etc/default/grub，修改GRUB_CMDLINE_LINUX添加参数。
2. 执行update-grub更新配置。
3. 重启主机使配置生效。

自动发现（Autodiscovery）

快速启动命令中通过SD_BACKEND=docker启用自动发现，Agent会基于默认模板自动对容器执行监控检查。

• 禁用自动发现：启动时省略SD_BACKEND环境变量。
• 自定义配置：通过SD_CONFIG_BACKEND指定配置后端（如etcd、consul、zk），结合SD_BACKEND_HOST、SD_BACKEND_PORT等参数配置服务发现源。

详细说明参见Datadog自动发现文档。

环境变量配置

通过环境变量可配置Agent核心参数，常用变量如下：

启用集成

Kubernetes集成

• 启用基础监控：设置KUBERNETES=yes。
• 采集事件：单集群仅在一个Agent上设置KUBERNETES_COLLECT_EVENTS=true，或通过KUBERNETES_LEADER_CANDIDATE=true启用leader选举。
• 命名空间过滤：通过KUBERNETES_NAMESPACE_NAME_REGEX指定需监控的命名空间（正则表达式）。

Mesos集成

• Mesos Master监控：设置MESOS_MASTER=yes。
• Mesos Slave监控：设置MESOS_SLAVE=yes。
• Marathon监控：设置MARATHON_URL=http://leader.mesos:8080。

JMX镜像

如需监控JVM应用（如Java服务），需使用JMX镜像，标签格式为{版本}-jmx，例如：

bash
docker run -d --name dd-agent-jmx \
  -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-jmx

DogStatsD配置

独立DogStatsD镜像

仅需DogStatsD指标收集时，使用{版本}-dogstatsd标签镜像，无需挂载主机卷：

bash
docker run -d --name dogstatsd \
  -e API_KEY={your_api_key_here} \
  -p 8125:8125/udp \
  datadog/docker-dd-agent:latest-dogstatsd

• 启用APM：添加-e DD_APM_ENABLED=true开启8126端口追踪。
• 安全注意：独立镜像以非root用户运行，适合OpenShift等平台。

主机访问DogStatsD

• 开放至所有IP：启动时添加-p 8125:8125/udp。
• 仅本地访问：使用-p 127.0.0.1:8125:8125/udp。

跨容器访问DogStatsD

通过Docker主机IP

容器内通过主机默认路由IP（如172.17.42.1）访问，可通过ip route命令获取主机IP。

通过Docker Links（Legacy）

启动客户端容器时添加--link dd-agent:dogstatsd，通过环境变量DOGSTATSD_PORT_8125_UDP_ADDR和DOGSTATSD_PORT_8125_UDP_PORT访问。

应用性能监控（APM）

启用APM

非Alpine镜像通过DD_APM_ENABLED=true启用APM，开放8126端口接收追踪数据：

bash
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} \
  -e DD_APM_ENABLED=true \
  -p 8126:8126/tcp \
  datadog/docker-dd-agent:latest

跨容器访问APM

通过Docker Links

客户端容器添加--link dd-agent:dd-agent，通过环境变量DD_AGENT_PORT_8126_TCP_ADDR和DD_AGENT_PORT_8126_TCP_PORT配置追踪客户端。

Python示例：

python
import os
from ddtrace import tracer
tracer.configure(
    hostname=os.environ["DD_AGENT_PORT_8126_TCP_ADDR"],
    port=os.environ["DD_AGENT_PORT_8126_TCP_PORT"]
)

构建自定义镜像

如需预配置Agent（如添加监控检查模板），可基于官方镜像构建自定义镜像：

1. 创建Dockerfile：

   dockerfile
   FROM datadog/docker-dd-agent:latest
   # 添加MySQL监控配置
   ADD conf.d/mysql.yaml /etc/dd-agent/conf.d/mysql.yaml
   

2. 构建镜像：

   bash
   docker build -t my-custom-dd-agent .
   

3. 启动自定义镜像：

   bash
   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} \
     my-custom-dd-agent
   

Alpine基础镜像

Alpine版本镜像体积更小（约为Debian版的40%），标签格式为{版本}-alpine，使用方式与默认镜像类似：

bash
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

注意事项：

• 配置文件路径为/opt/datadog-agent/agent/conf.d/（而非/etc/dd-agent/conf.d/）。
• 不支持JMX和APM追踪。
• 查看Agent信息命令：docker exec dd-agent /opt/datadog-agent/bin/agent info。

版本控制模式

镜像版本遵循X.Y.Z格式，其中：

• X：Docker镜像主版本号
• Y：Docker镜像次版本号
• Z：Datadog Agent版本号（三位数，如Agent 5.5.0对应550）

示例：10.0.550表示Docker镜像主版本10、次版本0，包含Agent 5.5.0。

Agent状态与信息

查看Agent状态

• Debian镜像：

  bash
  docker exec dd-agent service datadog-agent info
  

• Alpine镜像：

  bash
  docker exec dd-agent /opt/datadog-agent/bin/agent info
  

日志管理

复制日志到主机

bash
docker cp dd-agent:/var/log/datadog /tmp/datadog-logs  # Debian
# 或
docker cp dd-agent:/opt/datadog-agent/logs /tmp/datadog-logs  # Alpine

查看容器内日志

• Debian镜像：

  bash
  docker exec -it dd-agent bash
  tail -f /var/log/datadog/collector.log  # 主日志
  

• Alpine镜像：

  bash
  docker exec -it dd-agent ash
  tail -f /opt/datadog-agent/logs/dogstatsd.log  # DogStatsD日志
  

限制

• 磁盘指标：仅能监控挂载至Agent容器的卷，未挂载的主机分区无法采集。
• 网络与进程指标：受Docker隔离限制，部分主机网络和进程列表指标可能不完整。
• Alpine兼容性：部分功能（如JMX、APM）不支持Alpine版本。

反馈与贡献

如发现镜像缺陷或功能问题，可通过https://github.com/DataDog/docker-dd-agent/issues%E6%8F%90%E4%BA%A4%E5%8F%8D%E9%A6%88%E3%80%82Agent%E6%A0%B8%E5%BF%83%E5%8A%9F%E8%83%BD%E9%97%AE%E9%A2%98%E8%AF%B7%E5%8F%82%E8%80%83Datadog%E5%AE%98%E6%96%B9%E6%96%87%E6%A1%A3%E6%88%96https://github.com/DataDog/dd-agent/wiki%E3%80%82