快速入門
將 JSON 事件傳送到 Telemetry,再用 SQL 查詢。本快速入門將帶你傳送一個事件,檢查 Telemetry 建立的資料表,並執行查詢。
以下範例使用保留資料表 telemetry_quickstart 中的虛構資料,用來檢查傳送和查詢是否正常。要完成應用程式整合,請執行一個真實流程並查詢它產生的事件。
想了解資料如何儲存、查詢如何執行,請閱讀 Telemetry 系統架構。若想看完整的埋點範例,請閱讀追蹤 OpenAI 成本指南。
想按更簡短的任務逐步學習?請依次閱讀:
取得 API 金鑰
前往首頁,從設定提示詞取得 anon_… 金鑰。無需帳戶即可傳送和查詢事件。如果已有帳戶,請使用團隊設定 → API 金鑰中的 read-and-write 金鑰。
匿名查詢在首個事件後可用 24 小時。請在 7 天內建立帳戶,以保留事件和原金鑰。註冊會識別目前瀏覽器中的試用。在其他瀏覽器中,先選擇已有匿名 API 金鑰?,貼上金鑰並點擊尋找我的資料,再註冊。已有帳戶的使用者可在保留我的資料中復原金鑰,然後登入。未傳送事件的試用在建立 7 天後到期。
安裝 Telemetry
本教學使用 JavaScript。你也可以使用 Python SDK、Go SDK、Rust SDK、Ruby SDK、PHP SDK 或 cURL。
npm install telemetry-sh
傳送測試事件
傳送事件後,Telemetry 會自動建立資料表。以下範例把虛構的乘車資料寫入 telemetry_quickstart;資料表會包含 city、price,每筆事件也會有 timestamp_utc。
import telemetry from "telemetry-sh";
telemetry.init("YOUR_API_KEY");
await telemetry.log("telemetry_quickstart", {
city: "paris",
price: 42
});
先等事件傳送完成,再執行查詢,才能看見傳送失敗的錯誤。下方的查詢結果則可確認事件確實進入資料表;光是傳送請求成功還不足以證明這點。
查詢剛傳送的事件
無需註冊,就能先查詢並確認這筆事件:
const result = await telemetry.query("SELECT city, price FROM telemetry_quickstart WHERE city IS NOT NULL 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
}
}
}
上例展示的是儲存後的資料列。向 telemetry_quickstart 傳送事件時,請省略 timestamp_utc:Telemetry 根據 timestamp 產生它(省略時預設為目前的 UTC 時間)。上面的日期僅為範例。傳送歷史事件時,請設定 timestamp,並在「探索」中選擇包含該時間的範圍。請參閱 Log API 的正規化規則。
範例 1:過濾工具呼叫並檢查原始行
使用上面的虛構模式,在“探索”中嘗試以下操作:
- 將圖表型別設定為
Samples. - 新增過濾器:
event = tool_call. - 新增過濾器:
data.toolName = smart_avantis_buy. - 點選 執行.
URL 範本(替換佔位符):
/team/{team}/table/telemetry_quickstart?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_code 欄位的 HTTP 請求事件資料表,統計伺服器錯誤(HTTP 5xx)。前面的工具呼叫範例使用文字型 status 欄位,不能用於這個篩選條件。
- 在探索中,篩選同時符合
status_code >= 500和status_code < 600的列。 - 使用帶有聚合的折線圖
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 可以從程式碼讀取這些虛構的乘車事件。用於產品或內部儀表板時,請將此範例資料表替換為實際執行的流程所產生的事件資料表。
const results =
await telemetry.query(`
SELECT
city,
AVG(price)
FROM
telemetry_quickstart
WHERE city IS NOT NULL
GROUP BY
city
`);
當您準備好分析 API 錯誤、延遲百分位數、作業重試、LLM 成本、轉換、保留或丟失心跳時,請瀏覽 SQL配方庫。
對於這些秘訣背後的架構和分析模型,請繼續 SQL 用於可觀測性和事件分析。 要執行從攝取到 SQL 結果的完整合成工作流程,請使用 端到端 SaaS 可觀測性示範。