> ## 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.

# Node.js SDK (Deprecated)

> The Node.js SDK is deprecated in favor of OpenTelemetry

<Warning>
  **`@miradorlabs/nodejs-sdk` is deprecated.** Use a standard [OpenTelemetry SDK](/opentelemetry/sdks) for server-side instrumentation.
</Warning>

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](/opentelemetry/sdks). 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`](/web-sdk/overview) 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:

```bash theme={null}
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` |

```typescript theme={null}
// 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](/opentelemetry/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.

## Next steps

<CardGroup cols={2}>
  <Card title="Pick your language" icon="code" href="/opentelemetry/sdks">
    Install the OTel SDK for your runtime
  </Card>

  <Card title="Enrichment hints" icon="wand-magic-sparkles" href="/opentelemetry/enrichment-hints">
    Keep web3 correlation after the move
  </Card>
</CardGroup>