0
# Telemetry
1

2
Comprehensive telemetry capture system providing debugging context through user interactions, application events, network requests, and custom events.
3

4
## Capabilities
5

6
### Capture Event
7

8
Capture custom telemetry events with metadata and severity levels.
9

10
```typescript { .api }
11
/**
12
 * Capture a custom telemetry event
13
 * @param metadata - Event metadata and context
14
 * @param level - Severity level of the event
15
 * @returns Telemetry event object with UUID
16
 */
17
function captureEvent(metadata: object, level: Level): TelemetryEvent;
18
```
19

20
**Usage Examples:**
21

22
```javascript
23
// User interaction tracking
24
rollbar.captureEvent({
25
  type: 'user_action',
26
  action: 'button_click',
27
  button_id: 'checkout',
28
  user_id: '12345',
29
  cart_value: 99.99
30
}, 'info');
31

32
// Application state changes
33
rollbar.captureEvent({
34
  type: 'state_change',
35
  from: 'loading',
36
  to: 'loaded',
37
  component: 'ProductList',
38
  items_count: 25
39
}, 'debug');
40

41
// Performance metrics
42
rollbar.captureEvent({
43
  type: 'performance',
44
  operation: 'api_call',
45
  endpoint: '/api/users',
46
  duration_ms: 234,
47
  status_code: 200
48
}, 'info');
49
```
50

51
### Capture Error
52

53
Capture errors as telemetry events for debugging context.
54

55
```typescript { .api }
56
/**
57
 * Capture an error as a telemetry event
58
 * @param err - Error object to capture
59
 * @param level - Severity level
60
 * @param rollbarUUID - Optional UUID to associate with Rollbar item
61
 * @param timestamp - Optional custom timestamp
62
 * @returns Telemetry event object
63
 */
64
function captureError(
65
  err: Error,
66
  level: Level,
67
  rollbarUUID?: string,
68
  timestamp?: number
69
): TelemetryEvent;
70
```
71

72
### Capture Log
73

74
Capture log messages as telemetry events.
75

76
```typescript { .api }
77
/**
78
 * Capture a log message as telemetry event
79
 * @param message - Log message
80
 * @param level - Severity level
81
 * @param rollbarUUID - Optional UUID to associate with Rollbar item
82
 * @param timestamp - Optional custom timestamp
83
 * @returns Telemetry event object
84
 */
85
function captureLog(
86
  message: string,
87
  level: Level,
88
  rollbarUUID?: string,
89
  timestamp?: number
90
): TelemetryEvent;
91
```
92

93
### DOM Content Loaded
94

95
Capture DOM content loaded events (browser only).
96

97
```typescript { .api }
98
/**
99
 * Capture DOM content loaded event
100
 * @param timestamp - Optional custom timestamp
101
 * @returns Telemetry event object
102
 */
103
function captureDomContentLoaded(timestamp?: number): TelemetryEvent;
104
```
105

106
### Page Load
107

108
Capture page load events (browser only).
109

110
```typescript { .api }
111
/**
112
 * Capture page load event
113
 * @param timestamp - Optional custom timestamp
114
 * @returns Telemetry event object
115
 */
116
function captureLoad(timestamp?: number): TelemetryEvent;
117
```
118

119
### Copy Events
120

121
Get a filtered copy of all telemetry events.
122

123
```typescript { .api }
124
/**
125
 * Get a copy of all telemetry events, filtered by configuration
126
 * @returns Array of telemetry events
127
 */
128
function copyEvents(): TelemetryEvent[];
129
```
130

131
## Telemetry Event Interface
132

133
```typescript { .api }
134
interface TelemetryEvent {
135
  level: Level;
136
  type: string;
137
  timestamp_ms: number;
138
  body: object;
139
  source: string;
140
  uuid?: string;
141
}
142

143
type Level = 'debug' | 'info' | 'warning' | 'error' | 'critical';
144
```
145

146
## Auto-Instrumentation
147

148
Automatic telemetry capture for common browser events and interactions.
149

150
```typescript { .api }
151
interface AutoInstrumentSettings {
152
  network?: boolean;
153
  networkResponseHeaders?: boolean | string[];
154
  networkResponseBody?: boolean;
155
  networkRequestBody?: boolean;
156
  log?: boolean;
157
  dom?: boolean;
158
  navigation?: boolean;
159
  connectivity?: boolean;
160
  contentSecurityPolicy?: boolean;
161
  errorOnContentSecurityPolicy?: boolean;
162
}
163

164
type AutoInstrumentOptions = boolean | AutoInstrumentSettings;
165
```
166

167
### Network Instrumentation
168

169
Automatically capture network requests (fetch, XMLHttpRequest) and responses.
170

171
**Configuration:**
172

173
```javascript
174
const rollbar = new Rollbar({
175
  accessToken: 'YOUR_ACCESS_TOKEN',
176
  autoInstrument: {
177
    network: true,
178
    networkResponseHeaders: ['content-type', 'x-request-id', 'x-rate-limit'],
179
    networkResponseBody: true, // Capture response bodies
180
    networkRequestBody: false // Don't capture request bodies (may contain sensitive data)
181
  }
182
});
183
```
184

185
**Captured Data:**
186

187
- Request URL, method, headers
188
- Response status, headers, body (if enabled)
189
- Request duration
190
- Error details for failed requests
191

192
### DOM Instrumentation
193

194
Capture DOM events and user interactions.
195

196
**Configuration:**
197

198
```javascript
199
const rollbar = new Rollbar({
200
  accessToken: 'YOUR_ACCESS_TOKEN',
201
  autoInstrument: {
202
    dom: true // Capture clicks, form submissions, input changes
203
  }
204
});
205
```
206

207
**Captured Events:**
208

209
- Click events on buttons, links, and interactive elements
210
- Form submissions
211
- Input field changes
212
- Focus and blur events
213

214
### Navigation Instrumentation
215

216
Track page navigation and route changes.
217

218
**Configuration:**
219

220
```javascript
221
const rollbar = new Rollbar({
222
  accessToken: 'YOUR_ACCESS_TOKEN',
223
  autoInstrument: {
224
    navigation: true // Capture page loads, route changes, history events
225
  }
226
});
227
```
228

229
### Console Log Instrumentation
230

231
Capture console.log, console.error, and other console methods.
232

233
**Configuration:**
234

235
```javascript
236
const rollbar = new Rollbar({
237
  accessToken: 'YOUR_ACCESS_TOKEN',
238
  autoInstrument: {
239
    log: true // Capture all console output
240
  }
241
});
242
```
243

244
### Connectivity Instrumentation
245

246
Track online/offline status changes.
247

248
**Configuration:**
249

250
```javascript
251
const rollbar = new Rollbar({
252
  accessToken: 'YOUR_ACCESS_TOKEN',
253
  autoInstrument: {
254
    connectivity: true // Capture network connectivity changes
255
  }
256
});
257
```
258

259
## Telemetry Configuration
260

261
### Maximum Events
262

263
Control the maximum number of telemetry events stored.
264

265
```typescript { .api }
266
maxTelemetryEvents?: number;
267
```
268

269
**Default:** 100 events
270

271
### Event Filtering
272

273
Filter telemetry events before they are stored.
274

275
```typescript { .api }
276
filterTelemetry?: (event: TelemetryEvent) => boolean;
277
```
278

279
**Usage Example:**
280

281
```javascript
282
const rollbar = new Rollbar({
283
  accessToken: 'YOUR_ACCESS_TOKEN',
284
  filterTelemetry: (event) => {
285
    // Only keep error and warning level events
286
    return event.level === 'error' || event.level === 'warning';
287
  }
288
});
289
```
290

291
### Include Items in Telemetry
292

293
Include Rollbar items (errors, messages) in telemetry timeline.
294

295
```typescript { .api }
296
includeItemsInTelemetry?: boolean;
297
```
298

299
**Default:** true
300

301
### Telemetry Scrubbing
302

303
Control what data is captured in DOM telemetry events.
304

305
```typescript { .api }
306
type TelemetryScrubber = (description: TelemetryScrubberInput) => boolean;
307

308
type TelemetryScrubberInput = DomDescription | null;
309

310
interface DomDescription {
311
  tagName: string;
312
  id: string | undefined;
313
  classes: string[] | undefined;
314
  attributes: DomAttribute[];
315
}
316

317
interface DomAttribute {
318
  key: DomAttributeKey;
319
  value: string;
320
}
321

322
type DomAttributeKey = 'type' | 'name' | 'title' | 'alt';
323
```
324

325
**Usage Example:**
326

327
```javascript
328
const rollbar = new Rollbar({
329
  accessToken: 'YOUR_ACCESS_TOKEN',
330
  telemetryScrubber: (description) => {
331
    if (!description) return false;
332
    
333
    // Scrub password fields
334
    if (description.attributes.some(attr => 
335
      attr.key === 'type' && attr.value === 'password'
336
    )) {
337
      return true; // Don't capture this element
338
    }
339
    
340
    // Scrub elements with sensitive data attributes
341
    if (description.attributes.some(attr => 
342
      attr.key === 'data-sensitive'
343
    )) {
344
      return true;
345
    }
346
    
347
    return false; // Capture this element
348
  }
349
});
350
```
351

352
### Scrub Telemetry Inputs
353

354
Scrub sensitive input values from telemetry events.
355

356
```typescript { .api }
357
scrubTelemetryInputs?: boolean;
358
```
359

360
**Default:** false
361

362
## Telemetry Usage Examples
363

364
### E-commerce Application
365

366
```javascript
367
const rollbar = new Rollbar({
368
  accessToken: 'YOUR_ACCESS_TOKEN',
369
  autoInstrument: {
370
    network: true,
371
    dom: true,
372
    navigation: true
373
  },
374
  maxTelemetryEvents: 200
375
});
376

377
// Track shopping cart events
378
function addToCart(productId, quantity) {
379
  rollbar.captureEvent({
380
    type: 'ecommerce',
381
    action: 'add_to_cart',
382
    product_id: productId,
383
    quantity: quantity,
384
    cart_total: getCartTotal()
385
  }, 'info');
386
  
387
  // Your add to cart logic
388
}
389

390
// Track checkout process
391
function startCheckout() {
392
  rollbar.captureEvent({
393
    type: 'ecommerce',
394
    action: 'checkout_started',
395
    cart_value: getCartTotal(),
396
    item_count: getCartItemCount()
397
  }, 'info');
398
}
399

400
function completeCheckout(orderId) {
401
  rollbar.captureEvent({
402
    type: 'ecommerce',
403
    action: 'checkout_completed',
404
    order_id: orderId,
405
    order_value: getOrderTotal()
406
  }, 'info');
407
}
408
```
409

410
### Single Page Application
411

412
```javascript
413
const rollbar = new Rollbar({
414
  accessToken: 'YOUR_ACCESS_TOKEN',
415
  autoInstrument: {
416
    network: true,
417
    navigation: true,
418
    dom: true
419
  }
420
});
421

422
// Track route changes
423
function onRouteChange(from, to) {
424
  rollbar.captureEvent({
425
    type: 'navigation',
426
    action: 'route_change',
427
    from_route: from,
428
    to_route: to,
429
    user_id: getCurrentUserId()
430
  }, 'info');
431
}
432

433
// Track component lifecycle
434
function componentDidMount(componentName) {
435
  rollbar.captureEvent({
436
    type: 'component',
437
    action: 'mount',
438
    component: componentName,
439
    props: getComponentProps()
440
  }, 'debug');
441
}
442

443
// Track API calls with timing
444
async function apiCall(endpoint, method, data) {
445
  const startTime = Date.now();
446
  
447
  rollbar.captureEvent({
448
    type: 'api',
449
    action: 'request_start',
450
    endpoint: endpoint,
451
    method: method
452
  }, 'debug');
453
  
454
  try {
455
    const response = await fetch(endpoint, {
456
      method: method,
457
      body: JSON.stringify(data),
458
      headers: { 'Content-Type': 'application/json' }
459
    });
460
    
461
    const duration = Date.now() - startTime;
462
    
463
    rollbar.captureEvent({
464
      type: 'api',
465
      action: 'request_complete',
466
      endpoint: endpoint,
467
      method: method,
468
      status_code: response.status,
469
      duration_ms: duration
470
    }, response.ok ? 'info' : 'warning');
471
    
472
    return response;
473
  } catch (error) {
474
    const duration = Date.now() - startTime;
475
    
476
    rollbar.captureEvent({
477
      type: 'api', 
478
      action: 'request_error',
479
      endpoint: endpoint,
480
      method: method,
481
      error: error.message,
482
      duration_ms: duration
483
    }, 'error');
484
    
485
    throw error;
486
  }
487
}
488
```
489

490
### Form Interaction Tracking
491

492
```javascript
493
// Track form interactions for debugging form abandonment
494
function setupFormTelemetry(formId) {
495
  const form = document.getElementById(formId);
496
  
497
  form.addEventListener('focusin', (e) => {
498
    rollbar.captureEvent({
499
      type: 'form',
500
      action: 'field_focus',
501
      form_id: formId,
502
      field_name: e.target.name,
503
      field_type: e.target.type
504
    }, 'debug');
505
  });
506
  
507
  form.addEventListener('change', (e) => {
508
    rollbar.captureEvent({
509
      type: 'form',
510
      action: 'field_change',
511
      form_id: formId,
512
      field_name: e.target.name,
513
      field_type: e.target.type,
514
      value_length: e.target.value ? e.target.value.length : 0
515
    }, 'debug');
516
  });
517
  
518
  form.addEventListener('submit', (e) => {
519
    const formData = new FormData(form);
520
    rollbar.captureEvent({
521
      type: 'form',
522
      action: 'submit',
523
      form_id: formId,
524
      field_count: formData.keys().length,
525
      completion_time: getFormCompletionTime()
526
    }, 'info');
527
  });
528
}
529
```
530

531
## Server-side Telemetry
532

533
```javascript
534
const Rollbar = require('rollbar');
535

536
const rollbar = new Rollbar({
537
  accessToken: 'YOUR_ACCESS_TOKEN',
538
  environment: 'production'
539
});
540

541
// Track business logic events
542
function processOrder(order) {
543
  rollbar.captureEvent({
544
    type: 'business',
545
    action: 'order_processing',
546
    order_id: order.id,
547
    customer_id: order.customerId,
548
    order_value: order.total
549
  }, 'info');
550
  
551
  try {
552
    validateOrder(order);
553
    
554
    rollbar.captureEvent({
555
      type: 'business',
556
      action: 'order_validated',
557
      order_id: order.id
558
    }, 'info');
559
    
560
    const result = processPayment(order);
561
    
562
    rollbar.captureEvent({
563
      type: 'business',
564
      action: 'payment_processed',
565
      order_id: order.id,
566
      payment_method: order.paymentMethod,
567
      amount: order.total
568
    }, 'info');
569
    
570
    return result;
571
  } catch (error) {
572
    rollbar.captureEvent({
573
      type: 'business',
574
      action: 'order_processing_failed',
575
      order_id: order.id,
576
      error: error.message,
577
      step: getCurrentProcessingStep()
578
    }, 'error');
579
    
580
    throw error;
581
  }
582
}
583
```