By default, the signal handler writes the failure dump to the standard error.
+However, it is possible to customize the destination by installing a callback
+using the google::InstallFailureWriter() function. The function expects
+a pointer to a function with the following signature:
FATAL severity level messages or unsatisfied CHECK condition
terminate your program. You can change the behavior of the termination
-by InstallFailureFunction.
By default, glog tries to dump the stacktrace and calls std::abort. The
-stacktrace is generated only when running the application on a system supported
-by glog. Currently, glog supports x86, x86_64, PowerPC architectures,
-libunwind, and the Debug Help Library (dbghelp) on Windows for extracting
-the stack trace.
+stacktrace is generated only when running the application on a system
+supported1 by glog.
+
+
+
+
+
To extract the stack trace, glog currently supports the following targets:
Using Command-line Parameters and Environment Variables¶
+
If the Google gflags
+library is installed on your machine,
+the build system will automatically detect and use it, allowing you to
+pass flags on the command line.
+
+
Activate --logtostderr in an application from the command line
+
A binary you_application that uses glog can be started using
+
./your_application--logtostderr=1
+
+to log to stderr instead of writing the output to a log file.
+
+
+
Tip
+
You can set boolean flags to true by specifying 1, true, or yes. To
+set boolean flags to false, specify 0, false, or no. In either case
+the spelling is case-insensitive.
+
+
If the Google gflags library isn't installed, you set flags via
+environment variables, prefixing the flag name with GLOG_, e.g.,
+
+
Activate logtostderr without gflags
+
GLOG_logtostderr=1./your_application
+
+
+
The following flags are most commonly used:
+
+
logtostderr (bool, default=false)
+
+
Log messages to stderr instead of logfiles.
+
+
stderrthreshold (int, default=2, which is ERROR)
+
+
Copy log messages at or above this level to stderr in addition to
+logfiles. The numbers of severity levels INFO, WARNING, ERROR,
+and FATAL are 0, 1, 2, and 3, respectively.
+
+
minloglevel (int, default=0, which is INFO)
+
+
Log messages at or above this level. Again, the numbers of severity
+levels INFO, WARNING, ERROR, and FATAL are 0, 1, 2, and 3,
+respectively.
+
+
log_dir (string, default="")
+
+
If specified, logfiles are written into this directory instead of
+the default logging directory.
+
+
v (int, default=0)
+
+
Show all VLOG(m) messages for m less or equal the value of this
+flag. Overridable by --vmodule. Refer to verbose
+logging for more detail.
+
+
vmodule (string, default="")
+
+
Per-module verbose level. The argument has to contain a
+comma-separated list of <module name>=<log level>. <module name> is a
+glob pattern (e.g., gfs* for all modules whose name starts with "gfs"),
+matched against the filename base (that is, name ignoring .cc/.h./-inl.h).
+<log level> overrides any value given by --v. See also verbose
+logging for more details.
+
+
+
Additional flags are defined in
+flags.cc. Please see
+the source for their complete list.
You can also modify flag values in your program by modifying global variables
+FLAGS_*. Most settings start working immediately after you update FLAGS_*.
+The exceptions are the flags related to destination files. For instance, you
+might want to set FLAGS_log_dir before calling google::InitGoogleLogging.
+
+
Setting log_dir at runtime
+
LOG(INFO)<<"file";
+// Most flags work immediately after updating values.
+FLAGS_logtostderr=1;
+LOG(INFO)<<"stderr";
+FLAGS_logtostderr=0;
+// This won’t change the log destination. If you want to set this
+// value, you should do this before google::InitGoogleLogging .
+FLAGS_log_dir="/some/log/directory";
+LOG(INFO)<<"the same file";
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
\ No newline at end of file
diff --git a/0.8.0/index.html b/0.8.0/index.html
index 8d534cb..6b1e3cf 100644
--- a/0.8.0/index.html
+++ b/0.8.0/index.html
@@ -432,6 +432,8 @@
+
+
@@ -558,13 +560,14 @@ various helper macros.
The library can be installed using various package managers or
compiled from source. For a detailed overview of glog features and
their usage, please refer to the user guide.
@@ -595,7 +598,7 @@ their usage, please refer to the user guide.
- June 11, 2024
+ June 12, 2024
diff --git a/0.8.0/license/index.html b/0.8.0/license/index.html
index 960f102..6ebd2a9 100644
--- a/0.8.0/license/index.html
+++ b/0.8.0/license/index.html
@@ -352,6 +352,8 @@
+
+
diff --git a/0.8.0/log_cleaner/index.html b/0.8.0/log_cleaner/index.html
index c7baa66..e4b1ffd 100644
--- a/0.8.0/log_cleaner/index.html
+++ b/0.8.0/log_cleaner/index.html
@@ -356,6 +356,8 @@
+
+
@@ -416,6 +418,27 @@
+
Using Command-line Parameters and Environment Variables¶
-
If the Google gflags
-library is installed on your machine,
-the build system will automatically detect and use it, allowing you to
-pass flags on the command line.
-
-
Activate --logtostderr in an application from the command line
-
A binary you_application that uses glog can be started using
-
./your_application--logtostderr=1
-
-to log to stderr instead of writing the output to a log file.
-
-
-
Tip
-
You can set boolean flags to true by specifying 1, true, or yes. To
-set boolean flags to false, specify 0, false, or no. In either case
-the spelling is case-insensitive.
-
-
If the Google gflags library isn't installed, you set flags via
-environment variables, prefixing the flag name with GLOG_, e.g.,
-
-
Activate logtostderr without gflags
-
GLOG_logtostderr=1./your_application
-
-
-
The following flags are most commonly used:
-
-
logtostderr (bool, default=false)
-
-
Log messages to stderr instead of logfiles.
-
-
stderrthreshold (int, default=2, which is ERROR)
-
-
Copy log messages at or above this level to stderr in addition to
-logfiles. The numbers of severity levels INFO, WARNING, ERROR,
-and FATAL are 0, 1, 2, and 3, respectively.
-
-
minloglevel (int, default=0, which is INFO)
-
-
Log messages at or above this level. Again, the numbers of severity
-levels INFO, WARNING, ERROR, and FATAL are 0, 1, 2, and 3,
-respectively.
-
-
log_dir (string, default="")
-
-
If specified, logfiles are written into this directory instead of
-the default logging directory.
-
-
v (int, default=0)
-
-
Show all VLOG(m) messages for m less or equal the value of this
-flag. Overridable by --vmodule. Refer to verbose
-logging for more detail.
-
-
vmodule (string, default="")
-
-
Per-module verbose level. The argument has to contain a
-comma-separated list of <module name>=<log level>. <module name>
-is a glob pattern (e.g., gfs* for all modules whose name starts
-with "gfs"), matched against the filename base (that is, name
-ignoring .cc/.h./-inl.h). <log level> overrides any value given by
---v. See also verbose logging for
-more details.
-
-
-
Additional flags are defined in
-flags.cc. Please see
-the source for their complete list.
You can also modify flag values in your program by modifying global variables
-FLAGS_*. Most settings start working immediately after you update FLAGS_*.
-The exceptions are the flags related to destination files. For instance, you
-might want to set FLAGS_log_dir before calling google::InitGoogleLogging.
-
-
Setting log_dir at runtime
-
LOG(INFO)<<"file";
-// Most flags work immediately after updating values.
-FLAGS_logtostderr=1;
-LOG(INFO)<<"stderr";
-FLAGS_logtostderr=0;
-// This won’t change the log destination. If you want to set this
-// value, you should do this before google::InitGoogleLogging .
-FLAGS_log_dir="/some/log/directory";
-LOG(INFO)<<"the same file";
-
Sometimes, you may only want to log a message under certain conditions.
You can use the following macros to perform conditional logging:
-
LOG_IF(INFO,num_cookies>10)<<"Got lots of cookies";
+
LOG_IF(INFO,num_cookies>10)<<"Got lots of cookies";
The "Got lots of cookies" message is logged only when the variable
num_cookies exceeds 10. If a line of code is executed many times, it may be
useful to only log a message at certain intervals. This kind of logging is most
useful for informational messages.
-
LOG_EVERY_N(INFO,10)<<"Got the "<<google::COUNTER<<"th cookie";
+
LOG_EVERY_N(INFO,10)<<"Got the "<<google::COUNTER<<"th cookie";
The above line outputs a log messages on the 1st, 11th, 21st, ... times
it is executed.
@@ -1221,20 +1090,20 @@ it is executed.
You can combine conditional and occasional logging with the following
macro.
-
LOG_IF_EVERY_N(INFO,(size>1024),10)<<"Got the "<<google::COUNTER
-<<"th big cookie";
+
LOG_IF_EVERY_N(INFO,(size>1024),10)<<"Got the "<<google::COUNTER
+<<"th big cookie";
Instead of outputting a message every nth time, you can also limit the
output to the first n occurrences:
-
LOG_FIRST_N(INFO,20)<<"Got the "<<google::COUNTER<<"th cookie";
+
LOG_FIRST_N(INFO,20)<<"Got the "<<google::COUNTER<<"th cookie";
Outputs log messages for the first 20 times it is executed. The google::COUNTER identifier indicates which repetition is happening.
Other times, it is desired to only log a message periodically based on a
time. For instance, to log a message every 10ms:
When you are chasing difficult bugs, thorough log messages are very
@@ -1242,8 +1111,8 @@ useful. However, you may want to ignore too verbose messages in usual
development. For such verbose logging, glog provides the VLOG macro, which
allows you to define your own numeric logging levels.
The --v command line option controls which verbose messages are logged:
-
VLOG(1)<<"I’m printed when you run the program with --v=1 or higher";
-VLOG(2)<<"I’m printed when you run the program with --v=2 or higher";
+
VLOG(1)<<"I’m printed when you run the program with --v=1 or higher";
+VLOG(2)<<"I’m printed when you run the program with --v=2 or higher";
With VLOG, the lower the verbose level, the more likely messages are to be
logged. For example, if --v==1, VLOG(1) will log, but VLOG(2) will not log.
@@ -1259,7 +1128,7 @@ common values for them are small positive integers. For example, if you write
useful since we may not want verbose logs by default in most cases. The VLOG
macros always log at the INFO log level (when they log at all).
Verbose logging can be controlled from the command line on a per-module basis:
-
--vmodule=mapreduce=2,file=1,gfs*=3--v=0
+
--vmodule=mapreduce=2,file=1,gfs*=3--v=0
Specifying these options will specifically:
@@ -1270,28 +1139,31 @@ macros always log at the INFO log level (when they log at all).
The wildcarding functionality 3. supports both * (matches 0 or more
characters) and ? (matches any single character) wildcards. Please also refer
-to command line flags for more information.
There's also VLOG_IS_ON(n) "verbose level" condition macro. This macro
returns true when the --v is equal to or greater than n. The macro can be
used as follows:
-
if(VLOG_IS_ON(2)){
-// do some logging preparation and logging
-// that can’t be accomplished with just VLOG(2) << ...;
-}
+
if(VLOG_IS_ON(2)){
+// (1)
+}
+
+
Here we can perform some logging preparation and logging that can’t be
+ accomplished with just VLOG(2)<<"message ...";
+
Verbose level condition macros VLOG_IF, VLOG_EVERY_N and VLOG_IF_EVERY_N
behave analogous to LOG_IF, LOG_EVERY_N, LOG_IF_EVERY_N, but accept a
numeric verbosity level as opposed to a severity level.
-
VLOG_IF(1,(size>1024))
-<<"I’m printed when size is more than 1024 and when you run the "
-"program with --v=1 or more";
-VLOG_EVERY_N(1,10)
-<<"I’m printed every 10th occurrence, and when you run the program "
-"with --v=1 or more. Present occurrence is "<<google::COUNTER;
-VLOG_IF_EVERY_N(1,(size>1024),10)
-<<"I’m printed on every 10th occurrence of case when size is more "
-" than 1024, when you run the program with --v=1 or more. ";
-"Present occurrence is "<<google::COUNTER;
+
VLOG_IF(1,(size>1024))
+<<"I’m printed when size is more than 1024 and when you run the "
+"program with --v=1 or more";
+VLOG_EVERY_N(1,10)
+<<"I’m printed every 10th occurrence, and when you run the program "
+"with --v=1 or more. Present occurrence is "<<google::COUNTER;
+VLOG_IF_EVERY_N(1,(size>1024),10)
+<<"I’m printed on every 10th occurrence of case when size is more "
+" than 1024, when you run the program with --v=1 or more. ";
+"Present occurrence is "<<google::COUNTER;
Performance
@@ -1299,18 +1171,18 @@ numeric verbosity level as opposed to a severity level.
VLOG, etc.) are carefully implemented and don't execute the right hand
side expressions when the conditions are false. So, the following check may
not sacrifice the performance of your application.
-
Special debug mode logging macros only have an effect in debug mode and are
compiled away to nothing for non-debug mode compiles. Use these macros to avoid
slowing down your production application due to excessive logging.
-
DLOG(INFO)<<"Found cookies";
-DLOG_IF(INFO,num_cookies>10)<<"Got lots of cookies";
-DLOG_EVERY_N(INFO,10)<<"Got the "<<google::COUNTER<<"th cookie";
-DLOG_FIRST_N(INFO,10)<<"Got the "<<google::COUNTER<<"th cookie";
-DLOG_EVERY_T(INFO,0.01)<<"Got a cookie";
+
DLOG(INFO)<<"Found cookies";
+DLOG_IF(INFO,num_cookies>10)<<"Got lots of cookies";
+DLOG_EVERY_N(INFO,10)<<"Got the "<<google::COUNTER<<"th cookie";
+DLOG_FIRST_N(INFO,10)<<"Got the "<<google::COUNTER<<"th cookie";
+DLOG_EVERY_T(INFO,0.01)<<"Got a cookie";
It is a good practice to check expected conditions in your program
@@ -1321,7 +1193,7 @@ similar to the assert macro defined in the standard C library.
assert, it is not controlled by NDEBUG, so the check will be executed
regardless of compilation mode. Therefore, fp->Write(x) in the following
example is always executed:
-
CHECK(fp->Write(x)==4)<<"Write failed!";
+
CHECK(fp->Write(x)==4)<<"Write failed!";
There are various helper macros for equality/inequality checks
-CHECK_EQ, CHECK_NE, CHECK_LE, CHECK_LT, CHECK_GE, and
@@ -1329,28 +1201,28 @@ example is always executed:
values when the result is not as expected. The values must have
operator<<(ostream,...) defined.
You may append to the error message like so:
-
CHECK_NE(1,2)<<": The world must be ending!";
+
CHECK_NE(1,2)<<": The world must be ending!";
We are very careful to ensure that each argument is evaluated exactly
once, and that anything which is legal to pass as a function argument is legal
here. In particular, the arguments may be temporary expressions which will end
up being destroyed at the end of the apparent statement, for example:
-
CHECK_EQ(string("abc")[1],’b’);
+
CHECK_EQ(string("abc")[1],’b’);
The compiler reports an error if one of the arguments is a pointer and the other
is nullptr. To work around this, simply static_castnullptr to the type of the desired pointer.
Both arguments may be temporary objects which are destructed at the
end of the current full expression, such as
-
CHECK_STREQ(Foo().c_str(),Bar().c_str());
+
CHECK_STREQ(Foo().c_str(),Bar().c_str());
where Foo and Bar return std::string.
@@ -1386,7 +1258,7 @@ for detail.
PLOG() and PLOG_IF() and PCHECK() behave exactly like their LOG* and
CHECK equivalents with the addition that they append a description of the
current state of errno to their output lines. E.g.
Google Logging (glog) is a C++14 library that implements application-level logging. The library provides logging APIs based on C++-style streams and various helper macros.
"},{"location":"#how-to-use","title":"How to Use","text":"
You can log a message by simply streaming things to LOG(<a particular severity level>), e.g.,
The library can be installed using various package managers or compiled from source. For a detailed overview of glog features and their usage, please refer to the user guide.
Warning
The above example requires further Bazel or CMake setup for use in own projects.
"},{"location":"build/","title":"Building from Source","text":""},{"location":"build/#bazel","title":"Bazel","text":"
To use glog within a project which uses the Bazel build tool, add the following lines to your WORKSPACE file:
You can then add @com_github_google_glog//:glog to the deps section of a cc_binary or cc_library rule, and #include <glog/logging.h> to include it in your source code.
Using glog in a Bazel project
cc_binary(\n name = \"main\",\n srcs = [\"main.cc\"],\n deps = [\"@com_github_google_glog//:glog\"],\n)\n
glog can be compiled using CMake on a wide range of platforms. The typical workflow for building glog on a Unix-like system with GNU Make as build tool is as follows:
Clone the repository and change into source directory.
CMake provides different generators, and by default will pick the most relevant one to your environment. If you need a specific version of Visual Studio, use cmake . -G <generator-name>, and see cmake --help for the available generators. Also see -T <toolset-name>, which can be used to request the native x64 toolchain with -T host=x64.
Afterwards, generated files can be used to compile the project.
cmake --build build\n
Test the build software (optional).
cmake --build build --target test\n
Install the built files (optional).
cmake --build build --target install\n
Once successfully built, glog can be integrated into own projects.
"},{"location":"contribute/","title":"How to Contribute","text":"
We'd love to accept your patches and contributions to this project. There are a just a few small guidelines you need to follow.
Contributions to any Google project must be accompanied by a Contributor License Agreement. This is not a copyright assignment, it simply gives Google permission to use and redistribute your contributions as part of the project.
If you are an individual writing original source code and you're sure you own the intellectual property, then you'll need to sign an individual CLA.
If you work for a company that wants to allow you to contribute your work, then you'll need to sign a corporate CLA.
You generally only need to submit a CLA once, so if you've already submitted one (even if it was for a different project), you probably don't need to do it again.
Once your CLA is submitted (or if you already submitted one for another Google project), make a commit adding yourself to the AUTHORS and CONTRIBUTORS files. This commit can be part of your first pull request.
"},{"location":"contribute/#submitting-a-patch","title":"Submitting a Patch","text":"
It's generally best to start by opening a new issue describing the bug or feature you're intending to fix. Even if you think it's relatively minor, it's helpful to know what people are working on. Mention in the initial issue that you are planning to work on that bug or feature so that it can be assigned to you.
Follow the normal process of forking the project, and setup a new branch to work in. It's important that each group of changes be done in separate branches in order to ensure that a pull request only includes the commits related to that bug or feature.
Do your best to have well-formed commit messages for each change. This provides consistency throughout the project, and ensures that commit messages are able to be formatted properly by various git tools.
Finally, push the commits to your fork and submit a pull request.
"},{"location":"failures/","title":"Failure Signal Handler","text":""},{"location":"failures/#stacktrace-as-default-failure-handler","title":"Stacktrace as Default Failure Handler","text":"
The library provides a convenient signal handler that will dump useful information when the program crashes on certain signals such as SIGSEGV. The signal handler can be installed by google::InstallFailureSignalHandler(). The following is an example of output from the signal handler.
*** Aborted at 1225095260 (unix time) try \"date -d @1225095260\" if you are using GNU date ***\n*** SIGSEGV (@0x0) received by PID 17711 (TID 0x7f893090a6f0) from PID 0; stack trace: ***\nPC: @ 0x412eb1 TestWaitingLogSink::send()\n @ 0x7f892fb417d0 (unknown)\n @ 0x412eb1 TestWaitingLogSink::send()\n @ 0x7f89304f7f06 google::LogMessage::SendToLog()\n @ 0x7f89304f35af google::LogMessage::Flush()\n @ 0x7f89304f3739 google::LogMessage::~LogMessage()\n @ 0x408cf4 TestLogSinkWaitTillSent()\n @ 0x4115de main\n @ 0x7f892f7ef1c4 (unknown)\n @ 0x4046f9 (unknown)\n
By default, the signal handler writes the failure dump to the standard error. You can customize the destination by InstallFailureWriter().
FATAL severity level messages or unsatisfied CHECK condition terminate your program. You can change the behavior of the termination by InstallFailureFunction.
By default, glog tries to dump the stacktrace and calls std::abort. The stacktrace is generated only when running the application on a system supported by glog. Currently, glog supports x86, x86_64, PowerPC architectures, libunwind, and the Debug Help Library (dbghelp) on Windows for extracting the stack trace.
Copyright \u00a9 2024, Google Inc. All rights reserved.
Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
Neither the name of Google Inc. nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS \"AS IS\" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
"},{"location":"log_cleaner/","title":"Automatically Remove Old Logs","text":"
To enable the log cleaner:
using namespace std::chrono_literals;\ngoogle::EnableLogCleaner(24h * 3); // keep your logs for 3 days\n
In C++20 (and later) this can be shortened to:
using namespace std::chrono_literals;\ngoogle::EnableLogCleaner(3d); // keep your logs for 3 days\n
And then glog will check if there are overdue logs whenever a flush is performed. In this example, any log file from your project whose last modified time is greater than 3 days will be unlink()ed.
This feature can be disabled at any time (if it has been enabled) using
Strings used in log messages can increase the size of your binary and present a privacy concern. You can therefore instruct glog to remove all strings which fall below a certain severity level by using the GOOGLE_STRIP_LOG macro:
If your application has code like this:
#define GOOGLE_STRIP_LOG 1 // this must go before the #include!\n#include <glog/logging.h>\n
The compiler will remove the log messages whose severities are less than the specified integer value. Since VLOG logs at the severity level INFO (numeric value 0), setting GOOGLE_STRIP_LOG to 1 or greater removes all log messages associated with VLOGs as well as INFO log statements.
glog defines a series of macros that simplify many common logging tasks. You can log messages by severity level, control logging behavior from the command line, log based on conditionals, abort the program when expected conditions are not met, introduce your own logging levels, customize the prefix attached to log messages, and more.
You can specify one of the following severity levels (in increasing order of severity):
INFO,
WARNING,
ERROR, and
FATAL.
Logging a FATAL message terminates the program (after the message is logged).
Note
Messages of a given severity are logged not only to corresponding severity logfile but also to other logfiles of lower severity. For instance, a message of severity FATAL will be logged to logfiles of severity FATAL, ERROR, WARNING, and INFO.
The DFATAL severity logs a FATAL error in debug mode (i.e., there is no NDEBUG macro defined), but avoids halting the program in production by automatically reducing the severity to ERROR.
Placeholder Meaning L A single character, representing the log level (e.g., I for INFO) yyyy The year mm The month (zero padded; i.e., May is 05) dd The day (zero padded) hh:mm:ss.uuuuuu Time in hours, minutes and fractional seconds threadid The space-padded thread ID file The file name line The line number msg The user-supplied message
Default log line prefix format
I1103 11:57:31.739339 24395 google.cc:2341] Command line: ./some_prog\nI1103 11:57:31.739403 24395 google.cc:2342] Process id 24395\n
Note
Although microseconds are useful for comparing events on a single machine, clocks on different machines may not be well synchronized. Hence, use with caution when comparing the low bits of timestamps from different machines.
The predefined log line prefix can be replaced using a user-provided callback that formats the corresponding output.
For each log entry, the callback will be invoked with a reference to a google::LogMessage instance containing the severity, filename, line number, thread ID, and time of the event. It will also be given a reference to the output stream, whose contents will be prepended to the actual message in the final log line.
function to pass a pointer to the corresponding MyPrefixFormatter callback during initialization. InstallPrefixFormatter takes a second optional argument of type void* that allows supplying user data to the callback.
Custom prefix formatter
The following function outputs a prefix that matches glog's default format. The third parameter data can be used to access user-supplied data which unless specified defaults to nullptr.
"},{"location":"logging/#using-command-line-parameters-and-environment-variables","title":"Using Command-line Parameters and Environment Variables","text":"
If the Google gflags library is installed on your machine, the build system will automatically detect and use it, allowing you to pass flags on the command line.
Activate --logtostderr in an application from the command line
A binary you_application that uses glog can be started using
./your_application --logtostderr=1\n
to log to stderr instead of writing the output to a log file.
Tip
You can set boolean flags to true by specifying 1, true, or yes. To set boolean flags to false, specify 0, false, or no. In either case the spelling is case-insensitive.
If the Google gflags library isn't installed, you set flags via environment variables, prefixing the flag name with GLOG_, e.g.,
Activate logtostderr without gflags
GLOG_logtostderr=1 ./your_application\n
The following flags are most commonly used:
logtostderr (bool, default=false)
Log messages to stderr instead of logfiles.
stderrthreshold (int, default=2, which is ERROR)
Copy log messages at or above this level to stderr in addition to logfiles. The numbers of severity levels INFO, WARNING, ERROR, and FATAL are 0, 1, 2, and 3, respectively.
minloglevel (int, default=0, which is INFO)
Log messages at or above this level. Again, the numbers of severity levels INFO, WARNING, ERROR, and FATAL are 0, 1, 2, and 3, respectively.
log_dir (string, default=\"\")
If specified, logfiles are written into this directory instead of the default logging directory.
v (int, default=0)
Show all VLOG(m) messages for m less or equal the value of this flag. Overridable by --vmodule. Refer to verbose logging for more detail.
vmodule (string, default=\"\")
Per-module verbose level. The argument has to contain a comma-separated list of <module name>=<log level>. <module name> is a glob pattern (e.g., gfs* for all modules whose name starts with \"gfs\"), matched against the filename base (that is, name ignoring .cc/.h./-inl.h). <log level> overrides any value given by --v. See also verbose logging for more details.
Additional flags are defined in flags.cc. Please see the source for their complete list.
You can also modify flag values in your program by modifying global variables FLAGS_*. Most settings start working immediately after you update FLAGS_*. The exceptions are the flags related to destination files. For instance, you might want to set FLAGS_log_dir before calling google::InitGoogleLogging.
Setting log_dir at runtime
LOG(INFO) << \"file\";\n// Most flags work immediately after updating values.\nFLAGS_logtostderr = 1;\nLOG(INFO) << \"stderr\";\nFLAGS_logtostderr = 0;\n// This won\u2019t change the log destination. If you want to set this\n// value, you should do this before google::InitGoogleLogging .\nFLAGS_log_dir = \"/some/log/directory\";\nLOG(INFO) << \"the same file\";\n
Sometimes, you may only want to log a message under certain conditions. You can use the following macros to perform conditional logging:
LOG_IF(INFO, num_cookies > 10) << \"Got lots of cookies\";\n
The \"Got lots of cookies\" message is logged only when the variable num_cookies exceeds 10. If a line of code is executed many times, it may be useful to only log a message at certain intervals. This kind of logging is most useful for informational messages.
When you are chasing difficult bugs, thorough log messages are very useful. However, you may want to ignore too verbose messages in usual development. For such verbose logging, glog provides the VLOG macro, which allows you to define your own numeric logging levels.
The --v command line option controls which verbose messages are logged:
VLOG(1) << \"I\u2019m printed when you run the program with --v=1 or higher\";\nVLOG(2) << \"I\u2019m printed when you run the program with --v=2 or higher\";\n
With VLOG, the lower the verbose level, the more likely messages are to be logged. For example, if --v==1, VLOG(1) will log, but VLOG(2) will not log.
Warning
The VLOG behavior is opposite of the severity level logging, where INFO, ERROR, etc. are defined in increasing order and thus --minloglevel of 1 will only log WARNING and above.
Though you can specify any integers for both VLOG macro and --v flag, the common values for them are small positive integers. For example, if you write VLOG(0), you should specify --v=-1 or lower to silence it. This is less useful since we may not want verbose logs by default in most cases. The VLOG macros always log at the INFO log level (when they log at all).
Verbose logging can be controlled from the command line on a per-module basis:
--vmodule=mapreduce=2,file=1,gfs*=3 --v=0\n
Specifying these options will specifically:
Print VLOG(2) and lower messages from mapreduce.{h,cc}
Print VLOG(1) and lower messages from file.{h,cc}
Print VLOG(3) and lower messages from files prefixed with \"gfs\"
Print VLOG(0) and lower messages from elsewhere
The wildcarding functionality 3. supports both * (matches 0 or more characters) and ? (matches any single character) wildcards. Please also refer to command line flags for more information.
There's also VLOG_IS_ON(n) \"verbose level\" condition macro. This macro returns true when the --v is equal to or greater than n. The macro can be used as follows:
if (VLOG_IS_ON(2)) {\n // do some logging preparation and logging\n // that can\u2019t be accomplished with just VLOG(2) << ...;\n}\n
Verbose level condition macros VLOG_IF, VLOG_EVERY_N and VLOG_IF_EVERY_N behave analogous to LOG_IF, LOG_EVERY_N, LOG_IF_EVERY_N, but accept a numeric verbosity level as opposed to a severity level.
VLOG_IF(1, (size > 1024))\n << \"I\u2019m printed when size is more than 1024 and when you run the \"\n \"program with --v=1 or more\";\nVLOG_EVERY_N(1, 10)\n << \"I\u2019m printed every 10th occurrence, and when you run the program \"\n \"with --v=1 or more. Present occurrence is \" << google::COUNTER;\nVLOG_IF_EVERY_N(1, (size > 1024), 10)\n << \"I\u2019m printed on every 10th occurrence of case when size is more \"\n \" than 1024, when you run the program with --v=1 or more. \";\n \"Present occurrence is \" << google::COUNTER;\n
Performance
The conditional logging macros provided by glog (e.g., CHECK, LOG_IF, VLOG, etc.) are carefully implemented and don't execute the right hand side expressions when the conditions are false. So, the following check may not sacrifice the performance of your application.
Special debug mode logging macros only have an effect in debug mode and are compiled away to nothing for non-debug mode compiles. Use these macros to avoid slowing down your production application due to excessive logging.
DLOG(INFO) << \"Found cookies\";\nDLOG_IF(INFO, num_cookies > 10) << \"Got lots of cookies\";\nDLOG_EVERY_N(INFO, 10) << \"Got the \" << google::COUNTER << \"th cookie\";\nDLOG_FIRST_N(INFO, 10) << \"Got the \" << google::COUNTER << \"th cookie\";\nDLOG_EVERY_T(INFO, 0.01) << \"Got a cookie\";\n
It is a good practice to check expected conditions in your program frequently to detect errors as early as possible. The CHECK macro provides the ability to abort the application when a condition is not met, similar to the assert macro defined in the standard C library.
CHECK aborts the application if a condition is not true. Unlike assert, it is not controlled by NDEBUG, so the check will be executed regardless of compilation mode. Therefore, fp->Write(x) in the following example is always executed:
CHECK(fp->Write(x) == 4) << \"Write failed!\";\n
There are various helper macros for equality/inequality checks -CHECK_EQ, CHECK_NE, CHECK_LE, CHECK_LT, CHECK_GE, and CHECK_GT. They compare two values, and log a FATAL message including the two values when the result is not as expected. The values must have operator<<(ostream, ...) defined.
You may append to the error message like so:
CHECK_NE(1, 2) << \": The world must be ending!\";\n
We are very careful to ensure that each argument is evaluated exactly once, and that anything which is legal to pass as a function argument is legal here. In particular, the arguments may be temporary expressions which will end up being destroyed at the end of the apparent statement, for example:
CHECK_EQ(string(\"abc\")[1], \u2019b\u2019);\n
The compiler reports an error if one of the arguments is a pointer and the other is nullptr. To work around this, simply static_castnullptr to the type of the desired pointer.
Since this macro returns the given pointer, this is very useful in constructor initializer lists.
struct S {\n S(Something* ptr) : ptr_(CHECK_NOTNULL(ptr)) {}\n Something* ptr_;\n};\n
Warning
Due to the argument forwarding, CHECK_NOTNULL cannot be used to simultaneously stream an additional custom message. To provide a custom message, one can use the macro CHECK_EQ prior to the failing check.
If you are comparing C strings (char *), a handy set of macros performs both case sensitive and insensitive comparisons - CHECK_STREQ, CHECK_STRNE, CHECK_STRCASEEQ, and CHECK_STRCASENE. The CHECK_*CASE* macro variants are case-insensitive. You can safely pass nullptr pointers to this macro. They treat nullptr and any non-nullptr string as not equal. Two nullptrs are equal.
Note
Both arguments may be temporary objects which are destructed at the end of the current full expression, such as
CHECK_STREQ(Foo().c_str(), Bar().c_str());\n
where Foo and Bar return std::string.
The CHECK_DOUBLE_EQ macro checks the equality of two floating point values, accepting a small error margin. CHECK_NEAR accepts a third floating point argument, which specifies the acceptable error margin.
The header file <glog/raw_logging.h> can be used for thread-safe logging, which does not allocate any memory or acquire any locks. Therefore, the macros defined in this header file can be used by low-level memory allocation and synchronization code. Please check src/glog/raw_logging.h for detail.
PLOG() and PLOG_IF() and PCHECK() behave exactly like their LOG* and CHECK equivalents with the addition that they append a description of the current state of errno to their output lines. E.g.
SYSLOG, SYSLOG_IF, and SYSLOG_EVERY_N macros are available. These log to syslog in addition to the normal logs. Be aware that logging to syslog can drastically impact performance, especially if syslog is configured for remote logging! Make sure you understand the implications of outputting to syslog before you use these macros. In general, it's wise to use these macros sparingly.
"},{"location":"packages/","title":"Installation using Package Managers","text":""},{"location":"packages/#conan","title":"conan","text":"
You can download and install glog using the conan package manager:
The glog recipe in conan center is kept up to date by conan center index community contributors. If the version is out of date, please create an issue or pull request on the conan-center-index repository.
The glog port in vcpkg is kept up to date by Microsoft team members and community contributors. If the version is out of date, please create an issue or pull request on the vcpkg repository.
Under certain circumstances, it is useful to send the log output to a destination other than a file, stderr and/or stdout. In case, the library provides the google::LogSink interface whose implementations can be used to write the log output to arbitrary locations.
To use the custom sink and instance of the above interface implementation must be registered using google::AddLogSink which expects a pointer to the google::LogSink instance. To unregister use google::RemoveLogSink. Both functions are thread-safe.
LogSink ownership
The google::LogSink instance must not be destroyed until the referencing pointer is unregistered.
Instead of registering the sink, we can directly use to log messages. While LOG_TO_SINK(sink, severity) allows to log both to the sink and to a global log registry, e.g., a file, LOG_TO_SINK_BUT_NOT_TO_LOGFILE(sink, severity) will avoid the latter.
Using a custom sink
custom_sink.cc
#include <glog/logging.h>\n\n#include <algorithm>\n#include <cstddef>\n#include <iostream>\n#include <iterator>\n\nnamespace {\n\nstruct MyLogSink : google::LogSink { // (1)!\n void send(google::LogSeverity severity, const char* /*full_filename*/,\n const char* base_filename, int line,\n const google::LogMessageTime& /*time*/, const char* message,\n std::size_t message_len) override {\n std::cout << google::GetLogSeverityName(severity) << ' ' << base_filename\n << ':' << line << ' ';\n std::copy_n(message, message_len,\n std::ostreambuf_iterator<char>{std::cout});\n std::cout << '\\n';\n }\n};\n\n} // namespace\n\nint main(int /*argc*/, char** argv) {\n google::InitGoogleLogging(argv[0]);\n\n MyLogSink sink;\n google::AddLogSink(&sink); // (2)!\n\n LOG(INFO) << \"logging to MySink\";\n\n google::RemoveLogSink(&sink); // (3)!\n\n // We can directly log to a sink without registering it\n LOG_TO_SINK(&sink, INFO) << \"direct logging\"; // (4)!\n LOG_TO_SINK_BUT_NOT_TO_LOGFILE(&sink, INFO)\n << \"direct logging but not to file\";\n}\n
MySink implements a custom sink that sends log messages to std::cout.
The custom sink must be registered to for use with existing logging macros.
Once the custom sink is no longer needed we remove it from the registry.
A sink does not need to be registered globally. However, then, messages must be logged using dedicated macros.
Running the above example as GLOG_log_dir=. ./custom_sink_example will produce
Custom sink output
INFO custom_sink.cc:63 logging to MySink\nINFO custom_sink.cc:68 direct logging\nINFO custom_sink.cc:69 direct logging but not to file (1)\n
This line is not present in the log file because we used LOG_TO_SINK_BUT_NOT_TO_LOGFILE to log the message.
and the corresponding log file will contain
Log file generated with the custom sink
Log file created at: 2024/06/11 13:24:27\nRunning on machine: pc\nRunning duration (h:mm:ss): 0:00:00\nLog line format: [IWEF]yyyymmdd hh:mm:ss.uuuuuu threadid file:line] msg\nI20240611 13:24:27.476620 126237946035776 custom_sink.cc:63] logging to MySink\nI20240611 13:24:27.476796 126237946035776 custom_sink.cc:68] direct logging\n
"},{"location":"unwinder/","title":"Installation Notes for 64-bit Linux Systems","text":"
Note
The description on this page is possibly not up-to-date.
The glibc built-in stack-unwinder on 64-bit systems has some problems with glog. In particular, if you are using InstallFailureSignalHandler(), the signal may be raised in the middle of malloc, holding some malloc-related locks when they invoke the stack unwinder. The built-in stack unwinder may call malloc recursively, which may require the thread to acquire a lock it already holds resulting in a deadlock.
For above reason, if you use a 64-bit system and you need InstallFailureSignalHandler(), we strongly recommend you install libunwind before trying to configure or install google glog. libunwind can be found here.
Even if you already have libunwind installed, you will probably still need to install from the snapshot to get the latest version.
Warning
If you install libunwind from the URL above, be aware that you may have trouble if you try to statically link your binary with glog: that is, if you link with gcc -static -lgcc_eh .... This is because both libunwind and libgcc implement the same C++ exception handling APIs, but they implement them differently on some platforms. This is not likely to be a problem on ia64, but may be on x86-64.
Also, if you link binaries statically, make sure that you add -Wl,--eh-frame-hdr to your linker options. This is required so that libunwind can find the information generated by the compiler required for stack unwinding.
Using -static is rare, though, so unless you know this will affect you it probably won't.
As we already mentioned, glibc's unwinder has a deadlock issue. However, if you don't use InstallFailureSignalHandler() or you don't worry about the rare possibilities of deadlocks, you can use this stack-unwinder. If you specify no options and libunwind isn't detected on your system, the configure script chooses this unwinder by default.
"},{"location":"unwinder/#frame-pointer-based-stack-unwinder","title":"Frame Pointer based Stack-unwinder","text":"
The frame pointer based stack unwinder requires that your application, the glog library, and system libraries like libc, all be compiled with a frame pointer. This is not the default for x86-64.
"},{"location":"usage/","title":"Using glog in a CMake Project","text":"
Assuming that glog was previously built using CMake or installed using a package manager, you can use the CMake command find_package to build against glog in your CMake project as follows:
Compile definitions and options will be added automatically to your target as needed.
Alternatively, glog can be incorporated into using the CMake command add_subdirectory to include glog directly from a subdirectory of your project by replacing the find_package call from the previous snippet by add_subdirectory. The glog::glog target is in this case an ALIAS library target for the glog library target.
"},{"location":"windows/","title":"Notes for Windows Users","text":"
glog defines the severity level ERROR, which is also defined by windows.h. You can make glog not define INFO, WARNING, ERROR, and FATAL by defining GLOG_NO_ABBREVIATED_SEVERITIES before including glog/logging.h. Even with this macro, you can still use the iostream like logging facilities:
#define GLOG_NO_ABBREVIATED_SEVERITIES\n#include <windows.h>\n#include <glog/logging.h>\n\n// ...\n\nLOG(ERROR) << \"This should work\";\nLOG_IF(ERROR, x > y) << \"This should be also OK\";\n
However, you cannot use INFO, WARNING, ERROR, and FATAL anymore for functions defined in glog/logging.h.
#define GLOG_NO_ABBREVIATED_SEVERITIES\n#include <windows.h>\n#include <glog/logging.h>\n\n// ...\n\n// This won\u2019t work.\n// google::FlushLogFiles(google::ERROR);\n\n// Use this instead.\ngoogle::FlushLogFiles(google::GLOG_ERROR);\n
If you don't need ERROR defined by windows.h, there are a couple of more workarounds which sometimes don't work:
#define WIN32_LEAN_AND_MEAN or NOGDI before #include <windows.h>.
#undef ERROR after #include <windows.h>.
See this issue for more detail.
"}]}
\ No newline at end of file
+{"config":{"lang":["en"],"separator":"[\\s\\-]+","pipeline":["stopWordFilter"]},"docs":[{"location":"","title":"Google Logging Library","text":"
Google Logging (glog) is a C++14 library that implements application-level logging. The library provides logging APIs based on C++-style streams and various helper macros.
"},{"location":"#how-to-use","title":"How to Use","text":"
You can log a message by simply streaming things to LOG(<a particular severity level>), e.g.,
The library can be installed using various package managers or compiled from source. For a detailed overview of glog features and their usage, please refer to the user guide.
Warning
The above example requires further Bazel or CMake setup for use in own projects.
"},{"location":"build/","title":"Building from Source","text":""},{"location":"build/#bazel","title":"Bazel","text":"
To use glog within a project which uses the Bazel build tool, add the following lines to your WORKSPACE file:
You can then add @com_github_google_glog//:glog to the deps section of a cc_binary or cc_library rule, and #include <glog/logging.h> to include it in your source code.
Using glog in a Bazel project
cc_binary(\n name = \"main\",\n srcs = [\"main.cc\"],\n deps = [\"@com_github_google_glog//:glog\"],\n)\n
glog can be compiled using CMake on a wide range of platforms. The typical workflow for building glog on a Unix-like system with GNU Make as build tool is as follows:
Clone the repository and change into source directory.
CMake provides different generators, and by default will pick the most relevant one to your environment. If you need a specific version of Visual Studio, use cmake . -G <generator-name>, and see cmake --help for the available generators. Also see -T <toolset-name>, which can be used to request the native x64 toolchain with -T host=x64.
Afterwards, generated files can be used to compile the project.
cmake --build build\n
Test the build software (optional).
cmake --build build --target test\n
Install the built files (optional).
cmake --build build --target install\n
Once successfully built, glog can be integrated into own projects.
"},{"location":"contribute/","title":"How to Contribute","text":"
We'd love to accept your patches and contributions to this project. There are a just a few small guidelines you need to follow.
Contributions to any Google project must be accompanied by a Contributor License Agreement. This is not a copyright assignment, it simply gives Google permission to use and redistribute your contributions as part of the project.
If you are an individual writing original source code and you're sure you own the intellectual property, then you'll need to sign an individual CLA.
If you work for a company that wants to allow you to contribute your work, then you'll need to sign a corporate CLA.
You generally only need to submit a CLA once, so if you've already submitted one (even if it was for a different project), you probably don't need to do it again.
Once your CLA is submitted (or if you already submitted one for another Google project), make a commit adding yourself to the AUTHORS and CONTRIBUTORS files. This commit can be part of your first pull request.
"},{"location":"contribute/#submitting-a-patch","title":"Submitting a Patch","text":"
It's generally best to start by opening a new issue describing the bug or feature you're intending to fix. Even if you think it's relatively minor, it's helpful to know what people are working on. Mention in the initial issue that you are planning to work on that bug or feature so that it can be assigned to you.
Follow the normal process of forking the project, and setup a new branch to work in. It's important that each group of changes be done in separate branches in order to ensure that a pull request only includes the commits related to that bug or feature.
Do your best to have well-formed commit messages for each change. This provides consistency throughout the project, and ensures that commit messages are able to be formatted properly by various git tools.
Finally, push the commits to your fork and submit a pull request.
"},{"location":"failures/","title":"Failure Signal Handler","text":""},{"location":"failures/#stacktrace-as-default-failure-handler","title":"Stacktrace as Default Failure Handler","text":"
The library provides a convenient signal handler that will dump useful information when the program crashes on certain signals such as SIGSEGV. The signal handler can be installed by google::InstallFailureSignalHandler(). The following is an example of output from the signal handler.
*** Aborted at 1225095260 (unix time) try \"date -d @1225095260\" if you are using GNU date ***\n*** SIGSEGV (@0x0) received by PID 17711 (TID 0x7f893090a6f0) from PID 0; stack trace: ***\nPC: @ 0x412eb1 TestWaitingLogSink::send()\n @ 0x7f892fb417d0 (unknown)\n @ 0x412eb1 TestWaitingLogSink::send()\n @ 0x7f89304f7f06 google::LogMessage::SendToLog()\n @ 0x7f89304f35af google::LogMessage::Flush()\n @ 0x7f89304f3739 google::LogMessage::~LogMessage()\n @ 0x408cf4 TestLogSinkWaitTillSent()\n @ 0x4115de main\n @ 0x7f892f7ef1c4 (unknown)\n @ 0x4046f9 (unknown)\n
By default, the signal handler writes the failure dump to the standard error. However, it is possible to customize the destination by installing a callback using the google::InstallFailureWriter() function. The function expects a pointer to a function with the following signature:
FATAL severity level messages or unsatisfied CHECK condition terminate your program. You can change the behavior of the termination by google::InstallFailureFunction.
By default, glog tries to dump the stacktrace and calls std::abort. The stacktrace is generated only when running the application on a system supported1 by glog.
To extract the stack trace, glog currently supports the following targets:
"},{"location":"flags/#using-command-line-parameters-and-environment-variables","title":"Using Command-line Parameters and Environment Variables","text":"
If the Google gflags library is installed on your machine, the build system will automatically detect and use it, allowing you to pass flags on the command line.
Activate --logtostderr in an application from the command line
A binary you_application that uses glog can be started using
./your_application --logtostderr=1\n
to log to stderr instead of writing the output to a log file.
Tip
You can set boolean flags to true by specifying 1, true, or yes. To set boolean flags to false, specify 0, false, or no. In either case the spelling is case-insensitive.
If the Google gflags library isn't installed, you set flags via environment variables, prefixing the flag name with GLOG_, e.g.,
Activate logtostderr without gflags
GLOG_logtostderr=1 ./your_application\n
The following flags are most commonly used:
logtostderr (bool, default=false)
Log messages to stderr instead of logfiles.
stderrthreshold (int, default=2, which is ERROR)
Copy log messages at or above this level to stderr in addition to logfiles. The numbers of severity levels INFO, WARNING, ERROR, and FATAL are 0, 1, 2, and 3, respectively.
minloglevel (int, default=0, which is INFO)
Log messages at or above this level. Again, the numbers of severity levels INFO, WARNING, ERROR, and FATAL are 0, 1, 2, and 3, respectively.
log_dir (string, default=\"\")
If specified, logfiles are written into this directory instead of the default logging directory.
v (int, default=0)
Show all VLOG(m) messages for m less or equal the value of this flag. Overridable by --vmodule. Refer to verbose logging for more detail.
vmodule (string, default=\"\")
Per-module verbose level. The argument has to contain a comma-separated list of <module name>=<log level>. <module name> is a glob pattern (e.g., gfs* for all modules whose name starts with \"gfs\"), matched against the filename base (that is, name ignoring .cc/.h./-inl.h). <log level> overrides any value given by --v. See also verbose logging for more details.
Additional flags are defined in flags.cc. Please see the source for their complete list.
You can also modify flag values in your program by modifying global variables FLAGS_*. Most settings start working immediately after you update FLAGS_*. The exceptions are the flags related to destination files. For instance, you might want to set FLAGS_log_dir before calling google::InitGoogleLogging.
Setting log_dir at runtime
LOG(INFO) << \"file\";\n// Most flags work immediately after updating values.\nFLAGS_logtostderr = 1;\nLOG(INFO) << \"stderr\";\nFLAGS_logtostderr = 0;\n// This won\u2019t change the log destination. If you want to set this\n// value, you should do this before google::InitGoogleLogging .\nFLAGS_log_dir = \"/some/log/directory\";\nLOG(INFO) << \"the same file\";\n
Copyright \u00a9 2024, Google Inc. All rights reserved.
Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
Neither the name of Google Inc. nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS \"AS IS\" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
"},{"location":"log_cleaner/","title":"Automatically Remove Old Logs","text":"
To enable the log cleaner:
using namespace std::chrono_literals;\ngoogle::EnableLogCleaner(24h * 3); // keep your logs for 3 days\n
In C++20 (and later) this can be shortened to:
using namespace std::chrono_literals;\ngoogle::EnableLogCleaner(3d); // keep your logs for 3 days\n
And then glog will check if there are overdue logs whenever a flush is performed. In this example, any log file from your project whose last modified time is greater than 3 days will be unlink()ed.
This feature can be disabled at any time (if it has been enabled) using
Strings used in log messages can increase the size of your binary and present a privacy concern. You can therefore instruct glog to remove all strings which fall below a certain severity level by using the GOOGLE_STRIP_LOG macro:
If your application has code like this:
#define GOOGLE_STRIP_LOG 1 // this must go before the #include!\n#include <glog/logging.h>\n
The compiler will remove the log messages whose severities are less than the specified integer value. Since VLOG logs at the severity level INFO (numeric value 0), setting GOOGLE_STRIP_LOG to 1 or greater removes all log messages associated with VLOGs as well as INFO log statements.
glog defines a series of macros that simplify many common logging tasks. You can log messages by severity level, control logging behavior from the command line, log based on conditionals, abort the program when expected conditions are not met, introduce your own logging levels, customize the prefix attached to log messages, and more.
You can specify one of the following severity levels (in increasing order of severity):
INFO,
WARNING,
ERROR, and
FATAL.
Logging a FATAL message terminates the program (after the message is logged).
Note
Messages of a given severity are logged not only to corresponding severity logfile but also to other logfiles of lower severity. For instance, a message of severity FATAL will be logged to logfiles of severity FATAL, ERROR, WARNING, and INFO.
The DFATAL severity logs a FATAL error in debug mode (i.e., there is no NDEBUG macro defined), but avoids halting the program in production by automatically reducing the severity to ERROR.
Placeholder Meaning L A single character, representing the log level (e.g., I for INFO) yyyy The year mm The month (zero padded; i.e., May is 05) dd The day (zero padded) hh:mm:ss.uuuuuu Time in hours, minutes and fractional seconds threadid The space-padded thread ID file The file name line The line number msg The user-supplied message
Default log line prefix format
I1103 11:57:31.739339 24395 google.cc:2341] Command line: ./some_prog\nI1103 11:57:31.739403 24395 google.cc:2342] Process id 24395\n
Note
Although microseconds are useful for comparing events on a single machine, clocks on different machines may not be well synchronized. Hence, use with caution when comparing the low bits of timestamps from different machines.
The predefined log line prefix can be replaced using a user-provided callback that formats the corresponding output.
For each log entry, the callback will be invoked with a reference to a google::LogMessage instance containing the severity, filename, line number, thread ID, and time of the event. It will also be given a reference to the output stream, whose contents will be prepended to the actual message in the final log line.
function to pass a pointer to the corresponding MyPrefixFormatter callback during initialization. InstallPrefixFormatter takes a second optional argument of type void* that allows supplying user data to the callback.
Custom prefix formatter
The following function outputs a prefix that matches glog's default format. The third parameter data can be used to access user-supplied data which unless specified defaults to nullptr.
Sometimes, you may only want to log a message under certain conditions. You can use the following macros to perform conditional logging:
LOG_IF(INFO, num_cookies > 10) << \"Got lots of cookies\";\n
The \"Got lots of cookies\" message is logged only when the variable num_cookies exceeds 10. If a line of code is executed many times, it may be useful to only log a message at certain intervals. This kind of logging is most useful for informational messages.
When you are chasing difficult bugs, thorough log messages are very useful. However, you may want to ignore too verbose messages in usual development. For such verbose logging, glog provides the VLOG macro, which allows you to define your own numeric logging levels.
The --v command line option controls which verbose messages are logged:
VLOG(1) << \"I\u2019m printed when you run the program with --v=1 or higher\";\nVLOG(2) << \"I\u2019m printed when you run the program with --v=2 or higher\";\n
With VLOG, the lower the verbose level, the more likely messages are to be logged. For example, if --v==1, VLOG(1) will log, but VLOG(2) will not log.
Warning
The VLOG behavior is opposite of the severity level logging, where INFO, ERROR, etc. are defined in increasing order and thus --minloglevel of 1 will only log WARNING and above.
Though you can specify any integers for both VLOG macro and --v flag, the common values for them are small positive integers. For example, if you write VLOG(0), you should specify --v=-1 or lower to silence it. This is less useful since we may not want verbose logs by default in most cases. The VLOG macros always log at the INFO log level (when they log at all).
Verbose logging can be controlled from the command line on a per-module basis:
--vmodule=mapreduce=2,file=1,gfs*=3 --v=0\n
Specifying these options will specifically:
Print VLOG(2) and lower messages from mapreduce.{h,cc}
Print VLOG(1) and lower messages from file.{h,cc}
Print VLOG(3) and lower messages from files prefixed with \"gfs\"
Print VLOG(0) and lower messages from elsewhere
The wildcarding functionality 3. supports both * (matches 0 or more characters) and ? (matches any single character) wildcards. Please also refer to command line flags for more information.
There's also VLOG_IS_ON(n) \"verbose level\" condition macro. This macro returns true when the --v is equal to or greater than n. The macro can be used as follows:
if (VLOG_IS_ON(2)) {\n // (1)\n}\n
Here we can perform some logging preparation and logging that can\u2019t be accomplished with just VLOG(2) << \"message ...\";
Verbose level condition macros VLOG_IF, VLOG_EVERY_N and VLOG_IF_EVERY_N behave analogous to LOG_IF, LOG_EVERY_N, LOG_IF_EVERY_N, but accept a numeric verbosity level as opposed to a severity level.
VLOG_IF(1, (size > 1024))\n << \"I\u2019m printed when size is more than 1024 and when you run the \"\n \"program with --v=1 or more\";\nVLOG_EVERY_N(1, 10)\n << \"I\u2019m printed every 10th occurrence, and when you run the program \"\n \"with --v=1 or more. Present occurrence is \" << google::COUNTER;\nVLOG_IF_EVERY_N(1, (size > 1024), 10)\n << \"I\u2019m printed on every 10th occurrence of case when size is more \"\n \" than 1024, when you run the program with --v=1 or more. \";\n \"Present occurrence is \" << google::COUNTER;\n
Performance
The conditional logging macros provided by glog (e.g., CHECK, LOG_IF, VLOG, etc.) are carefully implemented and don't execute the right hand side expressions when the conditions are false. So, the following check may not sacrifice the performance of your application.
Special debug mode logging macros only have an effect in debug mode and are compiled away to nothing for non-debug mode compiles. Use these macros to avoid slowing down your production application due to excessive logging.
DLOG(INFO) << \"Found cookies\";\nDLOG_IF(INFO, num_cookies > 10) << \"Got lots of cookies\";\nDLOG_EVERY_N(INFO, 10) << \"Got the \" << google::COUNTER << \"th cookie\";\nDLOG_FIRST_N(INFO, 10) << \"Got the \" << google::COUNTER << \"th cookie\";\nDLOG_EVERY_T(INFO, 0.01) << \"Got a cookie\";\n
It is a good practice to check expected conditions in your program frequently to detect errors as early as possible. The CHECK macro provides the ability to abort the application when a condition is not met, similar to the assert macro defined in the standard C library.
CHECK aborts the application if a condition is not true. Unlike assert, it is not controlled by NDEBUG, so the check will be executed regardless of compilation mode. Therefore, fp->Write(x) in the following example is always executed:
CHECK(fp->Write(x) == 4) << \"Write failed!\";\n
There are various helper macros for equality/inequality checks -CHECK_EQ, CHECK_NE, CHECK_LE, CHECK_LT, CHECK_GE, and CHECK_GT. They compare two values, and log a FATAL message including the two values when the result is not as expected. The values must have operator<<(ostream, ...) defined.
You may append to the error message like so:
CHECK_NE(1, 2) << \": The world must be ending!\";\n
We are very careful to ensure that each argument is evaluated exactly once, and that anything which is legal to pass as a function argument is legal here. In particular, the arguments may be temporary expressions which will end up being destroyed at the end of the apparent statement, for example:
CHECK_EQ(string(\"abc\")[1], \u2019b\u2019);\n
The compiler reports an error if one of the arguments is a pointer and the other is nullptr. To work around this, simply static_castnullptr to the type of the desired pointer.
Since this macro returns the given pointer, this is very useful in constructor initializer lists.
struct S {\n S(Something* ptr) : ptr_(CHECK_NOTNULL(ptr)) {}\n Something* ptr_;\n};\n
Warning
Due to the argument forwarding, CHECK_NOTNULL cannot be used to simultaneously stream an additional custom message. To provide a custom message, one can use the macro CHECK_EQ prior to the failing check.
If you are comparing C strings (char *), a handy set of macros performs both case sensitive and insensitive comparisons - CHECK_STREQ, CHECK_STRNE, CHECK_STRCASEEQ, and CHECK_STRCASENE. The CHECK_*CASE* macro variants are case-insensitive. You can safely pass nullptr pointers to this macro. They treat nullptr and any non-nullptr string as not equal. Two nullptrs are equal.
Note
Both arguments may be temporary objects which are destructed at the end of the current full expression, such as
CHECK_STREQ(Foo().c_str(), Bar().c_str());\n
where Foo and Bar return std::string.
The CHECK_DOUBLE_EQ macro checks the equality of two floating point values, accepting a small error margin. CHECK_NEAR accepts a third floating point argument, which specifies the acceptable error margin.
The header file <glog/raw_logging.h> can be used for thread-safe logging, which does not allocate any memory or acquire any locks. Therefore, the macros defined in this header file can be used by low-level memory allocation and synchronization code. Please check src/glog/raw_logging.h for detail.
PLOG() and PLOG_IF() and PCHECK() behave exactly like their LOG* and CHECK equivalents with the addition that they append a description of the current state of errno to their output lines. E.g.
SYSLOG, SYSLOG_IF, and SYSLOG_EVERY_N macros are available. These log to syslog in addition to the normal logs. Be aware that logging to syslog can drastically impact performance, especially if syslog is configured for remote logging! Make sure you understand the implications of outputting to syslog before you use these macros. In general, it's wise to use these macros sparingly.
"},{"location":"packages/","title":"Installation using Package Managers","text":""},{"location":"packages/#conan","title":"conan","text":"
You can download and install glog using the conan package manager:
The glog recipe in conan center is kept up to date by conan center index community contributors. If the version is out of date, please create an issue or pull request on the conan-center-index repository.
The glog port in vcpkg is kept up to date by Microsoft team members and community contributors. If the version is out of date, please create an issue or pull request on the vcpkg repository.
Under certain circumstances, it is useful to send the log output to a destination other than a file, stderr and/or stdout. In case, the library provides the google::LogSink interface whose implementations can be used to write the log output to arbitrary locations.
To use the custom sink and instance of the above interface implementation must be registered using google::AddLogSink which expects a pointer to the google::LogSink instance. To unregister use google::RemoveLogSink. Both functions are thread-safe.
LogSink ownership
The google::LogSink instance must not be destroyed until the referencing pointer is unregistered.
Instead of registering the sink, we can directly use to log messages. While LOG_TO_SINK(sink, severity) allows to log both to the sink and to a global log registry, e.g., a file, LOG_TO_SINK_BUT_NOT_TO_LOGFILE(sink, severity) will avoid the latter.
Using a custom sink
custom_sink.cc
#include <glog/logging.h>\n\n#include <algorithm>\n#include <cstddef>\n#include <iostream>\n#include <iterator>\n\nnamespace {\n\nstruct MyLogSink : google::LogSink { // (1)!\n void send(google::LogSeverity severity, const char* /*full_filename*/,\n const char* base_filename, int line,\n const google::LogMessageTime& /*time*/, const char* message,\n std::size_t message_len) override {\n std::cout << google::GetLogSeverityName(severity) << ' ' << base_filename\n << ':' << line << ' ';\n std::copy_n(message, message_len,\n std::ostreambuf_iterator<char>{std::cout});\n std::cout << '\\n';\n }\n};\n\n} // namespace\n\nint main(int /*argc*/, char** argv) {\n google::InitGoogleLogging(argv[0]);\n\n MyLogSink sink;\n google::AddLogSink(&sink); // (2)!\n\n LOG(INFO) << \"logging to MySink\";\n\n google::RemoveLogSink(&sink); // (3)!\n\n // We can directly log to a sink without registering it\n LOG_TO_SINK(&sink, INFO) << \"direct logging\"; // (4)!\n LOG_TO_SINK_BUT_NOT_TO_LOGFILE(&sink, INFO)\n << \"direct logging but not to file\";\n}\n
MySink implements a custom sink that sends log messages to std::cout.
The custom sink must be registered to for use with existing logging macros.
Once the custom sink is no longer needed we remove it from the registry.
A sink does not need to be registered globally. However, then, messages must be logged using dedicated macros.
Running the above example as GLOG_log_dir=. ./custom_sink_example will produce
Custom sink output
INFO custom_sink.cc:63 logging to MySink\nINFO custom_sink.cc:68 direct logging\nINFO custom_sink.cc:69 direct logging but not to file (1)\n
This line is not present in the log file because we used LOG_TO_SINK_BUT_NOT_TO_LOGFILE to log the message.
and the corresponding log file will contain
Log file generated with the custom sink
Log file created at: 2024/06/11 13:24:27\nRunning on machine: pc\nRunning duration (h:mm:ss): 0:00:00\nLog line format: [IWEF]yyyymmdd hh:mm:ss.uuuuuu threadid file:line] msg\nI20240611 13:24:27.476620 126237946035776 custom_sink.cc:63] logging to MySink\nI20240611 13:24:27.476796 126237946035776 custom_sink.cc:68] direct logging\n
"},{"location":"unwinder/","title":"Installation Notes for 64-bit Linux Systems","text":"
Note
The description on this page is possibly not up-to-date.
The glibc built-in stack-unwinder on 64-bit systems has some problems with glog. In particular, if you are using InstallFailureSignalHandler(), the signal may be raised in the middle of malloc, holding some malloc-related locks when they invoke the stack unwinder. The built-in stack unwinder may call malloc recursively, which may require the thread to acquire a lock it already holds resulting in a deadlock.
For above reason, if you use a 64-bit system and you need InstallFailureSignalHandler(), we strongly recommend you install libunwind before trying to configure or install google glog. libunwind can be found here.
Even if you already have libunwind installed, you will probably still need to install from the snapshot to get the latest version.
Warning
If you install libunwind from the URL above, be aware that you may have trouble if you try to statically link your binary with glog: that is, if you link with gcc -static -lgcc_eh .... This is because both libunwind and libgcc implement the same C++ exception handling APIs, but they implement them differently on some platforms. This is not likely to be a problem on ia64, but may be on x86-64.
Also, if you link binaries statically, make sure that you add -Wl,--eh-frame-hdr to your linker options. This is required so that libunwind can find the information generated by the compiler required for stack unwinding.
Using -static is rare, though, so unless you know this will affect you it probably won't.
As we already mentioned, glibc's unwinder has a deadlock issue. However, if you don't use InstallFailureSignalHandler() or you don't worry about the rare possibilities of deadlocks, you can use this stack-unwinder. If you specify no options and libunwind isn't detected on your system, the configure script chooses this unwinder by default.
"},{"location":"unwinder/#frame-pointer-based-stack-unwinder","title":"Frame Pointer based Stack-unwinder","text":"
The frame pointer based stack unwinder requires that your application, the glog library, and system libraries like libc, all be compiled with a frame pointer. This is not the default for x86-64.
"},{"location":"usage/","title":"Using glog in a CMake Project","text":"
Assuming that glog was previously built using CMake or installed using a package manager, you can use the CMake command find_package to build against glog in your CMake project as follows:
Compile definitions and options will be added automatically to your target as needed.
Alternatively, glog can be incorporated into using the CMake command add_subdirectory to include glog directly from a subdirectory of your project by replacing the find_package call from the previous snippet by add_subdirectory. The glog::glog target is in this case an ALIAS library target for the glog library target.
"},{"location":"windows/","title":"Notes for Windows Users","text":"
glog defines the severity level ERROR, which is also defined by windows.h. You can make glog not define INFO, WARNING, ERROR, and FATAL by defining GLOG_NO_ABBREVIATED_SEVERITIES before including glog/logging.h. Even with this macro, you can still use the iostream like logging facilities:
#define GLOG_NO_ABBREVIATED_SEVERITIES\n#include <windows.h>\n#include <glog/logging.h>\n\n// ...\n\nLOG(ERROR) << \"This should work\";\nLOG_IF(ERROR, x > y) << \"This should be also OK\";\n
However, you cannot use INFO, WARNING, ERROR, and FATAL anymore for functions defined in glog/logging.h.
#define GLOG_NO_ABBREVIATED_SEVERITIES\n#include <windows.h>\n#include <glog/logging.h>\n\n// ...\n\n// This won\u2019t work.\n// google::FlushLogFiles(google::ERROR);\n\n// Use this instead.\ngoogle::FlushLogFiles(google::GLOG_ERROR);\n
If you don't need ERROR defined by windows.h, there are a couple of more workarounds which sometimes don't work1:
#define WIN32_LEAN_AND_MEAN or NOGDI before #include <windows.h>.
#undef ERROR after #include <windows.h>.
For more information refer to this issue.\u00a0\u21a9
"}]}
\ No newline at end of file
diff --git a/0.8.0/sinks/index.html b/0.8.0/sinks/index.html
index 421b467..319a4f2 100644
--- a/0.8.0/sinks/index.html
+++ b/0.8.0/sinks/index.html
@@ -11,7 +11,7 @@
-
+
@@ -356,6 +356,8 @@
+
+
@@ -414,6 +416,27 @@
+
+
+