CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/npm-sentry--integrations

Pluggable integrations that enhance Sentry JavaScript SDKs with additional error tracking, monitoring, and debugging capabilities.

—

Pending
Overview
Eval results
Files

frame-rewriting.mddocs/

Frame Rewriting

Transforms stack frame filenames using configurable rules. This integration is useful for normalizing file paths in different deployment environments, removing sensitive paths, or creating consistent frame references.

Capabilities

Modern Function-based Integration

/**
 * Rewrites event frame paths using configurable transformation rules
 * @param options - Frame rewriting configuration
 * @returns Integration instance that processes stack frames
 */
function rewriteFramesIntegration(options?: RewriteFramesOptions): Integration;

interface RewriteFramesOptions {
  /** Root path to strip from filenames */
  root?: string;
  /** Prefix to add to rewritten filenames. Default: 'app:///' */
  prefix?: string;
  /** Custom frame processing function */
  iteratee?: StackFrameIteratee;
}

type StackFrameIteratee = (frame: StackFrame) => StackFrame;

Legacy Class-based Integration (Deprecated)

/**
 * Legacy class-based frame rewriting integration
 * @deprecated Use rewriteFramesIntegration() instead
 */
class RewriteFrames implements Integration {
  constructor(options?: { 
    root?: string; 
    prefix?: string; 
    iteratee?: StackFrameIteratee 
  });
  name: string;
  processEvent(event: Event): Event;
}

Configuration Options

root Option

Base path to strip from filenames before applying prefix:

  • Purpose: Remove deployment-specific or sensitive path prefixes
  • Example: /var/www/app → strips this from /var/www/app/src/utils.js
  • Cross-platform: Handles both Unix and Windows paths

prefix Option

String to prepend to processed filenames:

  • Default: 'app:///'
  • Purpose: Create consistent, recognizable frame references
  • Example: utils.js → app:///utils.js

iteratee Option

Custom frame transformation function:

  • Signature: (frame: StackFrame) => StackFrame
  • Purpose: Complete control over frame processing
  • Overrides: When provided, replaces default transformation logic

Default Behavior

Without custom iteratee, the integration applies these transformations:

Path Detection

Automatically detects Windows vs Unix paths:

  • Windows: Paths starting with drive letters (C:\) or containing backslashes
  • Unix: Paths starting with forward slash (/)

Windows Path Processing

For Windows-style paths:

  1. Remove drive letter prefix (e.g., C:)
  2. Convert backslashes to forward slashes
  3. Apply root stripping and prefix

Unix Path Processing

For Unix-style paths:

  1. Apply root stripping (if configured)
  2. Use basename if no root specified
  3. Apply prefix

Usage Examples

import { rewriteFramesIntegration } from '@sentry/integrations';
import * as Sentry from '@sentry/browser';

// Basic prefix-only transformation
Sentry.init({
  dsn: 'YOUR_DSN',
  integrations: [
    rewriteFramesIntegration({
      prefix: 'myapp:///'
    })
  ]
});

// Strip deployment path and add prefix
Sentry.init({
  dsn: 'YOUR_DSN',
  integrations: [
    rewriteFramesIntegration({
      root: '/var/www/myapp',
      prefix: 'app:///'
    })
  ]
});

// Custom transformation logic
Sentry.init({
  dsn: 'YOUR_DSN',
  integrations: [
    rewriteFramesIntegration({
      iteratee: (frame) => {
        if (frame.filename) {
          // Custom logic: mask user-specific paths
          frame.filename = frame.filename.replace(
            /\/Users\/[^\/]+/,
            '/Users/***'
          );
          // Add custom prefix
          frame.filename = `custom:///${frame.filename}`;
        }
        return frame;
      }
    })
  ]
});

Path Transformation Examples

Default Behavior

// Input frames:
'/var/www/app/src/utils.js'       → 'app:///src/utils.js'
'C:\\app\\src\\utils.js'          → 'app:///src/utils.js'  
'/home/user/project/main.js'      → 'app:///main.js'

With Root Stripping

// Configuration: { root: '/var/www/app', prefix: 'myapp:///' }
'/var/www/app/src/utils.js'       → 'myapp:///src/utils.js'
'/var/www/app/lib/helper.js'      → 'myapp:///lib/helper.js'
'/different/path/file.js'         → 'myapp:///file.js'

Cross-platform Consistency

// Both produce same result:
'C:\\Users\\dev\\project\\src\\main.js'  → 'app:///src/main.js'
'/home/dev/project/src/main.js'          → 'app:///src/main.js'

Stack Frame Processing

The integration processes all stack frames in:

  • Exception events: All exception values and their stacktraces
  • Frame-by-frame: Each frame individually processed
  • Preserves metadata: Only filename is modified, other frame data unchanged

Common Use Cases

  1. Deployment Path Hiding: Remove server-specific paths from production stacktraces
  2. Cross-platform Consistency: Normalize Windows/Unix path differences
  3. Sensitive Path Masking: Hide user directories or internal system paths
  4. Logical Grouping: Add prefixes to identify different application components
  5. Development vs Production: Different prefixes for different environments

This integration is essential for production applications where stack frame paths need to be normalized or sanitized for security and consistency.

Install with Tessl CLI

npx tessl i tessl/npm-sentry--integrations

docs

console-capture.md

context-lines.md

debug-integration.md

error-deduplication.md

extra-error-data.md

frame-rewriting.md

http-client.md

index.md

offline-support.md

reporting-observer.md

session-timing.md

transaction-integration.md

tile.json