Traces over OTLP

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 attributes	Trace attributes
Span attributes	Stay on that span
`mirador.trace.*` attributes	Opt in to trace scope: tags and promoted trace attributes
Each span	A Mirador span with the original timing, attributes, and status
Each span event	A neutral event, or an error event when the span status is `ERROR`
Root span end	Finishes the trace

A span is a span: plain root-span attributes stay on the root span rather than becoming trace attributes. Use mirador.trace.attribute.<key> to promote one into the trace attribute bag, and mirador.trace.tags to set trace tags. Set service.name on the Resource. Span events are stored without a severity unless they carry mirador.event.severity, so they do not affect a trace’s info, warn, and error counts on their own. See Enrichment hints. 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:

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:

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();

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.

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 — or resolve an asset’s market rate — and stitch its outcome back into the same trace.

span.addEvent('mirador.web3.evm.txhint', {
  'tx.hash': transactionHash,
  'chain.id': 8453, // or 'base'
});

Event names and attribute keys are exact contracts. See 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.

OpenRouter LLM content

For the complete Broadcast configuration, endpoint, authentication header, and troubleshooting steps, see Connect OpenRouter to Mirador. OpenRouter’s Broadcast export triplicates each generation’s prompt and completion byte-for-byte across gen_ai.prompt, span.input, and trace.input (and gen_ai.completion, span.output, and trace.output), which can push a single span’s attribute bag into the megabytes. Mirador detects this signature on ingest and relocates one copy of each out of the span and trace attribute bags into span events — gen_ai.content.prompt and gen_ai.content.completion — whose details carries the content. The duplicates are dropped and the small gen_ai.* metadata such as model, tokens, and cost stays on the attributes. Relocated content is surfaced on the trace’s event history through GET /v1/traces/{trace_id}/events. Copies that are not byte-identical are left untouched. There is nothing to configure: this applies only to the byte-identical OpenRouter duplication shape.

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 for exporter configuration and preserved fields.

Next steps

Enrichment hints

Track transactions, Safe actions, Relay intents, Stripe payments, and market rates

Logs

Send structured logs with trace and span correlation

Getting Started

OpenTelemetry

Web SDK

Web3 Integration

Payments & Market Data

Automations

AI & Agents

Best Practices

How OTLP maps to Mirador

Export traces

Enrich traces with external actions

Delivery behavior

OpenRouter LLM content

Correlate logs with traces

Next steps

Enrichment hints

Logs

​How OTLP maps to Mirador

​Export traces

​Enrich traces with external actions

​Delivery behavior

​OpenRouter LLM content

​Correlate logs with traces

​Next steps

Enrichment hints

Logs

How OTLP maps to Mirador

Export traces

Enrich traces with external actions

Delivery behavior

OpenRouter LLM content

Correlate logs with traces

Next steps