# How to Enable and Configure Performance Tracking in Web-Tracing

> Learn to enable and configure performance tracking in your m-cheng-web/web-tracing implementation. Easily set performance flags in initOptions for detailed insights.

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

---

**Enable performance tracking in the web-tracing SDK by setting the `performance` flags (`core`, `firstResource`, `server`) to `true` inside the `initOptions` configuration object.**

The **web-tracing** SDK from `m-cheng-web/web-tracing` provides granular control over performance monitoring through three distinct configuration flags. When activated, the SDK automatically instantiates `PerformanceObserver` and `MutationObserver` instances to capture resource loading times, navigation metrics, and server request durations. This article explains the configuration options, internal architecture, and implementation steps required to collect performance data in your application.

## Understanding the Performance Configuration Options

The SDK exposes three boolean flags within the `performance` object passed to `initOptions`. Each flag controls a specific category of metrics collection:

- **`core`** – Captures static resource timings (images, scripts, stylesheets) and AJAX requests using the `PerformanceObserver` API. When enabled, the SDK listens for `'resource'` entries and extracts timing data such as DNS lookup, TCP connect, and response duration.
- **`firstResource`** – Records first-page navigation metrics including First Contentful Paint (FCP), Time to Interactive (TTI), and TCP connection times. This invokes `observeNavigationTiming()` to build a comprehensive `times` object from the browser's Navigation Timing API.
- **`server`** – Enables tracking of server-side request durations when backend calls complete successfully, providing end-to-end visibility into request latency.

All three flags default to `false` and must be explicitly enabled via `initOptions` as defined in [`packages/core/src/lib/options.ts`](https://github.com/m-cheng-web/web-tracing/blob/main/packages/core/src/lib/options.ts) (lines 19‑28).

## How Performance Tracking Works Internally

When you initialize the SDK with performance flags enabled, the core library executes `initPerformance()` (located in [`packages/core/src/lib/performance.ts`](https://github.com/m-cheng-web/web-tracing/blob/main/packages/core/src/lib/performance.ts), lines 53‑73). This function conditionally wires the following observers based on your configuration:

**PerformanceObserver Implementation**  
For browsers supporting the modern Performance Observer API, the SDK creates an observer for `'resource'` entries (lines 44‑53). Each entry is processed to extract metrics like `startTime`, `responseEnd`, and `initiatorType`, then normalized for transmission.

**MutationObserver Fallback**  
In environments lacking `PerformanceObserver` support, the SDK falls back to a `MutationObserver` (lines 104‑121) that detects dynamic DOM insertions of `<script>`, `<link>`, and `<img>` tags. This ensures resource tracking compatibility across older browsers.

**Navigation Timing Collection**  
When `firstResource` is enabled, the SDK invokes `observeNavigationTiming()` (lines 60‑98) to capture high-level page metrics including DNS resolution time, TCP handshake duration, and DOM readiness events. These metrics populate a structured `times` object that represents the full page lifecycle.

**Data Transmission**  
All collected performance data flows through `sendData.emit()` (lines 88‑100), which formats the payload and transmits it to the configured DSN endpoint.

## Step-by-Step Configuration Examples

### Enabling Core Resource Timing

To track static assets and network requests, enable the `core` flag during initialization:

```typescript
import { initOptions } from 'web-tracing';

initOptions({
  dsn: 'https://your-collector.example.com/collect',
  appName: 'production-app',
  performance: {
    core: true
  }
});

```

This configuration activates the `PerformanceObserver` for resource entries as implemented in [`packages/core/src/lib/performance.ts`](https://github.com/m-cheng-web/web-tracing/blob/main/packages/core/src/lib/performance.ts).

### Capturing First-Page Navigation Metrics

For single-page applications or landing pages where initial load performance is critical, enable `firstResource` to capture navigation timing:

```typescript
import { initOptions } from 'web-tracing';

initOptions({
  dsn: 'https://your-collector.example.com/collect',
  appName: 'production-app',
  performance: {
    core: true,
    firstResource: true
  }
});

```

This setting triggers `observeNavigationTiming()`, recording metrics such as `connectEnd`, `responseStart`, and `domInteractive` (lines 60‑98).

### Full Performance Suite with Server Timing

For comprehensive monitoring including backend latency, enable all three flags:

```typescript
import { initOptions } from 'web-tracing';

initOptions({
  dsn: 'https://your-collector.example.com/collect',
  appName: 'production-app',
  performance: {
    core: true,
    firstResource: true,
    server: true
  }
});

```

This configuration collects resource timings, navigation metrics, and server request durations, providing complete end-to-end visibility.

### Framework-Specific Integration (Vue 3)

When using the Vue 3 wrapper, import from the framework-specific entry point and call `initOptions` before mounting your application:

```typescript
import { createApp } from 'vue';
import WebTracing from 'web-tracing/vue3';
import App from './App.vue';

WebTracing.initOptions({
  dsn: 'https://your-collector.example.com/collect',
  appName: 'vue3-production-app',
  performance: { 
    core: true, 
    firstResource: true 
  }
});

createApp(App).mount('#app');

```

The Vue 3 wrapper automatically handles the internal call to `initPerformance()` once the options object is validated.

## Key Source Files and Architecture

Understanding the source structure helps with debugging and advanced customization:

- **[`packages/core/src/lib/performance.ts`](https://github.com/m-cheng-web/web-tracing/blob/main/packages/core/src/lib/performance.ts)** – Contains the main `initPerformance()` function, `PerformanceObserver` wiring, `MutationObserver` fallback logic, and `observeNavigationTiming()` implementation.
- **[`packages/core/src/lib/options.ts`](https://github.com/m-cheng-web/web-tracing/blob/main/packages/core/src/lib/options.ts)** – Defines the `performance` configuration interface and validates input parameters (lines 19‑28).
- **[`packages/core/src/lib/sendData.ts`](https://github.com/m-cheng-web/web-tracing/blob/main/packages/core/src/lib/sendData.ts)** – Handles the transmission layer that emits normalized performance records to your collector endpoint.
- **`packages/core/src/observer/`** – Directory containing reactive observer utilities ([`ref.ts`](https://github.com/m-cheng-web/web-tracing/blob/main/ref.ts), [`watcher.ts`](https://github.com/m-cheng-web/web-tracing/blob/main/watcher.ts)) that support the performance tracking infrastructure.
- **[`examples/vue3/src/main.ts`](https://github.com/m-cheng-web/web-tracing/blob/main/examples/vue3/src/main.ts)** – Reference implementation showing typical SDK initialization patterns in a Vue 3 application context.

## Summary

- **Enable tracking** by setting `performance.core`, `performance.firstResource`, or `performance.server` to `true` in `initOptions`.
- **Resource monitoring** uses `PerformanceObserver` for modern browsers and `MutationObserver` as a fallback for legacy support.
- **Navigation metrics** are captured via `observeNavigationTiming()` when `firstResource` is enabled, providing FCP, TTI, and TCP timing data.
- **Data transmission** occurs automatically through `sendData.emit()` without requiring manual intervention.
- **Framework wrappers** like `web-tracing/vue3` handle the internal initialization sequence automatically after `initOptions` is called.

## Frequently Asked Questions

### How do I disable performance tracking after enabling it?

Performance tracking is initialized once during the SDK bootstrap process based on the immutable configuration passed to `initOptions`. To disable tracking, you must omit the `performance` flags or set them to `false` before calling `initOptions`, then reload the application. There is no runtime toggle to disable observers after initialization according to the source implementation in [`packages/core/src/lib/performance.ts`](https://github.com/m-cheng-web/web-tracing/blob/main/packages/core/src/lib/performance.ts).

### What is the performance overhead of enabling all three flags?

The SDK uses native browser APIs (`PerformanceObserver` and `MutationObserver`) that operate on the browser's internal performance timeline without polling. The overhead is minimal for `core` and `firstResource` flags, typically adding less than 1ms of processing per resource entry. The `server` flag adds negligible overhead as it only records timestamp differences for completed requests, as implemented in the data emission logic (lines 88‑100 of [`performance.ts`](https://github.com/m-cheng-web/web-tracing/blob/main/performance.ts)).

### Can I track performance in Web Workers or Service Workers?

The current implementation in [`packages/core/src/lib/performance.ts`](https://github.com/m-cheng-web/web-tracing/blob/main/packages/core/src/lib/performance.ts) targets the main thread's `window` object and `document` for `MutationObserver` fallbacks. Performance tracking in Web Workers would require the Worker to post message timing data to the main thread, as the SDK does not directly instrument Worker contexts. The `PerformanceObserver` API is available in Workers, but the SDK's initialization logic expects a DOM environment.

### How do I customize which resource types are tracked (e.g., only images)??

The SDK's `PerformanceObserver` implementation captures all `'resource'` entry types without filtering by default (lines 44‑53). To track specific resource types only, you would need to modify the callback logic in [`packages/core/src/lib/performance.ts`](https://github.com/m-cheng-web/web-tracing/blob/main/packages/core/src/lib/performance.ts) to check `entry.initiatorType` (e.g., `'img'`, `'script'`, `'css'`) before calling `sendData.emit()`. The current API does not expose a configuration option for entry-type filtering in `initOptions`.