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

# Set up Trace Export

> Add an OpenTelemetry destination in Cosmos, choose what to send, and check that traces arrive in your observability platform.

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

To send traces, add a *destination* on the Trace Export page. A destination tells Cosmos your platform's OTLP/HTTP traces endpoint and how to authenticate with it.

Setup takes about five minutes:

1. [Open Trace Export](#1-open-trace-export).
2. [Add a destination](#2-add-a-destination) and test it.
3. [Check that spans arrive](#3-check-that-spans-arrive).
4. Optional: [choose what content to send](#4-choose-what-to-send) and [which sessions to export](#5-choose-which-sessions-to-export).

## What you need

* **The admin role** in a Cosmos organization on an Enterprise or team plan.
* **An OTLP/HTTP endpoint** that accepts protobuf over HTTPS, at a public host name or public IP address. Cosmos sends from the cloud, so it can't reach `localhost`, private or reserved IP ranges, or internal names such as `*.local` or `*.internal`. If you run your own OpenTelemetry Collector, its OTLP/HTTP receiver listens on port 4318 by default. Expose it over HTTPS with a certificate from a public certificate authority.
* **Credentials for the endpoint**, such as an API key, sent as request headers.

> [!NOTE]
>
> Cosmos sends OTLP/HTTP, not OTLP/gRPC. A gRPC endpoint (usually port 4317) doesn't work.

## 1. Open Trace Export

In Cosmos, open **Settings**, then **Trace Export** in the **Organization** section. The page lists your destinations, at most five, and the organization-wide **Content** and **Sessions to export** settings.

## 2. Add a destination

Click **Add Destination** (or, before you have any destinations, a provider tile on the page). Pick your platform from the provider list, or paste its endpoint URL into the search box: Cosmos detects the provider and region from the host and opens its form with the endpoint filled in. Providers are grouped into **APM & observability**, **AI & LLM observability** and **Cloud**.

> [tab] Supported provider
>
> The provider form asks only for what that platform needs, such as its region and API key, and shows where to find each value in the platform. Each field's hint and the **Setup guide** link point to the vendor's own instructions.
>
> * **Region, site or zone:** pick it from the list. Choose **Other…** to enter a value that isn't listed.
> * **Keys and tokens:** paste the bare value. Cosmos adds any required prefix, such as `Bearer ` or `Api-Token `.
> * **User and secret pairs:** for platforms that use HTTP Basic authentication, such as Grafana Cloud and Langfuse, enter both parts. Cosmos encodes them in your browser.
> * **Fixed headers:** headers the platform requires with a documented constant value, such as Datadog's `compute_stats: true`, are added for you.
>
> For each provider's endpoint, headers and supported signals, see [Supported providers](https://docs.augmentcode.com/cosmos/trace-export/providers.md). To edit the endpoint or headers by hand, choose **Use as a custom endpoint**.

> [tab] Custom OTLP
>
> Choose **Custom endpoint** for any other OTLP/HTTP collector, such as an OpenTelemetry Collector or a vendor that isn't listed.
>
> | Field | What to enter |
> | - | - |
> | **Name** | Required, at most 100 characters. For example, "Prod collector". In a provider form the name is optional and defaults to the provider's name. |
> | **Traces URL** | The full HTTPS URL of the traces endpoint, including the path, for example `https://otlp.example.com/v1/traces`. Cosmos posts to this URL as entered. Any path and query are allowed. |
> | **Request headers** | Up to 10 headers sent with every request, such as `Authorization`. Put credentials only in header values. |
>
> You can paste a configuration snippet into the **Traces URL** field instead of typing: `OTEL_EXPORTER_OTLP_*` environment variables or a `curl` command. Cosmos shows what it found, and nothing changes until you click **Fill form**. A paste can't be larger than 16 KB.
>
> * `OTEL_EXPORTER_OTLP_TRACES_ENDPOINT` is used as is. A base `OTEL_EXPORTER_OTLP_ENDPOINT` gets `/v1/traces` added.
> * `OTEL_EXPORTER_OTLP_TRACES_HEADERS` takes precedence over `OTEL_EXPORTER_OTLP_HEADERS`.
>
> The form warns about common mistakes before you test, for example a URL that doesn't end in `/v1/traces`, an OTLP/gRPC port, a credential in the query string (proxies often log query strings), or a header value missing the prefix the vendor expects.

### Send metrics and logs

Turn on **Send metrics** to also send token, cost, duration and session counts to `/v1/metrics`. Turn on **Send logs** to also send run, model, tool and MCP events to `/v1/logs`. Both are off by default and need a traces URL that ends in `/v1/traces`. Cosmos replaces only that ending and keeps the rest of the path and the query, so `https://otlp-gateway-prod-us-east-0.grafana.net/otlp/v1/traces` sends metrics to `…/otlp/v1/metrics` and logs to `…/otlp/v1/logs`. For platforms that accept only traces, the provider form disables the switch and says, for example, "Langfuse doesn't accept OTLP metrics." For what's sent, see [Metrics](https://docs.augmentcode.com/cosmos/trace-export/reference.md#metrics) and [Log events](https://docs.augmentcode.com/cosmos/trace-export/reference.md#log-events).

### Advanced settings

| Field | What it does |
| - | - |
| **Max request size** | When a batch's compressed body is larger than this, Cosmos splits it. Between 0.0625 MB (64 KB) and 4 MB; leave empty for 4 MB. A single span is still sent even if it's larger, and is dropped as **Too large** only if the endpoint answers HTTP 413. Databricks and Harness receive uncompressed bodies, which are larger than the compressed size. A New Relic destination starts at 1 MB. |
| **Max content size** | The most content, in KB, that each span carries. Between 1 and 128 KB; leave empty for everything that was captured. Shown only when at least one content level is on for this destination. See [Content limits](https://docs.augmentcode.com/cosmos/trace-export/content-and-privacy.md#content-limits). |
| **Resource attributes** | Up to 8 key-value pairs added to the OTLP resource of every request, such as `deployment.environment = prod`. Some providers route by one, such as Arize's `openinference.project.name`. |

Resource attribute rules:

* Keys start with a letter and use letters, digits, `.`, `_` or `-`, at most 128 characters. Each key can appear once.
* Values are 1 to 256 bytes of UTF-8 without control characters.
* `service.name` and `service.version` are set by Cosmos and can't be used.
* Keys that look like credentials (containing `key`, `token`, `secret`, `password` or `auth`) are rejected. Resource attributes aren't secret, so put credentials in a header.

### Test and save

Click **Add destination**. Cosmos first tests the connection, then saves and enables the destination if the test passes. To test without saving, click **Test connection** instead.

The test sends one span named `export_test` to your endpoint through the same checks and path as real exports, without content and without retries. If **Send metrics** or **Send logs** is on, it also sends an empty request to each of those endpoints, so an endpoint that accepts only traces fails the test instead of silently dropping them.

The **Connection test** shows each step and where it failed, with a suggested fix:

| Step | Checks |
| - | - |
| **DNS lookup** | The host name resolves to a public address |
| **Connection** | Cosmos can connect to the host and port |
| **TLS handshake** | The certificate is trusted and matches the host name |
| **Authentication** | The endpoint didn't reject the credentials (no HTTP 401 or 403) |
| **Test span accepted** | The endpoint returned a 2xx response and didn't reject the span |

When the test passes, the destination is saved and enabled. Find the test span in your platform within about 30 seconds by searching for `service.name` = `augment-cosmos`.

If the test fails, click **Fix and retry** to jump to the field the failure points at, or **Save anyway** to save the destination as it is. If the test couldn't run, click **Save without testing** or **Keep editing**. You can run 10 tests per minute in an organization.

When you edit a destination, the button is **Save**. Editing works differently from adding:

* **Save** tests the connection only if you changed the URL or headers. Other changes, such as the name, are saved without a test.
* Saving keeps the destination's **Enabled** setting as it is. Saving a fix to a disabled destination doesn't enable it; turn on **Enabled** in **Advanced**, or use **Test and re-enable**.

## 3. Check that spans arrive

1. Start a session in Cosmos.
2. On the Trace Export page, check the destination's status. It shows **Waiting for the first span** until the first delivery, then **Healthy**. See [Destination status](https://docs.augmentcode.com/cosmos/trace-export/delivery.md#destination-status).
3. In your platform, filter on `service.name` = `augment-cosmos`.

Spans are sent when they end, usually within a few seconds. A run's `invoke_agent` span arrives when the agent finishes responding.

## 4. Choose what to send

By default, destinations receive only metadata. The **Content** section adds more for every destination in the organization:

* **Conversation**, **Model inputs** and **Tool inputs and outputs** are off by default. Turning one on asks you to confirm. Turning one on or off takes effect within about 30 seconds, so content already being sent can still arrive during that time.
* **Include user identity** adds the user ID and email to spans, metrics and logs.

Content levels apply to every destination; there's no general per-destination setting yet. For what each level adds, how content is redacted, and the one case where a single destination receives less, see [Content and privacy](https://docs.augmentcode.com/cosmos/trace-export/content-and-privacy.md#send-less-content-to-one-destination).

## 5. Choose which sessions to export

**Sessions to export** sets whose sessions are sent, for every destination:

* **All sessions:** every session in your organization. The default.
* **Only selected experts:** only sessions started from the experts you select, up to 200. Select **Also export sessions not started from an expert** to include those too. Use **All spaces** or a single space to filter the expert list.

Click **Save** to apply your selection, or **Discard** to undo it. Nothing changes until you save. Saved changes apply within about 30 seconds. An expert that was deleted, or that you can't see, stays in the selection and its sessions are still exported.

## Manage destinations

Open a destination's **Actions** menu to **Edit or test**, **Disable** or **Enable**, or **Delete** it. Changes take effect within about 30 seconds.

* **Header values and the URL path are write-only.** After you save, Cosmos shows only the URL's scheme and host, and `••••` for header values. To keep a saved value, leave its field empty when you edit.
* **Changing the host needs the header values again.** If you change the URL's scheme, host or port, enter every header value again, so saved credentials are never sent to a new host.
* **A disabled destination receives nothing.** Spans aren't queued while it's disabled and aren't sent after you enable it again.
* **Five destinations at most.** When you have five, **Add Destination** is disabled. Delete one to add another.

To enable a destination that Cosmos [turned off automatically](https://docs.augmentcode.com/cosmos/trace-export/delivery.md#automatic-disabling), click **Test and re-enable** on its banner (or **Test and enable** in its status details). It's enabled only if the test passes; otherwise the form opens with the failure on the relevant field.

## Next steps

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

> [card] [Delivery and troubleshooting](https://docs.augmentcode.com/cosmos/trace-export/delivery.md)
>
> Destination states, delivery errors and limits.


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