建立儀表板

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 個小工具開始；僅當每個新增一個新的決策訊號時才新增更多。