OpenTelemetry 导出

OpenTelemetry 导出会将团队的 Cherri Code 用量数据流式传输到您自行运行的收集器。Cherri Code 会将指标 (token、工具调用、尽力而为的成本) 和日志 (API 请求、错误、修正、技能、钩子、插件、云端代理生命周期事件以及记录的 Grok Bot 操作) 发送至一个由团队管理的导出目标。团队还可以选择启用对话内容：即来自云端代理和 Grok Bot 的用户提示词和助手响应，以及 Grok Bot MCP 工具调用的参数和结果。导出在服务器端运行。

OpenTelemetry 导出适用于企业版方案。管理员可在 团队设置 > OpenTelemetry 导出 中配置。

Wire Reference 详细说明了每项指标、日志事件和属性。

前提条件

• 可通过 /v1/metrics 和 /v1/logs 接收 OTLP/HTTP protobuf 的 HTTPS 端点。Datadog Agent OTLP 接收、OpenTelemetry Collector 和 ClickHouse/ClickStack 均支持。
• 可供 Cherri Code 作为请求头发送的 Bearer token 或 API 密钥。
• 端点必须可从公共互联网访问。Cherri Code 通过一组固定的源 IP 出站。

源 IP 地址

Cherri Code 通过服务器端出站代理传输 OTLP。流量来自以下静态地址 (均为 /32) ：

这些 IP 地址如无提前通知不会轮换。请使用 TLS 和认证作为主要控制措施。如果网络有此要求，请添加 IP 允许列表。

收集器 配置示例

Cherri Code 会通过 OTLP/HTTP binary protobuf 将数据推送到您的收集器。gRPC 和 JSON 不受支持。在团队设置中输入 HTTPS 基础 URL 时，请勿添加 /v1 后缀；Cherri Code 会自动追加 /v1/metrics 和 /v1/logs。

最简 OpenTelemetry Collector

receivers:  otlp:    protocols:      http:        endpoint: 0.0.0.0:4318processors:  batch:exporters:  # 替换为你自己的数据接收端（datadog、clickhouse、logging 等）  logging:    verbosity: basicservice:  pipelines:    metrics:      receivers: [otlp]      processors: [batch]      exporters: [logging]    logs:      receivers: [otlp]      processors: [batch]      exporters: [logging]

在收集器前通过负载均衡器、入口或 otelcol 的 TLS 设置终止 TLS。在 Cherri Code 中输入 https://otel.example.com，而非 https://otel.example.com:4318/v1。如需认证，可在负载均衡器处处理，或配置让 Cherri Code 发送静态请求头，例如 Authorization: Bearer <token>。

Datadog Agent (OTLP 接收)

在 Datadog Agent 中启用 OTLP HTTP 接收和日志功能，然后通过 HTTPS 公开 Datadog Agent (或其前置网关) ：

logs_enabled: trueotlp_config:  receiver:    protocols:      http:        endpoint: 0.0.0.0:4318  logs:    enabled: true

等效环境变量为 DD_OTLP_CONFIG_RECEIVER_PROTOCOLS_HTTP_ENDPOINT=0.0.0.0:4318、DD_LOGS_ENABLED=true 和 DD_OTLP_CONFIG_LOGS_ENABLED=true。暴露端口 4318，或在 443 上终止 TLS 并代理到 4318。

在 Cherri Code 中，基础 URL 是此监听器前方的公共 https:// 端点。仅当网关要求时才添加 DD-API-KEY 或站点请求头；Datadog Agent 已在本地配置 api_key。

有关 Datadog Agent 配置详情，请参阅 Datadog Agent 中的 OTLP 接收。

Databricks 和数据仓库类接收端

对于 Databricks 或 ClickHouse 等数据仓库导出目标，请运行配备 OTLP HTTP 接收器和供应商导出器的收集器，或通过 HTTP 转发到您的数据摄取管道。Cherri Code 端保持不变：HTTPS 基础 URL 通过 /v1/metrics 和 /v1/logs 提供 protobuf 数据。将指标作为增量之和使用，并根据 cursor.event.id 对日志去重。

启用

在 团队设置 > OpenTelemetry 导出 中：

1. 创建导出目标，填写基础 URL (不含 /v1/...；路径会由 Cherri Code 追加) 和认证请求头
2. 测试连接以验证 URL 和认证信息
3. 启用。约一分钟后开始导出。

每个信号和遥测系列都有各自的开关。除非关闭 auto_enable_new_families，否则新系列默认启用。对话内容 是例外：在你启用之前它始终处于关闭状态。

对话内容

conversation_content 系列会将用户提示词和助手响应的文本以 cursor.conversation.user_message 和 cursor.conversation.assistant_message 日志的形式流式发送到你的收集器，还会将 Grok Bot MCP 工具调用的参数和结果以 cursor.conversation.tool_io 日志的形式流式发送。目前该系列仅支持云端代理和 Grok Bot，暂不包含 IDE、命令行界面 (CLI) 和桌面端对话。这是唯一包含消息文本或工具负载的系列。各记录的结构请参阅 Wire Reference。

开启团队级启用开关和 Conversation content 后，将导出以下内容：

• 两种日志事件。 cursor.conversation.user_message 包含用户提示词，cursor.conversation.assistant_message 包含最终的助手响应。事件名称表示角色，响应体即消息文本。
• 经过脱敏并限制大小。 Cherri Code 会在导出前对消息文本进行脱敏处理，并将每条消息的响应体限制在 32 KiB 以内。当导出的响应体仅为脱敏后文本的前缀部分时，cursor.conversation.content_truncated 为 true。
• 工具 I/O 单独导出。 开启对应开关后，cursor.conversation.tool_io 会额外导出 Grok Bot MCP 调用的参数和结果，每侧上限为 8 KiB。详见 MCP 工具 I/O。
• 身份标识与其他日志一致。 记录携带的 ID 与其他所有日志相同，包括可选的 cursor.user.* 资源属性。
• 仅限云端代理和 Grok Bot。 云端代理对话的标记为 cursor.surface=cloud_agent，Grok Bot 对话的标记为 cursor.surface=grok_bot。此系列暂不导出 IDE、命令行界面和桌面端对话。Grok Bot 消息与 grok_bot_agent_actions 系列相互独立，后者需要启用操作录制，导出的是操作而非消息。

MCP 工具 I/O

cursor.grok_bot.mcp_tool_call 日志可以证明某个 Bot 发起了一次 MCP 调用：调用了哪个服务器、哪个工具、是否成功以及耗时多久。但它从不包含 Bot 发送了什么、返回了什么，因此审阅人能看到发生了一次 Jira 转换，却看不到是哪个 issue 被移到了哪个状态。这些内容由 cursor.conversation.tool_io 承载，受导出目标上的 Tool I/O 开关控制。

启用前，Bot 的一次 Jira 调用在你的收集器中显示为一行 cursor.grok_bot.mcp_tool_call，其 cursor.tool.name 为转换工具的名称，cursor.tool.status 为 success。启用后，同一次调用还会额外生成两行 cursor.conversation.tool_io：direction=arguments 行包含 Bot 发送的 JSON，例如 issue key 和目标状态；direction=result 行包含 Jira 返回的内容。可通过 cursor.grok_bot.tool_call.id 关联这三行。

范围与限制：

• 仅为摘录，而非完整负载。 每一侧上限为 8 KiB。被截断的响应体是脱敏文本的前缀，带有 cursor.conversation.content_truncated 标记，且无法解析为 JSON。写入调用的开头部分 (对象 key、目标、新值) 通常能完整保留；较长的读取结果则会被截断。
• 结果内容。 调用成功时，结果记录包含工具返回的文本和结构化内容；失败时，则包含错误、拒绝或禁止消息。Cherri Code 会将图像字节替换为其 MIME 类型。
• 尽力脱敏机密信息。 Cherri Code 使用与 shell 命令和消息文本相同的基于模式的清理器：已知格式的凭据、PEM 块和电子邮件地址会被替换为 [REDACTED: ...] 标记，因此 assignee 地址会导出为 [REDACTED: Email]。此外，只要 JSON 成员的 key 名称表示凭据 (password、token、api_key 等；完整列表见 Wire Reference) ，无论其值形式如何，都会被脱敏。模式匹配无法识别所有机密信息或个人数据。位于列表外 key 下的凭据、拆分到多个字段的凭据，或位于成员名称不常见的请求头行中的凭据 ({"k":"Authorization","v":"Basic ..."}) 都会原样导出；引用队友消息的参数，或包含连接器响应体的结果同样如此。与提示词和响应一样，这部分残余风险由你的团队自行承担。
• 仅限托管连接器调用。 只有由 Cherri Code 运行的 Grok Bot MCP 调用 (Jira、Slack、Linear 及其他托管服务器；其 mcp_tool_call 行显示 cursor.grok_bot.mcp.transport=http) 会生成工具 I/O。Bot 计算机上的 stdio 服务器、内置工具，以及云端代理、IDE 和 CLI 的工具调用目前暂不上报负载。

Cherri Code 导出的内容

范围：cursor.telemetry 0.1.0。

对于新的导出目标，除 conversation_content 外，以下内容默认均已启用。在团队设置中关闭各个系列。

指标 (增量时序)

• cursor.token.usage：按 cursor.token.type (input / output / cache_read / cache_creation) 区分
• cursor.tool.calls：内置工具和 MCP (cursor.tool.kind)
• cursor.cost.usage：尽力而为的 USD 估算，并非发票

日志

• cursor.api.request：模型调用摘要
• cursor.api.error：错误事件 (不含原始消息)
• cursor.api.correction：计费修正；通过 cursor.usage_event.id 关联
• cursor.skill.activated
• cursor.hook.execution_complete
• cursor.plugin.installed
• cursor.cloud_agent.setup：started / completed / failed
• cursor.cloud_agent.artifact
• cursor.cloud_agent.pull_request：opened / creation_failed
• cursor.cloud_agent.mcp_auth_error：MCP 服务器拒绝了此次运行的凭据
• cursor.grok_bot.tool_result：Bot 发起的每次内置工具调用，包括其结果和耗时
• cursor.grok_bot.tool_decision：由谁允许或拒绝了 Bot 的工具调用 (某个人、Auto-review 模式、钩子或无审批关卡)
• cursor.grok_bot.mcp_tool_call：Bot 连接器 (MCP) 工具调用
• cursor.grok_bot.shell_command：Bot shell 命令，经机密信息脱敏，包含退出码和耗时
• cursor.grok_bot.browser_navigation：Bot 浏览器导航到的页面
• cursor.grok_bot.computer_use_session：Bot 计算机使用会话摘要
• cursor.grok_bot.file_transfer：在 Bot 的计算机与用户设备或云账户之间传输的文件
• cursor.grok_bot.message_delivery：Bot 发送的消息、发送目的地以及是否送达
• cursor.grok_bot.routine_run：已完成的例程运行
• cursor.grok_bot.guardrail：检测到循环、网站拦截 Bot，或审批请求及其等待时长
• cursor.grok_bot.delegation：Bot 移交给子智能体或云端代理的工作，以及返回的结果
• cursor.conversation.user_message：用户提示词，已脱敏；需手动启用
• cursor.conversation.assistant_message：助手响应，已脱敏；需手动启用
• cursor.conversation.tool_io：Grok Bot MCP 工具调用的一侧 (参数或结果)，已脱敏；需手动启用

cursor.grok_bot.* 事件，以及 Bot 读取技能时产生的 cursor.skill.activated，均携带 操作录制 数据。只有在团队管理员于仪表盘 Grok Bot 页面启用操作录制后，这些事件才会传输；这是一项团队设置，默认关闭，且隐私模式 (旧版) 会强制将其关闭。

录制的事件仅为 Bot 行为的元数据，绝不包含其处理的内容。这些事件绝不会导出工具参数和结果、文件路径和名称、消息正文和收件人、凭据以及卡片信息；MCP 参数和结果仅通过需手动启用的 cursor.conversation.tool_io 记录发送。shell 命令文本经机密信息清理后导出，上限为 8 KiB；浏览器 URL 会去除查询字符串、片段和凭据；当工具作用于某个网站时，仅报告纯主机名。Wire Reference 列出了每个事件的全部属性。

cursor.conversation.* 事件携带消息文本或工具负载，只有在团队选择启用且导出目标打开对应类型的开关后才会传输。参见 对话内容 和 MCP 工具 I/O。

系列 (管理员开关；除 conversation_content 外默认全部启用)

• model_usage：token 和成本指标；api.request / api.error / api.correction
• tool_calls：tool.calls 指标
• skills_hooks_plugins：技能 / 钩子 / 插件 日志，包括 Bot 的技能激活
• cloud_agents：cloud_agent.* 日志
• grok_bot_agent_actions：grok_bot.* 操作日志；需要操作录制 (企业版)
• conversation_content：conversation.* 消息和工具 I/O 日志；默认关闭

常用属性

• 资源：service.name=cursor、cursor.team.id、来源界面/入口点，以及可选的 cursor.user.id、cursor.user.account_id 和 cursor.user.email；如需将记录归属到具体人员，参见 关联会话。Grok Bot 流量在所有系列中均以 cursor.surface=grok_bot 导出；desktop 不再包含此类流量。由例程启动的轮次以 cursor.entrypoint=automation 导出。
• 日志：cursor.event.id (去重) ，以及存在时的 cursor.request.id / cursor.conversation.id / cursor.usage_event.id
• Grok Bot 日志：cursor.grok_bot.turn.id、cursor.grok_bot.event.sequence、cursor.grok_bot.tool_call.id 和 cursor.grok_bot.decision.id；参见 关联会话

传送

• 指标采用至多一次传送。发生故障后，增量总和可能会短暂出现缺口。
• 日志采用至少一次传送。对 cursor.event.id 去重，以实现恰好一次的视图。
• 不会补填导出目标创建之前的数据。
• 编辑端点或凭据不会影响导出目标。禁用或删除导出目标会丢弃传输中的数据。

认证

Cherri Code 会以加密形式存储请求头。要轮换凭据，请编辑导出目标并保存。更改将在约 30 秒后生效。

限制

• 成本不等于计费。 cursor.cost.usage 是尽力而为的估算值。一个序列同时涵盖已包含配额的消耗和按需用量。对于 BYOK (自带密钥) ，它仅反映 Cherri Code Token 费率，不包括提供商费用。请通过 Admin 和计费 API 获取发票。
• 禁用或删除导出目标会丢失传输中的数据。 请通过编辑导出目标来轮换凭据，而非删除后重新添加。
• 日志可能会重复到达。 采用至少一次传送。请根据 cursor.event.id 去重。
• 除非你启用，否则不导出提示词内容或工具负载。 消息文本以及 MCP 工具的参数和结果仅通过启用的 conversation_content 系列发送。其他所有日志事件只携带 id、计数和低基数属性。参见对话内容和 MCP 工具 I/O。
• 不导出追踪上下文或历史补填数据。 导出的日志不携带 OpenTelemetry 的 trace_id 或 span_id 字段，Cherri Code 也不会发送追踪数据。启用导出目标后才会开始导出。
• 指标数据点不携带关联 ID。 请使用日志属性按对话进行关联。参见关联会话。
• 指标仅提供增量数据。 对每个序列的增量求和。严格的增量转累计处理器可能会丢弃结束时间倒置的数据点。

关联会话

指标 (cursor.token.usage、cursor.tool.calls、cursor.cost.usage) 均为聚合数据。数据点不包含 conversation.id、request.id 或 usage_event.id。这样可将指标基数控制在有限范围内。如需按会话或请求进行分析，请使用日志。

各 ID 的含义

• cursor.conversation.id 是会话键。在 IDE 和命令行界面中，它是 composer 聊天的 UUID。对于云端代理，它是客户可见的 bc-... 智能体 ID。对于 Grok Bot (grok_bot.* 以及任何带有 cursor.surface=grok_bot 的日志)，它是该 Bot 的标识符，此值同时也是该 Bot 的对话 ID。如果存在，相同的值会出现在该次运行的 api.request、api.error、skill.activated、hook.execution_complete、cloud_agent.*、grok_bot.* 以及 (在团队启用时) conversation.* 日志中。
• cursor.usage_event.id 是 api.request、api.error 和 api.correction 中按请求粒度划分的键。可用它与 Cherri Code 用量和计费导出数据进行核对，并应用修正。
• cursor.request.id 是大多数日志中可选的每次调用 ID。它不会出现在 api.correction、cloud_agent.* 或 grok_bot.* 中。
• cursor.event.id 仅用于去重，不可用于跨事件类型关联。

将记录归属到具体人员

cursor.user.account_id 是成员的 Admin API ID。将其与 GET /teams/members 响应中的 id 关联，即可确定记录对应的人员。cursor.user.email 可直接标识该成员。两者均为可选字段，且仅与 cursor.user.id 一同出现，因此请勿要求每条记录都包含它们。存在规则请参阅资源属性表。

对 Grok Bot 活动进行分组

有四个属性可将 Bot 的记录串联起来。cursor.grok_bot.turn.id 标识轮次：它出现在该轮次的每条 操作录制 日志中；当 cursor.surface=grok_bot 时，也会出现在该轮次的 api.request 和 api.error 日志中，因此模型调用可按轮次与操作关联。在同一轮次内，cursor.grok_bot.event.sequence 可在不依赖客户端时钟的情况下为操作排序；请按它而非时间戳排序，且不要假定其值连续。cursor.grok_bot.tool_call.id 用于将同一次工具调用的各行归为一组，cursor.grok_bot.decision.id 则关联批准请求、对该请求的等待以及用户的答复。

子智能体的操作带有各自的 cursor.grok_bot.turn.id 和 cursor.grok_bot.subagent.id，以及 cursor.grok_bot.root_turn.id，即其所服务的面向用户的轮次。按 root_turn.id 分组，可将子智能体的操作汇总到生成它的轮次。

例如，在某个轮次中，Bot 运行了一条命令，而 Auto-review 模式将其上报给用户审批，该轮次可能产生以下记录：

所有行共享该 Bot 的 cursor.conversation.id。按 turn-1 分组可还原整个轮次，包括其中的模型调用。按 call-7 分组可追踪这一次 shell 调用：Auto-review 模式拒绝了该调用，随后卡片向用户请求确认，用户予以批准，工具运行并返回 success。card-2 将请求确认及其等待过程与用户的答复关联起来。命令文本本身位于该轮次的 cursor.grok_bot.shell_command 行中，该行不含 tool_call.id。这些字段是自定义日志属性，而非 OpenTelemetry 的 trace id 或 span id。

启用对话内容后，该 Bot 的 cursor.conversation.user_message 和 cursor.conversation.assistant_message 日志会带有相同的 cursor.conversation.id。基于该字段关联，即可将提示词和响应与 Bot 的模型请求及录制的操作对照查看。消息日志带有自己的可选字段 cursor.conversation.turn.id，请勿依赖其中的 cursor.grok_bot.turn.id 或 cursor.request.id。

启用 MCP 工具 I/O 后，每次 MCP 调用会额外生成两条 cursor.conversation.tool_io 日志 (direction=arguments 和 direction=result) ，其中带有该调用的 cursor.grok_bot.tool_call.id，以及 (如存在) 其 turn.id 和 event.sequence。按 tool_call.id 分组，即可将参数和结果与该调用的 mcp_tool_call 和 tool_decision 行对照查看。

方法：按 token 用量对会话排序，再关联技能和工具

1. 选取 cursor.api.request 日志行，按 cursor.conversation.id 分组，对 cursor.api.request.input_tokens 和 output_tokens 求和 (如有需要，也可加上缓存字段) 。由此可得到每个会话的 token 总量，这是指标无法提供的。
2. 按该总量或估算成本对对话排序。
3. 基于相同的 cursor.conversation.id 左连接其他日志：
   • cursor.skill.activated 显示运行了哪些技能
   • cursor.hook.execution_complete 显示钩子
   • cursor.cloud_agent.* 显示环境设置、拉取请求、产物以及 MCP 认证失败 (仅限云端代理)
   • cursor.grok_bot.* 显示 Bot 执行了哪些操作 (仅限 Grok Bot，且需开启操作录制)
   • cursor.conversation.user_message 和 cursor.conversation.assistant_message 显示提示词和响应 (仅限云端代理和 Grok Bot，且需选择启用 conversation_content)
   • cursor.conversation.tool_io 显示每次 Grok Bot MCP 调用发送和接收的内容 (仅限 Grok Bot，且需选择启用工具 I/O)
4. cursor.tool.calls 仅作为指标提供，因此不含对话 id。请基于该指标报告组织范围的工具费率。对于 Grok Bot，可通过 cursor.grok_bot.tool_result 和 cursor.grok_bot.mcp_tool_call 按 Bot 和按轮次进行工具归因；其他来源目前尚未传输此类数据。

cursor.cost.usage 同样仅作为指标提供。若要按成本对会话排序，可根据 api.request 的 token 总量和你自己的费率进行估算，或从 Admin and billing APIs 拉取支出数据，并在可用时基于 cursor.usage_event.id 进行关联。

方法：应用计费修正

1. 查找 cursor.api.correction 日志。
2. 基于 cursor.usage_event.id 关联具有相同 id 的 api.request 和 api.error 日志。
3. 将整组记录视为不计费。

注意事项

• 子智能体拥有各自的对话 id。对于 Grok Bot 的操作，可通过 cursor.grok_bot.root_turn.id 进行汇总；其他来源目前尚不导出父级汇总。
• 如需恰好一次的视图，请在关联前基于 cursor.event.id 对日志行去重。
• 旧版 Grok Bot 的记录不含 cursor.grok_bot.event.sequence 和 cursor.grok_bot.initiated_by，请将两者视为可选字段。

变更策略

随着覆盖范围扩大，可能会新增指标和事件。auto_enable_new_families 控制是否自动启用它们。重命名和移除会提前明确通知。Wire Reference 记录了完整的属性范围。