《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 用量流式傳輸到您的可觀測性技術棧。