將 OpenTelemetry GenAI 追蹤連線到結果事件
OpenTelemetry 追蹤和 Telemetry 結構化事件解決了 AI 代理調查的不同部分。將詳細的模型、代理和工具跨度儲存在與 OTLP 相容的可觀測性後端中。當您想要檢查 SQL 的成功、成本、延遲、發布、帳戶、移交或審查的產品價值時，向 Telemetry 傳送較小的終端結果事件。
Telemetry 不公開 OTLP 端點，也不是 OpenTelemetry 追蹤後端。連線是應用程式擁有的相關識別符號，而不是每個跨度的第二個匯出。
將每個系統用於其預期工作
OpenTelemetry 跡線非常適合回答：
- 哪個跨度或工具在一次慢速執行中占主導地位；
- 控制如何在代理、模型、檢索和工具操作之間移動；
- 哪種異常或依賴性解釋了個別失敗；
- 經批准的痕量保留邊界記憶體在哪些詳細屬性。
緊湊的結果事件非常適合回答：
- 哪個版本的終端任務成功率最高；
- 對於每個接受的結果，哪個工作流程成本最高；
- 本週工具重試或人工交接是否增加；
- 哪個客戶層受到有限錯誤類別的影響；
- 提示或模型版本後評估分數是否發生變化。
不要將所有跨度屬性複製到事件中。確定哪些聚合問題需要持久列並將這些欄位列入許可名單。
刻意對映語義
OpenTelemetry 生成式 AI 語義約定 定義了模型、代理和工具操作的不斷發展的屬性和跨度約定。固定您的服務使用的語義約定和工具庫版本，然後在升級期間檢查對映。
| OpenTelemetry概念 | Telemetry 活動場地 | 指導 |
|---|---|---|
| 活動跨度追蹤 ID | trace_id |
批准後安全關聯指標；請勿將其用作帳戶身分 |
| 應用程式執行或操作 ID | run_id 或 operation_id |
優先使用應用程式識別符號進行重試和以後審查的連線 |
gen_ai.operation.name |
operation_name |
保持有界操作類別 |
gen_ai.provider.name |
provider |
使用固定儀器發出的提供程式值 |
| 請求或回應模型 | model |
選擇並記錄一種含義，或分別保留 requested_model 和 response_model |
| 輸入和輸出使用 | input_tokens、output_tokens |
記錄一次數字使用情況；不要重複計算推理標記細節 |
| 代理人身分 | agent_name 或 agent_version |
使用穩定的邏輯名稱而不是生成的執行個體識別符號 |
| 跨度狀態或異常 | status、error_type |
將不受限制的訊息轉換為列入白名單的應用程式類別 |
語義約定在成熟時可能會發生變化。不要假設在一個 SDK 或框架中觀察到的屬性在任何地方都具有相同的穩定性或可用性。將精確對映視為版本化應用程式程式碼。
在追蹤旁邊發出一個最終結果
此 JavaScript 包裝器讀取當前追蹤 ID 並在代理執行後記錄應用程式結果。透過設定的OpenTelemetry SDK繼續匯出跡線；只有選定的欄位才會轉到 Telemetry。
import { trace } from "@opentelemetry/api";
import telemetry from "telemetry-sh";
telemetry.init(process.env.TELEMETRY_API_KEY);
export async function runSupportAgent({
agent,
input,
operationId,
accountId,
release,
}) {
const startedAt = Date.now();
let status = "success";
let errorType;
let result;
try {
result = await agent.run(input);
return result;
} catch (error) {
status = "failed";
errorType = classifyAgentError(error);
throw error;
} finally {
const activeSpan = trace.getActiveSpan();
const traceId = activeSpan?.spanContext().traceId;
await telemetry.log("agent_run_completed", {
operation_id: operationId,
trace_id: traceId,
workflow: "support_resolution",
account_id: accountId,
status,
error_type: errorType,
duration_ms: Date.now() - startedAt,
human_handoff: result?.handoffRequired ?? false,
tool_call_count: result?.toolCallCount ?? 0,
release,
});
}
}
使事件傳遞失敗成為非致命的，除非業務工作流程明確要求否則。使用短超時、有界重試、正常關閉以及 批次處理、背壓和關閉 中的交付指導。
僅新增一次模型用法
如果 OpenTelemetry 工具已經觀察到提供者請求，則不會自動將請求使用情況放入 Telemetry 中。確定聚合 SQL 問題是否需要單獨的 llm_request_completed 事件。
當發生這種情況時，為每個計費請求發出一個事件：
operation_id、run_id和可選的經批准的trace_id；provider、requested_model、response_model和service_tier；- 輸入、快取輸入、輸出和其他單獨定義的權杖類別；
estimated_cost_usd和版本化定價源；latency_ms、status、attempt、feature和release。
不要從跨度持續時間中得出成本。使用提供商報告的使用情況和經過審查的費率資料表，然後將估算值與提供商發票進行核對。 OpenAI 請求成本指南 顯示了這種模式。
保護資料邊界
生成式人工智慧遙測可能包含異常敏感的資料。預設情況下不將這些欄位傳送到 Telemetry：
- 提示或補全內容；
- 系統指令或思路內容；
- 檢索到的文件文字或嵌入；
- 工具參數、工具回應、shell 輸出或檔案內容；
- 授權標頭、cookie、API 金鑰、資料庫憑據或連線字串；
- 無限制的例外訊息或 OpenTelemetry 行李；
- 未透過產品收集和保留審查的個人資料。
優先選擇 input_category、output_category、tool_name、error_type、policy_result 和 review_outcome 等類別。在致電任一出口商之前應用許可名單；從儀表板中刪除欄位不會將其從儲存的資料中刪除。
查詢結果並保留追蹤連結
使用 SQL 進行聚合比較，同時保留回應者需要的相關指標：
SELECT
release,
workflow,
COUNT(*) AS completed_runs,
SUM(CASE WHEN status = 'success' THEN 1 ELSE 0 END) AS successful_runs,
SUM(CASE WHEN human_handoff THEN 1 ELSE 0 END) AS handoffs,
ROUND(AVG(duration_ms), 0) AS average_duration_ms,
MAX(trace_id) AS example_trace_id
FROM agent_run_completed
WHERE timestamp_utc >= now() - INTERVAL '7 days'
GROUP BY release, workflow
ORDER BY completed_runs DESC;
MAX(trace_id) 只是該組中的範例指標，而不是代表性追蹤。要進行調查，請開啟基礎行，選擇相關執行，並將其 trace_id 貼上到追蹤後端。如果該後端支援穩定的 URL 範本，請在存取控制的內部工具中建置連結，而不是將供應商憑據或私有主機名作為事件欄位傳送。
驗證連線
生產推出前：
- 生成一次成功執行、一次工具失敗、一次恢復重試和一次終端失敗。
- 確認追蹤後端包含預期的生成樹。
- 確認 Telemetry 每次執行包含一個終端事件以及預期的請求或工具事件。
- 比較追蹤和事件相關識別符號。
- 驗證提示、完成、參數、憑據和私人內容是否不存在。
- 測試匯出器速度緩慢或不可用時的行為。
- 文件所有者、保留、語義約定版本、取樣和調查移交。
有關一般架構和 SDK 範例，請閱讀 Telemetry 與 OpenTelemetry。對於特定於代理的結果設計，請繼續 使用 SQL 評估 AI 代理 和 AI代理監控產品邊界。