Trace Verbosity Levels¶

Verified by tests

TraceVerbosityTests, TracingOptionsTests, TraceComponentsTests — library CI run #31657041675 (2026-08-13)

The TraceVerbosity enum controls how much detail Whizbang emits in traces. Verbosity levels are hierarchical - higher levels include all output from lower levels.

Namespace¶

Namespace

using Whizbang.Core.Tracing;

Verbosity Levels¶

Level	Value	Description
`Off`	0	No tracing output
`Minimal`	1	Errors, failures, and explicitly marked traces only
`Normal`	2	Command/Event lifecycle stage transitions
`Verbose`	3	Outbox/Inbox operations, handler discovery
`Debug`	4	Full payload, timing breakdown, perspectives

Level Details¶

Off¶

No tracing output is emitted. Use this in production when tracing overhead must be eliminated entirely.

Disable Tracing

services.AddWhizbang(options => {
  options.Tracing.Verbosity = TraceVerbosity.Off;
});

Minimal¶

Emits traces only for:

Errors and failures
Handlers or messages explicitly marked with [WhizbangTrace]
Handlers or messages matching patterns in TracedHandlers or TracedMessages

Minimal Verbosity

services.AddWhizbang(options => {
  options.Tracing.Verbosity = TraceVerbosity.Minimal;
  options.Tracing.Components = TraceComponents.Production;

  // Explicitly trace specific handlers
  options.Tracing.TracedHandlers["PaymentReceptor"] = TraceVerbosity.Minimal;
});

Recommended for: Production environments where you only need error visibility and specific handler monitoring.

Normal¶

Includes Minimal plus:

Command and event lifecycle stage transitions
Handler invocation begin/end markers
Basic timing information

Normal Verbosity

services.AddWhizbang(options => {
  options.Tracing.Verbosity = TraceVerbosity.Normal;
  options.Tracing.Components = TraceComponents.Handlers | TraceComponents.Lifecycle;
});

Recommended for: Production environments where you need to track message flow without excessive detail.

Verbose¶

Includes Normal plus:

Handler discovery and routing decisions
Outbox write and delivery operations
Inbox read and processing operations
Service resolution details

Verbose Verbosity

services.AddWhizbang(options => {
  options.Tracing.Verbosity = TraceVerbosity.Verbose;
  options.Tracing.Components = TraceComponents.AllWithoutWorkers;
});

Recommended for: Staging environments or debugging message delivery issues.

Debug¶

Includes Verbose plus:

Full message payloads (serialized)
Detailed timing breakdowns
Perspective state changes
Internal decision points

Debug Verbosity

services.AddWhizbang(options => {
  options.Tracing.Verbosity = TraceVerbosity.Debug;
  options.Tracing.Components = TraceComponents.All;
  options.Tracing.EnablePerspectiveEventSpans = true;
});

Recommended for: Local development and deep debugging. Avoid in production due to performance impact and potential PII exposure.

Hierarchical Behavior¶

Higher verbosity levels automatically include all output from lower levels:

Debug (4) includes:
  - Verbose (3) which includes:
    - Normal (2) which includes:
      - Minimal (1) which includes:
        - Errors and explicit traces

This means setting TraceVerbosity.Verbose automatically includes lifecycle transitions (Normal) and error traces (Minimal).

Configuration via appsettings.json¶

appsettings.json Verbosity

{
  "Whizbang": {
    "Tracing": {
      "Verbosity": "Normal"
    }
  }
}

Valid string values: "Off", "Minimal", "Normal", "Verbose", "Debug"

Per-Handler Verbosity Override¶

Override verbosity for specific handlers regardless of global setting:

Handler-Specific Verbosity

services.AddWhizbang(options => {
  options.Tracing.Verbosity = TraceVerbosity.Minimal;  // Global: minimal
  options.Tracing.Components = TraceComponents.Handlers;

  // Override for specific handlers
  options.Tracing.TracedHandlers["PaymentReceptor"] = TraceVerbosity.Debug;
  options.Tracing.TracedHandlers["Order*"] = TraceVerbosity.Verbose;
});

Per-Message Verbosity Override¶

Override verbosity based on message type:

Message-Specific Verbosity

services.AddWhizbang(options => {
  options.Tracing.Verbosity = TraceVerbosity.Minimal;
  options.Tracing.Components = TraceComponents.Messages;

  // Debug all payment-related messages
  options.Tracing.TracedMessages["*PaymentCommand"] = TraceVerbosity.Debug;
  options.Tracing.TracedMessages["PaymentProcessed"] = TraceVerbosity.Verbose;
});

Verbosity and ShouldTrace¶

The TracingOptions.ShouldTrace() method checks if a trace at a given level should be emitted:

ShouldTrace Method

// Returns true if current verbosity meets or exceeds required level
if (options.ShouldTrace(TraceVerbosity.Verbose)) {
  // Emit verbose-level trace
}

Best Practices¶

Production¶

Production Verbosity

options.Tracing.Verbosity = TraceVerbosity.Minimal;
options.Tracing.Components = TraceComponents.Production;

// Explicitly trace critical paths
options.Tracing.TracedHandlers["PaymentReceptor"] = TraceVerbosity.Normal;

Development¶

Development Verbosity

options.Tracing.Verbosity = TraceVerbosity.Debug;
options.Tracing.Components = TraceComponents.AllWithoutWorkers;

Debugging Specific Issues¶

Targeted Debugging

options.Tracing.Verbosity = TraceVerbosity.Minimal;
options.Tracing.TracedHandlers["ProblematicHandler"] = TraceVerbosity.Debug;