From 89bede92e2bf6527fae4945da66a7a0931ec0b32 Mon Sep 17 00:00:00 2001
From: yasicar <yasica.rajesh@freshworks.com>
Date: Sun, 30 Nov 2025 20:09:00 +0530
Subject: [PATCH] docs: add StatefulSet PromQL queries

---
 docs/README.md                         |   7 ++
 docs/queries/statefulset-monitoring.md | 102 +++++++++++++++++++++++++
 2 files changed, 109 insertions(+)
 create mode 100644 docs/queries/statefulset-monitoring.md

diff --git a/docs/README.md b/docs/README.md
index 2caf4d86a..ad68cf054 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -8,6 +8,7 @@ Any contribution to improving this documentation or adding sample usages will be
 
 * [Metrics Stages](#metrics-stages)
 * [Exposed Metrics](#exposed-metrics)
+* [PromQL Queries](#promql-queries)
 * [Join Metrics](#join-metrics)
 * [CLI arguments](#cli-arguments)
 
@@ -71,6 +72,12 @@ See each file for specific documentation about the exposed metrics:
 * [RoleBinding Metrics](metrics/auth/rolebinding-metrics.md)
 * [ServiceAccount Metrics](metrics/auth/serviceaccount-metrics.md)
 
+## PromQL Queries
+
+For practical PromQL query examples and alerting rules:
+
+* [StatefulSet Queries & Alerts](queries/statefulset-monitoring.md)
+
 ## Join Metrics
 
 When an additional, not provided by default label is needed, a [Prometheus matching operator](https://prometheus.io/docs/prometheus/latest/querying/operators/#vector-matching)
diff --git a/docs/queries/statefulset-monitoring.md b/docs/queries/statefulset-monitoring.md
new file mode 100644
index 000000000..4752bb243
--- /dev/null
+++ b/docs/queries/statefulset-monitoring.md
@@ -0,0 +1,102 @@
+# StatefulSet Monitoring Guide
+
+This guide provides monitoring examples for StatefulSets using kube-state-metrics and Prometheus.
+
+## Query Cookbook
+
+### Health & Availability Queries
+
+**Check StatefulSet rollout status:**
+
+```promql
+# Percentage of updated replicas
+(kube_statefulset_status_replicas_updated / kube_statefulset_replicas) * 100
+```
+
+**Monitor unavailable replicas:**
+
+```promql
+# Number of unavailable replicas
+kube_statefulset_replicas - kube_statefulset_status_replicas_available
+```
+
+### Diagnostic & Troubleshooting Queries
+
+**Find StatefulSets with outdated replicas:**
+
+```promql
+# StatefulSets with replicas not yet updated
+kube_statefulset_status_replicas_current != kube_statefulset_status_replicas_updated
+```
+
+**StatefulSets stuck during rollout:**
+
+```promql
+# StatefulSets where observed generation is behind metadata generation
+kube_statefulset_status_observed_generation < kube_statefulset_metadata_generation
+```
+
+**StatefulSets with scaling issues:**
+
+```promql
+# StatefulSets where current replicas don't match desired
+kube_statefulset_status_replicas_current != kube_statefulset_replicas
+```
+
+## Production Alert Rules
+
+### Critical Alerts
+
+**StatefulSet is completely down:**
+
+```yaml
+- alert: StatefulSetDown
+  expr: kube_statefulset_status_replicas_available == 0 and kube_statefulset_replicas > 0
+  for: 5m
+  labels:
+    severity: critical
+  annotations:
+    summary: "StatefulSet {{ $labels.statefulset }} is completely down"
+    description: "StatefulSet {{ $labels.statefulset }} in namespace {{ $labels.namespace }} has no available replicas despite having {{ $labels.replicas }} desired replicas."
+```
+
+**StatefulSet rollout stuck:**
+
+```yaml
+- alert: StatefulSetRolloutStuck
+  expr: kube_statefulset_status_observed_generation < kube_statefulset_metadata_generation
+  for: 15m
+  labels:
+    severity: critical
+  annotations:
+    summary: "StatefulSet {{ $labels.statefulset }} rollout is stuck"
+    description: "StatefulSet {{ $labels.statefulset }} in namespace {{ $labels.namespace }} has been stuck rolling out for more than 15 minutes."
+```
+
+### Warning Alerts
+
+**StatefulSet has unavailable replicas:**
+
+```yaml
+- alert: StatefulSetReplicasUnavailable
+  expr: (kube_statefulset_replicas - kube_statefulset_status_replicas_available) > 0
+  for: 5m
+  labels:
+    severity: warning
+  annotations:
+    summary: "StatefulSet {{ $labels.statefulset }} has unavailable replicas"
+    description: "StatefulSet {{ $labels.statefulset }} in namespace {{ $labels.namespace }} has {{ $value }} unavailable replicas."
+```
+
+**StatefulSet replica count mismatch:**
+
+```yaml
+- alert: StatefulSetReplicasMismatch
+  expr: kube_statefulset_status_replicas_current != kube_statefulset_replicas
+  for: 10m
+  labels:
+    severity: warning
+  annotations:
+    summary: "StatefulSet {{ $labels.statefulset }} replica count mismatch"
+    description: "StatefulSet {{ $labels.statefulset }} in namespace {{ $labels.namespace }} has {{ $labels.status_replicas_current }} current replicas but {{ $labels.replicas }} are desired."
+```
\ No newline at end of file