tessl/npm-sentry--utils

Deprecated utilities package for Sentry JavaScript SDKs - all functionality moved to @sentry/core

—

Pending

Overview

Eval results

Files

Instrumentation & Event Handling

Name: tessl/npm-sentry--utils
Author: tessl

DEPRECATED: Import all functions from @sentry/core instead of @sentry/utils.

Instrumentation handlers for automatically capturing console logs, network requests, errors, and other events in web and Node.js environments.

Capabilities

Console Instrumentation

Captures console method calls (log, warn, error, etc.) for breadcrumb generation.

interface ConsoleLevel {
  0: 'log';
  1: 'warn'; 
  2: 'error';
  3: 'info';
  4: 'debug';
  5: 'assert';
}

/**
 * Adds a handler for console instrumentation
 * @param handler - Callback function that receives console level and arguments
 */
function addConsoleInstrumentationHandler(
  handler: (level: ConsoleLevel[keyof ConsoleLevel], ...args: any[]) => void
): void;

Usage Example:

import { addConsoleInstrumentationHandler } from "@sentry/core";

addConsoleInstrumentationHandler((level, ...args) => {
  console.log(`Console ${level} called with:`, args);
  
  // Create breadcrumb from console call
  addBreadcrumb({
    message: args.join(' '),
    level: level as SeverityLevel,
    category: 'console',
  });
});

Fetch Instrumentation

Captures fetch API calls for network request monitoring.

interface FetchBreadcrumbData {
  method: string;
  url: string;
  status_code?: number;
  reason?: string;
  start_timestamp: number;
  end_timestamp?: number;
}

/**
 * Adds a handler for fetch request instrumentation
 * @param handler - Callback function that receives fetch data
 */
function addFetchInstrumentationHandler(
  handler: (data: FetchBreadcrumbData) => void
): void;

/**
 * Adds a handler for fetch request completion
 * @param handler - Callback function that receives completed fetch data  
 */
function addFetchEndInstrumentationHandler(
  handler: (data: FetchBreadcrumbData) => void
): void;

Usage Examples:

import { 
  addFetchInstrumentationHandler, 
  addFetchEndInstrumentationHandler 
} from "@sentry/core";

// Track fetch requests
addFetchInstrumentationHandler((data) => {
  console.log(`Fetch started: ${data.method} ${data.url}`);
});

// Track fetch completions
addFetchEndInstrumentationHandler((data) => {
  console.log(`Fetch completed: ${data.status_code} in ${data.end_timestamp! - data.start_timestamp}ms`);
  
  addBreadcrumb({
    category: 'fetch',
    data: {
      method: data.method,
      url: data.url,
      status_code: data.status_code,
    },
    level: data.status_code && data.status_code >= 400 ? 'error' : 'info',
  });
});

Error Instrumentation

Captures global error events and unhandled promise rejections.

interface ErrorEventData {
  msg: string;
  url: string;
  line: number;
  column: number;
  error: Error;
}

interface UnhandledRejectionEventData {
  reason: any;
  promise: Promise<any>;
}

/**
 * Adds a handler for global error events (window.onerror, process.on('uncaughtException'))
 * @param handler - Callback function that receives error event data
 */
function addGlobalErrorInstrumentationHandler(
  handler: (data: ErrorEventData) => void
): void;

/**
 * Adds a handler for unhandled promise rejections
 * @param handler - Callback function that receives rejection data
 */
function addGlobalUnhandledRejectionInstrumentationHandler(
  handler: (data: UnhandledRejectionEventData) => void  
): void;

Usage Examples:

import { 
  addGlobalErrorInstrumentationHandler, 
  addGlobalUnhandledRejectionInstrumentationHandler 
} from "@sentry/core";

// Capture global errors
addGlobalErrorInstrumentationHandler((data) => {
  console.error('Global error:', data.error);
  
  captureException(data.error, {
    contexts: {
      errorInfo: {
        url: data.url,
        line: data.line,
        column: data.column,
      },
    },
  });
});

// Capture unhandled promise rejections
addGlobalUnhandledRejectionInstrumentationHandler((data) => {
  console.error('Unhandled rejection:', data.reason);
  
  captureException(data.reason, {
    tags: {
      unhandledRejection: true,
    },
  });
});

Generic Handler Management

Low-level instrumentation handler management for custom instrumentation.

/**
 * Adds a generic instrumentation handler
 * @param type - Type of instrumentation (e.g., 'console', 'fetch', 'error')
 * @param handler - Handler function
 */
function addHandler(type: string, handler: (...args: any[]) => void): void;

/**
 * Triggers all handlers for a specific instrumentation type
 * @param type - Type of instrumentation to trigger
 * @param data - Data to pass to handlers
 */
function triggerHandlers(type: string, data: any): void;

/**
 * Resets all instrumentation handlers (useful for testing)
 */
function resetInstrumentationHandlers(): void;

Conditional Instrumentation

Utility for conditionally applying instrumentation based on environment or configuration.

/**
 * Conditionally instruments a function or object method
 * @param obj - Object containing the method to instrument
 * @param name - Name of the method to instrument
 * @param replacement - Replacement function
 * @param isActive - Function that determines if instrumentation should be active
 */
function maybeInstrument<T extends Record<string, any>>(
  obj: T,
  name: keyof T,
  replacement: T[keyof T],
  isActive?: () => boolean,
): void;

Usage Example:

import { maybeInstrument, isBrowser } from "@sentry/core";

// Only instrument fetch in browser environments
maybeInstrument(
  window,
  'fetch',
  function instrumentedFetch(this: Window, ...args) {
    console.log('Fetch called with:', args);
    return originalFetch.apply(this, args);
  },
  () => isBrowser()
);

Instrumentation Setup Pattern

A typical instrumentation setup combines multiple handlers:

import { 
  addConsoleInstrumentationHandler,
  addFetchInstrumentationHandler,
  addGlobalErrorInstrumentationHandler,
  addGlobalUnhandledRejectionInstrumentationHandler,
  isBrowser 
} from "@sentry/core";

function setupInstrumentation() {
  // Console logging
  addConsoleInstrumentationHandler((level, ...args) => {
    addBreadcrumb({
      message: args.join(' '),
      level: level as SeverityLevel,
      category: 'console',
    });
  });

  // Network requests (browser only)
  if (isBrowser()) {
    addFetchInstrumentationHandler((data) => {
      addBreadcrumb({
        category: 'fetch',
        data: {
          method: data.method,
          url: data.url,
        },
        level: 'info',
      });
    });
  }

  // Global errors
  addGlobalErrorInstrumentationHandler((data) => {
    captureException(data.error);
  });

  // Unhandled rejections
  addGlobalUnhandledRejectionInstrumentationHandler((data) => {
    captureException(data.reason);
  });
}

Handler Types

Available Instrumentation Types

console - Console method calls
fetch - Fetch API requests
xhr - XMLHttpRequest calls (if available)
error - Global error events
unhandledrejection - Promise rejections
history - History API changes (pushState, replaceState)
dom - DOM events and mutations

Handler Lifecycle

Registration: Handlers are registered using addXInstrumentationHandler functions
Activation: Handlers are automatically activated when the corresponding API is called
Execution: Handler callbacks receive structured data about the instrumented event
Reset: All handlers can be cleared using resetInstrumentationHandlers() (useful for testing)

Migration Note: All instrumentation functions have been moved from @sentry/utils to @sentry/core. Update your imports accordingly.

Install with Tessl CLI