Skip to main content

​
What are Events?

Events are timestamped milestones within a trace. They record significant moments in your application flow, such as user actions, state changes, or external interactions.

​
Adding Events

Use addEvent() to record an event: 
trace.addEvent('button_clicked');

​
With Details

Events can include additional details as a string or object: 
// String details
trace.addEvent('error_occurred', 'Connection timeout');

// Object details (automatically stringified)
trace.addEvent('transaction_sent', {
  txHash: '0x123...',
  gasUsed: 21000,
  blockNumber: 12345678
});

​
With Custom Timestamp

By default, events use the current time. You can provide a custom timestamp using a Date object: 
const startTime = new Date();

// ... some operation ...

trace.addEvent('operation_started', null, startTime);
trace.addEvent('operation_completed');

​
Event Patterns

​
User Interaction Flow

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

trace.addEvent('cart_viewed')
     .addEvent('checkout_initiated')
     .addEvent('payment_method_selected', { method: 'crypto' })
     .addEvent('transaction_submitted')
     .addEvent('transaction_confirmed');

​
Error Handling

try {
  trace.addEvent('operation_started');
  await riskyOperation();
  trace.addEvent('operation_succeeded');
} catch (error) {
  trace.addEvent('operation_failed', {
    error: error.message,
    code: error.code
  });
}

​
State Transitions

trace.addEvent('state_change', { from: 'pending', to: 'processing' });
// ... later ...
trace.addEvent('state_change', { from: 'processing', to: 'completed' });

​
Method Signature

addEvent(
  name: string,
  details?: string | object,
  options?: AddEventOptions | Date
): Trace
ParameterTypeRequiredDescription
namestringYesEvent name
detailsstring | objectNoAdditional context
optionsAddEventOptions | DateNoOptions (e.g. { captureStackTrace: true }) or a Date timestamp

​
AddEventOptions

OptionTypeDefaultDescription
captureStackTracebooleanfalseCapture stack trace at event location

​
Best Practices

​
Use Consistent Naming

Adopt a naming convention for events: 
// snake_case for event names
trace.addEvent('wallet_connected');
trace.addEvent('transaction_signed');
trace.addEvent('swap_completed');

​
Record Both Success and Failure

Always capture the outcome: 
trace.addEvent('api_call_started', { endpoint: '/swap' });

if (success) {
  trace.addEvent('api_call_succeeded', { status: 200 });
} else {
  trace.addEvent('api_call_failed', { status: 500, error: message });
}

​
Include Relevant Context

Add details that help with debugging: 
trace.addEvent('validation_failed', {
  field: 'amount',
  value: userInput,
  reason: 'exceeds_balance'
});

​
Don’t Over-Event

Record significant milestones, not every micro-operation: 
// Good - meaningful milestones
trace.addEvent('form_submitted');
trace.addEvent('validation_passed');
trace.addEvent('transaction_sent');

// Avoid - too granular
trace.addEvent('field_focused');
trace.addEvent('character_typed');
trace.addEvent('field_blurred');

​
Next Steps

Attributes & Tags

Add metadata to your traces

Transaction Hints

Correlate with blockchain transactions