@cursor/july 0.1.109 → 0.1.112

package/dist/docs/guides/opentelemetry.md

@@ -1,232 +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_*` env, or author `agent/otel.ts`. 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
-or a `defineOtel` config.
+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 `defineOtel`. 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 …"
-```
-
-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.
+export OTEL_EXPORTER_OTLP_HEADERS="Authorization=Bearer $OTEL_TOKEN"
+export OTEL_SERVICE_NAME=incident-agent
 
-`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 or
-`agent/otel.ts` is set.
-
-## How do I author `agent/otel.ts`?
-
-Use `defineOtel` when you want the collector URL, headers, or sampling
-in the project instead of the environment:
+The default protocol is OTLP/HTTP protobuf. If you already call
+`serve()` from TypeScript, you can configure the same destination in
+code:
 
 ```ts
-import { defineOtel } from "@cursor/july/otel";
-
-export default defineOtel({
-  serviceName: "cursor",
-  exporters: [
-    {
-      url: "https://otel.example.com",
-      protocol: "http/protobuf",
-      headers: { Authorization: "Bearer …" },
-    },
-  ],
+await serve(dir, {
+  otel: {
+    serviceName: "incident-agent",
+    exporters: [
+      {
+        url: "https://otel.example.com",
+        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.
 
-You can also pass the same object to `serve(dir, { otel })`. Precedence
-is `serve({ otel })` over `agent/otel.ts` over env. An empty
-`defineOtel()` still records traces; export starts when
-`OTEL_EXPORTER_OTLP_*` or a factory-returned `exporters` list appears.
+## Follow one conversation
 
-Hosted deployments can bind secrets after startup. Pass a factory so
-flush can re-read them. The hosted handler constructs the OTLP client
-when it flushes and sends the queued batch.
+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.
 
-```ts
-export default defineOtel(() => resolveMyOtelConfig());
-```
-
-The companion skill is [`skills/otel/SKILL.md`](/docs/skills/otel.md).
-
-## 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
-```
+request: agent_sdk.http
 
-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.
-
-## 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("support.ticket.resolved", {
+  outcome: "fixed",
 });
-ctx.host.otel.increment("abc.ticket.resolved");
-ctx.host.otel.record("abc.approval.duration_ms", 1420, {
+
+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.
+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.
 
-## What stays off the OpenTelemetry wire?
+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.
 
-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`).
+## Choose signals
 
-Opt in with `OTEL_LOG_USER_PROMPTS=1` and `OTEL_LOG_TOOL_CONTENT=1`, or
-the matching `logs: { userPrompts, toolContent }` fields on
-`defineOtel`. Opted-in strings truncate at 2,048 characters.
+Once export has a destination, traces and metrics are on by default;
+logs remain off until you opt in.
 
-Deployment URLs from `agent.bound` stay off spans unless
-`toolContent` is on.
-
-## 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 `agent/otel.ts` files fail at serve start.
-Use the same `defineOtel` config on every mount, or 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`](/docs/skills/otel.md): compact
-  `defineOtel` 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)
+- [`skills/otel/SKILL.md`](https://github.com/cursor/cursor/blob/main/packages/agent-serve/skills/otel/SKILL.md): compact
+  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