跳到主要内容
版本：3.10.x

API7 网关 AI Agent Skill：datadog 插件

概览​

datadog 插件通过 DogStatsD 协议（UDP）将 API7 企业版的每请求指标推送到 Datadog Agent。它会报告请求数、延迟、带宽和上游耗时，并自动添加路由、服务、消费者、状态码等标签。

适用场景​

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

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

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

插件元数据（全局配置）​

为网关组中的所有路由设置 DogStatsD 服务器地址：

# 从上下文获取当前令牌和服务器地址
TOKEN=$(a7 context current -o json | jq -r .token)
SERVER=$(a7 context current -o json | jq -r .server)
GROUP="default"

curl "${SERVER}/apisix/admin/plugin_metadata/datadog?gateway_group=${GROUP}" \
  -X PUT \
  -H "X-API-TOKEN: ${TOKEN}" \
  -d '{
    "host": "127.0.0.1",
    "port": 8125,
    "namespace": "api7ee",
    "constant_tags": ["source:api7-ee"]
  }'
字段类型默认值说明
hoststring"127.0.0.1"DogStatsD 服务器主机
portinteger8125DogStatsD 服务器端口
namespacestring"api7ee"指标名称前缀
constant_tagsarray["source:api7-ee"]应用于所有指标的全局标签

生成的指标​

指标类型说明
{namespace}.request.countercounter请求数
{namespace}.request.latencyhistogram请求总延迟（毫秒）
{namespace}.upstream.latencyhistogram上游响应时间（毫秒）
{namespace}.apisix.latencyhistogramAPI7 企业版处理时间（毫秒）
{namespace}.ingress.sizetimer请求体大小（字节）
{namespace}.egress.sizetimer响应体大小（字节）

默认命名空间为 api7ee，因此指标名称类似 api7ee.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: trueHTTP 路径模式
method如果 include_method: trueHTTP 方法

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

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

a7 plugin-metadata create datadog --gateway-group default -f - <<'EOF'
{
  "host": "127.0.0.1",
  "port": 8125,
  "namespace": "api7ee",
  "constant_tags": ["source:api7-ee", "env:production"]
}
EOF

2. 在路由上启用​

a7 route create --gateway-group default -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": [{"host": "backend", "port": 8080, "weight": 1}]
  }
}
EOF

3. 在 Datadog 中验证​

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

常见模式​

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

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

远程 Datadog Agent​

a7 plugin-metadata update datadog --gateway-group default -f - <<'EOF'
{
  "host": "datadog-agent.internal",
  "port": 8125,
  "namespace": "mycompany",
  "constant_tags": ["source:api7-ee", "datacenter:us-east-1"]
}
EOF

Datadog 看板查询​

# 按路由统计请求速率
sum:api7ee.request.counter{*} by {route_name}.as_count()

# P95 延迟
percentile:api7ee.request.latency{*} by {route_name}, p:95

# 错误率
sum:api7ee.request.counter{response_status_class:5xx}.as_count()

# 按 IP 统计上游健康状态
avg:api7ee.upstream.latency{*} by {balancer_ip}

配置同步示例​

version: "1"
gateway_group: default
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:
      type: roundrobin
      nodes:
        - host: backend
          port: 8080
          weight: 1

故障排查​

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

本页面由 api7/a7 仓库中的 a7-plugin-datadog/SKILL.md 生成。你可以在 AI Agent Skills 页面查看所有技能。