From fb386b2f6163ae37fff72bda0c820f54e9b65baa Mon Sep 17 00:00:00 2001
From: timvisee <tim@visee.me>
Date: Thu, 7 Sep 2023 17:29:12 +0200
Subject: [PATCH] Describe how to debug yellow collection with optimizer log in
 telemetry

---
 .../documentation/guides/common-errors.md     | 77 +++++++++++++++++++
 1 file changed, 77 insertions(+)

diff --git a/qdrant-landing/content/documentation/guides/common-errors.md b/qdrant-landing/content/documentation/guides/common-errors.md
index 32467b0d2..96360190b 100644
--- a/qdrant-landing/content/documentation/guides/common-errors.md
+++ b/qdrant-landing/content/documentation/guides/common-errors.md
@@ -31,6 +31,83 @@ ulimit -n 10000
 
 Please note, the command should be executed before you run Qdrant server.
 
+## Collection status is always yellow
+
+Each collection has a [status color](../../guides/collections#collection-info).
+It may happen that the status of a collection always stays yellow.
+
+A yellow status means that the collection is optimizing. It is very likely that
+your collection is still optimizing. This process can take a very long time
+depending on how many points you insert and what hardware is used.
+
+You can use [telemetry](../telemetry) data to get an insight on what the
+optimizer is currently doing. The telemetry data contains a lot of optimizer
+events that describe its behavior. This log may be helpful to detect weird
+optimizer behavior such as an optimization never finishing or an infinite loop
+of optimizations. If you're experiencing problems, please always check your
+Qdrant logs to see if any errors are printed.
+
+The optimization log in telemetry output may look like this (with all other
+parts trimmed), at
+`result.collections.collections[].shards[].local.optimizations.log`. This lists
+four optimizer events for indexing and merging. Three optimizations are `done`,
+the fourth one is still `optimizing`:
+
+```http
+GET /telemetry?details_level=2
+
+{
+  "result": {
+    "collections": {
+      "collections": [{
+        "id": "my_collection",
+        "shards": [{
+          "id": 0,
+          "local": {
+            "optimizations": {
+              "log": [
+                {
+                  "name": "indexing",
+                  "segment_ids": [12596352011983712000, 683094100406536000],
+                  "status": "optimizing",
+                  "start_at": "2023-09-07T15:14:05.873193961Z",
+                  "end_at": null
+                },
+                {
+                  "name": "indexing",
+                  "segment_ids": [17554372345781762000, 4001657189184169500],
+                  "status": "done",
+                  "start_at": "2023-09-07T15:13:55.249372496Z",
+                  "end_at": "2023-09-07T15:14:05.873186801Z"
+                },
+                {
+                  "name": "merge",
+                  "segment_ids": [4650893139495580000, 6657980491957345000, 14402712336633991000],
+                  "status": "done",
+                  "start_at": "2023-09-07T15:13:48.831599648Z",
+                  "end_at": "2023-09-07T15:13:55.249370166Z"
+                },
+                {
+                  "name": "indexing",
+                  "segment_ids": [9867739984940812000],
+                  "status": "done",
+                  "start_at": "2023-09-07T15:13:46.616151260Z",
+                  "end_at": "2023-09-07T15:13:48.825460417Z"
+                }
+              ]
+            }
+          }
+        }]
+      }]
+    }
+  }
+}
+```
+
+The `status` of an event will be `error` if the optimization failed. The log
+shows the latest events first. It will keep at most 16 successful events. Errors
+and cancellations are always kept.
+
 ## Qdrant stuck/frozen, extract stack trace
 
 *Available as of v1.5.0*