Comment déboguer Qdrant avec les métriques

Commencez par vérifier le statut 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 le endpoint /collections/{collection_name}/optimizations (v1.17+) pour vérifier le statut Optimization monitoring
• Interrogez avec les 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 la progression
• L'interface Web a un onglet Optimizations avec une vue chronologique et des métriques de durée par tâche Web UI
• Si optimizer_status affiche une erreur dans les infos de collection, vérifiez les logs pour disque plein ou segments corrompus
• Les grandes fusions et reconstructions HNSW prennent légitimement des heures sur les gros datasets. Vérifiez la progression avant de supposer un blocage.

La mémoire semble trop élevée

À utiliser quand : la mémoire dépasse les attentes, un nœud plante avec OOM, ou la mémoire ne cesse de croître.

• Les métriques de mémoire du processus sont 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 par la RAM disponible est normal. Memory article
• Si la mémoire résidente (RSSAnon) dépasse 80 % de la RAM totale, enquêtez
• Vérifiez /telemetry pour une répartition par collection du nombre de points et des configurations vectorielles
• Estimez la mémoire attendue : num_vectors * dimensions * 4 octets * 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'index 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 histogramme rest_responses_duration_seconds (v1.8+) pour l'analyse des percentiles dans Grafana
• Métriques gRPC équivalentes avec le préfixe grpc_responses_
• Vérifiez d'abord le statut de l'optimizer. Les optimisations actives se disputent le CPU et les 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 signifie un index de payload manquant. Payload index

Ce qu'il NE FAUT PAS faire

• Ignorer le statut de l'optimizer lors du débogage des 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 configuration pendant que l'optimizer s'exécute (provoque des réoptimisations en cascade)
• Blâmer Qdrant avant de vérifier si un chargement en masse vient de se terminer (segments non fusionnés)