Como Depurar Qdrant com Métricas

Primeiro, verifique o status do otimizador. A maioria dos problemas de produção remonta a otimizações ativas competindo por recursos. Se o otimizador estiver limpo, verifique a memória e, em seguida, as métricas de requisição.

Otimizador Travado ou Muito Lento

Use quando: o otimizador está rodando por horas, não termina ou mostra erros.

• Use o endpoint /collections/{collection_name}/optimizations (v1.17+) para verificar o status Monitoramento de Otimização
• Consulte com flags de detalhe opcionais: ?with=queued,completed,idle_segments
• Retorna: contagem de otimizações em fila, tipo de otimizador ativo, segmentos envolvidos, rastreamento de progresso
• A Interface Web tem uma aba de Otimizações com visualização de linha do tempo e métricas de duração por tarefa Interface Web
• Se optimizer_status mostrar um erro nas informações da coleção, verifique os logs de disco cheio ou segmentos corrompidos
• Grandes mesclagens e reconstruções de HNSW legitimamente levam horas em grandes conjuntos de dados. Verifique o progresso antes de assumir que está travado.

Memória Parece Muito Alta

Use quando: a memória excede as expectativas, o nó trava com OOM (Out Of Memory), ou a memória continua crescendo.

• Métricas de memória do processo disponíveis via /metrics (RSS, bytes alocados, page faults)
• Qdrant usa dois tipos de RAM: memória residente (estruturas de dados, vetores quantizados) e cache de página do SO (leituras de disco em cache). O preenchimento do cache de página na RAM disponível é normal. Artigo sobre Memória
• Se a memória residente (RSSAnon) exceder 80% da RAM total, investigue
• Verifique /telemetry para um detalhamento por coleção de contagens de pontos e configurações de vetores
• Estime a memória esperada: num_vectors * dimensions * 4 bytes * 1.5 para vetores, mais sobrecarga de payload e índice Planejamento de Capacidade
• Causas comuns de crescimento inesperado: vetores quantizados com always_ram=true, muitos índices de payload, max_segment_size grande durante a otimização

Consultas Estão Lentas

Use quando: consultas mais lentas que o esperado e você precisa identificar a causa.

• Monitore rest_responses_avg_duration_seconds e rest_responses_max_duration_seconds por endpoint
• Use a métrica de histograma rest_responses_duration_seconds (v1.8+) para análise de percentil no Grafana
• Métricas gRPC equivalentes com prefixo grpc_responses_
• Verifique o status do otimizador primeiro. Otimizações ativas competem por CPU e I/O, degradando a latência de busca.
• Verifique a contagem de segmentos através das informações da coleção. Muitos segmentos não mesclados após upload em massa causam busca mais lenta.
• Compare tempos de consulta filtrados vs. não filtrados. Uma grande diferença significa índice de payload ausente. Índice de Payload

O Que NÃO Fazer

• Ignorar o status do otimizador ao depurar consultas lentas (causa raiz mais comum)
• Assumir vazamento de memória quando o cache de página preenche a RAM (comportamento normal do SO)
• Fazer alterações de configuração enquanto o otimizador está rodando (causa re-otimizações em cascata)
• Culpar o Qdrant antes de verificar se o upload em massa acabou de terminar (segmentos não mesclados)