《Cursor文档》-OpenTelemetry 导出

OpenTelemetry 导出会将团队的 Cursor 用量数据流式传输到您自行运行的收集器。Cursor 会将指标 (token、工具调用、尽力估算的成本) 和日志 (API 请求、错误、修正、技能、钩子、插件及云端代理生命周期事件) 发送至一个由团队管理的导出目标。导出在服务器端运行。

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

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

前提条件¶

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

源 IP 地址¶

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

IP 地址	CIDR
3.218.161.44	/32
3.231.18.206	/32
35.174.159.35	/32
184.73.225.134	/32
3.209.66.12	/32
52.44.113.131	/32

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

收集器配置示例¶

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

最简 OpenTelemetry Collector¶

receivers:
  otlp:
    protocols:
      http:
        endpoint: 0.0.0.0:4318

processors:
  batch:

exporters:
  # 替换为你自己的数据接收端（datadog、clickhouse、logging 等）
  logging:
    verbosity: basic

service:
  pipelines:
    metrics:
      receivers: [otlp]
      processors: [batch]
      exporters: [logging]
    logs:
      receivers: [otlp]
      processors: [batch]
      exporters: [logging]

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

Datadog Agent (OTLP 接收)¶

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

logs_enabled: true

otlp_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。

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

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

Databricks 和数据仓库类接收端¶

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

启用¶

在 团队设置 > OpenTelemetry 导出 中：

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

每个信号和遥测类别都有各自的开关。除非关闭 auto_enable_new_families，否则新类别默认启用。

Cursor 导出的内容¶

范围：cursor.telemetry 0.1.0。

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

指标 (增量时序)

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 服务器拒绝了此次运行的凭据

类别 (管理员开关；默认全部启用)

model_usage：token 和成本指标；api.request / api.error / api.correction
tool_calls：tool.calls 指标
skills_hooks_plugins：技能 / 钩子 / 插件日志
cloud_agents：cloud_agent.* 日志

常用属性

资源：service.name=cursor、cursor.team.id、可选的 cursor.user.id、来源界面/入口点
日志：cursor.event.id (去重) ，以及存在时的 cursor.request.id / cursor.conversation.id / cursor.usage_event.id

传送¶

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

认证¶

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

限制¶

成本不等于计费。 cursor.cost.usage 是尽力而为的估算值。一个序列同时涵盖已包含配额的消耗和按需用量。对于 BYOK (自带密钥) ，它仅反映 Cursor Token 费率，不包括提供商费用。请通过 Admin 和计费 API 获取发票。
禁用或删除导出目标会丢失传输中的数据。 请通过编辑导出目标来轮换凭据，而非删除后重新添加。
日志可能会重复到达。 采用至少一次传送。请根据 cursor.event.id 去重。
不导出提示词内容、追踪信息或历史回填数据。 启用导出目标后才会开始导出。
指标数据点不携带关联 ID。 请使用日志属性按对话进行关联。参见关联会话。
指标仅提供增量数据。 对每个序列的增量求和。严格的增量转累计处理器可能会丢弃结束时间倒置的数据点。

关联会话¶

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

各 ID 的含义

cursor.conversation.id 是会话键。在 IDE 和 CLI 中，它是 composer 聊天的 UUID。对于云端代理，它是客户可见的 bc-... 智能体 ID。如果存在，相同的值会出现在该次运行的 api.request、api.error、skill.activated、hook.execution_complete 和 cloud_agent.* 日志中。
cursor.usage_event.id 是 api.request、api.error 和 api.correction 中按请求粒度划分的键。可用它与 Cursor 用量和计费导出数据进行核对，并应用修正。
cursor.request.id 是大多数日志中可选的每次调用 ID。它不会出现在 api.correction 或 cloud_agent.* 中。
cursor.event.id 仅用于去重，不可用于跨事件类型关联。

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

获取 cursor.api.request 日志行。按 cursor.conversation.id 分组，对 cursor.api.request.input_tokens 和 output_tokens 求和 (如有需要，也可包括缓存字段) 。这样可获得每个会话的 token 总数，这是指标无法提供的。
按该总和或估算成本对会话排序。
在相同的 cursor.conversation.id 上左连接其他日志：
- cursor.skill.activated 显示运行了哪些技能
- cursor.hook.execution_complete 显示钩子
- cursor.cloud_agent.* 显示设置、PR、工件和 MCP 身份验证失败 (仅限云端代理)
cursor.tool.calls 仅提供指标，因此不含对话 ID。从该指标报告整个组织的工具费率。按会话归因的工具数据尚未在线路中提供。

cursor.cost.usage 也仅提供指标。若要按成本对会话排序，可根据 api.request token 总数和您自己的费率进行估算，或从 Admin 和计费 API 获取支出，并在可用时通过 cursor.usage_event.id 关联。

操作方法：应用计费修正

查找 cursor.api.correction 日志。
通过 cursor.usage_event.id 与具有相同 ID 的 api.request 和 api.error 日志关联。
将整个组视为未计费。

注意事项

子智能体有自己的对话 ID。父级汇总尚未导出。
如果需要确保每条记录仅计入一次，请在关联前根据 cursor.event.id 对日志行去重。

变更策略¶

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

OpenTelemetry 导出适用于企业版方案¶

联系我们的团队，将 Cursor 用量流式传输到您的可观测性技术栈。