From f442b57848ea63621c0de6d535a08939df583cd9 Mon Sep 17 00:00:00 2001
From: Alexsander Hamir <alexsanderhamirgomesbaptista@gmail.com>
Date: Wed, 14 Jan 2026 15:28:20 -0800
Subject: [PATCH] docs: Add structured issue reporting guides for CPU and
 memory issues (#19117)

---
 .../docs/troubleshoot/cpu_issues.md           | 31 ++++++++++++++++
 .../docs/troubleshoot/memory_issues.md        | 37 +++++++++++++++++++
 docs/my-website/sidebars.js                   |  8 ++++
 3 files changed, 76 insertions(+)
 create mode 100644 docs/my-website/docs/troubleshoot/cpu_issues.md
 create mode 100644 docs/my-website/docs/troubleshoot/memory_issues.md

diff --git a/docs/my-website/docs/troubleshoot/cpu_issues.md b/docs/my-website/docs/troubleshoot/cpu_issues.md
new file mode 100644
index 00000000000..8a9a8abe929
--- /dev/null
+++ b/docs/my-website/docs/troubleshoot/cpu_issues.md
@@ -0,0 +1,31 @@
+# CPU Issue Classification & Reproduction
+
+## 1. Classify the CPU Issue
+
+Select the options that best describes the CPU behavior observed.
+
+- [ ] CPU scales with traffic (RPS-driven)
+- [ ] CPU increases without a traffic increase
+- [ ] CPU increases after a LiteLLM upgrade
+
+## 2. Can you reproduce the issue?
+
+Before escalating, verify whether the CPU issue can be reproduced in a test environment that mirrors your production setup.  
+
+If reproducible, provide **detailed reproduction steps** along with any relevant requests or configuration used.  
+For guidance on the type of information we're looking for, see the [LiteLLM Troubleshooting Guide](../troubleshoot).
+
+## 3. Issue Cannot Be Reproduced
+
+If the CPU issue cannot be reproduced in a test environment that mirrors your production setup, please provide:
+
+1. **Information from Section 1 and 2**  
+   - CPU classification (Section 1)  
+   - Reproduction attempts and environment details (Section 2)  
+
+2. **Additional context** to help investigate:  
+   - **Workload:** A realistic sample of requests processed before and during the spike, including any recent configuration changes.  
+   - **Metrics:** CPU usage, P50/P99 latency, memory usage. Please include **screenshots** of the metrics whenever possible.  
+   - **Logs / Alerts:** Any relevant logs or alerts captured **before and during the spike**.
+
+> Providing this information allows the team to analyze patterns, correlate spikes with traffic or configuration, and attempt to reproduce the issue internally. Without it, our engineers won't have enough information to look into the problem.
diff --git a/docs/my-website/docs/troubleshoot/memory_issues.md b/docs/my-website/docs/troubleshoot/memory_issues.md
new file mode 100644
index 00000000000..1a3eb53f1c8
--- /dev/null
+++ b/docs/my-website/docs/troubleshoot/memory_issues.md
@@ -0,0 +1,37 @@
+# Memory Issue Classification & Reproduction
+
+## 1. Classify the Memory Issue
+
+Select the option(s) that best describe the memory behavior observed:
+
+- [ ] Memory scales with traffic (RPS-driven)  
+- [ ] Memory increases without a traffic increase  
+- [ ] Memory increases after a LiteLLM upgrade  
+- [ ] Memory leak (memory continuously grows over time)  
+- [ ] Out of Memory (OOM) events or pod restarts
+
+---
+
+## 2. Can you reproduce the issue?
+
+Before escalating, verify whether the memory or OOM issue can be reproduced in a test environment that mirrors your production deployment.  
+
+If reproducible, provide **detailed reproduction steps** along with any relevant requests, workloads, or configuration used.  
+For guidance on the type of information we’re looking for, see the [LiteLLM Troubleshooting Guide](../troubleshoot).
+
+---
+
+## 3. Issue Cannot Be Reproduced
+
+If the memory or OOM issue cannot be reproduced in a test environment that mirrors production, please provide:
+
+1. **Information from Sections 1 and 2**  
+   - Memory/issue classification (Section 1)  
+   - Reproduction attempts and environment details (Section 2)  
+
+2. **Additional context** to help investigate:  
+   - **Workload:** A realistic sample of requests processed before and during the spike, including any recent configuration changes.  
+   - **Metrics:** Memory usage, CPU usage, P50/P99 latency, and any pod restarts or OOM events. Please include **screenshots** of the metrics whenever possible.  
+   - **Logs / Alerts:** Any relevant logs or alerts captured **before and during the spike**, including OOM errors or stack traces if available.
+
+> Providing this information allows the team to analyze patterns, correlate memory spikes or OOMs with traffic or configuration, and attempt to reproduce the issue internally. Without it, our engineers will not have enough information to investigate the problem.
diff --git a/docs/my-website/sidebars.js b/docs/my-website/sidebars.js
index 033aef06003..8aa313d6fc5 100644
--- a/docs/my-website/sidebars.js
+++ b/docs/my-website/sidebars.js
@@ -971,6 +971,14 @@ const sidebars = {
       ],
     },
     "troubleshoot",
+    {
+      type: "category",
+      label: "Issue Reporting",
+      items: [
+        "troubleshoot/cpu_issues",
+        "troubleshoot/memory_issues",
+      ],
+    },
   ],
 };