> ## Documentation Index
> Fetch the complete documentation index at: https://docs.augmentcode.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Trace Export reference

> Every span, attribute, metric, log event and error type that Cosmos Trace Export sends.

> [!NOTE]
>
> This feature is in early access and behind a feature flag. Contact your Augment Solutions Architect to enable it for your tenant

This page lists everything Trace Export sends. Attribute names follow the OpenTelemetry [GenAI](https://opentelemetry.io/docs/specs/semconv/gen-ai/), [MCP](https://opentelemetry.io/docs/specs/semconv/gen-ai/mcp/) and general semantic conventions. An attribute is sent only when it has a value, so not every span carries every attribute listed for it.

| Looking for | Go to |
| - | - |
| What a span name means | [Span names and kinds](#span-names-and-kinds), [Setup steps](#setup-steps) |
| An attribute on a span | [Session, run and agent spans](#session-run-and-agent-spans), [Model request spans](#model-request-spans), [Tool call spans](#tool-call-spans), [MCP attributes](#mcp-attributes) |
| Prompts, responses and tool output | [Content attributes](#content-attributes) |
| Why a span failed | [Error types](#error-types), [MCP server failures](#mcp-server-failures) |
| A metric | [Metrics](#metrics) |
| A log event | [Log events](#log-events) |

Attribute names follow OpenTelemetry conventions wherever one exists. Names starting with `cosmos.` are Cosmos-specific, for things OpenTelemetry has no name for: on spans, only `cosmos.trigger`, `cosmos.credits`, `cosmos.cost_usd` and `cosmos.system_prompt.hash`; plus Cosmos's own metrics and log event attributes.

## Resource and scope

Every request groups its spans by session and agent runtime version. Each group has one resource.

| | Traces | Metrics | Logs |
| - | - | - | - |
| `service.name` | `augment-cosmos` | `augment-cosmos` | `augment-cosmos` |
| `service.version` | The agent runtime version that produced the spans | Not set | The agent runtime version |
| `service.instance.id` | Not set | A random ID of the Cosmos server instance that sends the totals | Not set |
| Your resource attributes | Added after the above | Added after the above | Added after the above |
| Instrumentation scope | `augment.cosmos.agent_trace`, version `1` | `augment.cosmos.agent_trace.metrics`, version `1` | `augment.cosmos.agent_trace.events`, version `1` |
| Schema URL | `https://opentelemetry.io/schemas/1.37.0` | `https://opentelemetry.io/schemas/1.45.0` | `https://opentelemetry.io/schemas/1.37.0` |

## Spans

### Span names and kinds

| Span | Name | Kind | `gen_ai.operation.name` | Parent |
| - | - | - | - | - |
| Session | `session` | `INTERNAL` | — | Root of the trace |
| Run | `invoke_agent {expert name}`, for example `invoke_agent PR Fixer`. When the name isn't available, `invoke_agent {expert id}`; without an expert, `invoke_agent` | `INTERNAL` | `invoke_agent` | Session |
| Agent turn | `invoke_agent auggie` | `INTERNAL` | `invoke_agent` | Run, or session for a turn outside a run |
| Subagent | `invoke_agent {agent name}`, for example `invoke_agent explore` | `INTERNAL` | `invoke_agent` | The tool call that started it |
| Model request | `chat {model}`, using the model's name in the Cosmos model picker, for example `chat Claude Opus 5.5`. A request for the default model is named after the model that served it | `CLIENT` | `chat` | Agent turn. A retried request has one child `chat` span per attempt. Subagents' model requests aren't traced |
| Tool call | `execute_tool {tool name}` | `CLIENT` for MCP and hosted integrations (`gen_ai.tool.type` = `extension`), otherwise `INTERNAL` | `execute_tool` | Agent turn or subagent |
| MCP server connection | `initialize {server}` | `CLIENT` | — | Run, or session before the first run |
| MCP server not started | `mcp_server_unavailable {server}` | `INTERNAL` | — | Run or session |
| Setup step | See [Setup steps](#setup-steps) | `INTERNAL` | — | Run, or session when no run is open |

Tool and subagent names contain only letters, digits and `._:/-`, at most 128 characters (64 for agent names); a name that doesn't match is replaced with the bare operation, for example `execute_tool`. Expert and model picker names are display names: they're flattened to one line, cut to 128 bytes, and not sent at all if they contain something that looks like a credential.

### Setup steps

Setup spans cover the time before the agent can respond. Their names are fixed.

| Name | Step | Failure `error.type` |
| - | - | - |
| `wait_for_agent` | From accepting the message until a ready agent receives it. Child of the run | `wait_for_agent_failed` |
| `wait_for_capacity` | Waiting for capacity to start the environment | `wait_for_capacity_failed` |
| `runtime_acquisition` | Starting a fresh environment, resuming one, dispatching to a daemon, or picking a daemon from a pool | `runtime_acquisition_failed` |
| `secrets` | Loading secrets | `secrets_failed` |
| `git_credentials` | Setting up Git credentials | `git_credentials_failed` |
| `repository` | Preparing the repository | `repository_failed` |
| `startup_script` | Running the environment's startup script | `startup_script_failed` |
| `agent_install` | Installing the agent | `agent_install_failed` |
| `workspace` | Preparing the daemon workspace or worktree | `workspace_failed` |
| `agent_connect` | Connecting the agent | `agent_connect_failed` |
| `agent_initialization` | Initializing the agent | `agent_initialization_failed` |
| `tool_initialization` | Starting tools that aren't MCP servers | `tool_initialization_failed` |
| `initialize {server}` | Connecting to an MCP server (MCP `initialize`). `mcp.method.name` = `initialize` | One of the [MCP server failures](#mcp-server-failures) |
| `mcp_server_unavailable {server}` | An MCP server the agent didn't try to connect, for example because its credentials weren't available or its name collided with another server | One of the [MCP server failures](#mcp-server-failures) |

`{server}` is the MCP server's name. For a server the agent couldn't load and never learned the name of, it's the partner's catalog name, such as `atlassian`, or `config-` and the first 8 characters of the server's configuration ID.

Setup steps under a run carry the run's `gen_ai.agent.id` and `cosmos.trigger`, so a failed step tells you which expert and trigger it affected. Steps before the first run, or between runs, carry the session's `gen_ai.agent.id` and no trigger.
\| `prepare_runtime` | Any other setup | `prepare_failed` |

### Attributes on every span

| Attribute | Type | Description |
| - | - | - |
| `gen_ai.conversation.id` | string | The Cosmos session ID. Same on every span of the session |
| `gen_ai.operation.name` | string | `invoke_agent`, `chat` or `execute_tool`, on those spans |
| `error.type` | string | Why the span failed. Set only on failed spans. See [Error types](#error-types) |
| `user.id`, `user.email` | string | The user the session belongs to. Only with **Include user identity** on |

### Session, run and agent spans

| Attribute | Type | Spans | Description |
| - | - | - | - |
| `gen_ai.agent.id` | string | Session, run, agent, setup | The ID of the expert the session was started from. Stays the same when the expert is renamed |
| `gen_ai.agent.version` | string | Run, agent | The expert revision |
| `gen_ai.agent.name` | string | Run, agent | On runs, the expert's display name. On agent spans, the agent's name: the main agent is `auggie`, subagents have their own names |
| `cosmos.trigger` | string | Run, agent, setup | What started the run: `user_message`, `automation`, `schedule`, `delegation` or `api` |
| `os.type` | string | Session, run, agent, setup | The environment's operating system |
| `host.arch` | string | Session, run, agent, setup | The environment's CPU architecture |

The run span has an `agent_ready` event at the time the agent received the message. The time from the run's start to `agent_ready` is the setup time the user waited for.

A run started by another session, such as a delegated worker, has a link to the calling tool span, with the caller's session ID in the link's `gen_ai.conversation.id` attribute. A message that Cosmos refused because the organization or user hit a usage limit or ran out of credits produces a run span with `error.type` = `usage_limit_reached` or `credits_depleted`, linked to the run it would have started. These spans are a signal, not an audit log: Cosmos sends at most one per session and reason per minute, at most 60 per organization per minute from each Cosmos server, and none for other kinds of refusal.

### Model request spans

| Attribute | Type | Description |
| - | - | - |
| `gen_ai.provider.name` | string | The model provider, for example `anthropic` |
| `gen_ai.request.model` | string | The model requested, by its Cosmos model picker name, for example `Claude Opus 5.5` or `Prism (GPT)`. Empty for a request for the default model |
| `gen_ai.response.model` | string | The public ID of the model that responded, for example `claude-opus-5-5`, so your platform can price the request. For Prism, the model Prism routed to. Left out when Cosmos can't identify the model, and on requests that failed before any response |
| `gen_ai.response.finish_reasons` | string\[] | Why the model stopped, as reported by the provider. At most 8 values |
| `gen_ai.response.time_to_first_chunk` | double | Seconds until the first streamed chunk |
| `gen_ai.usage.input_tokens` | int | Input tokens, including tokens read from and written to the prompt cache. Attempt spans only |
| `gen_ai.usage.output_tokens` | int | Output tokens. Attempt spans only |
| `gen_ai.usage.cache_read.input_tokens` | int | Input tokens read from the prompt cache. Attempt spans only |
| `gen_ai.usage.cache_write.input_tokens` | int | Input tokens written to the prompt cache. Attempt spans only |
| `cosmos.credits` | double | Augment credits the attempt used. Attempt spans only; left out when 0 |
| `cosmos.cost_usd` | double | The attempt's cost in US dollars, for organizations billed in dollars. Attempt spans only |
| `cosmos.system_prompt.hash` | string | SHA-256 (hex) of the system instructions sent with the request, at every content level. Use it to see when the system prompt changed, or to group requests by prompt, without exporting the prompt |

Usage, credits and cost are on attempt spans only, so summing them over all `chat` spans never counts a retried request twice. A request that failed before any response carries no usage.

> [!WARNING]
>
> Subagents' model requests aren't traced yet. Their tokens, credits and cost are missing from `chat` spans, `cosmos.api.*` log events and the usage metrics (`gen_ai.client.token.usage`, `cosmos.token.usage`, `cosmos.credit.usage`, `cosmos.cost.usage`), so totals from Trace Export are lower than your bill for sessions that use subagents.

`cosmos.system_prompt.hash` is computed from the system instructions before redaction and before [content limits](https://docs.augmentcode.com/cosmos/trace-export/content-and-privacy.md#content-limits), so you can't always recompute it from `gen_ai.system_instructions`. Compare hashes with each other rather than with your own hash of the exported text.

### Tool call spans

| Attribute | Type | Description |
| - | - | - |
| `gen_ai.tool.name` | string | The tool name. For an MCP tool called through Cosmos's tool search, this is the underlying MCP tool's name, not the search tool's, so it can differ from the name in the session transcript |
| `gen_ai.tool.call.id` | string | The model's ID for this tool call |
| `gen_ai.tool.type` | string | `function` for built-in tools, `extension` for MCP servers and hosted integrations, or `datastore`, as the GenAI conventions define them |

### MCP attributes

On MCP tool calls (`mcp.method.name` = `tools/call`) and MCP server connections (`mcp.method.name` = `initialize`).

| Attribute | Type | Description |
| - | - | - |
| `mcp.method.name` | string | `tools/call` or `initialize` |
| `mcp.protocol.version` | string | The negotiated MCP protocol version |
| `rpc.response.status_code` | string | The JSON-RPC error code, when the call failed |
| `network.transport` | string | `pipe` for stdio servers, `tcp` or `unix` for remote ones |
| `network.protocol.name` | string | `http`, for remote servers |
| `server.address` | string | The MCP server's host |
| `server.port` | int | The MCP server's port |

**Trace context to MCP servers.** On each `tools/call` request, Cosmos sends the W3C `traceparent` of the tool call's span in `params._meta`, as the OpenTelemetry MCP conventions describe. If your MCP server is instrumented and sends to the same platform, its spans appear under the Cosmos tool call in the same trace.

### Content attributes

Sent only for the [content levels](https://docs.augmentcode.com/cosmos/trace-export/content-and-privacy.md#content-levels) an admin turned on, within the destination's [content limit](https://docs.augmentcode.com/cosmos/trace-export/content-and-privacy.md#content-limits). Values are JSON strings.

| Attribute | Level | Spans | Description |
| - | - | - | - |
| `gen_ai.input.messages` | Conversation | Agent turn (`invoke_agent auggie`) | The user's prompts for the turn |
| `gen_ai.output.messages` | Conversation | Agent turn | The agent's final response text |
| `gen_ai.input.messages` | Model inputs | Model request (`chat`) | The messages sent to the model: all of them, or only those added since the linked earlier request |
| `gen_ai.output.messages` | Model inputs | Model request | The model's response, including tool calls |
| `gen_ai.system_instructions` | Model inputs | Model request | The system instructions, when they changed since the linked earlier request |
| `gen_ai.tool.definitions` | Model inputs | Model request | The tools offered to the model, when they changed since the linked earlier request |
| `gen_ai.tool.call.arguments` | Tool inputs and outputs | Tool call (not a subagent's) | The tool's arguments |
| `gen_ai.tool.call.result` | Tool inputs and outputs | Tool call (not a subagent's) | The tool's result text |

A subagent's tool call spans carry timing, status and `error.type`, but no arguments or results, even with **Tool inputs and outputs** on.

**Model inputs** includes the results of earlier tool calls, because they're part of what the model is sent. Turning **Tool inputs and outputs** off doesn't remove that text from `gen_ai.input.messages` when **Model inputs** is on.

With **Model inputs**, consecutive model requests send only what changed. A model request span that continues an earlier one has a span link to it in the same trace. A model request without a link starts a new chain and carries its full input. This happens on purpose when the history no longer matches the previous request (for example after context compaction), after spans were lost on the way, or when the previous request's content wasn't fully captured.

To rebuild a request's full input, follow the links back to a span without one, then walk forward:

* **`gen_ai.input.messages`**: append each span's messages to the ones before. An empty list means no new messages.
* **`gen_ai.system_instructions`** and **`gen_ai.tool.definitions`**: a span sends them only when they changed. If a span doesn't have one, keep the earlier value. An empty list means it was removed.

> [!WARNING]
>
> Reconstruction is exact only when no span in the chain was shortened by the destination's **Max content size**. Shortening drops system instructions and tool definitions first, then the earliest new messages, then cuts long text, and the span carries no marker saying so. A dropped `gen_ai.system_instructions` then looks like "unchanged", and dropped messages are simply missing. If you rebuild model inputs, leave **Max content size** empty (the full capture limit), and treat `cosmos.system_prompt.hash` as the reliable signal for when the system prompt changed.

### Status

| Outcome | Span status | `error.type` |
| - | - | - |
| Completed | `OK` | — |
| Failed | `ERROR`, with a status message | Set |
| Stopped by a user, automation or parent agent | `ERROR` | `cancelled` |
| Never ended because the agent or environment stopped first | `ERROR` | For example `runtime_lost`, or `interrupted` |
| Session archived, deleted or idle for 24 hours | `OK` | — (the normal end of a session) |
| Still running (provisional session span) | `OK` | — |

### Values and limits

* Cosmos also accepts `gen_ai.request.max_tokens`, `gen_ai.request.temperature`, `gen_ai.request.top_p`, `gen_ai.request.stream`, `gen_ai.usage.reasoning.output_tokens`, `process.exit.code`, `jsonrpc.request.id` and `network.protocol.version`, but the current Cosmos agent doesn't send them, so don't build dashboards on them yet. Reasoning tokens are counted in `gen_ai.usage.output_tokens`.

* Free-text values, such as `gen_ai.agent.name` and status messages, have credentials, emails, paths and long identifiers redacted. Attributes are cut to 256 characters and status messages to 1 KB. Identifiers, model names and enumerated values must match a fixed format, or the attribute isn't sent.

* A span has at most 64 attributes.

* Attribute names and values are checked against an allowlist. Anything not listed on this page isn't sent, including Cosmos-internal identifiers, environment and infrastructure details, and model reasoning text.

## Error types

`error.type` is a short, low-cardinality value, safe to group and alert on.

| Value | Spans | Meaning |
| - | - | - |
| `cancelled` | Run, agent, tool | Stopped by a user, an automation or a parent agent, or the session was archived, deleted or idle |
| `runtime_lost` | Run | The environment stopped before the run finished |
| `agent_error` | Run | The agent failed |
| `start_failed` | Run | The environment or agent failed to start |
| `usage_limit_reached` | Run | The organization or user reached a usage limit |
| `credits_depleted` | Run | The organization ran out of credits |
| `rejected` | Run | Cosmos refused the message |
| `timeout` | Tool | The tool call timed out |
| `interrupted` | Any | The span never ended because the agent stopped first |
| `{step}_failed` | Setup | A [setup step](#setup-steps) failed, for example `startup_script_failed` or `repository_failed` |
| `prepare_failed` | Setup | Another setup step failed |
| `mcp_*` | MCP connection | An MCP server failed to connect. See [MCP server failures](#mcp-server-failures) |
| `_OTHER` | Any | A failure with no more specific type |

Model request and tool spans carry the error type the agent classified:

| Spans | Values |
| - | - |
| Model request (`chat`) | `rate_limited`, `context_length_exceeded`, `provider_overloaded`, `provider_unavailable`, `auth_error`, `timeout`, `invalid_request`, `content_filtered`, `network_error`, or `model_error` when unclassified |
| MCP tool call | When the call itself failed: the JSON-RPC error code (for example `-32603`, also in `rpc.response.status_code`), the HTTP status (for example `401`), `timeout`, `connection_closed`, `cancelled`, a network error code (for example `ECONNREFUSED`), an error name, or `_OTHER`. When the call returned an error result: `auth_error`, `permission_denied`, `rate_limited`, `timeout`, `not_found`, `unavailable`, or `tool_error` when unclassified. So an authentication failure can appear as `401` or as `auth_error` |
| Other tool call | `timeout`, or `tool_error` |

### MCP server failures

A failed `initialize {server}` or `mcp_server_unavailable {server}` span has one of these 17 `error.type` values and its fixed status message. The server's own error text is never sent.

| `error.type` | Status message |
| - | - |
| `mcp_auth` | MCP server rejected the credentials; reconnect or re-authorize it. |
| `mcp_permission` | MCP server denied access, or tenant policy excludes it for this user. |
| `mcp_configuration` | MCP server configuration is invalid or incomplete. |
| `mcp_unavailable` | MCP server could not be reached; the cause was not identified. |
| `mcp_rate_limited` | MCP server rate-limited the connection (HTTP 429). |
| `mcp_timeout` | MCP server did not respond before the connection timed out. |
| `mcp_connection_refused` | MCP server refused the connection; check that it is running and the port is correct. |
| `mcp_dns` | MCP server host name could not be resolved. |
| `mcp_tls` | TLS handshake with the MCP server failed; check its certificate. |
| `mcp_not_found` | MCP server URL returned not found (HTTP 404); check the endpoint path. |
| `mcp_upstream_5xx` | MCP server returned a server error (HTTP 5xx). |
| `mcp_connection_reset` | MCP server closed the connection during initialization. |
| `mcp_command_not_found` | MCP server command was not found or is not executable; check the command and that it is installed. |
| `mcp_process_exited` | MCP server process exited during initialization; check its command, arguments and environment. |
| `mcp_protocol_error` | MCP server sent an invalid or unexpected MCP response during initialization. |
| `mcp_other` | MCP server failed to initialize. |
| `mcp_name_collision` | MCP server was not loaded: another server with the same name takes precedence. Rename or deselect one of them. |

`mcp_name_collision` isn't counted in `cosmos.mcp.connection.failures`, because the server with that name may be working.

## Metrics

Sent to `/v1/metrics` when **Send metrics** is on, every 60 seconds, with cumulative temporality. Histograms use explicit bucket boundaries. Metrics are derived from the same exported spans, so they follow the same **Sessions to export** and **Include user identity** settings.

| Metric | Type | Unit | Attributes |
| - | - | - | - |
| `gen_ai.client.inference.duration` | Histogram | `s` | `gen_ai.operation.name` (`chat`), `gen_ai.provider.name`, `gen_ai.request.model`, `gen_ai.response.model`, `error.type` |
| `gen_ai.client.inference.time_to_first_chunk` | Histogram | `s` | `gen_ai.operation.name`, `gen_ai.provider.name`, `gen_ai.request.model`, `gen_ai.response.model`. Successful requests only |
| `gen_ai.client.token.usage` | Histogram | `{token}` | `gen_ai.operation.name` (`chat`), `gen_ai.provider.name`, `gen_ai.request.model`, `gen_ai.response.model`, `gen_ai.token.type` (`input`, `output`). No `error.type` |
| `gen_ai.execute_tool.duration` | Histogram | `s` | `gen_ai.tool.name`, `gen_ai.tool.type`, `error.type` |
| `mcp.client.operation.duration` | Histogram | `s` | `gen_ai.operation.name` (`execute_tool`), `mcp.method.name`, `gen_ai.tool.name`, `mcp.protocol.version`, `network.transport`, `network.protocol.name`, `server.address`, `server.port`, `rpc.status_code`, `error.type`. MCP tool calls only |
| `gen_ai.invoke_agent.duration` | Histogram | `s` | `gen_ai.operation.name` (`invoke_agent`), `gen_ai.agent.name`, `error.type`. Counts runs, subagents, and agent turns outside a run. `gen_ai.agent.name` is the expert's name on runs and the subagent's name on subagents |
| `cosmos.token.usage` | Counter | `{token}` | `gen_ai.token.type` (`input`, `output`, `cache_read`, `cache_write`), `gen_ai.request.model`, `gen_ai.response.model`, `user.id`, `user.email` |
| `cosmos.credit.usage` | Counter (double) | `{credit}` | `gen_ai.request.model`, `gen_ai.response.model`, `user.id`, `user.email` |
| `cosmos.cost.usage` | Counter (double) | `USD` | `gen_ai.request.model`, `gen_ai.response.model`, `user.id`, `user.email`. Organizations billed in US dollars only |
| `cosmos.session.count` | Counter | `{session}` | `gen_ai.agent.id`, `user.id`, `user.email`. Counts each session's first run |
| `cosmos.mcp.connection.failures` | Counter | `{failure}` | `error.type` (an [MCP failure class](#mcp-server-failures)), `cosmos.mcp.server.name`, `gen_ai.agent.id`, `cosmos.trigger`. MCP servers that failed to connect, once per session or run |
| `otel.sdk.exporter.span.exported` | Counter | `{span}` | `otel.component.type` (`otlp_http_span_exporter`), `error.type`. Spans whose export finished; `error.type` is set for spans that were dropped |
| `cosmos.trace.span.dropped` | Counter | `{span}` | `error.type` (`agent_dropped`, `ingest_rejected`, `poseidon_dropped`). Spans dropped before export |

`user.id` and `user.email` are present only with **Include user identity** on. Without it, the `cosmos.*` usage counters are totals by model. The usage counters carry both the requested and the served model, so a request for the default model is attributed to the model that served it, and a fallback to another model is visible.

A new counter series first reports 0, then its total, so rate and increase functions count its first event.

`error.type` values on `otel.sdk.exporter.span.exported` are `queue_full`, `retry_exhausted`, `rejected`, `too_large`, `shutdown`, `destination_removed` and `policy_changed`.

### Histogram buckets

| Metrics | Boundaries |
| - | - |
| Inference, time to first chunk, tool | 0.01, 0.02, 0.04, 0.08, 0.16, 0.32, 0.64, 1.28, 2.56, 5.12, 10.24, 20.48, 40.96, 81.92 s |
| MCP | 0.01, 0.02, 0.05, 0.1, 0.2, 0.5, 1, 2, 5, 10, 30, 60, 120, 300 s |
| Agent | 0.1, 0.2, 0.4, 0.8, 1.6, 3.2, 6.4, 12.8, 25.6, 51.2, 102.4, 204.8, 409.6, 900, 1800, 3600, 7200, 14400, 43200, 86400 s |
| Token usage | 1, 4, 16, 64, 256, 1024, 4096, 16384, 65536, 262144, 1048576, 4194304, 16777216, 67108864 |

### Aggregating metrics

* Totals are cumulative per Cosmos server instance, identified by `service.instance.id`. Sum across instances, and use rate or increase functions rather than raw values.
* Each metric holds at most 2,000 attribute combinations per destination, or 10,000 for combinations with a user. Further combinations go to one series with `otel.metric.overflow` = `true`.
* Totals restart, with a new start time, after two hours without spans, and when **Sessions to export** or **Include user identity** changes.

## Log events

Sent to `/v1/logs` when **Send logs** is on. Each event is a log record with `EventName` and body set to the event name, the trace ID and span ID of the span it describes, and severity `INFO`, or `ERROR` when the span failed. Log events never contain content.

| Event | When | Time |
| - | - | - |
| `cosmos.session.start` | A session's first run starts | Run start |
| `cosmos.session.end` | A session ends (archive, delete, or 24 hours without a run) | Session end |
| `cosmos.agent.run` | A run ends | Run end |
| `cosmos.agent.setup` | A setup step ends, including MCP server connections | Step end |
| `cosmos.api.request` | A model request attempt succeeds | Request end |
| `cosmos.api.error` | A model request attempt fails | Request end |
| `cosmos.tool.result` | A tool call ends | Tool end |

Subagent spans and retried requests' parent spans have no events. A subagent's tool calls do have `cosmos.tool.result` events.

### Event attributes

| Attribute | Type | Events | Description |
| - | - | - | - |
| `gen_ai.conversation.id` | string | All | The session ID |
| `gen_ai.agent.id`, `gen_ai.agent.version` | string | All, when the span has them | The expert and its revision |
| `user.id`, `user.email` | string | All | Only with **Include user identity** on |
| `cosmos.success` | boolean | All except `cosmos.session.start` | Whether the step succeeded |
| `cosmos.duration_ms` | int | All except `cosmos.session.start` | Duration in milliseconds |
| `error.type` | string | All except `cosmos.session.start` | Set when the step failed |
| `cosmos.trigger` | string | `cosmos.session.start`, `cosmos.agent.run`, `cosmos.agent.setup` | What started the run: `user_message`, `automation`, `schedule`, `delegation` or `api`. Setup steps outside a run have none |
| `cosmos.setup.step` | string | `cosmos.agent.setup` | The setup span's name, for example `startup_script` or `initialize linear` |
| `cosmos.mcp.server.name` | string | `cosmos.agent.setup` | The MCP server, for MCP server steps |
| `gen_ai.provider.name`, `gen_ai.request.model`, `gen_ai.response.model` | string | `cosmos.api.*` | As on the model request span |
| `gen_ai.usage.*`, `gen_ai.response.time_to_first_chunk` | int, double | `cosmos.api.*` | As on the model request span |
| `cosmos.attempt` | int | `cosmos.api.*` | The attempt number, from 1 |
| `cosmos.credits` | double | `cosmos.api.*` | Augment credits for the request; left out when 0 |
| `cosmos.cost_usd` | double | `cosmos.api.*` | Cost in US dollars, for organizations billed in dollars |
| `gen_ai.tool.name`, `gen_ai.tool.type`, `gen_ai.tool.call.id`, `mcp.method.name`, `server.address`, `server.port` | | `cosmos.tool.result` | As on the tool call span |

## Test span

The connection test sends one span named `export_test`, status `OK`, with the resource attributes above and no other attributes. It has its own random trace ID.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.