datadog-dashboards

Datadog 仪表板

构建仪表板时，Datadog 会让你做出一些取舍，以及如何解决这些问题。每条规则都会指出它要纠正的错误默认做法；对于模型已经做对的事，则没有相应规则。

固定的是日期，而不是版本。 Datadog 持续发布，因此这里的每项说明都已于 2026 年 7 月 对照 docs.datadoghq.com 验证。信任任何与版本相关的内容之前，请重新验证——这里列出的弃用项（q、default、is_read_only、week_before()）目前仍可解析。

假设 Datadog MCP 服务已连接（https://mcp.<site>/v1/mcp，toolsets=dashboards,widgets）。本技能刻意不重复列出 Widget 架构——get_widget_reference 会在调用时返回最新架构，复制到这里很快就会过时。如果服务尚未连接，请先完成设置（ship-endpoint-follows-the-site）；本技能不涵盖 Terraform 或原始 API 管理。

何时使用

在以下情况使用本技能：

• 创建或编辑 Datadog 仪表板，或审查他人构建的仪表板——尤其是通过程序而非图表编辑器组装的仪表板，因为 .as_count() 差异会在这种情况下造成影响
• 编写要用于 Widget 的任何 Datadog 查询：带有空间聚合器和修饰符的指标查询，或使用 search + compute + group_by 的 logs / spans / rum 查询
• 选择可视化方式，或收到一个说要“图表”但实际需要排名、单个数值或错误预算的请求
• 仪表板显示的数字无人信任、面板呈现“无数据”，或数值会随时间范围变化
• 有人只说“给 X 做个仪表板”，却没有说明受众——在构建任何内容之前，应先按照 scope-ask-audience-and-decision 中的访谈流程提问

本技能不适用于：

• 通过 Terraform 或原始 Dashboard API 管理仪表板（本技能假设 MCP 服务已连接）
• 编写监控器或定义 SLO——不过，scope-not-every-question-is-a-dashboard 会介绍如何识别请求是否属于这类需求
• Datadog 埋点：Agent 配置、Tracer 设置，或决定最初要发出哪些指标
• 非 Datadog 可观测性平台——这里的查询语义无法直接移用

规则类别

#	类别	前缀	涵盖内容
1	目的与范围	scope-	受众、要推动的决策、用变量代替重复内容，以及何时不应使用仪表板
2	基于账户的信息	disco-	查询之前，确认指标、标签和 Facet 确实存在
3	查询语义	query-	看似会返回数值、实际却有误的查询
4	选择 Widget	widget-	让问题与可视化方式相匹配；不可互换的组合
5	仪表板 JSON	json-	Widget 验证无法发现或解释的内容
6	布局与可读性	layout-	Datadog 自身对结构、显示类型、标题和尺寸的标准
7	发布	ship-	写入前先验证并进行冒烟测试；区域端点

快速参考

1. 目的与范围

• scope-ask-audience-and-decision — 创建第一个 Widget 前要问的四个问题；答案应写在 description 中，而不是聊天里
• scope-one-dashboard-many-variables — 六个服务只需一个仪表板；变量下拉列表仅提供该仪表板自身 Widget 所查询的值
• scope-clone-before-building — 1000 多种集成已有预设，且通过 GET /dashboard 无法看到；应搜索，不要列举
• scope-not-every-question-is-a-dashboard — “在 X 发生时通知我们”需要的是监控器；叙事内容需要的是 Notebook

2. 以账户为依据

• disco-never-invent-metric-names — 错误的指标名称会显示空图表，而不会报错
• disco-read-type-and-unit-first — DogStatsD 的 increment() 会存储为 RATE；类型决定修饰符，单位决定标题
• disco-absence-is-not-proof — 指标会在 24h 后从发现结果中移除，但会保留 15 个月
• disco-log-attributes-need-facets — 未创建 facet 的属性无法分组，也没有 API 可以列出 facet

3. 查询语义

• query-append-as-count-explicitly — 默认设置中代价最高的一项。 UI 会追加 .as_count()；API 不会，而是使用 avg 汇总
• query-percentiles-require-distributions — p95: 需要启用百分位数的分布；对 p95 使用 avg: 并不等于百分位数
• query-aggregate-before-dividing — 不使用 .as_count() 的比率会对各时间间隔的比率求和，结果可能达到 150%
• query-gauge-gaps-are-interpolated — 默认情况下，每个间隔最多会填入 5 分钟的虚构数据点
• query-rollup-changes-the-number — 同一小组件在不同时间范围内表达的含义也不同
• query-event-sources-take-objects — 日志和 span 使用 search+compute+group_by；interval 的单位是毫秒，百分位数使用 pc95
• query-scope-syntax-does-not-mix — {env:prod AND !region:x} 无效；$var 后的通配符无法匹配任何内容
• query-top-n-subtotals-are-partial — top 列表下方的总计是可见行的总和

4. 选择小组件

• widget-match-the-question — 时间序列图回答一个问题；排名、单值和变化量需要使用其他小组件
• widget-heatmap-is-not-distribution — 一个以时间为 x 轴，另一个以数量为 x 轴
• widget-reuse-alerting-primitives — 嵌入 SLO 和监视器，而不是猜测阈值线

5. 仪表板 JSON

• json-type-strings-differ-from-ui-names — Pie Chart 对应 sunburst，Table 对应 query_table，Monitor Summary 对应 manage_status
• json-queries-and-formulas-not-q — q 和所有 *_query 字段均已弃用；data_source 是 profiles，而不是 profile_metrics
• json-layout-follows-reflow-type — 使用 reflow_type: auto 时，必须省略 layout，而不能仅仅忽略它
• json-template-variables-take-defaults — defaults 是一个数组；单数形式的 default 已弃用
• json-dashboard-tags-are-constrained — 最多 5 个，格式为 team:；is_read_only 已弃用，但 restricted_roles 未弃用

6. 布局与可读性

• layout-put-widgets-in-groups — 先放「关于」和「概览」，最后放流式数据，不要让任何内容孤零零地放在背景上
• layout-display-type-follows-metric-shape — 用面积图表示容量，用条形图表示计数，用折线图进行比较
• layout-let-datadog-render-units — 为每个公式设置别名；坐标轴已经显示单位
• layout-size-for-the-medium — 墙面看板和事件分诊看板不能是同一个仪表板

7. 发布

• ship-validate-before-upserting — 写入前对查询进行冒烟测试，并逐个验证工具
• ship-endpoint-follows-the-site — EU、AP 和 UK 组织需要使用各自的 MCP 主机；GovCloud 不受支持

使用方法

遇到相关决策时，阅读对应的参考文件。每条规则都会指出它要纠正的错误默认做法，然后展示规范形式；只有当错误做法确实容易导致问题时，才会对比错误与正确示例。

建议优先参考以下三条捷径：

• 要根据需求构建仪表板？ 先运行 scope-ask-audience-and-decision，再运行 disco-never-invent-metric-names，然后再生成任何内容。跳过其中任意一项，都会导致仪表板看似合理，实则毫无用处。

• 在检查数值似乎有误的仪表板？ 从 query-append-as-count-explicitly 和 query-percentiles-require-distributions 开始。它们能解释大多数看似可信、实则错误的 Datadog 面板问题，而且这两种问题都不会在界面中留下痕迹。

• 要迁移 2025 年之前编写的仪表板 JSON？ json-queries-and-formulas-not-q 和 json-template-variables-take-defaults 属于仍能解析的弃用用法，因此没有任何提示会提醒你注意它们。

• 章节定义 — 类别结构和排序理由

• 规则模板 — 用于添加新规则

• AGENTS.md — 自动生成涵盖所有规则的目录