Understanding the Debug Mode in web-tracing: Configuration and Usage

The debug mode in web-tracing is a runtime configuration flag that activates verbose console logging throughout the SDK, allowing developers to monitor internal operations during development while remaining completely silent in production environments.

The web-tracing library provides comprehensive tracking capabilities for web applications, but diagnosing its internal behavior requires visibility into its processing pipeline. The debug mode serves as an opt-in diagnostic layer that exposes the SDK's internal state through the browser console without modifying core functionality or data collection logic.

Architecture of the Debug Mode

Global Configuration in Options

The debug flag is defined as the debug property within the global Options object located in packages/core/src/lib/options.ts. By default, this boolean value is set to false, ensuring that production deployments remain free of console noise. When initializing the SDK, developers can toggle this flag through the initOptions function, which stores the value in a reactive options object accessible via options.value.debug.

The Centralized Logger Implementation

All diagnostic output routes through the debug helper function defined in packages/core/src/utils/debug.ts. This utility checks the current state of options.value.debug before emitting any output:

// packages/core/src/utils/debug.ts
import { options } from '../lib/options'

export function debug(...args: any[]): void {
  if (options.value.debug) console.log('@web-tracing: ', ...args)
}

When the flag is disabled, the function exits immediately as a no-op, preserving runtime performance. When enabled, it prefixes all messages with @web-tracing: for easy filtering in the browser console.

Enabling Debug Mode in Your Application

To activate diagnostic logging during development, set the debug property to true when calling initOptions:

import { initOptions } from '@web-tracing/core'

initOptions({
  dsn: 'https://example.com/trace',
  appName: 'my-app',
  debug: true   // Enables console diagnostics
})

This configuration is demonstrated in the Vue 3 example at examples/vue3/src/main.ts and the vanilla JavaScript example at examples/vanilla/main.ts, showing practical implementations across different framework setups.

Internal Usage and Diagnostic Coverage

Event Sending Pipeline

The SDK emits detailed logs during the data transmission phase. In packages/core/src/lib/sendData.ts, the sendEvents function calls debug before executing network requests:

// packages/core/src/lib/sendData.ts (excerpt)
import { debug, logError } from '../utils/debug'

export function sendEvents(payload) {
  debug('send events', payload)   // Visible only in debug mode
  // ... transmission logic
}

This allows developers to inspect the exact payload structure and transmission timing.

Network Status and Error Handling

Modules monitoring line status changes and error processing rules also utilize the debug function to report state transitions and ignore-rule matches. These logs appear only when the debug flag is active, providing visibility into why certain errors might be filtered or how the SDK responds to connectivity changes.

Distinguishing Debug Output from Error Logging

While the debug function is conditional, the SDK provides a separate logError utility that writes to console.error regardless of the debug mode setting. This ensures that critical failures are always visible, even in production environments where verbose tracing is disabled. The debug mode is strictly for operational visibility and never alters the SDK's data collection behavior or network traffic patterns.

Summary

• The debug mode is controlled by the debug property in packages/core/src/lib/options.ts, defaulting to false for production silence.
• The debug() helper in packages/core/src/utils/debug.ts conditionally logs messages prefixed with @web-tracing: only when the flag is enabled.
• Core modules like sendData.ts use this logger to expose internal operations without impacting performance when disabled.
• Unlike logError(), which always outputs to the console, the debug logger is strictly opt-in and safe for production builds.

Frequently Asked Questions

How do I enable debug mode in web-tracing?

Set the debug property to true in the configuration object passed to initOptions() during SDK initialization. This activates console logging prefixed with @web-tracing: across all internal modules.

Does debug mode affect application performance?

No. When debug is set to false (the default), the debug() function returns immediately without executing any logging logic, making it a zero-cost abstraction in production builds.

What is the difference between debug() and logError() in web-tracing?

The debug() function checks the options.value.debug flag and only outputs to console.log when enabled, while logError() always writes to console.error regardless of configuration, ensuring critical errors remain visible.

Where can I find examples of debug mode implementation?

Reference the Vue 3 implementation in examples/vue3/src/main.ts or the vanilla JavaScript version in examples/vanilla/main.ts to see practical initialization patterns with debug: true.

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