Traces

What is a Trace?

A trace represents a single logical operation or flow in your application. It’s the fundamental unit of data in the Mirador platform. Traces capture:

The operation name
Attributes (key-value metadata)
Tags (categorical labels)
Events (timestamped milestones)
Transaction hints (blockchain correlation)

Creating a Trace

Create a trace using the client.trace() method:

const trace = client.trace({ name: 'UserCheckout' });

Trace Options

Web SDK:

Option	Type	Default	Description
`name`	`string`	`undefined`	Name identifying the trace
`traceId`	`string`	`undefined`	Resume an existing trace by ID
`includeUserMeta`	`boolean`	`true`	Include browser metadata
`maxRetries`	`number`	`2`	Retry attempts on failure
`retryBackoff`	`number`	`500`	Base backoff delay (ms)
`autoClose`	`boolean`	`false`	Automatically close trace on page unload
`autoKeepAlive`	`boolean`	`true` / `false`	Auto-start keep-alive timer (`true` for new traces, `false` when `traceId` is set)

const trace = client.trace({
  name: 'CriticalOperation',
  includeUserMeta: true,
  maxRetries: 5
});

Node.js SDK:

Option	Type	Default	Description
`name`	`string`	`undefined`	Name identifying the trace
`traceId`	`string`	`undefined`	Resume an existing trace by ID (e.g., from frontend SDK)
`captureStackTrace`	`boolean`	`true`	Capture stack trace at trace creation
`maxRetries`	`number`	`2`	Retry attempts on failure
`retryBackoff`	`number`	`500`	Base backoff delay (ms)
`autoKeepAlive`	`boolean`	`true` / `false`	Auto-start keep-alive timer (`true` for new traces, `false` when `traceId` is set)

const trace = client.trace({
  name: 'BackendOperation',
  traceId: req.headers['x-mirador-trace-id'], // optional: resume frontend trace
  captureStackTrace: false
});

Trace Lifecycle

Create

Call client.trace() to create a new trace builder

Build

Add attributes, tags, events, and transaction hints using the fluent API

Flush

First flush sends FlushTrace to the gateway

Update

Subsequent flushes send FlushTrace with new data

Keep-Alive & Closing Traces

The SDK sends periodic keep-alive pings to the server to maintain trace liveness. The ping interval is configurable at the client level:

const client = new Client('your-api-key', {
  keepAliveIntervalMs: 15000  // Ping every 15 seconds (default: 10000)
});

Smart Defaults

The autoKeepAlive option controls whether the keep-alive timer starts automatically when a trace is created:

New traces (autoKeepAlive defaults to true): the timer starts automatically after the first flush.
Resumed traces (when traceId is set, autoKeepAlive defaults to false): the timer does not start automatically.

This prevents zombie keep-alive timers — for example, when a backend resumes a frontend trace just to append a few events and close it, there’s no need for the backend to keep pinging.

// New trace — keep-alive starts automatically
const trace = client.trace({ name: 'UserSession' });

// Resumed trace — no keep-alive by default
const resumed = client.trace({
  traceId: req.headers['x-mirador-trace-id'],
  name: 'BackendHandler'
});

// Override the default: force keep-alive on a resumed trace
const resumedWithKeepalive = client.trace({
  traceId: req.headers['x-mirador-trace-id'],
  name: 'LongRunningBackend',
  autoKeepAlive: true
});

Manual Control

You can manually start or stop the keep-alive timer at any time using the startKeepAlive() and stopKeepAlive() methods on the trace. Both methods are idempotent — calling them multiple times is safe.

const trace = client.trace({ name: 'ManualControl', autoKeepAlive: false });

// Start keep-alive manually when needed
trace.startKeepAlive();

// Stop it when the trace is idle
trace.stopKeepAlive();

Resilience

The keep-alive timer is resilient to transient network issues:

An in-flight guard prevents overlapping pings if a previous ping hasn’t completed yet.
On failure, the SDK performs a single retry before counting the attempt as failed.
After 3 consecutive failures, the timer automatically stops to avoid wasting resources.

Max Trace Lifetime

You can bound the maximum lifetime of a trace independently of keep-alive using the maxTraceLifetimeMs client option. When the lifetime is exceeded, the trace is automatically closed.

const client = new Client('your-api-key', {
  maxTraceLifetimeMs: 300000  // Auto-close traces after 5 minutes
});

maxTraceLifetimeMs defaults to 0 (disabled). When set, it applies to all traces created by the client.

Closing Traces

Always close traces when you’re done to clean up resources:

const trace = client.trace({ name: 'UserSession' });

try {
  // ... add events, attributes, etc ...
  await trace.close('Session ended');
} catch (error) {
  trace.addEvent('error', { message: error.message });
  await trace.close('Session failed');
}

Enable auto-close on page unload for browser applications:

const trace = client.trace({
  name: 'UserSession',
  autoClose: true  // Automatically close on page unload
});

The Builder Pattern

The Trace class uses a fluent builder pattern. All methods return this, allowing you to chain calls:

const trace = client.trace({ name: 'SwapExecution' })
  .addAttribute('from', '0xabc...')
  .addAttribute('to', '0xdef...')
  .addTags(['dex', 'swap', 'ethereum'])
  .addEvent('quote_received', { price: '1.5' })
  .addEvent('user_approved');

trace.web3.evm.addTxHint('0x123...', 'ethereum');
trace.web3.safe.addMsgHint('0xabc...', 'ethereum', 'Multisig approval');

Getting the Trace ID

In v2, the trace ID is generated client-side at creation time and is available immediately via getTraceId():

const trace = client.trace({ name: 'MyTrace' });
const traceId = trace.getTraceId(); // Available immediately
console.log('Trace ID:', traceId);

Client-Side Trace ID Generation

In v2, trace IDs are generated client-side at creation time as W3C Tracing Context compatible 32-character hex strings. The ID is available immediately via getTraceId() — no need to wait for the server response.

const trace = client.trace({ name: 'MyTrace' });
const traceId = trace.getTraceId(); // Available immediately

// Pass to backend before any network call
fetch('/api/action', {
  headers: { 'X-Mirador-Trace-Id': traceId }
});

This is especially important for cross-SDK trace sharing — the frontend can generate the ID and pass it to the backend via headers before any network call completes.

Flushing

Both the Web SDK and Node.js SDK automatically batch and send trace data at the end of the current JavaScript tick (microtask). All flushes send idempotent FlushTrace requests. You can also call flush() manually at any time to send pending data immediately:

const trace = client.trace({ name: 'MyTrace' })
  .addAttribute('key', 'value')
  .addEvent('started');

trace.flush();  // Send immediately instead of waiting for microtask

flush() is fire-and-forget — it returns void and maintains strict ordering of requests internally.

You can share a trace between the frontend (Web SDK) and backend (Node.js SDK) so that both sides contribute data to the same trace. This is useful when a user action in the browser triggers a backend API call that you want to correlate.

How It Works

The frontend creates a trace — the ID is available immediately via getTraceId()
The trace ID is passed to the backend (e.g., via an HTTP header) before any network call completes
The backend resumes the trace by passing traceId in TraceOptions

Frontend (Web SDK)

const trace = client.trace({ name: 'TokenSwap' })
  .addAttribute('wallet', userAddress)
  .addEvent('swap:initiated');

// ID is available immediately — no flush needed first
const traceId = trace.getTraceId();

// Pass trace ID to backend via HTTP header
const response = await fetch('/api/swap', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-Mirador-Trace-Id': traceId
  },
  body: JSON.stringify(swapParams)
});

Backend (Node.js SDK)

import { Client } from '@miradorlabs/nodejs-sdk';

const mirador = new Client(process.env.MIRADOR_API_KEY);

app.post('/api/swap', async (req, res) => {
  // Resume the frontend trace
  const trace = mirador.trace({
    traceId: req.headers['x-mirador-trace-id'],
    name: 'SwapBackend'
  })
    .addAttribute('endpoint', '/api/swap')
    .addEvent('backend:received');

  try {
    const result = await executeSwap(req.body);
    trace.addEvent('backend:completed', { txHash: result.hash });
    await trace.close('success');
    res.json(result);
  } catch (error) {
    trace.addEvent('backend:error', { message: error.message });
    await trace.close('error');
    res.status(500).json({ error: error.message });
  }
});

Backend → Frontend

You can also create a trace on the backend and resume it on the frontend:

// Backend creates the trace and returns the ID in the response
app.get('/api/session', async (req, res) => {
  const trace = mirador.trace({ name: 'UserSession' })
    .addAttribute('userId', req.user.id)
    .addEvent('session:started');

  // ID is available immediately
  const traceId = trace.getTraceId();

  res.json({ traceId });
});

// Frontend resumes the trace
const { traceId } = await fetch('/api/session').then(r => r.json());

const trace = client.trace({ name: 'UserSession', traceId })
  .addEvent('frontend:loaded');

Best Practices

Name Traces Descriptively

Use clear, action-oriented names:

// Good
client.trace({ name: 'UserSignup' })
client.trace({ name: 'TokenSwap' })
client.trace({ name: 'NFTMint' })

// Avoid
client.trace({ name: 'trace1' })
client.trace({ name: 'data' })

One Trace Per Logical Operation

Create a new trace for each distinct user action or flow:

// User connects wallet
const connectTrace = client.trace({ name: 'WalletConnect' });

// User initiates swap (separate operation)
const swapTrace = client.trace({ name: 'TokenSwap' });

Include Context Early

Add identifying attributes at trace creation:

const trace = client.trace({ name: 'Transfer' })
  .addAttribute('userId', currentUser.id)
  .addAttribute('sessionId', session.id)
  .addAttribute('walletAddress', wallet.address);

Getting Started

Core Concepts

Web3 Integration

OpenTelemetry

Automations

AI & Agents

Advanced

Best Practices

What is a Trace?

Creating a Trace

Trace Options

Trace Lifecycle

Keep-Alive & Closing Traces

Smart Defaults

Manual Control

Resilience

Max Trace Lifetime

Closing Traces

The Builder Pattern

Getting the Trace ID

Client-Side Trace ID Generation

Flushing

How It Works

Frontend (Web SDK)

Backend (Node.js SDK)

Backend → Frontend

Best Practices

Name Traces Descriptively

One Trace Per Logical Operation

Include Context Early

Next Steps

Events

Attributes & Tags

​What is a Trace?

​Creating a Trace

​Trace Options

​Trace Lifecycle

​Keep-Alive & Closing Traces

​Smart Defaults

​Manual Control

​Resilience

​Max Trace Lifetime

​Closing Traces

​The Builder Pattern

​Getting the Trace ID

​Client-Side Trace ID Generation

​Flushing

​Cross-SDK Trace Sharing

​How It Works

​Frontend (Web SDK)

​Backend (Node.js SDK)

​Backend → Frontend

​Best Practices

​Name Traces Descriptively

​One Trace Per Logical Operation

​Include Context Early

​Next Steps

Events

Attributes & Tags

What is a Trace?

Creating a Trace

Trace Options

Trace Lifecycle

Keep-Alive & Closing Traces

Smart Defaults

Manual Control

Resilience

Max Trace Lifetime

Closing Traces

The Builder Pattern

Getting the Trace ID

Client-Side Trace ID Generation

Flushing

Cross-SDK Trace Sharing

How It Works

Frontend (Web SDK)

Backend (Node.js SDK)

Backend → Frontend

Best Practices

Name Traces Descriptively

One Trace Per Logical Operation

Include Context Early

Next Steps