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 天 (与传递重试窗口分开) 。
