README.md
1# spdlog
2
3Very fast, header only, C++ logging library. [](https://travis-ci.org/gabime/spdlog) [](https://ci.appveyor.com/project/gabime/spdlog)
4
5
6## Install
7#### Just copy the headers:
8
9* Copy the source [folder](https://github.com/gabime/spdlog/tree/master/include/spdlog) to your build tree and use a C++11 compiler.
10
11#### Or use your favourite package manager:
12
13* Ubuntu: `apt-get install libspdlog-dev`
14* Homebrew: `brew install spdlog`
15* FreeBSD: `cd /usr/ports/devel/spdlog/ && make install clean`
16* Fedora: `yum install spdlog`
17* Gentoo: `emerge dev-libs/spdlog`
18* Arch Linux: `pacman -S spdlog-git`
19* vcpkg: `vcpkg install spdlog`
20
21
22## Platforms
23 * Linux, FreeBSD, Solaris
24 * Windows (vc 2013+, cygwin/mingw)
25 * Mac OSX (clang 3.5+)
26 * Android
27
28## Features
29* Very fast - performance is the primary goal (see [benchmarks](#benchmarks) below).
30* Headers only, just copy and use.
31* Feature rich [call style](#usage-example) using the excellent [fmt](https://github.com/fmtlib/fmt) library.
32* Extremely fast asynchronous mode (optional) - using lockfree queues and other tricks to reach millions of calls/sec.
33* [Custom](https://github.com/gabime/spdlog/wiki/3.-Custom-formatting) formatting.
34* Conditional Logging
35* Multi/Single threaded loggers.
36* Various log targets:
37 * Rotating log files.
38 * Daily log files.
39 * Console logging (colors supported).
40 * syslog.
41 * Windows debugger (```OutputDebugString(..)```)
42 * Easily extendable with custom log targets (just implement a single function in the [sink](include/spdlog/sinks/sink.h) interface).
43* Severity based filtering - threshold levels can be modified in runtime as well as in compile time.
44
45
46
47## Benchmarks
48
49Below are some [benchmarks](bench) comparing popular log libraries under Ubuntu 64 bit, Intel i7-4770 CPU @ 3.40GHz
50
51#### Synchronous mode
52Time needed to log 1,000,000 lines in synchronous mode (in seconds, the best of 3 runs):
53
54|threads|boost log 1.54|glog |easylogging |spdlog|
55|-------|:-------:|:-----:|----------:|------:|
56|1| 4.169s |1.066s |0.975s |0.302s|
57|10| 6.180s |3.032s |2.857s |0.968s|
58|100| 5.981s |1.139s |4.512s |0.497s|
59
60
61#### Asynchronous mode
62Time needed to log 1,000,000 lines in asynchronous mode, i.e. the time it takes to put them in the async queue (in seconds, the best of 3 runs):
63
64|threads|g2log <sup>async logger</sup> |spdlog <sup>async mode</sup>|
65|:-------|:-----:|-------------------------:|
66|1| 1.850s |0.216s |
67|10| 0.943s |0.173s|
68|100| 0.959s |0.202s|
69
70
71
72
73## Usage Example
74```c++
75
76#include "spdlog/spdlog.h"
77
78#include <iostream>
79#include <memory>
80
81void async_example();
82void syslog_example();
83void user_defined_example();
84void err_handler_example();
85
86namespace spd = spdlog;
87int main(int, char*[])
88{
89 try
90 {
91 // Console logger with color
92 auto console = spd::stdout_color_mt("console");
93 console->info("Welcome to spdlog!");
94 console->error("Some error message with arg{}..", 1);
95
96 // Conditional logging example
97 auto i = 2;
98 console->warn_if(i != 0, "an important message");
99
100 // Formatting examples
101 console->warn("Easy padding in numbers like {:08d}", 12);
102 console->critical("Support for int: {0:d}; hex: {0:x}; oct: {0:o}; bin: {0:b}", 42);
103 console->info("Support for floats {:03.2f}", 1.23456);
104 console->info("Positional args are {1} {0}..", "too", "supported");
105 console->info("{:<30}", "left aligned");
106
107
108 spd::get("console")->info("loggers can be retrieved from a global registry using the spdlog::get(logger_name) function");
109
110 // Create basic file logger (not rotated)
111 auto my_logger = spd::basic_logger_mt("basic_logger", "logs/basic.txt");
112 my_logger->info("Some log message");
113
114 // Create a file rotating logger with 5mb size max and 3 rotated files
115 auto rotating_logger = spd::rotating_logger_mt("some_logger_name", "logs/mylogfile", 1048576 * 5, 3);
116 for (int i = 0; i < 10; ++i)
117 rotating_logger->info("{} * {} equals {:>10}", i, i, i*i);
118
119 // Create a daily logger - a new file is created every day on 2:30am
120 auto daily_logger = spd::daily_logger_mt("daily_logger", "logs/daily", 2, 30);
121 // trigger flush if the log severity is error or higher
122 daily_logger->flush_on(spd::level::err);
123 daily_logger->info(123.44);
124
125 // Customize msg format for all messages
126 spd::set_pattern("*** [%H:%M:%S %z] [thread %t] %v ***");
127 rotating_logger->info("This is another message with custom format");
128
129
130 // Runtime log levels
131 spd::set_level(spd::level::info); //Set global log level to info
132 console->debug("This message shold not be displayed!");
133 console->set_level(spd::level::debug); // Set specific logger's log level
134 console->debug("This message shold be displayed..");
135
136 // Compile time log levels
137 // define SPDLOG_DEBUG_ON or SPDLOG_TRACE_ON
138 SPDLOG_TRACE(console, "Enabled only #ifdef SPDLOG_TRACE_ON..{} ,{}", 1, 3.23);
139 SPDLOG_DEBUG(console, "Enabled only #ifdef SPDLOG_DEBUG_ON.. {} ,{}", 1, 3.23);
140
141 // Asynchronous logging is very fast..
142 // Just call spdlog::set_async_mode(q_size) and all created loggers from now on will be asynchronous..
143 async_example();
144
145 // syslog example. linux/osx only
146 syslog_example();
147
148 // android example. compile with NDK
149 android_example();
150
151 // Log user-defined types example
152 user_defined_example();
153
154 // Change default log error handler
155 err_handler_example();
156
157 // Apply a function on all registered loggers
158 spd::apply_all([&](std::shared_ptr<spd::logger> l)
159 {
160 l->info("End of example.");
161 });
162
163 // Release and close all loggers
164 spd::drop_all();
165 }
166 // Exceptions will only be thrown upon failed logger or sink construction (not during logging)
167 catch (const spd::spdlog_ex& ex)
168 {
169 std::cout << "Log init failed: " << ex.what() << std::endl;
170 return 1;
171 }
172}
173
174void async_example()
175{
176 size_t q_size = 4096; //queue size must be power of 2
177 spd::set_async_mode(q_size);
178 auto async_file = spd::daily_logger_st("async_file_logger", "logs/async_log.txt");
179 for (int i = 0; i < 100; ++i)
180 async_file->info("Async message #{}", i);
181}
182
183//syslog example
184void syslog_example()
185{
186#ifdef SPDLOG_ENABLE_SYSLOG
187 std::string ident = "spdlog-example";
188 auto syslog_logger = spd::syslog_logger("syslog", ident, LOG_PID);
189 syslog_logger->warn("This is warning that will end up in syslog..");
190#endif
191}
192
193// user defined types logging by implementing operator<<
194struct my_type
195{
196 int i;
197 template<typename OStream>
198 friend OStream& operator<<(OStream& os, const my_type &c)
199 {
200 return os << "[my_type i="<<c.i << "]";
201 }
202};
203
204#include <spdlog/fmt/ostr.h> // must be included
205void user_defined_example()
206{
207 spd::get("console")->info("user defined type: {}", my_type { 14 });
208}
209
210//
211//custom error handler
212//
213void err_handler_example()
214{
215 spd::set_error_handler([](const std::string& msg) {
216 std::cerr << "my err handler: " << msg << std::endl;
217 });
218 // (or logger->set_error_handler(..) to set for specific logger)
219}
220
221```
222
223## Documentation
224Documentation can be found in the [wiki](https://github.com/gabime/spdlog/wiki/1.-QuickStart) pages.
225
