All notable changes to this project are documented in this file.
The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.
[Summary]
StormByte Logger is the stream-logging module of the StormByte C++ suite.
It depends directly on StormByte Base 3.0.0 and StormByte-BuildMaster >= 2.1.4. This repository is not Base, Buffer, Config, Crypto, Database, Multimedia, Network or System.
Public headers under StormByte/logger/ cover Log, ThreadedLog, header formats (L T i c g), hierarchical components and Scope facades, groups, ANSI colors, temporary formats, human-readable numbers and bytes, redaction of text and numbers, hex dumps (hex / nohex), and binary payloads (std::span<const std::byte>, std::vector<std::byte> and StormByte::Safe::Binary, default Base64). Owned text that crosses the logger DLL boundary uses StormByte::Safe::String / WString; StormByte::Size and StormByte::ByteSize are accepted as payloads. Views and caller-owned std::string are consumed synchronously. group, component and push_format are caller-side factories: a literal binds to const char*, std::string and std::string_view bind to the view, and StormByte::Safe::String binds by identity. The owned text is built in the caller.
From 2.0.0, original Logger sources are dual-licensed: GNU Lesser General Public License v3.0 or later, or a commercial license from the copyright holder. That change does not cover other StormByte modules or third-party material under thirdparty/ (including bundled StormByte Base).
If you landed here from a release link and have not read the tree:
- What this module is, how to build it, and short examples: README.md
- License: dual license LGPL-3.0-or-later or commercial, LICENSE
3.0.0 - 2026-11-04
Added
- Install FindStormByteLogger.cmake so Base 3.0.0 can discover Logger as a component.
Changed
- Breaking: Require Base 3.0.0 and select its Linux archive by architecture, libc and C++ standard library. Previous archive names and component packages without their own finder are unsupported.
- Require StormByte-BuildMaster 2.1.4 and pin the bundled submodule to that release.
- Leave CPU targeting and build-type optimization levels to the toolchain instead of imposing architecture-specific flags; ENABLE_LTO still controls interprocedural optimization.
- Build the same Linux amd64/arm64, glibc/musl and GCC/libstdc++ or Clang/libc++ variants in CI and releases. CI disables PGO and LTO; releases enable both and use the shared action's automatic CPU baselines.
- Breaking: Linux release ZIP names now include amd64 or arm64, libc and C++ standard library; previous asset names are not supported.
Fixed
- PGO training runner now prepends its library directories to LD_LIBRARY_PATH/DYLD_LIBRARY_PATH with the : separator (previously ;, which broke library lookup on musl) and no longer appends an empty entry when the variable is unset.
- Reconfigure automatically when VERSION changes so rebuilt and installed artifacts use the updated project version.
2.0.6 - 2026-11-02
Changed
- Bundled builds use StormByte Base 2.2.3.
- Rebuild release packages against the refreshed Base 2.2.3 release, including allocation-safe telemetry and map/set constructor fixes.
- Require BuildMaster 2.1.3 and pin its bundled submodule to the published release.
2.0.5 - 2026-10-28
Changed
- Header i formatting reuses the thread's formatted identifier instead of running a string stream for every line.
- Scoped logging skips component-path copies and ancestor lookups when no component-specific format or color exists. Overrides installed later still take effect immediately; emitted text, colors, filtering, throttling and line locking are unchanged.
- Bundled builds use Base 2.2.2.
Added
- Regression coverage for repeated thread-ID tokens on different threads and component overrides installed after default scoped output.
2.0.4 - 2026-10-24
Changed
- Bundled third-party StormByte dependencies now require the matching patch releases (Base 2.2.1, Buffer 2.0.4, Logger 2.0.4, System 2.1.1 where applicable) so a bundled build picks up the /arch:AVX change.
Changed
- Windows Release optimizations use /arch:AVX instead of /arch:AVX2. The previous baseline required a Haswell-or-newer CPU (AVX2). /arch:AVX runs on Sandy Bridge and Ivy Bridge (including the i7-3770K) and later.
2.0.3 - 2026-10-23
Bumped version to use StormByte base 2.2.0 bundled
2.0.2 - 2026-10-19
Added
- ENABLE_PGO and ENABLE_LTO. Profile-guided optimization trains in pgo-instr and installs this build. Link-time optimization follows ENABLE_LTO (default ON) for every build type. Both apply to Logger. Base is not rebuilt.
- Release archives include THIRD-PARTY (not THIRDPARTY: on Windows and macOS that name is the same path as the thirdparty/ directory, so the file never landed in those zips). No third-party object code is compiled into this shared library. StormByte Base is linked at run time and keeps its own notice.
- PerfTests trains the hot path, not only lines already dropped by the print floor. Each iteration mixes a level under the floor (no conversion and no throttle), a level that passes the floor and is then refused, and a sparse line that is written. Drop, Sample, Window and a live rate bucket are all exercised, including a scoped facade, a group rule and ThreadedLog from several threads. Admission therefore has a profile with and without the line lock.
Changed
- CI builds with ENABLE_LTO=ON, ENABLE_PGO=OFF and ENABLE_TEST=ON, then runs ctest. Profile-guided optimization stays on the release workflow.
- cmake/optimizations.cmake is the same file as Base. On Release, and only when that language was not set from the outside, it appends OPTIMIZATION_FLAGS_LINUX, OPTIMIZATION_FLAGS_MAC or OPTIMIZATION_FLAGS_WINDOWS. Linux is -O2 -march=x86-64-v3, Apple is -O2 -mcpu=apple-m1, Windows is /O2 /arch:AVX2. There is no /fp:fast and no /EHsc. cmake/pgo.cmake is the same file as Base, so a forwarded list keeps its semicolons.
- Requires StormByte-BuildMaster >= 2.1.0. An older install is not used; the buildmaster submodule supplies 2.1.0.
- Requires StormByte Base 2.1.0. The build downloads that release archive (stormbyte_component_url) and links it with BACKEND=binary. The Base submodule is gone. The archive matches this OS and C++ runtime: libstdc++ or libc++ on Linux and macOS, no runtime suffix on Windows. Doxygen include path is ${BUILDMASTER_INSTALL_INCLUDEDIR}, not thirdparty/StormByte/base/src.
- Bumped the project version to 2.0.2.
- Breaking: Logger::Exception no longer formats with std::format. A message with arguments replaces literal {} through Safe::String::ReplaceToken, the same rule as Base 2.1.0. what() stays StormByte.Logger: message. An extra Exception::Path is the segment under Logger, not the full path. ThrottleError is still a leaf and adds no segment.
Fixed
- -stdlib=libc++ and -stdlib=libstdc++ do not count as custom C++ flags. If either is the only extra flag, Release still gets -O2 and the CPU baseline.
- Human-readable numbers keep en_US grouping (1,000) when the named C++ locale has no thousands separator. musl does not group en_US.UTF-8, so humanreadable_number printed 1000 and redaction counted the shorter text.
- Part of the port: the DLL does not return a std:: object. std::strong_ordering is not a DLL ABI. clang-cl returns it through a hidden pointer and MSVC does not pass one, so a call into a clang-built Base wrote at address 0. Ordering is compiled by the caller from Base 2.1.0, where those operators are STORMBYTE_FORCE_INLINE. A signature that must return std:: (operator std::string) is STORMBYTE_FORCE_INLINE in the header too. This archive must be built against that Base.
- cmake/pgo.cmake matches Base. MSVC PGO links with /LTCG:PGINSTRUMENT and /LTCG:PGOPTIMIZE. /GENPROFILE alone fails with LNK1220 because the current link.exe requires an /LTCG specification, and CMake's own /LTCG stays off so it does not replace the profile mode. The profile mode is add_link_options on this project, not CMAKE_EXE_LINKER_FLAGS. A nested project() inherits the cache and its compiler test links cmTC_*.exe, which was never instrumented, so /LTCG:PGOPTIMIZE aborted with LNK1266 (cmTC_*.pgd missing). The cache keeps a bare /LTCG so those /GL objects still link. A static dependency stays LTCG and is optimized by the link that owns the .pgd.
- Clang PGO drops .profraw files left by compiler probes before ctest, and llvm-profdata merge uses -failure-mode=all. A probe writes a few hundred bytes for main, with a padded empty symbol name. The default failure mode is any, so that one file aborted the merge even after the instrumented tests had passed.
2.0.1 - 2026-10-13
Changed
- Updated dependency pins.
- Bumped the project version to 2.0.1.
2.0.0 - 2026-10-10
Added
- operator<< for StormByte::Safe::Optional, StormByte::Safe::Vector and StormByte::Safe::Map, with recursive values, explicit empty-option text, bracketed vectors and ordered multiline maps.
- SinkFunction, a StormByte::Safe::Function sink for Log and ThreadedLog; its callback context is released in the creator module.
- operator<< on Log and ThreadedLog for StormByte::Safe::String, StormByte::Safe::WString, StormByte::Size, StormByte::ByteSize and StormByte::Safe::Binary. Conversion and copy run only when WillWrite() is true.
- operator<< on StormByte::Safe::Shared and StormByte::Safe::Unique of Log or ThreadedLog, same sugar as std::shared_ptr: log << "Hola" without a dereference.
- ~Log and ~ThreadedLog are defined in the library, so the backend and the line lock are released inside the DLL. Copy and move assignment are too.
- Private StormByte::Logger::Detail human-readable number and IEC byte formatting. The manipulator API is unchanged; this logic no longer lives in String.
- Tests for owned-text payloads, filtered drop of owned text, Size, ByteSize, Safe::Binary, Safe optional/vector/map output, and ill-formed wide input substituted as U+FFFD.
Changed
- Logger depends on StormByte Base 2.0.0. Owned text, binary payloads, optional fields and clone owners use StormByte::Safe. There is no StormByte::BinaryData payload.
- Breaking: the backend and the ThreadedLog line lock are allocated with StormByte::Safe::MakeShared on Base's heap. Safe::Heap::MakeShared is not part of this API.
- Breaking: group, component and push_format are header factories. A literal binds to const char*, a view or std::string binds to std::string_view, and StormByte::Safe::String binds by identity. They are not exported DLL overloads. The manipulator still carries Safe::String, built in the caller.
- Breaking: with hex(N) active, std::span<const std::byte>, std::vector<std::byte> and StormByte::Safe::Binary are formatted with Safe::Binary::HexDump(N). Text, wide text and numbers still use the 0xAA dump. Without hex, binary payloads stay Base64. Base64Encode returns StormByte::Safe::String.
- Breaking: public streaming no longer treats std::string as an owned cross-module type. Use StormByte::Safe::String when the buffer is owned by another module; string_view remains valid for caller-owned data. A caller-owned std::string is streamed inline as a view and copied synchronously.
- Breaking (boundary): Log and ThreadedLog no longer write an std::ostream from inside the DLL. Construction from an std::ostream still works and still requires the stream to outlive the logger. Bytes and manipulators (std::endl) are applied by OStreamWrite / OStreamManip in the module that constructed the logger. A protected constructor takes those callbacks directly.
- Breaking: ThrottleSpec::Component and ThrottleSpec::Group use StormByte::Safe::Optional<StormByte::Safe::String>. Public optional fields in ThrottleSpec and ColorManip use StormByte::Safe::Optional. Public logger facades and manipulators declare their conditional DLL-safety with MaybeSafe.
- Breaking: ill-formed wide text is written as U+FFFD (EF BF BD). Logger does not throw StormByte::UTF8Error on that path.
- Breaking: Logger::Exception takes Exception::Path{"Logger"}. what() is StormByte.Logger: message. Component is gone. ThrottleError is a leaf and adds no segment. Destructors are defined in this module.
- Breaking: Log is StormByte::Safe::Clonable<Log>, so Clone, Move and Scope return StormByte::Safe::Shared<Log> allocated on Base's heap. std::shared_ptr<Log> is no longer a PointerType. Safe::Shared still converts to std::shared_ptr<Log> and keeps Base's deleter. The same applies to ThreadedLog.
- Log::m_scope_path is StormByte::Safe::String so a copied or derived Log does not carry std::string across a DLL boundary.
- The private backend is Engine (m_engine), in engine.hxx / engine.cxx. It was Implementation.
- LevelToString returns const char* (a string literal) instead of std::string. Call sites that store it in a std::string are unchanged.
- Filtered payloads (WillWrite() false) return before any conversion or copy. A filtered or throttled std::endl does not touch the stream. An emitted line still forwards real std::endl, so the text is flushed at that instant and the next payload prints a new header. std::endl / std::flush / std::ends are recognized without probing a string stream.
- Numeric and narrow-text payloads share Log::WriteValue; ThreadedLog only overrides BeginPayload for those payloads.
- ThreadedLog tracks each concrete line lock independently per thread, so nested writes through separate logger instances cannot bypass one another's mutex.
- ThreadedLog serializes configuration queries and updates with its shared line lock. Failures release the lock, preserve StormByte exceptions and translate foreign exceptions to Logger::Exception.
- Caller sinks are contained in noexcept output paths; typed callback sinks also receive header separator bytes. Message construction and numeric-format fallback failures stay inside those paths.
- Shared vs static follows CMake BUILD_SHARED_LIBS (declared in the project root, default ON). There is no STORMBYTE_LOGGER_SHARED CMake option. When the library is shared, the compile definition STORMBYTE_LOGGER_SHARED is still set so visibility.h can distinguish dllexport / dllimport / static. CI passes -DBUILD_SHARED_LIBS=ON. Vendored StormByte Base follows the same BUILD_SHARED_LIBS mode.
- License: original Logger sources are dual-licensed LGPL-3.0-or-later or commercial. Third-party trees under thirdparty/ keep their own licenses. Neither license grants patent rights.
Fixed
- Owned-text streaming keeps embedded NUL code units. Safe::String and Safe::WString are length-aware; there is no separate C-string wrapper on this path.
- A sink callback failure does not terminate the process through a noexcept write path. A ThreadedLog configuration failure does not leave the line lock held.
- Unknown or incomplete header-format tokens stay literal. A ThreadedLog that writes through another instance keeps its own lock.
- ThrottleSpec::Level is qualified so public headers compile with GCC 14+ without -Wchanges-meaning. The field and the designated-initializer API are unchanged.
1.2.0 - 2026-09-17
Added
- Log::Enabled(Level): print-floor query (Warning/Error/Fatal always true). Does not open a line and does not consult throttle.
- operator<<(std::string_view) and operator<<(std::wstring_view) on Log and ThreadedLog, with the same filtered early-out as other payloads. std::string / std::wstring convert to the views.
- hex / hex(N) / nohex: dump subsequent payloads as spaced 0xAA bytes. N is bytes per row (default 16); wrap uses a raw newline without a new header and without ending the logical line. hex(0) is nohex. Applies to text, wide text (after UTF-8), numbers (42 → bytes of "42") and binary spans. Hex runs before redaction.
- operator<<(std::span<const std::byte>) on Log and ThreadedLog. Default output is Base64 (StormByte::Base64Encode). std::vector<std::byte> converts to the span. With hex the dump is the raw bytes, not the Base64 text. Empty spans emit an empty payload. ThreadedLog formats the payload before taking the line lock (FormatBinary + WritePrepared).
- Hierarchical components: component("A") pushes a thread-local segment; nested pushes join with / for c and config lookup. pop_component pops one segment. reset_component still clears the stack. component("") does not push.
- Log::Scope(path) returns a std::shared_ptr<Log> facade with a sticky component path. Nested Scope joins relative to the parent. Never returns nullptr. Facades share the backend and, on ThreadedLog, the line lock. A Scope line uses the sticky path, not the TLS stack.
- Protected Clonable<Log, std::shared_ptr<Log>> on Log (Clone / Move) so Scope can copy the facade without exposing cloning in the public API.
- Pointer operator<< accepts shared_ptr / unique_ptr whose element type Type::DerivedFrom Log (Log and ThreadedLog).
Changed
- Dropped the dedicated operator<<(const std::string&) / operator<<(const std::wstring&) overloads. Call sites that pass std::string still compile.
- ThreadedLog wide payloads encode with String::UTF8Encode(std::wstring_view) before taking the line lock.
- Bundled StormByte Base is 1.2.0. Using UTF8Encode(std::wstring_view) and Base64Encode(std::span<const std::byte>) requires Base 1.2.0 or newer.
- Breaking: no_redact is now noredact, same shape as nocolor, nohex and nohumanreadable. There is no compatibility alias.
- Breaking: component("name") pushes onto the thread-local stack instead of replacing the current name. Sibling switches must reset_component or pop_component first, otherwise component("Media") then component("Other") becomes Media/Other.
- Format and color lookup use the longest matching component-path prefix, then the general setting. A child format may introduce c / g even when the parent format does not.
- Throttle still picks the most specific rule; component matching is by path prefix and longer paths win. Format / Color / Throttle without a component argument bind to the current facade path (Scope leaf, or global on the root logger).
- README documents the component stack, Scope, hex dumps and binary payloads.
Fixed
- ~Implementation no longer first-touches thread-local line state (Valgrind still-reachable TLS at exit).
- Inherited throttle rules keep one spec per prefix but one counter set per emitting path. A parent Scope("Multimedia").Throttle(Debug, …) no longer lets Encoder consume watermark tokens or print watermark dropped N messages when that leaf had not emitted anything at that level. Drop summaries stay on the leaf that dropped. Tests cover Log and ThreadedLog.
1.1.1 - 2026-09-15
Changed
1.1.0 - 2026-09-13
Added
- group("name") and g; the group is cleared by newline and is not rendered in the body when g is absent.
- Sticky per-thread component("name"), reset_component and c. component("") selects the root without throwing, while reset_component is the canonical reset. The state belongs to the thread, not the Log; two Log instances on one thread observe the same component.
- ANSI colors by Level and component override, with color, color(Color::X) and nocolor. Color output is disabled by default.
- Persistent general and component formats, plus nested push_format / pop_format; an empty pop_format is idempotent.
- Expanded tests for colors, temporary formats, groups, components, threads, Unicode and lock recovery.
- Added configurable line throttle policies (Drop, Sample, Window) with component/level/group rule precedence and drop summaries.
- Added FlushThrottle() and selective FlushThrottle(spec) for pending drop summaries at job boundaries.
Changed
- Requires StormByte Base 1.1.0 or newer (Exception with Component). Logger did not use the two-string Exception constructor.
- Warning, Error and Fatal are always emitted, even when the configured floor is higher. This is intentional.
- Expanded ThreadedLog coverage for the filtered hot path, wide conversion before locking, and recovery when Unicode conversion fails.
Fixed
- ThreadedLog::FlushThrottle preserves ownership of an already-held line lock.
- Format changes now reset the active throttle line snapshot after closing an open line.
- endl releases the ThreadedLog line lock even if WillWrite() changes midway through a line.
- Wide-string logging converts before acquiring the lock; a Unicode conversion error no longer terminates the logger from an internal noexcept path.
- ThreadedLog::Write(Level) — two threads sharing a ThreadedLog raced on Implementation’s optional<Color> (m_content_color.reset() at the start of a line). The level token now takes the line lock like other Write overloads; payload and endl already did.
1.0.0 - 2026-09-05
Initial public release of StormByte Logger.
Added
- Log streaming facade with operator<<
- Level filter: LowLevel, Debug, Warning, Notice, Info, Error, Fatal
- Header format: L, T, i, %%
- Manipulators: humanreadable_number, humanreadable_bytes, nohumanreadable
- Redaction: redact / redact(N) keep last N; redact_first(N) keep first N; no_redact; applies to text and numbers
- ThreadedLog: one lock per logical line; filtered messages do not take the lock
- Uses StormByte Base 1.0.0 (String, ThreadLock, platform)
- Unit tests (filter, threads, redaction)
- Project version read from the VERSION file
- CMake 3.28 floor
Notes
- Log is not thread-safe. Use ThreadedLog when several threads share one logger.
- Messages below the print level return early.
- Needs a C++26 compiler and StormByte Base 1.0.0.