OpenTelemetry Export Wire Reference

Companion to OpenTelemetry Export. Full wire surface: every metric, log event, attribute, enum, and presence rule.

The surface is additive. Tolerate unknown attributes, events, and enum values. Renames and removals get explicit notice.

Transport and scope

• OTLP/HTTP binary protobuf (application/x-protobuf), POST
• Endpoints: <base>/v1/metrics and <base>/v1/logs
• Scope: cursor.telemetry / 0.1.0

Resource attributes

One resource per (team, user, surface, entrypoint, surface version) grouping.

Families

Family ids match the toggles in Team Settings. All default on for a new destination except conversation_content, which is off until the team opts in and the destination turns on the toggle for each kind (see Conversation content).

The grok_bot_agent_actions family, and skill.activated when a Bot emits it, carry Action Recording data. They flow only after a team admin turns on Action Recording on the Grok Bot page of the dashboard. Privacy Mode (Legacy) forces recording off.

Metrics

All metrics are monotonic delta sums. Metric datapoints carry no correlation IDs; those appear on logs only.

Consume metrics as sums of deltas per series. A series is the resource, the metric name, and the exact datapoint attribute set. Windows for the same series can overlap across flushes.

cursor.token.usage

Unit {token}. Family model_usage.

cursor.tool.calls

Unit {call}. Family tool_calls. Value 1 per completed tool call.

cursor.cost.usage

Unit USD (double). Family model_usage. Best-effort estimated cost at event time, not an invoice. Subject to cursor.api.correction. For BYOK, this is the Cherri Code Token Rate only, not provider spend.

Log events

Severities: INFO=9, WARN=13, ERROR=17.

Common log attributes

cursor.api.request

INFO, body api_request. Family model_usage.

cursor.api.error

ERROR, body api_error. Family model_usage. No raw error messages. Low-cardinality kind and status attributes are planned; don't depend on them yet.

cursor.api.correction

WARN, body api_correction_<kind>. Family model_usage. Billing finalization: the usage event was retroactively not billed. Join on cursor.usage_event.id and drop the whole group for billing. Deliberately carries no cursor.model.name.

cursor.skill.activated

INFO, body skill_activated. Family skills_hooks_plugins.

A Bot reading a SKILL.md exports this same event with cursor.surface=grok_bot, and the record carries the shared grok_bot.* attributes so it joins the turn's other actions. cursor.skill.name is the skill's folder slug, cursor.skill.trigger is agent_read or skill_name_in_prompt (a skill invoked with / or @ is not recorded yet), and cursor.skill.source is builtin for Cherri Code-managed skills, plugin for installed plugin skills, user for the Bot's own, and otherwise classified as on every other surface. cursor.grok_bot.tool_call.id is the id of the Read that activated the skill and joins its tool_result row. Bot activations carry cursor.conversation.id and never cursor.request.id, and they flow only when Action Recording is on.

cursor.hook.execution_complete

INFO (ERROR for failed / timeout), body hook_execution_complete. Family skills_hooks_plugins.

cursor.plugin.installed

INFO, body plugin_installed. Family skills_hooks_plugins. No conversation.id (install is not conversation-scoped).

cursor.cloud_agent.pull_request

INFO (opened) / WARN (creation_failed), body cloud_agent_pull_request_<kind>. Family cloud_agents. conversation.id = bc-....

creation_failed is live. opened may be sparse while the producer rolls out.

cursor.cloud_agent.setup

INFO (started / completed) / ERROR (failed), body cloud_agent_setup_<kind>. Family cloud_agents. conversation.id = bc-....

cursor.cloud_agent.artifact

INFO, body cloud_agent_artifact_created. Family cloud_agents. conversation.id = bc-....

cursor.cloud_agent.mcp_auth_error

ERROR, body cloud_agent_mcp_auth_error. Family cloud_agents. conversation.id = bc-....

An MCP server you connected rejected the run's credentials. That server's tool calls failed while the run continued. ERROR because only you can fix the integration; alert on this to catch Automations and Cloud Agents silently losing an MCP server.

Shared grok_bot.* attributes

The bot itself is identified by cursor.conversation.id on every grok_bot.* record, and that value is the Bot's conversation id; cursor.grok_bot.subagent.id names a subagent when one acted. The grok_bot.* events carry Bot actions from Action Recording. Family grok_bot_agent_actions. Every record has cursor.surface=grok_bot.

Every event is metadata about an action, never its content. Tool arguments and results, file paths and names, message bodies and recipients, credentials, card details, and the Auto-review classifier's reasoning are never exported on these events; MCP arguments and results ship only as the opt-in cursor.conversation.tool_io record. The exceptions are named per event: the shell command text (secret-scrubbed and capped at 8 KiB), the normalized browser URL and page title, and bare hostnames. Every free-text field is scrubbed for credential shapes, payment card numbers, and OAuth tokens before it can reach your collector.

Each event also carries these attributes:

cursor.grok_bot.mcp_tool_call

INFO (ERROR for failure status), body grok_bot_mcp_tool_call. Family grok_bot_agent_actions. One MCP tool call made by a Bot. This row never carries tool arguments or results. For http calls, a team with tool I/O enabled receives them as two cursor.conversation.tool_io records, joined to this row on cursor.grok_bot.tool_call.id.

cursor.grok_bot.tool_call.id is present on every MCP call. Connector calls, including the browser tools on the Bot's computer, are recorded here and never as tool_result, so each tool call is recorded once.

cursor.grok_bot.shell_command

INFO (WARN when blocked), body grok_bot_shell_command. Family grok_bot_agent_actions. A shell command a Bot ran or was blocked from running. The record is written when the command settles and keeps the issue time as its timestamp, so a long command's record arrives well after its timestamp.

cursor.grok_bot.browser_navigation

INFO, body grok_bot_browser_navigation. Family grok_bot_agent_actions. conversation.id is the identifier for the Bot.

cursor.grok_bot.computer_use_session

INFO, body grok_bot_computer_use_session. Family grok_bot_agent_actions. Summary of one computer-use subagent session: counts and wall time only. No coordinates, typed text, or screenshots. cursor.grok_bot.turn.id is the parent turn that invoked the subagent, cursor.grok_bot.subagent.id the subagent itself, cursor.grok_bot.tool_call.id the invocation, and cursor.grok_bot.initiated_by is always subagent.

cursor.grok_bot.tool_result

INFO (success / cancelled), WARN (denied), ERROR (error), body grok_bot_tool_result. Family grok_bot_agent_actions. One settled builtin tool call made by a Bot (read, web_search, send_to_user, task, shell, ...). This is the row every builtin tool produces, so no tool a Bot can call goes unrecorded. Connector (MCP) calls are mcp_tool_call rows and never appear here.

cursor.grok_bot.tool_call.id joins the row to the tool_decision rows of the same call. One id can carry two tool_result rows when a call re-runs after a transient model-stream failure, so count distinct ids when counting calls.

Read outcome as "how the call returned", not "whether the action happened". The shells, browser and computer actions, and local-tool asks the person declined report a refusal as denied with error_category user_rejected. Mail, routine writes, connector file transfers, subagent launches, and cloud agent actions hand a refusal back to the model as text, so their tool_result reads success while the tool_decision row records the refusal.

cursor.grok_bot.tool_decision

INFO (allowed / held), WARN (denied / timed_out), body grok_bot_tool_decision. Family grok_bot_agent_actions. One decision about whether a Bot's tool call may run: who made it, through which approval mode, and what it was. A call can carry several decisions (Auto-review refuses to auto-allow, then a person answers the card), each its own record. They join the call's tool_result, mcp_tool_call, or computer_use_session row on cursor.grok_bot.tool_call.id. The classifier's rationale, the card copy, and the arguments never appear here.

What the sources mean:

• policy is every enforced Auto-review classification, allowed or denied, on any surface: the shells, connector calls, mail, routine writes, cloud agent and subagent launches. A classifier that fails or misses its deadline is a policy denied, and so is a review rule that sends a call to a person without classifying.
• human is what an Auto-review card ended with (approval_mode auto_review when the classifier escalated, ask_human when the surface always asks, such as product feedback, claiming a mail inbox, placing a phone call, or a Chrome cookie import), or a local-tool permission ask answered on the person's own computer (local_tool_permission). "Always" and "never" answers record as allowed and denied like a one-time answer.
• hook is a pre-tool hook's refusal.
• automatic is a call no gate spoke about, so every other builtin call that settled carries at least one decision. Three kinds of call carry none: a call the tool itself refused before any gate ran (its tool_result reads denied); a card the person answers after the turn has ended (a credential fill request, a secret request, or a virtual card request), because the answer arrives in a later turn; and a call cancelled before any gate spoke, since a cancelled call carries only the allowances and holds recorded before it was cut off. A virtual card request also ends the turn from inside its own call, so its tool_result reads cancelled.

A call Auto-review refused and a person then answered carries both rows, policy denied then human, in event.sequence order. There is no approver attribute: a Bot's cards are answered only by its owner, who is the record's cursor.user.id.

cursor.grok_bot.file_transfer

INFO (success), WARN (denied), ERROR (error), body grok_bot_file_transfer. Family grok_bot_agent_actions. One file move a Bot tried between its computer and another endpoint: the user's machine, a connected Google Drive, OneDrive, or Gmail account, or a read of a file on the user's machine straight into the Bot's context. Metadata only: which way, the far end, how many bytes moved, and how it settled. The path, the file name, and the content never export. A read of a file on the Bot's own computer is a tool_result row, not this event. cursor.grok_bot.tool_call.id joins the row to the call's tool_result and, for a refused move, to its tool_decision.

cursor.grok_bot.message_delivery

INFO (sent / held), ERROR (failed), body grok_bot_message_delivery. Family grok_bot_agent_actions. One outbound message from a Bot: to its user in the Grok Bot chat, to another of the user's Bots, to a Slack or Discord conversation the Bot was reached through, to outside email recipients, to the user's Mac Messages app, or onto a draft card the user sends or discards themselves. The row says where the message went and whether it got there, never what it said or to whom by name: no body, subject, recipient, attachment name, or length. cursor.grok_bot.tool_call.id joins the row to the tool_result of the same send call.

cursor.grok_bot.routine_run

INFO (success / cancelled), ERROR (error), body grok_bot_routine_run. Family grok_bot_agent_actions. One finished routine run by a Bot: which routine fired, why, how it ended, and how long it took. Cherri Code records the row when it closes the run (server provenance), so a run is recorded whether or not the Bot's computer was watching, and the row carries no box.id, event.sequence, or tool_call.id. It always carries cursor.grok_bot.initiated_by=routine and cursor.entrypoint=automation. Never the routine's prompt, its name, or the turn's text.

cursor.grok_bot.turn.id is the turn the run executed in, so the run's own tool_result, shell_command, and mcp_tool_call rows join on it. A run that executed as a routine subagent, or that failed before a turn was planned, carries no turn.id.

A run that pauses on an approval and is settled by the resumed turn, and a run that failed before any turn started, are not recorded. Action Recording is a team feature, so runs of a personal (team-less) owner are skipped like every other Bot action.

cursor.grok_bot.guardrail

INFO (continued), WARN (warned / stopped), body grok_bot_guardrail. Family grok_bot_agent_actions. A guardrail stepping in on a Bot turn: the loop detector tripping on repeated output or tool calls, a site's bot defense refusing the Bot's browser, or Auto-review stopping a tool call to ask a person and the wait that followed. Coded fields only; the classifier's rationale and the card's copy never export. The decision itself (Auto-review's refusal, the person's answer) is a tool_decision row and is never repeated here; an escalation row joins it on cursor.grok_bot.decision.id.

Rows ride WARN when the guardrail changed the turn (a nudge, a stop, a wait that ended refused or unanswered) and INFO when it only observed or the turn went on. One row per trip: a wall counts once per episode, so a page that stays on the same wall through reloads is one row.

An escalation is two rows for one card, in the order they happened. The tool_escalation row is the ask: a card was raised because a call under review could not run without a person. The pause row is the end of the wait: the person allowed (resumed) or refused (denied) the action, or nobody answered before the card expired or was withdrawn (abandoned). When the wait ended because a person stopped or redirected the turn instead of answering, the second row is interrupted. Both rows carry the escalated tool's cursor.tool.name, the call's cursor.grok_bot.tool_call.id, and the card's id as cursor.grok_bot.decision.id, the same value the human tool_decision row of that call carries, so the ask, the wait, and the answer join on one key.

cursor.grok_bot.tool_call.id is present on the escalation kinds and absent on the detections, which are not attributed to one tool call. A call Auto-review refused with no one to ask raises no card and carries only its tool_decision.

cursor.grok_bot.delegation

INFO (dispatched, completed with success or stopped), ERROR (completed with error), body grok_bot_delegation. Family grok_bot_agent_actions. Work a Bot handed to another agent and the result coming back: a background subagent it dispatched, or a Cherri Code cloud agent it launched or replied to. Ids and outcome only, never the prompt, the result text, or the delegate's own actions. A subagent's tool calls are its own grok_bot.* rows with initiated_by=subagent; a cloud agent's run is the cloud_agents family.

Two records per delegation share target_id: dispatched when the work was handed over, and completed when the result came back to the Bot. completed records take the turn that received the result as their turn.id, not the dispatching turn's. cursor.grok_bot.tool_call.id is the dispatching call (or the stop call on a subagent_stop record); it is on the dispatched record and on a subagent's completed record, and absent on a cloud agent's completion.

Known limits:

• Not recorded: a steer injected into a cloud agent's running turn (no new run), a launch or reply Cherri Code rejected, a cloud agent cancel, a run someone else started that the Bot only watches, and a routine's subagent waking its parent.
• A stopped subagent can still deliver an error completion afterwards, so one target_id can carry both a stopped and an error record.
• A cloud agent's completed record is best-effort: when the Bot re-watches an agent it launched in an earlier turn, the completion can carry kind cloud_agent_launch, and a launch re-watched mid-run can leave its dispatched without a completed. Pair the two records on target_id and tolerate a missing completion.
• Delivery is at-least-once like every grok_bot.* row: a launch, reply, or completion retried after a crash can record twice for one target_id. Dedupe on cursor.event.id first.

Conversation content

Family conversation_content. The conversation.* events are the only log records whose body is a payload (message text or one side of an MCP tool call) instead of a constant event name. Route on the log event name, as with every other family. cursor.conversation.user_message is a prompt, cursor.conversation.assistant_message is a response, and cursor.conversation.tool_io is the arguments or the result of an MCP tool call; don't parse the body to tell them apart.

Body. Scrubbed text. Messages are capped at 32 KiB and each side of a tool call at 8 KiB. cursor.conversation.content_truncated is set whenever the exported body is a prefix of the redacted text, whether the source crossed the cap or redaction pushed it over, and on tool_io also when scrubbing left a body within the cap unparseable.

Identity. Records carry the common log attributes. cursor.conversation.id joins them to the conversation's api.request, skill.activated, hook.execution_complete, cloud_agent.*, and grok_bot.* logs. The only user identifiers are the optional cursor.user.* resource attributes; the log attributes carry none. Don't depend on cursor.request.id, cursor.usage_event.id, or, on message records, cursor.grok_bot.turn.id; tool_io carries turn.id as a shared grok_bot.* attribute.

Surfaces. Cloud Agents and Grok Bot only. Cloud Agent conversations arrive with cursor.surface=cloud_agent on the resource. Grok Bot conversations arrive with cursor.surface=grok_bot, alongside the Bot's grok_bot.* action logs when Action Recording is on. tool_io is Grok Bot only. IDE, CLI, and desktop conversations are not on this family yet. Filter or route on cursor.surface.

Toggles. Each event flows only with the team opt-in and its destination toggle on: user_message needs Prompts, assistant_message needs Responses, and tool_io needs Tool I/O. The setup page covers the toggles.

All three events are INFO and carry these attributes:

cursor.conversation.user_message

INFO. Body: the scrubbed text of a user prompt.

cursor.conversation.assistant_message

INFO. Body: the scrubbed final assistant text for the response.

cursor.conversation.tool_io

INFO. Body: the scrubbed compact JSON of one side of an MCP tool call, at most 8 KiB. Two records per Grok Bot MCP tool call executed over http transport: the arguments record carries the JSON object the Bot sent, and the result record carries the connector's reply. On success that is the tool's text and structured content; on failure, the error, rejection, or denial message. Image bytes are replaced with their MIME type. stdio calls on the Bot's computer report metadata only and produce no tool_io record. Needs the destination's Tool I/O toggle in addition to the team opt-in.

Both records carry the shared grok_bot.* correlation attributes (provenance, turn.id, tool_call.id, event.sequence), so cursor.grok_bot.tool_call.id is present and joins them to the call's cursor.grok_bot.mcp_tool_call and cursor.grok_bot.tool_decision rows. cursor.tool.name, cursor.tool.status, and cursor.mcp.server.name repeat the metadata row's values so each record is readable on its own.

When cursor.conversation.content_truncated is true the body does not parse as JSON: it is a prefix of the redacted text, or scrubbing left it unparseable and Cherri Code exported it flagged instead of exporting a less-scrubbed body. Check the flag before parsing. Both sides pass the same scrubber as message text, plus a key-based pass that redacts the value of any JSON member or assignment whose key names a credential (password, passphrase, token, api_key, secret, secret_key, access_key, authorization, cookie, private_key, credentials, and compounds such as client_secret or x-api-key), whatever the value looks like. Header pairs count too: in [{"name":"Authorization","value":"Basic ..."}], the value sibling of a name, key, or header member on the list is redacted, as is the second item of a two-item array whose first is on the list (["password","..."]). Card fields held as numbers ("cvc": 123) become [REDACTED: Card], and ASCII \uXXXX escapes are decoded before scrubbing. A private-key block split across the items of one array (lines of a file, text blocks of a result) is redacted from its BEGIN line through its END line; one split across unrelated fields is not. The key-based pass reaches one level into JSON nested inside a string value; deeper re-encoded documents are scrubbed by value shape only. See MCP tool I/O for what the scrubber does not catch.

Identity and joins

Exported logs do not carry OpenTelemetry trace_id or span_id fields. Use cursor.conversation.id and cursor.grok_bot.turn.id for Bot and turn correlation. Metrics do not carry correlation ids; use api.request logs for per-conversation token totals.

See Joining sessions on the setup page for recipes.

Delivery semantics

• Logs are at-least-once. Transient failures recover automatically for about 7 days; dedupe on event.id. Terminal rejections (persistent 4xx, bad payloads) are not replayed.
• Metrics are at-most-once. Failed metric requests are not retried or replayed.
• No ordering guarantee. Corrections can arrive after the requests they amend; order by record timestamp.
• OTLP partial success is honored. Rejected items are not re-sent.
• No backfill from before destination activation. Source retention upstream of export is also about 7 days (separate from the delivery retry window).