跳至主要內容
Telemetry
瀏覽說明文件
概念與 SQL 模式更新於 2026年7月27日由 Telemetry 編輯團隊和產品團隊審查閱讀約需 2 分鐘

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

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

本頁內容
  1. 有用的高基數字段
  2. 偶然的基數
  3. 查詢模式

高基數字段

基數是欄位中不同值的數量。 status 欄位可以具有三個值; request_id 每行可能有不同的值。高基數本質上並不是錯誤的,但它改變了欄位的查詢和視覺化方式。

有用的高基數字段

請求、追蹤、作業、帳戶和使用者識別符號在調查過程中可能至關重要。它們可以讓您查詢相關事件或確定誰受到了影響。當存在特定的查詢或連線用例以及識別符號可以安全儲存時保留它們。

不要使用唯一識別符號作為圖表的預設分組維度。包含 100,000 個請求 ID 的條形圖既不可讀也不高效。篩選到特定識別符號,或按有界類別進行分組並將識別符號保留在詳細資訊資料表中。

偶然的基數

原始 URL、異常訊息、SQL 文字、使用者代理和自由格式標籤通常會無意中建立基數。將 /projects/abc123 標準化為 route_template,例如 /projects/:id。將異常對映到受控的 error_type,同時在適當的日誌系統中保留詳細的診斷資訊。切勿僅僅為了保留上下文而將秘密或原始使用者內容放入事件中。

分割區列值得格外小心。對過濾有用的欄位並不一定是一個好的分割區。過多的不同分割區會建立小檔案和規劃開銷。僅在測量代表性查詢後才選擇穩定的、經常過濾的維度。參見 選擇分割區列

查詢模式

啟動具有時間限制的聚合,按受控維度進行分組,並在對百分比進行排名之前施加最小量規則。對於調查,直接按高基數識別符號進行過濾並請求一組狹窄的列。

SELECT timestamp_utc, status, error_type, latency_ms
FROM api_requests
WHERE request_id = 'req_example'
ORDER BY timestamp_utc;

檢視 關聯 ID 指南敏感資料指南 旁邊的識別符號。

相關產品功能

記錄穩定的事件名稱、型別明確的欄位,以及經過隱私審查的上下文。

內容責任與技術參考

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

檢視編輯規範