iris/README.md

   1 # Overview
   2 `iris` is asynchronous logging library designed to log messages with minimum overhead to the performance. The cost of logging a message is merely copying the arguments into a lockfree queue.
   3
   4 # Design
   5 Under the hood, `iris` uses a background thread (logging thread) to offload logging from other threads.
   6 1. For every other threads, they keep a lockfree queue to buffer the messages.
   7 2. The logging thread periodically scans through all these queues to collect messages, formats them and writes them into log file.
   8
   9 A few highlights of the design of `iris` to achieve low latency:
  10 1. Buffering messages with thread local lockfree queue.
  11 2. Memory is managed by a thread local ringbuffer taking the advantage that logging is FIFO. Because the fact that logging is FIFO. This scales well in multithreaded environment.
  12 3. Minimum context switches.
  13
  14 # Usage
  15 The supported severity levels are:
  16 ```c++
  17 enum severity_level {
  18     TRACE,
  19     DEBUG,
  20     INFO,
  21     WARN,
  22     ERROR,
  23     FATAL
  24 };
  25 ```
  26 By default, `iris` logs messages to `stdout` and filters out severity level less than `INFO`.
  27
  28 ```c++
  29 #include <iris/level_logger.h>
  30
  31 // this creates a logging thread, logs messages to stdout
  32 iris::level_logger g_log;
  33
  34 int main (int argc, char const *argv[]) {
  35     //configure thread level parameters, these should be done before any logging
  36     // queue size
  37     g_log.set_thread_queue_size(1024);
  38     // ring buffer size
  39     g_log.set_thread_ringbuf_size(10240);
  40
  41     g_log.info("Greetings from %s, bye %d\n", 'iris', 0);
  42
  43     //this tells logging thread to persist the data into file and waits
  44     g_log.sync_and_close();
  45
  46     return 0;
  47 }
  48 ```
  49 Using a `file_writer` to logs all messages into a file:
  50 ```c++
  51 #include <iris/level_logger.h>
  52 #include <iris/file_writer.h>
  53
  54 iris::file_writer writer("./log.txt");
  55 // this creates a logging thread
  56 iris::level_logger g_log(&writer, iris::TRACE);
  57
  58 int main (int argc, char const *argv[]) {
  59     //configure thread level parameters, these should be done before any logging
  60     // queue size
  61     g_log.set_thread_queue_size(1024);
  62     // ring buffer size
  63     g_log.set_thread_ringbuf_size(20480);
  64
  65     g_log.info("Greetings from %s, bye %d\n", 'iris', 0);
  66
  67     //this tells logging thread to persist the data into file and waits
  68     g_log.sync_and_close();
  69
  70     return 0;
  71 }
  72 ```
  73
  74 # Building & Installation
  75
  76 To build the library, simply clone the projet, go inside the `iris` direcotry and  run following commands.
  77 ```shell
  78 make
  79 make test
  80 make install
  81 ```
  82 To integrate `iris` into your program, link with `-liris` options.