documentatino update

Author: dbarkowsky

docs-md/LOKI_HELM_CHART.md

@@ -35,7 +35,7 @@ deployments/openshift/helm/plg/
 | `loki.storageClassName` | Storage class (empty = cluster default) | `""` |
 | `loki.resources.requests.memory` | Memory request | `256Mi` |
 | `loki.resources.requests.cpu` | CPU request | `500m` |
-| `loki.resources.limits.memory` | Memory limit | `256Mi` |
+| `loki.resources.limits.memory` | Memory limit | `256Mi` (OpenShift override: `2Gi`) |
 | `loki.resources.limits.cpu` | CPU limit | `500m` |
 | `loki.httpPort` | HTTP listen port | `3100` |
 
@@ -71,6 +71,34 @@ To change the retention period, override `loki.retentionDays`:
 helm upgrade plg ./deployments/openshift/helm/plg --set loki.retentionDays=14
 ```
 
+## Ingestion Rate Limits
+
+The OpenShift deployment configures ingestion limits to apply back-pressure before Loki exhausts its memory ceiling:
+
+| Setting | Value | Purpose |
+|---------|-------|---------|
+| `ingestion_rate_mb` | 4 | Sustained ingest rate per tenant (MB/s) |
+| `ingestion_burst_size_mb` | 8 | Burst allowance above the sustained rate |
+| `chunk_idle_period` | 30m | Flush idle chunks to disk after this interval |
+| `chunk_target_size` | 1536000 (~1.5MB) | Flush a chunk to disk once it reaches this size |
+
+Without these limits, Loki accumulates unbounded in-memory chunks when ingestion outpaces disk flushes, eventually reaching the memory ceiling and being OOMKilled. The ingestion limits cause Promtail to receive a `429 Too Many Requests` response and retry, rather than Loki silently growing until it is killed.
+
+## Prometheus Metrics
+
+Loki exposes a `/metrics` endpoint on its HTTP port. The PLG Prometheus instance scrapes it via a dedicated `loki` scrape job configured in `prometheus-configmap.yaml`. Use `{job="loki"}` as the label selector in queries, for example:
+
+```promql
+# Current RSS memory usage
+process_resident_memory_bytes{job="loki"}
+
+# In-memory ingester chunks
+loki_ingester_memory_chunks
+
+# Ingest rate (bytes/sec)
+rate(loki_distributor_bytes_received_total[5m])
+```
+
 ## Deployment
 
 ### OpenShift

docs-md/PLG_DEPLOYMENT_INTEGRATION.md

@@ -74,6 +74,22 @@ The PLG deployment is completely independent of the Kustomize-based application
 - No Kustomize base or overlay files are modified for PLG
 - If PLG deployment fails, the application deployment is unaffected
 
+## Prometheus RBAC
+
+Prometheus uses Kubernetes pod service discovery (`kubernetes_sd_configs`) to scrape `backend-services` and `temporal-worker` pods by IP across replicas. This requires permission to list and watch pods in the namespace.
+
+The chart creates a dedicated `ServiceAccount`, `Role` (pods: `get`/`list`/`watch`), and `RoleBinding` for the Prometheus StatefulSet. These are scoped to the release namespace only. The `default` service account is not used — it has no pod-list permissions on OpenShift.
+
+## ches-adapter and Alertmanager
+
+The ches-adapter Deployment, Service, PodDisruptionBudget, and sidecar ConfigMaps are only rendered when **both** `alertmanager.notificationsEnabled: true` and `alertmanager.notificationChannel: "ches"`. When notifications are disabled (the default), none of these resources are created and no ches-adapter image is required.
+
+Similarly, the `ches-notifications` and `teams-notifications` receivers in the Alertmanager config are only emitted when `notificationsEnabled: true`. This prevents Alertmanager from failing to start due to empty webhook URL validation when notifications are off.
+
+## Grafana Storage
+
+Grafana stores its SQLite database and alert history on a `ReadWriteOnce` PersistentVolumeClaim. The Deployment uses `strategy: Recreate` rather than the default `RollingUpdate`, so the old pod is terminated before the new one starts. This prevents `Multi-Attach` errors caused by two pods competing for the same RWO volume during an upgrade.
+
 ## Accessing Grafana
 
 Grafana is not exposed via an OpenShift Route. Access it via port-forwarding:

docs-md/PROMTAIL_SIDECARS.md

@@ -22,14 +22,16 @@ Each application pod includes a Promtail sidecar container that:
 
 ## Resource Limits
 
-All Promtail sidecars use minimal resource allocations:
+Promtail sidecars on PVC-backed services (`backend-services`, `temporal-worker`) use the following allocations:
 
 | Resource | Request | Limit |
 |----------|---------|-------|
-| Memory | 32Mi | 64Mi |
+| Memory | 64Mi | 128Mi |
 | CPU | 50m | 100m |
 
-These defaults are sized for low-traffic environments. To adjust resource limits, modify the Promtail container resource specifications in the relevant deployment manifests under `deployments/openshift/kustomize/base/`.
+The memory limit is set to 128Mi to prevent OOMKills caused by Loki backpressure. When Loki is under memory pressure it slows ingest responses, causing Promtail to buffer pending log batches in-heap. A 64Mi limit was insufficient in practice and caused CrashLoopBackOff on both `backend-services` and `temporal-worker` pods.
+
+To adjust resource limits, modify the Promtail container resource specifications in the relevant deployment manifests under `deployments/openshift/kustomize/base/`.
 
 ## Configuration