OpenTelemetry 導出的配套文檔。完整傳輸協議：涵蓋每項指標、日誌事件、屬性、枚舉值和存在性規則。
傳輸協議僅以新增方式演進。可兼容未知的屬性、事件和枚舉值。如有重命名或移除，將明確通知。
傳輸協議和範圍¶
- OTLP/HTTP 二進制 Protobuf (
application/x-protobuf) ，POST - 端點：
<base>/v1/metrics和<base>/v1/logs - 範圍：
cursor.telemetry/0.1.0
資源屬性¶
每個 (團隊、用戶、來源界面、入口點、界面版本) 組合對應一個資源。
| 屬性 | 類型 | 是否存在 | 值 / 說明 | |||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|
service.name |
string | 始終 | 固定爲 cursor |
|||||||||
service.version |
string | 可選 | 來源爲桌面端/命令行界面時的客戶端版本；cloud_agent / bugbot 通常不包含此項 |
|||||||||
cursor.team.id |
int | 始終 | 你的團隊 ID | |||||||||
cursor.surface |
string | 始終 | unspecified |
desktop |
cli |
cloud_agent |
bugbot |
|||||
cursor.entrypoint |
string | 始終 | unspecified |
desktop |
cli |
web |
mobile |
sdk_ts |
sdk_py |
api |
automation |
github_pr |
cursor.user.id |
int | 可選 | 如果來源提供用戶 ID，則爲不透明的團隊範圍用戶 ID。雲端代理通常不包含此項。請勿要求此項必須存在。 |
系列¶
系列 ID 與團隊設置中的開關一致。新目標默認全部開啓。
| 系列 ID | 信號 | 包含內容 |
|---|---|---|
model_usage |
指標 + 日誌 | token.usage, cost.usage; api.request, api.error, api.correction |
tool_calls |
指標 | tool.calls |
skills_hooks_plugins |
日誌 | skill.activated, hook.execution_complete, plugin.installed |
cloud_agents |
日誌 | cloud_agent.pull_request, cloud_agent.setup, cloud_agent.artifact, cloud_agent.mcp_auth_error |
指標¶
所有指標均爲單調遞增的 delta 總和。指標數據點不包含關聯 ID；關聯 ID 僅存在於日誌中。
應將指標視爲每個序列的 delta 總和。一個序列由資源、指標名稱和完全一致的數據點屬性集定義。同一序列的時間窗口可能會跨多次 flush 重疊。
cursor.token.usage¶
單位：{token}。系列：model_usage。
| 屬性 | 類型 | 是否存在 | 值 / 說明 | |||
|---|---|---|---|---|---|---|
cursor.token.type |
string | 始終存在 | input |
output |
cache_read |
cache_creation |
cursor.model.name |
string | 可選 | 路由意圖歸併後的請求公有模型 (auto: 映射爲 Auto，thinking: 映射爲 Thinking，pro: 映射爲 Pro，premium: 映射爲 Premium；否則原樣保留) 。Bugbot 或源數據中沒有模型時不包含此字段。 |
|||
cursor.api.status |
string | 可選 | success |
errored |
aborted |
|
cursor.api.billable |
bool | 可選 |
cursor.tool.calls¶
單位 {call}。系列 tool_calls。每次成功完成工具調用時取值爲 1。
| 屬性 | 類型 | 是否存在 | 值 / 說明 | ||
|---|---|---|---|---|---|
cursor.tool.kind |
string | 始終 | builtin |
mcp |
|
cursor.tool.name |
string | 始終 | 內置 ID (例如 read、shell) 或客戶 MCP 工具名稱 (開放) |
||
cursor.tool.status |
string | 始終 | success |
failure |
aborted (MCP 不會報告 aborted) |
cursor.mcp.server.name |
string | 僅 MCP | 客戶定義的服務器顯示名稱 (開放) |
cursor.cost.usage¶
單位：USD (double) 。系列：model_usage。事件發生時的盡力估算費用，並非發票。可能會受 cursor.api.correction 修正。對於 BYOK (自帶密鑰)，這僅爲 Cursor Token 費率，不含 provider 支出。
| 屬性 | 類型 | 是否存在 | 值 / 說明 |
|---|---|---|---|
cursor.model.name |
string | 可選 | 與 token.usage 相同的摺疊規則 |
日誌事件¶
嚴重級別：INFO=9、WARN=13、ERROR=17。
通用日誌屬性¶
| 屬性 | 類型 | 是否存在 | 說明 |
|---|---|---|---|
cursor.event.id |
string | 始終 | **去重鍵。**不透明。在重試、worker 重啓和 Cursor Kafka 重放期間保持確定性。前綴 customer-telemetry:v1:... 是穩定的；請將整個 string 視爲不透明值。 |
cursor.source_event.id |
string | 始終 | 不透明的內部源標識。多個信號可能共用一個值。 |
cursor.request.id |
string | 可選 | 適用於 api.request、api.error、skill.activated、hook.execution_complete、plugin.installed。絕不適用於 api.correction 或 cloud_agent.*。 |
cursor.conversation.id |
string | 可選 | IDE/命令行界面：composer UUID。雲端代理：客戶可見的 bc-... 智能體 ID。用於跨 api、skill/hook 和 cloud_agent 日誌重建會話的連接鍵。 |
cursor.usage_event.id |
string | 可選 | 僅適用於 api.request / api.error / api.correction。用於關聯 Cursor 用量和計費導出的請求粒度鍵。 |
cursor.api.request¶
信息，響應體爲 api_request。模型系列爲 model_usage。
| 屬性 | 類型 | 是否必填 | 備註 |
|---|---|---|---|
cursor.api.request.input_tokens |
int | 始終 | |
cursor.api.request.output_tokens |
int | 始終 | |
cursor.api.request.cache_read_tokens |
int | 始終 | |
cursor.api.request.cache_creation_tokens |
int | 始終 | |
cursor.model.name |
string | 可選 | |
cursor.api.billable |
bool | 可選 |
cursor.api.error¶
ERROR，響應體爲 api_error。系列爲 model_usage。無原始錯誤消息。低基數的 kind 和 status 屬性已規劃；暫勿依賴這些屬性。
| 屬性 | 類型 | 是否存在 | 說明 |
|---|---|---|---|
cursor.model.name |
string | 可選 | |
cursor.api.billable |
bool | 可選 |
cursor.api.correction¶
WARN，響應體爲 api_correction_<kind>。系列爲 model_usage。計費結算：該用量事件被追溯爲不計費。按 cursor.usage_event.id 關聯，並將整個羣組排除在計費之外。特意不包含 cursor.model.name。
| 屬性 | 類型 | 是否存在 | 值 | |
|---|---|---|---|---|
cursor.api.correction.kind |
string | 始終 | not_billed_errored |
not_billed_aborted_before_timeout |
cursor.skill.activated¶
INFO，響應體爲 skill_activated。系列爲 skills_hooks_plugins。
| 屬性 | 類型 | 是否存在 | 值 / 說明 | |||||
|---|---|---|---|---|---|---|---|---|
cursor.skill.name |
string | 始終 | 客戶自定義 (開放) | |||||
cursor.skill.trigger |
string | 始終 | agent_read |
manually_attached |
skill_name_in_prompt |
|||
cursor.skill.source |
string | 始終 | unspecified |
workspace |
user |
builtin |
plugin |
claude |
cursor.plugin.name |
string | 可選 | 當技能來自插件時 |
cursor.hook.execution_complete¶
INFO (failed / timeout 時爲 ERROR) ，響應體爲 hook_execution_complete。系列：skills_hooks_plugins。
| 屬性 | 類型 | 是否必填 | 值 / 說明 | ||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|
cursor.hook.name |
string | 始終 | 由客戶配置 (開放) | ||||||||
cursor.hook.type |
string | 始終 | pre_tool_use |
post_tool_use |
post_tool_use_failure |
before_submit_prompt |
after_agent_response |
after_agent_thought |
stop |
subagent_start |
subagent_stop |
cursor.hook.outcome |
string | 始終 | success |
blocked |
failed |
timeout |
|||||
cursor.hook.duration_ms |
int | 始終 | |||||||||
cursor.plugin.name |
string | 可選 | 鉤子來自插件時 |
cursor.plugin.installed¶
INFO，響應體爲 plugin_installed。系列爲 skills_hooks_plugins。不含 conversation.id (安裝不屬於對話範圍) 。
| 屬性 | 類型 | 是否存在 | 值 / 說明 | ||
|---|---|---|---|---|---|
cursor.plugin.name |
string | 始終 | 打開 | ||
cursor.plugin.scope |
string | 始終 | unspecified |
public |
private_marketplace |
cursor.cloud_agent.pull_request¶
INFO (opened) / WARN (creation_failed) ，響應體爲 cloud_agent_pull_request_<kind>。系列爲 cloud_agents。conversation.id = bc-...。
| 屬性 | 類型 | 是否存在 | 值 / 說明 | |
|---|---|---|---|---|
cursor.cloud_agent.pull_request.kind |
string | 始終 | opened |
creation_failed |
cursor.cloud_agent.pull_request.number |
int | 僅 opened |
||
cursor.cloud_agent.pull_request.draft |
bool | 僅 opened |
creation_failed 已啓用。生產者逐步推出期間，opened 可能只包含部分字段。
cursor.cloud_agent.setup¶
INFO (started / completed) / ERROR (failed) ，響應體爲 cloud_agent_setup_<kind>。模型系列爲 cloud_agents。conversation.id = bc-...。
| 屬性 | 類型 | 是否存在 | 值 / 說明 | ||
|---|---|---|---|---|---|
cursor.cloud_agent.setup.kind |
string | 始終存在 | started |
completed |
failed |
cursor.cloud_agent.setup.duration_ms |
int | 終止類型中存在時 | completed / failed |
||
cursor.cloud_agent.setup.reason |
string | 僅 failed |
開放詞彙 (如 install_command_failed) |
cursor.cloud_agent.artifact¶
INFO，響應體 cloud_agent_artifact_created。模型系列 cloud_agents。conversation.id = bc-...。
| 屬性 | 類型 | 是否必填 | 值 / 說明 |
|---|---|---|---|
cursor.cloud_agent.artifact.file_name |
string | 始終 | Open |
cursor.cloud_agent.artifact.content_type |
string | 可選 | MIME |
cursor.cloud_agent.mcp_auth_error¶
ERROR，響應體爲 cloud_agent_mcp_auth_error。系列爲 cloud_agents。conversation.id = bc-...。
你連接的 MCP 服務器拒絕了本次運行的憑據。運行仍會繼續，但該服務器的工具調用將失敗。由於只有你能修復此集成，因此記爲 ERROR；請針對該 ERROR 設置告警，以便及時發現自動化和雲端代理在無提示的情況下失去 MCP 服務器。
| 屬性 | 類型 | 是否存在 | 值 / 說明 |
|---|---|---|---|
cursor.mcp.server.name |
string | 始終 | 用戶定義的服務器顯示名稱 (開放) ，例如 github。取值範圍與 cursor.tool.calls 數據點屬性相同。 |
標識與關聯¶
- 按
cursor.event.id對日誌去重。 - **會話重建：**按
cursor.conversation.id對日誌分組 (composer UUID 或bc-...)。 - 計費覈對粒度：
cursor.usage_event.id，涵蓋api.request/api.error/api.correction。 - 指標不包含這些 ID。請使用
api.request日誌獲取每個對話的令牌總數。
有關具體做法，請參閱設置頁面中的關聯會話。
傳遞語義¶
- 日誌採用至少一次傳遞。瞬時故障會在約 7 天內自動恢復；按
event.id去重。終止性拒絕 (持續性 4xx、無效負載) 不會重放。 - 指標採用至多一次傳遞。失敗的指標請求不會重試或重放。
- **不保證順序。**更正內容可能會在其所修正的請求之後到達；請按記錄時間戳排序。
- 支持 OTLP 部分成功。被拒絕的條目不會重新發送。
- 不會回填目標激活前的數據。導出上游的源數據保留期也約爲 7 天 (與傳遞重試窗口分開) 。
