Skip to content

Latest commit

 

History

History
255 lines (191 loc) · 6.84 KB

README.md

File metadata and controls

255 lines (191 loc) · 6.84 KB
Raw

Log++ Logging framework

lpp

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.
  • Customize log output
  • All log calls are thread-safe.
  • Lightweight with performance in mind
  • Header only
  • 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_DEFAULT
# 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 [email protected]:ethz-asl/lpp.git
  1. Add following lines in CMakeLists.txt
add_subdirectory(my_submodule_dir/lpp)
add_executable(my_executable main.cpp)
target_link_libraries(my_executable lpp)
  1. 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 [email protected]:ethz-asl/lpp.git
  1. Build package
$ catkin build lpp

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_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);
  ...
}

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

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

Naming Convention:

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