a6-plugin-datadog

概览

datadog 插件会通过 DogStatsD 将 Apache APISIX 的请求指标推送到 Datadog Agent， DogStatsD 使用 UDP 协议，报告请求数、延迟、带宽以及上游耗时， 并使用自动标签标识路由、服务、消费者和状态码等信息。

适用场景

• 使用 Datadog APM 和仪表板监控 Apache APISIX。
• 按路由跟踪请求速率、延迟和错误率。
• 为业务级指标添加自定义标签。
• 集成现有的 Datadog 基础设施。

插件配置参考（路由/服务）

字段	类型	是否必填	默认值	说明
prefer_name	boolean	否	true	在标签中使用路由/服务名称，而不是 ID
include_path	boolean	否	false	在标签中包含 HTTP 路径模式
include_method	boolean	否	false	在标签中包含 HTTP 方法
constant_tags	array	否	[]	为此路由设置的静态标签（例如 ["env:prod"]）
batch_max_size	integer	否	1000	每个批次的最大条目数
inactive_timeout	integer	否	5	批次刷新前等待的秒数
buffer_duration	integer	否	60	最早条目的最大保留时间
max_retry_count	integer	否	0	重试次数

插件元数据（全局配置）

为所有路由设置 DogStatsD 服务器地址：

curl "$(a6 context current -o json | jq -r .server)/apisix/admin/plugin_metadata/datadog" \
  -X PUT \
  -H "X-API-KEY: $(a6 context current -o json | jq -r .api_key)" \
  -d '{
    "host": "127.0.0.1",
    "port": 8125,
    "namespace": "apisix",
    "constant_tags": ["source:apisix"]
  }'

字段	类型	默认值	说明
host	string	"127.0.0.1"	DogStatsD 服务器主机
port	integer	8125	DogStatsD 服务器端口
namespace	string	"apisix"	指标名称前缀
constant_tags	array	["source:apisix"]	应用于所有指标的全局标签

生成的指标

指标	类型	说明
{namespace}.request.counter	counter	请求数
{namespace}.request.latency	histogram	请求总延迟（毫秒）
{namespace}.upstream.latency	histogram	上游响应时间（毫秒）
{namespace}.apisix.latency	histogram	Apache APISIX处理时间（毫秒）
{namespace}.ingress.size	timer	请求体大小（字节）
{namespace}.egress.size	timer	响应体大小（字节）

默认命名空间为 apisix，因此指标名称类似 apisix.request.counter。

自动标签

标签	始终存在	说明
route_name	是	路由 ID 或名称
service_name	路由包含服务时	服务 ID 或名称
consumer	请求经过身份认证时	消费者用户名
balancer_ip	是	处理请求的上游 IP
response_status	是	HTTP 状态码（例如 200）
response_status_class	是	状态码类别（例如 2xx、5xx）
scheme	是	http, https, grpc, grpcs
path	如果 include_path: true	HTTP 路径模式
method	如果 include_method: true	HTTP 方法

分步指南：将指标发送到 Datadog

1. 配置插件元数据（DogStatsD 地址）

curl "$(a6 context current -o json | jq -r .server)/apisix/admin/plugin_metadata/datadog" \
  -X PUT \
  -H "X-API-KEY: $(a6 context current -o json | jq -r .api_key)" \
  -d '{
    "host": "127.0.0.1",
    "port": 8125,
    "namespace": "apisix",
    "constant_tags": ["source:apisix", "env:production"]
  }'

2. 在路由上启用

a6 route create -f - <<'EOF'
{
  "id": "monitored-api",
  "name": "api-v1",
  "uri": "/api/v1/*",
  "plugins": {
    "datadog": {
      "prefer_name": true,
      "include_path": true,
      "include_method": true
    }
  },
  "upstream": {
    "type": "roundrobin",
    "nodes": {
      "backend:8080": 1
    }
  }
}
EOF

3. 在 Datadog 中验证

打开 Datadog → Metrics Explorer → 搜索 apisix.request.counter。

常见模式

为每个路由设置自定义常量标签

{
  "plugins": {
    "datadog": {
      "prefer_name": true,
      "constant_tags": [
        "team:platform",
        "api_version:v2",
        "tier:premium"
      ]
    }
  }
}

远程 Datadog Agent

curl "$(a6 context current -o json | jq -r .server)/apisix/admin/plugin_metadata/datadog" \
  -X PUT \
  -H "X-API-KEY: $(a6 context current -o json | jq -r .api_key)" \
  -d '{
    "host": "datadog-agent.internal",
    "port": 8125,
    "namespace": "mycompany",
    "constant_tags": ["source:apisix", "datacenter:us-east-1"]
  }'

使用 Docker Compose 部署 Datadog Agent

services:
  apisix:
    image: apache/apisix:3.15.0-debian
    depends_on:
      - datadog-agent

  datadog-agent:
    image: datadog/agent:latest
    environment:
      - DD_API_KEY=${DD_API_KEY}
      - DD_SITE=datadoghq.com
      - DD_DOGSTATSD_NON_LOCAL_TRAFFIC=true
    ports:
      - "8125:8125/udp"

Datadog 控制台查询

# Request rate by route
sum:apisix.request.counter{*} by {route_name}.as_count()

# P95 latency
percentile:apisix.request.latency{*} by {route_name}, p:95

# Error rate
sum:apisix.request.counter{response_status_class:5xx}.as_count()

# Upstream health by IP
avg:apisix.upstream.latency{*} by {balancer_ip}

配置同步示例

version: "1"
routes:
  - id: monitored-api
    name: api-v1
    uri: /api/v1/*
    plugins:
      datadog:
        prefer_name: true
        include_path: true
        include_method: true
        constant_tags:
          - "team:platform"
    upstream_id: my-upstream

故障排查

现象	原因	解决方法
Datadog 中没有指标	Agent 未接收 UDP 数据	检查插件元数据中的 host/port，并验证 Agent 配置
缺少消费者标签	路由未启用身份认证	该标签仅在经过身份认证的请求中出现
指标命名空间错误	默认值为 apisix	在插件元数据中修改 namespace
Datadog 拒绝标签	标签格式无效	标签必须以字母开头，不能以 : 结尾
指标延迟	inactive_timeout 设置过大	调低批次相关设置以加快传输

---

本文根据 api7/a6 仓库中的 a6-plugin-datadog/SKILL.md 生成。可在 AI Agent Skills 页面浏览全部 Skill。