From 5f0ca0fdeaea758cf595c823564cec0ea20ff30f Mon Sep 17 00:00:00 2001
From: Ishaan Jaffer <ishaanjaffer0324@gmail.com>
Date: Thu, 19 Feb 2026 12:39:38 -0800
Subject: [PATCH] docs: add x-litellm-overhead-duration-ms to latency
 troubleshooting guide

---
 .../docs/troubleshoot/latency_overhead.md      | 18 +++++++++++++++---
 1 file changed, 15 insertions(+), 3 deletions(-)

diff --git a/docs/my-website/docs/troubleshoot/latency_overhead.md b/docs/my-website/docs/troubleshoot/latency_overhead.md
index 1dea11c0d57..cfb2cb43a7e 100644
--- a/docs/my-website/docs/troubleshoot/latency_overhead.md
+++ b/docs/my-website/docs/troubleshoot/latency_overhead.md
@@ -4,12 +4,24 @@ Use this guide when you see unexpected latency overhead between LiteLLM proxy an
 
 ## Quick Checklist
 
-1. **Is DEBUG logging enabled?** This is the #1 cause of latency with large payloads.
-2. **Are you sending large base64 payloads?** (images, PDFs) — see [Large Payload Overhead](#large-payload-overhead).
-3. **Enable detailed timing headers** to pinpoint where time is spent.
+1. **Collect the `x-litellm-overhead-duration-ms` response header** — this tells you LiteLLM's total overhead on every request. Start here.
+2. **Is DEBUG logging enabled?** This is the #1 cause of latency with large payloads.
+3. **Are you sending large base64 payloads?** (images, PDFs) — see [Large Payload Overhead](#large-payload-overhead).
+4. **Enable detailed timing headers** to pinpoint where time is spent.
 
 ## Diagnostic Headers
 
+### `x-litellm-overhead-duration-ms` (always on)
+
+Every response from LiteLLM includes this header. It shows the total latency overhead in milliseconds added by LiteLLM proxy (i.e. total response time minus the LLM API call time). Collect this on every request to understand your baseline overhead.
+
+```bash
+curl -s -D - http://localhost:4000/v1/chat/completions \
+  -H "Authorization: Bearer sk-..." \
+  -d '{"model": "gpt-4o", "messages": [{"role": "user", "content": "hi"}]}' \
+  2>&1 | grep x-litellm-overhead-duration-ms
+```
+
 ### `x-litellm-callback-duration-ms` (always on)
 
 Shows time spent building callback/logging payloads (ms). If this is high (>100ms), your payloads may be too large for efficient logging.