跳至主要內容
Telemetry
瀏覽說明文件

概念與 SQL 模式更新於 2026年9月29日閱讀約需 4 分鐘

讓程式設計代理使用這篇文件

開啟 Claude Code、Codex、Cursor 或其他編碼代理的集中提示包,然後將其適應此處介紹的工作流程。

本頁內容
  1. 儀表板包含哪些內容
  2. 第 1 步:建立儀表板
  3. 第 2 步:從“探索”中新增小工具
  4. 第 3 步:從查詢新增小工具
  5. 第 4 步:佈置和維護儀表板
  6. 程式化儀表板建立
  7. 內聯互動範例
  8. 儀表板設計技巧

建立儀表板

Telemetry 儀表板在團隊共用頁面中顯示圖表、表格和筆記。固定探索或查詢的結果,然後排列小工具並加入筆記。也可以透過 API 建立儀表板。

儀表板包含哪些內容

  • 儀表板是一個有名稱的頁面,用於顯示相關指標。
  • 每個小工具包含已儲存的圖表、表格、章節標題或筆記。
  • 圖表和表格小工具使用探索設定或查詢結果。
  • 在編輯模式下,拖曳小工具以移動它們,並調整大小。

第 1 步:建立儀表板

您可以透過三種方式建立儀表板:

  1. 在左側邊欄中,開啟 儀表板選單並點選新建儀表板。
  2. 在 探索 結果中,沒有儀表板時使用 建立入門儀表板並儲存;否則直接儲存到按鈕標明的儀表板。
  3. 使用具有 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 支援的小工具
  • 為儀表板組織建立節標題和自由文字小工具

內聯互動範例

範例1:錯誤率趨勢小工具(線)

在“探索”或“查詢”中執行此命令,然後將其固定為 儲存到Getting Started.

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
範例 2:最慢端點小工具(條形圖)

使用一個 Bar 排名圖表。非常適合 API 和佇列監控儀表板。

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
範例 3:最近失敗的鑽取小工具(資料表)

將其新增為趨勢圖旁邊的表格小工具,以便快速進行根本原因除錯。

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

相關功能

將經過驗證的查詢轉變為重點突出、可審查的操作檢視。

頁面作者與參考資料

Telemetry 編輯團隊負責維護本文;產品團隊審查功能行為、範例和適用範圍。

我們如何審查文件