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

# Traces over OTLP

> Export OpenTelemetry spans, events, attributes, and status to Mirador

OTLP spans exported to Mirador become first-class Mirador traces. They appear live in the dashboard and can be searched, inspected, and used by automations like traces created with a Mirador SDK.

## How OTLP maps to Mirador

| OpenTelemetry                   | Mirador                                                          |
| ------------------------------- | ---------------------------------------------------------------- |
| `trace_id` (16 bytes)           | Trace ID as the same 32-character W3C hexadecimal value          |
| Root span with no parent        | Starts the trace; its name becomes the trace name                |
| Resource + root span attributes | Trace attributes; span values win on key conflicts               |
| Each span                       | A Mirador span with the original timing, attributes, and status  |
| Each span event                 | An info event, or an error event when the span status is `ERROR` |
| Root span end                   | Finishes the trace                                               |

Because the trace ID is preserved, the ID attached to an OTel log record or propagated in a W3C `traceparent` header is the same ID you search for in Mirador.

## Export traces

Configure a standard OTLP/HTTP trace exporter:

```bash theme={null}
export OTEL_SERVICE_NAME=checkout-api
export OTEL_EXPORTER_OTLP_TRACES_PROTOCOL=http/protobuf
export OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=https://otel.mirador.org/v1/traces
export OTEL_EXPORTER_OTLP_TRACES_HEADERS=Authorization=mir_srv_xxx
```

Or configure the Node.js SDK directly:

```typescript theme={null}
import { resourceFromAttributes } from '@opentelemetry/resources';
import { NodeSDK } from '@opentelemetry/sdk-node';
import { OTLPTraceExporter } from '@opentelemetry/exporter-trace-otlp-http';

const sdk = new NodeSDK({
  resource: resourceFromAttributes({
    'service.name': 'checkout-api',
    'deployment.environment.name': 'production',
  }),
  traceExporter: new OTLPTraceExporter({
    url: 'https://otel.mirador.org/v1/traces',
    headers: {
      Authorization: `Bearer ${process.env.MIRADOR_API_KEY}`,
    },
  }),
});

sdk.start();
```

<Tip>
  Set `service.name` on the OTel resource. It makes services recognizable across traces, metrics, and logs and gives you a reliable field for filtering and grouping.
</Tip>

## Enrich traces with external actions

Mirador recognizes reserved `mirador.*` **span events** as enrichment hints. A hint can tell Mirador to follow an EVM, Solana, Canton, Safe, Relay, or Stripe action and stitch its outcome back into the same trace.

```typescript theme={null}
span.addEvent('mirador.web3.evm.txhint', {
  'tx.hash': transactionHash,
  'chain.id': 8453,
});
```

Event names and attribute keys are exact contracts. See [Enrichment hints](/opentelemetry/enrichment-hints) for the complete catalog and language examples.

## Delivery behavior

* **Sampling matters.** A hint or span cannot reach Mirador when its parent span is sampled out. Use an always-on or parent-based always-on sampler for flows that must be observed.
* **Flush before exit.** Let batch processors drain, or call your provider's shutdown/force-flush method before a short-lived process exits.
* **Retries are idempotent.** Re-exporting the same span is deduplicated using deterministic command IDs.
* **Partial success is explicit.** Invalid or zero trace/span IDs are counted in the OTLP `RejectedSpans` response while valid spans in the same export continue.
* **Timestamps are preserved.** Mirador uses the SDK's wall-clock timestamps, so emitting hosts should have a reasonably synchronized clock.

## Correlate logs with traces

OTLP log records that contain `trace_id` and `span_id` remain linked to their originating trace and span. Most OTel logging integrations inject this context automatically when a log is emitted while a span is active.

See [Logs over OTLP](/opentelemetry/logs) for exporter configuration and preserved fields.

## Next steps

<CardGroup cols={2}>
  <Card title="Enrichment hints" icon="wand-magic-sparkles" href="/opentelemetry/enrichment-hints">
    Track transactions, Safe actions, Relay intents, and Stripe payments
  </Card>

  <Card title="Logs" icon="rectangle-list" href="/opentelemetry/logs">
    Send structured logs with trace and span correlation
  </Card>
</CardGroup>