4.9 KiB

Raw Blame History

IronTelemetry SDK for JavaScript/TypeScript

Error monitoring and crash reporting SDK for JavaScript and TypeScript applications. Capture exceptions, track user journeys, and get insights to fix issues faster.

Installation

npm install @ironservices/telemetry
# or
yarn add @ironservices/telemetry
# or
pnpm add @ironservices/telemetry

Quick Start

Basic Exception Capture

import IronTelemetry from '@ironservices/telemetry';

// Initialize with your DSN
IronTelemetry.init('https://pk_live_xxx@irontelemetry.com');

// Capture exceptions
try {
  doSomething();
} catch (error) {
  IronTelemetry.captureException(error);
  throw error;
}

// Or use the extension method
try {
  doSomething();
} catch (error) {
  throw error.capture();
}

Journey Tracking

Track user journeys to understand the context of errors:

import IronTelemetry from '@ironservices/telemetry';

// Track a complete user journey
{
  using journey = IronTelemetry.startJourney('Checkout Flow');

  IronTelemetry.setUser('user-123', 'user@example.com');

  {
    using step = IronTelemetry.startStep('Validate Cart', 'business');
    validateCart();
  }

  {
    using step = IronTelemetry.startStep('Process Payment', 'business');
    processPayment();
  }

  {
    using step = IronTelemetry.startStep('Send Confirmation', 'notification');
    sendConfirmationEmail();
  }
}

Any exceptions captured during the journey are automatically correlated.

Configuration

import IronTelemetry from '@ironservices/telemetry';

IronTelemetry.init({
  dsn: 'https://pk_live_xxx@irontelemetry.com',
  environment: 'production',
  appVersion: '1.2.3',
  sampleRate: 1.0,  // 100% of events
  debug: false,
  beforeSend: (event) => !event.message?.includes('expected error'),
});

Configuration Options

Option	Type	Default	Description
`dsn`	string	required	Your Data Source Name
`environment`	string	'production'	Environment name
`appVersion`	string	'0.0.0'	Application version
`sampleRate`	number	1.0	Sample rate (0.0 to 1.0)
`maxBreadcrumbs`	number	100	Max breadcrumbs to keep
`debug`	boolean	false	Enable debug logging
`beforeSend`	function	-	Hook to filter/modify events
`enableOfflineQueue`	boolean	true	Enable offline queue
`maxOfflineQueueSize`	number	500	Max offline queue size

Features

Automatic Exception Capture: Capture and report exceptions with full stack traces
Journey Tracking: Track user flows and correlate errors with context
Breadcrumbs: Leave a trail of events leading up to an error
User Context: Associate errors with specific users
Tags & Extras: Add custom metadata to your events
Offline Queue: Events are queued when offline and sent when connectivity returns
Sample Rate: Control the volume of events sent
Before Send Hook: Filter or modify events before sending

Breadcrumbs

// Add breadcrumbs to understand what happened before an error
IronTelemetry.addBreadcrumb('User clicked checkout button', 'ui');
IronTelemetry.addBreadcrumb('Payment API called', 'http');

// Or with full control
IronTelemetry.addBreadcrumb({
  category: 'auth',
  message: 'User logged in',
  level: 'info',
  data: { userId: '123' },
});

Global Exception Handling

import IronTelemetry, { useUnhandledExceptionHandler } from '@ironservices/telemetry';

IronTelemetry.init('your-dsn');
useUnhandledExceptionHandler();

This sets up handlers for:

Browser: window.onerror and unhandledrejection
Node.js: uncaughtException and unhandledRejection

Helper Methods

import { trackStep, trackStepAsync } from '@ironservices/telemetry';

// Track a step with automatic error handling
trackStep('Process Order', () => {
  processOrder();
});

// Async version
await trackStepAsync('Fetch Data', async () => {
  await fetchData();
});

// With return value
const result = trackStep('Calculate Total', () => {
  return calculateTotal();
});

Flushing

// Flush pending events before app shutdown
await IronTelemetry.flush();

TypeScript Support

This package is written in TypeScript and includes full type definitions:

import IronTelemetry, {
  TelemetryOptions,
  TelemetryEvent,
  Breadcrumb,
  SeverityLevel
} from '@ironservices/telemetry';

Browser Support

Works in all modern browsers (Chrome, Firefox, Safari, Edge) and Node.js 16+.

License

MIT License - see LICENSE for details.

4.9 KiB Raw Blame History