rollbar/CLAUDE.md

Effortlessly track and debug errors in your JavaScript applications with Rollbar. This package includes advanced error tracking features and an intuitive interface to help you identify and fix issues more quickly.

## About Rollbar.js

Rollbar.js is the official JavaScript SDK for the Rollbar error monitoring service. This library is not standalone - it works in tandem with the Rollbar platform to help developers detect, diagnose, and fix errors in real-time. The SDK sends error data to Rollbar's cloud service where errors are processed, grouped, and notifications are triggered.

The library works across platforms, supporting both browser and server-side JavaScript including frameworks like React, Angular, Express, and Next.js. Key features include:

- Cross-platform error tracking for client and server-side code
- Telemetry to provide context around errors (breadcrumbs of events)
- Automatic error grouping to reduce noise
- Real-time notifications for critical issues
- Detailed stack traces with source maps support
- Distributed tracing and session management
- Session replay capabilities for reproducing user actions

## Project Structure

```
src/
├── browser/      # Browser-specific implementation
├── server/       # Node.js-specific implementation
├── react-native/ # React Native implementation
├── tracing/      # Distributed tracing support
└── utility/      # Shared utility functions
```

## Build & Test Commands

- Build: `npm run build` (runs Grunt)
- Lint: `npm run lint` (ESLint)
- Test all: `npm run test` (runs both server and browser tests)
- Test browser only: `npm run test-browser`
- Test server only: `npm run test-server`
- Test specific browser test: `grunt test-browser:specificTestName`
  - Example: `grunt test-browser:transforms`
- Single test: `./node_modules/.bin/karma start --single-run --files={path/to/test}`

## Modern Development Environment

As of version 3.0.0, the SDK has been updated to use modern JavaScript features with appropriate transpilation:

- **ES Modules**: The codebase supports ES modules (`import/export`) syntax
- **Target Compatibility**:
  - Source code uses ECMAScript 2021 features
  - Builds target ES5 for broad browser compatibility
  - Lower versions can use the ES5/CommonJS compatible bundles
- **Build System**:
  - Webpack 5 with Babel for transpilation
  - ESLint for code quality
  - Configurable output formats (UMD, AMD, vanilla)
- **Minimum Node.js**: Version 18+ for absolute imports
- **Toolchain Configuration**:
  - `babel.config.json`: Controls transpilation options
  - `eslint.config.mjs`: Modern ESLint flat config format
  - `webpack.config.js`: Manages bundling and output formats

## Code Style Guidelines

- Use single quotes for strings
- Use camelCase for variables (underscore prefix for private)
- Indentation: 2 spaces
- Include trailing commas in multiline objects/arrays
- Max function complexity: 35
- Unused parameters prefixed with underscore: `function(a, _unused) {}`
- No whitespace in empty lines
- Files should end with exactly one newline
- Control statements (if, for, while, etc.) MUST use braces and newlines, even for single statements
- Opening braces should be on the same line as the control statement
- ESLint is used for enforcing code style
- Prettier for code formatting

### Documentation vs. Comments

- **Function Documentation (JSDoc/TSDoc)**: Always include comprehensive documentation for functions, classes, and methods using JSDoc/TSDoc format (`/** ... */`). These serve as API documentation, appear in IDE tooltips, and help developers understand purpose, parameters, and return values.

- **Inline Code Comments**: Avoid redundant comments that merely restate what the code is doing. Only add comments to explain:
  - Why the code works a certain way (decisions and reasoning)
  - Non-obvious behavior or edge cases
  - Complex algorithms or business logic
  - Workarounds for bugs or limitations
  
- **Self-documenting Code**: Write clear, readable code that explains itself through descriptive variable/function names and straightforward logic. Well-written code rarely needs explanatory comments.

- **Examples**:
  ```javascript
  // BAD - Redundant comment
  // Add one to x
  x += 1;
  
  // GOOD - Explains the non-obvious "why"
  // Increment before sending to API to account for zero-indexing
  x += 1;
  ```

## SDK Design Principles

- **User Problems Are SDK Improvement Opportunities**: When users encounter integration issues, treat these as SDK design improvements rather than user implementation mistakes.
  - Focus on enhancing the SDK to be more robust, intuitive and resilient
  - Implement automatic environment detection and appropriate behavior selection
  - Design APIs that work correctly across all supported contexts without requiring special user handling
  - Errors should be informative and suggest correct usage patterns
  - The burden of complexity should rest with the SDK, not its users

## Error Handling

- Prefer try/catch blocks around risky operations
- Log errors through Rollbar's own logger system
- Scrub sensitive fields in error payloads (see package.json defaults)
- The codebase uses a comprehensive error tracking approach with appropriate levels:
  - Debug level for development info
  - Warning level for non-critical issues
  - Error level for uncaught exceptions

## TypeScript Support

- Type definitions in index.d.ts
- Add JSDoc types to enable intellisense when needed

## Common Patterns

When working with this codebase, be aware of these patterns:

- Error transformation and normalization before sending
- Telemetry collection for context
- Queue-based sending with retry logic
- Environment and context detection
- Scrubbing of sensitive data

## Testing Philosophy

- **Analyze Test Failures Objectively**: When tests fail, evaluate both possibilities objectively:

  - The test could be correctly identifying an actual code issue
  - The test itself might contain errors or invalid expectations

- **Diagnostic Process**:

  1. Examine what the test is expecting vs. what the code actually does
  2. Consider the intended behavior and design of the system
  3. If the test is correct and identifying a legitimate bug, fix the code
  4. If the test contains misconceptions or errors, fix the test

- **Default to Code Quality**: When in doubt and both seem potentially valid, prioritize improving code quality over modifying tests to pass

## Tracing & Session Replay

The `src/tracing/` directory contains an OpenTelemetry-inspired tracing implementation that powers both distributed tracing and session recording features:

### Components

- **Context & ContextManager**: Manages propagation of tracing context through the application
- **Span**: Represents a unit of work or operation with timing information and attributes
- **Tracer**: Creates and manages spans for tracking operations
- **SpanProcessor & SpanExporter**: Processes and exports spans to their destination
- **Session**: Manages browser session data persistence and creation

### Usage Patterns

- **Tracing initialization**: Initialize via the main Tracing class with appropriate configuration
- **Context propagation**: Use context to pass trace information between components
- **Span creation**: Create spans to measure operations with `startSpan()`
- **Attributes and events**: Add metadata to spans with `setAttribute()` and `addEvent()`
- **Session management**: Automatically manages user sessions via browser sessionStorage

### Session Replay Implementation

The `src/browser/replay` directory contains the implementation of the Session Replay feature:

- **Recorder**: Core class that integrates with rrweb to record DOM events
- **ReplayMap**: Manages the mapping between error occurrences and session recordings
- **Configuration**: Configurable options in `defaults.js` for replay behavior

The Session Replay feature utilizes our tracing infrastructure to:

- Record user interactions using rrweb in a memory-efficient way
- Store recordings with checkpoints for better performance
- Generate spans that contain replay events with proper timing
- Associate recordings with user sessions for complete context
- Transport recordings to Rollbar servers via the API

### Session Replay Flow

1. **Recording**: The Recorder class continuously records DOM events using rrweb
2. **Error Occurrence**: When an error occurs, Queue.addItem() calls ReplayMap.add()
3. **Correlation**: ReplayMap generates a replayId and attaches it to the error
4. **Coordination**: After successful error submission, Queue triggers ReplayMap.send()
5. **Transport**: ReplayMap retrieves stored replay data and sends via api.postSpans()

### Testing Infrastructure

- **Unit Tests**: Component-focused tests in `test/replay/unit/`
- **Integration Tests**: Test component interactions in `test/replay/integration/`
- **End-to-End Tests**: Full flow verification in `test/replay/integration/e2e.test.js`
- **Mock Implementation**: `test/replay/util/mockRecordFn.js` provides a deterministic mock of rrweb
- **Fixtures**: Realistic rrweb events in `test/fixtures/replay/` for testing
- **Test Tasks**: Custom Grunt tasks for testing replay code specifically

## File Creation Guidelines

- **Newlines**: All new files MUST end with exactly one newline character
- **Encoding**: Use UTF-8 encoding for all text files
- **Line Endings**: Use LF (Unix-style) line endings, not CRLF