Como Perfilhar e Otimizar Pipelines de Agregação Lentas no MongoDB

Os pipelines de agregação do MongoDB são fáceis de crescer um estágio de cada vez. Um relatório começa com um $match, depois alguém adiciona um $lookup, depois um $group, depois uma ordenação, e seis meses depois o endpoint está tão lento que todos têm medo de tocá-lo.

A correção começa com evidências. Você precisa saber qual estágio lê demais, expande demais, ordena demais ou junta tarde demais. O MongoDB oferece duas ferramentas práticas para esse trabalho: o profiler do banco de dados para operações lentas históricas e .explain("executionStats") para uma análise detalhada de um pipeline específico.

Entendendo o Profiler do MongoDB

O Profiler do MongoDB registra os detalhes de execução das operações do banco de dados, incluindo comandos find, update, delete e, mais importante para este guia, aggregate. Ele registra quanto tempo uma operação levou, quais recursos consumiu e quais estágios contribuíram mais para a latência.

Ativando e Configurando Níveis de Perfilhamento

Antes de perfilhar, você deve garantir que o profiler esteja ativo e configurado em um nível que capture os dados necessários. Os níveis de perfilhamento variam de 0 (desligado) a 2 (todas as operações registradas).

Nível	Descrição
0	Profiler desabilitado.
1	Registra operações que levam mais tempo que a configuração slowOpThresholdMs.
2	Registra todas as operações executadas no banco de dados.

Para definir o nível do profiler, use o comando db.setProfilingLevel(). Geralmente, recomenda-se usar o Nível 1 ou 2 temporariamente durante testes de desempenho para evitar E/S de disco excessiva.

Exemplo: Configurando o Profiler para o Nível 1 (registrando operações mais lentas que 100ms)

// Conecte-se ao seu banco de dados: use myDatabase
db.setProfilingLevel(1, { slowOpThresholdMs: 100 })

// Verifique a configuração
db.getProfilingStatus()

Melhor Prática: Nunca deixe o profiler no Nível 2 em um sistema de produção indefinidamente, pois registrar todas as operações pode impactar significativamente o desempenho de escrita.

Visualizando Dados de Agregação Perfilhados

As operações perfilhadas são armazenadas na coleção system.profile dentro do banco de dados que você está perfilhando. Você pode consultar esta coleção para encontrar agregações lentas recentes.

Para encontrar consultas de agregação lentas, filtre os resultados onde o campo op é 'aggregate' e o tempo de execução (millis) excede seu limite.

// Encontre todas as operações de agregação lentas na última hora
db.system.profile.find(
  {
    op: 'aggregate',
    millis: { $gt: 100 } // Operações mais lentas que 100ms
  }
).sort({ ts: -1 }).limit(5).pretty()

Analisando Detalhes de Execução do Pipeline de Agregação

A saída do profiler é crucial. Ao examinar um documento de agregação lento, procure especificamente pelo planSummary e, mais importante, pelo array stages dentro do resultado.

Utilizando a Saída Detalhada de .explain('executionStats')

Enquanto o profiler captura dados históricos, executar uma agregação com .explain('executionStats') fornece detalhes granulares em tempo real sobre como o MongoDB executou o pipeline no conjunto de dados atual, incluindo tempos por estágio.

Exemplo usando Explain:

db.collection('sales').aggregate([
  { $match: { status: 'A' } },
  { $group: { _id: '$customerId', total: { $sum: '$amount' } } }
]).explain('executionStats');

Na saída, o array stages detalha cada operador no pipeline. Para cada estágio, procure por:

• executionTimeMillis: O tempo gasto executando aquele estágio específico.
• nReturned: O número de documentos passados para o próximo estágio.
• totalKeysExamined / totalDocsExamined: Métricas que indicam o custo de E/S.

Estágios com executionTimeMillis muito alto ou estágios que examinam muito mais documentos (totalDocsExamined) do que retornam são seus principais alvos de otimização.

Estratégias para Otimizar Estágios de Agregação Lentos

Uma vez que o perfilhamento identifica o estágio gargalo (por exemplo, $match, $lookup ou estágios de ordenação), você pode aplicar técnicas de otimização direcionadas.

1. Otimize a Filtragem Inicial ($match)

O estágio $match deve sempre ser o primeiro estágio em seu pipeline, se possível. Filtrar cedo reduz o número de documentos que estágios subsequentes e intensivos em recursos (como $group ou $lookup) precisam processar.

O Papel da Indexação: Se seu estágio $match inicial é lento, quase certamente está faltando um índice nos campos usados no filtro. Garanta que os índices cubram os campos usados em $match.

Se o estágio $match envolve campos que não são indexados, o estágio pode realizar uma varredura completa da coleção, o que será explicitamente visível na saída do explain como um alto totalDocsExamined.

2. Utilizando Eficientemente $lookup (Junções)

O estágio $lookup é frequentemente o componente mais lento. Ele efetivamente realiza uma junção anti contra outra coleção.

• Indexe a Chave Estrangeira: Garanta que o campo pelo qual você está juntando na coleção estrangeira (a que é consultada) seja indexado. Isso acelera significativamente o processo de consulta interna.
• Filtre Antes da Junção: Sempre que possível, aplique um estágio $match antes do $lookup para garantir que você está juntando apenas documentos necessários.

3. Lidando com Ordenação Custosa ($sort)

Ordenar documentos é computacionalmente caro, especialmente em grandes conjuntos de resultados. O MongoDB só pode usar um índice para ordenação se o prefixo do índice corresponder ao filtro da consulta e a ordem de classificação estiver alinhada com a definição do índice.

Otimização Chave para $sort: Se um estágio $sort parece caro, tente criar um índice coberto que corresponda ao filtro e à ordem de classificação necessária. Por exemplo, se você filtrar por { status: 1 } e depois ordenar por { date: -1 }, um índice em { status: 1, date: -1 } permitiria ao MongoDB recuperar documentos na ordem necessária sem uma ordenação em memória custosa.

4. Minimizando Movimentação de Dados com $project

Use o estágio $project estrategicamente para reduzir a quantidade de dados passados pelo pipeline. Se estágios posteriores precisam apenas de alguns campos, use $project no início do pipeline para descartar campos e documentos embutidos desnecessários. Documentos menores significam menos dados sendo movidos entre os estágios do pipeline e potencialmente melhor utilização da memória.

5. Evitando Estágios Custosos que Não Podem Usar Índices

Estágios como $unwind podem criar muitos novos documentos, aumentando rapidamente a sobrecarga de processamento. Embora às vezes necessário, garanta que a entrada para $unwind seja a menor possível. Da mesma forma, estágios que forçam uma reavaliação completa do conjunto de dados, como aqueles que dependem de cálculos ou expressões complexas sem suporte de índice, devem ser minimizados.

Um Passo a Passo Realista de Otimização

Imagine um painel de suporte que mostra o valor total de reembolso por cliente nos últimos 30 dias. Começou rápido, depois ficou lento após um ano de pedidos acumulados. O pipeline parece inofensivo:

db.orders.aggregate([
  { $lookup: {
      from: "customers",
      localField: "customerId",
      foreignField: "_id",
      as: "customer"
  }},
  { $unwind: "$customer" },
  { $match: { status: "refunded", createdAt: { $gte: startDate } } },
  { $group: { _id: "$customerId", totalRefunded: { $sum: "$amount" } } },
  { $sort: { totalRefunded: -1 } },
  { $limit: 50 }
])

O erro caro não é óbvio até você olhar para a ordem do trabalho. Este pipeline junta cada pedido a um cliente antes de filtrar para pedidos reembolsados nos últimos 30 dias. Em uma coleção grande, isso significa que o MongoDB faz muitas junções para documentos que serão descartados depois.

Uma primeira versão melhor filtra cedo:

db.orders.aggregate([
  { $match: { status: "refunded", createdAt: { $gte: startDate } } },
  { $group: { _id: "$customerId", totalRefunded: { $sum: "$amount" } } },
  { $sort: { totalRefunded: -1 } },
  { $limit: 50 },
  { $lookup: {
      from: "customers",
      localField: "_id",
      foreignField: "_id",
      as: "customer"
  }},
  { $unwind: "$customer" }
])

Agora a junção acontece apenas para os 50 principais clientes agrupados, não para cada pedido na coleção. Esse é o tipo de mudança que o perfilhamento deve te levar: menos dados entram nos estágios caros.

Para esta versão, um índice útil em orders poderia ser:

db.orders.createIndex({ status: 1, createdAt: -1, customerId: 1 })

O índice exato depende de seus filtros e necessidades de ordenação reais, mas a ideia é estável: suportar o $match inicial e incluir campos que ajudem o pipeline a evitar leituras extras de documentos quando possível. Na coleção customers, _id já é indexado, então o $lookup geralmente é bom. Se você juntar por outro campo, indexe esse campo estrangeiro.

Ao revisar .explain("executionStats"), não olhe apenas para o tempo total de execução. Procure por fan-out. Se um estágio retorna 500 documentos e o próximo retorna 2 milhões por causa de $unwind, você encontrou o estágio que mudou a forma do problema. Se totalDocsExamined é muito maior que nReturned, o índice não é seletivo o suficiente ou não está sendo usado da maneira que você esperava. Se uma ordenação aparece tarde no pipeline após um grande group, considere se você pode limitar mais cedo ou pré-agregar em uma coleção separada para painéis que não precisam de atualização a cada segundo.

Observe também o comportamento da memória. $group, $sort, $setWindowFields e alguns padrões de $lookup podem exigir muita memória. allowDiskUse: true pode evitar que um pipeline falhe quando excede os limites de memória, mas não é uma correção de desempenho por si só. Escrever em disco geralmente significa que o pipeline está fazendo muito trabalho de uma vez. Pode ser aceitável para um relatório noturno. Raramente é aceitável para um endpoint de API voltado para o usuário que é executado a cada carregamento de página.

Um hábito prático é salvar o pipeline lento, a saída do explain e os índices juntos nas notas do incidente. A próxima pessoa não deve ter que redescobrir por que um índice existe ou por que $lookup foi movido para depois de $limit. O ajuste de agregação é muito mais fácil quando o raciocínio sobrevive mais tempo que a sessão de depuração.

Índices que Ajudam Agregações e Índices que Só Parecem Ajudar

Pipelines de agregação frequentemente expõem índices compostos fracos. Suponha que sua API filtra por tenant e data, depois agrupa por status:

db.orders.aggregate([
  { $match: { tenantId, createdAt: { $gte: start, $lt: end } } },
  { $group: { _id: "$status", count: { $sum: 1 } } }
])

Um índice em { createdAt: -1 } pode ajudar um pouco, mas em um sistema multi-tenant ainda pode escanear um grande intervalo de datas para cada tenant. Um índice em { tenantId: 1, createdAt: -1 } geralmente corresponde melhor ao padrão de acesso porque estreita primeiro para o tenant e depois percorre o intervalo de datas. Se a maioria das consultas também inclui status, teste se { tenantId: 1, status: 1, createdAt: -1 } é melhor para essa carga de trabalho. Não adivinhe. Execute explain, compare keysExamined, docsExamined e o tempo decorrido em dados semelhantes aos de produção.

Tenha cuidado com campos de baixa cardinalidade na frente de um índice. Um índice começando com { status: 1 } pode não ser seletivo se quase todos os pedidos estão complete. Ainda pode ser útil quando combinado com outros campos, mas deve refletir a forma da consulta. O melhor índice não é aquele com mais campos; é aquele que reduz o espaço de busca cedo sem criar sobrecarga de escrita desnecessária.

Quando Parar de Otimizar o Pipeline

Às vezes, a correção certa não é outra reescrita de pipeline. Se um painel executa a mesma agregação cara toda vez que um gerente abre a página, a pré-agregação pode ser mais limpa. Um trabalho agendado pode escrever totais por hora em uma coleção order_stats_hourly, e o painel pode ler alguns documentos pequenos. Você troca atualização por latência previsível.

Essa troca geralmente é aceitável quando humanos estão lendo tendências. É menos aceitável quando o pipeline alimenta uma decisão de checkout ou regra de fraude. Torne o requisito de atualização explícito. "Dentro de cinco minutos" abre caminho para pré-agregação e cache. "Deve incluir o último pedido confirmado" provavelmente mantém você mais perto de leituras ao vivo com comportamento de escrita e leitura mais forte.

A otimização de agregação não é sobre tornar todo pipeline inteligente. É sobre remover trabalho que o banco de dados não deveria fazer no caminho da requisição.

Resumo e Próximos Passos

Perfilhar e otimizar pipelines de agregação do MongoDB requer uma abordagem sistemática e baseada em evidências. Ao aproveitar o profiler embutido (db.setProfilingLevel) e executar estatísticas de execução detalhadas (.explain('executionStats')), você pode transformar problemas complexos de desempenho em etapas solucionáveis.

O fluxo de trabalho de otimização é:

1. Ative o Perfilhamento: Defina o nível 1 e um slowOpThresholdMs.
2. Execute a Consulta: Execute o pipeline de agregação lento.
3. Analise os Dados Perfilhados: Identifique o estágio específico que consome mais tempo.
4. Explique em Detalhe: Use .explain('executionStats') no pipeline problemático.
5. Ajuste: Crie índices necessários, reordene estágios (filtre primeiro) e simplifique os dados passados para operadores caros.

O monitoramento contínuo garante que novos recursos adicionados ou o aumento do volume de dados não reintroduzam os problemas de desempenho que você resolveu.