common/options: document log_to_stderr's conditional default value

The default value of `log_to_stderr` varies depending on whether Ceph
runs as a daemon or a library. Previously, this was only documented via
the `default` property, which led to confusion when debugging client
applications.

For example, when debugging a CephFS client, setting `debug <subsystem> = 5`
in the configuration file doesn't produce visible debug logs as expected.
This occurs because `common_preinit()` overrides `log_to_stderr` to `false`
when Ceph runs as a library, preventing logs from appearing on stderr.

This commit adds clarification to the `long_desc` field to document this
conditional behavior and help users understand why debug output may not
appear in client scenarios.

Signed-off-by: Kefu Chai <k.chai@proxmox.com>

diff --git a/src/common/options/global.yaml.in b/src/common/options/global.yaml.in
index 222dc89076e294c9a0efbf91f7869e5a78ebc514..f3ebf1b1a8e2e8c6c24fa28af5545eea29ea5cd2 100644 (file)
--- a/src/common/options/global.yaml.in
+++ b/src/common/options/global.yaml.in
@@ -522,6 +522,9 @@ options:
   type: bool
   level: basic
   desc: send log lines to stderr
+  long_desc: When Ceph runs as a library (e.g., librados), the default value set to false because
+    stderr may not be writable by the application. For daemons, the daemon_default of false is used
+    instead.
   fmt_desc: Determines if logging messages should appear in ``stderr``.
   default: true
   daemon_default: false