@cursor/july 0.1.111 → 0.1.113

package/dist/docs/guides/opentelemetry.md

@@ -1,219 +1,150 @@
-# OpenTelemetry
+# Observe an agent with OpenTelemetry
 
-Agent SDK can push traces, metrics, and logs from the serve process to
-an OTLP collector you run. Point the process at the collector with
-standard `OTEL_EXPORTER_OTLP_*` environment variables, or pass the
-same options to `serve({ otel })`. Traces cover the inbound request,
-each turn, and every tool call.
+OpenTelemetry connects an agent turn to the observability system your
+team already uses. Once you configure an OTLP collector, each request,
+model turn, tool call, and subagent appears alongside token, tool, and
+cost metrics from the serve process.
 
-Export is opt-in. Nothing leaves the process until you set an endpoint.
+Export is opt-in. Nothing leaves the process until you configure a
+destination.
 
-## What does Agent SDK export?
+## Connect an OTLP collector
 
-| Signal | Default | What you get |
-| --- | --- | --- |
-| Traces | on | `agent_sdk.http` (per request) and `agent_sdk.turn` → `agent_sdk.tool` / `agent_sdk.subagent` |
-| Metrics | on | `cursor.token.usage`, `cursor.tool.calls`, `cursor.cost.usage`, plus `agent_sdk.*` session and turn counts |
-| Logs | off | Session events as log records. Prompt text, tool payloads, and failure messages stay off unless you opt in |
-
-Turn off a signal with `traces: false`, `metrics: false`, or `logs: false`
-on `serve({ otel })`. Logs also turn on when you set `OTEL_LOGS_EXPORTER` to
-anything other than `none`, or when you set the content flags below.
-
-## How do I turn OpenTelemetry export on?
-
-Set a collector URL in the serve process environment:
+Set the collector endpoint, start the agent, and send it a message. You
+should see an `agent_sdk.http` request span and an `agent_sdk.turn`
+trace, with any tool or subagent work nested under the turn.
 
 ```bash
 export OTEL_EXPORTER_OTLP_ENDPOINT=https://otel.example.com
-export OTEL_EXPORTER_OTLP_HEADERS="Authorization=Bearer …"
-```
+export OTEL_EXPORTER_OTLP_HEADERS="Authorization=Bearer $OTEL_TOKEN"
+export OTEL_SERVICE_NAME=incident-agent
 
-The default wire format is OTLP/HTTP protobuf. That matches
-[Cursor enterprise OpenTelemetry Export](https://cursor.com/docs/enterprise/opentelemetry-export).
-Set `OTEL_EXPORTER_OTLP_PROTOCOL=http/json` when your collector only
-accepts JSON. The runtime accepts `http/protobuf` and `http/json`.
-`grpc` falls back to protobuf and logs a warning.
-
-`OTEL_EXPORTER_OTLP_ENDPOINT` is the base URL. The runtime appends
-`/v1/traces`, `/v1/metrics`, and `/v1/logs`. If you pass a signal path,
-it is stripped back to the base first.
-
-To send each signal to a different collector, omit the base URL and set
-the per-signal vars:
-
-```bash
-export OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=https://traces.example.com/v1/traces
-export OTEL_EXPORTER_OTLP_METRICS_ENDPOINT=https://metrics.example.com/v1/metrics
-export OTEL_EXPORTER_OTLP_LOGS_ENDPOINT=https://logs.example.com/v1/logs
+agent-sdk serve --dir . --dev
 ```
 
-Optional:
-
-| Variable | Effect |
-| --- | --- |
-| `OTEL_SERVICE_NAME` | Resource `service.name`. Default `cursor` |
-| `OTEL_LOG_USER_PROMPTS=1` | Include user prompt text on logs and span events |
-| `OTEL_LOG_TOOL_CONTENT=1` | Include tool payloads and failure text (truncated) |
-
-`serve(dir, { otel: false })` turns export off even when env is set.
-
-You can pass the same options object to `serve(dir, { otel })`.
-Precedence is `serve({ otel })` over env.
+The default protocol is OTLP/HTTP protobuf. If you already call
+`serve()` from TypeScript, you can configure the same destination in
+code:
 
 ```ts
 await serve(dir, {
   otel: {
-    serviceName: "cursor",
+    serviceName: "incident-agent",
     exporters: [
       {
         url: "https://otel.example.com",
-        protocol: "http/protobuf",
-        headers: { Authorization: "Bearer …" },
+        headers: {
+          Authorization: `Bearer ${process.env.OTEL_TOKEN ?? ""}`,
+        },
       },
     ],
   },
 });
 ```
 
-Multiple `exporters` fan out to every destination. Restrict one
-destination with `signals: ["traces"]`.
+Use environment variables when you start the agent with
+`agent-sdk serve`. Use `serve({ otel })` when your TypeScript
+application starts the server itself.
 
-`defineOtel` / `agent/otel.ts` (`@cursor/july/internal/otel`) is
-factory-only. Discovery still loads that file for Cursor factory
-agents. It is not a public Agent SDK export.
+## Follow one conversation
 
-The companion skill is [`skills/otel/SKILL.md`](https://github.com/cursor/cursor/blob/main/packages/agent-serve/skills/otel/SKILL.md).
+Copy the complete session ID from the playground or session API, then
+filter your observability system on either `agent_sdk.session_id` or
+`cursor.conversation.id`. Every turn in that conversation carries the
+same value, including follow-ups and tool work.
 
-## What spans does a session produce?
+The trace shape stays small:
 
 ```text
-agent_sdk.http          inbound channel request (W3C traceparent)
-agent_sdk.turn          one root per turn (`agent_sdk.session_id` = session id)
-  ├─ agent_sdk.tool
-  └─ agent_sdk.subagent
-       └─ agent_sdk.tool
-```
-
-Conversational sessions stay on `session.waiting` and can take more
-turns, so there is no `agent_sdk.session` span — it would never end
-and OTel only exports ended spans. Each turn is its own root. Inbound
-HTTP is a separate SERVER span (it extracts W3C `traceparent`) and
-does not parent the turn, so the turn tree can export when the turn
-ends. Hosted flush ends that SERVER span before the one-shot export so
-`agent_sdk.http` is in the same batch.
-
-Turns that resume after restore, or a direct `callTool` with no
-`turn.started` in this process, open a synthetic turn span so tool
-calls still nest.
+request: agent_sdk.http
 
-## Which attributes land on the wire?
-
-Every signal carries these resource attributes:
-
-- `service.name` (`cursor` unless you override it)
-- `cursor.entrypoint=sdk_ts`
-- `cursor.surface=unspecified`
-- `agent_sdk.framework=@cursor/july`
-
-Span attributes (not process resource attributes — one serve process
-handles many sessions):
-
-- `agent_sdk.session_id` / `cursor.conversation.id`: the session id.
-  Search all turns for one conversation with `@agent_sdk.session_id`.
-
-Shared names (same keys as enterprise export):
-
-- `cursor.conversation.id`: the session id
-- `cursor.model.name`
-- `cursor.token.usage` with `cursor.token.type` of `input`, `output`,
-  `cache_read`, `cache_creation`, or `reasoning`
-- `cursor.tool.calls` with `cursor.tool.name`, `cursor.tool.kind`, and
-  `cursor.tool.status`
-- `cursor.cost.usage` (USD)
-
-Agent SDK only (`agent_sdk.*`): session id, agent name, turn id, channel,
-call id, subagent name, session mode, and HTTP duration
-(`agent_sdk.http.duration`).
+turn: agent_sdk.turn
+      |- agent_sdk.tool
+      `- agent_sdk.subagent
+         `- agent_sdk.tool
+```
 
-## How do I emit my own metrics?
+A conversation can produce several turn traces, so use the session ID
+as the join key instead of expecting one long-lived session span.
 
-`ctx.host.otel` is always present on tools, hooks, and channel
-handlers. Counters and histograms no-op when no meter is running.
-`setAttributes` still tags open turn/tool spans when a collector is
-attached.
+## Add domain telemetry
 
-Prefix metric names with your team or agent. First-party names
-(`cursor.token.usage`, `cursor.tool.calls`, `cursor.cost.usage`,
-`agent_sdk.session.count`, `agent_sdk.turn.count`,
-`agent_sdk.subagent.count`, `agent_sdk.http.duration`) and join keys
-(`cursor.conversation.id`, `agent_sdk.session_id`, `agent_sdk.agent`,
-`agent_sdk.turn_id`, `agent_sdk.framework`) are reserved. Custom spans
-are not on this
-surface.
+Use `ctx.host.otel` when your dashboard should answer questions the
+built-in telemetry cannot, such as which incident a turn handled or how
+long approval took. Attributes appear on the active turn and tool
+spans, while counters and histograms give you metrics to graph and
+alert on.
 
 ```ts
 ctx.host.otel.setAttributes({
-  "abc.ticket_id": "INC-123",
-  "abc.queue": "p1",
+  "support.ticket_id": "INC-123",
+  "support.queue": "p1",
 });
-ctx.host.otel.increment("abc.ticket.resolved");
-ctx.host.otel.record("abc.approval.duration_ms", 1420, {
+
+ctx.host.otel.increment("support.ticket.resolved", {
+  outcome: "fixed",
+});
+
+ctx.host.otel.record("support.approval.duration_ms", 1420, {
   outcome: "approved",
 });
 ```
 
-A session-bound host (tools and hooks) adds `cursor.conversation.id`
-and `agent_sdk.agent` for you. Tags merge: later `setAttributes` calls
-paint open spans and later first-party metrics.
-
-## What stays off the OpenTelemetry wire?
+This API is available in tools, hooks, and channel handlers. A
+session-bound context adds `cursor.conversation.id` and
+`agent_sdk.agent` automatically, so custom measurements join the
+first-party telemetry without extra plumbing.
 
-User prompts, tool arguments, tool results, and failure messages are
-omitted by default. Failure spans still record an error status with a
-generic message (`turn failed` / `session failed`).
+Prefix custom names with your team or agent. First-party metric names
+and join keys are reserved, and this surface does not create custom
+spans.
 
-Opt in with `OTEL_LOG_USER_PROMPTS=1` and `OTEL_LOG_TOOL_CONTENT=1`, or
-the matching `logs: { userPrompts, toolContent }` fields on
-`serve({ otel })`. Opted-in strings truncate at 2,048 characters.
+## Choose signals
 
-Deployment URLs from `agent.bound` stay off spans unless
-`toolContent` is on.
+Once export has a destination, traces and metrics are on by default;
+logs remain off until you opt in.
 
-## How does Agent SDK export relate to Cursor enterprise export?
+| Signal | What appears |
+| --- | --- |
+| Traces | HTTP requests, turns, tools, and subagents |
+| Metrics | Token usage, tool calls, cost, and Agent SDK session or turn counts |
+| Logs | Session events, after you enable log export |
 
-[Cursor enterprise OpenTelemetry Export](https://cursor.com/docs/enterprise/opentelemetry-export)
-is the team-admin path. Cursor servers send org-wide metrics and logs
-to a collector you configure in Team Settings.
+The first metrics to look for are `cursor.token.usage`,
+`cursor.tool.calls`, and `cursor.cost.usage`. Configure
+`traces: false`, `metrics: false`, or `logs: true` under
+`serve({ otel })` when you need a different signal mix.
 
-Agent SDK export is the process-local path. The serve process sends
-per-run traces, and optional metrics and logs, to a collector you
-point it at.
+## Control what leaves the process
 
-Point both at the same collector when you want one view. Group on
-`cursor.conversation.id`. Resource defaults (`service.name=cursor`,
-`cursor.entrypoint=sdk_ts`) keep the streams next to each other. The
-[wire reference](https://cursor.com/docs/enterprise/opentelemetry-export/wire)
-lists the shared attribute names.
+User prompts, tool arguments, tool results, and failure text stay off
+the wire by default. You still get trace structure, tool names and
+status, usage metrics, and generic failure status without exporting the
+underlying content.
 
-Evals (`defineEval`) stay the in-product regression check. OpenTelemetry
-is the graph in your observability stack.
+Turn on logs first, then opt into prompt or tool content separately:
 
-## What if another OpenTelemetry SDK is already running?
+```bash
+export OTEL_LOGS_EXPORTER=otlp
+export OTEL_LOG_USER_PROMPTS=1
+export OTEL_LOG_TOOL_CONTENT=1
+```
 
-OTel providers are process-global. If Cursor CLI, an extension host, or
-another library already registered a TracerProvider, MeterProvider, or
-LoggerProvider, Agent SDK reuses it. Run `serve` as its own process
-when the Agent SDK exporters should own the destination.
+`OTEL_LOG_USER_PROMPTS` exports user text. `OTEL_LOG_TOOL_CONTENT`
+exports tool inputs, outputs, and failure details. Enable either only
+when the collector's access and retention policies are appropriate for
+that data.
 
-Two mounts with different authored OTel configs fail at serve start.
-Configure once through `serve({ otel })` or env.
+The same controls are available as
+`logs: { userPrompts, toolContent }` under `serve({ otel })`.
 
-## What's next
+## Related
 
 - [`skills/otel/SKILL.md`](https://github.com/cursor/cursor/blob/main/packages/agent-serve/skills/otel/SKILL.md): compact
-  env / `serve({ otel })` reference for coding agents
-- [Hooks](/docs/reference/hooks.md): observe the same session event stream
-  in-process
-- [Deployment](/docs/deployment.md): env, secrets, and self-hosting
-- [Cursor enterprise OpenTelemetry Export](https://cursor.com/docs/enterprise/opentelemetry-export)
+  configuration and custom-metric reference for coding agents
+- [Hooks](/docs/reference/hooks.md): emit domain telemetry from session
+  events
+- [Deployment](/docs/deployment.md): set collector endpoints and secrets
+  on hosted or self-hosted agents
+- [Cursor enterprise OpenTelemetry Export](https://cursor.com/docs/enterprise/opentelemetry-export):
+  send organization-wide Cursor telemetry to the same collector