0
# Configuration
1

2
Comprehensive configuration system for customizing Rollbar behavior, data collection, filtering, and integration settings across different environments.
3

4
## Capabilities
5

6
### Configure Method
7

8
Update configuration options for an existing Rollbar instance.
9

10
```typescript { .api }
11
/**
12
 * Update configuration options
13
 * @param options - Configuration options to update
14
 * @returns Updated Rollbar instance for chaining
15
 */
16
function configure(options: Configuration): Rollbar;
17
```
18

19
**Usage Example:**
20

21
```javascript
22
rollbar.configure({
23
  environment: 'staging',
24
  reportLevel: 'warning',
25
  captureUncaught: false
26
});
27
```
28

29
### Global Configuration
30

31
Configure global rate limiting and settings that affect all Rollbar instances.
32

33
```typescript { .api }
34
/**
35
 * Configure global settings and rate limiting
36
 * @param options - Global configuration options
37
 * @returns Rollbar instance for chaining
38
 */
39
function global(options: Configuration): Rollbar;
40
```
41

42
### Static Init Method
43

44
Initialize and return a global Rollbar instance with configuration.
45

46
```typescript { .api }
47
/**
48
 * Initialize global Rollbar instance
49
 * @param options - Initial configuration options
50
 * @returns Configured Rollbar instance
51
 */
52
static function init(options: Configuration): Rollbar;
53
```
54

55
**Usage Example:**
56

57
```javascript
58
const rollbar = Rollbar.init({
59
  accessToken: 'YOUR_ACCESS_TOKEN',
60
  environment: 'production',
61
  captureUncaught: true
62
});
63
```
64

65
## Configuration Interface
66

67
```typescript { .api }
68
interface Configuration {
69
  // Core Settings
70
  accessToken?: string;
71
  environment?: string;
72
  endpoint?: string;
73
  enabled?: boolean;
74
  transmit?: boolean;
75
  
76
  // Error Handling
77
  captureUncaught?: boolean;
78
  captureUnhandledRejections?: boolean;
79
  ignoreDuplicateErrors?: boolean;
80
  exitOnUncaughtException?: boolean;
81
  
82
  // Logging Levels
83
  logLevel?: Level;
84
  reportLevel?: Level;
85
  uncaughtErrorLevel?: Level;
86
  
87
  // Rate Limiting
88
  maxItems?: number;
89
  itemsPerMinute?: number;
90
  maxRetries?: number;
91
  retryInterval?: number | null;
92
  timeout?: number;
93
  
94
  // Data Collection
95
  captureIp?: boolean | 'anonymize';
96
  captureEmail?: boolean;
97
  captureUsername?: boolean;
98
  captureDeviceInfo?: boolean;
99
  addErrorContext?: boolean;
100
  
101
  // Filtering and Scrubbing
102
  scrubFields?: string[];
103
  scrubHeaders?: string[];
104
  scrubPaths?: string[];
105
  scrubRequestBody?: boolean;
106
  scrubTelemetryInputs?: boolean;
107
  overwriteScrubFields?: boolean;
108
  
109
  // Message Filtering
110
  ignoredMessages?: (string | RegExp)[];
111
  checkIgnore?: (isUncaught: boolean, args: LogArgument[], item: Dictionary) => boolean;
112
  
113
  // Host Filtering
114
  hostSafeList?: string[];
115
  hostBlockList?: string[];
116
  
117
  // Telemetry
118
  maxTelemetryEvents?: number;
119
  filterTelemetry?: (event: TelemetryEvent) => boolean;
120
  includeItemsInTelemetry?: boolean;
121
  telemetryScrubber?: TelemetryScrubber;
122
  
123
  // Code Version
124
  codeVersion?: string;
125
  code_version?: string;
126
  version?: string;
127
  
128
  // Transform and Hooks
129
  transform?: (data: Dictionary, item: Dictionary) => void | Promise<void>;
130
  onSendCallback?: (isUncaught: boolean, args: LogArgument[], item: Dictionary) => void;
131
  
132
  // Server-specific Options
133
  host?: string;
134
  locals?: LocalsOptions;
135
  captureLambdaTimeouts?: boolean;
136
  nodeSourceMaps?: boolean;
137
  addRequestData?: (data: Dictionary, req: Dictionary) => void;
138
  
139
  // Browser-specific Options
140
  wrapGlobalEventHandlers?: boolean;
141
  inspectAnonymousErrors?: boolean;
142
  stackTraceLimit?: number;
143
  
144
  // Auto-instrumentation
145
  autoInstrument?: boolean | AutoInstrumentSettings;
146
  
147
  // Payload Customization
148
  payload?: Payload;
149
  sendConfig?: boolean;
150
  verbose?: boolean;
151
  
152
  // File Path Rewriting
153
  rewriteFilenamePatterns?: string[];
154
}
155
```
156

157
## Core Configuration Options
158

159
### Access Token
160

161
```typescript { .api }
162
accessToken?: string;
163
```
164

165
Your Rollbar project access token. Required for sending data to Rollbar.
166

167
**Example:**
168
```javascript
169
{
170
  accessToken: 'YOUR_POST_SERVER_ITEM_ACCESS_TOKEN'
171
}
172
```
173

174
### Environment
175

176
```typescript { .api }
177
environment?: string;
178
```
179

180
The environment your code is running in (e.g., 'production', 'staging', 'development').
181

182
### Enabled
183

184
```typescript { .api }
185
enabled?: boolean;
186
```
187

188
Whether Rollbar is enabled. When false, no data is collected or sent.
189

190
## Auto-Instrumentation Settings
191

192
```typescript { .api }
193
interface AutoInstrumentSettings {
194
  network?: boolean;
195
  networkResponseHeaders?: boolean | string[];
196
  networkResponseBody?: boolean;
197
  networkRequestBody?: boolean;
198
  log?: boolean;
199
  dom?: boolean;
200
  navigation?: boolean;
201
  connectivity?: boolean;
202
  contentSecurityPolicy?: boolean;
203
  errorOnContentSecurityPolicy?: boolean;
204
}
205
```
206

207
**Usage Example:**
208

209
```javascript
210
{
211
  autoInstrument: {
212
    network: true,
213
    networkResponseHeaders: ['content-type', 'x-request-id'],
214
    log: true,
215
    dom: true,
216
    navigation: true
217
  }
218
}
219
```
220

221
## Payload Configuration
222

223
```typescript { .api }
224
interface Payload {
225
  person?: {
226
    id: string | number | null;
227
    username?: string;
228
    email?: string;
229
    [property: string]: any;
230
  };
231
  context?: any;
232
  client?: {
233
    javascript?: {
234
      code_version?: string | number;
235
      source_map_enabled?: boolean;
236
      guess_uncaught_frames?: boolean;
237
      [property: string]: any;
238
    };
239
    [property: string]: any;
240
  };
241
  environment?: string;
242
  server?: {
243
    branch?: string;
244
    host?: string;
245
    root?: string;
246
    [property: string]: any;
247
  };
248
  [property: string]: any;
249
}
250
```
251

252
## Local Variable Capture Options
253

254
```typescript { .api }
255
interface LocalsSettings {
256
  module: LocalsType;
257
  enabled?: boolean;
258
  uncaughtOnly?: boolean;
259
  depth?: number;
260
  maxProperties?: number;
261
  maxArray?: number;
262
}
263

264
type LocalsOptions = LocalsType | LocalsSettings;
265
```
266

267
## Telemetry Scrubber
268

269
```typescript { .api }
270
type TelemetryScrubber = (description: TelemetryScrubberInput) => boolean;
271

272
type TelemetryScrubberInput = DomDescription | null;
273

274
interface DomDescription {
275
  tagName: string;
276
  id: string | undefined;
277
  classes: string[] | undefined;
278
  attributes: DomAttribute[];
279
}
280

281
interface DomAttribute {
282
  key: DomAttributeKey;
283
  value: string;
284
}
285

286
type DomAttributeKey = 'type' | 'name' | 'title' | 'alt';
287
```
288

289
## Default Configuration Values
290

291
### Universal Defaults
292

293
```javascript
294
{
295
  endpoint: 'api.rollbar.com/api/1/item/',
296
  logLevel: 'debug',
297
  reportLevel: 'debug',
298
  uncaughtErrorLevel: 'error',
299
  maxItems: 0, // unlimited
300
  itemsPerMinute: 60,
301
  enabled: true,
302
  transmit: true,
303
  captureUncaught: true,
304
  captureUnhandledRejections: true,
305
  ignoreDuplicateErrors: true
306
}
307
```
308

309
### Default Scrub Fields
310

311
```javascript
312
{
313
  scrubFields: [
314
    'pw', 'pass', 'passwd', 'password', 'password_confirmation',
315
    'passwordConfirmation', 'confirm_password', 'confirmPassword',
316
    'secret', 'secret_token', 'secretToken', 'secret_key', 'secretKey',
317
    'api_key', 'access_token', 'accessToken', 'authenticity_token',
318
    'oauth_token', 'token', 'user_session_secret'
319
  ]
320
}
321
```
322

323
### Default Scrub Headers (Server-side)
324

325
```javascript
326
{
327
  scrubHeaders: [
328
    'authorization', 'www-authorization', 'http_authorization',
329
    'omniauth.auth', 'cookie', 'oauth-access-token', 'x-access-token',
330
    'x_csrf_token', 'http_x_csrf_token', 'x-csrf-token'
331
  ]
332
}
333
```
334

335
## Configuration Examples
336

337
### Server Configuration
338

339
```javascript
340
const rollbar = new Rollbar({
341
  accessToken: 'YOUR_SERVER_ACCESS_TOKEN',
342
  environment: 'production',
343
  captureUncaught: true,
344
  captureUnhandledRejections: true,
345
  reportLevel: 'warning',
346
  locals: {
347
    enabled: true,
348
    depth: 3
349
  },
350
  payload: {
351
    server: {
352
      host: 'web-server-01',
353
      branch: 'main'
354
    }
355
  }
356
});
357
```
358

359
### Browser Configuration
360

361
```javascript
362
const rollbar = new Rollbar({
363
  accessToken: 'YOUR_CLIENT_ACCESS_TOKEN',
364
  environment: 'production',
365
  captureUncaught: true,
366
  captureUnhandledRejections: true,
367
  autoInstrument: {
368
    network: true,
369
    dom: true,
370
    navigation: true
371
  },
372
  payload: {
373
    client: {
374
      javascript: {
375
        source_map_enabled: true,
376
        code_version: '1.2.3'
377
      }
378
    },
379
    person: {
380
      id: '12345',
381
      username: 'alice',
382
      email: 'alice@example.com'
383
    }
384
  }
385
});
386
```