创建仪表板

Telemetry 仪表板在团队共享页面中显示图表、表格和笔记。固定探索或查询的结果，然后排列小部件并添加笔记。也可以通过 API 创建仪表板。

仪表板包含哪些内容

• 仪表板是一个有名称的页面，用于显示相关指标。
• 每个小部件包含已保存的图表、表格、分节标题或笔记。
• 图表和表格小部件使用探索配置或查询结果。
• 在编辑模式下，拖动小部件以移动它们，并调整大小。

第 1 步：创建仪表板

您可以通过三种方式创建仪表板：

1. 在左侧边栏中，打开 仪表板菜单并单击新建仪表板。
2. 从 探索，单击 添加到仪表板。如果尚不存在仪表板，Telemetry 将提示您先创建一个仪表板。
3. 使用具有 write 或 read-and-write 范围的 API 密钥调用 POST /dashboard。

第 2 步：从“探索”中添加小部件

1. 打开一个表并转到 探索 选项卡。
2. 选择：
   • 图形类型（Samples、Table、Line、Bar 或 Stacked Area）
   • 聚合和粒度（对于图表视图）
   • 时间范围、过滤器和按字段分组
3. 单击运行。
4. 在图表上方的结果工具栏中，单击“添加到仪表板”。
5. 输入小部件标题，选择仪表板，然后保存。

运行探索查询后，Telemetry 在结果工具栏的右侧显示操作按钮：

Telemetry 存储完整的探索状态，因此该小部件与您固定的图表/表格保持一致。

第 3 步：从查询添加小部件

1. 打开已保存的查询或草稿查询。
2. 运行查询并切换到 结果或图表。
3. 单击“添加到仪表板”。
4. 选择目标仪表板并保存。

当您想要完全自定义 SQL 而不是 Explore 生成的 SQL 时，请使用此路径。

第 4 步：布置和维护仪表板

1. 打开/team/{team}/dashboard/{dashboard-slug}。
2. 单击编辑。
3. 使用添加组件插入：
   • 节标题块，用于在共享标题和描述下对相关小部件进行分组
   • 自由文本 用于 Markdown 注释、链接和 Runbook 样式上下文的块
4. 通过手柄拖动小部件，根据需要调整大小，并使用 X 删除小部件。
5. 当布局更改看起来正确时，单击 完成。

您还可以从侧边栏的仪表板操作菜单中重命名、复制 URL 或删除仪表板。

程序化仪表板创建

当您想要从代码配置仪表板、播种新环境或在入职期间生成仪表板时，请使用 仪表板API。

API 可以：

• 创建一个空的仪表板外壳
• 在一个请求中创建仪表板及其第一个小部件
• 创建 SQL 支持的查询小部件和 Explore 支持的小部件
• 为仪表板组织创建节标题和自由文本小部件

内联交互示例

SELECT
  date_trunc('hour', timestamp_utc) AS hour,
  100.0 * SUM(CASE WHEN status_code >= 500 THEN 1 ELSE 0 END) / COUNT(*) AS error_rate_pct
FROM
  http_logs
WHERE
  timestamp_utc >= now() - INTERVAL '7 days'
GROUP BY
  hour
ORDER BY
  hour ASC

SELECT
  endpoint,
  AVG(duration_ms) AS avg_duration_ms
FROM
  http_logs
WHERE
  timestamp_utc >= now() - INTERVAL '24 hours'
GROUP BY
  endpoint
ORDER BY
  avg_duration_ms DESC
LIMIT 15

SELECT
  timestamp_utc,
  service,
  endpoint,
  status_code,
  error_message
FROM
  http_logs
WHERE
  status_code >= 500
  AND timestamp_utc >= now() - INTERVAL '24 hours'
ORDER BY
  timestamp_utc DESC
LIMIT 200

仪表板设计技巧

• 每个小部件保留一个主要问题（例如：“错误率是否上升？”）。
• 将趋势小部件与钻取表混合在一起。
• 在主要组之前添加部分标题，以便仪表板在增长时保持可扫描性。
• 使用自由文本注释来提醒团队成员在调试时需要的上下文、操作手册链接或定义。
• 使用清晰的小部件标题，以便队友可以快速浏览页面。
• 从 4-8 个小部件开始；仅当每个添加一个新的决策信号时才添加更多。