rollbar 2.26.4 → 3.0.0-alpha.1

package/.cursor/rules/guidelines.mdc

@@ -0,0 +1,154 @@
+---
+description: Rollbar JS SDK Guidelines
+globs:
+alwaysApply: true
+---
+
+## 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
+
+## 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
+
+### Integration with Session Replay
+
+The Session Replay feature utilizes this tracing infrastructure to:
+
+- Track and record user sessions with unique identifiers
+- Associate spans with specific user sessions for complete context
+- Capture timing information for accurate playback
+- Store interaction events as span attributes and events

package/.github/workflows/ci.yml

@@ -9,19 +9,17 @@ on:
 
 jobs:
   build:
-    runs-on: ubuntu-20.04
+    runs-on: ubuntu-22.04
 
     strategy:
       matrix:
         include:
-          - node: 14
-            npm: ^8
-          - node: 16
-            npm: ^8
           - node: 18
             npm: ^9
           - node: 20
             npm: ^10
+          - node: 22
+            npm: ^10
           - node: latest
             npm: latest
 
@@ -50,4 +48,4 @@ jobs:
           eslint_extensions: js
 
       - name: Run tests
-        run: npm run test_ci
+        run: npm run test-ci

package/CLAUDE.md

@@ -0,0 +1,201 @@
+## 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

package/Gruntfile.js

@@ -112,7 +112,6 @@ module.exports = function (grunt) {
   grunt.loadNpmTasks('grunt-karma');
   grunt.loadNpmTasks('grunt-webpack');
   grunt.loadNpmTasks('grunt-text-replace');
-  grunt.loadNpmTasks('grunt-vows');
 
   var rollbarJsSnippet = fs.readFileSync('dist/rollbar.snippet.js');
   var rollbarjQuerySnippet = fs.readFileSync('dist/plugins/jquery.min.js');
@@ -120,14 +119,6 @@ module.exports = function (grunt) {
   grunt.initConfig({
     pkg: pkg,
     webpack: webpackConfig,
-    vows: {
-      all: {
-        options: {
-          reporter: 'spec',
-        },
-        src: ['test/server.*.test.js'],
-      },
-    },
 
     karma: buildGruntKarmaConfig(singleRun, browserTests, reporters),
 
@@ -145,7 +136,6 @@ module.exports = function (grunt) {
           // Main rollbar snippet
           {
             from: new RegExp(
-              /* eslint-disable-next-line no-control-regex */
               '^(.*// Rollbar Snippet)[\n\r]+(.*[\n\r])*(.*// End Rollbar Snippet)',
               'm',
             ),
@@ -157,7 +147,6 @@ module.exports = function (grunt) {
           // jQuery rollbar plugin snippet
           {
             from: new RegExp(
-              /* eslint-disable-next-line no-control-regex */
               '^(.*// Rollbar jQuery Snippet)[\n\r]+(.*[\n\r])*(.*// End Rollbar jQuery Snippet)',
               'm',
             ),
@@ -183,13 +172,11 @@ module.exports = function (grunt) {
 
   grunt.registerTask('build', ['webpack', 'replace:snippets']);
   grunt.registerTask('default', ['build']);
-  grunt.registerTask('test', ['test-server', 'test-browser']);
+  grunt.registerTask('test', [
+    'test-browser',
+  ]);
   grunt.registerTask('release', ['build', 'copyrelease']);
 
-  grunt.registerTask('test-server', function (_target) {
-    var tasks = ['vows'];
-    grunt.task.run.apply(grunt.task, tasks);
-  });
 
   grunt.registerTask('test-browser', function (target) {
     var karmaTask = 'karma' + (target ? ':' + target : '');
@@ -197,6 +184,62 @@ module.exports = function (grunt) {
     grunt.task.run.apply(grunt.task, tasks);
   });
 
+  function findReplayTests() {
+    return Object.keys(browserTests).filter(function (testName) {
+      var testPath = browserTests[testName];
+      return (
+        testPath.includes('test/replay/') ||
+        testPath.includes('test/tracing/') ||
+        testPath.match(/test\/browser\.replay\..*\.test\.js/)
+      );
+    });
+  }
+
+  grunt.registerTask('test-replay', function () {
+    var replayTests = findReplayTests();
+
+    grunt.log.writeln('Running all replay-related tests:');
+    replayTests.forEach(function (testName) {
+      grunt.log.writeln('- ' + testName + ' (' + browserTests[testName] + ')');
+    });
+
+    replayTests.forEach(function (testName) {
+      grunt.task.run('karma:' + testName);
+    });
+  });
+
+  grunt.registerTask('test-replay-unit', function () {
+    var unitTests = findReplayTests().filter(function (testName) {
+      var testPath = browserTests[testName];
+      return testPath.includes('/replay/unit/');
+    });
+
+    grunt.log.writeln('Running replay unit tests:');
+    unitTests.forEach(function (testName) {
+      grunt.log.writeln('- ' + testName + ' (' + browserTests[testName] + ')');
+    });
+
+    unitTests.forEach(function (testName) {
+      grunt.task.run('karma:' + testName);
+    });
+  });
+
+  grunt.registerTask('test-replay-integration', function () {
+    var integrationTests = findReplayTests().filter(function (testName) {
+      var testPath = browserTests[testName];
+      return testPath.includes('/replay/integration/');
+    });
+
+    grunt.log.writeln('Running replay integration tests:');
+    integrationTests.forEach(function (testName) {
+      grunt.log.writeln('- ' + testName + ' (' + browserTests[testName] + ')');
+    });
+
+    integrationTests.forEach(function (testName) {
+      grunt.task.run('karma:' + testName);
+    });
+  });
+
   grunt.registerTask('copyrelease', function createRelease() {
     var version = pkg.version;
     var builds = ['', '.umd'];

package/Makefile

@@ -17,8 +17,8 @@ test-server:
 	@npm run test-server
 	@echo ""
 
-test_ci:
-	@npm run test_ci
+test-ci:
+	@npm run test-ci
 	@echo ""
 
-.PHONY: test test_ci
+.PHONY: test test-ci

package/SECURITY.md

@@ -0,0 +1,5 @@
+# Security Policy
+
+## Reporting a Vulnerability
+
+Please report security issues to `security@rollbar.com`

package/babel.config.json

@@ -0,0 +1,9 @@
+{
+  "parserOpts": {
+    "ecmaVersion": 2021,
+    "sourceType": "module",
+  },
+  "presets": [
+    "@babel/preset-env"
+  ]
+}

package/codex.md

@@ -0,0 +1,148 @@
+## 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
+
+## 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
+
+### Integration with Session Replay
+
+The Session Replay feature utilizes this tracing infrastructure to:
+
+- Track and record user sessions with unique identifiers
+- Associate spans with specific user sessions for complete context
+- Capture timing information for accurate playback
+- Store interaction events as span attributes and events