Web Client SDK:
import { Trace } from '@miradorlabs/web-sdk';
import { Trace } from '@miradorlabs/nodejs-sdk';
You typically don’t instantiate Trace directly. Use client.trace() instead.
Methods
addAttribute()
Add a single attribute to the trace.
addAttribute(key: string, value: string | number | boolean | object): Trace
Parameters
| Parameter | Type | Description |
|---|
key | string | Attribute key |
value | string | number | boolean | object | Attribute value (objects are JSON stringified) |
Examples
trace.addAttribute('userId', 'user-123')
.addAttribute('amount', 1.5)
.addAttribute('config', { slippage: 0.5 }); // Stringified
addAttributes()
Add multiple attributes at once.
addAttributes(attrs: Record<string, string | number | boolean | object>): Trace
Parameters
| Parameter | Type | Description |
|---|
attrs | Record<string, any> | Object of key-value pairs |
Examples
trace.addAttributes({
from: '0xabc...',
to: '0xdef...',
value: 1.0,
metadata: { source: 'web' }
});
addTag()
Add a single tag to the trace.
addTag(tag: string): Trace
Parameters
| Parameter | Type | Description |
|---|
tag | string | Tag to add |
Examples
trace.addTag('ethereum')
.addTag('swap');
Add multiple tags at once.
addTags(tags: string[]): Trace
Parameters
| Parameter | Type | Description |
|---|
tags | string[] | Array of tags |
Examples
trace.addTags(['dex', 'uniswap', 'v3']);
addEvent()
Add a timestamped event to the trace.
addEvent(
name: string,
details?: string | object,
options?: AddEventOptions | Date
): Trace
Parameters
| Parameter | Type | Required | Description |
|---|
name | string | Yes | Event name |
details | string | object | No | Event details (objects are stringified) |
options | AddEventOptions | Date | No | Options with captureStackTrace, or legacy Date |
AddEventOptions
| Option | Type | Default | Description |
|---|
captureStackTrace | boolean | false | Capture stack trace at event location |
Examples
// Simple event
trace.addEvent('started');
// With string details
trace.addEvent('error', 'Connection timeout');
// With object details
trace.addEvent('transaction_sent', {
txHash: '0x123...',
gasUsed: 21000
});
// With stack trace capture
trace.addEvent('error_occurred', { code: 500 }, { captureStackTrace: true });
// Legacy: timestamp can still be passed for backward compatibility
trace.addEvent('operation_started', null, new Date());
addTxHint()
Add a blockchain transaction hash hint.
addTxHint(
txHash: string,
chain: ChainName,
details?: string
): Trace
Parameters
| Parameter | Type | Required | Description |
|---|
txHash | string | Yes | Transaction hash |
chain | ChainName | Yes | Blockchain network |
details | string | No | Description of the transaction |
ChainName Values
'ethereum''polygon''arbitrum''base''optimism''bsc'
Examples
trace.addTxHint('0x123...', 'ethereum');
trace.addTxHint('0x456...', 'polygon', 'Bridge transaction');
flush()
Send pending data to the gateway.
The first call sends CreateTrace, subsequent calls send UpdateTrace.
flush() is fire-and-forget. It returns immediately but maintains strict ordering of requests internally.
Examples
trace.addEvent('important_milestone');
trace.flush(); // Send immediately
getTraceId()
Get the trace ID after the first flush completes.
getTraceId(): string | null
Returns
string - The trace ID if availablenull - If the first flush hasn’t completed yet
Examples
const trace = client.trace({ name: 'MyTrace' });
trace.flush();
// Later, after flush completes
const traceId = trace.getTraceId();
if (traceId) {
console.log(`Trace ID: ${traceId}`);
}
create()
Submit the trace to the gateway (Node.js SDK only).
create(): Promise<string | undefined>
Returns
Promise<string | undefined> - The trace ID if successful, undefined if failed
This method is only available in the Node.js SDK. The Web SDK uses flush() instead. Keep-alive timer starts automatically after successful creation.
Examples
const trace = client.trace({ name: 'MyTrace' })
.addAttribute('userId', 'user-123')
.addEvent('started');
const traceId = await trace.create();
if (traceId) {
console.log(`Trace created: ${traceId}`);
}
addStackTrace()
Capture and add the current stack trace as an event.
addStackTrace(eventName?: string, additionalDetails?: object): Trace
Parameters
| Parameter | Type | Required | Description |
|---|
eventName | string | No | Event name (default: “stack_trace”) |
additionalDetails | object | No | Additional details to include |
Examples
trace.addStackTrace(); // Creates event named "stack_trace"
trace.addStackTrace('checkpoint', { stage: 'validation' });
addExistingStackTrace()
Add a previously captured stack trace as an event.
addExistingStackTrace(
stackTrace: StackTrace,
eventName?: string,
additionalDetails?: object
): Trace
Parameters
| Parameter | Type | Required | Description |
|---|
stackTrace | StackTrace | Yes | Previously captured stack trace |
eventName | string | No | Event name (default: “stack_trace”) |
additionalDetails | object | No | Additional details to include |
Examples
import { captureStackTrace } from '@miradorlabs/web-sdk';
// Capture stack trace now
const stack = captureStackTrace();
// ... later ...
trace.addExistingStackTrace(stack, 'deferred_location', { reason: 'async operation' });
close()
Close the trace and stop all timers. After calling this method, all subsequent operations will be ignored.
close(reason?: string): Promise<void>
Parameters
| Parameter | Type | Required | Description |
|---|
reason | string | No | Reason for closing the trace |
Examples
await trace.close();
await trace.close('User completed workflow');
// Best practice: use try-catch
const trace = client.trace({ name: 'CheckoutFlow' });
try {
// ... trace user checkout flow ...
await trace.close('Checkout completed');
} catch (error) {
trace.addEvent('error', { message: error.message });
await trace.close('Checkout failed');
}
Once a trace is closed, all method calls will be ignored with a warning. The keep-alive timer will be stopped and a close request will be sent to the server.
isClosed()
Check if the trace has been closed.
Returns
boolean - true if the trace has been closed, false otherwise
Examples
const closed = trace.isClosed();
if (!closed) {
trace.addEvent('still_active');
}
Method Chaining
All builder methods return this, enabling fluent chaining:
const trace = client.trace({ name: 'CompleteExample' })
.addAttribute('userId', 'user-123')
.addAttributes({ token: 'ETH', amount: 1.5 })
.addTag('swap')
.addTags(['dex', 'ethereum'])
.addEvent('initiated')
.addEvent('processing', { step: 1 })
.addTxHint('0x123...', 'ethereum', 'Main transaction');
Lifecycle
Web SDK:
client.trace() → Trace instance created
↓
addAttribute/addEvent/etc. → Data buffered
↓
flush() (first) → CreateTrace sent to gateway
↓
addAttribute/addEvent/etc. → More data buffered
↓
flush() (subsequent) → UpdateTrace sent to gateway
client.trace({ name: '...' }) → Trace instance created
↓
addAttribute/addEvent/etc. → Data buffered locally
↓
create() → CreateTrace sent to gateway
↓
addAttribute/addEvent/etc. → Data buffered locally
↓
close() → Final updates sent to gateway
Next Steps
