Quickstart

This walkthrough uses the standard OpenTelemetry SDK for your language. No Mirador package is required.

Building a browser app that needs wallet capture? Use the Web SDK instead.

1. Create an API key

In the Mirador dashboard, open your project’s API keys page and create a server key (mir_srv_*). Keep it out of source control.

2. Install an OpenTelemetry SDK

npm install @opentelemetry/sdk-node \
            @opentelemetry/auto-instrumentations-node \
            @opentelemetry/exporter-trace-otlp-http

pip install opentelemetry-distro opentelemetry-exporter-otlp
opentelemetry-bootstrap -a install

go get go.opentelemetry.io/otel \
       go.opentelemetry.io/otel/sdk \
       go.opentelemetry.io/otel/exporters/otlp/otlptrace/otlptracehttp

curl -L -O https://github.com/open-telemetry/opentelemetry-java-instrumentation/releases/latest/download/opentelemetry-javaagent.jar

See Pick your language for .NET, Rust, Ruby, PHP, Erlang/Elixir, Swift, and C++.

3. Point it at Mirador

Every OpenTelemetry SDK reads these standard variables:

export OTEL_SERVICE_NAME=checkout-api
export OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf
export OTEL_EXPORTER_OTLP_ENDPOINT=https://otel.mirador.org
export OTEL_EXPORTER_OTLP_HEADERS=Authorization=mir_srv_xxx

With the base endpoint set, HTTP exporters append /v1/traces, /v1/metrics, and /v1/logs automatically. For OTLP/gRPC, use otel.mirador.org:4317 and set OTEL_EXPORTER_OTLP_PROTOCOL=grpc.

4. Run your service

node --require @opentelemetry/auto-instrumentations-node/register app.js

opentelemetry-instrument python app.py

go run .

java -javaagent:./opentelemetry-javaagent.jar -jar app.jar

Exercise a request. Auto-instrumentation produces spans for inbound HTTP, outbound calls, and database queries with no code changes. Traces appear in the Mirador dashboard within a few seconds.

5. Add your own span

Wrap a meaningful unit of work so the trace reflects your domain, not just transport:

import { trace } from '@opentelemetry/api';

const tracer = trace.getTracer('checkout');

await tracer.startActiveSpan('checkout.submit', async (span) => {
  span.setAttribute('order.id', orderId);
  span.setAttribute('user.wallet', walletAddress);
  try {
    await submitOrder();
  } finally {
    span.end();
  }
});

from opentelemetry import trace

tracer = trace.get_tracer("checkout")

with tracer.start_as_current_span("checkout.submit") as span:
    span.set_attribute("order.id", order_id)
    span.set_attribute("user.wallet", wallet_address)
    submit_order()

tracer := otel.Tracer("checkout")

ctx, span := tracer.Start(ctx, "checkout.submit")
span.SetAttributes(
    attribute.String("order.id", orderID),
    attribute.String("user.wallet", walletAddress),
)
defer span.End()

submitOrder(ctx)

6. Correlate an on-chain action

This is the step that makes a Mirador trace different from a generic OTel trace. When an external action starts, emit a reserved mirador.* span event carrying its identity. Mirador follows the action and stitches the outcome (receipt, bridge fill, confirmation, refund) back into the same trace.

const txHash = await wallet.sendTransaction(tx);

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

span.add_event("mirador.web3.evm.txhint", {
    "tx.hash": tx_hash,
    "chain.id": 8453,
})

span.AddEvent("mirador.web3.evm.txhint", trace.WithAttributes(
    attribute.String("tx.hash", txHash),
    attribute.Int64("chain.id", 8453),
))

Emit the event only after the external system returns its identity, and use flat attribute keys ('tx.hash', not a nested object). A hint missing a required attribute is preserved as an ordinary span event, so typos stay visible instead of silently dropping.

EVM, Solana, Canton, Safe, Relay, Stripe, and market rates are supported. See Enrichment hints for the full catalog.

Next steps

Pick your language

Setup for every supported runtime

Enrichment hints

Every reserved event and its required attributes

Logs and metrics

Send all three OTLP signals to the same endpoint

Best practices

Naming, attributes, and sampling guidance

Getting Started

OpenTelemetry

Web SDK

Web3 Integration

Payments & Market Data

Automations

AI & Agents

Best Practices

1. Create an API key

2. Install an OpenTelemetry SDK

3. Point it at Mirador

4. Run your service

5. Add your own span

6. Correlate an on-chain action

Next steps

Pick your language

Enrichment hints

Logs and metrics

Best practices

​1. Create an API key

​2. Install an OpenTelemetry SDK

​3. Point it at Mirador

​4. Run your service

​5. Add your own span

​6. Correlate an on-chain action

​Next steps

Pick your language

Enrichment hints

Logs and metrics

Best practices

1. Create an API key

2. Install an OpenTelemetry SDK

3. Point it at Mirador

4. Run your service

5. Add your own span

6. Correlate an on-chain action

Next steps