Comment déboguer Qdrant avec les métriques

D'abord vérifiez l'état de l'optimizer. La plupart des problèmes de production remontent à des optimisations actives qui se disputent les ressources. Si l'optimizer est propre, vérifiez la mémoire, puis les métriques de requête.

Optimizer bloqué ou trop lent

À utiliser quand : l'optimizer s'exécute depuis des heures sans terminer, ou affiche des erreurs.

• Utilisez l'endpoint /collections/{collection_name}/optimizations (v1.17+) pour vérifier l'état Optimization monitoring
• Interrogez avec des flags de détail optionnels : ?with=queued,completed,idle_segments
• Retourne : nombre d'optimisations en attente, type d'optimizer actif, segments impliqués, suivi de progression
• L'interface web dispose d'un onglet Optimizations avec vue chronologique et métriques de durée par tâche Web UI
• Si optimizer_status affiche une erreur dans les infos de collection, consultez les logs pour disque plein ou segments corrompus
• Les grandes fusions et reconstructions HNSW peuvent légitimement prendre des heures sur de grands datasets. Vérifiez la progression avant de supposer que c'est bloqué.

La mémoire semble trop élevée

À utiliser quand : la mémoire dépasse les attentes, le nœud plante avec OOM, ou la mémoire ne cesse d'augmenter.

• Métriques de mémoire du processus disponibles via /metrics (RSS, octets alloués, défauts de page)
• Qdrant utilise deux types de RAM : la mémoire résidente (structures de données, vecteurs quantifiés) et le cache de pages du système d'exploitation (lectures disque en cache). Le remplissage du cache de pages dans la RAM disponible est normal. Memory article
• Si la mémoire résidente (RSSAnon) dépasse 80 % de la RAM totale, enquêter
• Vérifiez /telemetry pour une ventilation par collection des nombres de points et configurations de vecteurs
• Estimez la mémoire attendue : num_vectors * dimensions * 4 bytes * 1.5 pour les vecteurs, plus surcharge de payload et d'index Capacity planning
• Causes courantes de croissance inattendue : vecteurs quantifiés avec always_ram=true, trop d'indexes de payload, max_segment_size trop grand lors de l'optimisation

Les requêtes sont lentes

À utiliser quand : les requêtes sont plus lentes que prévu et vous devez identifier la cause.

• Suivez rest_responses_avg_duration_seconds et rest_responses_max_duration_seconds par endpoint
• Utilisez la métrique histogram rest_responses_duration_seconds (v1.8+) pour l'analyse par percentile dans Grafana
• Métriques gRPC équivalentes avec le préfixe grpc_responses_
• Vérifiez d'abord l'état de l'optimizer. Les optimisations actives se disputent le CPU et l'I/O, dégradant la latence de recherche.
• Vérifiez le nombre de segments via les infos de collection. Trop de segments non fusionnés après un chargement en masse ralentit la recherche.
• Comparez les temps de requête filtrée vs non filtrée. Un grand écart indique un index de payload manquant. Payload index

Ce qu'il NE FAUT PAS faire

• Ignorer l'état de l'optimizer lors du débogage de requêtes lentes (cause racine la plus courante)
• Supposer une fuite mémoire quand le cache de pages remplit la RAM (comportement normal du système d'exploitation)
• Effectuer des changements de config pendant que l'optimizer s'exécute (provoque des re-optimisations en cascade)
• Blâmer Qdrant avant de vérifier si un chargement en masse vient de terminer (segments non fusionnés)