DOC-15118: Document how to change log config

src/current/v25.4/configure-logs.md

@@ -30,6 +30,8 @@ To configure the logging behavior of a `cockroach` command, include one of these
 
 To disable logging, set `--log-dir` to a blank directory (`--log-dir=`) instead of using one of the other logging flags. Do not use `--log-dir=""`; this creates a new directory named `""` and stores log files in that directory.
 
+To apply changes to an existing node's logging configuration, restart the node with the updated `--log` flag or point it to the updated `--log-config-file`. CockroachDB reads these settings during startup. Before restarting, use [`cockroach debug check-log-config`](#cockroach-debug-check-log-config) to verify the effective configuration produced by your changes.
+
 {{site.data.alerts.callout_success}}
 All [`cockroach` commands]({% link {{ page.version.version }}/cockroach-commands.md %}) support logging and can be configured with `--log` or `--log-config-file`. However, note that most messages related to cluster operation are generated by [`cockroach start`]({% link {{ page.version.version }}/cockroach-start.md %}) or [`cockroach start-single-node`]({% link {{ page.version.version }}/cockroach-start-single-node.md %}). Other commands generate messages related to their own execution, which are mainly useful when troubleshooting the behaviors of those commands.
 {{site.data.alerts.end}}
@@ -77,10 +79,47 @@ capture-stray-errors: ... # parameters for the stray error capture system
 
 Providing a logging configuration is optional. Any fields included in the YAML payload will override the same fields in the [default logging configuration](#default-logging-configuration).
 
-{{site.data.alerts.callout_success}}
-You can view the default settings by running `cockroach debug check-log-config`, which returns the YAML definitions and a URL to a visualization of the default logging configuration.
+{{site.data.alerts.callout_danger}}
+When you provide a minimal logging configuration for `file-groups`, CockroachDB replaces the entire default `file-groups` structure rather than merging only the specified fields. As a result, all logging channels flow into the `default` file sink, which can lead to noisy logs and rapid log rotation. Although users may expect partial YAML overrides to merge with the default logging configuration, this behavior is not supported. To avoid misconfiguration, validate logging settings using the [`cockroach debug check-log-config`](#cockroach-debug-check-log-config) command.
 {{site.data.alerts.end}}
 
+For example, the following minimal logging configuration attempts to set `max-group-size` for `default` file sink to `1000MiB`:
+
+~~~ yaml
+sinks:
+  file-groups:
+    default:
+      max-group-size: 1000MiB
+      channels:
+        INFO: [DEV, OPS, HEALTH, STORAGE, SESSIONS, SQL_SCHEMA, USER_ADMIN, PRIVILEGES, SENSITIVE_ACCESS, SQL_EXEC, SQL_INTERNAL_PERF, TELEMETRY, KV_DISTRIBUTION]
+~~~
+
+Compared to the [default logging configuration](#default-logging-configuration), the actual effective configuration updates `max-group-size` for `default` file sink, adds `all` channels to the `default` file sink, and removes all other `file-groups`:
+
+~~~ yaml
+file-defaults: ...
+fluent-defaults: ...
+http-defaults: ...
+otlp-defaults: ...
+sinks:
+  file-groups:
+    default:
+      channels: {INFO: all}
+      ...
+      max-group-size: 1000MiB
+      ...
+  stderr: ...
+capture-stray-errors: ...
+~~~
+
+{% include {{ page.version.version }}/log-channel-note.md %}
+
+### `cockroach debug check-log-config`
+
+The `cockroach debug check-log-config` command helps you validate logging settings before starting or restarting nodes. It returns the YAML definitions and a URL to a visualization of the default logging configuration.
+
+When you run it without logging flags, it prints the [default log configuration](#default-logging-configuration). If you pass a logging flag (for example, `--log=...` or `--log-config-file=...`), the output shows the configuration after your YAML payload is applied, so you can confirm the final sink, channel, and formatting behaviors.
+
 ## Configure log sinks
 
 Log *sinks* route events from specified [logging channels]({% link {{ page.version.version }}/logging-overview.md %}#logging-channels) to destinations outside CockroachDB. These destinations include:
@@ -414,7 +453,7 @@ channels: 'all except [ops, health]'
 When setting up a logging configuration, it's simplest to define shared parameters in `file-defaults`, `fluent-defaults`, `http-defaults`, and `otlp-defaults` and override specific values as needed in [`file-groups`](#output-to-files), [`fluent-servers`](#output-to-fluentd-compatible-network-collectors), [`http-servers`](#output-to-http-network-collectors), [`otlp-servers`](#output-to-otlp-compatible-network-collectors) and [`stderr`](#output-to-stderr). For a complete example, see the [default configuration](#default-logging-configuration).
 
 {{site.data.alerts.callout_success}}
-You can view your current settings by running `cockroach debug check-log-config`, which returns the YAML definitions and a URL to a visualization of the current logging configuration.
+You can verify your current settings by running [`cockroach debug check-log-config`](#cockroach-debug-check-log-config) with the applicable logging flag. The command returns the YAML definitions and a URL to a visualization of the logging configuration.
 {{site.data.alerts.end}}
 
 This section describes some recommended defaults.