docs: clarify docker-driver config options (backport release-3.6.x) (#21495)

Co-authored-by: J Stickler <julie.stickler@grafana.com>

Author: loki-gh-app[bot]

docs/sources/send-data/docker-driver/_index.md

@@ -79,7 +79,7 @@ docker plugin rm loki
 
 The driver keeps all logs in memory and will drop log entries if Loki is not reachable and if the quantity of `max_retries` has been exceeded. To avoid the dropping of log entries, setting `max_retries` to zero allows unlimited retries; the driver will continue trying forever until Loki is again reachable. Trying forever may have undesired consequences, because the Docker daemon will wait for the Loki driver to process all logs of a container, until the container is removed. Thus, the Docker daemon might wait forever if the container is stuck.
 
-The wait time can be lowered by setting `loki-retries=2`, `loki-max-backoff=800ms`, `loki-timeout=1s` and `keep-file=true`. This way the daemon will be locked only for a short time and the logs will be persisted locally when the Loki client is unable to re-connect.
+The wait time can be lowered by setting `loki-retries=2`, `loki-max-backoff=800ms`, `loki-timeout=1s` and `keep-file=true`. This way the daemon will be locked only for a short time and the JSON log files will be retained on disk when the Loki client is unable to re-connect.
 
 Also you can use non-blocking mode by setting `services.logger.logging.options.mode=non-blocking` in your `docker-compose` file. Non-blocking means that the process of writing logs to Loki will not block the main flow of an application or service if Loki is temporarily unavailable or unable to process log messages. In non-blocking mode, log messages will be buffered and sent to Loki asynchronously, which allows the main thread to continue working without delay. If Loki is unavailable, log messages will be stored in a buffer and sent when Loki becomes available again. However, this setting is useful to prevent blocking the main flow of an application or service due to logging issues, but it can also lead to loss of log messages if the buffer overflows or if Loki is unavailable for a long time.
 

docs/sources/send-data/docker-driver/configuration.md

@@ -40,7 +40,7 @@ The Loki logging driver still uses the json-log driver in combination with sendi
 to keep the `docker logs` command working.
 You can adjust file size and rotation using the respective log option `max-size` and `max-file`. Keep in mind that
 default values for these options are not taken from json-log configuration.
-You can deactivate this behavior by setting the log option `no-file` to true.
+You can disable JSON log file creation by setting the log option `no-file` to `true`, but this also disables `docker logs` for the container.
 {{< /admonition >}}
 
 ## Change the default logging driver
@@ -238,14 +238,24 @@ To specify additional logging driver options, you can use the --log-opt NAME=VAL
 | `loki-tls-server-name`          |    No     |                            | Name used to validate the server certificate.                                                                                                                                                                                                                                                                   |
 | `loki-tls-insecure-skip-verify` |    No     |          `false`*          | Allow to skip tls verification.                                                                                                                                                                                                                                                                                 |
 | `loki-proxy-url`                |    No     |                            | Proxy URL use to connect to Loki.                                                                                                                                                                                                                                                                               |
-| `no-file`                       |    No     |          `false`*          | Default is "false" and log files are created.  Set to "true" to tell driver not to ever create log files on disk. However, this means you won't be able to use `docker logs` on the container anymore. Use this setting if you don't need to use `docker logs` or run with limited disk space.                      |
-| `keep-file`                     |    No     |          `false`*          | Default is "false" and log files are removed once a container is stopped. Set to "true" to tell driver to keep json log files once a container is stopped.                                                                                                                                                 |
+| `no-file`                       |    No     |          `false`*          | When `false` (default), the driver creates a local JSON log file for each container, which enables `docker logs`. Set to `true` to skip creating JSON log files entirely — no disk space is used for logs, but `docker logs` will not work for the container.                                |
+| `keep-file`                     |    No     |          `false`*          | When `false` (default), the JSON log file for a container is deleted when the container stops. Set to `true` to retain the JSON log file after the container stops. Has no effect when `no-file=true`, because no JSON log file is created.                                                                      |
 | `max-size`                      |    No     |             -1             | The maximum size of the log before it is rolled. A positive integer plus a modifier representing the unit of measure (k, m, or g). Defaults to -1 (unlimited). This is used by json-log required to keep the `docker log` command working.                                                                      |
 | `max-file`                      |    No     |             1              | The maximum number of log files that can be present. If rolling the logs creates excess files, the oldest file is removed. Only effective when max-size is also set. A positive integer. Defaults to 1.                                                                                                         |
 | `labels`                        |    No     |                            | Comma-separated list of keys of labels, which should be included in message, if these labels are specified for container.                                                                                                                                                                                       |
 | `env`                           |    No     |                            | Comma-separated list of keys of environment variables to be included in message if they specified for a container.                                                                                                                                                                                              |
 | `env-regex`                     |    No     |                            | A regular expression to match logging-related environment variables. Used for advanced log label options. If there is collision between the label and env keys, the value of the env takes precedence. Both options add additional fields to the labels of a logging message.                                   |
 
+### `no-file` and `keep-file` interactions
+
+The `no-file` and `keep-file` options control whether JSON log files are created and how long they are kept:
+
+| `no-file` | `keep-file` | JSON log file created? | Deleted on container stop? | `docker logs` available? |
+|:---------:|:-----------:|:----------------------:|:--------------------------:|:------------------------:|
+| `false`   | `false`     | Yes                    | Yes                        | Yes                      |
+| `false`   | `true`      | Yes                    | No                         | Yes                      |
+| `true`    | (any)       | No                     | N/A                        | No                       |
+
 ### *note:
 
 Boolean values in the configuration file only accept the following string type: