StormByte::Logger Namespace Reference

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 errors. 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...

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
template<typename Ptr , typename T > requires StormByte::Type::DerivedFrom<typename std::remove_cvref_t<Ptr>::element_type, Log>
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 StormByte::Type::DerivedFrom<typename std::remove_cvref_t<Ptr>::element_type, Log>
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 StormByte::Type::DerivedFrom<typename std::remove_cvref_t<Ptr>::element_type, Log>
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 (std::string name)
	Set the producer group for the current line.
ComponentManip	component (std::string name)
	Select the component associated with subsequent log lines on this thread.
FormatManip	push_format (std::string format)
	Save the current format and activate a temporary format.
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 std::string	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.

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()

ComponentManip StormByte::Logger::component

(

std::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()

GroupManip StormByte::Logger::group

(

std::string

name

)

Set the producer group for the current line.

Parameters

name	Group name, or an empty string 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 std::string 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".

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 StormByte::Type::DerivedFrom<typename std::remove_cvref_t<Ptr>::element_type, Log>

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 or std::unique_ptr whose element type derives from Log.

Parameters

logger	Smart pointer to the logger.
level	Level to set.

Returns

Reference to the smart pointer.

operator<<() [2/3]

template<typename Ptr , typename T >
requires StormByte::Type::DerivedFrom<typename std::remove_cvref_t<Ptr>::element_type, Log>

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 or std::unique_ptr whose element type derives from Log.
T	Value type.

Parameters

logger	Smart pointer to the logger.
value	Value to stream.

Returns

Reference to the smart pointer.

operator<<() [3/3]

template<typename Ptr >
requires StormByte::Type::DerivedFrom<typename std::remove_cvref_t<Ptr>::element_type, Log>

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.

Template Parameters

Ptr	std::shared_ptr or std::unique_ptr whose element type derives from Log.

Parameters

logger	Smart pointer to the logger.
manip	Stream manipulator (e.g. std::endl).

Returns

Reference to the smart pointer.

push_format()

FormatManip StormByte::Logger::push_format

(

std::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.