|
| 1 | +--- |
| 2 | +title: "OpenRouter Broadcast tracing with Future AGI" |
| 3 | +description: "Send OpenRouter Broadcast traces straight to Observe with OpenRouter's OpenTelemetry Collector destination: one endpoint and three headers, no code in your app." |
| 4 | +--- |
| 5 | + |
| 6 | +## About |
| 7 | + |
| 8 | +[OpenRouter Broadcast](https://openrouter.ai/docs/guides/features/broadcast) sends a trace of each request that passes through OpenRouter to the observability tools you pick, with no code in your app. This page points Broadcast's **OpenTelemetry Collector** destination at Future AGI, so those traces land in an Observe project. |
| 9 | + |
| 10 | +Broadcast is not client tracing. The [OpenAI instrumentor](/docs/integrations/traceai/openai), with the base URL `https://openrouter.ai/api/v1`, traces the calls your own code makes, under your own agent and tool spans. Broadcast traces what OpenRouter received, from any client, including tools you cannot instrument. |
| 11 | + |
| 12 | +<Note> |
| 13 | +This setup needs a Future AGI collector that reads the `X-Project-Name` header. Broadcast's OpenTelemetry Collector destination can set headers but not resource attributes, so the header is how each trace names its Observe project. A collector without the header rejects every trace with `400` `no project_name`. On a self-hosted deployment, upgrade before you start. |
| 14 | +</Note> |
| 15 | + |
| 16 | +## Before you start |
| 17 | + |
| 18 | +| You need | Where to get it | |
| 19 | +|---|---| |
| 20 | +| A Future AGI API key and secret key | **Settings > API Keys** at [app.futureagi.com/dashboard/keys](https://app.futureagi.com/dashboard/keys). Only an Owner can create keys, and the secret key is shown once. See [API keys](/docs/admin-settings/api-keys). | |
| 21 | +| Access to Broadcast in OpenRouter | [Settings > Observability](https://openrouter.ai/settings/observability). In an OpenRouter organization, only an organization admin can edit it. | |
| 22 | + |
| 23 | +A key pair belongs to one workspace, and every trace sent with it lands in that workspace. |
| 24 | + |
| 25 | +## Set up |
| 26 | + |
| 27 | +<Steps> |
| 28 | + |
| 29 | +<Step title="Enable Broadcast"> |
| 30 | + |
| 31 | +In OpenRouter, open [Settings > Observability](https://openrouter.ai/settings/observability) and switch on **Enable Broadcast**. |
| 32 | + |
| 33 | +</Step> |
| 34 | + |
| 35 | +<Step title="Configure the OpenTelemetry Collector destination"> |
| 36 | + |
| 37 | +Click the edit icon next to **OpenTelemetry Collector** and fill in: |
| 38 | + |
| 39 | +| Field | Value | |
| 40 | +|---|---| |
| 41 | +| Endpoint | `https://api.futureagi.com/tracer/v1/traces` | |
| 42 | +| Headers | The JSON object below, with your keys and the name of the Observe project | |
| 43 | + |
| 44 | +```json |
| 45 | +{ |
| 46 | + "X-Api-Key": "YOUR_API_KEY", |
| 47 | + "X-Secret-Key": "YOUR_SECRET_KEY", |
| 48 | + "X-Project-Name": "my-chatbot" |
| 49 | +} |
| 50 | +``` |
| 51 | + |
| 52 | +- **Endpoint**: the full traces URL, exactly as shown, with no trailing slash. |
| 53 | +- **`X-Project-Name`**: if the key's workspace has no project with this name, Future AGI creates an Observe project when the first span arrives. Send one name of at most 255 characters, with no commas and no control or invisible characters. [Naming the project](/docs/observe/reference/export-formats#naming-the-project) has the full rules. |
| 54 | +- **Self-hosted Future AGI**: use your collector's OTLP/HTTP traces URL instead, for example `https://otel.example.com/v1/traces`. OpenRouter's cloud has to reach it over the internet. The collector listens on port 4318 over plain HTTP, so put TLS in front of it. |
| 55 | + |
| 56 | +Leave **Privacy Mode** off to send prompts and responses, or tick it to keep them out. See [Privacy](#privacy). |
| 57 | + |
| 58 | +</Step> |
| 59 | + |
| 60 | +<Step title="Test and save"> |
| 61 | + |
| 62 | +Click **Test Connection**. OpenRouter saves the destination only if the test passes. |
| 63 | + |
| 64 | +The test posts one span with your headers. Future AGI answers `200` when the keys are valid and the project name is accepted, `401` when the keys are wrong, and `400` when the project name breaks the rules above. |
| 65 | + |
| 66 | +</Step> |
| 67 | + |
| 68 | +<Step title="Send a request through OpenRouter"> |
| 69 | + |
| 70 | +Any client works. `user`, `session_id` and `trace` are optional. They arrive in Future AGI as `user.id`, `session.id` and `trace.metadata.*` attributes. |
| 71 | + |
| 72 | +```bash |
| 73 | +curl https://openrouter.ai/api/v1/chat/completions \ |
| 74 | + -H "Authorization: Bearer $OPENROUTER_API_KEY" \ |
| 75 | + -H "Content-Type: application/json" \ |
| 76 | + -d '{ |
| 77 | + "model": "openai/gpt-4o-mini", |
| 78 | + "messages": [{"role": "user", "content": "What is the capital of France?"}], |
| 79 | + "user": "user_12345", |
| 80 | + "session_id": "session_abc", |
| 81 | + "trace": {"trace_name": "Capital lookup", "environment": "staging"} |
| 82 | + }' |
| 83 | +``` |
| 84 | + |
| 85 | +OpenRouter sends the trace after the request completes. In Future AGI, open **Observe**, select `my-chatbot`, and open the trace. |
| 86 | + |
| 87 | +</Step> |
| 88 | + |
| 89 | +</Steps> |
| 90 | + |
| 91 | +To send different OpenRouter traffic to different projects, add one destination per project and use OpenRouter's API key filters on each. OpenRouter allows up to 5 destinations of each type. |
| 92 | + |
| 93 | +## What shows up in Observe |
| 94 | + |
| 95 | +| Signal | What you see | |
| 96 | +|---|---| |
| 97 | +| Spans | One trace per request. The root span is named `LLM Generation`, whatever `trace_name` says; `trace_name` arrives as the attribute `trace.name`. Under the root sits one `provider attempt N: <provider>` span per provider attempt, and a streamed request also has a `generation` span. | |
| 98 | +| Span types | The root is an LLM span, because OpenRouter sets `gen_ai.operation.name` to `chat`. The attempt and `generation` spans carry no span type and show as `unknown`. | |
| 99 | +| Model and provider | The model slug from `gen_ai.request.model`, for example `openai/gpt-4o-mini`, and the provider that served it from `gen_ai.provider.name`, for example `azure`. A request that failed before reaching a provider shows provider `unknown`. | |
| 100 | +| Tokens | Input, output and total from `gen_ai.usage.input_tokens`, `gen_ai.usage.output_tokens` and `gen_ai.usage.total_tokens`. | |
| 101 | +| Cost | With **Cost** switched on under **Additional generation metadata**, OpenRouter sends its charge in US dollars as `gen_ai.usage.total_cost`. Observe does not read that attribute. It prices the span by exact model name instead, and OpenRouter slugs such as `openai/gpt-4o-mini` are not in its price list, so cost usually shows $0. OpenRouter's value stays on the span as an attribute. | |
| 102 | +| Prompt and response | Sent on the root span as `span.input` and `span.output`, and again as `gen_ai.prompt` and `gen_ai.completion`, unless Privacy Mode is on. They are stored as span attributes. The Input and Output panes stay empty. | |
| 103 | +| Session | `session_id` arrives as `session.id`. Requests with the same value are grouped into one session. | |
| 104 | +| User | `user` arrives as `user.id` and is stored as a span attribute. It is not linked to an end user in the Users tab: that link needs the `project_type` resource attribute, which this destination cannot set. | |
| 105 | +| Custom metadata | Each key in `trace` arrives as a `trace.metadata.<key>` span attribute. OpenRouter adds its own `trace.metadata.openrouter.*` attributes on every generation, including the name of the OpenRouter API key and the ids of its owner. With **Cost** or **Request context** on, the `openrouter_generation.*` fields arrive twice, under `span.metadata.` and `trace.metadata.`. They repeat the same quantities, so do not add them up. | |
| 106 | +| Errors | A request that fails after OpenRouter accepts it, for example a `402` for too few credits, arrives as an `ERROR` span. The error text is its status message, and also arrives as the attribute `span.status_message` and in an `exception` event. `error.type` holds the HTTP status. A request OpenRouter rejects before routing, such as one with an unknown model id, sends no trace. | |
| 107 | + |
| 108 | +## Privacy |
| 109 | + |
| 110 | +| Setting | Effect | |
| 111 | +|---|---| |
| 112 | +| Privacy Mode off | OpenRouter sends prompts and responses. Future AGI stores them as span attributes. | |
| 113 | +| Privacy Mode on | OpenRouter removes prompts and responses before sending, and replaces its raw provider usage object with `null`. Tokens, cost, timing, model, `user.id`, `session.id` and custom metadata are still sent. | |
| 114 | + |
| 115 | +Nothing between OpenRouter and Future AGI removes anything else: what OpenRouter sends is stored. OpenRouter documents Privacy Mode as removing prompts and completions. Error text arrives in separate attributes (the status message, `span.status_message` and the `exception` event) and can repeat details of the request, so check one failed trace in your project before you rely on Privacy Mode for it. |
| 116 | + |
| 117 | +`user` and `trace` are values you choose, and they are stored as sent. Use internal ids, not e-mail addresses or free text. |
| 118 | + |
| 119 | +Your Future AGI keys are stored in OpenRouter's settings. OpenRouter says it encrypts destination credentials and decrypts them only to send traces. To keep the keys, or the error text, on your own side, run your own OpenTelemetry Collector between OpenRouter and Future AGI: Broadcast sends to your collector with a token of your own, and your collector forwards to the endpoint above with the three headers. |
| 120 | + |
| 121 | +## Limits and errors |
| 122 | + |
| 123 | +| Response | Meaning | What to do | |
| 124 | +|---|---|---| |
| 125 | +| `200` | Accepted. | Nothing. | |
| 126 | +| `400` `no project_name` | The collector does not read `X-Project-Name`, or the header is missing. | Check the Headers JSON. On a self-hosted deployment, upgrade the collector. | |
| 127 | +| `400` | The `X-Project-Name` value breaks a rule: more than one value, a comma, more than 255 characters, or control or invisible characters. | Fix the name. See [Naming the project](/docs/observe/reference/export-formats#naming-the-project). | |
| 128 | +| `401` | The keys are wrong for this workspace, or one of the key headers is missing. An `Authorization: Bearer` header is not accepted. | Copy both keys again from the keys page. | |
| 129 | +| `413` | The request is over 16 MiB. OpenRouter shortens any single attribute at 10,000,000 characters and sends the prompt twice, so a very long conversation can go over. | Turn on Privacy Mode for that destination, or keep long transcripts out of it with API key filters. See [Ingestion request limits](/docs/observe/reference/export-formats#ingestion-request-limits). | |
| 130 | +| `429` | The workspace reached its usage limit. | Check usage in Future AGI. | |
| 131 | +| `503` with `Retry-After` | The collector is busy. | Temporary. | |
| 132 | + |
| 133 | +## Troubleshooting |
| 134 | + |
| 135 | +| What you see | What it means | |
| 136 | +|---|---| |
| 137 | +| Test Connection fails | Compare the Endpoint and Headers with the step above. A wrong or missing key gives `401`. A project name with a comma, or longer than 255 characters, gives `400`. | |
| 138 | +| Test Connection passes and no trace appears | Widen the date range in Observe. Check the destination's sampling rate and API key filters in OpenRouter: a trace they leave out is never sent. | |
| 139 | +| Every trace is rejected with `400` `no project_name` | The collector does not read `X-Project-Name`. See the note at the top of this page. | |
| 140 | +| Cost shows $0 | See Cost in [What shows up in Observe](#what-shows-up-in-observe). | |
| 141 | +| No prompt or response | Privacy Mode is on for the destination, or you are looking at the Input and Output panes: open the root span's attributes. | |
| 142 | +| The Users tab is empty | `user.id` is stored on the span but not linked to an end user. See User in [What shows up in Observe](#what-shows-up-in-observe). | |
| 143 | + |
| 144 | +## Next Steps |
| 145 | + |
| 146 | +- [OpenAI instrumentor](/docs/integrations/traceai/openai), to trace the calls your own code makes to OpenRouter |
| 147 | +- [Export formats and endpoints](/docs/observe/reference/export-formats), for the endpoint, headers and limits in full |
| 148 | +- [Observe](/docs/observe) |
0 commit comments