luo980/glog
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: cleanup (#1041)

Browse Source
This commit is contained in:
Sergiu Deitsch 2024-01-06 15:04:12 +01:00 committed by GitHub
parent 25a349f7ae
commit 2c735b8dfb
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
2 changed files with 164 additions and 96 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

253
README.rst
View File

@ -46,8 +46,8 @@ their usage, please refer to the `user guide <#user-guide>`__.
.. pull-quote::
[!IMPORTANT]
The above example requires further Bazel or CMake setup for
`use in own projects <#usage-in-projects>`__.
The above example requires further `Bazel <#bazel>`__ or
`CMake <#usage-in-projects>`__ setup for use in own projects.
.. contents:: Table of Contents
@ -221,23 +221,63 @@ Severity Levels
~~~~~~~~~~~~~~~
You can specify one of the following severity levels (in increasing
order of severity): ``INFO``, ``WARNING``, ``ERROR``, and ``FATAL``.
order of severity):
1. ``INFO``,
2. ``WARNING``,
3. ``ERROR``, and
4. ``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``.
logged).
.. pull-quote::
[!NOTE]
Messages of a given severity are logged not only to corresponding severity
logfile but also to other logfiles of lower severity. For instance, a message
of severity ``FATAL`` will be logged to 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.
Unless otherwise specified, glog uses the format
::
<tmp>/<program name>.<hostname>.<user name>.log.<severity level>.<date>-<time>.<pid>
for log filenames written to a directory designated as ``<tmp>`` and determined
according to the following rules.
**Windows**
glog uses the
`GetTempPathA <https://learn.microsoft.com/en-us/windows/win32/api/fileapi/nf-fileapi-gettemppatha>`__
API function to retrieve the directory for temporary files with a fallback to
1. ``C:\TMP\``
2. ``C:\TEMP\``
(in the order given.)
**non-Windows**
The directory is determined by referencing the environment variables
1. ``TMPDIR``
2. ``TMP``
if set with a fallback to ``/tmp/``.
The default path to a log file on Linux, for instance, could be
::
/tmp/hello_world.example.com.hamaji.log.INFO.20080709-222411.10474
By default, glog echos ``ERROR`` and ``FATAL`` messages to standard error in
addition to log files.
Setting Flags
~~~~~~~~~~~~~
@ -245,8 +285,8 @@ Setting Flags
Several flags influence glog’s output behavior. If the `Google gflags library
<https://github.com/gflags/gflags>`__ 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 :cmd:`--logtostderr` on,
you can start your application with the following command line:
command line. For example, if you want to activate :cmd:`--logtostderr`, you can
start your application with the following command line:
.. code:: bash
@ -262,10 +302,14 @@ environment variables, prefixing the flag name with ``GLOG_``, e.g.,
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).
Log messages to ``stderr`` instead of logfiles.
.. pull-quote::
[!TIP]
You can set boolean flags to :cpp:`true` by specifying ``1``, :cpp:`true`,
or ``yes``. To set boolean flags to :cpp:`false`, specify ``0``,
``false``, or ``no``. In either case the spelling is case-insensitive.
``stderrthreshold`` (``int``, default=2, which is ``ERROR``)
Copy log messages at or above this level to stderr in addition to
@ -282,20 +326,20 @@ The following flags are most commonly used:
default logging directory.
``v`` (``int``, default=0)
Show all ``VLOG(m)`` messages for ``m`` less or equal the value of
this flag. Overridable by :cmd:`--vmodule`. See `the section about
verbose logging <#verbose-logging>`__ for more detail.
Show all ``VLOG(m)`` messages for ``m`` less or equal the value of this flag.
Overridable by :cmd:`--vmodule`. Refer to `verbose logging <#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
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 :cmd:`--v`.
See also `the section about verbose logging <#verbose-logging>`__.
.cc/.h./-inl.h). ``<log level>`` overrides any value given by :cmd:`--v`.
See also `verbose logging <#verbose-logging>`__ for more details.
There are some other flags defined in logging.cc. Please grep the source
code for ``DEFINE_`` to see a complete list of all flags.
Additional flags are defined in `flags.cc <src/flags.cc>`__. Please see the
source for their complete list.
You can also modify flag values in your program by modifying global
variables ``FLAGS_*`` . Most settings start working immediately after
@ -335,8 +379,12 @@ logging is most useful for informational messages.
LOG_EVERY_N(INFO, 10) << "Got the " << google::COUNTER << "th cookie";
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.
it is executed.
.. pull-quote::
[!NOTE]
The placeholder ``google::COUNTER`` identifies the reccuring repetition.
You can combine conditional and occasional logging with the following
macro.
@ -353,11 +401,11 @@ output to the first n occurrences:
LOG_FIRST_N(INFO, 20) << "Got the " << google::COUNTER << "th cookie";
Outputs log messages for the first 20 times it is executed. Again, the
Outputs log messages for the first 20 times it is executed. The
``google::COUNTER`` identifier indicates which repetition is happening.
Other times, it is desired to only log a message periodically based on a time.
So for example, to log a message every 10ms:
For instance, to log a message every 10ms:
.. code:: cpp
@ -450,21 +498,32 @@ constructor initializer lists.
Something* ptr_;
};
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.
.. pull-quote::
[!WARNING]
Due to the argument forwarding, ``CHECK_NOTNULL`` cannot be used to
simultaneously stream an additional custom message. To provide a custom
message, one can use the macro ``CHECK_EQ`` prior to the failing check.
If you are comparing C strings (:cpp:`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 :cpp:`nullptr` pointers for this macro. They
treat :cpp:`nullptr` and any non-:cpp:`nullptr` string as not equal. Two :cpp:`nullptr`\
s are equal.
both case sensitive and insensitive comparisons - ``CHECK_STREQ``,
``CHECK_STRNE``, ``CHECK_STRCASEEQ``, and ``CHECK_STRCASENE``. The
``CHECK_*CASE*`` macro variants are case-insensitive. You can safely pass
:cpp:`nullptr` pointers to this macro. They treat :cpp:`nullptr` and any
non-:cpp:`nullptr` string as not equal. Two :cpp:`nullptr`\ s are equal.
Note that both arguments may be temporary strings which are destructed
at the end of the current "full expression" (e.g.,
:cpp:`CHECK_STREQ(Foo().c_str(), Bar().c_str())` where ``Foo`` and ``Bar``
return C++’s :cpp:`std::string`).
.. pull-quote::
[!NOTE]
Both arguments may be temporary objects which are destructed at the end of
the current "full expression", such as
.. code:: cpp
CHECK_STREQ(Foo().c_str(), Bar().c_str());
where ``Foo`` and ``Bar`` return :cpp:`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
@ -486,12 +545,19 @@ controls which verbose messages are logged:
With ``VLOG``, the lower the verbose level, the more likely messages are to be
logged. For example, if :cmd:`--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. :cmd:`--minloglevel` of 1 will log ``WARNING`` and above. Though
you can specify any integers for both ``VLOG`` macro and :cmd:`--v` flag, the
common values for them are small positive integers. For example, if you write
``VLOG(0)``, you should specify :cmd:`--v=-1` or lower to silence it. This is
less useful since we may not want verbose logs by default in most cases. The
will not log.
.. pull-quote::
[!CAUTION]
The ``VLOG`` behavior is opposite of the severity level logging, where
``INFO``, ``ERROR``, etc. are defined in increasing order and thus
:cmd:`--minloglevel` of 1 will only log ``WARNING`` and above.
Though you can specify any integers for both ``VLOG`` macro and :cmd:`--v` flag,
the common values for them are small positive integers. For example, if you
write ``VLOG(0)``, you should specify :cmd:`--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
@ -501,20 +567,21 @@ basis:
--vmodule=mapreduce=2,file=1,gfs*=3 --v=0
will:
Specifying these options will specficially:
(a) Print ``VLOG(2)`` and lower messages from mapreduce.{h,cc}
(b) Print ``VLOG(1)`` and lower messages from file.{h,cc}
(c) Print ``VLOG(3)`` and lower messages from files prefixed with "gfs"
(d) Print ``VLOG(0)`` and lower messages from elsewhere
1. Print ``VLOG(2)`` and lower messages from mapreduce.{h,cc}
2. Print ``VLOG(1)`` and lower messages from file.{h,cc}
3. Print ``VLOG(3)`` and lower messages from files prefixed with "gfs"
4. 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 <#setting-flags>`__.
The wildcarding functionality 3. supports both ``*`` (matches 0
or more characters) and ``?`` (matches any single character) wildcards.
Please also refer to `command line flags <#setting-flags>`__ for more
information.
There’s also ``VLOG_IS_ON(n)`` "verbose level" condition macro. This
macro returns true when the :cmd:`--v` is equal or greater than ``n``. To
be used as
There’s also ``VLOG_IS_ON(n)`` "verbose level" condition macro. This macro
returns ``true`` when the :cmd:`--v` is equal to or greater than ``n``. The
macro can be used as follows:
.. code:: cpp
@ -546,22 +613,20 @@ Custom Log Prefix Format
~~~~~~~~~~~~~~~~~~~~~~~~
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.
receiving a user-provided callback that generates such strings.
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:
For example, the following function outputs a prefix that matches glog's default
format. The third parameter ``data`` can be used to access user-supplied data
which unless specified defaults to :cpp:`nullptr`.
.. code:: cpp
/* This function writes a prefix that matches glog's default format.
* (The third parameter can be used to receive user-supplied data, and is
* nullptr by default.)
*/
void CustomPrefix(std::ostream &s, const LogMessageInfo &l, void*) {
void CustomPrefix(std::ostream& s, const LogMessageInfo& l, void* /*data*/) {
s << l.severity[0]
<< setw(4) << 1900 + l.time.year()
<< setw(2) << 1 + l.time.month()
@ -579,11 +644,15 @@ For example:
}
To enable the use of ``CustomPrefix()``, simply give glog a pointer to it
during initialization: ``InitGoogleLogging(argv[0], &CustomPrefix);``.
To enable the use of a custom prefix, use the
Optionally, ``InitGoogleLogging()`` takes a third argument of type ``void*``
to pass on to the callback function.
.. code:: cpp
InitGoogleLogging(argv[0], &CustomPrefix);
overload to pass a pointer to the corresponding :cpp:`CustomPrefix` function during
initialization. :cpp:`InitGoogleLogging()` takes a third optional argument of
type :cpp:`void*` that allows supplying user data to the callback.
Failure Signal Handler
~~~~~~~~~~~~~~~~~~~~~~
@ -641,10 +710,12 @@ by :cpp:`InstallFailureFunction`.
google::InstallFailureFunction(&YourFailureFunction);
}
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).
By default, glog tries to dump the stacktrace and calls :cpp:`std::abort`. The
stacktrace is generated only when running the application on a system supported
by glog. Currently, glog supports x86, x86_64, PowerPC architectures,
``libunwind``, and the Debug Help Library (``dbghelp``) on Windows for
extracting the stack trace.
Raw Logging
~~~~~~~~~~~
@ -652,8 +723,8 @@ Raw Logging
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
<src/glog/raw_logging.h.in>`__ for detail.
synchronization code. Please check
`src/glog/raw_logging.h <src/glog/raw_logging.h>`__ for detail.
Google Style ``perror()``
~~~~~~~~~~~~~~~~~~~~~~~~~
@ -771,9 +842,9 @@ anymore for functions defined in ``glog/logging.h`` .
If you don’t need ``ERROR`` defined by ``windows.h``, there are a couple
of more workarounds which sometimes don’t work:
- ``#define WIN32_LEAN_AND_MEAN`` or ``NOGDI`` **before** you
``#include windows.h``.
- ``#undef ERROR`` **after** you ``#include windows.h`` .
- :cpp:`#define WIN32_LEAN_AND_MEAN` or :cpp:`NOGDI` **before**
:cpp:`#include <windows.h>`.
- :cpp:`#undef ERROR` **after** :cpp:`#include <windows.h>`.
See `this
issue <http://code.google.com/p/google-glog/issues/detail?id=33>`__ for
@ -815,19 +886,19 @@ Using :cmd:`-static` is rare, though, so unless you know this will affect you it
probably won’t.
If you cannot or do not wish to install libunwind, you can still try to
use two kinds of stack-unwinder: 1. glibc built-in stack-unwinder and 2.
frame pointer based stack-unwinder.
use two kinds of stack-unwinder:
1. As we already mentioned, glibc’s unwinder has a deadlock issue.
However, if you don’t use :cpp:`InstallFailureSignalHandler()` or you
don’t worry about the rare possibilities of deadlocks, you can use
this stack-unwinder. If you specify no options and ``libunwind``
isn’t detected on your system, the configure script chooses this
unwinder by default.
glibc built-in stack-unwinder
As we already mentioned, glibc’s unwinder has a deadlock issue. However, if
you don’t use :cpp:`InstallFailureSignalHandler()` or you don’t worry about
the rare possibilities of deadlocks, you can use this stack-unwinder. If you
specify no options and ``libunwind`` isn’t detected on your system, the
configure script chooses this unwinder by default.
2. The frame pointer based stack unwinder requires that your
application, the glog library, and system libraries like libc, all be
compiled with a frame pointer. This is *not* the default for x86-64.
frame pointer based stack-unwinder
The frame pointer based stack unwinder requires that your application, the
glog library, and system libraries like libc, all be compiled with a frame
pointer. This is *not* the default for x86-64.
How to Contribute

7
src/logging.cc
View File

@ -2300,12 +2300,10 @@ static void GetTempDirectories(vector<string>* list) {
// C:/Documents & Settings/whomever/TEMP (or whatever GetTempPath() is)
// C:/TMP/
// C:/TEMP/
// C:/WINDOWS/ or C:/WINNT/
// .
char tmp[MAX_PATH];
if (GetTempPathA(MAX_PATH, tmp)) list->push_back(tmp);
list->push_back("C:\\tmp\\");
list->push_back("C:\\temp\\");
list->push_back("C:\\TMP\\");
list->push_back("C:\\TEMP\\");
#else
// Directories, in order of preference. If we find a dir that
// exists, we stop adding other less-preferred dirs
@ -2337,7 +2335,6 @@ static void GetTempDirectories(vector<string>* list) {
return;
}
}
#endif
}