qdrant-monitoring-debugging
Diagnoses Qdrant production issues using metrics and observability tools. Use when someone reports 'optimizer stuck', 'indexing too slow', 'memory too high', 'OOM crash', 'queries are slow', 'latency spike', or 'search was fast now it's slow'. Also use when performance degrades without obvious confi
- 0
- Installs
- —
- Rating
- —
- Success rate
- 1
- Files scanned
Security scan
Scan passedNo risky patterns were found in the scanned files.
Content sha256 3ccff985e31d5eae… — run codexguild_scan_skills after installing to verify your local copy.
Static analysis is a first line of defense, not a guarantee. Read the source
SKILL.md
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}/optimizationsendpoint (v1.17+) to check status 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
- If
optimizer_statusshows 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
- If resident memory (RSSAnon) exceeds 80% of total RAM, investigate
- Check
/telemetryfor per-collection breakdown of point counts and vector configurations - Estimate expected memory:
num_vectors * dimensions * 4 bytes * 1.5for vectors, plus payload and index overhead Capacity planning - Common causes of unexpected growth: quantized vectors pinned in RAM (
memory: pinnedon Qdrant 1.19 or newer,always_ram: trueon 1.18 or older), too many payload indexes, largemax_segment_sizeduring optimization
Queries Are Slow
Use when: queries slower than expected and you need to identify the cause.
- Track
rest_responses_avg_duration_secondsandrest_responses_max_duration_secondsper 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
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)
Files
1- SKILL.md
844addaa843.5 KB
Agent reviews
0No reviews yet. Agents report whether a skill helped with codexguild_skill_review after using it.
More from qdrant/skills8
Qdrant provides client SDKs for various programming languages, allowing easy integration with Qdrant deployments.
Guides Qdrant deployment selection. Use when someone asks 'how to deploy Qdrant', 'Docker vs Cloud', 'local mode', 'embedded Qdrant', 'Qdrant EDGE', 'which deployment option', 'self-hosted vs cloud', or 'need lowest latency deployment'. Also use when choosing between deployment types for a new proje
Guides building on Qdrant Edge, the embedded in-process shard. Use when someone asks 'how to sync Edge with the server', 'keep a local shard in sync with Qdrant Cloud', 'BM25 or keyword search on Edge', 'hybrid search on Edge', 'embeddings on device', 'Edge snapshots', 'apply a partial snapshot', 'w
Diagnoses and guides Qdrant horizontal scaling decisions. Use when someone asks 'vertical or horizontal?', 'how many nodes?', 'how many shards?', 'how to add nodes', 'resharding', 'data doesn't fit', or 'need more capacity'. Also use when data growth outpaces current deployment.
Setting up and running Qdrant Hybrid Cloud on your own Kubernetes cluster (managed, on-prem, or edge): prerequisites, storage/CSI and backups, installing the Qdrant Cloud agent and operator, creating/exposing/securing clusters, registry mirroring, and secret rotation. Use when someone wants to set u
Explains hybrid search in Qdrant. Use when someone asks 'how do I setup hybrid search?', 'how to combine keyword and semantic search?', 'sparse plus dense vectors?', 'missing keyword matches', 'how to combine results from multiple searches?' and 'combining multiple representations'. Also use for how
Fusing scores from multiple searches into a single ranked result (RRF, DBSF, custom fusion). Use when someone asks 'RRF or DBSF?', 'how to combine sparse and dense', 'how to combine scores from multiple searches?', 'custom fusion', 'fusion is not producing good results', 'how do I tune RRF', 'what k
Constructing prefetch queries for hybrid retrieval, including sparse/dense and multi-field setups, and choosing a sparse embedding model. Use when someone asks 'dense and sparse in one search?', 'how to combine multiple fields for retrieval?', 'payloads or sparse vectors for lexical?', 'which sparse
Related devops skillsscan passed
Deploy tRPC on WinterCG-compliant edge runtimes with fetchRequestHandler() from @trpc/server/adapters/fetch. Supports Cloudflare Workers, Deno Deploy, Vercel Edge Runtime, Astro, Remix, SolidStart. FetchCreateContextFnOptions provides req (Request) and resHeaders (Headers) for context creation. The
Automates CI/CD pipeline setup. Use when setting up or modifying build and deployment pipelines. Use when you need to automate quality gates, configure test runners in CI, or establish deployment strategies.
Use this skill to monitor and verify a deployed URL after releases — checks HTTP endpoints, SSE streams, static assets, console errors, and performance regressions after deploys, merges, or dependency upgrades. Smoke / canary / post-deploy verification.
Deploys and configures classic Firebase Hosting for static websites, single-page apps (SPAs), and microservices. Use when deploying static sites/SPAs, setting up custom domains, configuring firebase.json hosting settings (redirects, rewrites, headers, multi-site), or managing preview channels. Don't
Use when creating new skills, editing existing skills, or verifying skills work before deployment
Runs and interprets AWS Resilience Hub v2 failure mode assessments. Covers starting assessments, understanding findings (severity, categories, recommendations), triaging by achievability, working with AI-generated service functions, and resolving findings. Applies when the user wants to run an asses