Soralog: High-Performance Logging Library

Overview

Soralog is a high-performance, flexible logging library designed for C++ applications. It provides robust logging features, supports multiple logging backends, and allows extensive customization. The library is designed to be lightweight, efficient, and easy to integrate into various projects.

Features

• Multiple log sinks: console, file, syslog, and more.
• Efficient lock-free circular buffer for log messages.
• Thread-safe logging with minimal overhead.
• Hierarchical logging groups with inheritance.
• Configurable log levels and formats.
• Configurable via YAML or programmatically.
• Macro-based or object-based logging interface (up to user).

Installation

Dependencies

Soralog requires:

• fmt for formatting log messages.
• yaml-cpp for convenient configuring.
• gtest for unit tests (optional).

Soralog uses CMake as its build system and supports different configurations through CMake options.

Build Options

• BUILD_TESTS (default: OFF) – Build unit tests.
• EXAMPLES (default: OFF) – Build example programs.
• ASAN, LSAN, MSAN, TSAN, UBSAN (default: OFF) – Enable sanitizers.

Supported Package Managers

Soralog supports dependency management via hunter and vcpkg. By default, hunter is used unless a vcpkg toolchain file is detected.

git clone https://github.com/xDimon/soralog.git
cd soralog
mkdir build && cd build
cmake .. -DBUILD_TESTS=ON -DEXAMPLES=ON
make

To use vcpkg, specify the toolchain file:

cmake -DCMAKE_TOOLCHAIN_FILE=/path/to/vcpkg.cmake ..

To include Soralog in your project, add the following to your CMakeLists.txt:

find_package(soralog REQUIRED)
target_link_libraries(your_project PRIVATE soralog)

Basic Usage

Creating a Logger

Before using any loggers, you must configure the logging system. The LoggingSystem::configure() method must be called, returning a Configurator::Result indicating success or failure.

LoggingSystem logging_system(configurator); // See examples
const auto result = logging_system.configure();
if (result.has_error) {
  std::cerr << result.message;
}
soralog::Logger logger = logging_system.getLogger("logger", "main_group");

Using logger methods

logger.debug("Hello, {}!", "world");
logger.info("Hello, {}!", "world");

Using Logging Macros

SL_INFO(logger, "Hello, {}!", "world");
SL_WARN(logger, "Hello, {}!", "world");

Configuration model

Soralog supports passing multiple configurators to the LoggingSystem. These configurators are applied sequentially, allowing flexible and incremental configuration.

The configuration process occurs in four waves:

1. Prepare – initial setup and validation.
2. Apply sinks – creation and configuration of sinks.
3. Apply groups – setup of logging groups with hierarchy.
4. Cleanup – finalization and resource management.

Later configurators may override or extend settings from earlier ones, enabling complex configurations via cascading.

Configuration File

Soralog uses a YAML-based configuration file. Below is a detailed breakdown of all available parameters.

Notes

• The builtin sink "*" always exists and discards all output.
• The syslog sink is process-global; only one sink of type: syslog may be defined.
• The latency parameter controls flushing delay in milliseconds. Setting latency: 0 forces immediate synchronous flush on every log event, which may increase overhead.

Example YAML Configuration

sinks:
  - name: colored_stdout
    type: console
    stream: stdout
    color: true

  - name: file
    type: file
    path: /tmp/soralog.log

groups:
  - name: main
    sink: colored_stdout
    level: trace
    is_fallback: true
    children:
      - name: example_group

Sink Configuration Options

Common Sink Parameters

Parameter	Type	Required	Default	Description
name	string	Yes	N/A	Unique identifier of the sink
type	string	Yes	N/A	Sink type (console, file, syslog, multisink)
thread	string	No	none	Thread info mode (name, id, none)
capacity	int	No	64	Number of buffered events in the lock-free circular buffer
buffer	int	No	131072	Buffer size in bytes
latency	int	No	100	Max delay in milliseconds before flushing. 0 means immediate synchronous flush (higher overhead).
level	string	No	trace	Minimum log level (trace, debug, verbose, info, warn, error, critical)

Flushing occurs when either the capacity or buffer size limits are exceeded, or when the latency timer expires.

Console Sink (type: console)

Parameter	Type	Required	Default	Description
stream	string	No	stdout	Output stream (stdout, stderr)
color	bool	No	false	Enables colored output

File Sink (type: file)

Parameter	Type	Required	Default	Description
path	string	Yes	N/A	Path to the log file
at_fault	string	No	wait	Action on failure (terminate, wait, ignore)

Syslog Sink (type: syslog)

Parameter	Type	Required	Default	Description
ident	string	No	N/A	Identifier for syslog messages

Multisink (type: multisink)

Parameter	Type	Required	Default	Description
sinks	array	Yes	N/A	List of sink names to forward logs to

Group Configuration Options

Parameter	Type	Required	Default	Description
name	string	Yes	N/A	Unique identifier of the group
sink	string	Yes	N/A	Sink used for this group
level	string	Yes (for root groups)	N/A	Minimum log level (trace, debug, verbose, info, warn, error, critical)
is_fallback	bool	No	false	Marks this group as the default fallback
children	array	No	[]	List of child groups

FATAL / CRITICAL Semantics

• CRITICAL log level causes the current sink to flush immediately.
• FATAL log level flushes all sinks and then aborts the process.

Examples

Soralog provides various examples demonstrating different use cases and configurations. Below is a list of available examples:

1. 01-hello_world – A minimal example that initializes a logger and writes a simple message.
2. 02-manual – Demonstrates programmatic configuration of logging without using a YAML config file.
3. 03-with_config_file – Shows how to configure Soralog using a YAML configuration file.
4. 04-cascade_config – Demonstrates hierarchical logging groups with inherited settings.
5. 05-two_sinks – Example of logging to two different sinks (e.g., console and file).
6. 06-multisink – Uses a multisink to send log messages to multiple destinations.
7. 07-multisink_with_different_level – Extends the multisink example by setting different log levels for different sinks.
8. 08-logfile – Logging to file with buffering and latency control.
9. 09-logfile_rotate – Logfile rotation using logrotate.
10. 99-most_features – A comprehensive example showcasing most of Soralog’s features, including:
    • multi configurators
    • multisinks
    • per-sink log levels
    • thread naming and concurrent logging
    • long message truncation

Example Source Code

The source code for these examples is available in the example directory.

Projects Using Soralog

Soralog is utilized in several open-source projects, including:

• cpp-libp2p
• qlean-mini
• Kagome
• cpp-jam

Contributing

We welcome contributions! Feel free to submit issues and pull requests.

License

Soralog is licensed under the Apache-2.0 license. See the LICENSE file for details.