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

docs: move flags out of logging

Browse Source
This commit is contained in:
Sergiu Deitsch 2024-06-12 23:54:11 +02:00
parent df683bbc81
commit d49e700897
No known key found for this signature in database
3 changed files with 97 additions and 99 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

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/0.7.x/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";
```

102
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/0.7.x/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

1
mkdocs.yml
View File

@ -110,6 +110,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