K8SPSMDB-297 Documented cluster-level logging

 modified:   docs/debug-logs.md

Author: nastena1606

docs/debug-logs.md

@@ -46,7 +46,7 @@ In the following examples we will access containers of the `my-cluster-name-rs0-
 
 ## Changing logs representation
 
-You can also change the representation of logs: either use structured representation, which produces a parsing-friendly JSON, or use traditional console-frienldy logging with specific level. Changing representation of logs is possible by editing the `deploy/operator.yml` file, which sets the following environment variables with self-speaking names and values:
+You can also change the representation of logs: either use structured representation, which produces a parsing-friendly JSON, or use traditional console-friendly logging with specific level. Changing representation of logs is possible by editing the `deploy/operator.yml` file, which sets the following environment variables with self-speaking names and values:
 
 ```yaml
 env:
@@ -57,3 +57,28 @@ env:
     value: INFO
     ...
 ```
+
+## Cluster-level logging
+
+In a distributed Kubernetes environment, it's often difficult to debug issues because logs are tied to the lifecycle of individual Pods and containers. If a Pod fails and restarts, its logs are lost, making it hard to identify the root cause of an issue.
+
+Percona Operator for MongoDB addresses this challenge with **cluster-level logging**, ensuring logs are stored persistently, independent of the Pods. This approach helps ensure that logs are available for review even after a Pod restarts.
+
+The Operator collects logs using [Fluent Bit :octicons-link-external-16:](https://fluentbit.io/) - a lightweight log processor, which supports many output plugins and has broad forwarding capabilities. Fluent Bit runs as a sidecar container within each database Pod. It collects logs from the primary `mongod` container, adds metadata, and stores them in a single file in a dedicated log-specific Persistent Volume Claim (PVC) at `/data/db/logs/`. This allows logs to survive Pod restarts and be accessed for later debugging.
+
+Logs are also streamed to standard output, making them accessible via the `kubectl logs` command for quick troubleshooting:
+
+```{.bash data-prompt="$"}
+$ kubectl logs my-cluster-name-rs0-0 -c logs
+```
+
+Currently, logs are collected only for the `mongod` instance. All other logs are ephemeral, meaning they will not persist after a Pod restart. Logs are stored for 7 days and are rotated afterwards.
+
+### Configure log collector
+
+Cluster-level logging is enabled by default and is controlled with the `logcollector.enabled` key in the `deploy/cr.yaml` Custom Resource manifest.
+
+You can additionally configure Fluent Bit using the `logcollector.configuration` subsection in 
+the `deploy/cr.yaml` Custom Resource manifest. This allows you to define custom filters and output plugins to suit your specific logging and monitoring needs.
+
+When you add a new configuration to the `logcollector.configuration` and this field was previously empty, it triggers a Smart Update. However, if the configuration was not empty, subsequent changes won't trigger an update automatically.