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

> Learn how to use web-tracing debug mode to enable verbose console logging for internal operations during development. Enhance your debugging experience with this powerful feature.

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

---

**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`](https://github.com/m-cheng-web/web-tracing/blob/main/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`](https://github.com/m-cheng-web/web-tracing/blob/main/packages/core/src/utils/debug.ts). This utility checks the current state of `options.value.debug` before emitting any output:

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

```typescript
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`](https://github.com/m-cheng-web/web-tracing/blob/main/examples/vue3/src/main.ts) and the vanilla JavaScript example at [`examples/vanilla/main.ts`](https://github.com/m-cheng-web/web-tracing/blob/main/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`](https://github.com/m-cheng-web/web-tracing/blob/main/packages/core/src/lib/sendData.ts), the `sendEvents` function calls `debug` before executing network requests:

```typescript
// 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`](https://github.com/m-cheng-web/web-tracing/blob/main/packages/core/src/lib/options.ts), defaulting to `false` for production silence.
- The `debug()` helper in [`packages/core/src/utils/debug.ts`](https://github.com/m-cheng-web/web-tracing/blob/main/packages/core/src/utils/debug.ts) conditionally logs messages prefixed with `@web-tracing:` only when the flag is enabled.
- Core modules like [`sendData.ts`](https://github.com/m-cheng-web/web-tracing/blob/main/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`](https://github.com/m-cheng-web/web-tracing/blob/main/examples/vue3/src/main.ts) or the vanilla JavaScript version in [`examples/vanilla/main.ts`](https://github.com/m-cheng-web/web-tracing/blob/main/examples/vanilla/main.ts) to see practical initialization patterns with `debug: true`.