Client - Mirador SDK

Overview

Client is the main entry point for the Mirador SDK. It handles authentication, plugin registration, sampling, and creates trace builders.

Import

Web SDK:

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

Node.js SDK:

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

Constructor

Web SDK:

new Client(apiKey: string, options?: ClientOptions)

Node.js SDK:

new Client(apiKey?: string, options?: ClientOptions)

Parameters

Parameter	Type	Required	Description
`apiKey`	`string`	Yes (Web) / No (Node.js)	API key for authentication
`options`	`ClientOptions`	No	Configuration options

Options

Web SDK:

interface ClientOptions {
  apiUrl?: string;              // Gateway URL (default: ingest.mirador.org:443)
  keepAliveIntervalMs?: number; // Keep-alive ping interval in milliseconds (default: 10000)
  callTimeoutMs?: number;       // Timeout for individual API calls in milliseconds (default: 5000)
  maxTraceLifetimeMs?: number;  // Max trace lifetime in milliseconds (default: 0 / disabled)
  debug?: boolean;              // Enable debug logging (default: false)
  logger?: Logger;              // Custom logger implementation
  callbacks?: TraceCallbacks;   // Lifecycle callbacks for all traces
  sampleRate?: number;          // Sampling rate 0-1 (default: 1)
  sampler?: Function;           // Custom sampler function
  plugins?: MiradorPlugin[];    // Plugins to install on all traces
}

Node.js SDK:

interface ClientOptions {
  apiUrl?: string;              // Gateway URL (default: ingest.mirador.org:443)
  keepAliveIntervalMs?: number; // Keep-alive ping interval in milliseconds (default: 10000)
  callTimeoutMs?: number;       // Timeout for individual API calls in milliseconds (default: 5000)
  maxTraceLifetimeMs?: number;  // Max trace lifetime in milliseconds (default: 0 / disabled)
  debug?: boolean;              // Enable debug logging (default: false)
  logger?: Logger;              // Custom logger implementation
  callbacks?: TraceCallbacks;   // Lifecycle callbacks for all traces
  sampleRate?: number;          // Sampling rate 0-1 (default: 1)
  sampler?: Function;           // Custom sampler function
  plugins?: MiradorPlugin[];    // Plugins to install on all traces
  useSsl?: boolean;             // Use SSL for gRPC connection (default: true)
}

Examples

Basic initialization:

const client = new Client('your-api-key');

With custom gateway:

const client = new Client('your-api-key', {
  apiUrl: 'https://custom-gateway.example.com:443'
});

With custom keep-alive interval:

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

With Web3Plugin:

import { Client, Web3Plugin } from '@miradorlabs/web-sdk';

const client = new Client('your-api-key', {
  plugins: [Web3Plugin({ provider: window.ethereum })]
});

// All traces have web3 methods available
const trace = client.trace({ name: 'Swap' });
const txHash = await trace.web3.evm.sendTransaction({
  from: userAddress,
  to: contractAddress,
  data: calldata
});

Sampling

Control what percentage of traces are recorded. Unsampled traces return a NoopTrace that silently discards all operations, so your code doesn’t need any conditional checks. Fixed sample rate:

const client = new Client('your-api-key', {
  sampleRate: 0.1  // Record 10% of traces
});

Custom sampler function:

const client = new Client('your-api-key', {
  sampler: (name, options) => {
    // Always record critical operations
    if (name === 'Payment') return true;
    // Sample everything else at 10%
    return Math.random() < 0.1;
  }
});

Lifecycle Callbacks

Register callbacks to observe trace lifecycle events across all traces. See the Lifecycle Callbacks guide for detailed usage patterns and examples.

const client = new Client('your-api-key', {
  callbacks: {
    onCreated: (traceId) => console.log('Trace created:', traceId),
    onFlushed: (traceId, itemCount) => console.log(`Flushed ${itemCount} items for ${traceId}`),
    onFlushError: (error, operation) => console.error(`${operation} failed:`, error),
    onClosed: (traceId, reason) => console.log('Trace closed:', traceId, reason),
    onDropped: (count, reason) => console.warn(`Dropped ${count} items: ${reason}`)
  }
});

Methods

trace()

Creates a new trace builder. Web SDK:

trace(options?: TraceOptions): Trace

Node.js SDK:

trace(options?: TraceOptions): Trace

Parameters

Parameter	Type	Required	Description
`options`	`TraceOptions`	No	Trace configuration

TraceOptions

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`	Maximum retry attempts
`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)
`maxQueueSize`	`number`	`4096`	Max items in flush queue before dropping
`callbacks`	`TraceCallbacks`	`undefined`	Per-trace lifecycle callbacks

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`	Maximum retry attempts
`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)
`maxQueueSize`	`number`	`4096`	Max items in flush queue before dropping
`callbacks`	`TraceCallbacks`	`undefined`	Per-trace lifecycle callbacks

Returns

Trace - A trace builder instance (or NoopTrace if the trace is not sampled)

Examples

Web SDK - Basic trace:

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

Web SDK - With full options:

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

Node.js SDK - Basic trace:

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

Node.js SDK - Without stack trace:

const trace = client.trace({ name: 'UserAction', captureStackTrace: false });

Usage Patterns

Single Client Instance

Create one client instance and reuse it: Web SDK:

// client.ts
import { Client, Web3Plugin } from '@miradorlabs/web-sdk';

export const mirador = new Client(process.env.MIRADOR_API_KEY, {
  plugins: [Web3Plugin({ provider: window.ethereum })]
});

// component.ts
import { mirador } from './client';

function handleAction() {
  const trace = mirador.trace({ name: 'ComponentAction' });
  // ...
}

Node.js SDK:

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

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

// handler.ts
import { mirador } from './client';

async function handleAction() {
  const trace = mirador.trace({ name: 'ComponentAction' })
    .addAttribute('action', 'process')
    .addEvent('started');
  // → auto-flushed at end of current JS tick

  // ... do work ...

  await trace.close('done');
}

Multiple Traces

A single client can create multiple concurrent traces: Web SDK:

const client = new Client('api-key');

// User flow trace
const userTrace = client.trace({ name: 'UserSession' });

// Background operation trace
const bgTrace = client.trace({ name: 'BackgroundSync' });

// Both traces operate independently
userTrace.addEvent('user_clicked');
bgTrace.addEvent('sync_started');

Node.js SDK:

const client = new Client('api-key');

// Both traces operate independently — auto-flushed
const userTrace = client.trace({ name: 'UserSession' })
  .addEvent('user_clicked');

const bgTrace = client.trace({ name: 'BackgroundSync' })
  .addEvent('sync_started');

Environment-Based Configuration

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

Authentication

The API key is sent with every request in the x-ingest-api-key header. Keep your API key secure:

Don’t commit it to version control
Use environment variables
Consider using different keys for dev/prod

Next Steps

Trace

Trace builder methods

Types

TypeScript type definitions

Classes

Web3

Types

​Overview

​Import

​Constructor

​Parameters

​Options

​Examples

​Sampling

​Lifecycle Callbacks

​Methods

​trace()

​Parameters

​TraceOptions

​Returns

​Examples

​Usage Patterns

​Single Client Instance

​Multiple Traces

​Environment-Based Configuration

​Authentication

​Next Steps

Trace

Types

Overview

Import

Constructor

Parameters

Options

Examples

Sampling

Lifecycle Callbacks

Methods

trace()

Parameters

TraceOptions

Returns

Examples

Usage Patterns

Single Client Instance

Multiple Traces

Environment-Based Configuration

Authentication

Next Steps