logpp

A modern, fast, structured logging framework in C++
Explore the docs »
Report Bug · Request Feature

Table of Contents

1. About The Project
   • Features
   • Built With
2. Getting Started
   • Prerequisites
   • Installation
3. Usage
4. Roadmap
5. Contributing
6. License
7. Contact
8. Acknowledgements

About The Project

The logging framework you've always dreamed of.

Log events are first recorded from a Logger, formatted with a Formatter like logfmt or pattern and sent to a Sink for persistence or visualization like console, file and others

Unlike other well-known logging frameworks, logpp has been designed with the idea of enriching log events with information called structured data. The act of adding data to log messages is called structured logging.

For example, with logpp, a typical structured log event looks like this:

logpp::info("Handling http request",
    logpp::field("path", path),
    logpp::field("method", method));

and will yield the following string rendered into logfmt format:

lvl=Info msg="Handling http request" path=/v1/ping method=GET

At its core, logpp has been designed with a zero-allocation approach, meaning that it will avoid memory allocations for small log events. Combined with asynchronocity, logpp is a perfect fit for logging in critical code paths.

Features

• Level-based logging API with familiar levels like debug, info, warn, error
• Hierarchical loggers. Loggers are organized in a tree-based hierarchy, e.g Namespace, Namespace.Component, Namespace.Component.Class
• TOML runtime configuration, see logpp.toml example
• Enrichment of log messages with contextual structured fields
• Built-in support for a variety of sinks
  • Colored console
  • File
  • Rolling file
  • Please contribute yours !
• Extandable and configurable log formatters
  • Pattern
  • logfmt
• Asynchronous logging (optional)
• Zero-allocation logging strategy for small log messages

Built With

• conan
• CMake

Getting Started

Prerequisites

To retrieve logpp external dependencies, make sure to install and configure conan on your local machine.

Installation

1. Clone the repo

   git clone https://github.com/oktal/logpp.git

2. Create a build directory

        cd logpp
        mkdir build

3. Install dependencies

       cd build
       conan install ..

4. Build the library

       conan build ..

Usage

Namespace

The logpp api is located in the logpp namespace

Basic

#include "logpp/logpp.h"

int main(int argc, char* argv[])
{
    logpp::info("This is a log message",
        logpp::field("exe_name", argv[0]));
}

2021-04-12 13:28:50 [info] (logpp) This is a log message - exe_name=./bin/sample_BasicLogger

logpp provides a default logger that will log all messages into the standard output. logpp trace, debug, info, warn and error functions will all use the default logger provided by logpp.

Manual setup

This example demonstrates how to setup a manual logger to log to a file.

#include "logpp/sinks/file/FileSink.h"
#include "logpp/core/Logger.h"

using namespace logpp;

int main()
{
    auto sink = std::make_shared<sink::FileSink>("main.log");
    auto logger = std::make_shared<Logger>("main", LogLevel::Info, sink);

    logger->info("Hello from main");
}

> cat main.log 
2021-04-12 13:34:35 [info] (main) Hello from main

Configuration file

Logpp registry can be configured from a TOML configuration file. The following example demonstrates how to do it:

#include "logpp/config/TomlConfigurator.h"
#include "logpp/logpp.h"

#include <iostream>

int main(int argc, const char* argv[])
{
    std::string file = "logpp.toml";
    if (argc == 2)
        file = argv[1];

    std::cout << "Configuring logger with " << file << std::endl;
    auto err = logpp::TomlConfigurator::configureFile(file);

    if (err)
    {
        std::cerr << "Error configuring logger: " << *err << std::endl;
        return 0;
    }

    auto logger = logpp::getLogger("main");

    logger->info("This is an informational message",
                 logpp::field("exe_name", argv[0]));
}

For a detailed description of logpp configuration format, please refer to logpp.toml

Examples

For more examples, please refer to the examples folder

Roadmap

See the open issues for a list of proposed features (and known issues).

Contributing

Contributions are what make the open source community such an amazing place to be learn, inspire, and create. Any contributions you make are greatly appreciated.

1. Fork the Project
2. Create your Feature Branch (git checkout -b feature/AmazingFeature)
3. Commit your Changes (git commit -m 'Add some AmazingFeature')
4. Push to the Branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

License

Distributed under the MIT License. See LICENSE for more information.