rollbar 2.26.3 → 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

@@ -2,30 +2,50 @@ name: Rollbar.js CI
 
 on:
   push:
-    branches: [ master ]
-    tags: [ v* ]
+    branches: [master]
+    tags: [v*]
   pull_request:
-    branches: [ master ]
+    branches: [master]
 
 jobs:
   build:
-    runs-on: ubuntu-20.04
+    runs-on: ubuntu-22.04
+
     strategy:
       matrix:
-        node-version: [10, 12, 14, 16]
+        include:
+          - node: 18
+            npm: ^9
+          - node: 20
+            npm: ^10
+          - node: 22
+            npm: ^10
+          - node: latest
+            npm: latest
 
     steps:
-      - uses: actions/checkout@v2
-        with:
-          submodules: recursive
+      - name: Checkout
+        uses: actions/checkout@v4
 
-      - name: Install node.js
-        uses: actions/setup-node@v2-beta
+      - name: Set up node ${{ matrix.node }}
+        uses: actions/setup-node@v4
         with:
-          node-version: ${{ matrix.node-version }}
+          node-version: ${{ matrix.node }}
+
+      - name: Update npm
+        run: npm install -g npm@${{ matrix.npm }}
 
       - name: npm install
         run: npm install
 
+      - name: Lint
+        uses: wearerequired/lint-action@v2
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          prettier: true
+          eslint: true
+          eslint_args: '--max-warnings 0'
+          eslint_extensions: js
+
       - name: Run tests
-        run: npm run test_ci
+        run: npm run test-ci

package/.lgtm.yml

@@ -1,8 +1,8 @@
 path_classifiers:
-    generated:
-      - release
-      - dist
-    docs:
-      - examples
-    test:
-      - test
+  generated:
+    - release
+    - dist
+  docs:
+    - examples
+  test:
+    - test

package/.prettierignore

@@ -0,0 +1,18 @@
+.github
+.next
+.yalc
+build
+bundles
+coverage
+dist
+lib
+node_modules
+out
+public
+release
+vendor
+
+# ignore prettifying examples for now due to
+# 1. there being minified snippets all over the place and
+# 2. some tests fail cause they depend on some sources being exactly as they are
+examples

package/.vscode/settings.json

@@ -0,0 +1,39 @@
+{
+  "[github-actions-workflow]": {
+    "editor.defaultFormatter": "esbenp.prettier-vscode",
+    "editor.formatOnSave": true
+  },
+  "[javascript]": {
+    "editor.defaultFormatter": "esbenp.prettier-vscode",
+    "editor.formatOnSave": true
+  },
+  "[javascriptreact]": {
+    "editor.defaultFormatter": "esbenp.prettier-vscode",
+    "editor.formatOnSave": true
+  },
+  "[json5]": {
+    "editor.defaultFormatter": "esbenp.prettier-vscode",
+    "editor.formatOnSave": true
+  },
+  "[jsonc]": {
+    "editor.defaultFormatter": "esbenp.prettier-vscode",
+    "editor.formatOnSave": true
+  },
+  "[typescript]": {
+    "editor.defaultFormatter": "esbenp.prettier-vscode",
+    "editor.formatOnSave": true
+  },
+  "[typescriptreact]": {
+    "editor.defaultFormatter": "esbenp.prettier-vscode",
+    "editor.formatOnSave": true
+  },
+  "editor.defaultFormatter": "esbenp.prettier-vscode",
+  "editor.formatOnSave": true,
+  "editor.formatOnSaveMode": "file",
+  "editor.tabSize": 2,
+  "editor.codeActionsOnSave": {
+    "source.fixAll.eslint": "explicit"
+  },
+  "files.trimTrailingWhitespace": true,
+  "prettier.useEditorConfig": false
+}