introduction | detailed information | Configure & Build | API description | Custom log formatting
G3log is an asynchronous logger with three main features:
LOG(...)
APIDesign-by-contract
CHECK(...)
functionalityThe super quick introduction to g3log can be seen in the steps 1 - 9 below.
For more in-depth information please see the full usage description in g3log_usage.md. If you want to understand better the internals of g3log, then plase look at the API.md for both high-level and deep-dive insights.
ref: codespaces.md
Avoid deep dependency injection complexity and instead get access to the logger as easy as:
#include <g3log/g3log.hpp>
Both streaming syntax LOG
and print_f LOGF
syntax are available:
LOGF(INFO, "Hi log %d", 123);
LOG(INF) << "Hi log " << 123;
LOG_IF(INFO, (1 < 2)) << "If true this message will be logged";
LOGF_IF(INFO, (1 < 2), "If true, then this %s will be logged", "message");
CHECK(less != more); // not fatal
CHECK_F(less > more, "CHECK(false) will trigger a fatal message")
By default g3log will capture fatal events such as LOG(FATAL)
, CHECK(false)
and otherwise fatal signals such as:
SIGABRT
SIGFPE
SIGILL
SIGSEGV
SIGTERM
When a fatal event happens the not-yet written log activity will be flushed to the logging sinks. Only when all logging activity up to the point of the fatal event has happend, will g3log allow the fatal event to proceed and exit the process.
If object
symbols are available the fatal handler will attempt to push the stacktrace up to the fatal reason to the logging sink.
For overriding fatal error handling to use your own, or to add code hooks
that you want to execute please see the API.md doc.
The default logging levels are DEBUG
, INFO
, WARNING
and FATAL
. You can define your own logging levels or completely replace the logging levels. Ref: API.md
Log filtering is handled in g3log if dynamic logging levels are enabled in the configuration. See the API.md for information. Log filtering can also be handled through the sink as can be seen in github/Kjellod/g3sinks
The default logging sink has no external 3rd party dependencies. For more logging sinks please see github/Kjellod/g3sinks
See the API.md for more information about the simple steps to creating your own logging sink.
With the default application name left as is (i.e. "g3log") a creation of the logger could look something like this:
const std::string directory = "./";
const std::string name = "TestLogFile";
auto worker = g3::LogWorker::createLogWorker();
auto handle = worker->addDefaultLogger(name, directory);
The resulting filename would be something like:
./TestLogFile.g3log.20160217-001406.log
G3log aims to keep all background logging to sinks with as little log overhead as possible to the logging sink and with as small "worst case latency" as possible. For this reason g3log is a good logger for many systems that deal with critical tasks. Depending on platform the average logging overhead will differ. On my 2010 laptop the average call, when doing extreme performance testing, will be about ~2 us.
The worst case latency is kept stable with no extreme peaks, in spite of any sudden extreme pressure. I have a blog post regarding comparing worst case latency for g3log and other loggers which might be of interest. You can find it here: https://kjellkod.wordpress.com/2015/06/30/the-worlds-fastest-logger-vs-g3log/
The g3log repository is evaluating github actions for executing test coverage, installation and document generation. In case you want to look into change any of these setups the following files are the ones of interest.
See Actions
for matrix (ubuntu, macos, windows) testing as well as other actions for doc publishing.
If you like this logger (or not) it would be nice with some feedback. That way I can improve g3log and it is always nice to hear when and how someone is using it.
If you have ANY questions or problems please do not hesitate in contacting me at
Hedstrom @ Kjellod. cc
This logger is available for free and all of its source code is public domain. A great way of saying thanks is to send a donation. It would go a long way not only to show your support but also to boost continued development.
Cheers
Kjell (a.k.a. KjellKod)
introduction | detailed information | Configure & Build | API description | Custom log formatting