🚀 Try Statly for free →
SDKs
JavaScript
Configuration

Configuration

Customize SDK behavior with configuration options.

All Options

import { init } from '@statly/observe';
 
init({
  // Required
  dsn: 'https://[email protected]/your-org',
 
  // Optional
  environment: 'production',      // Environment name
  release: '1.2.3',              // App version
  debug: false,                   // Enable debug logging
  sampleRate: 1.0,               // 0.0-1.0, event sampling
  maxBreadcrumbs: 100,           // Max breadcrumbs stored
  autoCapture: true,             // Auto-capture global errors
  captureConsole: true,          // Capture console.error as breadcrumbs
  tags: {                        // Default tags for all events
    service: 'api',
    team: 'backend',
  },
  beforeSend: (event) => event,  // Modify/filter events
});

Option Reference

dsn

Required. Your Data Source Name containing API key and organization.

dsn: 'https://[email protected]/acme'

Format: https://<api-key>@statly.live/<org-slug>

environment

Environment name for filtering events in the dashboard.

environment: 'production' // or 'staging', 'development'

If not set, auto-detected from window.location.hostname:

  • localhost or 127.0.0.1 → 'development'
  • Contains staging or stage → 'staging'
  • Otherwise → 'production'

release

Your application version. Used for release tracking and error grouping.

release: '1.2.3' // or 'abc123' (commit hash)

debug

Enable verbose logging to console for troubleshooting.

debug: true

Logs SDK initialization, event capture, and transport activity.

sampleRate

Probability that an event will be sent (0.0 to 1.0).

sampleRate: 0.5 // Send 50% of events

Useful for high-traffic applications to reduce volume.

maxBreadcrumbs

Maximum number of breadcrumbs to store per event.

maxBreadcrumbs: 50 // Default: 100

Oldest breadcrumbs are dropped when limit is reached.

autoCapture

Automatically capture global errors.

autoCapture: true // Default: true

When enabled, attaches handlers to:

  • window.onerror (browser)
  • unhandledrejection event (browser)
  • process.on('uncaughtException') (Node.js)
  • process.on('unhandledRejection') (Node.js)

captureConsole

Capture console.error, console.warn, etc. as breadcrumbs.

captureConsole: true // Default: true

Maps console methods to breadcrumb levels:

  • console.debug → debug
  • console.info, console.log → info
  • console.warn → warning
  • console.error → error

tags

Default tags added to all events.

tags: {
  service: 'api',
  version: process.env.VERSION,
}

Can be overridden per-event with setTag() or setTags().

beforeSend

Callback to modify or drop events before sending.

beforeSend: (event) => {
  // Drop events from test users
  if (event.user?.email?.endsWith('@test.com')) {
    return null;
  }
 
  // Remove sensitive data
  if (event.extra?.creditCard) {
    event.extra.creditCard = '[REDACTED]';
  }
 
  return event;
}

Return null to drop the event entirely.

Runtime Configuration

Some settings can be changed after initialization:

import { setTag, setTags, setUser } from '@statly/observe';
 
// Add tags dynamically
setTag('feature_flag', 'new_checkout');
setTags({ region: 'us-east', datacenter: 'dc1' });
 
// Set user context
setUser({
  id: 'user_123',
  email: '[email protected]',
  plan: 'pro',
});

Environment Variables

Common pattern for configuration:

init({
  dsn: process.env.STATLY_DSN,
  environment: process.env.NODE_ENV,
  release: process.env.GIT_SHA,
  debug: process.env.DEBUG === 'true',
});
InstallationAPI Reference