Configuration Options - Sentry JavaScript SDK

Configuration options control the behavior of the Sentry SDK.

Basic Options

dsn

string

The Data Source Name tells the SDK where to send events. Required for sending data to Sentry.

Sentry.init({
  dsn: 'https://[email protected]/0'
});

environment

string

default:"production"

The environment your application is running in.

Sentry.init({
  dsn: 'your-dsn',
  environment: process.env.NODE_ENV // 'production', 'staging', 'development'
});

release

string

The release version of your application. Used to track regressions and associate source maps.

Sentry.init({
  dsn: 'your-dsn',
  release: '[email protected]'
});

dist

string

The distribution identifier. Used to disambiguate build or deployment variants.

Sentry.init({
  dsn: 'your-dsn',
  release: '[email protected]',
  dist: '123'
});

Sampling Options

sampleRate

number

default:"1.0"

Sample rate for error events. Value between 0.0 (0%) and 1.0 (100%).

Sentry.init({
  dsn: 'your-dsn',
  sampleRate: 0.5 // Sample 50% of error events
});

tracesSampleRate

number

Sample rate for transaction events. Value between 0.0 (0%) and 1.0 (100%).

Sentry.init({
  dsn: 'your-dsn',
  tracesSampleRate: 0.1 // Sample 10% of transactions
});

tracesSampler

function

Dynamic sampling function for fine-grained control over trace sampling.

Sentry.init({
  dsn: 'your-dsn',
  tracesSampler: (samplingContext) => {
    // Sample 100% of checkout transactions
    if (samplingContext.name?.includes('checkout')) {
      return 1.0;
    }
    
    // Sample 10% of other transactions
    return 0.1;
  }
});

Event Processing

beforeSend

function

Called before sending error events. Can modify or drop events.

Sentry.init({
  dsn: 'your-dsn',
  beforeSend(event, hint) {
    // Filter out errors from browser extensions
    if (event.exception?.values?.[0]?.stacktrace?.frames?.some(
      frame => frame.filename?.includes('extension://')
    )) {
      return null; // Drop event
    }
    
    // Scrub sensitive data
    if (event.request?.data) {
      delete event.request.data.password;
    }
    
    return event;
  }
});

beforeSendTransaction

function

Called before sending transaction events.

Sentry.init({
  dsn: 'your-dsn',
  beforeSendTransaction(event, hint) {
    // Don't send transactions for health checks
    if (event.transaction === 'GET /health') {
      return null;
    }
    return event;
  }
});

beforeBreadcrumb

Called before adding a breadcrumb. Can modify or drop breadcrumbs.

Sentry.init({
  dsn: 'your-dsn',
  beforeBreadcrumb(breadcrumb, hint) {
    // Filter out console breadcrumbs
    if (breadcrumb.category === 'console') {
      return null;
    }
    
    // Scrub URLs
    if (breadcrumb.data?.url) {
      breadcrumb.data.url = breadcrumb.data.url.replace(
        /token=[^&]+/,
        'token=REDACTED'
      );
    }
    
    return breadcrumb;
  }
});

Integrations

integrations

Integration[]

required

List of integrations to enable. See Integrations for details.

import * as Sentry from '@sentry/node';
import { httpIntegration, captureConsoleIntegration } from '@sentry/node';

Sentry.init({
  dsn: 'your-dsn',
  integrations: [
    httpIntegration(),
    captureConsoleIntegration({ levels: ['error'] })
  ]
});

Data Limits

maxBreadcrumbs

number

default:"100"

Maximum number of breadcrumbs to keep.

Sentry.init({
  dsn: 'your-dsn',
  maxBreadcrumbs: 50
});

maxValueLength

number

default:"250"

Maximum string length before truncation.

Sentry.init({
  dsn: 'your-dsn',
  maxValueLength: 1000
});

normalizeDepth

number

default:"3"

Maximum depth to traverse in objects.

Sentry.init({
  dsn: 'your-dsn',
  normalizeDepth: 5
});

normalizeMaxBreadth

number

default:"1000"

Maximum properties/elements in arrays or objects.

Sentry.init({
  dsn: 'your-dsn',
  normalizeMaxBreadth: 100
});

Filtering

ignoreErrors

Array<string | RegExp>

default:"[]"

Errors matching these patterns won’t be sent.

Sentry.init({
  dsn: 'your-dsn',
  ignoreErrors: [
    'Non-Error promise rejection',
    /^NetworkError/,
    'ResizeObserver loop limit exceeded'
  ]
});

ignoreTransactions

Array<string | RegExp>

default:"[]"

Transactions matching these patterns won’t be sent.

Sentry.init({
  dsn: 'your-dsn',
  ignoreTransactions: [
    'GET /health',
    /^\/api\/internal/
  ]
});

allowUrls

Array<string | RegExp>

default:"[]"

Only send errors from URLs matching these patterns.

Sentry.init({
  dsn: 'your-dsn',
  allowUrls: [
    /^https:\/\/myapp\.com/,
    'cdn.myapp.com'
  ]
});

denyUrls

Array<string | RegExp>

default:"[]"

Don’t send errors from URLs matching these patterns.

Sentry.init({
  dsn: 'your-dsn',
  denyUrls: [
    /extensions\//i,
    'chrome-extension://'
  ]
});

Tracing

tracePropagationTargets

TracePropagationTargets

Control which outgoing requests get tracing headers. See Propagation for details.

Sentry.init({
  dsn: 'your-dsn',
  tracePropagationTargets: [
    'localhost',
    /^https:\/\/api\.myapp\.com/
  ]
});

propagateTraceparent

boolean

default:"false"

Enable W3C traceparent header propagation.

Sentry.init({
  dsn: 'your-dsn',
  propagateTraceparent: true
});

Transport

transport

function

required

Transport factory function. Usually provided by the SDK.

import { makeNodeTransport } from '@sentry/node';

Sentry.init({
  dsn: 'your-dsn',
  transport: makeNodeTransport
});

transportOptions

TransportOptions

Options for the transport. See Transport Options for details.

Sentry.init({
  dsn: 'your-dsn',
  transportOptions: {
    bufferSize: 30,
    headers: {
      'X-Custom-Header': 'value'
    }
  }
});

tunnel

string

Proxy endpoint for forwarding events.

Sentry.init({
  dsn: 'your-dsn',
  tunnel: '/api/tunnel'
});

Debug Options

debug

boolean

default:"false"

Enable debug logging.

Sentry.init({
  dsn: 'your-dsn',
  debug: true
});

enabled

boolean

default:"true"

Enable or disable the SDK.

Sentry.init({
  dsn: 'your-dsn',
  enabled: process.env.NODE_ENV === 'production'
});

Privacy

sendDefaultPii

boolean

default:"false"

Send personally identifiable information by default.

Sentry.init({
  dsn: 'your-dsn',
  sendDefaultPii: false
});

Server Options

serverName

string

Server or device name.

Sentry.init({
  dsn: 'your-dsn',
  serverName: 'web-server-01'
});

shutdownTimeout

number

default:"2000"

Milliseconds to wait before shutdown.

Sentry.init({
  dsn: 'your-dsn',
  shutdownTimeout: 5000
});

Complete Example

import * as Sentry from '@sentry/node';
import { httpIntegration, captureConsoleIntegration } from '@sentry/node';

Sentry.init({
  // Basic
  dsn: 'your-dsn',
  environment: process.env.NODE_ENV,
  release: '[email protected]',
  
  // Sampling
  sampleRate: 1.0,
  tracesSampleRate: 0.1,
  
  // Event Processing
  beforeSend(event) {
    if (event.request?.data) {
      delete event.request.data.password;
    }
    return event;
  },
  
  // Integrations
  integrations: [
    httpIntegration(),
    captureConsoleIntegration({ levels: ['error'] })
  ],
  
  // Data Limits
  maxBreadcrumbs: 100,
  maxValueLength: 250,
  
  // Filtering
  ignoreErrors: ['ResizeObserver loop limit exceeded'],
  
  // Tracing
  tracePropagationTargets: ['localhost', /^https:\/\/api\./],
  
  // Debug
  debug: false,
  enabled: true
});

Core SDK

Capture Methods

Tracing API

Configuration

Types

​Basic Options

​dsn

​environment

​release

​dist

​Sampling Options

​sampleRate

​tracesSampleRate

​tracesSampler

​Event Processing

​beforeSend

​beforeSendTransaction

​beforeBreadcrumb

​Integrations

​integrations

​Data Limits

​maxBreadcrumbs

​maxValueLength

​normalizeDepth

​normalizeMaxBreadth

​Filtering

​ignoreErrors

​ignoreTransactions

​allowUrls

​denyUrls

​Tracing

​tracePropagationTargets

​propagateTraceparent

​Transport

​transport

​transportOptions

​tunnel

​Debug Options

​debug

​enabled

​Privacy

​sendDefaultPii

​Server Options

​serverName

​shutdownTimeout

​Complete Example

​Related

Build docs developers (and LLMs) love

Basic Options

dsn

environment

release

dist

Sampling Options

sampleRate

tracesSampleRate

tracesSampler

Event Processing

beforeSend

beforeSendTransaction

beforeBreadcrumb

Integrations

integrations

Data Limits

maxBreadcrumbs

maxValueLength

normalizeDepth

normalizeMaxBreadth

Filtering

ignoreErrors

ignoreTransactions

allowUrls

denyUrls

Tracing

tracePropagationTargets

propagateTraceparent

Transport

transport

transportOptions

tunnel

Debug Options

debug

enabled

Privacy

sendDefaultPii

Server Options

serverName

shutdownTimeout

Complete Example

Related