DogStatsD 独立镜像技术文档

一、镜像概述

1.1 主要用途

DogStatsD 独立镜像是基于 StatsD 协议的轻量级指标聚合器，专为自定义指标收集设计。作为 Datadog 生态的一部分，它能够独立部署（无需完整 Datadog Agent），负责接收、聚合应用程序发送的自定义指标，并将其高效转发至 Datadog 平台，适用于容器化、微服务等场景的指标集中管理。

二、核心功能与特性

2.1 核心功能

StatsD 协议支持：兼容标准 StatsD 指标类型（计数 count、计量 gauge、定时 timing、直方图 histogram 等），支持自定义指标上报。
独立部署能力：无需依赖完整 Datadog Agent，降低资源占用，简化部署流程。
高效指标聚合：本地聚合指标（如计算平均值、百分位），减少网络传输量，提升数据处理效率。
Datadog 集成：原生支持与 Datadog 平台对接，自动处理指标格式转换与上报。

2.2 特性

轻量级设计：基于 Alpine 基础镜像，体积小、启动快，适合资源受限环境。
灵活配置：通过环境变量自定义端口、标签、目标 Datadog 站点等参数。
版本兼容：6.x 与 7.x 版本间无破坏性变更，版本号同步 Datadog Agent 主版本。

三、使用场景与适用范围

3.1 典型使用场景

微服务架构指标收集：在分布式系统中，集中接收各服务实例发送的自定义业务指标（如订单量、接口延迟）。
资源受限环境：相比完整 Datadog Agent，减少 CPU/内存占用，适合边缘节点、轻量容器等场景。
自定义应用监控：为非标准监控场景（如业务指标、自定义性能指标）提供标准化数据入口。
容器/K8s 环境集成：与 Docker、Kubernetes 等容器编排平台无缝集成，通过 DaemonSet 或独立 Pod 部署，覆盖集群内所有应用指标。

四、使用方法

4.1 镜像标签说明

标签格式	说明
`latest`	最新稳定版本
`7` / `7.X.X`	Agent 7 系列版本（当前主版本）
`6.X.X`	历史 Agent 6 系列版本（兼容无破坏性变更）

注意：6.x 与 7.x 版本间无功能破坏性变更，版本号仅同步 Datadog Agent 主版本策略。

4.2 部署示例

4.2.1 Docker 命令部署

通过 docker run 快速启动容器，需映射 UDP 端口（默认 8125）并配置必要环境变量：

bash
docker run -d \
  --name dogstatsd \
  -p 8125:8125/udp \  # DogStatsD 默认 UDP 端口
  -e DD_API_KEY=<your_datadog_api_key> \  # 替换为实际 API Key
  -e DD_SITE=datadoghq.com \  # 可选，指定 Datadog 站点（如欧洲区为 datadoghq.eu）
  -e DD_TAGS="env:prod,app:my-service" \  # 可选，全局标签（键值对格式，逗号分隔）
  gcr.io/datadoghq/dogstatsd:latest  # 或指定标签如 7

4.2.2 Docker Compose 部署

创建 docker-compose.yml 配置文件：

yaml
version: '3'
services:
  dogstatsd:
    image: gcr.io/datadoghq/dogstatsd:7  # 指定 7 系列版本
    container_name: dogstatsd
    ports:
      - "8125:8125/udp"  # 暴露 UDP 端口接收指标
    environment:
      - DD_API_KEY=<your_datadog_api_key>  # 必填，Datadog API Key
      - DD_SITE=datadoghq.com  # 可选，默认 datadoghq.com
      - DD_TAGS="env:prod,team:backend"  # 可选，全局标签
      - DD_DOGSTATSD_PORT=8125  # 可选，自定义监听端口（默认 8125）
    restart: unless-stopped  # 确保服务持续运行

启动命令：docker-compose up -d

4.3 配置参数（环境变量）

环境变量	描述	默认值	必填
`DD_API_KEY`	Datadog API 密钥，用于认证并将指标发送至 Datadog 平台	无	是
`DD_SITE`	Datadog 站点域名，根据部署地区选择（如美国区 `datadoghq.com`、欧洲区 `datadoghq.eu`）	`datadoghq.com`	否
`DD_TAGS`	全局标签，格式为 `key:value`，多标签用逗号分隔（如 `env:prod,app:api`），将附加到所有指标	无	否
`DD_DOGSTATSD_PORT`	DogStatsD 监听端口（UDP）	`8125`	否
`DD_DOGSTATSD_NON_LOCAL_TRAFFIC`	是否允许非本地流量（如跨容器/主机指标发送），设为 `true` 开启	`false`	否
`DD_AGGREGATOR_BUCKETS`	指标聚合时间窗口（秒），控制指标本地缓存与聚合周期	`10`	否