> ## 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

> Send OpenTelemetry traces, metrics and logs of every Cosmos agent session to the observability platform you already use.

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

Trace Export sends a record of what your Cosmos agents do to your own observability platform, using [OpenTelemetry](https://opentelemetry.io/) (OTel). Use it to:

* **Debug** a failed or slow session: see every setup step, model request and tool call in order, with timing and errors.
* **Track usage and cost** by model, expert and user.
* **Alert** when something breaks, for example when an MCP server's credentials expire or a scheduled run fails.

OpenTelemetry is a vendor-neutral standard that most observability platforms support, including Datadog, Grafana Cloud, Honeycomb, Langfuse and [20 others](https://docs.augmentcode.com/cosmos/trace-export/providers.md). Cosmos follows the OpenTelemetry [GenAI](https://opentelemetry.io/docs/specs/semconv/gen-ai/) and [MCP](https://opentelemetry.io/docs/specs/semconv/gen-ai/mcp/) conventions, so these platforms recognize the data without extra setup.

## How it works

```mermaid theme={null}
flowchart LR
  A["Cosmos agent sessions"] --> C["Cosmos<br/>(redacts, applies your settings)"]
  C -- "traces → /v1/traces" --> D["Your observability platform"]
  C -. "metrics → /v1/metrics (optional)" .-> D
  C -. "logs → /v1/logs (optional)" .-> D
```

An organization admin adds a **destination**: your platform's OTLP endpoint and API key. From then on, Cosmos sends every session to it as the session runs. Augment doesn't store the exported data.

## Key terms

| Term | Meaning |
| - | - |
| **Session** | One Cosmos conversation with an agent. Each session is one **trace**. |
| **Run** | One response of the agent, from the message that started it to the end of the response. A session has one run per message. |
| **Span** | One step in a trace, with a start time, an end time and attributes. Runs, setup steps, model requests and tool calls are all spans. |
| **Setup step** | Work before the agent can respond, such as starting the environment, running the startup script or connecting an MCP server. |
| **Destination** | Where Cosmos sends the data: an OTLP/HTTP endpoint and its credentials. An organization can have up to five. |
| **Metadata** | Timing, status, errors, model names, token counts and tool names. Always sent. |
| **Content** | Prompts, responses, model inputs and tool inputs and outputs. Off by default; an admin turns on each level. |

## Which signal do I need?

Each destination always receives traces. Metrics and logs are optional and turned on per destination.

| Signal | Best for | Example question |
| - | - | - |
| **Traces** | Debugging one session in detail | "Why did this session take 12 minutes?" |
| **Metrics** | Dashboards, trends, cost and alerts | "What did each model cost this week, and is P99 latency rising?" |
| **Logs** | Searching and auditing individual events, and sending them to a SIEM | "Which scheduled runs failed yesterday, and why?" |

Metrics and logs are derived from the same sessions as traces. Turning them on doesn't record anything extra in Cosmos; it only sends the same activity in a form that's easier to chart or search.

## Get started

**1. Open Trace Export**

As an organization admin, open **Settings → Trace Export**.

**2. Add a destination**

Click **Add Destination**, pick your platform, and paste its API key. Turn on **Send metrics** and **Send logs** if you want them.

**3. Test and save**

Click **Add destination**. Cosmos sends a test span and saves and enables the destination when it's accepted.

**4. Run a session**

Start any session, then search your platform for `service.name` = `augment-cosmos`.

For every option, see [Set up Trace Export](https://docs.augmentcode.com/cosmos/trace-export/setup.md).

## What a session looks like

This example follows one session in which a user asks an expert to fix a flaky test, in a fresh cloud environment with a Linear MCP server.

1. The session starts. Cosmos starts the environment (`runtime_acquisition`), runs its startup script (`startup_script`) and connects the Linear MCP server (`initialize linear`).
2. The user's message starts a run (`invoke_agent Flaky Test Fixer`, named after the expert). Its `wait_for_agent` span covers the time until the agent received the message.
3. The agent's turn (`invoke_agent auggie`) asks the model what to do (`chat Claude Sonnet 4.5`, named as in the Cosmos model picker).
4. The agent reads a file (`execute_tool view`) and runs the tests (`execute_tool launch-process`), then asks the model again.
5. The agent delegates a search to a subagent. The tool call that starts it (`execute_tool agent`) is the parent of the subagent's span (`invoke_agent explore`), and the subagent's own tool calls sit under that. Subagents' model requests aren't traced yet, so their usage and cost aren't in the trace.
6. The agent replies and the run ends. When the session is archived, the `session` span ends.

```text theme={null}
session                                       2 h 05 min
├── runtime_acquisition                       41 s
├── startup_script                            18 s
├── initialize linear                         1.2 s      CLIENT
└── invoke_agent Flaky Test Fixer            4 min 10 s
    ├── wait_for_agent                        1 min 2 s
    └── invoke_agent auggie                   3 min 6 s
        ├── chat Claude Sonnet 4.5            3.2 s      CLIENT
        ├── execute_tool view                 0.4 s
        ├── execute_tool launch-process       12.8 s
        ├── chat Claude Sonnet 4.5            2.9 s      CLIENT
        └── execute_tool agent                25 s
            └── invoke_agent explore          24 s
                └── execute_tool grep         0.3 s
```

Durations are illustrative. Things to notice:

* **Setup time** is visible: the user waited 1 minute for `wait_for_agent` before the agent started working.
* **Every span has `gen_ai.conversation.id`**, the session ID, so you can find the whole session from any one span.
* **Model requests carry usage and cost**: token counts (`gen_ai.usage.*`), Augment credits (`cosmos.credits`), and cost in US dollars for dollar-billed organizations (`cosmos.cost_usd`). `gen_ai.response.model` is the public model ID, such as `claude-sonnet-4-5`, so platforms that price LLM calls can price these.
* **A failure has a reason**: a failed span has status `ERROR` and an [`error.type`](https://docs.augmentcode.com/cosmos/trace-export/reference#error-types), such as `mcp_auth` on `initialize linear` if the Linear credentials had expired. Setup steps carry the expert and the trigger, so you can tell it was this expert's scheduled run that broke.

For how to read and query these spans, see [Use your data](https://docs.augmentcode.com/cosmos/trace-export/use-your-data.md). For every span and attribute, see the [Export reference](https://docs.augmentcode.com/cosmos/trace-export/reference.md).

## Content and privacy

By default, Cosmos sends only metadata. An admin can turn on three content levels: **Conversation**, **Model inputs** and **Tool inputs and outputs**. Before anything leaves Cosmos, recognized credentials are redacted and private model reasoning is removed. See [Content and privacy](https://docs.augmentcode.com/cosmos/trace-export/content-and-privacy.md).

## Who can use it

* **Plans:** Enterprise and team organizations. Not available on individual plans.
* **Role:** organization admins configure it. Other members don't see the Trace Export page.

## Availability

Trace Export is in early access and behind a feature flag. Contact your Augment Solutions Architect to enable it for your tenant. The page, the supported providers and the exported data can change before general availability.

Not supported yet:

* **OTLP/gRPC and OTLP/JSON.** Cosmos sends OTLP/HTTP with protobuf only.
* **Configurable sampling.** There's no sampling setting. Cosmos sends every span it captures, but the agent stops creating new spans for a run after 2,000, so very long runs can be missing later model requests and tool calls (and their usage). To reduce volume, export only [selected experts](https://docs.augmentcode.com/cosmos/trace-export/setup.md#5-choose-which-sessions-to-export), or sample in your own OpenTelemetry Collector.
* **Keyless cloud authentication.** Destinations authenticate with request headers. Google Cloud Trace, AWS SigV4 and Azure Monitor identity federation aren't available.
* **Non-OTLP destinations**, such as Amazon EventBridge, webhooks or object storage. Send to an OpenTelemetry Collector and forward from there.
* **Replay.** Augment doesn't store exported data, so data that was dropped, or produced while a destination was disabled, can't be sent again.
* **Joining your application's traces.** Each Cosmos session starts its own trace; you can't pass in a trace context to make a session part of a trace in your own application. In the other direction, your [MCP servers can join Cosmos traces](https://docs.augmentcode.com/cosmos/trace-export/reference.md#mcp-attributes).
* **A truncation marker.** When content is shortened to fit, the span carries no attribute saying so.
* **An API or CLI for destinations.** Destinations are managed on the Trace Export page only.

## Next steps

> [card] [Set up Trace Export](https://docs.augmentcode.com/cosmos/trace-export/setup.md)
>
> Add a destination and choose what to send.

> [card] [Use your data](https://docs.augmentcode.com/cosmos/trace-export/use-your-data.md)
>
> Find sessions, count tokens and cost, build dashboards and alerts.

> [card] [Content and privacy](https://docs.augmentcode.com/cosmos/trace-export/content-and-privacy.md)
>
> What's sent, what's never sent, and how content is limited.

> [card] [Export reference](https://docs.augmentcode.com/cosmos/trace-export/reference.md)
>
> Every span, attribute, metric, log event and error type.


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