docs: move flags out of logging
This commit is contained in:
Sergiu Deitsch
parent
df683bbc81
commit
d49e700897
93
docs/flags.md
Normal file
93
docs/flags.md
Normal 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
102
docs/logging.md
@ -1,8 +1,8 @@
|
||||
# Logging
|
||||
|
||||
glog defines a series of macros that simplify many common logging tasks. You can
|
||||
log messages by [severity level](#severity-levels), [control
|
||||
logging](#adjusting-output) behavior from the command line, log based on
|
||||
log messages by [severity level](#severity-levels), [control logging](flags.md)
|
||||
behavior from the command line, log based on
|
||||
[conditionals](#conditional-occasional-logging), abort the program when
|
||||
[expected conditions](#runtime-checks) are not met, introduce your [own logging
|
||||
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
|
||||
|
||||
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
|
||||
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
|
||||
returns `#!cpp true` when the `--v` is equal to or greater than `n`. The macro can be
|
||||
|
||||
@ -110,6 +110,7 @@ nav:
|
||||
- Installation using Package Managers: packages.md
|
||||
- User Guide:
|
||||
- Logging: logging.md
|
||||
- Adjusting Output: flags.md
|
||||
- Custom Sinks: sinks.md
|
||||
- Failure Handler: failures.md
|
||||
- Log Removal: log_cleaner.md
|
||||
|
||||
Loading…
Reference in New Issue
Block a user