快速入門
將 JSON 事件傳送到 Telemetry，再用 SQL 查詢。本快速入門將帶你傳送一個事件，檢查 Telemetry 建立的資料表，並執行查詢。
如果您有興趣瞭解有關 Telemetry 內部工作原理的更多資訊，請檢視我們的 Telemetry架構文件 以獲取詳細概述。有關更深入的用例，例如透過檢測 API 呼叫來追蹤 OpenAI 成本，請參閱我們的 追蹤 OpenAI 成本 指南。
想按更簡短的任務逐步學習？請依次閱讀：
取得 API 金鑰
前往首頁，從設定提示詞取得 anon_… 金鑰。無需帳戶即可傳送和查詢事件。如果已有帳戶，請使用團隊設定 → API 金鑰中的 read-and-write 金鑰。
匿名查詢在首個事件後可用 24 小時。請在 7 天內建立帳戶，以保留事件和原金鑰。註冊會識別目前瀏覽器中的試用。在其他瀏覽器中，先選擇已有匿名 API 金鑰？，貼上金鑰並點擊尋找我的資料，再註冊。已有帳戶的使用者可在保留我的資料中復原金鑰，然後登入。未傳送事件的試用在建立 7 天後到期。
安裝Telemetry
本教程使用JavaScript。您還可以使用 Python、Go、Rust、Ruby、PHP 或 cURL。
npm install telemetry-sh
記錄一些資料
Telemetry 在記錄資料時自動建立資料表。在以下範例中，我們將合成騎行資料記錄到名為 uber_rides 的資料表中。 Telemetry 使用 city 和 price 建立資料表及其架構；每行還收到 timestamp_utc。
import telemetry from "telemetry-sh";
telemetry.init("YOUR_API_KEY");
telemetry.log("uber_rides", {
city: "paris",
price: 42
});
使用我們的 UI 探索資料
先透過查詢驗證事件，無需註冊：
const result = await telemetry.query("SELECT city, price FROM uber_rides LIMIT 10");
console.log(result);
要使用圖表、儀表板和警報，請建立帳戶並保留資料。現有金鑰仍然有效，註冊後會開啟存有事件的工作區。已有帳戶則可連結試用。
Telemetry 流程示意圖：從資料表、SQL 查詢和圖表，到共享儀表板或警示。
探索檢視
使用探索分頁篩選事件、建立圖表或表格，無需編寫 SQL。
探索每次處理一個資料表。開啟方式如下：
- 進入你的團隊頁面。
- 開啟資料表。
- 選擇一個資料表。
- 開啟該資料表頁面上的 探索 選項卡。
路由格式：
/team/{team}/table/{table}?tab=explore
- 選擇圖形型別（
Samples、Table、Line、Bar或Stacked Area）。 - 設定時間範圍並新增一個或多個過濾器。
- 選擇要包含的列（包括
data.toolName等巢狀欄位）。 - 點選執行來執行並呈現結果。
提示：控制元件處於草稿狀態。僅當您點選“執行”時，結果才會更新。
假設的範例資料集（虛構）
對於下面的探索範例，假設您使用如下結構記錄了合成測試事件（沒有真實的使用者資料）：
{
"timestamp_utc": "2026-02-27T12:00:00.000Z",
"event": "tool_call",
"status": "success",
"data": {
"toolName": "smart_avantis_buy",
"args": {
"symbol": "BTC-USD",
"amountUsd": 2500
}
}
}
您可以將其記錄到 agent_demo_events 等資料表中，並在“探索”中使用該資料表。
範例 1：過濾工具呼叫並檢查原始行
使用上面的虛構模式，在“探索”中嘗試以下操作：
- 將圖表型別設定為
Samples. - 新增過濾器：
event = tool_call. - 新增過濾器：
data.toolName = smart_avantis_buy. - 點選 執行.
URL 範本（替換佔位符）：
/team/{team}/table/agent_demo_events?tab=explore&graphType=samples&f=event:=:tool_call&f=data.toolName:=:smart_avantis_buy範例 2：比較圖表檢視與表格檢視
使用相同的過濾器，然後：
- 選擇
Line然後點選 執行. - 切換到
Table然後點選 執行 再次。
這為您提供了一種快速驗證趨勢和準確值的方法。
範例 3：“所有列”模式下的巢狀列
當你保留 All columns 在探索中選擇，生成的 SQL 顯式列舉列，因此包含巢狀欄位。
生成的 SQL 形狀範例：
SELECT "timestamp_utc", "event", "data.toolName", "data.args.symbol"
FROM "your_table"
WHERE timestamp_utc >= now() - INTERVAL '7 days'
ORDER BY timestamp_utc DESC
LIMIT 200儀表板
儀表板可讓您將探索圖表/表格和查詢結果固定到一個共享檢視中。
建立和使用儀表板：
- 開啟探索中的任何資料表或開啟已儲存的查詢結果。
- 點選“新增到儀表板”。
- 選擇現有的儀表板，或先建立一個新的儀表板。
- 為小工具指定標題並確認。
儀表板路由格式：
/team/{team}/dashboard/{dashboardSlug}
使用儀表板將團隊的關鍵訊號（延遲、錯誤率、成本和轉化指標）儲存在一個位置。
建立提醒
獲得圖表或查詢結果後，您可以將其轉換為 Telemetry UI 中的警示。
- 在 探索中開啟資料表或在結果/圖表 檢視中執行查詢。
- 點選“建立警示”。
- 設定條件（聚合、最後 N 點、比較和閾值）。
- 設定檢查間隔和一個或多個電子郵件收件人。
- 點選“建立警示”進行儲存。您將被重定向到
/team/{team}/alert/{alertSlug}以監控狀態和歷史記錄。
提示：為儲存時間序列啟用忽略最後一個資料點，因為最新的儲存桶通常不完整。
有關完整演練，請參閱 警示指南。
互動式內嵌範例
範例 1：延遲尖峰檢測器 (p95)
在“探索”資料表中嘗試此操作 latency_ms:
- 將圖表型別設定為
Line. - 將聚合設定為
p95帶公制latency_ms. - 點選 執行，然後點選 建立警示.
- 條件：
p95 of last 5 data points is Greater than 850. - 間隔：
Every minute，然後新增收件人電子郵件。
URL 範本（替換佔位符）：
/team/{team}/table/{table}?tab=explore&graphType=line&agg=p95&metric=latency_ms&time=7d範例 2：錯誤突發檢測器（計數）
檢測失敗請求中的峰值：
- 在探索中，使用以下內容過濾行
status >= 500. - 使用帶有聚合的折線圖
count. - 點選 建立警示.
- 條件：
Average of last 3 data points is Greater than 20.
這可以捕獲短暫的錯誤突發，同時避免來自單個壞桶的噪音。
範例 3：安靜流量檢測器（低於閾值）
將其用於 cron 作業、佇列或攝取管道：
- 查詢或繪製隨時間變化的事件量圖表。
- 建立比較警示
Less than. - 條件：
Sum of last 10 data points is Less than 50.
如果觸發此情況，通常意味著資料在客戶注意到之前停止流動。
與您的程式碼儲存庫整合
您可以透過查詢 API 來使用 SQL 查詢資料，從而將 Telemetry 整合到您的產品或內部儀表板中。
const results =
await telemetry.query(`
SELECT
city,
AVG(price)
FROM
uber_rides
GROUP BY
city
`);
當您準備好分析 API 錯誤、延遲百分位數、作業重試、LLM 成本、轉換、保留或丟失心跳時，請瀏覽 SQL配方庫。
對於這些秘訣背後的架構和分析模型，請繼續 SQL 用於可觀測性和事件分析。 要執行從攝取到 SQL 結果的完整合成工作流程，請使用 端到端 SaaS 可觀測性示範。