Log++ Logging framework

Latest Code Coverage Report (master branch)

---

Features

• Framework to standardize ros and glog output at compile time.
• Uses ros/glog's native log calls depending on selected mode.
• Optional Python bindings with a method-based logger API.
• Customize log output
• All log calls are thread-safe.
• Lightweight with performance in mind
• Header only for C++
• GCC 8 or later required
• Recommended to use with C++17/C++20, but also works with C++11/C++14.

Example

src/demo.cpp

#include <log++.h>

int main(int argc, char **argv) {
  LOG_INIT(argv[0]);
  int foo = 5;
  
  LOG(I, "Foo: " << foo);           //Log++ syntax
  ROS_INFO_STREAM("Foo: " << foo);  //ROS syntax
  LOG(INFO) << "Foo: " << foo;      //Glog syntax
  return 0;
}

Output with different flags

• MODE_DEFAULT:

INFO  Foo: 5
[ INFO] [1664445448.151401926]: Foo: 5
I0929 11:57:28.151427 1360708 main.cpp:8] Foo: 5

• MODE_LPP:

INFO  Foo: 5
INFO  Foo: 5
INFO  Foo: 5

• MODE_GLOG:

I0929 11:57:50.238454 1360823 main.cpp:6] Foo: 5
I0929 11:57:50.238514 1360823 main.cpp:7] Foo: 5
I0929 11:57:50.238536 1360823 main.cpp:8] Foo: 5

• MODE_ROSLOG:

[ INFO] [1664445486.584182057]: Foo: 5
[ INFO] [1664445486.584212352]: Foo: 5
[ INFO] [1664445486.584240476]: Foo: 5

Installation

Option 1: Copy the header

1. Copy the header file include/log++.h to your project.

2. Add the following line to CMakeLists.txt to select the desired mode for...

• a project:

# Valid modes are: MODE_LPP MODE_GLOG MODE_ROSLOG MODE_SYSD MODE_DEFAULT MODE_NOLOG
# Use add_definitions(-DMODE_LPP) if cmake version <= 3.11

add_compile_definitions(MODE_LPP)

• a specific executable or library:

target_compile_definitions(my_executable PRIVATE MODE_LPP) 

Option 2: Add Log++ as a submodule

1. Add Log++ as a submodule with following command:

$ git submodule add git@github.com:ethz-asl/lpp.git

2. Add following lines in CMakeLists.txt

add_subdirectory(my_submodule_dir/lpp)
add_executable(my_executable main.cpp)
target_link_libraries(my_executable lpp)

3. To update Log++ to the latest commit, execute the following commands:

From submodule directory

$ git pull origin master

From parent directory

$ git add path/to/submodule_dir

Option 3: Build as catkin package

1. Clone the package into the catkin workspace

$ git clone git@github.com:ethz-asl/lpp.git

2. Build package

$ catkin build lpp

Option 4: Install the Python package

The Python bindings are built only through scikit-build. Normal CMake and catkin builds do not require Python or nanobind.

$ uv pip install .

or build a wheel:

$ uv build

Usage

Modes

• MODE_LPP Log++ Logging output.
• MODE_GLOG: Google Logging output. Calls abort() if it logs a fatal error.
• MODE_ROSLOG: ROS Logging output.
• MODE_SYSD: systemd journal output. Logs can be viewed with journalctl -t <identifier>, or followed live with journalctl -f -t <identifier>. The identifier is the systemd journal SYSLOG_IDENTIFIER field; by default it is the executable name passed to LOG_INIT(argv[0]), with any path stripped.
• MODE_DEFAULT: Disables Logging standardization. Messages are logged according to their framework.
• MODE_NOLOG: Disables Logging completely. Useful for unittests or in some cases for release builds.

How severity levels should be used

• Debug: Everything too verbose during normal execution and can be ignored.
• Info: Everything that could be of interest during a normal execution, but could also be ignored.
• Warning: Things that may need attention, but are probably not dangerous.
• Error: Things that need attention and probably are dangerous if not handled.
• Fatal: Everything that should stop execution immediately.

Note for glog:

• When using with MODE_ROSLOG or MODE_LPP, the macros DLOG(severity) and VLOG() will get converted to debug severity.

• When using with MODE_GLOG, the Log++ and Roslog debug macros LOG(D) and ROS_DEBUG() will get converted to DLOG(INFO).

• Fatal log messages call abort(). (glog only)

Log++ Syntax

Log++ provides its own logging functions, if you want to use Log++ as the base logging framework

Default logging

int foo = 1;
int bar = 3;
LOG(I, "Values: " << foo << " " << bar);

Conditional logging

int foo = 1;
int bar = 3;
LOG(I, foo != bar, "Values: " << foo << " " << bar);

Occasional logging

int foo = 1;
int bar = 3;

for (int i = 0; i < 50; i++) {
  LOG_EVERY(I, 20, "Values: " << foo << " " << bar) // Log every 20 calls.
}

Logging first N occurrences

int foo = 1;
int bar = 3;

for (int i = 0; i < 10; i++) {
  LOG_FIRST(I, 5, "Values: " << foo << " " << bar) //Log first 5 calls.
}

Log output customization

Log++ also allows you to customize the log output with a callback function when using MODE_LPP:

void logCallback(BaseSeverity severity, const std::string& str) {
  std::cout << str << std::endl;
}

int main(int argc, char **argv) {
  LOG_INIT(argv[0], logCallback);
  ...
}

Python bindings

The Python API provides a low-boilerplate Logger() helper for short scripts. It returns a standard logging.Logger configured with an LppHandler and logging.INFO level.

from lpp import LogMode, Logger

logger = Logger("foo", LogMode.MODE_LPP)

logger.info("started")
logger.warning("many retries")
logger.critical("cannot continue")

Python modes

• LogMode.MODE_LPP: Log++ stdout-style output. This mode also supports a Python callback.
• LogMode.MODE_SYSD: systemd journal output. Pass identifier="my-service" to set SYSLOG_IDENTIFIER. Logs can be viewed with journalctl -t my-service, or followed live with journalctl -f -t my-service. If no identifier is provided, the Python binding uses the process basename from sys.argv[0].
• LogMode.MODE_NOLOG: accepts log calls and emits nothing.
• LogMode.MODE_DEFAULT: uses Log++ stdout-style output for the Python handler.
• LogMode.MODE_GLOG and LogMode.MODE_ROSLOG: enum values are exported, but construction raises RuntimeError unless these backends are implemented for Python.

import logging
from lpp import LogMode, Logger

logger = Logger("my-service", LogMode.MODE_SYSD, identifier="my-service")
logger.error("failed to connect")

Python logging methods

Use the standard Python logging API:

logger.debug("details")
logger.info("ready")
logger.info("value=%s", value)
logger.warning("retrying")
logger.error("failed")
logger.critical("cannot continue")

critical() maps to Log++ fatal severity. Python logging handles formatting, filters, levels, propagation, and handlers before the record reaches LppHandler. Log++ policy helpers such as LOG_EVERY are intentionally not part of the Python API; use standard logging.Filter patterns for Python-side filtering or throttling.

For advanced logging setup, attach LppHandler manually:

import logging
from lpp import LogMode, LppHandler

logger = logging.getLogger("foo")
logger.addHandler(LppHandler(LogMode.MODE_LPP))
logger.setLevel(logging.INFO)

MODE_LPP can also route output through a callback, which is useful for tests:

events = []
logger = Logger("test", callback=lambda severity, message: events.append((severity, message)))
logger.warning("captured")

Overview of logging methods

Method	Log++	Glog	ROS
Default logging	LOG(I, str)	LOG(INFO) << str	ROS_INFO(str)
Conditional logging	LOG(I, cond, str)	LOG_IF(INFO, cond) << str	ROS_INFO_COND(cond, str)
Occasional logging	LOG_EVERY(I, n, str)	LOG_EVERY_N(INFO, n) << str	-
Conditional occasional logging	-	LOG_IF_EVERY_N(INFO, cond, n) << str	-
Timed logging	LOG_TIMED(I, t, str)	LOG_EVERY_T(INFO, t) << str	ROS_INFO_THROTTLE(t, str)
First N occurrences	LOG_FIRST(I, n, str)	LOG_FIRST_N(INFO, n) << str	ROS_INFO_ONCE(str) (only 1)
Log to std::vector<string>	-	LOG_STRING(INFO, &vec) << str	-

The following features are currently not supported (Feel free to contribute)

• Implement ROS_INFO_NAMED() etc.
• ROS2 support

Contributions

The following information should be considered when contributing to Log++.

Build Unittests

Unittests can be built by setting the LPP_BUILD_TESTS flag. If building with catkin, the tests can be built with the following command:

$ catkin build lpp -DLPP_BUILD_TESTS=1

Python binding tests are written with pytest. Run with:

uv run --with pytest pytest test/python

Unittests

• All modes (default, glog, lpp, roslog, nolog) have a separate test suite. All tests should run with each mode.
• Test all severity levels (Debug, Info, Warning, Error, Fatal)
• Test if the functionality of a logging function works, not only the logging format (Default, Conditional, Occasional, Timed, First N occurrences)
• Tests must run in debug mode in order to test debug log output
• Python tests mirror the C++ behavior groups for the method-based binding API.

Naming Convention:

TEST(<mode>_<LoggingMethod>, <mode>_syntax_severity_<severity>) {
  //Test logic
}