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

# Set Up Trace Forwarding

> Add a General or GenAI OTLP endpoint, authenticate it, attach it to environments, and understand how delivery works.

Trace forwarding sends the spans of your automations and AI agents to an OpenTelemetry Protocol (OTLP) endpoint that you control. You set it up in two places: add the endpoint once for your organization, then choose which environments send to it.

## Before you start

* You need the Organization Administrator role to view or change trace forwarding.
* You need an OTLP traces endpoint that is reachable from the internet, and its credentials. Most tracing backends and the OpenTelemetry Collector provide one.
* Decide whether to use gRPC or HTTP. Use the protocol your backend documents for OTLP traces.

## Add an endpoint

1. Open ![Settings icon](https://mintcdn.com/elementum/TFCVHNVI8zhq54sg/images/icons/settings.svg?fit=max\&auto=format\&n=TFCVHNVI8zhq54sg\&q=85\&s=3ffc43e8a0875412cc27335241aeb4c8) **Organization Settings** > **Platform** > **Trace Forwarding**.
2. In **General Traces**, select **Add General Endpoint**.
3. Fill in the connection, authentication, headers, and resource attributes. The fields are described below.
4. Select **Save & Test**. Elementum saves the endpoint and sends one test span.
5. Check the result. **Message delivered** means your endpoint accepted the test span.

Use a **General** endpoint for automation spans. GenAI endpoints never receive automation spans. To send AI agent spans to an evaluation platform, see [Add a GenAI endpoint](#add-a-genai-endpoint).

To edit an endpoint, click ![Edit icon](https://mintcdn.com/elementum/WBtBRoedx7pT-MEg/images/icons/pencil.png?fit=max\&auto=format\&n=WBtBRoedx7pT-MEg\&q=85\&s=c1d9879f4dee19013fd2fde270735e6d) in its row. Editing opens the same dialog.

### Connection

| Field | What to enter |
| - | - |
| **Name** | A label for this endpoint, for example `Production Tempo`. Required. |
| **Endpoint URL** | The full OTLP traces URL. It must start with `http://` or `https://`. See the protocol notes below. |
| **Protocol** | **gRPC** or **HTTP**. |

**Protocol notes**

| Protocol | Endpoint URL format | Example |
| - | - | - |
| HTTP | Include the full traces path. Elementum posts to the URL exactly as entered. | `https://otlp.example.com:4318/v1/traces` |
| gRPC | Scheme, host, and port only. | `https://otlp.example.com:4317` |

HTTP uses the OTLP/HTTP protobuf encoding. A common mistake is to enter only the host for HTTP. The test then fails with an endpoint-not-found error.

### Authentication

Choose one **Authorization Type**:

| Type | Fields | What Elementum sends |
| - | - | - |
| **None** | none | No authorization header. |
| **Bearer Token** | **Bearer Token**, optional **Bearer Scheme** | An `Authorization` header of the scheme and token. The scheme defaults to `Bearer`. |
| **Basic Auth** | **Username**, **Password** | An `Authorization: Basic` header. The value is the base64 encoding of `username:password`. |
| **Custom Headers** | one or more **Header Key** and **Header Value** pairs | Each header as entered. Use this for API key headers, for example `x-honeycomb-team` or `DD-API-KEY`. |

Secret values (tokens, passwords, and custom header values) are write-only. After you save, Elementum shows only whether a value is set. To change one, enter a new value.

### Additional headers

**Additional Headers** are sent with every export, in addition to the authentication header. Use them for non-secret settings your backend needs, for example a dataset or tenant header. Their values stay visible on the settings page, so do not put secrets here. Use **Custom Headers** authentication for secrets.

### Resource attributes

**Resource Attributes** are key and value pairs that Elementum adds to the OTLP resource of every span sent to this endpoint. Values are sent as strings.

Use them to label Elementum spans in your backend. For example:

| Key | Value | Why |
| - | - | - |
| `deployment.environment` | `production` | Filter by environment. Elementum does not add environment ids to spans. |
| `elementum.org` | `acme-prod` | Tell organizations apart if several send to one backend. |

Every span already has `service.name` set to `elementum` and, when available, `service.version` set to the Elementum platform release. A resource attribute you configure with the same key replaces Elementum's value. For example, setting `service.name` to `elementum-prod` changes the service name of every span sent to this endpoint.

## Attach an endpoint to an environment

An endpoint receives spans only from the environments you attach it to.

1. Open ![Settings icon](https://mintcdn.com/elementum/TFCVHNVI8zhq54sg/images/icons/settings.svg?fit=max\&auto=format\&n=TFCVHNVI8zhq54sg\&q=85\&s=3ffc43e8a0875412cc27335241aeb4c8) **Organization Settings** > **Platform** > **Environments**.
2. On the environment card, click **Configure**, then **Edit Environment**.
3. In **Trace Forwarding**, select the endpoints that should receive traces from this environment.
4. Click **Save Changes**.

Each environment can send to several endpoints, and each endpoint can receive from several environments. Every attached, enabled endpoint receives its own full copy of the spans.

Changes can take up to about a minute to take effect.

## Add a GenAI endpoint

A GenAI endpoint receives only the spans of AI agents, LLM calls, and tool runs, for an evaluation platform such as W\&B Weave. See [GenAI tracing](https://docs.elementum.io/administration/trace-forwarding/genai-tracing.md) for what it receives.

1. In ![Settings icon](https://mintcdn.com/elementum/TFCVHNVI8zhq54sg/images/icons/settings.svg?fit=max\&auto=format\&n=TFCVHNVI8zhq54sg\&q=85\&s=3ffc43e8a0875412cc27335241aeb4c8) **Organization Settings** > **Platform** > **Trace Forwarding**, go to **GenAI Traces** and select **Add GenAI Endpoint**.
2. Fill in the same fields as for a General endpoint: connection, authentication, additional headers, and resource attributes.
3. Select **Save & Test**.
4. Attach the endpoint to environments, as in [Attach an endpoint to an environment](#attach-an-endpoint-to-an-environment).

What differs from a General endpoint:

| Topic | GenAI endpoint |
| - | - |
| What it receives | AI agent, LLM call, tool, and some voice call spans. Never automation spans. |
| **Protocol** | Defaults to **HTTP**. Most evaluation platforms accept only OTLP over HTTP. |
| Helper text | **Endpoint URL** and **Authorization Type** show a Weave example. See [W\&B Weave](https://docs.elementum.io/administration/trace-forwarding/evaluating-ai.md#wb-weave). |
| Saving | The dialog has **Save & Test** only. Every save sends a test span. |
| Content | Spans carry prompts, replies, and tool results. Read [Prompt and response content](https://docs.elementum.io/administration/trace-forwarding/genai-tracing.md#prompt-and-response-content) before you connect an endpoint. |
| Endpoint type | Fixed when you add the endpoint. To change it, add a new endpoint of the other type and delete the old one. |

Everything else is the same as for a General endpoint: authentication types, write-only secrets, resource attributes, the test span, attaching to environments, enabling and disabling, and delivery. In an environment's **Trace Forwarding** section, General and GenAI endpoints appear in one list, by name. Name GenAI endpoints so you can tell them apart, for example `Weave - production`.

A General endpoint also receives AI agent spans, with the same content, alongside automation spans. You do not need a GenAI endpoint to see AI spans in a general tracing backend.

## Enable, disable, or delete an endpoint

* **Disable** stops all forwarding to the endpoint, from every environment, without removing its settings. A disabled endpoint is shown struck through in the environment's **Trace Forwarding** section.
* **Enable** resumes forwarding. Spans recorded while the endpoint was disabled are not sent.
* **Delete** removes the endpoint and detaches it from every environment. Click ![Delete icon](https://mintcdn.com/elementum/WBtBRoedx7pT-MEg/images/icons/trash.png?fit=max\&auto=format\&n=WBtBRoedx7pT-MEg\&q=85\&s=5d4518c1ae0f6ec1d34fb58721c472ff) in the endpoint row and confirm.

## Test the connection

**Save & Test**, and **Test Connection** on a saved endpoint, send a single span named `elementum.connection-test` with your configured headers and resource attributes. The result shows:

| Result | Meaning |
| - | - |
| **Message delivered** | Your endpoint accepted the span. The result shows the latency and the test span's trace id and span id, so you can find it in your backend. |
| **Failed to deliver message** | The endpoint rejected the span or could not be reached. The result suggests what to check: credentials, the URL and path, the server, or whether the URL is reachable. |

The test rejects URLs that resolve to private, loopback, or link-local addresses. Your endpoint must be reachable over the public internet. A test that waits longer than 10 seconds for your endpoint fails.

The test span is not an automation span. You can ignore or delete it in your backend.

## Delivery and failures

| Topic | Behavior |
| - | - |
| When spans are sent | After each step ends. Spans usually arrive within seconds. A run's spans can arrive in more than one batch and out of order. Your backend assembles the trace by id. |
| Endpoint timeout | Elementum waits up to 5 seconds for your endpoint to accept a batch. A slower response counts as a failure. |
| Failure handling | If your endpoint rejects a batch, times out, or cannot be reached, that batch is dropped. Elementum does not queue or resend it. Later batches are sent normally. |
| Effect on automations | None. Forwarding never slows down, retries, or fails an automation. |
| Several endpoints | Each endpoint is sent to independently. A failing endpoint does not affect the others. |

Because delivery is best effort, use traces to observe and debug automations. Use the Elementum run history as the record of what ran.

## Checklist

* [ ] Endpoint added under **General Traces** with the full URL. HTTP needs the traces path, for example `/v1/traces`.
* [ ] **Save & Test** shows **Message delivered**, and you found the `elementum.connection-test` span in your backend.
* [ ] Endpoint attached to the environment on the **Environments** page.
* [ ] Optional: a `deployment.environment` resource attribute so you can tell environments apart.
* [ ] Run an automation, wait a few seconds, and search your backend for `service.name = elementum`.
* [ ] For a GenAI endpoint: send a message to an agent in an attached environment and look for an `invoke_agent` span.

Next: [Continue your trace into Elementum](https://docs.elementum.io/administration/trace-forwarding/continue-your-trace.md).


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