Debugging

---
name: qdrant-monitoring-debugging
description: Use when a Qdrant deployment misbehaves — slow queries, memory pressure, stuck optimizers, unhealthy shards, or failed replicas. Covers the metrics and telemetry endpoints to inspect and how to read them.
source: "https://github.com/qdrant/skills"
attribution: "qdrant/skills by Qdrant"
---

> **Attribution:** Sourced from [qdrant/skills](https://github.com/qdrant/skills) by [Qdrant](https://qdrant.tech).

# How to Debug Qdrant with Metrics

First check optimizer status. Most production issues trace back to active optimizations competing for resources. If optimizer is clean, check memory, then request metrics.


## Optimizer Stuck or Too Slow

Use when: optimizer running for hours, not finishing, or showing errors.

- Use `/collections/{collection_name}/optimizations` endpoint (v1.17+) to check status [Optimization monitoring](https://search.qdrant.tech/md/documentation/operations/optimizer/?s=optimization-monitoring)
- Query with optional detail flags: `?with=queued,completed,idle_segments`
- Returns: queued optimizations count, active optimizer type, involved segments, progress tracking
- Web UI has an Optimizations tab with timeline view and per-task duration metrics [Web UI](https://search.qdrant.tech/md/documentation/operations/optimizer/?s=web-ui)
- If `optimizer_status` shows an error in collection info, check logs for disk full or corrupted segments
- Large merges and HNSW rebuilds legitimately take hours on big datasets. Check progress before assuming it's stuck.


## Memory Seems Too High

Use when: memory exceeds expectations, node crashes with OOM, or memory keeps growing.

- Process memory metrics available via `/metrics` (RSS, allocated bytes, page faults)
- Qdrant uses two types of RAM: resident memory (data structures, quantized vectors) and OS page cache (cached disk reads). Page cache filling available RAM is normal. [Memory article](https://qdrant.tech/articles/memory-consumption/)
- If resident memory (RSSAnon) exceeds 80% of total RAM, investigate
- Check `/telemetry` for per-collection breakdown of point counts and vector configurations
- Estimate expected memory: `num_vectors * dimensions * 4 bytes * 1.5` for vectors, plus payload and index overhead [Capacity planning](https://search.qdrant.tech/md/documentation/operations/capacity-planning/)
- Common causes of unexpected growth: quantized vectors with `always_ram=true`, too many payload indexes, large `max_segment_size` during optimization


## Queries Are Slow

Use when: queries slower than expected and you need to identify the cause.

- Track `rest_responses_avg_duration_seconds` and `rest_responses_max_duration_seconds` per endpoint
- Use histogram metric `rest_responses_duration_seconds` (v1.8+) for percentile analysis in Grafana
- Equivalent gRPC metrics with `grpc_responses_` prefix
- Check optimizer status first. Active optimizations compete for CPU and I/O, degrading search latency.
- Check segment count via collection info. Too many unmerged segments after bulk upload causes slower search.
- Compare filtered vs unfiltered query times. Large gap means missing payload index. [Payload index](https://search.qdrant.tech/md/documentation/manage-data/indexing/?s=payload-index)


## What NOT to Do

- Ignore optimizer status when debugging slow queries (most common root cause)
- Assume memory leak when page cache fills RAM (normal OS behavior)
- Make config changes while optimizer is running (causes cascading re-optimizations)
- Blame Qdrant before checking if bulk upload just finished (unmerged segments)