Logging

The log domain provides bounded background logging through erbsland::log::LogManager and lightweight, hierarchical erbsland::log::LogStream producer endpoints. Entries keep their UTC creation time and sanitized message, while routing, line formatting, and output happen on the manager’s private event loop. Queued entries and formatted lines use shared immutable pointers. Writer batches therefore move and copy only pointer values, and a custom writer can safely retain an item beyond the batch call by copying its shared pointer.

Configuration and Routing

erbsland::log::LogConfiguration combines line formatting, queue limits, enabled trace sections, and writer routes. Each route filters complete path segments and levels. Replacing a configuration is a synchronous barrier; streams update their cached trace flag before the call returns. erbsland::log::LogConfigurationParser validates any selected ELCL document branch with one shared compiled ruleset and creates the corresponding built-in writers.

Writers

The console writer renders one styled paragraph directly through a terminal. The manager delivers same-configuration entries to writers in bounded batches. Custom writers can override batch delivery to amortize target checks while retaining the single-entry method as their compatibility baseline. The file writer uses ordinary path and stream APIs, checks file identity once per batch, detects external replacement, and supports time- or size-based rotation. The syslog writer emits RFC 5424 over UDP, RFC 6587 octet-counted TCP, or TLS using the log/syslog configuration label. The last-errors writer retains a bounded FIFO snapshot of error entries.

Interface

class ConsoleLogWriterOptions

Style and wrapping settings for console log output.

Public Functions

ConsoleLogWriterOptions(): Create default console styling and paragraph settings.

inline const cterm::ParagraphOptions &paragraphOptions() const noexcept: Access the paragraph layout settings.

ConsoleLogWriterOptions &setParagraphOptions(cterm::ParagraphOptions value) noexcept

Set the paragraph layout settings.

Parameters:: value – The complete paragraph options passed to the terminal.
Returns:: These options for chained configuration.

inline cterm::BlockStyle baseLineStyle() const noexcept: Get the base style applied to each line.

ConsoleLogWriterOptions &setBaseLineStyle(cterm::BlockStyle style) noexcept

Set the base style applied to each line.

Parameters:: style – The style applied before level and semantic-part styles.
Returns:: These options for chained configuration.

cterm::BlockStyle lineStyle(LogLevel level) const noexcept

Get the additional line style for a severity level.

Parameters:: level – The severity whose line style shall be returned.
Returns:: The additional style applied to complete lines of level.

ConsoleLogWriterOptions &setLineStyle(LogLevel level, cterm::BlockStyle style) noexcept

Set the additional line style for a severity level.

Parameters:

level – The severity whose line style shall be changed.
style – The additional style applied after the base line style.

Returns:

These options for chained configuration.

cterm::BlockStyle partStyle(LogLinePart part, LogLevel level) const noexcept

Get the effective semantic-part style for a severity level.

Parameters:

part – The semantic line part whose style shall be resolved.
level – The entry severity whose overrides shall be included.

Returns:

The merged base-part and part-level style.

ConsoleLogWriterOptions &setPartStyle(LogLinePart part, cterm::BlockStyle style) noexcept

Set the base style for a semantic line part.

Parameters:

part – The semantic line part whose base style shall be changed.
style – The style applied after complete-line styles.

Returns:

These options for chained configuration.

ConsoleLogWriterOptions &setPartStyle(LogLinePart part, LogLevel level, cterm::BlockStyle style) noexcept

Set the additional style for a semantic part and severity level.

Parameters:

part – The semantic line part whose level override shall be changed.
level – The severity selecting the override.
style – The final style applied after all base styles.

Returns:

These options for chained configuration.

class FileLogWriterOptions

Settings for a resilient file log writer.

Public Functions

inline explicit FileLogWriterOptions(path::Path path)

Create options for the given base path.

Parameters:: path – The active log-file path from which archive names are derived.

inline const path::Path &path() const noexcept: Get the configured base path.

inline LogFileMode mode() const noexcept: Get the initial open mode.

FileLogWriterOptions &setMode(LogFileMode value) noexcept

Set the initial open mode.

Parameters:: value – Whether the first open preserves or replaces existing content.
Returns:: These options for chained configuration.

inline LogFileRotation rotation() const noexcept: Get the rotation rule.

FileLogWriterOptions &setRotation(LogFileRotation value) noexcept

Set the rotation rule.

Parameters:: value – The schedule or size rule selecting rotation.
Returns:: These options for chained configuration.

inline unit::ByteLength maximumSize() const noexcept: Get the file-size rotation threshold.

FileLogWriterOptions &setMaximumSize(unit::ByteLength value) noexcept

Set the file-size rotation threshold.

Parameters:: value – The maximum active-file size before rotation.
Returns:: These options for chained configuration.

inline std::size_t retention() const noexcept: Get the maximum number of retained archives.

FileLogWriterOptions &setRetention(std::size_t value) noexcept

Set the maximum number of retained archives.

Parameters:: value – The archive count to retain; zero removes every rotated archive.
Returns:: These options for chained configuration.

class LogLine

A formatted log line with semantic segments for styled writers.

Public Functions

LogLine() = default: Create an empty formatted line.

explicit LogLine(std::vector<LogLineSegment> segments)

Create a line from ordered semantic segments.

Parameters:: segments – The rendered segments in output order.

inline const text::String &text() const noexcept: Get the complete rendered text.

inline const std::vector<LogLineSegment> &segments() const noexcept: Get the ordered semantic segments.

using erbsland::log::LogLinePtr = std::shared_ptr<LogLine>: Shared pointer to a mutable formatted log line.

using erbsland::log::LogLineConstPtr = std::shared_ptr<const LogLine>: Shared pointer to an immutable formatted log line.

class LogLinePart

The semantic role of a formatted line segment.

Public Types

enum Value

The raw line-part value.

Values:

enumerator Literal: Literal text from the format pattern.

enumerator Time: Rendered timestamp.

enumerator Level: Rendered severity level.

enumerator Name: Rendered stream path.

enumerator Message: Rendered message.

enumerator _Count: Number of semantic parts.

Public Functions

constexpr LogLinePart() noexcept = default: Create the default literal part.

inline constexpr LogLinePart(const Value value) noexcept

Create a line part from its raw value.

Parameters:: value – The raw semantic-part value.

inline constexpr Value toRawValue() const noexcept

Get the raw semantic-part value.

Returns:: The embedded value.

text::String toString() const

Convert this part to its placeholder identifier.

Returns:: The lowercase placeholder name, or an empty string for a literal or invalid part.

Public Static Functions

static std::optional<LogLinePart> fromString(const text::String &text) noexcept

Parse a placeholder identifier.

Parameters:: text – The placeholder name without braces.
Returns:: The corresponding semantic part, or an empty optional if the name is unknown.

static LogLinePart fromStringOrThrow(const text::String &text)

Parse a placeholder identifier.

Parameters:: text – The placeholder name without braces.
Throws:: err::ParseError – If the placeholder name is unknown.
Returns:: The corresponding semantic part.

struct LogLineSegment

One semantic segment of a formatted line.

Public Members

LogLinePart part = {LogLinePart::Literal}: Semantic role of this segment.

text::String text: Rendered segment text.

class LogConfiguration

A complete immutable-by-snapshot manager configuration.

Public Functions

LogConfiguration() = default: Create a configuration without writer routes.

inline const LogLineFormat &lineFormat() const noexcept: Access the line-format settings.

LogConfiguration &setLineFormat(LogLineFormat value) noexcept

Replace the line-format settings.

Parameters:: value – The shared formatting settings used by every writer route.
Returns:: This configuration for chained option construction.

inline const LogManagerOptions &managerOptions() const noexcept: Access the manager resource limits.

LogConfiguration &setManagerOptions(LogManagerOptions value)

Validate and replace the manager resource limits.

Parameters:: value – The complete manager limits to validate and store.
Returns:: This configuration for chained option construction.

inline std::size_t writerCount() const noexcept

Get the number of configured writer routes.

Returns:: The number of writer and filter pairs in this configuration.

LogConfiguration &addWriter(LogWriterPtr writer, LogWriterFilter filter = {})

Add a writer route.

Parameters:

writer – The writer instance receiving accepted entries.
filter – The level and path filter evaluated before delivery.

Returns:

This configuration for chained route construction.

inline const std::vector<LogTraceSection> &traceSections() const noexcept: Access explicitly enabled trace sections.

LogConfiguration &enableTraceSection(LogTraceSection section)

Enable a trace section.

Parameters:: section – The case-sensitive trace section to enable.
Returns:: This configuration for chained option construction.

bool isTraceSectionEnabled(const LogTraceSection &section) const noexcept

Test whether the given trace section is enabled.

Parameters:: section – The trace section to look up.
Returns:: true if the section is present in the enabled-section list.

bool acceptsTrace(const LogPath &path, const LogTraceSection &section) const noexcept

Test whether a trace entry would be accepted by any route.

Parameters:

path – The path of the stream being evaluated.
section – The optional trace section of the stream.

Returns:

true if the section is enabled when named and at least one route accepts trace for path.

class LogConfigurationParser

Parse and validate a logging configuration from any selected ELCL branch.

Public Functions

inline explicit LogConfigurationParser(cterm::TerminalPtr terminal = {}) noexcept

Create a parser with an optional terminal for console-writer configuration.

Parameters:: terminal – The terminal used by configured console writers, or empty to reject console writers.

LogConfiguration parse(const conf::ValuePtr &sectionValue) const

Validate and parse one document or section branch.

Parameters:: sectionValue – The selected ELCL section containing logging configuration values.
Throws:: conf::ConfError – If the selected branch fails the compiled validation rules.
Returns:: A complete configuration with newly constructed built-in writers.

Public Static Functions

static const conf::vr::RulesPtr &validationRules()

Access the compiled validation rules shared by all parser instances.

Returns:: The immutable compiled rules for a selected logging configuration branch.

static conf::Integer version(): Get the current version of the log configuration format.

class LogEntry

One immutable log entry created by a producer.

Public Functions

LogEntry(uint64_t sequence, time::DateTime timestamp, LogLevel level, LogPath path, text::String message, bool truncated = false)

Create an immutable entry from producer-captured values.

Parameters:

sequence – The monotonically increasing sequence assigned by the manager.
timestamp – The UTC timestamp captured before formatting the producer message.
level – The severity selected by the producer.
path – The path of the producing stream.
message – The sanitized message text.
truncated – Whether the producer-side message-size limit truncated the message.

inline uint64_t sequence() const noexcept: Get the manager-assigned sequence number.

inline const time::DateTime &timestamp() const noexcept: Get the retained UTC creation timestamp.

inline LogLevel level() const noexcept: Get the entry severity level.

inline const LogPath &path() const noexcept: Get the producing stream path.

inline const text::String &message() const noexcept: Get the sanitized message text.

inline bool isTruncated() const noexcept: Test whether the producer-side size limit truncated the message.

using erbsland::log::LogEntryPtr = std::shared_ptr<LogEntry>: Shared pointer to a mutable log entry.

using erbsland::log::LogEntryConstPtr = std::shared_ptr<const LogEntry>: Shared pointer to an immutable log entry.

class LogFileMode

The mode used when initially opening a log file.

Public Types

enum Value

The raw file mode value.

Values:

enumerator Overwrite: Replace existing file content when first opened.

enumerator Append: Preserve existing file content when first opened.

Public Functions

constexpr LogFileMode() noexcept = default: Create the default append mode.

inline constexpr LogFileMode(const Value value) noexcept

Create a mode from its raw value.

Parameters:: value – The raw file mode value.

inline constexpr Value toRawValue() const noexcept

Get the raw file mode value.

Returns:: The embedded value.

text::String toString() const

Convert this mode to its canonical configuration identifier.

Returns:: overwrite or append.

Public Static Functions

static text::StringList allStrings()

Get all canonical configuration identifiers.

Returns:: The identifiers accepted by fromString(), irrespective of ASCII letter case.

static std::optional<LogFileMode> fromString(const text::String &text) noexcept

Parse a canonical file mode identifier case-insensitively using ASCII folding.

Parameters:: text – The identifier to parse.
Returns:: The parsed mode, or an empty optional if the identifier is unknown.

static LogFileMode fromStringOrThrow(const text::String &text)

Parse a canonical file mode identifier.

Parameters:: text – The identifier to parse.
Throws:: err::ParseError – If the identifier is unknown.
Returns:: The parsed mode.

class LogFileRotation

The rotation schedule used for a log file.

Public Types

enum Value

The raw rotation value.

Values:

enumerator None: Never rotate the file.

enumerator Hourly: Rotate when the entry’s UTC hour changes.

enumerator Daily: Rotate when the entry’s UTC calendar day changes.

enumerator Weekly: Rotate when the entry’s UTC calendar week changes.

enumerator Size: Rotate before the configured size would be exceeded.

Public Functions

constexpr LogFileRotation() noexcept = default: Create the default no-rotation value.

inline constexpr LogFileRotation(const Value value) noexcept

Create a rotation mode from its raw value.

Parameters:: value – The raw rotation value.

inline constexpr Value toRawValue() const noexcept

Get the raw rotation value.

Returns:: The embedded value.

text::String toString() const

Convert this rotation mode to its canonical configuration identifier.

Returns:: The lowercase rotation identifier.

Public Static Functions

static text::StringList allStrings()

Get all canonical configuration identifiers.

Returns:: The identifiers accepted by fromString(), irrespective of ASCII letter case.

static std::optional<LogFileRotation> fromString(const text::String &text) noexcept

Parse a canonical rotation identifier case-insensitively using ASCII folding.

Parameters:: text – The identifier to parse.
Returns:: The parsed rotation, or an empty optional if the identifier is unknown.

static LogFileRotation fromStringOrThrow(const text::String &text)

Parse a canonical rotation identifier.

Parameters:: text – The identifier to parse.
Throws:: err::ParseError – If the identifier is unknown.
Returns:: The parsed rotation.

class LogLevel

The severity of a log entry.

Public Types

enum class Value : uint8_t

The raw severity value and flag bit.

Values:

enumerator Trace: Detailed diagnostics disabled by default.

enumerator Information: Normal application progress and state.

enumerator Warning: A recoverable problem or unexpected condition.

enumerator Error: An operation failure requiring attention.

enumerator All: All available severity levels.

Public Functions

constexpr LogLevel() noexcept = default: Create the default information level.

inline constexpr LogLevel(const Value value) noexcept

Create a level from its raw value.

Parameters:: value – The raw severity value.

inline constexpr Value toRawValue() const noexcept

Get the raw severity value.

Returns:: The embedded value.

text::String toString() const

Convert this level to its canonical configuration identifier.

Returns:: The full lowercase severity identifier.

text::String toString(LogLevelFormat format) const

Render this level using a configured spelling and case.

Parameters:: format – The desired level representation.
Returns:: The rendered severity text, or unknown for an invalid value.

Public Static Functions

static text::StringList allStrings()

Get all supported configuration identifiers, including aliases.

Returns:: The identifiers accepted by fromString(), irrespective of ASCII letter case.

static std::optional<LogLevel> fromString(const text::String &text) noexcept

Parse a severity identifier case-insensitively using ASCII folding.

The aliases info and warn are accepted in addition to canonical identifiers.

Parameters:: text – The identifier to parse.
Returns:: The parsed level, or an empty optional if the identifier is unknown.

static LogLevel fromStringOrThrow(const text::String &text)

Parse a severity identifier.

Parameters:: text – The identifier to parse.
Throws:: err::ParseError – If the identifier is unknown.
Returns:: The parsed level.

Public Static Attributes

static constexpr auto Trace = Value::Trace : Detailed diagnostics disabled by default.

static constexpr auto Information = Value::Information : Normal application progress and state.

static constexpr auto Warning = Value::Warning : A recoverable problem or unexpected condition.

static constexpr auto Error = Value::Error : An operation failure requiring attention.

static constexpr auto All = Value::All : All available severity levels.

using erbsland::log::LogLevels = util::EnumFlags<LogLevel::Value>: A set of log severity levels.

class LogLevelFormat

The spelling and case used for a rendered level.

Public Types

enum Value

The raw level-format value.

Values:

enumerator ThreeLetterUpper: Three uppercase letters.

enumerator ShortLower: Three lowercase letters.

enumerator FullLower: Full lowercase name.

enumerator FullUpper: Full uppercase name.

Public Functions

constexpr LogLevelFormat() noexcept = default: Create the default three-letter uppercase format.

inline constexpr LogLevelFormat(const Value value) noexcept

Create a level format from its raw value.

Parameters:: value – The raw level-format value.

inline constexpr Value toRawValue() const noexcept

Get the raw level-format value.

Returns:: The embedded value.

text::String toString() const

Convert this format to its canonical configuration identifier.

Returns:: The lowercase format identifier.

Public Static Functions

static text::StringList allStrings()

Get all canonical configuration identifiers.

Returns:: The identifiers accepted by fromString(), irrespective of ASCII letter case.

static std::optional<LogLevelFormat> fromString(const text::String &text) noexcept

Parse a canonical level-format identifier case-insensitively using ASCII folding.

Parameters:: text – The identifier to parse.
Returns:: The parsed format, or an empty optional if the identifier is unknown.

static LogLevelFormat fromStringOrThrow(const text::String &text)

Parse a canonical level-format identifier.

Parameters:: text – The identifier to parse.
Throws:: err::ParseError – If the identifier is unknown.
Returns:: The parsed format.

class LogLineFormat

Formatting settings shared by log writers.

Public Functions

LogLineFormat(): Create the default {time} {level} - {message} format.

inline const text::String &pattern() const noexcept: Get the placeholder pattern.

LogLineFormat &setPattern(text::String value)

Validate and set the placeholder pattern.

Parameters:: value – The pattern containing literals, escaped braces, and supported placeholders.
Returns:: These settings for chained configuration.

inline LogTimestampZone timestampZone() const noexcept: Get the timestamp rendering zone.

LogLineFormat &setTimestampZone(LogTimestampZone value) noexcept

Set the timestamp rendering zone.

Parameters:: value – The zone used only while formatting retained UTC timestamps.
Returns:: These settings for chained configuration.

inline LogLevelFormat levelFormat() const noexcept: Get the severity-level representation.

LogLineFormat &setLevelFormat(LogLevelFormat value) noexcept

Set the severity-level representation.

Parameters:: value – The spelling and case used for rendered levels.
Returns:: These settings for chained configuration.

inline LogNameFormat nameFormat() const noexcept: Get the stream-name representation.

LogLineFormat &setNameFormat(LogNameFormat value) noexcept

Set the stream-name representation.

Parameters:: value – The representation used for hierarchical stream paths.
Returns:: These settings for chained configuration.

inline unit::CpLength nameLimit() const noexcept: Get the character limit for left-truncated names.

LogLineFormat &setNameLimit(unit::CpLength value) noexcept

Set the character limit for left-truncated names.

Parameters:: value – The maximum code-point count when LogNameFormat::LeftTruncated is selected.
Returns:: These settings for chained configuration.

inline LogMessageTruncation messageTruncation() const noexcept: Get the message-truncation rule.

LogLineFormat &setMessageTruncation(LogMessageTruncation value) noexcept

Set the message-truncation rule.

Parameters:: value – The rendering-time truncation rule to apply.
Returns:: These settings for chained configuration.

inline unit::CpLength messageLimit() const noexcept: Get the configured message or total-line character limit.

LogLineFormat &setMessageLimit(unit::CpLength value) noexcept

Set the message or total-line character limit.

Parameters:: value – The code-point limit used by the selected truncation rule.
Returns:: These settings for chained configuration.

inline const text::String &truncationMark() const noexcept: Get the mark appended to truncated text.

LogLineFormat &setTruncationMark(text::String value) noexcept

Set the mark appended to truncated text.

Parameters:: value – The marker appended after rendering-time truncation.
Returns:: These settings for chained configuration.

class LogManager

Background logging manager.

Public Functions

explicit LogManager(LogManagerOptions options, PrivateTag)

Internal constructor used by create().

Parameters:: options – The validated queue and shutdown limits for the manager.

~LogManager(): Shut down the worker during destruction.

const LogStreamPtr &rootStream() const noexcept: Access the root producer stream.

LogStreamPtr createStream(LogPath path, LogTraceSection traceSection = {})

Create a stream for a validated path.

Parameters:

path – The validated hierarchical path for the stream.
traceSection – The optional trace section controlling trace emission.

Returns:

A new lightweight producer stream owned independently of the manager.

LogStreamPtr createStream(const text::String &path, LogTraceSection traceSection = {})

Validate a path and create its stream.

Parameters:

path – The lowercase ASCII slash-delimited stream path.
traceSection – The optional trace section controlling trace emission.

Returns:

A new lightweight producer stream owned independently of the manager.

void setConfiguration(LogConfiguration configuration)

Synchronously replace the active configuration.

Entries already inside a writer complete with the old configuration. Queued entries use the replacement.

Parameters:: configuration – The complete replacement configuration.
Throws:: err::LogicError – If shutdown started or a writer is active in another manager.

LogConfiguration configuration() const

Copy the active configuration snapshot.

Returns:: A copy of the configuration currently used by the worker.

void pause() noexcept: Pause ordinary worker draining while retaining queued entries.

void resume() noexcept: Resume worker draining.

void shutdown() noexcept: Gracefully stop the worker within the configured deadline.

LogManagerStatistics statistics() const noexcept

Read a point-in-time statistics snapshot.

Returns:: The counters accumulated by the manager at the time of the call.

Public Static Functions

static LogManagerPtr create(LogManagerOptions options = {})

Create and start a shared logging manager.

Parameters:: options – The queue, message, and shutdown limits to use.
Returns:: A running manager with a root stream and no writer routes.

class LogManagerOptions

Resource limits for a log manager.

Public Functions

inline std::size_t maximumEntries() const noexcept

Get the maximum number of queued entries.

Returns:: The complete entry capacity including reserved entries.

LogManagerOptions &setMaximumEntries(std::size_t value)

Set the maximum number of queued entries.

Parameters:: value – The positive complete entry capacity.
Returns:: These options for chained configuration.

inline unit::ByteLength maximumBytes() const noexcept

Get the maximum number of bytes retained in the queue.

Returns:: The complete byte capacity including reserved bytes.

LogManagerOptions &setMaximumBytes(unit::ByteLength value)

Set the maximum number of bytes retained in the queue.

Parameters:: value – The positive complete byte capacity.
Returns:: These options for chained configuration.

inline std::size_t reservedErrorEntries() const noexcept

Get the entry slots reserved for warning and error entries.

Returns:: The reserved entry capacity.

LogManagerOptions &setReservedErrorEntries(std::size_t value) noexcept

Set the entry slots reserved for warning and error entries.

Parameters:: value – The reserved entry capacity, which must not exceed maximumEntries() when installed.
Returns:: These options for chained configuration.

inline unit::ByteLength reservedErrorBytes() const noexcept

Get the bytes reserved for warning and error entries.

Returns:: The reserved byte capacity.

LogManagerOptions &setReservedErrorBytes(unit::ByteLength value) noexcept

Set the bytes reserved for warning and error entries.

Parameters:: value – The reserved bytes, which must not exceed maximumBytes() when installed.
Returns:: These options for chained configuration.

inline unit::ByteLength maximumMessageBytes() const noexcept

Get the maximum sanitized size of one message.

Returns:: The positive producer-side message limit.

LogManagerOptions &setMaximumMessageBytes(unit::ByteLength value)

Set the maximum sanitized size of one message.

Parameters:: value – The positive producer-side message limit.
Returns:: These options for chained configuration.

inline time::TimeDelta shutdownTimeout() const noexcept

Get the graceful shutdown deadline.

Returns:: The positive duration available for draining queued entries.

LogManagerOptions &setShutdownTimeout(time::TimeDelta value)

Set the graceful shutdown deadline.

Parameters:: value – The positive duration available for draining queued entries.
Returns:: These options for chained configuration.

struct LogManagerStatistics

A point-in-time snapshot of manager counters.

Public Members

uint64_t acceptedEntries = {}: Number of entries accepted into the queue.

uint64_t writtenEntries = {}: Number of entries delivered to at least one writer.

uint64_t droppedEntries = {}: Number of entries discarded due to limits or shutdown.

uint64_t writerFailures = {}: Number of contained writer failures.

std::size_t queuedEntries = {}: Current number of queued entries.

unit::ByteLength queuedBytes = {}: Current message bytes retained in the queue.

class LogMessageTruncation

The rule used to limit rendered message text.

Public Types

enum Value

The raw message-truncation value.

Values:

enumerator None: Do not truncate while rendering.

enumerator FirstLine: Keep only the first message line.

enumerator CharacterCount: Limit the message by character count.

enumerator TotalLineLength: Limit the complete formatted line length.

Public Functions

constexpr LogMessageTruncation() noexcept = default: Create the default no-truncation rule.

inline constexpr LogMessageTruncation(const Value value) noexcept

Create a truncation rule from its raw value.

Parameters:: value – The raw message-truncation value.

inline constexpr Value toRawValue() const noexcept

Get the raw message-truncation value.

Returns:: The embedded value.

text::String toString() const

Convert this rule to its canonical configuration identifier.

Returns:: The lowercase truncation identifier.

Public Static Functions

static text::StringList allStrings()

Get all canonical configuration identifiers.

Returns:: The identifiers accepted by fromString(), irrespective of ASCII letter case.

static std::optional<LogMessageTruncation> fromString(const text::String &text) noexcept

Parse a canonical message-truncation identifier case-insensitively using ASCII folding.

Parameters:: text – The identifier to parse.
Returns:: The parsed rule, or an empty optional if the identifier is unknown.

static LogMessageTruncation fromStringOrThrow(const text::String &text)

Parse a canonical message-truncation identifier.

Parameters:: text – The identifier to parse.
Throws:: err::ParseError – If the identifier is unknown.
Returns:: The parsed rule.

class LogNameFormat

The representation used for a rendered stream name.

Public Types

enum Value

The raw name-format value.

Values:

enumerator Full: The complete hierarchical path.

enumerator Leaf: Only the final path segment.

enumerator HeadAndLeaf: The first and final path segments.

enumerator LeftTruncated: The full path truncated on its left side.

Public Functions

constexpr LogNameFormat() noexcept = default: Create the default full-name format.

inline constexpr LogNameFormat(const Value value) noexcept

Create a name format from its raw value.

Parameters:: value – The raw name-format value.

inline constexpr Value toRawValue() const noexcept

Get the raw name-format value.

Returns:: The embedded value.

text::String toString() const

Convert this format to its canonical configuration identifier.

Returns:: The lowercase format identifier.

Public Static Functions

static text::StringList allStrings()

Get all canonical configuration identifiers.

Returns:: The identifiers accepted by fromString(), irrespective of ASCII letter case.

static std::optional<LogNameFormat> fromString(const text::String &text) noexcept

Parse a canonical name-format identifier case-insensitively using ASCII folding.

Parameters:: text – The identifier to parse.
Returns:: The parsed format, or an empty optional if the identifier is unknown.

static LogNameFormat fromStringOrThrow(const text::String &text)

Parse a canonical name-format identifier.

Parameters:: text – The identifier to parse.
Throws:: err::ParseError – If the identifier is unknown.
Returns:: The parsed format.

class LogPath

A validated hierarchical log path.

Public Functions

LogPath() = default: Create the root path.

explicit LogPath(const text::String &value)

Validate and create a path.

Parameters:: value – The lowercase ASCII slash-delimited path, or an empty string for the root path.
Throws:: err::ParameterError – If the path does not follow the log-path syntax.

inline bool isRoot() const noexcept: Test whether this is the root path.

inline const text::String &value() const noexcept: Get the canonical slash-delimited path value.

inline text::String toString() const noexcept: Convert this path to its canonical string representation.

bool contains(const LogPath &other) const noexcept

Test if this path is an equal or ancestor path of other.

Parameters:: other – The path to test against this path.
Returns:: true if this path contains other by complete path segments.

class LogStream

A lightweight producer endpoint for one hierarchical log path.

Public Functions

LogStream(LogPath path, LogTraceSection traceSection, impl::LogManagerDataWeakPtr manager, PrivateTag)

Internal constructor used by the manager.

Parameters:

path – The validated path represented by this stream.
traceSection – The optional trace configuration section.
manager – Weak ownership of the manager receiving entries.

inline const LogPath &path() const noexcept: Access the stream path.

inline const LogTraceSection &traceSection() const noexcept: Access the optional trace section.

inline bool traceEnabled() const noexcept: Read the cached trace-enabled flag with one atomic operation.

template<typename ...tArgs> inline void trace(const tArgs&... args)

Emit a trace entry when tracing is currently enabled.

Parameters:: args – Printable values passed in order to the text-print system.

template<typename ...tArgs> inline void info(const tArgs&... args)

Emit an informational entry.

Parameters:: args – Printable values passed in order to the text-print system.

template<typename ...tArgs> inline void warn(const tArgs&... args)

Emit a warning entry.

Parameters:: args – Printable values passed in order to the text-print system.

template<typename ...tArgs> inline void error(const tArgs&... args)

Emit an error entry.

Parameters:: args – Printable values passed in order to the text-print system.

Public Static Functions

static LogStreamPtr createMuted()

Create a muted log stream.

Can be used to effectively discard any log messages of a component.

class LogTimestampZone

The time zone used when rendering an entry timestamp.

Public Types

enum Value

The raw timestamp-zone value.

Values:

enumerator Utc: Render the retained UTC timestamp.

enumerator Local: Convert to the local time zone while rendering.

Public Functions

constexpr LogTimestampZone() noexcept = default: Create the default UTC timestamp zone.

inline constexpr LogTimestampZone(const Value value) noexcept

Create a timestamp zone from its raw value.

Parameters:: value – The raw timestamp-zone value.

inline constexpr Value toRawValue() const noexcept

Get the raw timestamp-zone value.

Returns:: The embedded value.

text::String toString() const

Convert this zone to its canonical configuration identifier.

Returns:: utc or local.

Public Static Functions

static text::StringList allStrings()

Get all canonical configuration identifiers.

Returns:: The identifiers accepted by fromString(), irrespective of ASCII letter case.

static std::optional<LogTimestampZone> fromString(const text::String &text) noexcept

Parse a canonical timestamp-zone identifier case-insensitively using ASCII folding.

Parameters:: text – The identifier to parse.
Returns:: The parsed zone, or an empty optional if the identifier is unknown.

static LogTimestampZone fromStringOrThrow(const text::String &text)

Parse a canonical timestamp-zone identifier.

Parameters:: text – The identifier to parse.
Throws:: err::ParseError – If the identifier is unknown.
Returns:: The parsed zone.

class LogTraceSection

An optional case-sensitive trace configuration section.

Public Functions

LogTraceSection() = default: Create an empty trace section.

explicit LogTraceSection(const text::String &value)

Validate and create a trace section.

Parameters:: value – The case-sensitive configuration identifier, or an empty string for no section.
Throws:: err::ParameterError – If the section is not a configuration identifier.

inline bool isEmpty() const noexcept: Test whether this trace section is unnamed.

inline const text::String &value() const noexcept: Get the case-sensitive configuration identifier.

inline text::String toString() const noexcept: Convert this section to its identifier string.

class LogWriter

Interface for background log targets.

Subclassed by erbsland::log::impl::ConsoleLogWriter, erbsland::log::impl::FileLogWriter, erbsland::log::impl::LastErrorsLogWriter, erbsland::log::impl::SyslogLogWriter

Public Types

using Batch = std::span<const BatchItem>

A contiguous batch of shared immutable entry and line pointers.

The span itself is valid only for the duration of writeBatch(). A writer can safely retain an entry or line beyond the call by copying its shared pointer.

Public Functions

virtual void write(const LogEntryConstPtr &entry, const LogLineConstPtr &line) = 0

Deliver one filtered entry and its formatted line.

The manager calls this method only on its private worker and contains any exception it propagates.

Parameters:

entry – The nonempty shared immutable producer-created entry accepted by the route.
line – The nonempty shared immutable line formatted from entry using the active configuration.

Throws:

Any – implementation-specific delivery exception. The manager contains and counts it.

virtual void writeBatch(Batch batch)

Deliver a batch of filtered entries and formatted lines.

The default implementation calls write() for every item in order. Writers can override this method to amortize target checks and system calls over the batch.

Parameters:: batch – The ordered nonempty batch to deliver during the call.
Throws:: Any – implementation-specific delivery exception. The manager contains and counts it.

inline virtual void flush()

Flush any buffered writer data.

Throws:: Any – implementation-specific delivery exception. The manager contains and counts it.

inline virtual void close() noexcept: Release writer resources before manager shutdown.

Public Static Functions

static LogWriterPtr createForConsole(cterm::TerminalPtr terminal)

Create the built-in console writer.

Parameters:: terminal – The terminal receiving complete log paragraphs.
Returns:: A writer that renders styled paragraphs to terminal.

static LogWriterPtr createForConsole(cterm::TerminalPtr terminal, const ConsoleLogWriterOptions &options)

Create the built-in console writer.

Parameters:

terminal – The terminal receiving complete log paragraphs.
options – Style and paragraph layout settings.

Returns:

A writer that renders styled paragraphs to terminal.

static LogWriterPtr createForFile(const FileLogWriterOptions &options)

Create the built-in resilient file writer.

Parameters:: options – The target path, open mode, rotation, and retention settings.
Returns:: A writer that persists formatted lines to the configured file.

static LogWriterPtr createForSyslog()

Create the built-in syslog writer with default UDP settings.

Returns:: A writer that sends RFC 5424 messages to the default syslog endpoint.

static LogWriterPtr createForSyslog(const SyslogLogWriterOptions &options)

Create the built-in syslog writer.

Parameters:: options – The transport, endpoint, RFC 5424 fields, TLS label, and pending-data limit.
Returns:: A writer that sends RFC 5424 messages using the configured transport.

class BatchItem

One immutable entry and formatted line in a writer batch.

Public Functions

BatchItem(LogEntryConstPtr entry, LogLineConstPtr line)

Create a batch item sharing immutable entry and line values.

Parameters:

entry – The nonempty immutable entry to deliver.
line – The nonempty formatted line associated with entry.

inline const LogEntryConstPtr &entry() const noexcept

Access the shared immutable entry.

Returns:: The nonempty producer-created entry pointer.

inline const LogLineConstPtr &line() const noexcept

Access the shared formatted line.

Returns:: The nonempty worker-formatted line pointer.

class LogWriterFilter

Level and path routing for one writer.

Public Functions

LogWriterFilter() = default: Create a filter accepting all levels and paths.

inline explicit LogWriterFilter(LogLevels levels) noexcept

Create a filter accepting the given levels and all paths.

Parameters:: levels – The set of severity levels to accept.

inline LogLevels levels() const noexcept: Get the accepted severity levels.

LogWriterFilter &setLevels(LogLevels value) noexcept

Set the accepted severity levels.

Parameters:: value – The complete severity mask to accept.
Returns:: This filter for chained route construction.

inline const std::vector<LogPath> &paths() const noexcept: Get the accepted path roots.

LogWriterFilter &addPath(LogPath value)

Add an accepted path root.

An empty path list accepts every path. Once a root is added, matching uses complete path segments.

Parameters:: value – The root path to add.
Returns:: This filter for chained route construction.

bool accepts(LogLevel level, const LogPath &path) const noexcept

Test whether this filter accepts the level and complete-segment path.

Parameters:

level – The entry severity to test.
path – The entry path to test.

Returns:

true if the level is enabled and the path is within an accepted root.

class SyslogLogWriterOptions

Configuration for a syslog writer.

Public Functions

SyslogLogWriterOptions(): Create default UDP syslog settings.

inline SyslogTransport transport() const noexcept: Get the network transport.

SyslogLogWriterOptions &setTransport(SyslogTransport value) noexcept

Set the network transport.

Parameters:: value – The UDP, TCP, or TLS transport to use.
Returns:: These options for chained configuration.

inline const network::HostEndpoint &endpoint() const noexcept: Get the target endpoint.

SyslogLogWriterOptions &setEndpoint(network::HostEndpoint value) noexcept

Set the target endpoint.

Parameters:: value – The remote address and port receiving syslog messages.
Returns:: These options for chained configuration.

inline uint8_t facility() const noexcept: Get the RFC 5424 facility number.

SyslogLogWriterOptions &setFacility(uint8_t value)

Validate and set the RFC 5424 facility number.

Parameters:: value – The facility in the inclusive range zero through 23.
Returns:: These options for chained configuration.

inline const text::String &hostName() const noexcept: Get the RFC 5424 host name field.

SyslogLogWriterOptions &setHostName(text::String value)

Validate and set the RFC 5424 host name field.

Parameters:: value – The printable ASCII host name, or - for NILVALUE.
Returns:: These options for chained configuration.

inline const text::String &applicationName() const noexcept: Get the RFC 5424 application name field.

SyslogLogWriterOptions &setApplicationName(text::String value)

Validate and set the RFC 5424 application name field.

Parameters:: value – The printable ASCII application name, or - for NILVALUE.
Returns:: These options for chained configuration.

inline const text::String &processId() const noexcept: Get the RFC 5424 process identifier field.

SyslogLogWriterOptions &setProcessId(text::String value)

Validate and set the RFC 5424 process identifier field.

Parameters:: value – The printable ASCII process identifier, or - for NILVALUE.
Returns:: These options for chained configuration.

inline const text::String &messageId() const noexcept: Get the RFC 5424 message identifier field.

SyslogLogWriterOptions &setMessageId(text::String value)

Validate and set the RFC 5424 message identifier field.

Parameters:: value – The printable ASCII message identifier, or - for NILVALUE.
Returns:: These options for chained configuration.

inline const text::String &tlsConfigurationLabel() const noexcept: Get the TLS configuration label.

SyslogLogWriterOptions &setTlsConfigurationLabel(text::String value)

Validate and set the TLS configuration label.

Parameters:: value – The nonempty network/TLS configuration label.
Returns:: These options for chained configuration.

inline unit::ByteLength maximumPendingBytes() const noexcept: Get the maximum pending network-data size.

SyslogLogWriterOptions &setMaximumPendingBytes(unit::ByteLength value)

Validate and set the maximum pending network-data size.

Parameters:: value – The positive byte limit for messages awaiting transmission.
Returns:: These options for chained configuration.

class SyslogTransport

The transport used for standards-based syslog output.

Public Types

enum Value

The raw transport value.

Values:

enumerator Udp: RFC 5424 messages in UDP datagrams.

enumerator Tcp: RFC 5424 messages with RFC 6587 octet-counted framing.

enumerator Tls: RFC 5424 messages with RFC 6587 framing over TLS.

Public Functions

constexpr SyslogTransport() noexcept = default: Create the default UDP transport.

inline constexpr SyslogTransport(const Value value) noexcept

Create a transport from its raw value.

Parameters:: value – The raw transport value.

inline constexpr Value toRawValue() const noexcept

Get the raw transport value.

Returns:: The embedded value.

text::String toString() const

Convert this transport to its canonical configuration identifier.

Returns:: udp, tcp, or tls.

Public Static Functions

static text::StringList allStrings()

Get all canonical configuration identifiers.

Returns:: The identifiers accepted by fromString(), irrespective of ASCII letter case.

static std::optional<SyslogTransport> fromString(const text::String &text) noexcept

Parse a canonical transport identifier case-insensitively using ASCII folding.

Parameters:: text – The identifier to parse.
Returns:: The parsed transport, or an empty optional if the identifier is unknown.

static SyslogTransport fromStringOrThrow(const text::String &text)

Parse a canonical transport identifier.

Parameters:: text – The identifier to parse.
Throws:: err::ParseError – If the identifier is unknown.
Returns:: The parsed transport.