generic-library/g3log
1
0
Fork 0
mirror of https://github.com/KjellKod/g3log.git synced 2024-12-13 10:42:56 +01:00
Code Issues Projects Releases Wiki Activity

improved documentation (#358)

Browse Source
This commit is contained in:
Kjell Hedström : Available for new Engineering Leadership and Engineering Opportunities 2020-06-06 15:39:27 -07:00 committed by GitHub
parent 68f3b174d9
commit f9ac8f5e08
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
1 changed files with 94 additions and 60 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

90
README.markdown
View File

@ -9,9 +9,41 @@ LOG(INFO) << "streaming API is as easy as ABC or " << 123;
LOGF(WARNING, "Printf-style syntax is also %s", "available");
```
# Content
* [What G3log is](#what-g3log-is)
* [Conditional Logging](#conditional-logging)
* [Design by Contract](#design-by-contract)
* [Detailed API documentation](API.markdown)
* [Benefits with g3log](#benefits-with-g3log)
* [G3log with sinks](#g3log-with-sinks)
* [Crazy simple to create a custom sink](#crazy-simple)
* [Code Examples](#code-examples)
* [Custom Sink Walkthrough](#custom-sink)
* [Default File Logger](#default-file-logger)
* [Building G3log](#building-g3log)
* [Prerequisites](#prerequisites)
* [Configuration Options](#configuration)
* [Build Commands](#build-commands)
* [Installation](#installation)
* [Packaging](#packaging)
* [Testing](#testing)
* [CMake Module](#cmake-module)
* Overview of the [API description](#overview-api-description)
* [Performance](#performance)
* [Feedback](#feedback)
* [Say Thanks](#say-thanks)
#### Conditional logging
## <a name="what-g3log-is">What G3Log is</a>
* ***G3log*** is the acting name for the third version of g2log and it stands for **g3log with dynamic sinks**
* G3log is an asynchronous, "crash-safe" logger. You can read more about it here [[g2log version]](
http://www.codeproject.com/Articles/288827/g2log-An-efficient-asynchronous-logger-using-Cplus)
* You can choose to use the default log receiver which saves all LOG calls to file, **or** you can choose to use your own custom made log receiver(s), **or** both, **or** as many sinks as you need.
#### <a name="#conditional-logging">Conditional logging</a>
int less = 1; int more = 2
LOG_IF(INFO, (less<more)) <<"If [true], then this text will be logged";
@ -20,7 +52,7 @@ LOGF(WARNING, "Printf-style syntax is also %s", "available");
#### Design-by-Contract
#### <a name="design-by-contract">Design-by-Contract</a>
*CHECK(false)* will trigger a "fatal" message. It will be logged, and then the
application will exit.
@ -30,17 +62,13 @@ CHECK(less > more) << "CHECK(false) triggers a FATAL message";
```
## What G3Log is:
* ***G3log*** is the acting name for the third version of g2log and it stands for **g3log with dynamic sinks**
* G3log is an asynchronous, "crash-safe" logger. You can read more about it here [[g2log version]](
http://www.codeproject.com/Articles/288827/g2log-An-efficient-asynchronous-logger-using-Cplus)
* You can choose to use the default log receiver which saves all LOG calls to file, **or** you can choose to use your own custom made log receiver(s), **or** both, **or** as many sinks as you need.
## Detailed API documentation
Please look at [API.markdown](API.markdown) for detailed API documentation
## Benefits you get when using G3log ##
## <a name="benefits-with-g3log">Benefits you get when using G3log</a>
1. Easy to use, clean syntax and a blazing fast logger.
2. All the slow log I/O disk access is done in a background thread. This ensures that the LOG caller can immediately continue with other tasks and do not have to wait for the LOG call to finish.
@ -60,21 +88,21 @@ The logger will catch certain fatal events *(Linux/OSX: signals, Windows: fatal
8. The code is given for free as public domain. This gives the option to change, use, and do whatever with it, no strings attached.
9. Two versions of g3log exist that are under active development.
9. Two versions of g3log exists.
* This version: *[g3log](https://github.com/KjellKod/g3log)* : which is made to facilitate easy adding of custom log receivers. Its tested on at least the following platforms with Linux(Clang/gcc), Windows (mingw, visual studio 2013). My recommendation is to go with g3log if you have full C++14 support (C++11 support up to version: https://github.com/KjellKod/g3log/releases/tag/1.3.1).
* *[g2log](https://bitbucket.org/KjellKod/g2log)*: The original. Simple, easy to modify and with the most OS support. Clients use g2log on environments such as OSX/Clang, Ubuntu, CentOS, Windows/mingw, Windows/Visual Studio. The focus on g2log is "slow to change" and compiler support. Only well, time tested, features from g3log will make it into g2log.
* *[g2log](https://bitbucket.org/KjellKod/g2log)*: The original. Simple, easy to modify and with the most OS support. Clients use g2log on environments such as OSX/Clang, Ubuntu, CentOS, Windows/mingw, Windows/Visual Studio. The focus on g2log is "slow to change" and compiler support. Only well, time tested, features from g3log will make it into g2log. Currently there is not active development or support on g2log but feel free to shoot me a question if you need assistance.
# G3log with sinks
# <a name="g3log-with-sinks">G3log with sinks</a>
[Sinks](http://en.wikipedia.org/wiki/Sink_(computing)) are receivers of LOG calls. G3log comes with a default sink (*the same as G3log uses*) that can be used to save log to file. A sink can be of *any* class type without restrictions as long as it can either receive a LOG message as a *std::string* **or** as a *g3::LogMessageMover*.
The *std::string* comes pre-formatted. The *g3::LogMessageMover* is a wrapped struct that contains the raw data for custom handling in your own sink.
A sink is *owned* by the G3log and is added to the logger inside a ```std::unique_ptr```. The sink can be called though its public API through a *handler* which will asynchronously forward the call to the receiving sink.
Silly example to show what is needed to make a custom sink that is using custom log formatting but only using that
It is <a name="crazy-simple">crazy simple to create a custom sink</a>. This example show what is needed to make a custom sink that is using custom log formatting but only using that
for adding color to the default log formatting. The sink forwards the colored log to cout
@ -112,14 +140,15 @@ struct CustomSink {
auto sinkHandle = logworker->addSink(std::make_unique<CustomSink>(),
&CustomSink::ReceiveLogMessage);
```
**More sinks** can be found in the repository **[github.com/KjellKod/g3sinks](https://github.com/KjellKod/g3sinks)**.
# Code Examples
Example usage where a custom sink is added. A function is called though the sink handler to the actual sink object.
# <a name="code-examples">Code Examples</a>
Example usage where a <a name="custom-sink">custom sink</a> is added. A function is called though the sink handler to the actual sink object.
```cpp
// main.cpp
#include <g3log/g3log.hpp>
@ -165,7 +194,7 @@ void SomeFunction() {
}
```
Example usage where a the default file logger is used **and** a custom sink is added
Example usage where a the <a name="default-file-logger">default file logger</a> is used **and** a custom sink is added
```cpp
// main.cpp
#include <g3log/g3log.hpp>
@ -194,7 +223,7 @@ int main(int argc, char**argv) {
# BUILDING g3log
# <a name="building-g3log">Building G3log</a>
```
git clone https://github.com/KjellKod/g3log
@ -203,7 +232,7 @@ mkdir build
cd build
```
## Prerequisites
## <a name="prerequisites">Prerequisites</a>
Assume you have got your shiny C++14 compiler installed, you also need these tools to build g3log from source:
- CMake (*Required*)
@ -216,7 +245,7 @@ Assume you have got your shiny C++14 compiler installed, you also need these too
cmake -DVERSION=1.3.2 ..
```
## Configuring
## <a name="configuration">Configuration Options</a>
g3log provides following CMake options (and default values):
```
$ cmake -LAH # List non-advanced cached variables. See `cmake --help` for more details.
@ -317,7 +346,7 @@ Linux/OSX package maintainers may be interested in the `CPACK_PACKAGING_INSTALL_
cmake .. -DCPACK_PACKAGING_INSTALL_PREFIX=/usr/local
```
## Building
## <a name="build-commands">Build Commands</a>
Once the configuration is done, you may build g3log with:
```
# Suppose you are still in the `build` directory. I won't repeat it anymore!
@ -335,7 +364,7 @@ msbuild g3log.sln /p:Configuration=Release
```
Windows users can also open the generated Visual Studio solution file and build it happily.
## Installing
## <a name="installing">Installation</a>
Install from source in a CMake way:
```
cmake --build . --target install
@ -346,7 +375,7 @@ sudo make install
```
You may also create a package first and install g3log with it. See the next section.
## Packaging
## <a name=packaging>Packaging</a>
A CMake way:
```
cmake --build . --config Release --target package
@ -385,7 +414,7 @@ sudo dpkg -i g3log-<version>-Linux.deb
```
will install the g3log library to `CPACK_PACKAGING_INSTALL_PREFIX`.
## Testing
## <a name="testing">Testing</a>
By default, tests will not be built. To enable unit testing, you should turn on `ADD_G3LOG_UNIT_TEST`.
@ -398,8 +427,13 @@ or:
make test
```
for Linux users.
or for a detailed gtest output of all the tests:
```
cd build;
../scripts/runAllTests.sh
```
## CMake module
## <a name="cmake-module">CMake module</a>
g3log comes with a CMake module. Once installed, it can be found under `${CMAKE_INSTALL_PREFIX}/lib/cmake/g3logger`. Users can use g3log in a CMake-based project this way:
@ -415,7 +449,7 @@ To make sure that CMake can find g3log(or g3logger), you also need to tell CMake
cmake .. -DCMAKE_PREFIX_PATH=<g3log's install prefix>
```
# API description
# Overview of the <a name="overview-api-description">API description</a>
Most of the API that you need for using g3log is described in this readme. For more API documentation and examples please continue to read the [API readme](API.markdown). Examples of what you will find here are:
* Sink creation and utilization
@ -431,20 +465,20 @@ Most of the API that you need for using g3log is described in this readme. For m
* CHECK calls
# Performance
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 laptop the average call, when doing extreme performance testing, will be about ~2 us.
# <a name="performance">Performance</a>
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 stabile 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/
# Feedback
# <a name="feedback">Feedback</a>
If you like this logger (or not) it would be nice with some feedback. That way I can improve g3log and g2log and it is also nice to see if someone is using it.
If you have ANY questions or problems please do not hesitate in contacting me on my blog
http://kjellkod.wordpress.com/2011/11/17/kjellkods-g2log-vs-googles-glog-are-asynchronous-loggers-taking-over
or at ```Hedstrom at KjellKod dot cc```
# Say Thanks
# <a name="say-thanks">Say Thanks</a>
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.
[![Donate](https://img.shields.io/badge/Donate-PayPal-green.svg)](https://www.paypal.me/g3log/25)