Logger module of the StormByte suite. More...

Classes
struct	ColorManip
	Temporarily selects a configured or explicit content color. More...

struct	ComponentManip
	Selects the sticky component for the current thread. More...

class	Exception
	Root exception for Logger. More...

struct	FormatManip
	Temporarily replaces the logger format and saves the previous one. More...

struct	GroupManip
	Labels the current logging line with a producer group. More...

struct	HexManip
	Dump subsequent payloads as hex bytes until nohex. More...

class	Log
	Public streaming facade for the StormByte logger. More...

struct	NoColorManip
	Disables color for subsequent content until changed. More...

struct	NoHexManip
	Disable hex dumps and restore default payload formatting. More...

struct	PopComponentManip
	Pops one segment from the current thread's component stack. More...

struct	PopFormatManip
	Restores the most recently saved logger format. More...

struct	RedactManip
	Stateful redaction manipulator. More...

struct	ResetComponentManip
	Clears the component associated with the current thread. More...

class	ThreadedLog
	Thread-safe logging facade. More...

class	ThrottleError
	Thrown when a throttle rule is invalid. More...

struct	ThrottleSpec
	Immutable rule description used by Log::Throttle. 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.

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 (StormByte::String::String name)
	Set the producer group for the current line.

GroupManip	group (std::string_view name)
	Set the producer group from caller-owned text.

ComponentManip	component (StormByte::String::String name)
	Select the component associated with subsequent log lines on this thread.

ComponentManip	component (std::string_view name)
	Select the component from caller-owned text.

FormatManip	push_format (StormByte::String::String 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 caller-owned text.

constexpr RedactManip	redact_first (std::size_t n) noexcept
	Build a manipulator that keeps the first `n` characters visible.

Log &	humanreadable_number (Log &log) noexcept
	Enable human-readable formatting for numeric values.

Log &	humanreadable_bytes (Log &log) noexcept
	Enable human-readable formatting for byte counts.

Log &	nohumanreadable (Log &log) noexcept
	Disable human-readable formatting (raw numbers).

Log &	noredact (Log &log) noexcept
	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.

constexpr 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

◆ SinkManip

using StormByte::Logger::SinkManip = typedef 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 = typedef 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/2]

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

inline

Select the component from caller-owned text.

Parameters

name	Component name viewed in the caller; copied into an owned String.

Returns: Component manipulator carrying the requested name.

◆ component() [2/2]

ComponentManip StormByte::Logger::component ( StormByte::String::String name )

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

Parameters

name	Component 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.

◆ group() [1/2]

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

inline

Set the producer group from caller-owned text.

Parameters

name	Group name viewed in the caller; copied into an owned String.

Returns: Group manipulator carrying the requested name.

◆ group() [2/2]

GroupManip StormByte::Logger::group ( StormByte::String::String name )

Set the producer group for the current line.

Parameters

name	Group name, or empty text to clear the group.

Returns: Group manipulator carrying the requested name.

◆ humanreadable_bytes()

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

noexcept

Enable human-readable formatting for byte counts.

Parameters

log	The 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

log	The Log instance to modify.

Returns: Reference to the same Log.

◆ LevelToString()

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

staticconstexprnoexcept

Convert a Level to a short name.

Parameters

l	Level 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

log	The 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

log	The 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

Ptr	`std::shared_ptr`, `std::unique_ptr`, StormByte::Shared or StormByte::Unique whose element type derives from Log.

Parameters

logger	Smart pointer to the logger. An empty owner is a no-op.
level	Level 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

Ptr	`std::shared_ptr`, `std::unique_ptr`, StormByte::Shared or StormByte::Unique whose element type derives from Log.
T	Value type.

Parameters

logger	Smart pointer to the logger. An empty owner is a no-op.
value	Value 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 &(*)(std::ostream &)	manip
	)

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

Ptr	`std::shared_ptr`, `std::unique_ptr`, StormByte::Shared or StormByte::Unique whose element type derives from Log.

Parameters

logger	Smart pointer to the logger. An empty owner is a no-op.
manip	Stream manipulator.

Returns: Reference to the smart pointer.

◆ OStreamManip()

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

inline

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

Parameters

context	Address of the caller's `std::ostream`.
manip	Manipulator, 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

context	Address of the caller's `std::ostream`.
data	Bytes to write.
size	Number of bytes.

◆ push_format() [1/2]

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

inline

Save the current format and activate a temporary format from caller-owned text.

Parameters

format Format viewed in the caller; copied into an owned String.

Returns: Format manipulator containing the requested format.

◆ push_format() [2/2]

FormatManip StormByte::Logger::push_format ( StormByte::String::String format )

Save the current format and activate a temporary format.

Parameters

format Format to activate until pop_format is streamed.

Returns: Format manipulator containing the requested format.

◆ redact_first()

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

constexprnoexcept

Build a manipulator that keeps the first n characters visible.

Parameters

n	Number of leading characters to keep unmasked.

Returns: A RedactManip configured for keep-first.

Variable Documentation

◆ color

constexpr ColorManip StormByte::Logger::color {}

inlineconstexpr

Restore the configured color for the current level.

◆ hex

constexpr HexManip StormByte::Logger::hex {}

inlineconstexpr

Enable hex dumps with 16 bytes per row.

◆ nocolor

constexpr NoColorManip StormByte::Logger::nocolor {}

inlineconstexpr

Disable color for subsequent content in the current line.

◆ nohex

constexpr NoHexManip StormByte::Logger::nohex {}

inlineconstexpr

Disable hex dumps for subsequent payloads.

◆ pop_component

constexpr 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

constexpr PopFormatManip StormByte::Logger::pop_format {}

inlineconstexpr

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

◆ redact

constexpr RedactManip StormByte::Logger::redact {}

inlineconstexpr

Full redaction manipulator (mask everything).

See also: RedactManip

◆ reset_component

constexpr ResetComponentManip StormByte::Logger::reset_component {}

inlineconstexpr

Clear the current thread's component.

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

Classes

Concepts

Typedefs

Enumerations

Functions

Variables

Detailed Description

Typedef Documentation

◆ SinkManip

◆ SinkWrite

Enumeration Type Documentation

◆ Color

◆ Level

◆ ThrottlePolicy

Function Documentation

◆ component() [1/2]

◆ component() [2/2]

◆ group() [1/2]

◆ group() [2/2]

◆ humanreadable_bytes()

◆ humanreadable_number()

◆ LevelToString()

◆ nohumanreadable()

◆ noredact()

◆ operator<<() [1/3]

◆ operator<<() [2/3]

◆ operator<<() [3/3]

◆ OStreamManip()

◆ OStreamWrite()

◆ push_format() [1/2]

◆ push_format() [2/2]

◆ redact_first()

Variable Documentation

◆ color

◆ hex

◆ nocolor

◆ nohex

◆ pop_component

◆ pop_format

◆ redact

◆ reset_component