From d49e70089741de90a351812327421e99f7d61d45 Mon Sep 17 00:00:00 2001 From: Sergiu Deitsch Date: Wed, 12 Jun 2024 23:54:11 +0200 Subject: [PATCH] docs: move flags out of logging --- docs/flags.md | 93 +++++++++++++++++++++++++++++++++++++++++++ docs/logging.md | 102 ++---------------------------------------------- mkdocs.yml | 1 + 3 files changed, 97 insertions(+), 99 deletions(-) create mode 100644 docs/flags.md diff --git a/docs/flags.md b/docs/flags.md new file mode 100644 index 000000000..6f1db335c --- /dev/null +++ b/docs/flags.md @@ -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 `=`. `` 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). + `` 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"; + ``` diff --git a/docs/logging.md b/docs/logging.md index a844f4ee3..c6b13c31a 100644 --- a/docs/logging.md +++ b/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 `=`. `` - 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). `` 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 diff --git a/mkdocs.yml b/mkdocs.yml index fd9a11449..6c0e550c8 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -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