# Web-Tracing SDK Core Modules: Complete Architecture Guide

> Explore the web tracing SDK's 15+ core modules for error tracking, performance monitoring, and user analytics. Discover the complete architecture and control with init and destroy functions.

- Repository: [m-cheng-web/web-tracing](https://github.com/m-cheng-web/web-tracing)
- Tags: architecture
- Published: 2026-03-06

---

**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`](https://github.com/m-cheng-web/web-tracing/blob/main/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`](https://github.com/m-cheng-web/web-tracing/blob/main/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`](https://github.com/m-cheng-web/web-tracing/blob/main/err.ts))**: Captures uncaught exceptions and custom error reports via global event listeners. Located at [`packages/core/src/lib/err.ts`](https://github.com/m-cheng-web/web-tracing/blob/main/packages/core/src/lib/err.ts), this module processes stack traces and batches error payloads for transmission.

**HTTP ([`http.ts`](https://github.com/m-cheng-web/web-tracing/blob/main/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`](https://github.com/m-cheng-web/web-tracing/blob/main/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`](https://github.com/m-cheng-web/web-tracing/blob/main/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`](https://github.com/m-cheng-web/web-tracing/blob/main/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`](https://github.com/m-cheng-web/web-tracing/blob/main/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`](https://github.com/m-cheng-web/web-tracing/blob/main/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`](https://github.com/m-cheng-web/web-tracing/blob/main/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`](https://github.com/m-cheng-web/web-tracing/blob/main/replace.ts))**: Performs monkey-patching of native browser APIs before application code executes. Located at [`packages/core/src/lib/replace.ts`](https://github.com/m-cheng-web/web-tracing/blob/main/packages/core/src/lib/replace.ts), this module is critical for intercepting `fetch`, `XMLHttpRequest`, and `console` methods without breaking native functionality.

**SendData ([`sendData.ts`](https://github.com/m-cheng-web/web-tracing/blob/main/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`](https://github.com/m-cheng-web/web-tracing/blob/main/base.ts))**: Collects static environment information including browser version, operating system, screen resolution, and user agent data.

**Options ([`options.ts`](https://github.com/m-cheng-web/web-tracing/blob/main/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`](https://github.com/m-cheng-web/web-tracing/blob/main/observer/index.ts))**: Exports a lightweight reactive system (`ref`, `computed`, `watch`) used internally for state management. Located in [`packages/core/src/observer/index.ts`](https://github.com/m-cheng-web/web-tracing/blob/main/packages/core/src/observer/index.ts), these utilities can be imported directly for building reactive tracing integrations.

**Export Methods ([`exportMethods.ts`](https://github.com/m-cheng-web/web-tracing/blob/main/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:

```typescript
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:

```typescript
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:

```typescript
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`](https://github.com/m-cheng-web/web-tracing/blob/main/packages/core/index.ts) | Public entry point; aggregates all modules and exports the SDK API |
| [`packages/core/src/lib/replace.ts`](https://github.com/m-cheng-web/web-tracing/blob/main/packages/core/src/lib/replace.ts) | Native API monkey-patching for interception |
| [`packages/core/src/lib/err.ts`](https://github.com/m-cheng-web/web-tracing/blob/main/packages/core/src/lib/err.ts) | Global error capture and formatting |
| [`packages/core/src/lib/sendData.ts`](https://github.com/m-cheng-web/web-tracing/blob/main/packages/core/src/lib/sendData.ts) | Network transmission and batching logic |
| [`packages/core/src/lib/exportMethods.ts`](https://github.com/m-cheng-web/web-tracing/blob/main/packages/core/src/lib/exportMethods.ts) | User-facing helper function definitions |
| [`packages/core/src/observer/index.ts`](https://github.com/m-cheng-web/web-tracing/blob/main/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`](https://github.com/m-cheng-web/web-tracing/blob/main/options.ts)), and data transmission ([`sendData.ts`](https://github.com/m-cheng-web/web-tracing/blob/main/sendData.ts))
- The **Replace** module at [`packages/core/src/lib/replace.ts`](https://github.com/m-cheng-web/web-tracing/blob/main/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`](https://github.com/m-cheng-web/web-tracing/blob/main/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`](https://github.com/m-cheng-web/web-tracing/blob/main/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`](https://github.com/m-cheng-web/web-tracing/blob/main/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.