Debug and Logging

The SDK provides internal logging functionality to help with debugging and troubleshooting. You can control the verbosity of SDK logs and inspect the current configuration state.

Critical Debug and Logging Behavior:

• Default log level is warn
• Log level changes take effect immediately
• Log level is not persisted across page loads
• debug() outputs to console synchronously
• If console is unavailable, logging is silently disabled
• Log levels are case-sensitive
• Invalid log levels may be ignored or default to warn

Capabilities

Set Active Log Level

Changes the active log level of the SDK to control internal logging verbosity.

/**
 * Changes the logging verbosity of Dash0's Web SDK
 * @param level - The log level to set
 * @throws No errors thrown; invalid levels may be ignored
 */
function setActiveLogLevel(level: LogLevel): void;

type LogLevel = "debug" | "info" | "warn" | "error";

Default log level: warn

Usage Examples:

import { setActiveLogLevel } from "@dash0/sdk-web";

// Enable debug logging for troubleshooting
setActiveLogLevel("debug");

// Set to info level for moderate verbosity
setActiveLogLevel("info");

// Set to warn (default)
setActiveLogLevel("warn");

// Only show errors
setActiveLogLevel("error");

For IIFE (script tag) usage:

dash0("setActiveLogLevel", "debug");

Critical Behavior:

• Log level changes take effect immediately
• Invalid log levels may be ignored or default to warn
• Log level is case-sensitive
• Log level affects all subsequent log messages
• Log level is not persisted across page loads
• Log level is independent per tab (not shared)
• Setting log level before init() affects initialization logging

Debug Configuration

Logs the current SDK configuration state to the console.

/**
 * Logs the current Dash0 Web SDK configuration state
 * @throws No errors thrown; console errors may occur if console is unavailable
 */
function debug(): void;

Usage Example:

import { debug } from "@dash0/sdk-web";

// Log current configuration
debug();

For IIFE (script tag) usage:

dash0("debug");

This will output the internal SDK state including:

• Configured endpoints
• Resource attributes
• Instrumentation scope
• Signal attributes
• Ignore rules (URLs, error messages)
• Event handler and timer wrapping settings
• Propagator configuration
• Timing configuration
• Header capture configuration
• URL scrubber configuration
• Page view instrumentation settings
• Transport compression settings

Critical Behavior:

• Output is written to console synchronously
• Output format is implementation-specific and may change
• If console is unavailable, output is silently suppressed
• Output includes all current configuration, not just user-provided values
• Output may be large for complex configurations
• Calling debug() before init() may show incomplete configuration
• Output includes sensitive information (auth tokens, etc.); use with caution

Log Levels

The SDK supports four log levels, each including messages from higher severity levels:

Debug

Most verbose level. Includes all SDK internal operations.

setActiveLogLevel("debug");

Use for:

• Detailed troubleshooting
• Understanding SDK behavior
• Investigating integration issues

Critical Behavior:

• Debug level includes all log messages (debug, info, warn, error)
• Debug logging can generate significant console output
• Debug logging may impact performance in production
• Debug messages are only visible in browser console
• Debug logging may expose sensitive information
• Debug logging may slow down telemetry collection

Info

Informational messages about SDK operations.

setActiveLogLevel("info");

Use for:

• General SDK activity monitoring
• Confirming successful operations
• Development environments

Critical Behavior:

• Info level includes info, warn, and error messages (not debug)
• Info messages provide general operational information
• Info logging has minimal performance impact
• Info messages are less verbose than debug messages

Warn (Default)

Warnings about potential issues that don't prevent SDK operation.

setActiveLogLevel("warn");

Use for:

• Production environments
• Identifying configuration issues
• Detecting deprecated API usage

Critical Behavior:

• Warn level includes warn and error messages (not debug or info)
• Warn is the default log level
• Warn messages indicate potential issues but don't prevent operation
• Warn messages are important for production monitoring

Error

Only critical errors that affect SDK functionality.

setActiveLogLevel("error");

Use for:

• Minimal logging in production
• Only showing critical issues
• Performance-sensitive scenarios

Critical Behavior:

• Error level includes only error messages
• Error messages indicate critical issues that affect SDK operation
• Error logging has minimal performance impact
• Error messages are the most important for troubleshooting

Common Use Cases

Development Environment

Enable debug logging during development:

import { init, setActiveLogLevel } from "@dash0/sdk-web";

// Enable debug logging in development
if (process.env.NODE_ENV === "development") {
  setActiveLogLevel("debug");
}

init({
  serviceName: "my-website",
  endpoint: { url: "...", authToken: "..." },
});

Troubleshooting Integration

Use debug logging and configuration inspection when troubleshooting:

import { init, setActiveLogLevel, debug } from "@dash0/sdk-web";

// Enable debug logging
setActiveLogLevel("debug");

// Initialize SDK
init({
  serviceName: "my-website",
  endpoint: { url: "...", authToken: "..." },
  propagators: [
    { type: "traceparent", match: [/.*\/api\/.*/] },
  ],
});

// Inspect configuration
debug();

// Check browser console for detailed logs

Production Monitoring

Use warn level in production, with ability to enable debug on demand:

import { init, setActiveLogLevel } from "@dash0/sdk-web";

// Default to warn level
setActiveLogLevel("warn");

// Initialize SDK
init({
  serviceName: "my-website",
  endpoint: { url: "...", authToken: "..." },
});

// Make setActiveLogLevel available globally for debugging
if (typeof window !== "undefined") {
  window.enableDash0Debug = () => setActiveLogLevel("debug");
  window.disableDash0Debug = () => setActiveLogLevel("warn");
}

Then in browser console:

// Enable debug logging in production for troubleshooting
window.enableDash0Debug();

// Disable when done
window.disableDash0Debug();

Conditional Logging Based on User

Enable debug logging for specific users or sessions:

import { init, setActiveLogLevel, identify } from "@dash0/sdk-web";

init({
  serviceName: "my-website",
  endpoint: { url: "...", authToken: "..." },
});

// After user login
async function handleLogin(userId) {
  // Enable debug logging for specific users
  if (isDebugUser(userId)) {
    setActiveLogLevel("debug");
  }

  identify(userId);
}

Query Parameter Control

Allow enabling debug mode via query parameter:

import { init, setActiveLogLevel } from "@dash0/sdk-web";

// Check for debug query parameter
const urlParams = new URLSearchParams(window.location.search);
const debugMode = urlParams.get("dash0_debug") === "true";

if (debugMode) {
  setActiveLogLevel("debug");
  console.log("Dash0 debug mode enabled via query parameter");
}

init({
  serviceName: "my-website",
  endpoint: { url: "...", authToken: "..." },
});

Usage: https://example.com?dash0_debug=true

Error-Only Logging

Minimize logging overhead in performance-critical scenarios:

import { init, setActiveLogLevel } from "@dash0/sdk-web";

// Only log errors
setActiveLogLevel("error");

init({
  serviceName: "my-website",
  endpoint: { url: "...", authToken: "..." },
});

Staged Log Levels

Use different log levels for different environments:

import { init, setActiveLogLevel } from "@dash0/sdk-web";

// Configure log level based on environment
const logLevels = {
  development: "debug",
  staging: "info",
  production: "warn",
};

setActiveLogLevel(logLevels[process.env.NODE_ENV] || "warn");

init({
  serviceName: "my-website",
  endpoint: { url: "...", authToken: "..." },
});

Configuration Validation

Use debug() to validate configuration after initialization:

import { init, debug } from "@dash0/sdk-web";

init({
  serviceName: "my-website",
  endpoint: { url: "...", authToken: "..." },
  propagators: [
    { type: "traceparent", match: [/.*\/api\/.*/] },
  ],
  ignoreUrls: [/.*\/health$/],
  additionalSignalAttributes: {
    "app.version": "1.2.3",
  },
});

// Verify configuration in console
debug();

Console Output

SDK logs are written to the browser console with prefixes to identify them as Dash0 SDK messages. The exact format depends on the log level:

• Debug: Detailed information about SDK operations
• Info: General informational messages
• Warn: Warnings about potential issues
• Error: Critical errors

Critical Behavior:

• Log messages are prefixed to identify them as Dash0 SDK messages
• Log format is implementation-specific and may change
• Log messages are written to console synchronously
• Log messages may include stack traces for errors
• Log messages may include sensitive information (auth tokens, etc.)
• Console output may be throttled by browsers in some scenarios

Performance Considerations

• Debug logging can generate significant console output, which may impact performance
• Use warn or error levels in production to minimize overhead
• The debug() function creates a complete snapshot of the configuration state
• Log level changes take effect immediately for all subsequent log messages
• Console output may be throttled by browsers in some scenarios
• Very frequent log messages may impact performance
• Large log messages may impact performance

Browser Console Compatibility

The SDK checks for console availability and log method support before attempting to log. If the console or specific log methods are unavailable, logging is silently disabled.

Critical Behavior:

• Console availability is checked before each log operation
• If console is unavailable, logging is silently disabled (no errors thrown)
• Different browsers may have different console implementations
• Console methods (log, warn, error) are checked for availability
• Logging failures do not affect SDK operation
• Console may be overridden by other code, affecting logging behavior
• Console filtering may hide log messages

Edge Cases and Error Conditions

Log Level Edge Cases

• Invalid Levels: Invalid log level values may be ignored or default to warn
• Case Sensitivity: Log levels are case-sensitive; "Debug" is not the same as "debug"
• Null/Undefined: Null or undefined log levels may cause errors or be ignored
• Non-String Values: Non-string log level values may be ignored or cause errors
• Empty Strings: Empty string log levels may be ignored or cause errors
• Very Long Strings: Very long log level strings may be ignored or cause errors

Console Edge Cases

• Console Unavailable: If console is unavailable, logging is silently disabled
• Console Methods Missing: If specific console methods are missing, logging may fail silently
• Console Overridden: If console is overridden by code, logging behavior may change
• Console Filtering: Browser console filters may hide log messages
• Console Throttling: Browsers may throttle console output, causing log messages to be delayed or dropped
• Console Performance: Very frequent console operations may impact performance

Debug Function Edge Cases

• Before Init: Calling debug() before init() may show incomplete or empty configuration
• After Multiple Init: If init() is called multiple times, debug() shows the current configuration
• Large Configurations: Very large configurations may cause console output issues
• Circular References: Configuration with circular references may cause serialization issues
• Sensitive Information: debug() output includes sensitive information (auth tokens, etc.)
• Console Overflow: Very large debug output may overflow console buffers

Performance Edge Cases

• High Frequency Logging: Very frequent log messages may impact performance
• Large Log Messages: Very large log messages may impact performance
• Console Throttling: Browsers may throttle console output, causing log messages to be delayed or dropped
• Memory Usage: Debug logging may increase memory usage, especially with large configurations
• CPU Usage: Debug logging may increase CPU usage, especially with high-frequency logging

Multiple Tabs

• Independent Log Levels: Log levels are independent per tab (not shared)
• Shared Configuration: Configuration is shared across tabs (via storage), but log levels are not
• Console Isolation: Each tab has its own console, so log messages are not shared
• Tab Synchronization: Log level changes in one tab do not affect other tabs

Network and Transmission

• Logging and Telemetry: Log levels do not affect telemetry transmission
• Debug Output: Debug output is separate from telemetry data
• Log Transmission: Log messages are not transmitted to Dash0 endpoints (only telemetry is)
• Log Filtering: Log level filtering only affects console output, not telemetry

Security Edge Cases

• Sensitive Information: Log messages may include sensitive information (auth tokens, user data, etc.)
• Production Logging: Be careful about logging sensitive information in production
• Console Access: Console output is accessible to anyone with browser access
• Log Persistence: Log messages are not persisted; they only exist in console

Environment Edge Cases

• Development vs Production: Different log levels may be appropriate for different environments
• Environment Detection: Environment detection may not always be accurate
• Build Tools: Build tools may affect environment variables
• Server-Side Rendering: Log levels may behave differently in SSR environments