datadog-design-dashboard

设计 Datadog 仪表板

设计清晰易懂的仪表板布局——从高层健康信号逐步深入到细粒度诊断，并使用恰当的组件类型、分组组织方式和模板变量来实现复用。

重要：始终先使用 pup dashboards list --agent 检查现有仪表板。如果同一服务或用途已有仪表板，请勿新建，而应更新现有仪表板。只有在没有相关仪表板，或用户明确要求新建时，才创建新仪表板。

理念：此技能中的框架、布局和组件指南只是起点，并非硬性规则。每种产品和业务都各不相同。先了解领域，再调整框架以满足实际需求。最好的仪表板应体现业务的实际运作方式，而不是照搬通用模板。

---

访谈

首先确定模式：

• 设计模式 — 用户希望创建或重新设计仪表板 → 提出设计问题，然后执行完整工作流
• 审查模式 — 用户希望审查现有仪表板，且无意重新设计 → 跳转到审查

设计问题

如果以下所有信息都已明确，则跳过：仪表板用途、目标受众、数据源、模板变量需求、仪表板策略。

1. 用途 — “这个仪表板的用途是什么？服务概览、基础设施、管理层 KPI、调试，还是 SLO 跟踪？”
2. 受众 — “谁会使用它？值班工程师、平台团队、管理层，还是混合受众？”
3. 数据源 — “涉及哪些 Datadog 产品？仅指标、APM + 指标、日志 + 指标，还是全栈？”
4. 范围 — “这是针对单个服务、一组服务，还是整个基础设施？”
5. 仪表板策略 — “每个服务一个仪表板，还是使用整合视图？”——参考 references/layouts.md 分享其中的权衡，帮助用户做出决定。如果不确定，请询问：“发生故障时，团队是一次排查一个服务，还是需要同时查看所有服务？”
6. 现有仪表板 — “是否有现有仪表板需要审查或重新设计？”如果有，请在设计前使用 pup dashboards get <id> --agent 获取。

审查问题

如果以下所有信息都已明确，则跳过：仪表板 ID 或 URL、服务名称或团队背景。

以下情况始终进行访谈：未提供仪表板 ID，或可能有多个相关仪表板。

1. 仪表板 — “应该审查哪个仪表板？请提供仪表板 ID、URL，或服务名称以便搜索。”
2. 业务背景 — “能否介绍一下这项服务为客户提供什么？有没有代码库或文档可供我了解产品？”
   • 影响：了解业务领域有助于审查是否跟踪了正确的指标，而不仅仅是是否遵循通用规则
3. 关注重点 — “有什么特别需要我关注的吗？(A) 全面审查、(B) 仅检查告警阈值、(C) 业务板块、(D) 布局和可读性”
   • 如果未指定，默认进行全面审查

---

领域探索

适用于设计模式。仅进行审计时请跳过。

开始设计前，先了解你要为其构建可观测性的领域。哪些指标重要，完全取决于产品和业务背景。

询问用户：

• “能介绍一下这款产品，以及这项服务为业务做什么吗？客户与它交互时会有怎样的体验？”
• “这项服务遇到糟糕的一天会是什么样？哪些环节会出问题，客户会有什么感受？”
• “有没有我可以查看的代码库、架构文档或 README 文件，以便了解这项服务及其依赖项？”

如果用户提供了代码库：阅读代码。查看入口点、API 路由、数据库模型、队列消费者和外部服务调用。理解代码有助于你选择真正重要的指标，而不只是通用的 RED/USE 信号。

如果用户介绍了业务：根据这些背景调整业务（B）部分。电商服务关注结账成功率，消息服务关注投递延迟，支付服务关注交易完成情况。通用的“请求速率”和“错误率”只是起点，真正的价值来自能够反映客户可见结果的指标。

以下情况可跳过领域探索：你已通过之前的对话深入了解这项服务，或用户已提供详细规格。

门槛：设计业务组之前，你必须能够用产品经理能够理解的日常语言，说出至少 3 个专属于这项服务的领域结果。例如：“下单成功”“支付完成”“消息已送达”。如果说不出来，请先询问用户再继续。不要用传输层指标（gRPC 错误率、HTTP 请求速率）代替这些结果——它们属于 P，而非 B。请参阅 references/widgets.md 中的 B 常见误区。

---

设计

如果用户只想审查现有仪表板，请跳至 审计。

1. 收集现有背景信息

pup dashboards list --agent
pup dashboards get <dashboard-id> --agent

如果要审计现有仪表板，请先获取其定义，并在重新设计前分析其当前结构。

2. 探索可用的遥测数据

设计组件前，先检查这项服务实际有哪些指标和标签值。这样可以避免围绕不存在的指标进行设计，或在查询中使用错误的标签值。

# See what metrics are available for the service
pup metrics list --filter="<service-name>.*" --agent

# Verify the service tag is active and see what metrics are flowing
pup metrics list --filter="trace.*" --tag-filter="service:<service-name>" --agent

编写组件查询时，使用在此处找到的实际指标名称和标签值——不要猜测或编造。如果预期中的指标没有出现，请在基于它构建组件前告知用户。

这适用于所有查询类型：指标查询、APM span 筛选器（operation_name、resource_name、span 标签）和日志筛选器。references/widgets.md 中的 **Configuration** 部分只介绍 JSON 结构和字段限制，并不规定查询内容。使用这些筛选值前，务必通过 pup 验证。

3. 选择框架

根据仪表板的用途选择合适的框架。详细的指标映射和分组结构请阅读 references/frameworks.md。

用途	框架
服务概览	RED（速率、错误、耗时）
基础设施	USE（利用率、饱和度、错误）
高管/业务	黄金信号
SLO 跟踪	SLI/SLO
调试	深入分析

4. 设计布局

根据你对领域的了解和选定的框架，设计分组结构并选择小组件。设计前请阅读以下参考资料：

• layouts.md — 模板变量约定、分组结构模式、仪表板策略权衡、网格尺寸、反模式
• widgets.md — 小组件选择指南、显示选项、尺寸、命名约定
• thresholds.md — 告警阈值标记、阈值接近度、Y 轴配置

5. 考虑使用标签页

如果仪表板的顶层分组达到 7 个或以上，请评估使用标签页是否能减少滚动疲劳。阅读 references/tabs.md，了解组织模式、JSON 架构和常见错误。

在现有仪表板中添加标签页之前，请检查所有小组件 ID 是否有重复项——标签页会触发严格的唯一性验证。

6. 编写设计输出

使用此模板呈现设计：

# Dashboard Design: [Dashboard Title]

## Purpose
[1-2 sentences: what this monitors, who uses it]

## Template Variables
| Variable | Tag | Default |
|----------|-----|---------|
| ... | ... | `*` |

## Layout

### Group: [Group Title]
| Widget | Type | Query/Metric | Width | Alert Threshold |
|--------|------|-------------|-------|----------------|
| ... | ... | ... | ... | ... |

[Repeat for each group]

---

审核

适用于两种模式。在设计后运行，或直接用于审核现有仪表板。

核心原则是：图表应通过配置告警阈值证明其必要性；阈值应接近正常流量；顶部应包含业务分组；即使对服务一无所知的人也应能读懂仪表板。

这些原则用于指导判断，而非僵化的检查清单。请根据产品和业务背景灵活应用。提供背景信息的指标（例如部署事件）即使没有阈值，也可能值得保留。流量模式特殊的服务可能需要采用不同的接近度规则。

1. 获取仪表板

# If given a service name, list all dashboards and identify the relevant one by title
pup dashboards list --agent

# If given a URL, extract the dashboard ID from the path (e.g., /dashboard/abc-def-ghi/...)

# Get the full dashboard definition (includes the dashboard URL in the response)
pup dashboards get <dashboard-id> --agent

# Verify real metric names exist
pup metrics list --filter="trace.http.request.*" --agent

解析响应，整理所有小组件、分组及其配置的清单。

2. 整理小组件清单

在编目之前，请阅读 references/widgets.md，了解完整的小组件前缀系统。

为仪表板中的每个小组件编目：

小组件标题	前缀	类型	分组	是否有告警阈值	阈值	备注
...	I0/P1/D0/B0/—	...	...	...	...	...

重点检查时序图和查询值小组件——它们是配置告警阈值标记的主要候选项。

3. 审核告警阈值

请阅读 references/thresholds.md，了解阈值标记原则、配置详情和发现项格式。

对于每个时序图，请检查：

• 是否配置了标记线/阈值线？
• 标记颜色是否为红色，以确保醒目？
• 阈值是否对应实际的监控器/告警？

4. 审核阈值接近度

请阅读 references/thresholds.md，了解接近度指南、Y 轴配置规则和发现项格式。

对于每个带阈值的小组件，请检查：

• 典型（正常）数值范围是多少？
• 阈值设在什么位置？
• 正常曲线与告警线之间是否存在过多空白？
• Y 轴是自动缩放还是显式设置？

5. 审查业务部分

原则：仪表板顶部应有一个专门的业务（B）组，包含 5-8 个关键指标，以便立即发现故障。业务指标应体现客户可见的结果，而非基础设施或领域内部指标。具体指标应反映产品的业务交易，而不是通用流量和错误率。

检查：

• 是否存在业务组（名称为“Business”“B”或类似名称）？
• 它是否是仪表板上的第一个组？
• 其中的小组件是否使用 B0-N: 前缀？
• 是否包含 5-8 个指标，涵盖客户可见的成功率、关键交易流程和影响 SLA 的延迟？
• 用户打开仪表板后，能否在 5 秒内判断“客户是否受到影响”？
• B 陷阱检查：对于每个带有 B 前缀的小组件，问一句：“产品经理无需了解传输协议，能否解读这个指标？”如果不能——例如 gRPC 错误率、HTTP 请求率、队列深度——那么它就属于 P，而不是 B，无论它被放在什么位置。请标记并建议将其移至相应的平台组。

发现格式：

#### Business Section Audit

**Status**: MISSING / INCOMPLETE / OK

**Current state**: [Description of what exists]

**Recommended metrics** (if missing or incomplete):
1. B0: Key transaction success rate (are critical flows completing?)
2. B0: Customer-facing error rate (are requests failing for customers?)
3. B1: API p99 latency (are responses slow for customers?)
4. B1: Total request rate (are we receiving traffic?)
5. B2: Queue depth or processing lag (is async work backing up?)
6. B2: Key business event throughput (e.g. orders created, payments processed)

6. 应用零知识查看者测试

原则：对服务一无所知的人，也应该能够通过查找红色指示器发现问题。

评估：

• 不看小组件标题，能否在 10 秒内发现问题？
• 每张图表上是否都以红线标出阈值？
• 查询值小组件是否应用了条件格式（绿色/黄色/红色）？
• 组名是否一目了然？
• 是否有包含运行手册链接或团队归属信息的备注小组件？

发现格式：

#### Zero-Knowledge Readability Audit

| Check | Status | Finding |
|-------|--------|---------|
| Problems visible in <10s | FAIL | No red lines on 8 of 12 graphs |
| Conditional formatting on QV widgets | PARTIAL | 2 of 4 QV widgets have thresholds |
| Group names self-explanatory | OK | All groups use clear names |
| Runbook/ownership note | MISSING | No note widget with team info |

7. 审查标签页组织

如果仪表板有 7 个或更多顶层组，请检查是否使用了标签页。请参阅 references/tabs.md。

• 是否按可观测性层将相关组整合到标签页中？
• 标签页名称是否能体现其要回答的问题（Service Health、Platform、Infrastructure）？
• 所有顶层小组件是否都恰好分配到了一个标签页？

8. 生成审查报告

将所有发现汇总为一份结构化报告：

# Dashboard Audit: [Dashboard Title]

**Dashboard ID**: [id]
**URL**: [url]
**Review date**: [date]

## Summary

[2-3 sentence summary: overall health of the dashboard, critical issues count]

## Critical Issues

[List issues that must be fixed before the dashboard is production-ready]

## Alert Threshold Audit
[From step 3]

## Threshold Proximity Audit
[From step 4]

## Business Section Audit
[From step 5]

## Zero-Knowledge Readability Audit
[From step 6]

## Recommended Actions

### Must Fix
1. [Action item with specific widget and group reference]

### Should Fix
1. [Action item]

### Nice to Have
1. [Action item]

---

质量原则

• 小组件查询使用通过 pup metrics list --agent 验证过的真实指标名称——不得编造指标名称
• 仪表板应反映实际产品和业务——指标应针对具体领域进行定制
• 仪表板标题遵循 [service] Purpose 模式——不添加“Dashboard”后缀，标题中不包含环境信息
• 更新 JSON 中的 title 字段（不能只改文件名）——标题有任何更改后都要重新部署
• 模板变量与仪表板类型相匹配——请参阅 references/layouts.md
• 小组件查询使用通过 pup metrics list --agent 验证过的模板变量作用域——不得对环境、服务或主机值进行硬编码；应使用适合仪表板类型的变量集（请参阅 references/layouts.md）
• 包含业务组，其中有 5-8 个以 B 为前缀的指标，针对服务的客户可见结果进行定制
• 组按从宏观到微观的顺序排列（业务 → 概览 → 详情）
• 每个小组件标题都使用层级优先级前缀（I0:、P1:、D0:、B0: 等）——请参阅 references/widgets.md
• 小组件标题使用句首字母大写格式，且不重复组名
• 时间序列小组件在指标可触发告警时包含告警阈值标记（红线）——请参阅 references/thresholds.md
• 阈值应接近正常流量——不得留白过多
• 确保零知识可读性——对服务一无所知的人也能通过红色指示器发现问题
• 查询值小组件应用条件格式（绿色/黄色/红色）
• 每个指标都应有存在的价值——如果它出现峰值，应有人能够据此采取行动
• 所有审查发现都包含具体的小组件名称和组引用
• 建议的操作按优先级分类（必须/应该/可选）
• 审查报告中包含仪表板 URL

参考资料

• 可观测性框架 — RED、USE、黄金信号、SLI/SLO 及其指标映射
• 布局与结构 — 模板变量、分组模式、仪表板策略、网格尺寸、反模式
• 小组件 — 小组件前缀系统、类型、显示选项、尺寸、命名约定
• 告警阈值 — 阈值标记、接近度指南、Y 轴配置
• 标签页 — 仪表板标签页组织、JSON 架构、@N 位置引用、常见错误