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 + 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:

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 and stitch its outcome back into the same trace.

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

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.

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.

Getting Started

Core Concepts

Web3 Integration

OpenTelemetry

Automations

AI & Agents

Advanced

Best Practices

How OTLP maps to Mirador

Export traces

Enrich traces with external actions

Delivery behavior

Correlate logs with traces

Next steps

Enrichment hints

Logs

​How OTLP maps to Mirador

​Export traces

​Enrich traces with external actions

​Delivery behavior

​Correlate logs with traces

​Next steps

Enrichment hints

Logs

How OTLP maps to Mirador

Export traces

Enrich traces with external actions

Delivery behavior

Correlate logs with traces

Next steps