Google Logging (glog) is a C++98 library that implements application-level
logging. The library provides logging APIs based on C++-style streams and
various helper macros.
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. Here’s a simple example:
glog also supports CMake that can be used to build the project on a wide
range of platforms. If you don’t have CMake installed already, you can
download it for from CMake’s official
website.
CMake works by generating native makefiles or build projects that can be
used in the compiler environment of your choice. You can either build
glog with CMake as a standalone project or it can be incorporated into
an existing CMake build for another project.
When building glog as a standalone project, on Unix-like systems with
GNU Make as build tool, the typical workflow is:
Get the source code and change to it. e.g., cloning with git:
git clone https://github.com/google/glog.git
cd glog
Run CMake to configure the build tree.
cmake -S . -B build -G "Unix Makefiles"
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.
You can also use the CMake command add_subdirectory to include glog
directly from a subdirectory of your project by replacing the
find_package call from the previous example by
add_subdirectory. The glog::glog target is in this case an
ALIAS library target for the glog library target.
Again, compile definitions and options will be added automatically to
your target as needed.
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.
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 verbose logging
levels, customize the prefix attached to log messages, and more.
Following sections describe the functionality supported by glog. Please note
this description may not be complete but limited to the most useful ones. If you
want to find less common features, please check header files under src/glog directory.
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 that messages of a given severity are logged not only in
the logfile for that severity, but also in all logfiles of lower
severity. E.g., a message of severity FATAL will be logged to the
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.
Unless otherwise specified, glog writes to the filename
/tmp/\<program name\>.\<hostname\>.\<user name\>.log.\<severity level\>.\<date\>-\<time\>.\<pid\>
(e.g.,
/tmp/hello_world.example.com.hamaji.log.INFO.20080709-222411.10474).
By default, glog copies the log messages of severity level ERROR or
FATAL to standard error (stderr) in addition to log files.
Several flags influence glog’s output behavior. 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. For example, if you want to turn the flag --logtostderr on,
you can start your application with the following command line:
./your_application --logtostderr=1
If the Google gflags library isn’t installed, you set flags via
environment variables, prefixing the flag name with GLOG_, e.g.,
GLOG_logtostderr=1 ./your_application
The following flags are most commonly used:
logtostderr (bool, default=false)
Log messages to stderr instead of logfiles. Note: you can set
binary flags to true by specifying 1, true, or yes
(case insensitive). Also, you can set binary flags to false by
specifying 0, false, or no (again, case insensitive).
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. See the section about
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 the section about verbose logging.
There are some other flags defined in logging.cc. Please grep the source
code for DEFINE_ to see a complete list of all flags.
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 example, you might want to set FLAGS_log_dir
before calling google::InitGoogleLogging . Here is an example:
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";
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.
The above line outputs a log messages on the 1st, 11th, 21st, ... times
it is executed. Note that the special google::COUNTER value is used
to identify which repetition is happening.
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";
Instead of outputting a message every nth time, you can also limit the
output to the first n occurrences:
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.
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!";
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!";
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’);
The compiler reports an error if one of the arguments is a pointer and the other
is NULL. To work around this, simply static_castNULL to
the type of the desired pointer.
CHECK_EQ(some_ptr, static_cast<SomeType*>(NULL));
Better yet, use the CHECK_NOTNULL macro:
CHECK_NOTNULL(some_ptr);
some_ptr->DoSomething();
Since this macro returns the given pointer, this is very useful in
constructor initializer lists.
Note that you cannot use this macro as a C++ stream due to this feature.
Please use CHECK_EQ described above to log a custom message before
aborting the application.
If you are comparing C strings (char *), a handy set of macros performs
case sensitive as well as case insensitive comparisons - CHECK_STREQ,
CHECK_STRNE, CHECK_STRCASEEQ, and CHECK_STRCASENE. The CASE versions
are case-insensitive. You can safely pass NULL pointers for this macro. They
treat NULL and any non-NULL string as not equal. Two NULLs are equal.
Note that both arguments may be temporary strings which are destructed
at the end of the current "full expression" (e.g.,
CHECK_STREQ(Foo().c_str(), Bar().c_str()) where Foo and Bar
return C++’s 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.
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’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. This is opposite of the severity level, where INFO is 0, and
ERROR is 2. --minloglevel of 1 will 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
will:
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 shown by (c) supports both ’*’ (matches 0
or more characters) and ’?’ (matches any single character) wildcards.
Please also check the section about command line flags.
There’s also VLOG_IS_ON(n) "verbose level" condition macro. This
macro returns true when the --v is equal or greater than n. To
be used as
if (VLOG_IS_ON(2)) {
// do some logging preparation and logging// that can’t be accomplished with just VLOG(2) << ...;
}
Verbose level condition macros VLOG_IF, VLOG_EVERY_N and
VLOG_IF_EVERY_N behave analogous to LOG_IF, LOG_EVERY_N,
LOF_IF_EVERY, 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 occurence is " << google::COUNTER;
VLOG_IF_EVERY_N(1, (size > 1024), 10)
<< "I’m printed on every 10th occurence of case when size is more "
" than 1024, when you run the program with --v=1 or more. ";
"Present occurence is " << google::COUNTER;
glog supports changing the format of the prefix attached to log messages by
receiving a user-provided callback to be used to generate such strings. That
feature must be enabled at compile time by the WITH_CUSTOM_PREFIX flag.
For each log entry, the callback will be invoked with a LogMessageInfo
struct 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.
For example:
/* This function writes a prefix that matches glog's default format. * (The third parameter can be used to receive user-supplied data, and is * NULL by default.)*/voidCustomPrefix(std::ostream &s, const LogMessageInfo &l, void*) {
s << l.severity[0]
<< setw(4) << 1900 + l.time.year()
<< setw(2) << 1 + l.time.month()
<< setw(2) << l.time.day()
<< ''
<< setw(2) << l.time.hour() << ':'
<< setw(2) << l.time.min() << ':'
<< setw(2) << l.time.sec() << "."
<< setw(6) << l.time.usec()
<< ''
<< setfill('') << setw(5)
<< l.thread_id << setfill('0')
<< ''
<< l.filename << ':' << l.line_number << "]";
}
To enable the use of CustomPrefix(), simply give glog a pointer to it
during initialization: InitGoogleLogging(argv[0], &CustomPrefix);.
Optionally, InitGoogleLogging() takes a third argument of type void*
to pass on to the callback function.
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 ***
*** SIGSEGV (@0x0) received by PID 17711 (TID 0x7f893090a6f0) from PID 0; stack trace: ***
PC: @ 0x412eb1 TestWaitingLogSink::send()
@ 0x7f892fb417d0 (unknown)
@ 0x412eb1 TestWaitingLogSink::send()
@ 0x7f89304f7f06 google::LogMessage::SendToLog()
@ 0x7f89304f35af google::LogMessage::Flush()
@ 0x7f89304f3739 google::LogMessage::~LogMessage()
@ 0x408cf4 TestLogSinkWaitTillSent()
@ 0x4115de main
@ 0x7f892f7ef1c4 (unknown)
@ 0x4046f9 (unknown)
By default, the signal handler writes the failure dump to the standard
error. You can customize the destination by InstallFailureWriter().
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.
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 stacktrace and makes the program exit
with status 1. The stacktrace is produced only when you run the program
on an architecture for which glog supports stack tracing (as of
September 2008, glog supports stack tracing for x86 and x86_64).
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.in 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.
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:
#defineGOOGLE_STRIP_LOG1// this must go before the #
客服电话
APP下载
官方微信
)
请发表评论