blob: 0edaa66e76902983304b16a2d3c9eabcd4b4075b [file] [log] [blame]
Austin Schuh906616c2019-01-21 20:25:11 -08001<!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
43logging. This library provides logging APIs based on C++-style
44streams and various helper macros.
45You can log a message by simply streaming things to LOG(&lt;a
46particular <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
61tasks. You can log messages by severity level, control logging
62behavior from the command line, log based on conditionals, abort the
63program when expected conditions are not met, introduce your own
64verbose logging levels, and more. This document describes the
65functionality supported by glog. Please note that this document
66doesn't describe all features in this library, but the most useful
67ones. If you want to find less common features, please check
68header files under <code>src/glog</code> directory.
69
70<h2> <A NAME=severity>Severity Level</A> </h2>
71
72<p>
73You can specify one of the following severity levels (in
74increasing order of severity): <code>INFO</code>, <code>WARNING</code>,
75<code>ERROR</code>, and <code>FATAL</code>.
76Logging a <code>FATAL</code> message terminates the program (after the
77message is logged).
78Note that messages of a given severity are logged not only in the
79logfile for that severity, but also in all logfiles of lower severity.
80E.g., a message of severity <code>FATAL</code> will be logged to the
81logfiles of severity <code>FATAL</code>, <code>ERROR</code>,
82<code>WARNING</code>, and <code>INFO</code>.
83
84<p>
85The <code>DFATAL</code> severity logs a <code>FATAL</code> error in
86debug mode (i.e., there is no <code>NDEBUG</code> macro defined), but
87avoids halting the program in production by automatically reducing the
88severity 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").
93By default, glog copies the log messages of severity level
94<code>ERROR</code> or <code>FATAL</code> to standard error (stderr)
95in addition to log files.
96
97<h2><A NAME=flags>Setting Flags</A></h2>
98
99<p>Several flags influence glog's output behavior.
100If the <a href="https://github.com/gflags/gflags">Google
101gflags library</a> is installed on your machine, the
102<code>configure</code> script (see the INSTALL file in the package for
103detail of this script) will automatically detect and use it,
104allowing you to pass flags on the command line. For example, if you
105want to turn the flag <code>--logtostderr</code> on, you can start
106your application with the following command line:
107
108<pre>
109 ./your_application --logtostderr=1
110</pre>
111
112If the Google gflags library isn't installed, you set flags via
113environment variables, prefixing the flag name with "GLOG_", e.g.
114
115<pre>
116 GLOG_logtostderr=1 ./your_application
117</pre>
118
119<!-- TODO(hamaji): Fill the version number
120<p>By glog version 0.x.x, you can use GLOG_* environment variables
121even if you have gflags. If both an environment variable and a flag
122are specified, the value specified by a flag wins. E.g., if GLOG_v=0
123and --v=1, the verbosity will be 1, not 0.
124-->
125
126<p>The following flags are most commonly used:
127
128<dl>
129<dt><code>logtostderr</code> (<code>bool</code>, default=<code>false</code>)
130<dd>Log messages to stderr instead of logfiles.<br>
131Note: you can set binary flags to <code>true</code> by specifying
132<code>1</code>, <code>true</code>, or <code>yes</code> (case
133insensitive).
134Also, you can set binary flags to <code>false</code> by specifying
135<code>0</code>, <code>false</code>, or <code>no</code> (again, case
136insensitive).
137<dt><code>stderrthreshold</code> (<code>int</code>, default=2, which
138is <code>ERROR</code>)
139<dd>Copy log messages at or above this level to stderr in
140addition to logfiles. The numbers of severity levels
141<code>INFO</code>, <code>WARNING</code>, <code>ERROR</code>, and
142<code>FATAL</code> are 0, 1, 2, and 3, respectively.
143<dt><code>minloglevel</code> (<code>int</code>, default=0, which
144is <code>INFO</code>)
145<dd>Log messages at or above this level. Again, the numbers of
146severity levels <code>INFO</code>, <code>WARNING</code>,
147<code>ERROR</code>, and <code>FATAL</code> are 0, 1, 2, and 3,
148respectively.
149<dt><code>log_dir</code> (<code>string</code>, default="")
150<dd>If specified, logfiles are written into this directory instead
151of the default logging directory.
152<dt><code>v</code> (<code>int</code>, default=0)
153<dd>Show all <code>VLOG(m)</code> messages for <code>m</code> less or
154equal the value of this flag. Overridable by --vmodule.
155See <a href="#verbose">the section about verbose logging</a> for more
156detail.
157<dt><code>vmodule</code> (<code>string</code>, default="")
158<dd>Per-module verbose level. The argument has to contain a
159comma-separated list of &lt;module name&gt;=&lt;log level&gt;.
160&lt;module name&gt;
161is a glob pattern (e.g., <code>gfs*</code> for all modules whose name
162starts with "gfs"), matched against the filename base
163(that is, name ignoring .cc/.h./-inl.h).
164&lt;log level&gt; overrides any value given by --v.
165See also <a href="#verbose">the section about verbose logging</a>.
166</dl>
167
168<p>There are some other flags defined in logging.cc. Please grep the
169source code for "DEFINE_" to see a complete list of all flags.
170
171<p>You can also modify flag values in your program by modifying global
172variables <code>FLAGS_*</code> . Most settings start working
173immediately after you update <code>FLAGS_*</code> . The exceptions are
174the flags related to destination files. For example, you might want to
175set <code>FLAGS_log_dir</code> before
176calling <code>google::InitGoogleLogging</code> . Here is an example:
177
178<pre>
179 LOG(INFO) << "file";
180 // Most flags work immediately after updating values.
181 FLAGS_logtostderr = 1;
182 LOG(INFO) << "stderr";
183 FLAGS_logtostderr = 0;
184 // This won't change the log destination. If you want to set this
185 // value, you should do this before google::InitGoogleLogging .
186 FLAGS_log_dir = "/some/log/directory";
187 LOG(INFO) << "the same file";
188</pre>
189
190<h2><A NAME=conditional>Conditional / Occasional Logging</A></h2>
191
192<p>Sometimes, you may only want to log a message under certain
193conditions. You can use the following macros to perform conditional
194logging:
195
196<pre>
197 LOG_IF(INFO, num_cookies &gt; 10) &lt;&lt; "Got lots of cookies";
198</pre>
199
200The "Got lots of cookies" message is logged only when the variable
201<code>num_cookies</code> exceeds 10.
202
203If a line of code is executed many times, it may be useful to only log
204a message at certain intervals. This kind of logging is most useful
205for informational messages.
206
207<pre>
208 LOG_EVERY_N(INFO, 10) &lt;&lt; "Got the " &lt;&lt; google::COUNTER &lt;&lt; "th cookie";
209</pre>
210
211<p>The above line outputs a log messages on the 1st, 11th,
21221st, ... times it is executed. Note that the special
213<code>google::COUNTER</code> value is used to identify which repetition is
214happening.
215
216<p>You can combine conditional and occasional logging with the
217following macro.
218
219<pre>
220 LOG_IF_EVERY_N(INFO, (size &gt; 1024), 10) &lt;&lt; "Got the " &lt;&lt; google::COUNTER
221 &lt;&lt; "th big cookie";
222</pre>
223
224<p>Instead of outputting a message every nth time, you can also limit
225the output to the first n occurrences:
226
227<pre>
228 LOG_FIRST_N(INFO, 20) &lt;&lt; "Got the " &lt;&lt; google::COUNTER &lt;&lt; "th cookie";
229</pre>
230
231<p>Outputs log messages for the first 20 times it is executed. Again,
232the <code>google::COUNTER</code> identifier indicates which repetition is
233happening.
234
235<h2><A NAME=debug>Debug Mode Support</A></h2>
236
237<p>Special "debug mode" logging macros only have an effect in debug
238mode and are compiled away to nothing for non-debug mode
239compiles. Use these macros to avoid slowing down your production
240application due to excessive logging.
241
242<pre>
243 DLOG(INFO) &lt;&lt; "Found cookies";
244
245 DLOG_IF(INFO, num_cookies &gt; 10) &lt;&lt; "Got lots of cookies";
246
247 DLOG_EVERY_N(INFO, 10) &lt;&lt; "Got the " &lt;&lt; google::COUNTER &lt;&lt; "th cookie";
248</pre>
249
250<h2><A NAME=check>CHECK Macros</A></h2>
251
252<p>It is a good practice to check expected conditions in your program
253frequently to detect errors as early as possible. The
254<code>CHECK</code> macro provides the ability to abort the application
255when a condition is not met, similar to the <code>assert</code> macro
256defined in the standard C library.
257
258<p><code>CHECK</code> aborts the application if a condition is not
259true. Unlike <code>assert</code>, it is *not* controlled by
260<code>NDEBUG</code>, so the check will be executed regardless of
261compilation mode. Therefore, <code>fp-&gt;Write(x)</code> in the
262following example is always executed:
263
264<pre>
265 CHECK(fp-&gt;Write(x) == 4) &lt;&lt; "Write failed!";
266</pre>
267
268<p>There are various helper macros for
269equality/inequality checks - <code>CHECK_EQ</code>,
270<code>CHECK_NE</code>, <code>CHECK_LE</code>, <code>CHECK_LT</code>,
271<code>CHECK_GE</code>, and <code>CHECK_GT</code>.
272They compare two values, and log a
273<code>FATAL</code> message including the two values when the result is
274not as expected. The values must have <code>operator&lt;&lt;(ostream,
275...)</code> defined.
276
277<p>You may append to the error message like so:
278
279<pre>
280 CHECK_NE(1, 2) &lt;&lt; ": The world must be ending!";
281</pre>
282
283<p>We are very careful to ensure that each argument is evaluated exactly
284once, and that anything which is legal to pass as a function argument is
285legal here. In particular, the arguments may be temporary expressions
286which will end up being destroyed at the end of the apparent statement,
287for example:
288
289<pre>
290 CHECK_EQ(string("abc")[1], 'b');
291</pre>
292
293<p>The compiler reports an error if one of the arguments is a
294pointer and the other is NULL. To work around this, simply static_cast
295NULL to the type of the desired pointer.
296
297<pre>
298 CHECK_EQ(some_ptr, static_cast&lt;SomeType*&gt;(NULL));
299</pre>
300
301<p>Better yet, use the CHECK_NOTNULL macro:
302
303<pre>
304 CHECK_NOTNULL(some_ptr);
305 some_ptr-&gt;DoSomething();
306</pre>
307
308<p>Since this macro returns the given pointer, this is very useful in
309constructor initializer lists.
310
311<pre>
312 struct S {
313 S(Something* ptr) : ptr_(CHECK_NOTNULL(ptr)) {}
314 Something* ptr_;
315 };
316</pre>
317
318<p>Note that you cannot use this macro as a C++ stream due to this
319feature. Please use <code>CHECK_EQ</code> described above to log a
320custom message before aborting the application.
321
322<p>If you are comparing C strings (char *), a handy set of macros
323performs case sensitive as well as case insensitive comparisons -
324<code>CHECK_STREQ</code>, <code>CHECK_STRNE</code>,
325<code>CHECK_STRCASEEQ</code>, and <code>CHECK_STRCASENE</code>. The
326CASE versions are case-insensitive. You can safely pass <code>NULL</code>
327pointers for this macro. They treat <code>NULL</code> and any
328non-<code>NULL</code> string as not equal. Two <code>NULL</code>s are
329equal.
330
331<p>Note that both arguments may be temporary strings which are
332destructed at the end of the current "full expression"
333(e.g., <code>CHECK_STREQ(Foo().c_str(), Bar().c_str())</code> where
334<code>Foo</code> and <code>Bar</code> return C++'s
335<code>std::string</code>).
336
337<p>The <code>CHECK_DOUBLE_EQ</code> macro checks the equality of two
338floating point values, accepting a small error margin.
339<code>CHECK_NEAR</code> accepts a third floating point argument, which
340specifies the acceptable error margin.
341
342<h2><A NAME=verbose>Verbose Logging</A></h2>
343
344<p>When you are chasing difficult bugs, thorough log messages are very
345useful. However, you may want to ignore too verbose messages in usual
346development. For such verbose logging, glog provides the
347<code>VLOG</code> macro, which allows you to define your own numeric
348logging levels. The <code>--v</code> command line option controls
349which verbose messages are logged:
350
351<pre>
352 VLOG(1) &lt;&lt; "I'm printed when you run the program with --v=1 or higher";
353 VLOG(2) &lt;&lt; "I'm printed when you run the program with --v=2 or higher";
354</pre>
355
356<p>With <code>VLOG</code>, the lower the verbose level, the more
357likely messages are to be logged. For example, if
358<code>--v==1</code>, <code>VLOG(1)</code> will log, but
359<code>VLOG(2)</code> will not log. This is opposite of the severity
360level, where <code>INFO</code> is 0, and <code>ERROR</code> is 2.
361<code>--minloglevel</code> of 1 will log <code>WARNING</code> and
362above. Though you can specify any integers for both <code>VLOG</code>
363macro and <code>--v</code> flag, the common values for them are small
364positive integers. For example, if you write <code>VLOG(0)</code>,
365you should specify <code>--v=-1</code> or lower to silence it. This
366is less useful since we may not want verbose logs by default in most
367cases. The <code>VLOG</code> macros always log at the
368<code>INFO</code> log level (when they log at all).
369
370<p>Verbose logging can be controlled from the command line on a
371per-module basis:
372
373<pre>
374 --vmodule=mapreduce=2,file=1,gfs*=3 --v=0
375</pre>
376
377<p>will:
378
379<ul>
380 <li>a. Print VLOG(2) and lower messages from mapreduce.{h,cc}
381 <li>b. Print VLOG(1) and lower messages from file.{h,cc}
382 <li>c. Print VLOG(3) and lower messages from files prefixed with "gfs"
383 <li>d. Print VLOG(0) and lower messages from elsewhere
384</ul>
385
386<p>The wildcarding functionality shown by (c) supports both '*'
387(matches 0 or more characters) and '?' (matches any single character)
388wildcards. Please also check the section about <a
389href="#flags">command line flags</a>.
390
391<p>There's also <code>VLOG_IS_ON(n)</code> "verbose level" condition
392macro. This macro returns true when the <code>--v</code> is equal or
393greater than <code>n</code>. To be used as
394
395<pre>
396 if (VLOG_IS_ON(2)) {
397 // do some logging preparation and logging
398 // that can't be accomplished with just VLOG(2) &lt;&lt; ...;
399 }
400</pre>
401
402<p>Verbose level condition macros <code>VLOG_IF</code>,
403<code>VLOG_EVERY_N</code> and <code>VLOG_IF_EVERY_N</code> behave
404analogous to <code>LOG_IF</code>, <code>LOG_EVERY_N</code>,
405<code>LOF_IF_EVERY</code>, but accept a numeric verbosity level as
406opposed to a severity level.
407
408<pre>
409 VLOG_IF(1, (size &gt; 1024))
410 &lt;&lt; "I'm printed when size is more than 1024 and when you run the "
411 "program with --v=1 or more";
412 VLOG_EVERY_N(1, 10)
413 &lt;&lt; "I'm printed every 10th occurrence, and when you run the program "
414 "with --v=1 or more. Present occurence is " &lt;&lt; google::COUNTER;
415 VLOG_IF_EVERY_N(1, (size &gt; 1024), 10)
416 &lt;&lt; "I'm printed on every 10th occurence of case when size is more "
417 " than 1024, when you run the program with --v=1 or more. ";
418 "Present occurence is " &lt;&lt; google::COUNTER;
419</pre>
420
421<h2> <A name="signal">Failure Signal Handler</A> </h2>
422
423<p>
424The library provides a convenient signal handler that will dump useful
425information when the program crashes on certain signals such as SIGSEGV.
426The signal handler can be installed by
427google::InstallFailureSignalHandler(). The following is an example of output
428from the signal handler.
429
430<pre>
431*** Aborted at 1225095260 (unix time) try "date -d @1225095260" if you are using GNU date ***
432*** SIGSEGV (@0x0) received by PID 17711 (TID 0x7f893090a6f0) from PID 0; stack trace: ***
433PC: @ 0x412eb1 TestWaitingLogSink::send()
434 @ 0x7f892fb417d0 (unknown)
435 @ 0x412eb1 TestWaitingLogSink::send()
436 @ 0x7f89304f7f06 google::LogMessage::SendToLog()
437 @ 0x7f89304f35af google::LogMessage::Flush()
438 @ 0x7f89304f3739 google::LogMessage::~LogMessage()
439 @ 0x408cf4 TestLogSinkWaitTillSent()
440 @ 0x4115de main
441 @ 0x7f892f7ef1c4 (unknown)
442 @ 0x4046f9 (unknown)
443</pre>
444
445<p>
446By default, the signal handler writes the failure dump to the standard
447error. You can customize the destination by InstallFailureWriter().
448
449<h2> <A name="misc">Miscellaneous Notes</A> </h2>
450
451<h3><A NAME=message>Performance of Messages</A></h3>
452
453<p>The conditional logging macros provided by glog (e.g.,
454<code>CHECK</code>, <code>LOG_IF</code>, <code>VLOG</code>, ...) are
455carefully implemented and don't execute the right hand side
456expressions when the conditions are false. So, the following check
457may not sacrifice the performance of your application.
458
459<pre>
460 CHECK(obj.ok) &lt;&lt; obj.CreatePrettyFormattedStringButVerySlow();
461</pre>
462
463<h3><A NAME=failure>User-defined Failure Function</A></h3>
464
465<p><code>FATAL</code> severity level messages or unsatisfied
466<code>CHECK</code> condition terminate your program. You can change
467the behavior of the termination by
468<code>InstallFailureFunction</code>.
469
470<pre>
471 void YourFailureFunction() {
472 // Reports something...
473 exit(1);
474 }
475
476 int main(int argc, char* argv[]) {
477 google::InstallFailureFunction(&amp;YourFailureFunction);
478 }
479</pre>
480
481<p>By default, glog tries to dump stacktrace and makes the program
482exit with status 1. The stacktrace is produced only when you run the
483program on an architecture for which glog supports stack tracing (as
484of September 2008, glog supports stack tracing for x86 and x86_64).
485
486<h3><A NAME=raw>Raw Logging</A></h3>
487
488<p>The header file <code>&lt;glog/raw_logging.h&gt;</code> can be
489used for thread-safe logging, which does not allocate any memory or
490acquire any locks. Therefore, the macros defined in this
491header file can be used by low-level memory allocation and
492synchronization code.
493Please check <code>src/glog/raw_logging.h.in</code> for detail.
494</p>
495
496<h3><A NAME=plog>Google Style perror()</A></h3>
497
498<p><code>PLOG()</code> and <code>PLOG_IF()</code> and
499<code>PCHECK()</code> behave exactly like their <code>LOG*</code> and
500<code>CHECK</code> equivalents with the addition that they append a
501description of the current state of errno to their output lines.
502E.g.
503
504<pre>
505 PCHECK(write(1, NULL, 2) &gt;= 0) &lt;&lt; "Write NULL failed";
506</pre>
507
508<p>This check fails with the following error message.
509
510<pre>
511 F0825 185142 test.cc:22] Check failed: write(1, NULL, 2) &gt;= 0 Write NULL failed: Bad address [14]
512</pre>
513
514<h3><A NAME=syslog>Syslog</A></h3>
515
516<p><code>SYSLOG</code>, <code>SYSLOG_IF</code>, and
517<code>SYSLOG_EVERY_N</code> macros are available.
518These log to syslog in addition to the normal logs. Be aware that
519logging to syslog can drastically impact performance, especially if
520syslog is configured for remote logging! Make sure you understand the
521implications of outputting to syslog before you use these macros. In
522general, it's wise to use these macros sparingly.
523
524<h3><A NAME=strip>Strip Logging Messages</A></h3>
525
526<p>Strings used in log messages can increase the size of your binary
527and present a privacy concern. You can therefore instruct glog to
528remove all strings which fall below a certain severity level by using
529the GOOGLE_STRIP_LOG macro:
530
531<p>If your application has code like this:
532
533<pre>
534 #define GOOGLE_STRIP_LOG 1 // this must go before the #include!
535 #include &lt;glog/logging.h&gt;
536</pre>
537
538<p>The compiler will remove the log messages whose severities are less
539than the specified integer value. Since
540<code>VLOG</code> logs at the severity level <code>INFO</code>
541(numeric value <code>0</code>),
542setting <code>GOOGLE_STRIP_LOG</code> to 1 or greater removes
543all log messages associated with <code>VLOG</code>s as well as
544<code>INFO</code> log statements.
545
546<h3><A NAME=windows>Notes for Windows users</A></h3>
547
548<p>Google glog defines a severity level <code>ERROR</code>, which is
549also defined in <code>windows.h</code> . You can make glog not define
550<code>INFO</code>, <code>WARNING</code>, <code>ERROR</code>,
551and <code>FATAL</code> by defining
552<code>GLOG_NO_ABBREVIATED_SEVERITIES</code> before
553including <code>glog/logging.h</code> . Even with this macro, you can
554still use the iostream like logging facilities:
555
556<pre>
557 #define GLOG_NO_ABBREVIATED_SEVERITIES
558 #include &lt;windows.h&gt;
559 #include &lt;glog/logging.h&gt;
560
561 // ...
562
563 LOG(ERROR) &lt;&lt; "This should work";
564 LOG_IF(ERROR, x &gt; y) &lt;&lt; "This should be also OK";
565</pre>
566
567<p>
568However, you cannot
569use <code>INFO</code>, <code>WARNING</code>, <code>ERROR</code>,
570and <code>FATAL</code> anymore for functions defined
571in <code>glog/logging.h</code> .
572
573<pre>
574 #define GLOG_NO_ABBREVIATED_SEVERITIES
575 #include &lt;windows.h&gt;
576 #include &lt;glog/logging.h&gt;
577
578 // ...
579
580 // This won't work.
581 // google::FlushLogFiles(google::ERROR);
582
583 // Use this instead.
584 google::FlushLogFiles(google::GLOG_ERROR);
585</pre>
586
587<p>
588If you don't need <code>ERROR</code> defined
589by <code>windows.h</code>, there are a couple of more workarounds
590which sometimes don't work:
591
592<ul>
593 <li>#define <code>WIN32_LEAN_AND_MEAN</code> or <code>NOGDI</code>
594 <strong>before</strong> you #include <code>windows.h</code> .
595 <li>#undef <code>ERROR</code> <strong>after</strong> you #include
596 <code>windows.h</code> .
597</ul>
598
599<p>See <a href="http://code.google.com/p/google-glog/issues/detail?id=33">
600this issue</a> for more detail.
601
602<hr>
603<address>
604Shinichiro Hamaji<br>
605Gregor Hohpe<br>
606<script type=text/javascript>
607 var lm = new Date(document.lastModified);
608 document.write(lm.toDateString());
609</script>
610</address>
611
612</body>
613</html>