datadog/dev-dd-agent

Datadog Agent 5.x Docker镜像文档

镜像概述和主要用途

本仓库用于构建Datadog Agent 5.x容器的基础镜像。用户需使用构建后的镜像配置并运行Agent。若需Datadog Agent 6.x Dockerfile，可参考https://github.com/DataDog/datadog-agent/tree/master/Dockerfiles%E3%80%82

核心功能和特性

• 容器化监控：通过挂载主机资源（/proc、/sys/fs/cgroup、Docker socket）实现对主机和容器的监控。
• 自动发现（Autodiscovery）：支持基于Docker的服务自动发现，自动对指定容器运行检查。
• 多环境适配：支持标准Linux系统、Amazon Linux（<2版本）及Alpine Linux。
• 可扩展配置：通过环境变量、配置文件挂载或自定义构建镜像实现灵活配置。
• DogStatsD集成：内置DogStatsD服务器，支持 metrics 收集；提供独立DogStatsD镜像选项。
• APM追踪：支持启用trace-agent，接收应用性能追踪数据（非Alpine版本）。
• 标签管理：支持通过环境变量或EC2实例标签配置主机标签。

使用场景和适用范围

• 容器化环境监控：适用于Docker、Kubernetes等容器环境，监控主机及容器资源使用率、性能指标。
• 动态服务监控：通过自动发现功能，监控动态扩缩容的容器服务。
• 多平台部署：支持Debian和Alpine基础镜像，满足不同体积和安全需求。
• 代理配置：支持通过环境变量配置HTTP代理，适应内网环境。

详细使用方法和配置说明

快速启动

默认镜像可直接使用，仅需通过环境变量设置API_KEY。

标准系统启动命令

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）启动命令

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

配置

主机名（Hostname）

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

• 直接修改/etc/dd-agent/datadog.conf中的hostname字段。
• 通过环境变量DD_HOSTNAME设置（推荐，见下文环境变量说明）。

控制组（CGroups）

为确保Docker检查正常运行，主机需启用cgroup内存管理，配置方法参考Debian Wiki。
例如，Debian Jessie及以上系统需在启动参数中添加cgroup_enable=memory swapaccount=1，否则Agent无法识别系统。修改启动参数的方法可参考此线程。

自动发现（Autodiscovery）

快速启动命令中已启用自动发现（auto-conf模式），Agent会自动对默认检查模板中列出的容器镜像运行检查。

• 详细说明参考自动发现指南。
• 如需禁用，启动容器时省略SD_BACKEND环境变量。

环境变量

部分配置参数可通过环境变量调整，具体如下：

启用集成

通过环境变量启用

• Kubernetes监控：设KUBERNETES=yes启用Kubernetes检查。

  • 收集事件：单集群仅需一个Agent设KUBERNETES_COLLECT_EVENTS=true；或启用Leader选举（KUBERNETES_LEADER_CANDIDATE=true）并通过KUBERNETES_LEADER_LEASE_DURATION设置租期（秒）。
  • 命名空间过滤：默认仅收集default命名空间，通过KUBERNETES_NAMESPACE_NAME_REGEX设置正则表达式匹配目标命名空间。
  • 服务标签：默认查询apiserver事件和服务端点以收集kube_service标签，设KUBERNETES_COLLECT_SERVICE_TAGS=false禁用。
  • kubelet地址：默认使用容器默认路由，可通过KUBERNETES_KUBELET_HOST覆盖。

• Mesos监控：设MESOS_MASTER=yes启用Mesos Master检查；MESOS_SLAVE=yes启用Mesos Slave检查。

• Marathon监控：设MARATHON_URL=http://leader.mesos:8080启用Marathon检查。

通过自动发现启用

适用于Kubernetes、ECS、Docker Swarm等动态环境，详细说明参考自动发现指南。

通过配置文件挂载启用

1. 主机创建配置目录并编写YAML配置文件：

   bash
   mkdir /opt/dd-agent-conf.d
   touch /opt/dd-agent-conf.d/nginx.yaml  # 示例：Nginx检查配置
   

2. 启动容器时挂载目录：

   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 \
     -v /opt/dd-agent-conf.d:/conf.d:ro \  # 挂载配置目录
     -e API_KEY={your_api_key_here} \
     datadog/docker-dd-agent
   

   容器启动时会自动将/conf.d下的.yaml文件复制至/etc/dd-agent/conf.d/（Alpine版本为/opt/datadog-agent/agent/conf.d/）。

JMX镜像

如需运行基于JMX的检查，需使用JMX镜像（标签格式usual_tag-jmx），例如datadog/docker-dd-agent:latest-jmx、datadog/docker-dd-agent:11.0.5150-jmx。此类镜像在基础镜像上添加了JVM，支持jmxfetch运行。

DogStatsD

独立DogStatsD镜像

默认镜像（如latest）同时运行DogStatsD服务器和Agent收集器。如需仅运行DogStatsD，使用独立镜像（标签格式usual_tag-dogstatsd），例如datadog/docker-dd-agent:latest-dogstatsd、datadog/docker-dd-agent:11.0.5141-dogstatsd-alpine。

• 特点：以非root用户运行，无需挂载主机/proc、/sys/fs或Docker socket。
• 限制：指标不包含datadog.conf中的全局标签（收集器未运行）。
• 可选启用trace-agent：添加-e DD_APM_ENABLED=true接收APM追踪数据。

从主机访问DogStatsD

• 开放至所有网络：添加-p 8125:8125/udp至启动命令。
• 仅主机访问：使用-p 127.0.0.1:8125:8125/udp。

禁用DogStatsD

设USE_DOGSTATSD=no禁用DogStatsD。

从其他容器访问DogStatsD

通过Docker主机IP

容器内通过默认路由IP（如ip route查询）访问主机上的DogStatsD，例如配置客户端连接172.17.42.1:8125。

通过Docker链接（Legacy）

启动客户端容器时添加--link dogstatsd:dogstatsd，环境变量DOGSTATSD_PORT_8125_UDP_ADDR和DOGSTATSD_PORT_8125_UDP_PORT自动注入，供客户端使用。

Tracing + APM

添加-e DD_APM_ENABLED=true启用trace-agent（非Alpine镜像支持），接收APM追踪数据。

从主机访问APM

• 开放至所有网络：添加-p 8126:8126/tcp至启动命令。
• 仅主机访问：使用-p 127.0.0.1:8126:8126/tcp。

示例启动命令：

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

从其他容器访问APM

通过Docker链接

启动客户端容器时添加--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"]
)

通过Docker主机IP

客户端配置追踪器连接主机默认路由IP（如172.17.0.1）：

python
from ddtrace import tracer; tracer.configure(hostname="172.17.0.1", port=8126)

构建自定义镜像

如需在镜像中预配置Agent，可基于官方镜像构建：

1. 创建Dockerfile：

   dockerfile
   FROM datadog/docker-dd-agent
   # 示例：添加MySQL检查配置
   ADD conf.d/mysql.yaml /etc/dd-agent/conf.d/mysql.yaml
   

2. 构建镜像：

   bash
   docker build -t dd-agent-image .
   

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} \
     dd-agent-image
   

Alpine基础镜像

Agent 5.7+提供Alpine Linux基础镜像（标签格式usual_tag-alpine），体积约为Debian版本的60%，安全性更高。

• 兼容性：支持自动发现、集成启用等功能，但不支持JMX和APM（trace-agent未包含）。
• 示例启动命令：

  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/）。
  • 基于源码安装Agent，命令需适配（如查看信息：/opt/datadog-agent/bin/agent info）。

版本控制模式

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

• X：Docker镜像主版本
• Y：Docker镜像次版本
• Z：Agent版本

示例：首个包含Datadog Agent 5.5.0的Docker镜像版本为10.0.550。

查看Agent状态

• Debian镜像：

  bash
  docker exec dd-agent service datadog-agent info
  

• Alpine镜像：

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

注：docker exec命令需Docker 1.3及以上版本支持。

日志管理

复制容器日志到主机

bash
docker cp dd-agent:/var/log/datadog /tmp/log-datadog-agent

查看Supervisor日志

• Debian镜像：

  bash
  docker exec -it dd-agent bash
  tail -f /var/log/datadog/dogstatsd.log
  

• Alpine镜像：

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

限制

• 未挂载至Agent容器的卷无法收集磁盘指标。
• 因Docker容器隔离性，部分主机指标可能缺失或不准确，包括：网络指标、进程列表。
• 部分集成功能可能不完整，详细参考官方文档或https://github.com/DataDog/dd-agent/wiki%E3%80%82

贡献

如发现容器相关问题，可提交https://github.com/DataDog/docker-dd-agent/issues%EF%BC%9BAgent%E6%9C%AC%E8%BA%AB%E9%97%AE%E9%A2%98%E8%AF%B7%E5%8F%82%E8%80%83%E5%85%B6%E6%96%87%E6%A1%A3%E6%88%96https://github.com/DataDog/dd-agent/wiki%E3%80%82<|FCResponseEnd|># Datadog Agent 5.x Docker镜像文档

镜像概述和主要用途

本镜像用于构建Datadog