qdrant-monitoring-debugging

--- Diagnostique les problèmes de production Qdrant en utilisant les métriques et les outils d'observabilité. À utiliser quand quelqu'un signale « optimizer stuck », « indexing too slow », « memory too high », « OOM crash », « queries are slow », « latency spike », ou « search was fast now it's slow ». À utiliser également quand les performances se dégradent sans changements de configuration évidents.

npx skills add https://github.com/qdrant/skills --skill qdrant-monitoring-debugging

Comment déboguer Qdrant avec les métriques

Commencez par vérifier le statut de l'optimiseur. La plupart des problèmes de production remontent à des optimisations actives qui se disputent les ressources. Si l'optimiseur est en bon état, vérifiez la mémoire, puis les métriques de requête.

Optimiseur bloqué ou trop lent

À utiliser quand : l'optimiseur s'exécute pendant 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 des drapeaux de détail optionnels : ?with=queued,completed,idle_segments
  • Retourne : nombre d'optimisations en attente, type d'optimiseur actif, segments impliqués, suivi de la progression
  • L'interface Web dispose d'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 journaux pour un disque plein ou des segments corrompus
  • Les grandes fusions et les reconstructions HNSW prennent légitimement des heures sur les grands ensembles de données. 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 un OOM, ou la mémoire continue d'augmenter.

  • Les métriques de mémoire de 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 de disque en cache). Le remplissage du cache de pages de 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 ventilation par collection des nombres de points et des configurations de vecteurs
  • Estimez la mémoire attendue : nombre_vecteurs * dimensions * 4 octets * 1.5 pour les vecteurs, plus les frais généraux des payloads et des 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 pendant 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'optimiseur. Les optimisations actives se disputent le CPU et les E/S, 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 téléchargement en masse ralentissent la recherche.
  • Comparez les temps de requête filtrés et non filtrés. Un grand écart signifie un index de payload manquant. Payload index

Ce qu'il NE FAUT PAS faire

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