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 |
grok_bot |
|||||
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 |
grok_bot_agent_actions |
日志 | grok_bot.mcp_tool_call, grok_bot.shell_command, grok_bot.browser_navigation, grok_bot.computer_use_session |
指标¶
所有指标均为单调递增的 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.* 或 grok_bot.*。 |
cursor.conversation.id |
string | 可选 | IDE/命令行界面：composer UUID。云端代理：客户可见的 bc-... 智能体 ID。Grok Bot grok_bot.* 事件：Grok Bot 对话 ID。用于跨 api、skill/hook、cloud_agent 和 grok_bot 日志重建会话的连接键。 |
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 数据点属性相同。 |
共享的 grok_bot.* 属性¶
grok_bot.* 事件承载来自 Action Recording 的 Bot 操作，导出前已完成机密信息清理。所属系列为 grok_bot_agent_actions。每条记录均带有 cursor.surface=grok_bot。每个事件还包含：
| 属性 | 类型 | 是否存在 | 值 / 说明 | |
|---|---|---|---|---|
cursor.grok_bot.provenance |
string | 始终 | client (由 Grok Bot 主机上报) |
server (由 Cursor 观测) |
cursor.grok_bot.turn.id |
string | 可选 | 对话中的轮次 id | |
cursor.grok_bot.box.id |
string | 可选 | Grok Bot 电脑 id；来源为 server 时无此字段 |
cursor.grok_bot.mcp_tool_call¶
INFO (failure 状态时为 ERROR) ，响应体 grok_bot_mcp_tool_call。系列为 grok_bot_agent_actions。表示 Bot 发起的一次 MCP 工具调用。工具参数与结果不会被导出。
| 属性 | 类型 | 是否存在 | 值 / 说明 | |
|---|---|---|---|---|
cursor.tool.name |
string | 始终 | 客户定义的 MCP tool 名称 (开放取值) | |
cursor.tool.status |
string | 始终 | success |
failure |
cursor.grok_bot.mcp.transport |
string | 始终 | http (服务器侧观测) |
stdio (在计算机上) |
cursor.grok_bot.mcp.duration_ms |
int | 始终 | ||
cursor.mcp.server.name |
string | 可选 | 客户定义的服务器显示名称 (开放取值) | |
cursor.grok_bot.tool_call.id |
string | 可选 | Grok Bot 工具调用 的 id |
cursor.grok_bot.shell_command¶
INFO(被阻止时为 WARN),响应体 grok_bot_shell_command。系列 grok_bot_agent_actions。Bot 已运行或被阻止运行的 shell 命令。
| 属性 | 类型 | 是否存在 | 值 / 说明 | |
|---|---|---|---|---|
cursor.grok_bot.shell.command |
string | 始终 | 经机密信息清理的命令文本,最多 8 KiB(open) | |
cursor.grok_bot.shell.command_truncated |
bool | 始终 | 源命令超出上限时为 True | |
cursor.grok_bot.shell.kind |
string | 始终 | foreground |
background |
cursor.grok_bot.shell.target |
string | 始终 | box(Grok Bot 电脑) |
user_machine |
cursor.grok_bot.shell.allowed |
bool | 始终 | shell 策略判定结果 | |
cursor.grok_bot.shell.blocked_reason |
string | 可选 | 被阻止时的策略原因;经机密信息清理(open) | |
cursor.grok_bot.shell.classification_reasons |
string[] | 可选 | 最多 10 条策略分类原因;经机密信息清理(open) |
cursor.grok_bot.browser_navigation¶
INFO，响应体 grok_bot_browser_navigation。系列 grok_bot_agent_actions。conversation.id 为 Grok Bot 对话 ID。
| 属性 | 类型 | 是否存在 | 值 / 说明 |
|---|---|---|---|
cursor.grok_bot.browser.url |
string | 始终 | 规范化后的 scheme://host/path (open) 。非层级式 scheme 从不导出 |
cursor.grok_bot.browser.page_title |
string | 可选 | 经机密信息清理 (open) |
cursor.grok_bot.computer_use_session¶
INFO，响应体 grok_bot_computer_use_session。系列 grok_bot_agent_actions。仅包含次数和实际耗时，不含坐标、输入文本或屏幕截图。
| 属性 | 类型 | 是否存在 | 值 / 说明 |
|---|---|---|---|
cursor.grok_bot.computer_use.action_count |
int | 始终 | |
cursor.grok_bot.computer_use.duration_ms |
int | 始终 | |
cursor.grok_bot.computer_use.screenshot_count |
int | 始终 | |
cursor.grok_bot.tool_call.id |
string | 可选 | 子智能体调用的工具调用 id |
标识与关联¶
- 按
cursor.event.id对日志去重。 - **会话重建：**按
cursor.conversation.id对日志分组 (composer UUID、bc-...或 Grok Bot 对话 ID)。 - 计费核对粒度：
cursor.usage_event.id，涵盖api.request/api.error/api.correction。 - 指标不包含这些 ID。请使用
api.request日志获取每个对话的令牌总数。
有关具体做法，请参阅设置页面中的关联会话。
传递语义¶
- 日志采用至少一次传递。瞬时故障会在约 7 天内自动恢复；按
event.id去重。终止性拒绝 (持续性 4xx、无效负载) 不会重放。 - 指标采用至多一次传递。失败的指标请求不会重试或重放。
- **不保证顺序。**更正内容可能会在其所修正的请求之后到达；请按记录时间戳排序。
- 支持 OTLP 部分成功。被拒绝的条目不会重新发送。
- 不会回填目标激活前的数据。导出上游的源数据保留期也约为 7 天 (与传递重试窗口分开) 。
