Web-Tracing SDK Core Modules: Complete Architecture Guide

The web-tracing SDK provides 15+ specialized core modules for error tracking, performance monitoring, and user behavior analytics, all exposed through named exports from packages/core/index.ts and controlled via the init() and destroyTracing() lifecycle functions.

The m-cheng-web/web-tracing repository delivers a modular observability SDK designed for browser applications. Located in the packages/core directory, the web-tracing SDK core modules provide granular control over data collection, network interception, and event transmission without requiring framework-specific dependencies.

Core Module Architecture

The SDK follows a functional architecture where each module resides in packages/core/src/lib/ and handles a specific observability concern. The public API surface is defined in packages/core/index.ts, which aggregates these modules into named exports while also offering a default export bundle for quick initialization.

Modules are categorized into three functional groups:

• Data Collection: Capture errors, network requests, performance metrics, and user interactions
• Infrastructure: Manage SDK lifecycle, configuration, and data transmission
• Utilities: Provide reactive primitives and helper functions for advanced integrations

Data Collection Modules

These modules instrument the browser environment to capture telemetry data.

Error (err.ts): Captures uncaught exceptions and custom error reports via global event listeners. Located at packages/core/src/lib/err.ts, this module processes stack traces and batches error payloads for transmission.

HTTP (http.ts): Intercepts XMLHttpRequest and fetch calls to record network request timing, status codes, and response bodies. Works in conjunction with the Replace module to monkey-patch native APIs.

Performance (performance.ts): Gathers Navigation Timing API entries, Resource Timing data, and custom performance marks. This module automatically collects core web vitals and asset loading metrics.

Page-View (pv.ts): Handles single-page application route changes and traditional page load events. Tracks URL transitions and referrer data for complete navigation trails.

Event (event.ts): Records custom user-defined events with arbitrary payloads. Developers use this to track business-specific interactions like button clicks or form submissions.

IntersectionObserver (intersectionObserver.ts): Provides an "exposure" API that watches DOM elements entering the viewport. Essential for tracking ad impressions and content visibility without polling.

RecordScreen (recordscreen.ts): Captures screen recordings using the MediaRecorder API for error replay scenarios. Stores compressed video data alongside error reports for debugging production issues.

Line-Status (line-status.ts): Monitors JavaScript execution context to pinpoint exact line numbers for runtime errors, enhancing stack trace accuracy.

Infrastructure and Lifecycle Modules

These modules handle SDK initialization, configuration, and data egress.

Init / Destroy: The bootstrap functions init() and destroyTracing() register and unregister all global listeners. Calling destroyTracing() cleans up monkey-patches and event listeners to prevent memory leaks in single-page applications.

Replace (replace.ts): Performs monkey-patching of native browser APIs before application code executes. Located at packages/core/src/lib/replace.ts, this module is critical for intercepting fetch, XMLHttpRequest, and console methods without breaking native functionality.

SendData (sendData.ts): Implements batching, compression, and retry logic for transmitting collected events to the configured server endpoint. Handles offline buffering using local storage.

Base (base.ts): Collects static environment information including browser version, operating system, screen resolution, and user agent data.

Options (options.ts): Centralizes configuration state for the SDK. Stores initialization parameters and runtime flags accessible via the getOptions() helper.

Reactive Utilities and Helper Functions

Observer (observer/index.ts): Exports a lightweight reactive system (ref, computed, watch) used internally for state management. Located in packages/core/src/observer/index.ts, these utilities can be imported directly for building reactive tracing integrations.

Export Methods (exportMethods.ts): Contains user-facing helper functions including traceError(), tracePerformance(), traceCustomEvent(), getUserUuid(), and setUserUuid(). These allow manual reporting outside automatic instrumentation.

Utils: A collection of polyfills, local storage wrappers, fingerprinting algorithms, and IP lookup helpers located in packages/core/src/utils/.

Import Patterns and Usage Examples

Initializing the SDK

Import the entry point and initialize with your project configuration:

import { init, destroyTracing } from '@web-tracing/core'

init({
  projectId: 'YOUR_PROJECT_ID',
  recordScreen: true,
  localization: true
})

// Cleanup when needed (e.g., during SPA navigation)
destroyTracing()

Using Helper Methods

Access individual reporting functions through named exports:

import {
  traceError,
  tracePerformance,
  traceCustomEvent,
  intersectionObserver,
  getUserUuid,
  setUserUuid
} from '@web-tracing/core'

// Manual error reporting
traceError({ message: 'Something went wrong', stack: new Error().stack })

// Custom performance mark
tracePerformance({ name: 'loadTime', duration: 1234 })

// Business event tracking
traceCustomEvent({ name: 'buttonClick', props: { id: 'saveBtn' } })

// Viewport exposure tracking
intersectionObserver({
  element: document.getElementById('hero'),
  name: 'heroVisible',
  threshold: 0.5
})

// User identification
setUserUuid('user-12345')
console.log('Current user UUID →', getUserUuid())

Accessing Configuration and Manual Controls

Inspect runtime options or force immediate data transmission:

import { getOptions, sendLocal } from '@web-tracing/core'

// Read current SDK configuration
const currentConfig = getOptions()
console.log('SDK runtime options', currentConfig)

// Force transmission of buffered local storage data
sendLocal()

Key Source Files and Entry Points

Path	Responsibility
packages/core/index.ts	Public entry point; aggregates all modules and exports the SDK API
packages/core/src/lib/replace.ts	Native API monkey-patching for interception
packages/core/src/lib/err.ts	Global error capture and formatting
packages/core/src/lib/sendData.ts	Network transmission and batching logic
packages/core/src/lib/exportMethods.ts	User-facing helper function definitions
packages/core/src/observer/index.ts	Reactive primitives (ref, computed, watch)
packages/core/src/utils/	Polyfills, storage wrappers, and fingerprinting

Framework-specific adapters in packages/vue3/, packages/react/, packages/vue2/, and packages/nuxt/ re-export these core modules with framework-specific initialization logic.

Summary

• The web-tracing SDK core modules reside in packages/core and provide 15+ specialized observability functions
• Data collection modules capture errors, HTTP requests, performance metrics, page views, and DOM exposures
• Infrastructure modules handle SDK lifecycle (init/destroyTracing), configuration (options.ts), and data transmission (sendData.ts)
• The Replace module at packages/core/src/lib/replace.ts monkey-patches native APIs to enable interception without breaking application code
• Export methods like traceError() and getUserUuid() allow manual instrumentation alongside automatic collection
• All modules are accessible via named exports from @web-tracing/core with TypeScript definitions included

Frequently Asked Questions

What is the main entry point for the web-tracing SDK core modules?

The main entry point is packages/core/index.ts, which exports all functionality through named exports and a default export bundle. This file imports from packages/core/src/lib/exportMethods and aggregates the init/destroy lifecycle functions with all user-facing helper methods.

How does the Replace module intercept network requests?

The Replace module located at packages/core/src/lib/replace.ts monkey-patches the global XMLHttpRequest and fetch APIs immediately upon SDK initialization. It wraps native methods to capture request timing, payload data, and response status before delegating to the original implementations, ensuring zero breaking changes to application network code.

Can I use individual core modules without initializing the full SDK?

Yes. While automatic data collection requires calling init(), individual helper functions like traceError(), traceCustomEvent(), and getUserUuid() can be imported directly from @web-tracing/core and used independently. However, modules like HTTP interception and automatic error capture only activate after init() registers the global listeners.

What reactive utilities does the web-tracing SDK provide?

The SDK includes a lightweight reactive system in packages/core/src/observer/index.ts exporting ref(), computed(), and watch() functions. These utilities power internal SDK state management but are also exposed for developers building custom reactive integrations with the tracing system.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}