API Reference

Full reference for all exported functions from @statly/observe.

Initialization

init(options)

Initialize the SDK. Call once at application startup.

function init(options: StatlyOptions): void

Parameters:

options - Configuration object (see Configuration)

Example:

import { init } from '@statly/observe';
 
init({
  dsn: 'https://[email protected]/your-org',
  environment: 'production',
});

Capturing Events

captureException(error, context?)

Capture an error or exception.

function captureException(
  error: Error | unknown,
  context?: Record<string, unknown>
): string

Parameters:

error - The error to capture
context - Optional additional context

Returns: Event ID (UUID string)

Example:

import { captureException } from '@statly/observe';
 
try {
  riskyOperation();
} catch (error) {
  const eventId = captureException(error, {
    operation: 'riskyOperation',
    userId: currentUser.id,
  });
  console.log('Captured event:', eventId);
}

captureMessage(message, level?)

Capture a message event.

function captureMessage(
  message: string,
  level?: 'debug' | 'info' | 'warning' | 'error' | 'fatal'
): string

Parameters:

message - Message text
level - Severity level (default: 'info')

Returns: Event ID

Example:

import { captureMessage } from '@statly/observe';
 
captureMessage('User completed onboarding', 'info');
captureMessage('Payment processing slow', 'warning');
captureMessage('Database connection lost', 'fatal');

Context Management

setUser(user)

Set user context for all future events.

function setUser(user: User | null): void
 
interface User {
  id?: string;
  email?: string;
  username?: string;
  name?: string;
  [key: string]: unknown; // Custom fields
}

Example:

import { setUser } from '@statly/observe';
 
// Set user after login
setUser({
  id: 'user_123',
  email: '[email protected]',
  username: 'janedoe',
  plan: 'enterprise', // Custom field
});
 
// Clear user on logout
setUser(null);

setTag(key, value)

Set a single tag.

function setTag(key: string, value: string): void

Example:

import { setTag } from '@statly/observe';
 
setTag('feature', 'checkout');
setTag('experiment', 'new_ui');

setTags(tags)

Set multiple tags at once.

function setTags(tags: Record<string, string>): void

Example:

import { setTags } from '@statly/observe';
 
setTags({
  region: 'us-east-1',
  service: 'payment-api',
  version: '2.1.0',
});

Breadcrumbs

addBreadcrumb(breadcrumb)

Add a breadcrumb to the trail.

function addBreadcrumb(breadcrumb: Omit<Breadcrumb, 'timestamp'>): void
 
interface Breadcrumb {
  message?: string;
  category?: string;
  level?: 'debug' | 'info' | 'warning' | 'error';
  data?: Record<string, unknown>;
  timestamp?: number; // Auto-set
}

Example:

import { addBreadcrumb } from '@statly/observe';
 
// Navigation
addBreadcrumb({
  category: 'navigation',
  message: 'User navigated to /checkout',
  level: 'info',
});
 
// User action
addBreadcrumb({
  category: 'user',
  message: 'Clicked "Submit Order"',
  level: 'info',
  data: { orderId: 'ord_123' },
});
 
// API call
addBreadcrumb({
  category: 'http',
  message: 'POST /api/orders',
  level: 'info',
  data: { status: 201, duration: 245 },
});

Lifecycle

flush()

Wait for all pending events to be sent.

function flush(): Promise<void>

Example:

import { flush, captureMessage } from '@statly/observe';
 
captureMessage('Important event');
await flush(); // Wait for event to be sent
process.exit(0);

close()

Flush pending events and shut down the SDK.

function close(): Promise<void>

Example:

import { close } from '@statly/observe';
 
// Before server shutdown
process.on('SIGTERM', async () => {
  await close();
  process.exit(0);
});

getClient()

Get the SDK client instance.

function getClient(): StatlyClient | null

Example:

import { getClient } from '@statly/observe';
 
const client = getClient();
if (client) {
  console.log('SDK is initialized');
}

Types

StatlyOptions

interface StatlyOptions {
  dsn: string;
  environment?: string;
  release?: string;
  debug?: boolean;
  sampleRate?: number;
  maxBreadcrumbs?: number;
  autoCapture?: boolean;
  captureConsole?: boolean;
  tags?: Record<string, string>;
  beforeSend?: (event: StatlyEvent) => StatlyEvent | null;
}

StatlyEvent

interface StatlyEvent {
  message: string;
  timestamp?: number;
  level?: 'debug' | 'info' | 'warning' | 'error' | 'fatal';
  stack?: string;
  exception?: {
    type?: string;
    value?: string;
    stacktrace?: { frames?: StackFrame[] };
  };
  environment?: string;
  release?: string;
  url?: string;
  user?: User;
  tags?: Record<string, string>;
  extra?: Record<string, unknown>;
  breadcrumbs?: Breadcrumb[];
  browser?: { name?: string; version?: string };
  os?: { name?: string; version?: string };
  sdk?: { name: string; version: string };
}

User

interface User {
  id?: string;
  email?: string;
  username?: string;
  name?: string;
  [key: string]: unknown;
}

Breadcrumb

interface Breadcrumb {
  timestamp?: number;
  category?: string;
  message?: string;
  level?: 'debug' | 'info' | 'warning' | 'error';
  data?: Record<string, unknown>;
}

Configuration Express.js