From 9d336166d24323341d78cd9cb6b71e2039192e91 Mon Sep 17 00:00:00 2001
From: Alexsander Hamir <alexsanderhamirgomesbaptista@gmail.com>
Date: Wed, 14 Jan 2026 15:23:04 -0800
Subject: [PATCH] Add memory issue classification and reproduction guide to
 Issue Reporting section

---
 .../docs/troubleshoot/memory_issues.md        | 37 +++++++++++++++++++
 docs/my-website/sidebars.js                   |  1 +
 2 files changed, 38 insertions(+)
 create mode 100644 docs/my-website/docs/troubleshoot/memory_issues.md

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 a016d040ab2..8aa313d6fc5 100644
--- a/docs/my-website/sidebars.js
+++ b/docs/my-website/sidebars.js
@@ -976,6 +976,7 @@ const sidebars = {
       label: "Issue Reporting",
       items: [
         "troubleshoot/cpu_issues",
+        "troubleshoot/memory_issues",
       ],
     },
   ],