GLogger Module

Table of Contents

• Introduction
• Message categories
• Verbosity and debug levels
• Available Options and their usage
• Message header format
• Implementation notes
• Usage
• Examples
  • Example: basic logger construction and baseline info
  • Example: verbosity-gated information
  • Example: developer-focused debug output

Structured log filtering and emission

Introduction

The GLogger module provides structured, consistently formatted logging for the simulation runtime. It is intended to be the single place where verbosity/debug policies and log formatting rules are applied so that the rest of the codebase can emit messages without re-implementing filtering, headers, or formatting.

At a high level, a logger instance:

• Looks up its verbosity and debug configuration in GOptions using a caller-chosen subsystem name.
• Prepends each line with a compact header that identifies the subsystem and a monotonically increasing per-instance message counter.
• Emits messages to Geant4 output streams (i.e. G4cout / G4cerr).

Message categories

The logger supports multiple message categories:

• Debug messages (filtered by a debug level)
• Informational messages (filtered by a verbosity level)
• Warnings (always printed)
• Errors (printed and then the process terminates with an exit code)
• Critical messages (always printed with emphasized formatting)

Verbosity and debug levels

Many subsystems in this project derive from GLogger (or aggregate a GLogger instance) and expose runtime-configurable output control.

Verbosity affects informational messages:

• Level 0 prints baseline run information (always shown).
• Level 1 prints additional operational details (shown when verbosity > 0).
• Level 2 prints the most detailed step-by-step information (shown when verbosity > 1).

Debug affects debug messages:

• When debug is enabled (nonzero), debug messages are printed, including optional constructor / destructor markers that help trace object lifetime and ownership transitions.
• Debug output is intended for developers and may be verbose and implementation-specific.

Available Options and their usage

This module reads the following option keys from the runtime option provider:

• verbosity
  • Type: structured option (sequence/map, implementation-defined by GOptions)
  • Meaning: per-logger verbosity configuration
  • Behavior:
    • loggers query their verbosity level using their configured logger name as a key
    • typical levels:
      • 0 prints baseline informational output
      • 1 prints additional informational output
      • 2 prints the most detailed informational output
• debug
  • Type: structured option (sequence/map, implementation-defined by GOptions)
  • Meaning: per-logger debug enablement / debug level configuration
  • Behavior:
    • loggers query their debug configuration using their configured logger name as a key
    • values are commonly false/true (mapped to 0/1) or an integer level, depending on consumer expectations

Note: GOptions(argc,argv,...) defines these keys as global conventions so any module can participate in consistent logging without re-defining these options.

Message header format

Each emitted message is prepended with a compact header that includes:

• The configured logger name (a logical subsystem identifier).
• A monotonically increasing counter (per logger instance).

The counter is particularly useful in multi-threaded environments because it helps correlate message order even when different threads interleave output.

Implementation notes

• The implementation is intentionally lightweight and header-driven.
• Debug/info/warning/error/critical accept a variadic list of "streamable" arguments, which are concatenated using an std::ostringstream.
• A std::atomic<int> counter is used to produce the per-instance sequence number in a thread-safe manner.
• Debug logging supports special constructor/destructor styles to make lifetime tracing easier.

Usage

1. Construct a GLogger instance with :
   • A shared pointer to GOptions (used to resolve verbosity/debug configuration).
   • A caller class name (informational; currently not used for filtering).
   • A logger name (used as a lookup key in GOptions).
2. Call the relevant message methods:
   • debug()
   • info()
   • warning()
   • error()
   • critical()

Note

The error() method is marked [[noreturn]] and terminates the process.

Examples

Example: basic logger construction and baseline info

This example shows how a subsystem creates a logger with a configured subsystem name and emits always-on informational output.

// Suppose gopts is a std::shared_ptr<GOptions> configured elsewhere.
GLogger log(gopts, "MySubsystem", "mysubsystem");
log.info("starting run ", runNumber);

Example: verbosity-gated information

This example shows how to emit progressively more detailed messages depending on verbosity.

log.info(0, "run header...");
log.info(1, "loaded geometry variant ", variantName);
log.info(2, "per-channel thresholds: ", thresholdsSummary);

Example: developer-focused debug output

This example shows debug output that appears only when debug is enabled for the logger name.

log.debug(NORMAL, "constructed calibration map with ", nEntries, " entries");

Author

© Maurizio Ungaro

e-mail: ungar.nosp@m.o@jl.nosp@m.ab.or.nosp@m.g