mirror of
https://github.com/KjellKod/g3log.git
synced 2024-12-13 10:42:56 +01:00
1 line
53 KiB
JSON
1 line
53 KiB
JSON
{"config":{"lang":["en"],"separator":"[\\s\\-]+","pipeline":["stopWordFilter"]},"docs":[{"location":"","title":"Introduction to G3log","text":"<p>introduction | detailed information | Configure & Build | API description | Custom log formatting</p>"},{"location":"#welcome-to-g3log","title":"Welcome to g3log","text":"<p>G3log is an asynchronous logger with three main features: 1. Intuitive <code>LOG(...)</code> API 2. <code>Design-by-contract</code> <code>CHECK(...)</code> functionality 3. Fatal crash handling for graceful shutdown of the logged process without loosing any log details up to the point of the crash</p> <p>The super quick introduction to g3log can be seen in the steps 1 - 9 below. </p> <p>For more in-depth information please see the full usage description in g3log_usage.md. The internal API for more advanced integration with g3log can be accessed in API.md</p>"},{"location":"#1-easy-usage-in-files","title":"1. Easy usage in files","text":"<p>Avoid deep dependency injection complexity and instead get access to the logger as easy as </p> <pre><code>#include <g3log/g3log.hpp>\n</code></pre>"},{"location":"#2-access-to-streaming-and-print_f-log-call-syntax","title":"2. Access to streaming and print_f log call syntax","text":"<p>Both streaming syntax <code>LOG</code> and print_f <code>LOGF</code> syntax are available. </p> <pre><code>LOGF(INFO, \"Hi log %d\", 123);\nLOG(INF) << \"Hi log \" << 123;\n\n</code></pre>"},{"location":"#3-conditional-logging","title":"3. Conditional logging","text":"<pre><code>LOG_IF(INFO, (1 < 2)) << \"If true this message will be logged\";\nLOGF_IF(INFO, (1 < 2), \"If true, then this %s will be logged\", \"message\");\n</code></pre>"},{"location":"#4-design-by-contract-framework","title":"4. Design-by-contract framework","text":"<pre><code>CHECK(less != more); // not fatal\nCHECK_F(less > more, \"CHECK(false) will trigger a fatal message\")\n</code></pre>"},{"location":"#5-handling-of-fatal","title":"5. Handling of fatal","text":"<p>By default g3log will capture fatal events such as <code>LOG(FATAL)</code>, <code>CHECK(false)</code> and otherwise fatal signals such as: </p> <pre><code> SIGABRT\n SIGFPE\n SIGILL\n SIGSEGV\n SIGTERM\n</code></pre> <p>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. </p> <p>If <code>object</code> symbols are available the fatal handler will attempt to push the stacktrace up to the fatal reason to the logging sink. </p>"},{"location":"#5b-overriding-and-customization-of-fatal-event-handling","title":"5b. Overriding and customization of fatal event handling","text":"<p>For overriding fatal error handling to use your own, or to add code <code>hooks</code> that you want to execute please see the API.md doc. </p>"},{"location":"#6-default-and-custom-logging-levels","title":"6. Default and Custom logging levels","text":"<p>The default logging levels are <code>DEBUG</code>, <code>INFO</code>, <code>WARNING</code> and <code>FATAL</code>. You can define your own logging levels or completely replace the logging levels. Ref: API.md</p>"},{"location":"#7-log-filtering","title":"7. Log filtering","text":"<p>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</p>"},{"location":"#8-3rd-party-and-custom-logging-sinks","title":"8. 3rd party and custom logging sinks","text":"<p>The default logging sink has no external 3rd party dependencies. For more logging sinks please see github/Kjellod/g3sinks</p> <ul> <li>log rotate</li> <li>log to syslog</li> <li>log to colored terminal output</li> <li>log rotate with filter</li> </ul> <p>See the API.md for more information about the simple steps to creating your own logging sink.</p>"},{"location":"#9-log-instantiation","title":"9. Log instantiation","text":"<p>With the default application name left as is (i.e. \"g3log\") a creation of the logger could look something like this: </p> <pre><code> const std::string directory = \"./\";\n const std::string name = \"TestLogFile\";\n auto worker = g3::LogWorker::createLogWorker();\n auto handle = worker->addDefaultLogger(name, directory);\n</code></pre> <p>The resulting filename would be something like: </p> <pre><code> ./TestLogFile.g3log.20160217-001406.log\n</code></pre>"},{"location":"#performance","title":"Performance","text":"<p>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.</p> <p>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/</p>"},{"location":"#continuos-integration","title":"Continuos Integration","text":"<p>The g3log repository is evaluating both github actions and CircleCI for executing test coverage, installation and document generation. For windows the repo is still relying on appveyor. In case you want to look into change any of these setups the following files are the ones of interest. </p> <pre><code>1. appveyor --> g3log/appveyor.yml\n2. circleCI --> g3log/.circleci/config.yml\n3. github actions --> g3log/.github/workflows/*.yml\n\n\n</code></pre>"},{"location":"#feedback","title":"Feedback","text":"<p>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. </p> <p>If you have ANY questions or problems please do not hesitate in contacting me at <code>Hedstrom @ Kjellod. cc</code></p>"},{"location":"#say-thanks","title":"Say Thanks","text":"<p>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.</p> <p></p> <ul> <li>$5 for a cup of coffee</li> <li>$25 for a late evening coding with takeout </li> </ul> <p>Cheers</p> <p>Kjell (a.k.a. KjellKod)</p> <p>introduction | detailed information | Configure & Build | API description | Custom log formatting</p>"},{"location":"API/","title":"API description","text":"<p>introduction | detailed information | Configure & Build | API description | Custom log formatting</p>"},{"location":"API/#high-level-description-of-g3log","title":"High Level Description of g3log","text":"<p>The <code>g3log</code> logger is an asynchronous, crash-safe logging library designed for C++ applications. It allows for logging messages to various sinks without blocking the main application thread. Below is a high-level overview of how the <code>g3log</code> logger works.</p>"},{"location":"API/#asynchronous-logging","title":"Asynchronous Logging","text":"<p>The logger operates on a separate thread, ensuring that the main application thread is not blocked by I/O operations when logging messages. This is achieved by using a background worker (<code>LogWorker</code>) that queues log messages and processes them asynchronously.</p>"},{"location":"API/#logworker-and-sinks","title":"LogWorker and Sinks","text":"<p>The <code>LogWorker</code> is responsible for managing the logging sinks. A sink is an object that defines where and how log messages are outputted (e.g., to a file, console, or over the network). Users can add custom sinks to the <code>LogWorker</code> using the <code>addSink</code> method, which takes a unique pointer to a sink object and a function pointer to the method that will save the log message.</p>"},{"location":"API/#signal-handling","title":"Signal Handling","text":"<p>The logger includes a signal handler for Unix-like systems that captures fatal signals (e.g., <code>SIGSEGV</code>, <code>SIGABRT</code>) and ensures that all pending log messages are flushed to the sinks before the application exits. The signal handler function (<code>signalHandler</code>) is registered to handle these signals and will attempt to generate a stack trace when a fatal signal is received. This stack trace is then logged, providing valuable debugging information.</p>"},{"location":"API/#stack-trace-generation","title":"Stack Trace Generation","text":"<p>Upon receiving a fatal signal, the <code>signalHandler</code> function will call <code>stackdump</code> to generate a stack trace. This function uses platform-specific calls to retrieve the stack frames and attempts to demangle the function names to make the stack trace more readable.</p>"},{"location":"API/#log-message-formatting","title":"Log Message Formatting","text":"<p>Log messages can be formatted using either a streaming API (e.g., <code>LOG(INFO) << \"message\";</code>) or a printf-like syntax (e.g., <code>LOGF(INFO, \"message %d\", value);</code>). This provides flexibility in how messages are constructed.</p>"},{"location":"API/#log-levels","title":"Log Levels","text":"<p>The library supports various log levels (e.g., <code>DEBUG</code>, <code>INFO</code>, <code>WARNING</code>, <code>FATAL</code>). Users can define custom log levels or modify the existing ones. The log levels can be dynamically enabled or disabled at runtime if the <code>G3_DYNAMIC_LOGGING</code> preprocessor definition is set.</p>"},{"location":"API/#crash-safety","title":"Crash Safety","text":"<p>In the event of a crash, the logger is designed to be crash-safe by catching fatal events and ensuring that all log messages are flushed to the sinks before the process exits.</p>"},{"location":"API/#customization","title":"Customization","text":"<p>The library allows for extensive customization, including adding custom log levels, creating custom sinks, and overriding the default signal handling behavior.</p>"},{"location":"API/#thread-safety","title":"Thread Safety","text":"<p>The <code>g3log</code> logger is thread-safe, meaning it can be used from multiple threads without the need for additional synchronization.</p>"},{"location":"API/#public-domain-software","title":"Public Domain Software","text":"<p>The <code>g3log</code> code is released into the public domain, allowing users to use, modify, and distribute it freely without restrictions.</p>"},{"location":"API/#logging-and-fatal-events-explained","title":"Logging and Fatal Events Explained","text":"<p>diagrams created with https://mermaid.live </p>"},{"location":"API/#api-description","title":"API description","text":"<p>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. Examples of what you will find here are: </p>"},{"location":"API/#logging-api-log-calls","title":"Logging API: LOG calls","text":"<p>LOG calls can follow streaming <code>LOG(INFO) << \"some text\"</code> or printf-like syntax <code>LOGF(WARNING, \"some number %d\", 123);</code></p> <p>Conditional logging is made with <code>LOG_IF(INFO, <boolean-expression>) << \" some text\"</code> or <code>LOGF_IF(WARNING, <boolean-expression>) << \" some text\".</code> Only if the expressions evaluates to <code>true</code> will the logging take place. </p> <p>Example: <code>LOG_IF(INFO, 1 != 200) << \" some text\";</code> or <code>LOG_IF(FATAL, SomeFunctionCall()) << \" some text\";</code></p> <p>A call using FATAL logging level, such as the <code>LOG_IF(FATAL,...)</code> example above, will after logging the message at <code>FATAL</code>level also kill the process. It is essentially the same as a <code>CHECK(<boolea-expression>) << ...</code> with the difference that the <code>CHECK(<boolean-expression)</code> triggers when the expression evaluates to <code>false</code>.</p>"},{"location":"API/#contract-api-check-calls","title":"Contract API: CHECK calls","text":"<p>The contract API follows closely the logging API with <code>CHECK(<boolean-expression>) << ...</code> for streaming or (*) <code>CHECKF(<boolean-expression>, ...);</code> for printf-style.</p> <p>If the <code><boolean-expression></code> evaluates to false then the the message for the failed contract will be logged in FIFO order with previously made messages. The process will then shut down after the message is sent to the sinks and the sinks have dealt with the fatal contract message. </p> <p><code>CHECK_F(<boolean-expression>, ...);</code> was the the previous API for printf-like CHECK. It is still kept for backwards compatability but is exactly the same as <code>CHECKF</code></p>"},{"location":"API/#logfatal-or-checkfalse","title":"LOG(fATAL) or CHECK(false)","text":"<p>Fatal logging or failed `CHECK calls follows the same handling. </p>"},{"location":"API/#logging-levels","title":"Logging levels","text":"<p>The default logging levels are <code>DEBUG</code>, <code>INFO</code>, <code>WARNING</code> and <code>FATAL</code> (see FATAL usage above). The logging levels are defined in loglevels.hpp.</p> <p>For some windows framework there is a clash with the <code>DEBUG</code> logging level. One of the CMake Build options can be used to then change offending default level from <code>DEBUG</code> TO <code>DBUG</code>.</p> <p>**CMake option: (default OFF) ** <code>cmake -DCHANGE_G3LOG_DEBUG_TO_DBUG=ON ..</code> </p> <p>### disable/enabled levels at runtime Logging levels can be disabled at runtime. The logic for this happens in loglevels.hpp, loglevels.cpp and g3log.hpp.</p> <p>There is a cmake option to enable the dynamic enable/disable of levels. When the option is enabled there will be a slight runtime overhead for each <code>LOG</code> call when the enable/disable status is checked. For most intent and purposes this runtime overhead is negligable. </p> <p>There is no runtime overhead for internally checking if a level is enabled//disabled if the cmake option is turned off. If the dynamic logging cmake option is turned off then all logging levels are enabled.</p> <p>CMake option: (default OFF) <code>cmake -DUSE_DYNAMIC_LOGGING_LEVELS=ON ..</code> </p> <p>### custom logging levels Custom logging levels can be created and used. When defining a custom logging level you set the value for it as well as the text for it. You can re-use values for other levels such as INFO, WARNING etc or have your own values. Any value with equal or higher value than the FATAL value will be considered a FATAL logging level. </p> <p>To keep in mind when adding your own custom levels. 1. If the cmake option <code>G3_DYNAMIC_LOGGING</code> is enabled then you must use <code>g3::only_change_at_initialization::addLogLevel(...)</code> to give g3log a record of your logging level and if it is an enabled or disbled logging level. 1. If the cmake <code>G3_DYNAMIC_LOGGING</code> is turned OFF, then giving g3log a record of your logging level with 'addLogLevel(...) is not needed since no <code>\"disbled/enabled\"</code> check will happen - all logging levels will be considered enabled.</p> <p>Example: ```cpp // In CustomLoggingLevels.hpp #include <p>// all values with a + 1 higher than their closest equivalet // they could really have the same value as well.</p> <p>const LEVELS FYI {DEBUG.value + 1, {\"For Your Information\"}}; const LEVELS CUSTOM {INFO.value + 1, {\"CUSTOM\"}}; const LEVELS SEVERE {WARNING.value +1, {\"SEVERE\"}}; const LEVELS DEADLY {FATAL.value + 1, {\"DEADLY\"}}; ```</p> <p>More examples can be viwed in the unit tests. </p>"},{"location":"API/#sink-creation-and-utilization","title":"Sink creation and utilization","text":"<p>The default sink for g3log is the one as used in g2log. It is a simple file sink with a limited API. The details for the default file sink can be found in filesink.hpp, filesink.cpp, filesinkhelper.ipp</p> <p>More sinks can be found at g3sinks (log rotate, log rotate with filtering on levels)</p> <p>A logging sink is not required to be a subclass of a specific type. The only requirement of a logging sink is that it can receive a logging message of </p>"},{"location":"API/#using-the-default-sink","title":"Using the default sink","text":"<p>Sink creation is defined in logworker.hpp and used in logworker.cpp. For in-depth knowlege regarding sink implementation details you can look at sinkhandle.hpp and sinkwrapper.hpp</p> <pre><code> std::unique_ptr<FileSinkHandle> addDefaultLogger(\n const std::string& log_prefix\n , const std::string& log_directory\n , const std::string& default_id = \"g3log\");\n</code></pre> <p>With the default id left as is (i.e. \"g3log\") a creation of the logger in the unit test \"test_filechange\" would look like this</p> <pre><code> const std::string directory = \"./\";\n const std::string name = \"(ReplaceLogFile)\";\n auto worker = g3::LogWorker::createLogWorker();\n auto handle = worker->addDefaultLogger(name, directory);\n</code></pre> <p>The resulting filename would be something like: </p> <pre><code> ./(ReplaceLogFile).g3log.20160217-001406.log\n</code></pre>"},{"location":"API/#designate-the-sink-functions-log-entry-receving-function","title":"Designate the sink function's log entry receving function","text":"<p>The default log formatting look can be overriden by any sink. If the sink receiving function calls <code>toString()</code> then the default log formatting will be used. If the sink receiving function calls <code>toString(&XFunc)</code> then the <code>XFunc</code>will be used instead (see <code>LogMessage.h/cpp</code> for code details if it is not clear). (<code>XFunc</code> is a place holder for your formatting function of choice). </p> <p>The API for the function-ptr to pass in is </p> <pre><code>std::string (*) (const LogMessage&)\n</code></pre> <p>or for short as defined in <code>LogMessage.h</code></p> <pre><code>using LogDetailsFunc = std::string (*) (const LogMessage&);\n</code></pre>"},{"location":"API/#log-format-customization","title":"Log format customization","text":"<p>Please seeAPI_custom_formatting.md</p>"},{"location":"API/#log-flushing","title":"LOG flushing","text":"<p>The default file sink will flush each log entry at set intervals. The default buffer size for flushing is set to 100 entries. You can adjust this down to 1, or as high as makes sense for your system. Please see FileSink </p> <p>Even more flushing policies and log rotations can be found at g3sinks logrotate and LogRotateWithFilters.</p> <p>At shutdown all enqueued logs will be flushed to the sink. At a discovered fatal event (SIGSEGV et.al) all enqueued logs will be flushed to the sink.</p> <p>A programmatically triggered abrupt process exit such as a call to <code>exit(0)</code> will of course not get the enqueued log entries flushed. Similary a bug that does not trigger a fatal signal but a process exit will also not get the enqueued log entries flushed. G3log can catch several fatal crashes and it deals well with RAII exits but magic is so far out of its' reach.</p> <p></p>"},{"location":"API/#g3log-and-sink-usage-code-example","title":"G3log and Sink Usage Code Example","text":"<p>Example usage where a logrotate sink (g3sinks) is added. In the example it is shown how the logrotate API is called. The logrotate limit is changed from the default to instead be 10MB. The limit is changed by calling the sink handler which passes the function call through to the actual logrotate sink object.</p> <pre><code>\n// main.cpp\n#include <g3log/g3log.hpp>\n#include <g3log/logworker.h>\n#include <g3sinks/LogRotate.h>\n#include <memory>\n\nint main(int argc, char**argv) {\n using namespace g3;\n std::unique_ptr<LogWorker> logworker{ LogWorker::createLogWorker() };\n auto sinkHandle = logworker->addSink(std::make_unique<LogRotate>(),\n &LogRotate::save);\n\n // initialize the logger before it can receive LOG calls\n initializeLogging(logworker.get()); \n\n // You can call in a thread safe manner public functions on the logrotate sink\n // The call is asynchronously executed on your custom sink.\n const int k10MBInBytes = 10 * 1024 * 1024;\n std::future<void> received = sinkHandle->call(&LogRotate::setMaxLogSize, k10MBInBytes);\n\n // Run the main part of the application. This can be anything of course, in this example\n // we'll call it \"RunApplication\". Once this call exits we are in shutdown mode\n RunApplication();\n\n // If the LogWorker is initialized then at scope exit the g3::shutDownLogging() will be \n // called automatically. \n // \n // This is important since it protects from LOG calls from static or other entities that will go out of\n // scope at a later time. \n //\n // It can also be called manually if for some reason your setup is different then the one highlighted in\n // this example\n g3::shutDownLogging();\n}\n</code></pre>"},{"location":"API/#dynamic-message-sizing","title":"Dynamic Message Sizing","text":"<p>The default build uses a fixed size buffer for formatting messages. The size of this buffer is 2048 bytes. If an incoming message results in a formatted message that is greater than 2048 bytes, it will be bound to 2048 bytes and will have the string <code>[...truncated...]</code> appended to the end of the bound message. There are cases where one would like to dynamically change the size at runtime. For example, when debugging payloads for a server, it may be desirable to handle larger message sizes in order to examine the whole payload. Rather than forcing the developer to rebuild the server, dynamic message sizing could be used along with a config file which defines the message size at runtime.</p> <p>This feature supported as a CMake option:</p> <p>CMake option: (default OFF) <code>cmake -DUSE_G3_DYNAMIC_MAX_MESSAGE_SIZE=ON ..</code></p> <p>The following is an example of changing the size for the message.</p> <pre><code> g3::only_change_at_initialization::setMaxMessageSize(10000);\n</code></pre>"},{"location":"API/#fatal-handling","title":"Fatal handling","text":"<p>The default behaviour for G3log is to catch several fatal events before they force the process to exit. After catching a fatal event a stack dump is generated and all log entries, up to the point of the stack dump are together with the dump flushed to the sink(s).</p> <p></p>"},{"location":"API/#linuxnix","title":"Linux/*nix","text":"<p>The default fatal handling on Linux deals with fatal signals. At the time of writing these signals were <code>SIGABRT, SIGFPE, SIGILL, SIGSEGV, SIGTERM</code>. The Linux fatal handling is handled in crashhandler.hpp and crashhandler_unix.cpp</p> <p>A signal that commonly is associated with voluntarily process exit is <code>SIGINT</code> (ctrl + c) G3log does not deal with it. </p> <p>The fatal signals can be disabled or changed/added . </p> <p>An example of a Linux stackdump as shown in the output from the fatal example g3log-FATAL-sigsegv. ``` * FATAL SIGNAL RECEIVED * \"Received fatal signal: SIGSEGV(11) PID: 6571</p> <pre><code>***** SIGNAL SIGSEGV(11)\n\n******* STACKDUMP *******\n stack dump [1] ./g3log-FATAL-sigsegv() [0x42a500]\n stack dump [2] /lib/x86_64-linux-gnu/libpthread.so.0+0x10340 [0x7f83636d5340]\n\n stack dump [3] ./g3log-FATAL-sigsegv : example_fatal::tryToKillWithAccessingIllegalPointer(std::unique_ptr<std::__cxx11::basic_string<char, std::char_traits<char>, std::allocator<char> >, std::default_delete<std::__cxx11::basic_string<char, std::char_traits<char>, std::allocator<char> > > >)+0x119 [0x4107b9]\n stack dump [4] ./g3log-FATAL-sigsegvmain+0xdec [0x40e51c]\n stack dump [5] /lib/x86_64-linux-gnu/libc.so.6__libc_start_main+0xf5 [0x7f8363321ec5]\n stack dump [6] ./g3log-FATAL-sigsegv() [0x40ffa2]\n\nExiting after fatal event (FATAL_SIGNAL). Fatal type: SIGSEGV\nLog content flushed sucessfully to sink\n\n\"\ng3log g3FileSink shutdown at: 16:33:18\n\n```\n</code></pre>"},{"location":"API/#custom-fatal-handling-override-defaults","title":"Custom fatal handling - override defaults","text":"<p>By default the fatal signals are defined in https://github.com/KjellKod/g3log/tree/master/src/g3log.cpp as <code>SIGABRT SIGFPE SIGILL SIGSEGV SIGTERM</code> If you want to define your own set of fatal signals, override the default ones, then this can be done as shown in src/g3log/crashhandler.hpp <code>cpp // Example when SIGTERM is skipped due to ZMQ usage g3::overrideSetupSignals({ {SIGABRT, \"SIGABRT\"}, {SIGFPE, \"SIGFPE\"}, {SIGILL, \"SIGILL\"}, {SIGSEGV, \"SIGSEGV\"}});</code></p>"},{"location":"API/#pre-fatal-hook","title":"Pre fatal hook","text":"<p>You can define a custom call back function that will be called before the fatal signal handling re-emits the <code>fatal</code> signal. See src/g3log/g3log.hpp for details. <code>// Example of how to enforce important shutdown cleanup even in the event of a fatal crash: g3::setFatalPreLoggingHook([]{ cleanup(); });</code></p>"},{"location":"API/#disable-fatal-handling","title":"Disable fatal handling","text":"<p>Fatal signal handling can be disabled with a CMake option: <code>ENABLE_FATAL_SIGNALHANDLING</code>. See Options.cmake for more details</p>"},{"location":"API/#pid1-fatal-signal-recommendations","title":"PID1 Fatal Signal Recommendations","text":"<p>If you are using g3log on a PID1 process then you absolutely should provide your own signal handling (ref: issue 269) as g3log re-emits the fatal signal after it has restored the previous signal handler for that signal. PID1 processed do not shutdown the process for a normal fatal signal so the choice to exit the PID1 process after such a signal must be taken by the coder - not by g3log.</p>"},{"location":"API/#windows","title":"Windows","text":"<p>Windows fatal handling also deals with fatal signals just like Linux. In addition to fatal signals it also deals with unhandled exceptions, vectored exceptions. Windows fatal handling is handled in crashhandler.hpp, crashhandler_windows.cpp, stacktrace_windows.hpp, stacktrace_windows.cpp</p> <p>An example of a Windows stackdump as shown in the output from the fatal example g3log-FATAL-sigsegv. </p> <p>introduction | detailed information | Configure & Build | API description | Custom log formatting</p>"},{"location":"API_custom_formatting/","title":"API for custom log formatting","text":"<p>introduction | detailed information | Configure & Build | API description | Custom log formatting</p>"},{"location":"API_custom_formatting/#custom-log-formatting","title":"Custom LOG formatting","text":""},{"location":"API_custom_formatting/#overriding-the-default-file-sinks-file-header","title":"Overriding the Default File Sink's file header","text":"<p>The default file header can be customized in the default file sink in calling </p> <pre><code> FileSink::overrideLogHeader(std::string);\n</code></pre>"},{"location":"API_custom_formatting/#overriding-the-default-filesinks-log-formatting","title":"Overriding the Default FileSink's log formatting","text":"<p>The default log formatting is defined in <code>LogMessage.hpp</code></p> <pre><code> static std::string DefaultLogDetailsToString(const LogMessage& msg);\n</code></pre>"},{"location":"API_custom_formatting/#adding-thread-id-to-the-log-formatting","title":"Adding thread ID to the log formatting","text":"<p>An \"all details\" log formatting function is also defined - this one also adds the \"calling thread's ID\"</p> <pre><code> static std::string FullLogDetailsToString(const LogMessage& msg);\n</code></pre>"},{"location":"API_custom_formatting/#override-default-sink-log-formatting","title":"Override default sink log formatting","text":"<p>For convenience the Default sink has a function for doing exactly this</p> <pre><code> void overrideLogDetails(LogMessage::LogDetailsFunc func);\n</code></pre> <p>Example code for replacing the default log formatting for \"full details\" formatting (it adds thread ID)</p> <pre><code> auto worker = g3::LogWorker::createLogWorker();\n auto handle= worker->addDefaultLogger(argv[0], path_to_log_file);\n g3::initializeLogging(worker.get());\n handle->call(&g3::FileSink::overrideLogDetails, &LogMessage::FullLogDetailsToString);\n</code></pre> <p>See test_message.cpp for details and testing</p> <p>Example code for overloading the formatting of a custom sink. The log formatting function will be passed into the <code>LogMessage::toString(...)</code> this will override the default log formatting</p> <p>Example</p> <pre><code>namespace {\n std::string MyCustomFormatting(const LogMessage& msg) {\n ... how you want it ...\n }\n }\n\n void MyCustomSink::ReceiveLogEntry(LogMessageMover message) {\n std::string formatted = message.get().toString(&MyCustomFormatting) << std::flush;\n }\n...\n...\n auto worker = g3::LogWorker::createLogWorker();\n auto sinkHandle = worker->addSink(std::make_unique<MyCustomSink>(),\n &MyCustomSink::ReceiveLogMessage);\n // ReceiveLogMessage(...) will used the custom formatting function \"MyCustomFormatting(...)\n\n</code></pre> <p>introduction | detailed information | Configure & Build | API description | Custom log formatting</p>"},{"location":"building/","title":"Configure, Build, Package, Install and Test","text":"<p>introduction | detailed information | Configure & Build | API description | Custom log formatting</p>"},{"location":"building/#configure-build-package-install-and-test-g3log","title":"Configure, build, package, install and test g3log","text":""},{"location":"building/#example-project-with-g3log","title":"Example Project with g3log","text":"<p>An example project integration of g3log, both statially and dynamically built can be found at g3log_example_integration</p>"},{"location":"building/#building-it-standalone-to-try-out-is-as-easy-as","title":"Building it standalone to try out is as easy as:","text":"<pre><code>git clone https://github.com/KjellKod/g3log\ncd g3log\nmkdir build\ncd build\n</code></pre>"},{"location":"building/#prerequisites","title":"Prerequisites","text":"<p>You also need these tools to build g3log from source: - CMake (Required)</p> <p>g3log uses CMake as a one-stop solution for configuring, building, installing, packaging and testing on Windows, Linux and OSX.</p> <ul> <li>Git (Optional but Recommended)</li> </ul> <p>When building g3log it uses git to calculate the software version from the commit history of this repository. If you don't want that, or your setup does not have access to git, or you download g3log source archive from the GitHub Releases page so that you do not have the commit history downloaded, you can instead pass in the version as part of the CMake build arguments. See this issue for more information. <code>cmake -DVERSION=1.3.2 ..</code></p>"},{"location":"building/#configuration-options","title":"Configuration Options","text":"<p>g3log provides following CMake options (and default values):</p> <pre><code>$ cmake -LAH # List non-advanced cached variables. See `cmake --help` for more details.\n\n...\n\n// Fatal (fatal-crashes/contract) examples\nADD_FATAL_EXAMPLE:BOOL=ON\n\n// g3log performance test\nADD_G3LOG_BENCH_PERFORMANCE:BOOL=OFF\n\n// g3log unit tests\nADD_G3LOG_UNIT_TEST:BOOL=OFF\n\n// Use DBUG logging level instead of DEBUG.\n// By default DEBUG is the debugging level\nCHANGE_G3LOG_DEBUG_TO_DBUG:BOOL=OFF\n\n\n// Windows only: Use __FUNCSIG__ instead of the default __FUNCTION__ \n// to show LOG function location\n// WARNING: using this in heavily templated code, like boost can expand\n// the function name into massive size\nWINDOWS_FUNCSIG:BOOL=OFF\n\n\n// gcc/clang only: Use __PRETTY_FUNCTION__ instead of the default __FUNCTION__ \n// to show LOG function location\n// WARNING: using this in heavily templated code, like boost can expand\n// the function name into massive size\nPRETTY_FUNCTION:BOOL=OFF\n\n\n// Specifies the build type on single-configuration generators.\n// Possible values are empty, Debug, Release, RelWithDebInfo, MinSizeRel, \u2026\nCMAKE_BUILD_TYPE:STRING=\n\n// Install path prefix, prepended onto install directories.\n// This variable defaults to /usr/local on UNIX\n// and c:/Program Files/${PROJECT_NAME} on Windows.\nCMAKE_INSTALL_PREFIX:PATH=\n\n// The prefix used in the built package.\n// On Linux, if this option is not set:\n// 1) If CMAKE_INSTALL_PREFIX is given, then it will be\n// set with the value of CMAKE_INSTALL_PREFIX by g3log.\n// 2) Otherwise, it will be set as /usr/local by g3log.\nCPACK_PACKAGING_INSTALL_PREFIX:PATH=\n\n// Enable Visual Studio break point when receiving a fatal exception.\n// In __DEBUG mode only\nDEBUG_BREAK_AT_FATAL_SIGNAL:BOOL=OFF\n\n// Vectored exception / crash handling with improved stack trace\nENABLE_FATAL_SIGNALHANDLING:BOOL=ON\n\n// Vectored exception / crash handling with improved stack trace\nENABLE_VECTORED_EXCEPTIONHANDLING:BOOL=ON\n\n// iOS version of library.\nG3_IOS_LIB:BOOL=OFF\n\n// Log full filename\nG3_LOG_FULL_FILENAME:BOOL=OFF\n\n// Build shared library\nG3_SHARED_LIB:BOOL=ON\n\n// Build shared runtime library MSVC\nG3_SHARED_RUNTIME:BOOL=ON\n\n// Turn ON/OFF log levels.\n// An disabled level will not push logs of that level to the sink.\n// By default dynamic logging is disabled\nUSE_DYNAMIC_LOGGING_LEVELS:BOOL=OFF\n\n// Use dynamic memory for message buffer during log capturing\nUSE_G3_DYNAMIC_MAX_MESSAGE_SIZE:BOOL=OFF\n\n...\n</code></pre> <p>For additional option context and comments please also see Options.cmake</p> <p>If you want to leave everything as it was, then you should:</p> <pre><code>cmake ..\n</code></pre> <p>You may also specify one or more of those options listed above from the command line. For example, on Windows:</p> <pre><code>cmake .. -G \"Visual Studio 15 2017\"\n -DG3_SHARED_LIB=OFF\n -DCMAKE_INSTALL_PREFIX=C:/g3log\n -DADD_G3LOG_UNIT_TEST=ON\n -DADD_FATAL_EXAMPLE=OFF\n</code></pre> <p>will use a Visual Studio 2017 solution generator, build g3log as a static library, headers and libraries will be installed to <code>C:\\g3log</code> when installed from source, enable unit testing, but do not build fatal example.</p> <p>MinGW users on Windows may find they should use a different generator:</p> <pre><code>cmake .. -G \"MinGW Makefiles\"\n</code></pre> <p>By default, headers and libraries will be installed to <code>/usr/local</code> on Linux when installed from build tree via <code>make install</code>. You may overwrite it by:</p> <pre><code>cmake .. -DCMAKE_INSTALL_PREFIX=/usr\n</code></pre> <p>This will install g3log to <code>/usr</code> instead of <code>/usr/local</code>.</p> <p>Linux/OSX package maintainers may be interested in the <code>CPACK_PACKAGING_INSTALL_PREFIX</code>. For example:</p> <pre><code>cmake .. -DCPACK_PACKAGING_INSTALL_PREFIX=/usr/local\n</code></pre>"},{"location":"building/#build-commands","title":"Build Commands","text":"<p>Once the configuration is done, you may build g3log with:</p> <pre><code># Suppose you are still in the `build` directory. I won't repeat it anymore!\ncmake --build . --config Release\n</code></pre> <p>You may also build it with a system-specific way.</p> <p>On Linux, OSX and MinGW:</p> <pre><code>make\n</code></pre> <p>On Windows:</p> <pre><code>msbuild g3log.sln /p:Configuration=Release\n</code></pre> <p>Windows users can also open the generated Visual Studio solution file and build it happily.</p>"},{"location":"building/#installation","title":"Installation","text":"<p>Install from source in a CMake way:</p> <pre><code>cmake --build . --target install\n</code></pre> <p>Linux users may also use:</p> <pre><code>sudo make install\n</code></pre> <p>You may also create a package first and install g3log with it. See the next section.</p>"},{"location":"building/#packaging","title":"Packaging","text":"<p>A CMake way:</p> <pre><code>cmake --build . --config Release --target package\n</code></pre> <p>or</p> <pre><code>cpack -C Release\n</code></pre> <p>if the whole library has been built in the previous step. It will generate a ZIP package on Windows, and a DEB package on Linux.</p> <p>Linux users may also use a Linux way:</p> <pre><code>make package\n</code></pre> <p>If you want to use a different package generator, you should specify a <code>-G</code> option.</p> <p>On Windows:</p> <pre><code>cpack -C Release -G NSIS;7Z\n</code></pre> <p>this will create a installable NSIS package and a 7z package.</p> <p>Note: To use the NSIS generator, you should install <code>NSIS</code> first.</p> <p>On Linux:</p> <pre><code>cpack -C Release -G TGZ\n</code></pre> <p>this will create a .tar.gz archive for you.</p> <p>Once done, you may install or uncompress the package file to the target machine. For example, on Debian or Ubuntu:</p> <pre><code>sudo dpkg -i g3log-<version>-Linux.deb\n</code></pre> <p>will install the g3log library to <code>CPACK_PACKAGING_INSTALL_PREFIX</code>.</p>"},{"location":"building/#testing","title":"Testing","text":"<p>By default, tests will be built. To disable unit testing, you should turn off <code>ADD_G3LOG_UNIT_TEST</code>.</p> <p>Suppose the build process has completed, then you can run the tests with:</p> <pre><code>ctest -C Release\n</code></pre> <p>or:</p> <pre><code>make test\n</code></pre> <p>for Linux users. or for a detailed gtest output of all the tests:</p> <pre><code>cd build;\n../scripts/runAllTests.sh\n</code></pre>"},{"location":"building/#cmake-module","title":"CMake module","text":"<p>g3log comes with a CMake module. Once installed, it can be found under <code>${CMAKE_INSTALL_PREFIX}/lib/cmake/g3log</code>. Users can use g3log in a CMake-based project this way:</p> <pre><code>find_package(g3log CONFIG REQUIRED)\ntarget_link_libraries(main PRIVATE g3log)\n</code></pre> <p>To make sure that CMake can find g3log, you also need to tell CMake where to search for it:</p> <pre><code>cmake .. -DCMAKE_PREFIX_PATH=<g3log's install prefix>\n</code></pre>"},{"location":"building/#build-options","title":"Build Options","text":"<p>The build options are defined in the file Options.cmake</p> <p>build options are generated and saved to a header file. This avoid having to set the define options in the client source code</p> <p>introduction | detailed information | Configure & Build | API description | Custom log formatting</p>"},{"location":"codespaces/","title":"Codespaces","text":"<p>You can experiment with codespaces and g3log. </p>"},{"location":"codespaces/#learn-about-github-codespaces","title":"Learn about Github Codespaces","text":"<p>For an introduction to codespaces you can check out example c++ codespace and using-github-codespaces-with-github-cli</p>"},{"location":"codespaces/#commandline-codespaces-quick-reference","title":"Commandline codespaces Quick Reference","text":"<ol> <li>List all your codespaces <code>gh codespace list</code></li> <li>Create a new codespace <code>gh codespace create -r OWNER/REPO_NAME [-b BRANCH]</code>. Ref docs/github: Creating a codespace for a repository</li> <li>View codebase details <code>gh codespace view</code></li> <li>Stop <code>gh codespace stop -c CODESPACE-NAME</code></li> <li>Delete <code>gh codespace delete -c CODESPACE-NAME</code></li> <li>Rebuild <code>gh codespace rebuild</code></li> <li>Rename <code>gh codespace edit -c CODESPACE-NAME -d DISPLAY-NAME</code></li> <li>SSH into REMOTE codespace <code>gh codespace ssh -c CODESPACE-NAME</code></li> <li>Open a remote codespace in CVisual Studio <code>gh codespace code -c CODESPACE-NAME</code> (ref: github:doc cs studio)</li> <li>Copy local file to/from codespace <code>gh codespace cp [-r] SOURCE(S) DESTINATION</code>. Example: Copy a file from the local machine to the $HOME directory of a codespace: <code>gh codespace cp myfile.txt remote:</code>. Example Copy a file from a codespace to the current directory on the local machine: <code>gh codespace cp remote:myfile.txt .</code> (more information available here)</li> </ol>"},{"location":"codespaces/#try-g3log-in-a-local-dev-container","title":"Try g3log in a local dev container.","text":"<p>Please note that this will build g3log as if it's on a Debian Linux platform.</p> <ol> <li>Clone this repository to your local filesystem.</li> <li>Start Visual Studio Code. Press F1 and select the <code>Dev Containers: Open Folder in Container...</code> command.</li> <li>Select the cloned copy of this g3log folder, wait for the container to start, and try things out! You should have debian C++ environment at hand. </li> </ol>"},{"location":"codespaces/#example-cmake-configuration-and-build","title":"Example cmake configuration and build","text":"<pre><code>Open a terminal in Visual Studio Code\nmkdir debianbuild\ncd debianbuild\ncmake -DADD_G3LOG_UNIT_TEST=ON -DADD_G3LOG_BENCH_PERFORMANCE=ON ..\nmake -j \n</code></pre>"},{"location":"codespaces/#example-runs","title":"Example runs","text":"<ol> <li>performance test in the container <code>./g3log-performance-threaded_mean 4</code></li> <li>unit tests <code>ctest -v</code></li> <li>Try a fatal example with dumped stack trace <code>./g3log-FATAL-contract</code></li> </ol>"},{"location":"codespaces/#example-with-debugging","title":"Example with Debugging.","text":"<p>Without any need to set up environment on your local machine you can also use Codespaces to debug examples, unit tests etc of g3log. The pesky thing with VSCode, especially with cmake is to set up the launh.json. It's a little bit easier if you open a VSCode terminal and do the cmake configuration and build there. Then the <code>launch.json</code> only needs to contain information about the pecific executable. </p> <p>Here we try out the <code>g3log-FATAL-contract</code> after cmake configure with <code>-DCMAKE_BUILD_TYPE=Debug</code></p> <pre><code>{\n // Use IntelliSense to learn about possible attributes.\n // Hover to view descriptions of existing attributes.\n // For more information, visit: https://go.microsoft.com/fwlink/?linkid=830387\n // Remember to build the specific part of cmake with \n // \"cmake -DCMAKE_BUILD_TYPE=Debug\" if you want to be able to debug it. \n \"version\": \"0.2.0\",\n \"configurations\": [\n {\n \"name\": \"(gdb) Start\",\n \"type\": \"cppdbg\",\n \"request\": \"launch\",\n \"program\": \"${workspaceFolder}/build/g3log-FATAL-contract\",\n \"MIMode\": \"gdb\",\n \"cwd\": \"${workspaceFolder}/build\"\n \"setupCommands\": [\n {\n \"description\": \"Enable pretty-printing for gdb\",\n \"text\": \"-enable-pretty-printing\",\n \"ignoreFailures\": true\n },\n {\n \"description\": \"Set Disassembly Flavor to Intel\",\n \"text\": \"-gdb-set disassembly-flavor intel\",\n \"ignoreFailures\": true\n }\n ]\n }\n\n ]\n}\n</code></pre>"},{"location":"contributing/","title":"Information for contributing to g3log","text":""},{"location":"contributing/#license","title":"License","text":"<p>LICENSE </p>"},{"location":"contributing/#contributing","title":"Contributing","text":"<p>CONTRIBUTING.md</p>"},{"location":"contributing/#code-of-conduct","title":"Code of conduct","text":"<p>CODE_OF_CONDUCT.md</p>"},{"location":"contributing/#pull-request-template","title":"Pull request template","text":"<p>PULL_REQUEST_TEMPLATE.md</p>"},{"location":"g3log_usage/","title":"G3log usage","text":"<p>introduction | detailed information | Configure & Build | API description | Custom log formatting</p>"},{"location":"g3log_usage/#how-to-use-g3log","title":"How to use g3log","text":"<p>G3log is an asynchronous logger with dynamic sinks</p>"},{"location":"g3log_usage/#example-usage","title":"Example USAGE","text":""},{"location":"g3log_usage/#optional-to-use-either-streaming-or-printf-like-syntax","title":"Optional to use either streaming or printf-like syntax","text":"<pre><code>LOG(INFO) << \"streaming API is as easy as ABC or \" << 123;\n\nLOGF(WARNING, \"Printf-style syntax is also %s\", \"available\");\n</code></pre>"},{"location":"g3log_usage/#what-g3log-is","title":"What g3Log is","text":"<ul> <li>G3log is the acting name for the third version of g2log and it stands for g3log with dynamic sinks</li> <li>G3log is an asynchronous, \"crash-safe\" logger. You can read more about it here [g2log version]</li> <li>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.</li> </ul>"},{"location":"g3log_usage/#conditional-logging","title":"Conditional logging","text":"<pre><code>int less = 1; int more = 2\nLOG_IF(INFO, (less<more)) <<\"If [true], then this text will be logged\";\n\n// or with printf-like syntax\nLOGF_IF(INFO, (less<more), \"if %d<%d then this text will be logged\", less,more);\n</code></pre>"},{"location":"g3log_usage/#design-by-contract","title":"Design-by-Contract","text":"<p>CHECK(false) will trigger a \"fatal\" message. It will be logged, and then the application will exit.</p> <pre><code>CHECK(less != more); // not FATAL\nCHECK(less > more) << \"CHECK(false) triggers a FATAL message\";\n</code></pre>"},{"location":"g3log_usage/#detailed-api-documentation","title":"Detailed API documentation","text":"<p>Please look at API.md for detailed API documentation</p>"},{"location":"g3log_usage/#benefits-you-get-when-using-g3log","title":"Benefits you get when using g3log","text":"<ol> <li> <p>Easy to use, clean syntax and a blazing fast logger.</p> </li> <li> <p>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.</p> </li> <li> <p>G3log provides logging, Design-by-Contract [#CHECK], and flush of log to file at shutdown. Buffered logs will be written to the sink before the application shuts down.</p> </li> <li> <p>It is thread safe, so using it from multiple threads is completely fine.</p> </li> <li> <p>It is CRASH SAFE. It will save the made logs to the sink before it shuts down. The logger will catch certain fatal events (Linux/OSX: signals, Windows: fatal OS exceptions and signals) , so if your application crashes due to, say a segmentation fault, SIGSEGV, it will log and save the crash and all previously buffered log entries before exiting.</p> </li> <li> <p>It is cross platform. Tested and used by me or by clients on OSX, Windows, Ubuntu, CentOS</p> </li> <li> <p>G3log and G2log are used worldwide in commercial products as well as hobby projects. G2log was introduced in early 2011 and is now retired.</p> </li> <li> <p>The code is given for free as public domain. This gives the option to change, use, and do whatever with it, no strings attached.</p> </li> <li> <p>g3log : 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) and OSX. My recommendation is to go with g3log if you have full C++17 support </p> </li> </ol> <p>C++11 support up to version: https://github.com/KjellKod/g3log/releases/tag/1.3.1).</p> <p>C++14 support up to version: https://github.com/KjellKod/g3log/releases/tag/1.3.4</p>"},{"location":"g3log_usage/#g3log-with-sinks","title":"G3log with sinks","text":"<p>Sinks 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.</p> <p>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.</p> <p>A sink is owned by the g3log and is added to the logger inside a <code>std::unique_ptr</code>. The sink can be called though its public API through a handler which will asynchronously forward the call to the receiving sink.</p> <p>It is crazy simple to create a custom sink. 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</p> <pre><code>// in file Customsink.hpp\n#pragma once\n#include <string>\n#include <iostream>\n#include <g3log/logmessage.hpp>\n\nstruct CustomSink {\n\n// Linux xterm color\n// http://stackoverflow.com/questions/2616906/how-do-i-output-coloured-text-to-a-linux-terminal\n enum FG_Color {YELLOW = 33, RED = 31, GREEN=32, WHITE = 97};\n\n FG_Color GetColor(const LEVELS level) const {\n if (level.value == WARNING.value) { return YELLOW; }\n if (level.value == DEBUG.value) { return GREEN; }\n if (g3::internal::wasFatal(level)) { return RED; }\n\n return WHITE;\n }\n\n void ReceiveLogMessage(g3::LogMessageMover logEntry) {\n auto level = logEntry.get()._level;\n auto color = GetColor(level);\n\n std::cout << \"\\033[\" << color << \"m\"\n << logEntry.get().toString() << \"\\033[m\" << std::endl;\n }\n};\n\n// in main.cpp, main() function\n\nauto sinkHandle = logworker->addSink(std::make_unique<CustomSink>(),\n &CustomSink::ReceiveLogMessage);\n\n</code></pre>"},{"location":"g3log_usage/#adding-and-removing-sinks","title":"Adding and Removing Sinks","text":"<p>You can safely remove and add sinks during the running of your program. </p> <p>Keep in mind</p> <ul> <li>Initialization of the logger should happen before you have started any other threads that may call the logger. </li> <li>Destruction of the logger (RAII concept) should happen AFTER shutdown of other threads that are calling the logger.</li> </ul> <p>Adding Sinks</p> <pre><code> auto sinkHandle1 = logworker->addSink(std::make_unique<CustomSink>(),\n &CustomSink::ReceiveLogMessage);\n auto sinkHandle2 = logworker->addDefaultLogger(argv[0],\n path_to_log_file);\n logworker->removeSink(std::move(sinkHandle1)); // this will in a thread-safe manner remove the sinkHandle1\n logworker->removeAllSinks(); // this will in a thread-safe manner remove any sinks. \n</code></pre> <p>More sinks can be found in the repository github.com/KjellKod/g3sinks.</p>"},{"location":"g3log_usage/#code-examples","title":"Code Examples","text":"<p>Example usage where a custom sink is added. A function is called though the sink handler to the actual sink object.</p> <pre><code>// main.cpp\n#include <g3log/g3log.hpp>\n#include <g3log/logworker.hpp>\n#include <memory>\n\n#include \"CustomSink.h\"\n\nint main(int argc, char**argv) {\n using namespace g3;\n std::unique_ptr<LogWorker> logworker{ LogWorker::createLogWorker() };\n auto sinkHandle = logworker->addSink(std::make_unique<CustomSink>(),\n &CustomSink::ReceiveLogMessage);\n\n // initialize the logger before it can receive LOG calls\n initializeLogging(logworker.get());\n LOG(WARNING) << \"This log call, may or may not happend before\"\n << \"the sinkHandle->call below\";\n\n\n // You can call in a thread safe manner public functions on your sink\n // The call is asynchronously executed on your custom sink.\n std::future<void> received = sinkHandle->call(&CustomSink::Foo,\n param1, param2);\n\n // If the LogWorker is initialized then at scope exit the g3::internal::shutDownLogging() will be called.\n // This is important since it protects from LOG calls from static or other entities that will go out of\n // scope at a later time.\n //\n // It can also be called manually:\n g3::internal::shutDownLogging();\n}\n\n\n// some_file.cpp : To show how easy it is to get the logger to work\n// in other parts of your software\n\n#include <g3log/g3log.hpp>\n\nvoid SomeFunction() {\n ...\n LOG(INFO) << \"Hello World\";\n}\n</code></pre> <p>Example usage where a the default file logger is used and a custom sink is added</p> <pre><code>// main.cpp\n#include <g3log/g3log.hpp>\n#include <g3log/logworker.hpp>\n#include <memory>\n\n#include \"CustomSink.h\"\n\nint main(int argc, char**argv) {\n using namespace g3;\n auto worker = LogWorker::createLogWorker();\n auto defaultHandler = worker->addDefaultLogger(argv[0],\n path_to_log_file);\n\n // logger is initialized\n g3::initializeLogging(worker.get());\n\n LOG(DEBUG) << \"Make log call, then add another sink\";\n\n worker->addSink(std::make_unique<CustomSink>(),\n &CustomSink::ReceiveLogMessage);\n\n ...\n}\n</code></pre> <p>introduction | detailed information | Configure & Build | API description | Custom log formatting</p>"}]} |