How to Enable and Configure Performance Tracking in Web-Tracing

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 (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, 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:

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.

Capturing First-Page Navigation Metrics

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

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:

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:

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 – Contains the main initPerformance() function, PerformanceObserver wiring, MutationObserver fallback logic, and observeNavigationTiming() implementation.
• packages/core/src/lib/options.ts – Defines the performance configuration interface and validates input parameters (lines 19‑28).
• 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, watcher.ts) that support the performance tracking infrastructure.
• 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.

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).

Can I track performance in Web Workers or Service Workers?

The current implementation in 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 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.

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