name: datadog-analysis description: Datadog日志和指标分析。用于查询Datadog日志、指标或APM数据。提供脚本和查询语法参考。 allowed-tools: Bash(python *)

Datadog分析

认证

重要：凭据由代理层自动注入。不要在环境变量中检查DATADOG_API_KEY或DATADOG_APP_KEY——它们对您不可见。直接运行脚本；认证是透明的。

您可以检查的配置环境变量（非机密）：

DATADOG_SITE - Datadog站点（例如，us5.datadoghq.com，datadoghq.eu）

强制：统计优先调查

永远不要直接转储原始日志。 始终遵循此模式：

STATISTICS → SAMPLE → PATTERNS → CORRELATE

统计优先 - 在采样前了解数量、错误率和顶部模式
战略采样 - 基于统计选择合适的策略
模式提取 - 聚类相似错误以找到根本原因
上下文关联 - 调查异常时间戳周围

可用脚本

所有脚本都在.claude/skills/observability-datadog/scripts/中

主要调查脚本

get_statistics.py - 始终从这里开始

包含模式提取的全面统计。

python .claude/skills/observability-datadog/scripts/get_statistics.py [--service SERVICE] [--time-range MINUTES]

# 示例：
python .claude/skills/observability-datadog/scripts/get_statistics.py --time-range 60
python .claude/skills/observability-datadog/scripts/get_statistics.py --service payment

输出包括：

总数、错误数、错误率百分比
状态分布（信息、警告、错误）
按日志量排名的顶部服务
顶部错误模式（快速分类的关键）
可操作建议

sample_logs.py - 战略采样

基于统计选择合适的采样策略。

python .claude/skills/observability-datadog/scripts/sample_logs.py --strategy STRATEGY [--service SERVICE] [--limit N]

# 策略：
#   errors_only   - 仅错误日志（事件默认）
#   warnings_up   - 警告和错误日志
#   around_time   - 围绕特定时间戳的日志
#   all           - 所有日志级别

# 示例：
python .claude/skills/observability-datadog/scripts/sample_logs.py --strategy errors_only --service payment
python .claude/skills/observability-datadog/scripts/sample_logs.py --strategy around_time --timestamp "2026-01-27T05:00:00Z" --window 5

Datadog查询语言（DQL）

基本过滤器

# 服务过滤器
service:payment

# 状态过滤器
status:error
status:warn

# 主机过滤器
host:web-server-01

# 使用AND（空格）或OR组合
service:payment status:error
service:payment OR service:checkout

方面过滤器

# 标签过滤器
env:production
version:1.2.3

# 属性过滤器
@http.status_code:>=500
@duration:>1000

# 通配符
service:payment-*

时间范围

# 相对
@timestamp:[now-1h TO now]

# 绝对
@timestamp:[2026-01-27T00:00:00Z TO 2026-01-27T12:00:00Z]

常见模式

# 过去一小时的所有错误
status:error

# 特定服务的错误
service:api-gateway status:error

# 慢请求（>1秒）
@duration:>1000000

# HTTP 5xx错误
@http.status_code:>=500

# 异常
*exception* OR *error* OR *failed*

调查工作流程

标准事件调查

┌─────────────────────────────────────────────────────────────┐
│ 1. 统计优先（强制）                                          │
│    python get_statistics.py --service <service>              │
│    → 了解数量、错误率、顶部模式                             │
└─────────────────────────────────────────────────────────────┘
                             │
                             ▼
                     高错误率？
               ┌─────────────┴─────────────┐
               │                           │
       是 (>5%)                            否
               │                           │
               ▼                           ▼
┌─────────────────────────────┐  ┌───────────────────────────────────────────┐
│ 2. 快速路径                  │  │ 2. 针对性调查                            │
│    直接采样错误             │  │    按特定条件过滤                        │
│    python sample_logs.py    │  │    python sample_logs.py --strategy all   │
│    --strategy errors_only   │  │    → 寻找异常                            │
└─────────────────────────────┘  └───────────────────────────────────────────┘

快速命令参考

目标	命令
开始调查	`get_statistics.py --service X`
仅采样错误	`sample_logs.py --strategy errors_only --service X`
调查峰值	`sample_logs.py --strategy around_time --timestamp T`
所有日志	`sample_logs.py --strategy all --service X --limit 20`

指标查询语法

基本结构

aggregation:metric_name{tag_filters}

聚合

avg:   - 跨系列的平均值
sum:   - 跨系列的总和
min:   - 最小值
max:   - 最大值
p50:   - 第50百分位数（APM）
p95:   - 第95百分位数（APM）
p99:   - 第99百分位数（APM）

常见指标

# 系统
avg:system.cpu.user{service:X}
avg:system.mem.used{service:X}

# APM（跟踪）
sum:trace.http.request.hits{service:X}.as_rate()
sum:trace.http.request.errors{service:X}.as_rate()
p95:trace.http.request.duration{service:X}

要避免的反模式

❌ 永远不要跳过统计 - get_statistics.py 是强制的第一步
❌ 无边界查询 - 始终指定时间范围和限制
❌ 获取所有日志 - 使用采样策略，而不是无边界搜索
❌ 忽略错误率 - 高错误率意味着立即调查
❌ 缺少服务过滤器 - 对于多服务应用，始终按服务过滤