doc/glog.html

   1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
   2
   3 <html>
   4 <head>
   5 <title>How To Use Google Logging Library (glog)</title>
   6
   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"
   9       rel="shortcut icon">
  10 <link href="designstyle.css" type="text/css" rel="stylesheet">
  11 <style type="text/css">
  12 <!--
  13   ol.bluelist li {
  14     color: #3366ff;
  15     font-family: sans-serif;
  16   }
  17   ol.bluelist li p {
  18     color: #000;
  19     font-family: "Times Roman", times, serif;
  20   }
  21   ul.blacklist li {
  22     color: #000;
  23     font-family: "Times Roman", times, serif;
  24   }
  25 //-->
  26 </style>
  27 </head>
  28
  29 <body>
  30
  31 <h1>How To Use Google Logging Library (glog)</h1>
  32 <small>(as of
  33 <script type=text/javascript>
  34   var lm = new Date(document.lastModified);
  35   document.write(lm.toDateString());
  36 </script>)
  37 </small>
  38 <br>
  39
  40 <h2> <A NAME=intro>Introduction</A> </h2>
  41
  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(&lt;a
  46 particular <a href="#severity">severity level</a>&gt;), e.g.
  47
  48 <pre>
  49    #include &lt;glog/logging.h&gt;
  50
  51    int main(int argc, char* argv[]) {
  52      // Initialize Google's logging library.
  53      google::InitGoogleLogging(argv[0]);
  54
  55      // ...
  56      LOG(INFO) &lt;&lt; "Found " &lt;&lt; num_cookies &lt;&lt; " cookies";
  57    }
  58 </pre>
  59
  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/glog</code> directory.
  69
  70 <h2> <A NAME=severity>Severity Level</A> </h2>
  71
  72 <p>
  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
  77 message is logged).
  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>.
  83
  84 <p>
  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>.
  89
  90 <p>Unless otherwise specified, glog writes to the filename
  91 "/tmp/&lt;program name&gt;.&lt;hostname&gt;.&lt;user name&gt;.log.&lt;severity level&gt;.&lt;date&gt;.&lt;time&gt;.&lt;pid&gt;"
  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.
  96
  97 <h2><A NAME=flags>Setting Flags</A></h2>
  98
  99 <p>Several flags influence 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:
 107
 108 <pre>
 109    ./your_application --logtostderr=1
 110 </pre>
 111
 112 If the Google gflags library isn't installed, you set flags via
 113 environment variables, prefixing the flag name with "GLOG_", e.g.
 114
 115 <pre>
 116    GLOG_logtostderr=1 ./your_application
 117 </pre>
 118
 119 <p>The following flags are most commonly used:
 120
 121 <dl>
 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
 126 insensitive).
 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
 129 insensitive).
 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,
 141 respectively.
 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
 149 detail.
 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 &lt;module name&gt;=&lt;log level&gt;.
 153 &lt;module name&gt;
 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 &lt;log level&gt; overrides any value given by --v.
 158 See also <a href="#verbose">the section about verbose logging</a>.
 159 </dl>
 160
 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.
 163
 164 <h2><A NAME=conditional>Conditional / Occasional Logging</A></h2>
 165
 166 <p>Sometimes, you may only want to log a message under certain
 167 conditions. You can use the following macros to perform conditional
 168 logging:
 169
 170 <pre>
 171    LOG_IF(INFO, num_cookies &gt; 10) &lt;&lt; "Got lots of cookies";
 172 </pre>
 173
 174 The "Got lots of cookies" message is logged only when the variable
 175 <code>num_cookies</code> exceeds 10.
 176
 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.
 180
 181 <pre>
 182    LOG_EVERY_N(INFO, 10) &lt;&lt; "Got the " &lt;&lt; COUNTER &lt;&lt; "th cookie";
 183 </pre>
 184
 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
 188 happening.
 189
 190 <p>You can combine conditional and occasional logging with the
 191 following macro.
 192
 193 <pre>
 194    LOG_IF_EVERY_N(INFO, (size &gt; 1024), 10) &lt;&lt; "Got the " &lt;&lt; COUNTER
 195                                            &lt;&lt; "th big cookie";
 196 </pre>
 197
 198 <p>Instead of outputting a message every nth time, you can also limit
 199 the output to the first n occurrences:
 200
 201 <pre>
 202    LOG_FIRST_N(INFO, 20) &lt;&lt; "Got the " &lt;&lt; COUNTER &lt;&lt; "th cookie";
 203 </pre>
 204
 205 <p>Outputs log messages for the first 20 times it is executed.  Again,
 206 the <code>COUNTER</code> identifier indicates which repetition is
 207 happening.
 208
 209 <h2><A NAME=debug>Debug Mode Support</A></h2>
 210
 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.
 215
 216 <pre>
 217    DLOG(INFO) &lt;&lt; "Found cookies";
 218
 219    DLOG_IF(INFO, num_cookies &gt; 10) &lt;&lt; "Got lots of cookies";
 220
 221    DLOG_EVERY_N(INFO, 10) &lt;&lt; "Got the " &lt;&lt; COUNTER &lt;&lt; "th cookie";
 222 </pre>
 223
 224 <h2><A NAME=check>CHECK Macros</A></h2>
 225
 226 <p>It is a good practice to check expected conditions in your program
 227 frequently to detect errors as early as possible. The
 228 <code>CHECK</code> macro provides the ability to abort the application
 229 when a condition is not met, similar to the <code>assert</code> macro
 230 defined in the standard C library.
 231
 232 <p><code>CHECK</code> aborts the application if a condition is not
 233 true.  Unlike <code>assert</code>, it is *not* controlled by
 234 <code>NDEBUG</code>, so the check will be executed regardless of
 235 compilation mode.  Therefore, <code>fp-&gt;Write(x)</code> in the
 236 following example is always executed:
 237
 238 <pre>
 239    CHECK(fp-&gt;Write(x) == 4) &lt;&lt; "Write failed!";
 240 </pre>
 241
 242 <p>There are various helper macros for
 243 equality/inequality checks - <code>CHECK_EQ</code>,
 244 <code>CHECK_NE</code>, <code>CHECK_LE</code>, <code>CHECK_LT</code>,
 245 <code>CHECK_GE</code>, and <code>CHECK_GT</code>.
 246 They compare two values, and log a
 247 <code>FATAL</code> message including the two values when the result is
 248 not as expected.  The values must have <code>operator&lt;&lt;(ostream,
 249 ...)</code> defined.
 250
 251 <p>You may append to the error message like so:
 252
 253 <pre>
 254    CHECK_NE(1, 2) &lt;&lt; ": The world must be ending!";
 255 </pre>
 256
 257 <p>We are very careful to ensure that each argument is evaluated exactly
 258 once, and that anything which is legal to pass as a function argument is
 259 legal here.  In particular, the arguments may be temporary expressions
 260 which will end up being destroyed at the end of the apparent statement,
 261 for example:
 262
 263 <pre>
 264    CHECK_EQ(string("abc")[1], 'b');
 265 </pre>
 266
 267 <p>The compiler reports an error if one of the arguments is a
 268 pointer and the other is NULL. To work around this, simply static_cast
 269 NULL to the type of the desired pointer.
 270
 271 <pre>
 272    CHECK_EQ(some_ptr, static_cast&lt;SomeType*&gt;(NULL));
 273 </pre>
 274
 275 <p>Better yet, use the CHECK_NOTNULL macro:
 276
 277 <pre>
 278    CHECK_NOTNULL(some_ptr);
 279    some_ptr-&gt;DoSomething();
 280 </pre>
 281
 282 <p>Since this macro returns the given pointer, this is very useful in
 283 constructor initializer lists.
 284
 285 <pre>
 286    struct S {
 287      S(Something* ptr) : ptr_(CHECK_NOTNULL(ptr)) {}
 288      Something* ptr_;
 289    };
 290 </pre>
 291
 292 <p>Note that you cannot use this macro as a C++ stream due to this
 293 feature.  Please use <code>CHECK_EQ</code> described above to log a
 294 custom message before aborting the application.
 295
 296 <p>If you are comparing C strings (char *), a handy set of macros
 297 performs case sensitive as well as case insensitive comparisons -
 298 <code>CHECK_STREQ</code>, <code>CHECK_STRNE</code>,
 299 <code>CHECK_STRCASEEQ</code>, and <code>CHECK_STRCASENE</code>.  The
 300 CASE versions are case-insensitive.  You can safely pass <code>NULL</code>
 301 pointers for this macro.  They treat <code>NULL</code> and any
 302 non-<code>NULL</code> string as not equal.  Two <code>NULL</code>s are
 303 equal.
 304
 305 <p>Note that both arguments may be temporary strings which are
 306 destructed at the end of the current "full expression"
 307 (e.g., <code>CHECK_STREQ(Foo().c_str(), Bar().c_str())</code> where
 308 <code>Foo</code> and <code>Bar</code> return C++'s
 309 <code>std::string</code>).
 310
 311 <p>The <code>CHECK_DOUBLE_EQ</code> macro checks the equality of two
 312 floating point values, accepting a small error margin.
 313 <code>CHECK_NEAR</code> accepts a third floating point argument, which
 314 specifies the acceptable error margin.
 315
 316 <h2><A NAME=verbose>Verbose Logging</A></h2>
 317
 318 <p>When you are chasing difficult bugs, thorough log messages are very
 319 useful.  However, you may want to ignore too verbose messages in usual
 320 development.  For such verbose logging, glog provides the
 321 <code>VLOG</code> macro, which allows you to define your own numeric
 322 logging levels.  The <code>--v</code> command line option controls
 323 which verbose messages are logged:
 324
 325 <pre>
 326    VLOG(1) &lt;&lt; "I'm printed when you run the program with --v=1 or higher";
 327    VLOG(2) &lt;&lt; "I'm printed when you run the program with --v=2 or higher";
 328 </pre>
 329
 330 <p>With <code>VLOG</code>, the lower the verbose level, the more
 331 likely messages are to be logged.  For example, if
 332 <code>--v==1</code>, <code>VLOG(1)</code> will log, but
 333 <code>VLOG(2)</code> will not log.  This is opposite of the severity
 334 level, where <code>INFO</code> is 0, and <code>ERROR</code> is 2.
 335 <code>--minloglevel</code> of 1 will log <code>WARNING</code> and
 336 above.  Though you can specify any integers for both <code>VLOG</code>
 337 macro and <code>--v</code> flag, the common values for them are small
 338 positive integers.  For example, if you write <code>VLOG(0)</code>,
 339 you should specify <code>--v=-1</code> or lower to silence it.  This
 340 is less useful since we may not want verbose logs by default in most
 341 cases.  The <code>VLOG</code> macros always log at the
 342 <code>INFO</code> log level (when they log at all).
 343
 344 <p>Verbose logging can be controlled from the command line on a
 345 per-module basis:
 346
 347 <pre>
 348    --vmodule=mapreduce=2,file=1,gfs*=3 --v=0
 349 </pre>
 350
 351 <p>will:
 352
 353 <ul>
 354   <li>a. Print VLOG(2) and lower messages from mapreduce.{h,cc}
 355   <li>b. Print VLOG(1) and lower messages from file.{h,cc}
 356   <li>c. Print VLOG(3) and lower messages from files prefixed with "gfs"
 357   <li>d. Print VLOG(0) and lower messages from elsewhere
 358 </ul>
 359
 360 <p>The wildcarding functionality shown by (c) supports both '*'
 361 (matches 0 or more characters) and '?' (matches any single character)
 362 wildcards.  Please also check the section about <a
 363 href="#flags">command line flags</a>.
 364
 365 <p>There's also <code>VLOG_IS_ON(n)</code> "verbose level" condition
 366 macro.  This macro returns true when the <code>--v</code> is equal or
 367 greater than <code>n</code>.  To be used as
 368
 369 <pre>
 370    if (VLOG_IS_ON(2)) {
 371      // do some logging preparation and logging
 372      // that can't be accomplished with just VLOG(2) &lt;&lt; ...;
 373    }
 374 </pre>
 375
 376 <p>Verbose level condition macros <code>VLOG_IF</code>,
 377 <code>VLOG_EVERY_N</code> and <code>VLOG_IF_EVERY_N</code> behave
 378 analogous to <code>LOG_IF</code>, <code>LOG_EVERY_N</code>,
 379 <code>LOF_IF_EVERY</code>, but accept a numeric verbosity level as
 380 opposed to a severity level.
 381
 382 <pre>
 383    VLOG_IF(1, (size &gt; 1024))
 384       &lt;&lt; "I'm printed when size is more than 1024 and when you run the "
 385          "program with --v=1 or more";
 386    VLOG_EVERY_N(1, 10)
 387       &lt;&lt; "I'm printed every 10th occurrence, and when you run the program "
 388          "with --v=1 or more. Present occurence is " &lt;&lt; COUNTER;
 389    VLOG_IF_EVERY_N(1, (size &gt; 1024), 10)
 390       &lt;&lt; "I'm printed on every 10th occurence of case when size is more "
 391          " than 1024, when you run the program with --v=1 or more. ";
 392          "Present occurence is " &lt;&lt; COUNTER;
 393 </pre>
 394
 395 <h2> <A name="signal">Failure Signal Handler</A> </h2>
 396
 397 <p>
 398 The library provides a convenient signal handler that will dump useful
 399 information when the program crashes on certain signals such as SIGSEGV.
 400 The signal handler can be installed by
 401 google::InstallFailureSignalHandler().  The following is an example of output
 402 from the signal handler.
 403
 404 <pre>
 405 *** Aborted at 1225095260 (unix time) try "date -d @1225095260" if you are using GNU date ***
 406 *** SIGSEGV (@0x0) received by PID 17711 (TID 0x7f893090a6f0) from PID 0; stack trace: ***
 407 PC: @           0x412eb1 TestWaitingLogSink::send()
 408     @     0x7f892fb417d0 (unknown)
 409     @           0x412eb1 TestWaitingLogSink::send()
 410     @     0x7f89304f7f06 google::LogMessage::SendToLog()
 411     @     0x7f89304f35af google::LogMessage::Flush()
 412     @     0x7f89304f3739 google::LogMessage::~LogMessage()
 413     @           0x408cf4 TestLogSinkWaitTillSent()
 414     @           0x4115de main
 415     @     0x7f892f7ef1c4 (unknown)
 416     @           0x4046f9 (unknown)
 417 </pre>
 418
 419 <p>
 420 By default, the signal handler writes the failure dump to the standard
 421 error.  You can customize the destination by InstallFailureWriter().
 422
 423 <h2> <A name="misc">Miscellaneous Notes</A> </h2>
 424
 425 <h3><A NAME=message>Performance of Messages</A></h3>
 426
 427 <p>The conditional logging macros provided by glog (e.g.,
 428 <code>CHECK</code>, <code>LOG_IF</code>, <code>VLOG</code>, ...) are
 429 carefully implemented and don't execute the right hand side
 430 expressions when the conditions are false.  So, the following check
 431 may not sacrifice the performance of your application.
 432
 433 <pre>
 434    CHECK(obj.ok) &lt;&lt; obj.CreatePrettyFormattedStringButVerySlow();
 435 </pre>
 436
 437 <h3><A NAME=failure>User-defined Failure Function</A></h3>
 438
 439 <p><code>FATAL</code> severity level messages or unsatisfied
 440 <code>CHECK</code> condition terminate your program.  You can change
 441 the behavior of the termination by
 442 <code>InstallFailureFunction</code>.
 443
 444 <pre>
 445    void YourFailureFunction() {
 446      // Reports something...
 447      exit(1);
 448    }
 449
 450    int main(int argc, char* argv[]) {
 451      google::InstallFailureFunction(&amp;YourFailureFunction);
 452    }
 453 </pre>
 454
 455 <p>By default, glog tries to dump stacktrace and makes the program
 456 exit with status 1.  The stacktrace is produced only when you run the
 457 program on an architecture for which glog supports stack tracing (as
 458 of September 2008, glog supports stack tracing for x86 and x86_64).
 459
 460 <h3><A NAME=raw>Raw Logging</A></h3>
 461
 462 <p>The header file <code>&lt;glog/raw_logging.h&gt;</code> can be
 463 used for thread-safe logging, which does not allocate any memory or
 464 acquire any locks.  Therefore, the macros defined in this
 465 header file can be used by low-level memory allocation and
 466 synchronization code.
 467 Please check <code>src/glog/raw_logging.h.in</code> for detail.
 468 </p>
 469
 470 <h3><A NAME=plog>Google Style perror()</A></h3>
 471
 472 <p><code>PLOG()</code> and <code>PLOG_IF()</code> and
 473 <code>PCHECK()</code> behave exactly like their <code>LOG*</code> and
 474 <code>CHECK</code> equivalents with the addition that they append a
 475 description of the current state of errno to their output lines.
 476 E.g.
 477
 478 <pre>
 479    PCHECK(write(1, NULL, 2) &gt;= 0) &lt;&lt; "Write NULL failed";
 480 </pre>
 481
 482 <p>This check fails with the following error message.
 483
 484 <pre>
 485    F0825 185142 test.cc:22] Check failed: write(1, NULL, 2) &gt;= 0 Write NULL failed: Bad address [14]
 486 </pre>
 487
 488 <h3><A NAME=syslog>Syslog</A></h3>
 489
 490 <p><code>SYSLOG</code>, <code>SYSLOG_IF</code>, and
 491 <code>SYSLOG_EVERY_N</code> macros are available.
 492 These log to syslog in addition to the normal logs.  Be aware that
 493 logging to syslog can drastically impact performance, especially if
 494 syslog is configured for remote logging!  Make sure you understand the
 495 implications of outputting to syslog before you use these macros. In
 496 general, it's wise to use these macros sparingly.
 497
 498 <h3><A NAME=strip>Strip Logging Messages</A></h3>
 499
 500 <p>Strings used in log messages can increase the size of your binary
 501 and present a privacy concern.  You can therefore instruct glog to
 502 remove all strings which fall below a certain severity level by using
 503 the GOOGLE_STRIP_LOG macro:
 504
 505 <p>If your application has code like this:
 506
 507 <pre>
 508    #define GOOGLE_STRIP_LOG 1    // this must go before the #include!
 509    #include &lt;glog/logging.h&gt;
 510 </pre>
 511
 512 <p>The compiler will remove the log messages whose severities are less
 513 than the specified integer value.  Since
 514 <code>VLOG</code> logs at the severity level <code>INFO</code>
 515 (numeric value <code>0</code>),
 516 setting <code>GOOGLE_STRIP_LOG</code> to 1 or greater removes
 517 all log messages associated with <code>VLOG</code>s as well as
 518 <code>INFO</code> log statements.
 519
 520 <hr>
 521 <address>
 522 Shinichiro Hamaji<br>
 523 Gregor Hohpe<br>
 524 <script type=text/javascript>
 525   var lm = new Date(document.lastModified);
 526   document.write(lm.toDateString());
 527 </script>
 528 </address>
 529
 530 </body>
 531 </html>