StormByte-Logger 3.0.0
C++26 logger module of the StormByte suite
Loading...
Searching...
No Matches
StormByte::Logger Namespace Reference

Logger module of the StormByte suite. More...

Classes

class  Exception
 Root exception for Logger. More...
class  ThrottleError
 Thrown when a throttle rule is invalid. More...
class  Log
 Public streaming facade for the StormByte logger. More...
struct  ThrottleSpec
 Immutable rule description used by Log::Throttle. More...
struct  GroupManip
 Labels the current logging line with a producer group. More...
struct  ComponentManip
 Selects the sticky component for the current thread. More...
struct  ResetComponentManip
 Clears the component associated with the current thread. More...
struct  PopComponentManip
 Pops one segment from the current thread's component stack. More...
struct  FormatManip
 Temporarily replaces the logger format and saves the previous one. More...
struct  PopFormatManip
 Restores the most recently saved logger format. More...
struct  ColorManip
 Temporarily selects a configured or explicit content color. More...
struct  NoColorManip
 Disables color for subsequent content until changed. More...
struct  RedactManip
 Stateful redaction manipulator. More...
struct  HexManip
 Dump subsequent payloads as hex bytes until nohex. More...
struct  NoHexManip
 Disable hex dumps and restore default payload formatting. More...
class  ThreadedLog
 Thread-safe logging facade. More...

Concepts

concept  LogPointer
 Pointer-like owner of Log or a derived logger.

Typedefs

using SinkWrite = void (*)(void* context, const char* data, std::size_t size)
 Caller-side write of raw bytes into the sink.
using SinkManip = void (*)(void* context, std::ostream& (*manip)(std::ostream&))
 Caller-side application of an std::ostream manipulator.
using SinkFunction = StormByte::Safe::Function<void(const StormByte::Safe::String&)>
 Typed text callback whose context is released in its creator module.

Enumerations

enum class  ThrottlePolicy : unsigned char { Drop , Sample , Window }
 Count policy applied before the optional rate bucket. More...
enum class  Color : unsigned char {
  Default , Black , Red , Green ,
  Yellow , Blue , Magenta , Cyan ,
  Gray , White , BrightBlack , BrightRed ,
  BrightGreen , BrightYellow , BrightBlue , BrightMagenta ,
  BrightCyan , BrightWhite
}
 ANSI foreground colors supported by the logger. More...
enum class  Level : unsigned short {
  LowLevel = 0 , Debug , Warning , Notice ,
  Info , Error , Fatal
}
 Severity levels used by the logger. More...

Functions

void OStreamWrite (void *context, const char *data, std::size_t size)
 Write raw bytes into an std::ostream owned by the caller.
void OStreamManip (void *context, std::ostream &(*manip)(std::ostream &))
 Apply an std::ostream manipulator in the caller's module.
template<typename Ptr, typename T>
requires LogPointer<Ptr>
Ptr & operator<< (Ptr &logger, const T &value) noexcept
 Stream a value into a smart pointer to Log or a derived logger.
template<typename Ptr>
requires LogPointer<Ptr>
Ptr & operator<< (Ptr &logger, const Level &level) noexcept
 Stream a Level into a smart pointer to Log or a derived logger.
template<typename Ptr>
requires LogPointer<Ptr>
Ptr & operator<< (Ptr &logger, std::ostream &(*manip)(std::ostream &)) noexcept
 Stream a stream manipulator into a smart pointer to Log or a derived logger.
GroupManip group (const char *name)
 Set the producer group for the current line.
GroupManip group (std::string_view name)
 Set the producer group from a view.
GroupManip group (const StormByte::Safe::String &name)
 Set the producer group from an owned string.
ComponentManip component (const char *name)
 Select the component associated with subsequent log lines on this thread.
ComponentManip component (std::string_view name)
 Select the component from a view.
ComponentManip component (const StormByte::Safe::String &name)
 Select the component from an owned string.
FormatManip push_format (const char *format)
 Save the current format and activate a temporary format.
FormatManip push_format (std::string_view format)
 Save the current format and activate a temporary format from a view.
FormatManip push_format (const StormByte::Safe::String &format)
 Save the current format and activate a temporary format from an owned string.
constexpr RedactManip redact_first (std::size_t n) noexcept
 Build a manipulator that keeps the first n characters visible.
Log & humanreadable_number (Log &log)
 Enable human-readable formatting for numeric values.
Log & humanreadable_bytes (Log &log)
 Enable human-readable formatting for byte counts.
Log & nohumanreadable (Log &log)
 Disable human-readable formatting (raw numbers).
Log & noredact (Log &log)
 Disable redaction until the next redact / redact(n) / redact_first(n).
static constexpr const char * LevelToString (const Level &l) noexcept
 Convert a Level to a short name.

Variables

constexpr ResetComponentManip reset_component {}
 Clear the current thread's component.
constexpr PopComponentManip pop_component {}
 Pop one component segment from the current thread's stack.
constexpr PopFormatManip pop_format {}
 Restore the most recently saved format, or do nothing if empty.
const ColorManip color {}
 Restore the configured color for the current level.
constexpr NoColorManip nocolor {}
 Disable color for subsequent content in the current line.
constexpr RedactManip redact {}
 Full redaction manipulator (mask everything).
constexpr HexManip hex {}
 Enable hex dumps with 16 bytes per row.
constexpr NoHexManip nohex {}
 Disable hex dumps for subsequent payloads.

Detailed Description

Logger module of the StormByte suite.

Typedef Documentation

◆ SinkFunction

Typed text callback whose context is released in its creator module.

◆ SinkManip

using StormByte::Logger::SinkManip = void (*)(void* context, std::ostream& (*manip)(std::ostream&))

Caller-side application of an std::ostream manipulator.

Used for std::endl and any other stream manipulator. The call happens in the module that owns the stream.

◆ SinkWrite

using StormByte::Logger::SinkWrite = void (*)(void* context, const char* data, std::size_t size)

Caller-side write of raw bytes into the sink.

The function runs in the module that created the logger, not in this DLL.

Enumeration Type Documentation

◆ Color

enum class StormByte::Logger::Color : unsigned char
strong

ANSI foreground colors supported by the logger.

Default emits no ANSI sequence and leaves the terminal color unchanged.

Enumerator
Default 

No ANSI sequence; preserve the terminal's current color.

Black 

Standard black foreground.

Red 

Standard red foreground.

Green 

Standard green foreground.

Yellow 

Standard yellow foreground.

Blue 

Standard blue foreground.

Magenta 

Standard magenta foreground.

Cyan 

Standard cyan foreground.

Gray 

Bright black/gray foreground.

White 

Standard white foreground.

BrightBlack 

Bright black foreground.

BrightRed 

Bright red foreground.

BrightGreen 

Bright green foreground.

BrightYellow 

Bright yellow foreground.

BrightBlue 

Bright blue foreground.

BrightMagenta 

Bright magenta foreground.

BrightCyan 

Bright cyan foreground.

BrightWhite 

Bright white foreground.

◆ Level

enum class StormByte::Logger::Level : unsigned short
strong

Severity levels used by the logger.

Ordered from least to most severe. Used both as the print floor and as the level of the current message. Warning, Error and Fatal are always emitted regardless of the configured print floor.

Enumerator
LowLevel 

Verbose diagnostics.

Debug 

Debug information.

Warning 

Recoverable problems.

Notice 

Significant normal events.

Info 

Informational messages.

Error 

Error conditions.

Fatal 

Unrecoverable errors.

◆ ThrottlePolicy

enum class StormByte::Logger::ThrottlePolicy : unsigned char
strong

Count policy applied before the optional rate bucket.

Enumerator
Drop 

Admit while the rate bucket has credit.

Sample 

Admit the first and then one line of every sample period.

Window 

Admit the first WindowKeep lines of every WindowPeriod.

Function Documentation

◆ component() [1/3]

ComponentManip StormByte::Logger::component ( const char * name)
inline

Select the component associated with subsequent log lines on this thread.

Parameters
nameComponent name; empty selects the root component.
Returns
Component manipulator carrying the requested name.
Note
An empty component is allowed for compatibility, but reset_component is preferred when returning to the root component explicitly. A literal binds here. The owned string is built in the caller.

◆ component() [2/3]

ComponentManip StormByte::Logger::component ( const StormByte::Safe::String & name)
inline

Select the component from an owned string.

Parameters
nameComponent name already owned by Base.
Returns
Component manipulator carrying the requested name.

◆ component() [3/3]

ComponentManip StormByte::Logger::component ( std::string_view name)
inline

Select the component from a view.

Parameters
nameComponent name viewed in the caller; copied into an owned String.
Returns
Component manipulator carrying the requested name. std::string binds here. It does not compete with a literal.

◆ group() [1/3]

GroupManip StormByte::Logger::group ( const char * name)
inline

Set the producer group for the current line.

Parameters
nameGroup name, or empty text to clear the group.
Returns
Group manipulator carrying the requested name. A literal binds here. The owned string is built in the caller.

◆ group() [2/3]

GroupManip StormByte::Logger::group ( const StormByte::Safe::String & name)
inline

Set the producer group from an owned string.

Parameters
nameGroup name already owned by Base.
Returns
Group manipulator carrying the requested name.

◆ group() [3/3]

GroupManip StormByte::Logger::group ( std::string_view name)
inline

Set the producer group from a view.

Parameters
nameGroup name viewed in the caller; copied into an owned String.
Returns
Group manipulator carrying the requested name. std::string binds here. It does not compete with a literal.

◆ humanreadable_bytes()

Log & StormByte::Logger::humanreadable_bytes ( Log & log)
noexcept

Enable human-readable formatting for byte counts.

Parameters
logThe Log instance to modify.
Returns
Reference to the same Log.

◆ humanreadable_number()

Log & StormByte::Logger::humanreadable_number ( Log & log)
noexcept

Enable human-readable formatting for numeric values.

Parameters
logThe Log instance to modify.
Returns
Reference to the same Log.

◆ LevelToString()

constexpr const char * StormByte::Logger::LevelToString ( const Level & l)
staticconstexprnoexcept

Convert a Level to a short name.

Parameters
lLevel to convert.
Returns
Name such as "Info" or "Error". A string literal, not an owning string.

◆ nohumanreadable()

Log & StormByte::Logger::nohumanreadable ( Log & log)
noexcept

Disable human-readable formatting (raw numbers).

Parameters
logThe Log instance to modify.
Returns
Reference to the same Log.

◆ noredact()

Log & StormByte::Logger::noredact ( Log & log)
noexcept

Disable redaction until the next redact / redact(n) / redact_first(n).

Parameters
logThe Log instance to modify.
Returns
Reference to the same Log.

◆ operator<<() [1/3]

template<typename Ptr>
requires LogPointer<Ptr>
Ptr & StormByte::Logger::operator<< ( Ptr & logger,
const Level & level )
noexcept

Stream a Level into a smart pointer to Log or a derived logger.

Template Parameters
Ptrstd::shared_ptr, std::unique_ptr, StormByte::Safe::Shared or StormByte::Safe::Unique whose element type derives from Log.
Parameters
loggerSmart pointer to the logger. An empty owner is a no-op.
levelLevel to set.
Returns
Reference to the smart pointer.

◆ operator<<() [2/3]

template<typename Ptr, typename T>
requires LogPointer<Ptr>
Ptr & StormByte::Logger::operator<< ( Ptr & logger,
const T & value )
noexcept

Stream a value into a smart pointer to Log or a derived logger.

Template Parameters
Ptrstd::shared_ptr, std::unique_ptr, StormByte::Safe::Shared or StormByte::Safe::Unique whose element type derives from Log.
TValue type.
Parameters
loggerSmart pointer to the logger. An empty owner is a no-op.
valueValue to stream.
Returns
Reference to the smart pointer.

◆ operator<<() [3/3]

template<typename Ptr>
requires LogPointer<Ptr>
Ptr & StormByte::Logger::operator<< ( Ptr & logger,
std::ostream &(* manip )(std::ostream &) )
noexcept

Stream a stream manipulator into a smart pointer to Log or a derived logger.

A dedicated overload so overloaded manipulators such as std::endl can be resolved.

Template Parameters
Ptrstd::shared_ptr, std::unique_ptr, StormByte::Safe::Shared or StormByte::Safe::Unique whose element type derives from Log.
Parameters
loggerSmart pointer to the logger. An empty owner is a no-op.
manipStream manipulator.
Returns
Reference to the smart pointer.

◆ OStreamManip()

void StormByte::Logger::OStreamManip ( void * context,
std::ostream &(* manip )(std::ostream &) )
inline

Apply an std::ostream manipulator in the caller's module.

Parameters
contextAddress of the caller's std::ostream.
manipManipulator, for example std::endl.

◆ OStreamWrite()

void StormByte::Logger::OStreamWrite ( void * context,
const char * data,
std::size_t size )
inline

Write raw bytes into an std::ostream owned by the caller.

Instantiated in the caller's module. The DLL only stores the function pointer.

Parameters
contextAddress of the caller's std::ostream.
dataBytes to write.
sizeNumber of bytes.

◆ push_format() [1/3]

FormatManip StormByte::Logger::push_format ( const char * format)
inline

Save the current format and activate a temporary format.

Parameters
formatFormat to activate until pop_format is streamed.
Returns
Format manipulator containing the requested format. A literal binds here. The owned string is built in the caller.

◆ push_format() [2/3]

FormatManip StormByte::Logger::push_format ( const StormByte::Safe::String & format)
inline

Save the current format and activate a temporary format from an owned string.

Parameters
formatFormat already owned by Base.
Returns
Format manipulator containing the requested format.

◆ push_format() [3/3]

FormatManip StormByte::Logger::push_format ( std::string_view format)
inline

Save the current format and activate a temporary format from a view.

Parameters
formatFormat viewed in the caller; copied into an owned String.
Returns
Format manipulator containing the requested format. std::string binds here. It does not compete with a literal.

◆ redact_first()

RedactManip StormByte::Logger::redact_first ( std::size_t n)
constexprnoexcept

Build a manipulator that keeps the first n characters visible.

Parameters
nNumber of leading characters to keep unmasked.
Returns
A RedactManip configured for keep-first.

Variable Documentation

◆ color

const ColorManip StormByte::Logger::color {}
inline

Restore the configured color for the current level.

◆ hex

HexManip StormByte::Logger::hex {}
inlineconstexpr

Enable hex dumps with 16 bytes per row.

◆ nocolor

NoColorManip StormByte::Logger::nocolor {}
inlineconstexpr

Disable color for subsequent content in the current line.

◆ nohex

NoHexManip StormByte::Logger::nohex {}
inlineconstexpr

Disable hex dumps for subsequent payloads.

◆ pop_component

PopComponentManip StormByte::Logger::pop_component {}
inlineconstexpr

Pop one component segment from the current thread's stack.

Note
Thread-local; does not affect other threads or Scope facades.

◆ pop_format

PopFormatManip StormByte::Logger::pop_format {}
inlineconstexpr

Restore the most recently saved format, or do nothing if empty.

◆ redact

RedactManip StormByte::Logger::redact {}
inlineconstexpr

Full redaction manipulator (mask everything).

See also
RedactManip

◆ reset_component

ResetComponentManip StormByte::Logger::reset_component {}
inlineconstexpr

Clear the current thread's component.

Note
The reset is thread-local and does not affect other threads.