PageRenderTime 29ms CodeModel.GetById 10ms app.highlight 12ms RepoModel.GetById 1ms app.codeStats 0ms

/thirdparty/breakpad/third_party/glog/doc/glog.html

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