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

Merge branch '0.7.x'

Browse Source
This commit is contained in:
Sergiu Deitsch 2024-06-13 00:01:17 +02:00
commit 0c10a02229
No known key found for this signature in database
6 changed files with 142 additions and 117 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

40
docs/failures.md
View File

@ -21,15 +21,33 @@ from the signal handler.
@ 0x7f892f7ef1c4 (unknown) @ 0x7f892f7ef1c4 (unknown)
@ 0x4046f9 (unknown) @ 0x4046f9 (unknown)
By default, the signal handler writes the failure dump to the standard
error. You can customize the destination by ## Customizing Handler Output
`#!cpp InstallFailureWriter()`.
By default, the signal handler writes the failure dump to the standard error.
However, it is possible to customize the destination by installing a callback
using the `#!cpp google::InstallFailureWriter()` function. The function expects
a pointer to a function with the following signature:
``` cpp
void YourFailureWriter(const char* message/* (1)! */, std::size_t length/* (2)! */);
```
1. The pointer references the start of the failure message.
!!! danger
The string is **not null-terminated**.
2. The message length in characters.
!!! warning "Possible overflow errors"
Users should not expect the `message` string to be null-terminated.
## User-defined Failure Function ## User-defined Failure Function
`FATAL` severity level messages or unsatisfied `CHECK` condition `FATAL` severity level messages or unsatisfied `CHECK` condition
terminate your program. You can change the behavior of the termination terminate your program. You can change the behavior of the termination
by `InstallFailureFunction`. by `google::InstallFailureFunction`.
``` cpp ``` cpp
void YourFailureFunction() { void YourFailureFunction() {
@ -43,7 +61,13 @@ int main(int argc, char* argv[]) {
``` ```
By default, glog tries to dump the stacktrace and calls `#!cpp std::abort`. The 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 stacktrace is generated only when running the application on a system
by glog. Currently, glog supports x86, x86_64, PowerPC architectures, supported[^1] by glog.
`libunwind`, and the Debug Help Library (`dbghelp`) on Windows for extracting
the stack trace. [^1]: To extract the stack trace, glog currently supports the following targets:
* x86, x86_64,
* PowerPC architectures,
* `libunwind`,
* and the Debug Help Library (`dbghelp`) on Windows.

93
docs/flags.md Normal file
View File

@ -0,0 +1,93 @@
# Adjusting Output
Several flags influence glog's output behavior.
## Using Command-line Parameters and Environment Variables
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.
!!! example "Activate `--logtostderr` in an application from the command line"
A binary `you_application` that uses glog can be started using
``` bash
./your_application --logtostderr=1
```
to log to `stderr` instead of writing the output to a log file.
!!! tip
You can set boolean flags to `true` by specifying `1`, `true`, or `yes`. To
set boolean flags to `false`, specify `0`, `false`, or `no`. In either case
the spelling is case-insensitive.
If the Google gflags library isn't installed, you set flags via
environment variables, prefixing the flag name with `GLOG_`, e.g.,
!!! example "Activate `logtostderr` without gflags"
``` bash
GLOG_logtostderr=1 ./your_application
```
The following flags are most commonly used:
`logtostderr` (`bool`, default=`false`)
: Log messages to `stderr` instead of logfiles.
`stderrthreshold` (`int`, default=2, which is `ERROR`)
: Copy log messages at or above this level to `stderr` in addition to
logfiles. The numbers of severity levels `INFO`, `WARNING`, `ERROR`,
and `FATAL` are 0, 1, 2, and 3, respectively.
`minloglevel` (`int`, default=0, which is `INFO`)
: Log messages at or above this level. Again, the numbers of severity
levels `INFO`, `WARNING`, `ERROR`, and `FATAL` are 0, 1, 2, and 3,
respectively.
`log_dir` (`string`, default="")
: If specified, logfiles are written into this directory instead of
the default logging directory.
`v` (`int`, default=0)
: Show all `#!cpp VLOG(m)` messages for `m` less or equal the value of this
flag. Overridable by `#!bash --vmodule`. Refer to [verbose
logging](logging.md#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
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 `--v`. See also [verbose
logging](logging.md#verbose-logging) for more details.
Additional flags are defined in
[flags.cc](https://github.com/google/glog/blob/master/src/flags.cc). Please see
the source for their complete list.
## Modifying Flags Programmatically
You can also modify flag values in your program by modifying global variables
`FLAGS_*`. Most settings start working immediately after you update `FLAGS_*`.
The exceptions are the flags related to destination files. For instance, you
might want to set `FLAGS_log_dir` before calling `google::InitGoogleLogging`.
!!! example "Setting `log_dir` at runtime"
``` cpp
LOG(INFO) << "file";
// Most flags work immediately after updating values.
FLAGS_logtostderr = 1;
LOG(INFO) << "stderr";
FLAGS_logtostderr = 0;
// This won’t change the log destination. If you want to set this
// value, you should do this before google::InitGoogleLogging .
FLAGS_log_dir = "/some/log/directory";
LOG(INFO) << "the same file";
```

10
docs/index.md
View File

@ -13,14 +13,14 @@ You can log a message by simply streaming things to `LOG`(<a particular
#include <glog/logging.h> #include <glog/logging.h>
int main(int argc, char* argv[]) { int main(int argc, char* argv[]) {
// Initialize Google’s logging library. google::InitGoogleLogging(argv[0]); // (1)!
google::InitGoogleLogging(argv[0]); LOG(INFO) << "Found " << num_cookies << " cookies"; // (2)!
// ...
LOG(INFO) << "Found " << num_cookies << " cookies";
} }
``` ```
1. Initialize the Google Logging Library
2. Log a message with informational severity
The library can be installed using various [package managers](packages.md) or The library can be installed using various [package managers](packages.md) or
compiled [from source](build.md). For a detailed overview of glog features and compiled [from source](build.md). For a detailed overview of glog features and
their usage, please refer to the [user guide](logging.md). their usage, please refer to the [user guide](logging.md).

108
docs/logging.md
View File

@ -1,8 +1,8 @@
# Logging # Logging
glog defines a series of macros that simplify many common logging tasks. You can glog defines a series of macros that simplify many common logging tasks. You can
log messages by [severity level](#severity-levels), [control log messages by [severity level](#severity-levels), [control logging](flags.md)
logging](#adjusting-output) behavior from the command line, log based on behavior from the command line, log based on
[conditionals](#conditional-occasional-logging), abort the program when [conditionals](#conditional-occasional-logging), abort the program when
[expected conditions](#runtime-checks) are not met, introduce your [own logging [expected conditions](#runtime-checks) are not met, introduce your [own logging
levels](#verbose-logging), [customize the prefix](#format-customization) levels](#verbose-logging), [customize the prefix](#format-customization)
@ -146,102 +146,6 @@ of type `#!cpp void*` that allows supplying user data to the callback.
``` ```
## Adjusting Output
Several flags influence glog's output behavior.
### Using Command-line Parameters and Environment Variables
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.
!!! example "Activate `--logtostderr` in an application from the command line"
A binary `you_application` that uses glog can be started using
``` bash
./your_application --logtostderr=1
```
to log to `stderr` instead of writing the output to a log file.
!!! tip
You can set boolean flags to `true` by specifying `1`, `true`, or `yes`. To
set boolean flags to `false`, specify `0`, `false`, or `no`. In either case
the spelling is case-insensitive.
If the Google gflags library isn't installed, you set flags via
environment variables, prefixing the flag name with `GLOG_`, e.g.,
!!! example "Activate `logtostderr` without gflags"
``` bash
GLOG_logtostderr=1 ./your_application
```
The following flags are most commonly used:
`logtostderr` (`bool`, default=`false`)
: Log messages to `stderr` instead of logfiles.
`stderrthreshold` (`int`, default=2, which is `ERROR`)
: Copy log messages at or above this level to `stderr` in addition to
logfiles. The numbers of severity levels `INFO`, `WARNING`, `ERROR`,
and `FATAL` are 0, 1, 2, and 3, respectively.
`minloglevel` (`int`, default=0, which is `INFO`)
: Log messages at or above this level. Again, the numbers of severity
levels `INFO`, `WARNING`, `ERROR`, and `FATAL` are 0, 1, 2, and 3,
respectively.
`log_dir` (`string`, default="")
: If specified, logfiles are written into this directory instead of
the default logging directory.
`v` (`int`, default=0)
: Show all `#!cpp VLOG(m)` messages for `m` less or equal the value of this
flag. Overridable by `#!bash --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 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
`--v`. See also [verbose logging](#verbose-logging) for
more details.
Additional flags are defined in
[flags.cc](https://github.com/google/glog/blob/master/src/flags.cc). Please see
the source for their complete list.
### Modifying Flags Programmatically
You can also modify flag values in your program by modifying global variables
`FLAGS_*`. Most settings start working immediately after you update `FLAGS_*`.
The exceptions are the flags related to destination files. For instance, you
might want to set `FLAGS_log_dir` before calling `google::InitGoogleLogging`.
!!! example "Setting `log_dir` at runtime"
``` cpp
LOG(INFO) << "file";
// Most flags work immediately after updating values.
FLAGS_logtostderr = 1;
LOG(INFO) << "stderr";
FLAGS_logtostderr = 0;
// This won’t change the log destination. If you want to set this
// value, you should do this before google::InitGoogleLogging .
FLAGS_log_dir = "/some/log/directory";
LOG(INFO) << "the same file";
```
## Conditional / Occasional Logging ## Conditional / Occasional Logging
Sometimes, you may only want to log a message under certain conditions. Sometimes, you may only want to log a message under certain conditions.
@ -341,7 +245,7 @@ Specifying these options will specifically:
The wildcarding functionality 3. supports both `*` (matches 0 or more The wildcarding functionality 3. supports both `*` (matches 0 or more
characters) and `?` (matches any single character) wildcards. Please also refer characters) and `?` (matches any single character) wildcards. Please also refer
to [command line flags](#adjusting-output) for more information. to [command line flags](flags.md) for more information.
There's also `#!cpp VLOG_IS_ON(n)` "verbose level" condition macro. This macro There's also `#!cpp VLOG_IS_ON(n)` "verbose level" condition macro. This macro
returns `#!cpp true` when the `--v` is equal to or greater than `n`. The macro can be returns `#!cpp true` when the `--v` is equal to or greater than `n`. The macro can be
@ -349,11 +253,13 @@ used as follows:
``` cpp ``` cpp
if (VLOG_IS_ON(2)) { if (VLOG_IS_ON(2)) {
// do some logging preparation and logging // (1)
// that can’t be accomplished with just VLOG(2) << ...;
} }
``` ```
1. Here we can perform some logging preparation and logging that can’t be
accomplished with just `#!cpp VLOG(2) << "message ...";`
Verbose level condition macros `VLOG_IF`, `VLOG_EVERY_N` and `VLOG_IF_EVERY_N` Verbose level condition macros `VLOG_IF`, `VLOG_EVERY_N` and `VLOG_IF_EVERY_N`
behave analogous to `LOG_IF`, `LOG_EVERY_N`, `LOG_IF_EVERY_N`, but accept a behave analogous to `LOG_IF`, `LOG_EVERY_N`, `LOG_IF_EVERY_N`, but accept a
numeric verbosity level as opposed to a severity level. numeric verbosity level as opposed to a severity level.

6
docs/windows.md
View File

@ -34,11 +34,11 @@ google::FlushLogFiles(google::GLOG_ERROR);
``` ```
If you don't need `ERROR` defined by `windows.h`, there are a couple of more If you don't need `ERROR` defined by `windows.h`, there are a couple of more
workarounds which sometimes don't work: workarounds which sometimes don't work[^1]:
- `#!cpp #define WIN32_LEAN_AND_MEAN` or `NOGDI` **before** - `#!cpp #define WIN32_LEAN_AND_MEAN` or `NOGDI` **before**
`#!cpp #include <windows.h>`. `#!cpp #include <windows.h>`.
- `#!cpp #undef ERROR` **after** `#!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 [^1]: For more information refer to [this
more detail. issue](http://code.google.com/p/google-glog/issues/detail?id=33).

2
mkdocs.yml
View File

@ -9,6 +9,7 @@ markdown_extensions:
- admonition - admonition
- attr_list - attr_list
- def_list - def_list
- footnotes
- md_in_html - md_in_html
- pymdownx.details - pymdownx.details
- pymdownx.highlight: - pymdownx.highlight:
@ -110,6 +111,7 @@ nav:
- Installation using Package Managers: packages.md - Installation using Package Managers: packages.md
- User Guide: - User Guide:
- Logging: logging.md - Logging: logging.md
- Adjusting Output: flags.md
- Custom Sinks: sinks.md - Custom Sinks: sinks.md
- Failure Handler: failures.md - Failure Handler: failures.md
- Log Removal: log_cleaner.md - Log Removal: log_cleaner.md