Node.js SDK (Deprecated)

@miradorlabs/nodejs-sdk is deprecated. Use a standard OpenTelemetry SDK for server-side instrumentation.

Mirador is an OTLP-native platform. For backend services, pointing a standard OpenTelemetry SDK at Mirador gives you more than the Node.js SDK does: traces, metrics, and logs through one vendor-neutral pipeline, in any language, with no Mirador-specific API to learn or migrate off later.

What this means


New services	Start with OpenTelemetry. Do not install `@miradorlabs/nodejs-sdk`.
Existing services	The package keeps working and stays installable on npm. No planned feature releases; critical fixes only.
Browser apps	`@miradorlabs/web-sdk` is not deprecated and remains fully supported.

Traces already ingested from the Node.js SDK are unaffected, and nothing changes in the dashboard.

Migrate to OpenTelemetry

Install the OTel SDK for your runtime and export to Mirador:

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

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

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

Auto-instrumentation covers HTTP, gRPC, database, and framework spans that the Node.js SDK never captured, so most services end up with more coverage than they started with.

API mapping

Node.js SDK	OpenTelemetry
`client.trace({ name })`	`tracer.startSpan(name)` (root span)
`trace.startSpan(name)` / `trace.span(name, fn)`	`tracer.startSpan(name)` / `tracer.startActiveSpan(name, fn)`
`trace.addAttribute(k, v)` / `addAttributes(obj)`	`span.setAttribute(k, v)` / `span.setAttributes(obj)`
`trace.info/warn/error(name, details)`	`span.addEvent(name, attrs)` plus `span.setStatus(...)`
`trace.addTags([...])`	Span or resource attributes
`trace.close()`	`span.end()`
`sampleRate` / `sampler`	`TraceIdRatioBased` or a custom `Sampler`
`debug: true` / custom `logger`	`diag` logger and `OTEL_LOG_LEVEL`

Web3 correlation

The web3.* hint methods map onto reserved mirador.* span events. The backend expands them into the same on-chain lifecycle, so nothing is lost:

Node.js SDK	OpenTelemetry span event
`trace.web3.evm.addTxHint(hash, chain)`	`mirador.web3.evm.txhint` with `tx.hash` + `chain.id`
`trace.web3.safe.addTxHint(hash, chain)`	`mirador.web3.safe.txhint` with `safe.tx_hash` + `chain.id`
`trace.web3.safe.addMsgHint(hash, chain)`	`mirador.web3.safe.msghint` with `safe.message_hash` + `chain.id`
`trace.web3.solana.addTxHint(sig)`	`mirador.web3.solana.txhint` with `tx.signature`
`trace.web3.relay.addQuoteHint(requestId)`	`mirador.web3.relay.requesthint` with `relay.request_id`
`trace.web3.canton.addTxHint(updateId, partyId?)`	`mirador.web3.canton.txhint` with `tx.update_id` + optional `canton.party_id`

// Before
trace.web3.evm.addTxHint(tx.hash, 'base');

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

See Enrichment hints for the full catalog, required attributes, and validation rules.

Migrating incrementally

Both paths write to the same pipeline, so you can move one service at a time. A service still on the Node.js SDK and a service already on OTel will correlate normally while both are in flight, as long as they share a trace ID.

Getting Started

OpenTelemetry

Web SDK

Web3 Integration

Payments & Market Data

Automations

AI & Agents

Best Practices

Node.js SDK (Deprecated)

What this means

Migrate to OpenTelemetry

API mapping

Web3 correlation

Migrating incrementally

Next steps

Pick your language

Enrichment hints

​What this means

​Migrate to OpenTelemetry

​API mapping

​Web3 correlation

​Migrating incrementally

​Next steps

Pick your language

Enrichment hints

What this means

Migrate to OpenTelemetry

API mapping

Web3 correlation

Migrating incrementally

Next steps