1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
5 <title>How To Use Google Logging Library (glog)</title>
7 <meta http-equiv="Content-Type" content="text/html; charset=utf-8">
8 <link href="http://www.google.com/favicon.ico" type="image/x-icon"
10 <link href="designstyle.css" type="text/css" rel="stylesheet">
11 <style type="text/css">
15 font-family: sans-serif;
19 font-family: "Times Roman", times, serif;
23 font-family: "Times Roman", times, serif;
31 <h1>How To Use Google Logging Library (glog)</h1>
33 <script type=text/javascript>
34 var lm = new Date(document.lastModified);
35 document.write(lm.toDateString());
40 <h2> <A NAME=intro>Introduction</A> </h2>
42 <p><b>Google glog</b> is a library that implements application-level
43 logging. This library provides logging APIs based on C++-style
44 streams and various helper macros.
45 You can log a message by simply streaming things to LOG(<a
46 particular <a href="#severity">severity level</a>>), e.g.
49 #include <google/logging.h>
51 int main(int argc, char* argv[]) {
52 // Initialize Google's logging library.
53 google::InitGoogleLogging(argv[0]);
56 LOG(INFO) << "Found " << num_cookies << " cookies";
60 <p>Google glog defines a series of macros that simplify many common logging
61 tasks. You can log messages by severity level, control logging
62 behavior from the command line, log based on conditionals, abort the
63 program when expected conditions are not met, introduce your own
64 verbose logging levels, and more. This document describes the
65 functionality supported by glog. Please note that this document
66 doesn't describe all features in this library, but the most useful
67 ones. If you want to find less common features, please check
68 header files under <code>src/google</code> directory.
70 <h2> <A NAME=severity>Severity Level</A> </h2>
73 You can specify one of the following severity levels (in
74 increasing order of severity): <code>INFO</code>, <code>WARNING</code>,
75 <code>ERROR</code>, and <code>FATAL</code>.
76 Logging a <code>FATAL</code> message terminates the program (after the
78 Note that messages of a given severity are logged not only in the
79 logfile for that severity, but also in all logfiles of lower severity.
80 E.g., a message of severity <code>FATAL</code> will be logged to the
81 logfiles of severity <code>FATAL</code>, <code>ERROR</code>,
82 <code>WARNING</code>, and <code>INFO</code>.
85 The <code>DFATAL</code> severity logs a <code>FATAL</code> error in
86 debug mode (i.e., there is no <code>NDEBUG</code> macro defined), but
87 avoids halting the program in production by automatically reducing the
88 severity to <code>ERROR</code>.
90 <p>Unless otherwise specified, glog writes to the filename
91 "/tmp/<program name>.<hostname>.<user name>.log.<severity level>.<date>.<time>.<pid>"
92 (e.g., "/tmp/hello_world.example.com.hamaji.log.INFO.20080709-222411.10474").
93 By default, glog copies the log messages of severity level
94 <code>ERROR</code> or <code>FATAL</code> to standard error (stderr)
95 in addition to log files.
97 <h2><A NAME=flags>Setting Flags</A></h2>
99 <p>Several flags influences glog's output behavior.
100 If the <a href="http://code.google.com/p/google-gflags/">Google
101 gflags library</a> is installed on your machine, the
102 <code>configure</code> script (see the INSTALL file in the package for
103 detail of this script) will automatically detect and use it,
104 allowing you to pass flags on the command line. For example, if you
105 want to turn the flag <code>--logtostderr</code> on, you can start
106 your application with the following command line:
109 ./your_application --logtostderr=1
112 If the Google gflags library isn't installed, you set flags via
113 environment variables, prefixing the flag name with "GLOG_", e.g.
116 GLOG_logtostderr=1 ./your_application
119 <p>The following flags are most commonly used:
122 <dt><code>logtostderr</code> (<code>bool</code>, default=<code>false</code>)
123 <dd>Log messages to stderr instead of logfiles.<br>
124 Note: you can set binary flags to <code>true</code> by specifying
125 <code>1</code>, <code>true</code> , or <code>yes</code> (case
127 Also, you can set binary flags to <code>false</code> by specifying
128 <code>0</code>, <code>false</code>, or <code>no</code> (again, case
130 <dt><code>stderrthreshold</code> (<code>int</code>, default=2, which
131 is <code>ERROR</code>)
132 <dd>Copy log messages at or above this level to stderr in
133 addition to logfiles. The numbers of severity levels
134 <code>INFO</code>, <code>WARNING</code>, <code>ERROR</code>, and
135 <code>FATAL</code> are 0, 1, 2, and 3, respectively.
136 <dt><code>minloglevel</code> (<code>int</code>, default=0, which
137 is <code>INFO</code>)
138 <dd>Log messages at or above this level. Again, the numbers of
139 severity levels <code>INFO</code>, <code>WARNING</code>,
140 <code>ERROR</code>, and <code>FATAL</code> are 0, 1, 2, and 3,
142 <dt><code>log_dir</code> (<code>string</code>, default="")
143 <dd>If specified, logfiles are written into this directory instead
144 of the default logging directory.
145 <dt><code>v</code> (<code>int</code>, default=0)
146 <dd>Show all <code>VLOG(m)</code> messages for <code>m</code> less or
147 equal the value of this flag. Overridable by --vmodule.
148 See <a href="#verbose">the section about verbose logging</a> for more
150 <dt><code>vmodule</code> (<code>string</code>, default="")
151 <dd>Per-module verbose level. The argument has to contain a
152 comma-separated list of <module name>=<log level>.
154 is a glob pattern (e.g., <code>gfs*</code> for all modules whose name
155 starts with "gfs"), matched against the filename base
156 (that is, name ignoring .cc/.h./-inl.h).
157 <log level> overrides any value given by --v.
158 See also <a href="#verbose">the section about verbose logging</a>.
161 <p>There are some other flags defined in logging.cc. Please grep the
162 source code for "DEFINE_" to see a complete list of all flags.
164 <h2><A NAME=conditional>Conditional / Occasional Logging</A></h2>
166 <p>Sometimes, you may only want to log a message under certain
167 conditions. You can use the following macros to perform conditional
171 LOG_IF(INFO, num_cookies > 10) << "Got lots of cookies";
174 The "Got lots of cookies" message is logged only when the variable
175 <code>num_cookies</code> exceeds 10.
177 If a line of code is executed many times, it may be useful to only log
178 a message at certain intervals. This kind of logging is most useful
179 for informational messages.
182 LOG_EVERY_N(INFO, 10) << "Got the " << COUNTER << "th cookie";
185 <p>The above line outputs a log messages on the 1st, 11th,
186 21st, ... times it is executed. Note that the special
187 <code>COUNTER</code> value is used to identify which repetition is
190 <p>You can combine conditional and occasional logging with the
194 LOG_IF_EVERY_N(INFO, (size > 1024), 10) << "Got the " << COUNTER
195 << "th big cookie";
198 <p>Instead of outputting a message every nth time, you can also limit
199 the output to the first n occurrences:
202 LOG_FIRST_N(INFO, 20) << "Got the " << COUNTER << "th cookie";
205 <p>Outputs log messages for the first 20 times it is executed. Again,
206 the <code>COUNTER</code> identifier indicates which repetition is
209 <h2><A NAME=debug>Debug Mode Support</A></h2>
211 <p>Special "debug mode" logging macros only have an effect in debug
212 mode and are compiled away to nothing for non-debug mode
213 compiles. Use these macros to avoid slowing down your production
214 application due to excessive logging.
217 DLOG(INFO) << "Found cookies";
219 DLOG_IF(INFO, num_cookies > 10) << "Got lots of cookies";
221 DLOG_EVERY_N(INFO, 10) << "Got the " << COUNTER << "th cookie";
224 <p>All "debug mode" logging is compiled away to nothing for non-debug mode
227 <h2><A NAME=check>CHECK Macros</A></h2>
229 <p>It is a good practice to check expected conditions in your program
230 frequently to detect errors as early as possible. The
231 <code>CHECK</code> macro provides the ability to abort the application
232 when a condition is not met, similar to the <code>assert</code> macro
233 defined in the standard C library.
235 <p><code>CHECK</code> aborts the application if a condition is not
236 true. Unlike <code>assert</code>, it is *not* controlled by
237 <code>NDEBUG</code>, so the check will be executed regardless of
238 compilation mode. Therefore, <code>fp->Write(x)</code> in the
239 following example is always executed:
242 CHECK(fp->Write(x) == 4) << "Write failed!";
245 <p>There are various helper macros for
246 equality/inequality checks - <code>CHECK_EQ</code>,
247 <code>CHECK_NE</code>, <code>CHECK_LE</code>, <code>CHECK_LT</code>,
248 <code>CHECK_GE</code>, and <code>CHECK_GT</code>.
249 They compare two values, and log a
250 <code>FATAL</code> message including the two values when the result is
251 not as expected. The values must have <code>operator<<(ostream,
254 <p>You may append to the error message like so:
257 CHECK_NE(1, 2) << ": The world must be ending!";
260 <p>We are very careful to ensure that each argument is evaluated exactly
261 once, and that anything which is legal to pass as a function argument is
262 legal here. In particular, the arguments may be temporary expressions
263 which will end up being destroyed at the end of the apparent statement,
267 CHECK_EQ(string("abc")[1], 'b');
270 <p>The compiler reports an error if one of the arguments is a
271 pointer and the other is NULL. To work around this, simply static_cast
272 NULL to the type of the desired pointer.
275 CHECK_EQ(some_ptr, static_cast<SomeType*>(NULL));
278 <p>Better yet, use the CHECK_NOTNULL macro:
281 CHECK_NOTNULL(some_ptr);
282 some_ptr->DoSomething();
285 <p>Since this macro returns the given pointer, this is very useful in
286 constructor initializer lists.
290 S(Something* ptr) : ptr_(CHECK_NOTNULL(ptr)) {}
295 <p>Note that you cannot use this macro as a C++ stream due to this
296 feature. Please use <code>CHECK_EQ</code> described above to log a
297 custom message before aborting the application.
299 <p>If you are comparing C strings (char *), a handy set of macros
300 performs case sensitive as well as case insensitive comparisons -
301 <code>CHECK_STREQ</code>, <code>CHECK_STRNE</code>,
302 <code>CHECK_STRCASEEQ</code>, and <code>CHECK_STRCASENE</code>. The
303 CASE versions are case-insensitive. You can safely pass <code>NULL</code>
304 pointers for this macro. They treat <code>NULL</code> and any
305 non-<code>NULL</code> string as not equal. Two <code>NULL</code>s are
308 <p>Note that both arguments may be temporary strings which are
309 destructed at the end of the current "full expression"
310 (e.g., <code>CHECK_STREQ(Foo().c_str(), Bar().c_str())</code> where
311 <code>Foo</code> and <code>Bar</code> returns C++'s
312 <code>std::string</code>).
314 <p>The <code>CHECK_DOUBLE_EQ</code> macro checks the equality of two
315 floating point values, accepting a small error margin.
316 <code>CHECK_NEAR</code> accepts a third floating point argument, which
317 specifies the acceptable error margin.
319 <h2><A NAME=verbose>Verbose Logging</A></h2>
321 <p>When you are chasing difficult bugs, thorough log messages are very
322 useful. However, you may want to ignore too verbose messages in usual
323 development. For such verbose logging, glog provides the
324 <code>VLOG</code> macro, which allows you to define your own numeric
325 logging levels. The <code>--v</code> command line option controls
326 which verbose messages are logged:
329 VLOG(1) << "I'm printed when you run the program with --v=1 or higher";
330 VLOG(2) << "I'm printed when you run the program with --v=2 or higher";
333 <p>With <code>VLOG</code>, the lower the verbose level, the more
334 likely messages are to be logged. For example, if
335 <code>--v==1</code>, <code>VLOG(1)</code> will log, but
336 <code>VLOG(2)</code> will not log. This is opposite of the severity
337 level, where <code>INFO</code> is 0, and <code>ERROR</code> is 2.
338 <code>--minloglevel</code> of 1 will log <code>WARNING</code> and
339 above. Though you can specify any integers for both <code>VLOG</code>
340 macro and <code>--v</code> flag, the common values for them are small
341 positive integers. For example, if you write <code>VLOG(0)</code>,
342 you should specify <code>--v=-1</code> or lower to silence it. This
343 is less useful since we may not want verbose logs by default in most
344 cases. The <code>VLOG</code> macros always log at the
345 <code>INFO</code> log level (when they log at all).
347 <p>Verbose logging can be controlled from the command line on a
351 --vmodule=mapreduce=2,file=1,gfs*=3 --v=0
357 <li>a. Print VLOG(2) and lower messages from mapreduce.{h,cc}
358 <li>b. Print VLOG(1) and lower messages from file.{h,cc}
359 <li>c. Print VLOG(3) and lower messages from files prefixed with "gfs"
360 <li>d. Print VLOG(0) and lower messages from elsewhere
363 <p>The wildcarding functionality shown by (c) supports both '*'
364 (matches 0 or more characters) and '?' (matches any single character)
365 wildcards. Please also check the section about <a
366 href="#flags">command line flags</a>.
368 <p>There's also <code>VLOG_IS_ON(n)</code> "verbose level" condition
369 macro. This macro returns true when the <code>--v</code> is equal or
370 greater than <code>n</code>. To be used as
374 // do some logging preparation and logging
375 // that can't be accomplished with just VLOG(2) << ...;
379 <p>Verbose level condition macros <code>VLOG_IF</code>,
380 <code>VLOG_EVERY_N</code> and <code>VLOG_IF_EVERY_N</code> behave
381 analogous to <code>LOG_IF</code>, <code>LOG_EVERY_N</code>,
382 <code>LOF_IF_EVERY</code>, but accept a numeric verbosity level as
383 opposed to a severity level.
386 VLOG_IF(1, (size > 1024))
387 << "I'm printed when size is more than 1024 and when you run the "
388 "program with --v=1 or more";
390 << "I'm printed every 10th occurrence, and when you run the program "
391 "with --v=1 or more. Present occurence is " << COUNTER;
392 VLOG_IF_EVERY_N(1, (size > 1024), 10)
393 << "I'm printed on every 10th occurence of case when size is more "
394 " than 1024, when you run the program with --v=1 or more. ";
395 "Present occurence is " << COUNTER;
398 <h2> <A name="misc">Miscellaneous Notes</A> </h2>
400 <h3><A NAME=message>Performance of Messages</A></h3>
402 <p>The conditional logging macros provided by glog (e.g.,
403 <code>CHECK</code>, <code>LOG_IF</code>, <code>VLOG</code>, ...) are
404 carefully implemented and don't execute the right hand side
405 expressions when the conditions are false. So, the following check
406 may not sacrifice the performance of your application.
409 CHECK(obj.ok) << obj.CreatePrettyFormattedStringButVerySlow();
412 <h3><A NAME=failure>User-defined Failure Function</A></h3>
414 <p><code>FATAL</code> severity level messages or unsatisfied
415 <code>CHECK</code> condition terminate your program. You can change
416 the behavior of the termination by
417 <code>InstallFailureFunction</code>.
420 void YourFailureFunction() {
421 // Reports something...
425 int main(int argc, char* argv[]) {
426 google::InstallFailureFunction(&YourFailureFunction);
430 <p>By default, glog tries to dump stacktrace and makes the program
431 exit with status 1. The stacktrace is produced only when you run the
432 program on an architecture for which glog supports stack tracing (as
433 of September 2008, glog supports stack tracing for x86 and x86_64).
435 <h3><A NAME=raw>Raw Logging</A></h3>
437 <p>The header file <code><google/raw_logging.h></code> can be
438 used for thread-safe logging, which does not allocate any memory or
439 acquire any locks. Therefore, the macros defined in this
440 header file can be used by low-level memory allocation and
441 synchronization code.
442 Please check <code>src/google/raw_logging.h.in</code> for detail.
445 <h3><A NAME=plog>Google Style perror()</A></h3>
447 <p><code>PLOG()</code> and <code>PLOG_IF()</code> and
448 <code>PCHECK()</code> behave exactly like their <code>LOG*</code> and
449 <code>CHECK</code> equivalents with the addition that they append a
450 description of the current state of errno to their output lines.
454 PCHECK(write(1, NULL, 2) >= 0) << "Write NULL failed";
457 <p>This check fails with the following error message.
460 F0825 185142 test.cc:22] Check failed: write(1, NULL, 2) >= 0 Write NULL failed: Bad address [14]
463 <h3><A NAME=syslog>Syslog</A></h3>
465 <p><code>SYSLOG</code>, <code>SYSLOG_IF</code>, and
466 <code>SYSLOG_EVERY_N</code> macros are available.
467 These log to syslog in addition to the normal logs. Be aware that
468 logging to syslog can drastically impact performance, especially if
469 syslog is configured for remote logging! Make sure you understand the
470 implications of outputting to syslog before you use these macros. In
471 general, it's wise to use these macros sparingly.
473 <h3><A NAME=strip>Strip Logging Messages</A></h3>
475 <p>Strings used in log messages can increase the size of your binary
476 and present a privacy concern. You can therefore instruct glog to
477 remove all strings which fall below a certain severity level by using
478 the GOOGLE_STRIP_LOG macro:
480 <p>If your application has code like this:
483 #define GOOGLE_STRIP_LOG 1 // this must go before the #include!
484 #include <google/logging.h>
487 <p>The compiler will remove the log messages whose severity are less
488 than the specified integer value. Since
489 <code>VLOG</code> logs at the severity level <code>INFO</code>
490 (numeric value <code>0</code>),
491 setting <code>GOOGLE_STRIP_LOG</code> to 1 or greater removes
492 all log messages associated with <code>VLOG</code>s as well as
493 <code>INFO</code> log statements.
497 Shinichiro Hamaji<br>
499 <script type=text/javascript>
500 var lm = new Date(document.lastModified);
501 document.write(lm.toDateString());