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

# OTLP routing: span attribute vs request header

> Route OTLP spans to experiments using span attributes or request headers when collecting telemetry through a shared BYOC or hosted collector.

> [!NOTE]
>
> **Applies to:**
>
> * Plan - 
> * Deployment - Hosted and BYOC
> *
> * Use case - How to route OTLP spans to experiments/rows using braintrust.parent vs x-bt-parent when using a shared collector (BYOC and hosted)

## Summary

OTLP spans sent to `/otel/v1/traces` through a shared collector are routed using either a per-span `braintrust.parent` attribute or the `x-bt-parent` request header.

## What is happening

When you send OTLP traces to `/otel/v1/traces` through a shared collector, Braintrust uses each span's `braintrust.parent` attribute to determine where the span is routed. For spans without that attribute, Braintrust uses the `x-bt-parent` header supplied with that request.

## Fix or suggestion

### Option 1: Per-span routing (recommended)

1. Set `braintrust.parent` on every span you emit, including child spans.
2. Use the intended experiment row span's exported parent value as the attribute value.

OTLP attribute fragment:

```json theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
{
  "key": "braintrust.parent",
  "value": {
    "stringValue": "<EXPORTED_ROW_PARENT>"
  }
}
```

### Option 2: Per-request header (alternative)

The `x-bt-parent` header is a request-wide default. Use this option only for requests containing spans for a single experiment row. For requests containing spans for multiple experiment rows, set `braintrust.parent` on every span, including child spans.

1. For spans without `braintrust.parent`, set the request's `x-bt-parent` header to the intended experiment row span's exported parent value.

## Verify routing

* Send a test trace using the intended row span's exported parent value and verify that it appears beneath that row.

> [!NOTE]
>
> The API key used by the collector must have write access to every destination you route spans to.


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