dd-monitors

Datadog 监控器

创建、管理和维护用于告警的监控器。

前置条件

需要确保 pup 位于路径中。请参阅 设置 Pup。

命令执行顺序（节省令牌）

对于范围限定的命令，请按以下顺序执行：

1. 首先检查上下文（先前的输出、对话内容、已保存的值）。
2. 如果缺少必需的值，先运行发现命令。
3. 如果仍有歧义，请让用户确认。
4. 然后运行目标命令。
5. 避免运行可能失败的推测性命令。

快速入门

pup auth login

常见操作

列出监控器

pup monitors list
pup monitors list --tags "team:platform"

获取监控器

pup monitors get <id>

创建监控器

pup monitors create --file monitor.json

静默告警（停机时间）

# No pup monitors mute/unmute commands.
# Use downtime payloads to silence monitor notifications.
pup downtime create --file downtime.json
pup downtime cancel <downtime_id>

创建监控器的最佳实践

1. 避免告警疲劳

规则	原因
避免告警抖动	使用 last_Xm，而不是 last_1m
设置有意义的阈值	根据 SLO 设置，而非猜测
确保告警可执行	如果无需采取行动，就不要发出告警
附上运行手册	在消息中添加 @runbook-url

# WRONG - will flap constantly
query = "avg(last_1m):avg:system.cpu.user{*} > 50"  # ❌ Too sensitive

# CORRECT - stable alerting
query = "avg(last_5m):avg:system.cpu.user{env:prod} by {host} > 80"  # ✅ Reasonable window

2. 正确设置范围

# WRONG - alerts on everything
query = "avg(last_5m):avg:system.cpu.user{*} > 80"  # ❌ No scope

# CORRECT - scoped to what matters
query = "avg(last_5m):avg:system.cpu.user{env:prod,service:api} by {host} > 80"  # ✅

3. 设置恢复阈值

monitor = {
    "query": "avg(last_5m):avg:system.cpu.user{env:prod} > 80",
    "options": {
        "thresholds": {
            "critical": 80,
            "critical_recovery": 70,  # ✅ Prevents flapping
            "warning": 60,
            "warning_recovery": 50
        }
    }
}

4. 在消息中加入上下文

message = """
## High CPU Alert

Host: {{host.name}}
Current Value: {{value}}
Threshold: {{threshold}}

### Runbook
1. Check top processes: `ssh {{host.name}} 'top -bn1 | head -20'`
2. Check recent deploys
3. Scale if needed

@slack-ops @pagerduty-oncall
"""

切勿直接删除监控器

请使用安全删除工作流（与仪表板相同）：

def safe_mark_monitor_for_deletion(monitor_id: str, client) -> bool:
    """Mark monitor instead of deleting."""
    monitor = client.get_monitor(monitor_id)
    name = monitor.get("name", "")
    
    if "[MARKED FOR DELETION]" in name:
        print(f"Already marked: {name}")
        return False
    
    new_name = f"[MARKED FOR DELETION] {name}"
    client.update_monitor(monitor_id, {"name": new_name})
    print(f"✓ Marked: {new_name}")
    return True

监控器类型

类型	使用场景
metric alert	CPU、内存、自定义指标
query alert	复杂指标查询
service check	Agent 检查状态
event alert	事件流模式
log alert	日志模式匹配
composite	合并多个监控器
apm	APM 指标

审计监控器

# Find monitors without owners
pup monitors list | jq '.[] | select(.tags | contains(["team:"]) | not) | {id, name}'

# Find noisy monitors (high alert count)
pup monitors list | jq 'sort_by(.overall_state_modified) | .[:10] | .[] | {id, name, status: .overall_state}'

停机时间与静默

用途	适用情况
停机时间	任何计划内的静默时段
编辑监控器	查询或阈值行为发生变化

# Downtime (preferred)
pup downtime create --file downtime.json

故障处理

问题	解决方法
未触发告警	检查查询是否返回数据、阈值是否正确
告警过多	延长时间窗口，添加恢复阈值
无数据告警	检查 Agent 连接状态和指标是否存在
身份验证错误	pup auth refresh

参考资料

• 监控器类型
• 告警最佳实践
• SLO 监控器