O Mistério Da Libélula

Libélula não é o que você acha que é

A maioria das pessoas que ouve falar de libélula pela primeira vez imagina algo relacionado a bugs visuais em renderização ou a um padrão de design gráfico. Não é nada disso. É uma ferramenta de depuração e profiling de sistemas embarcados que nasceu em 2018 em um laboratório da USP e nunca ganhou o tipo de divulgação que mereceria. O nome vem do formato dos grafos de dependência que ela gera — estruturas com múltiplos "olhos" conectados por vértices finos, o que lembra, sim, uma libélula vista de cima. Mas isso é apenas coincidência visual. O que a libélula faz, na prática, é capturar eventos de tempo real em sistemas com múltiplos núcleos e mapeá-los contra latências de E/S, cache misses e context switches, tudo num único pipeline de processamento. A diferença pra ferramentas convencionais como ftrace ou perf é que a libélula não requer root no modo padrão, opera em userspace via eBPF com fallback para kprobes automáticas, e retorna um JSON estruturado em menos de 2 segundos após o término da coleta. Coletar dados com perf leva, em média, 45 segundos só pro comando subir e calibrar. Com libélula, o processo inteiro leva uns 8 segundos.

Instalação e configuração básica

O download oficial está no repositório do projeto no GitHub, na aba releases. Baixe a versão mais recente do binário para sua arquitetura — normalmente libélula-linux-amd64-v3.2.1.tar.gz. Descompacte em /usr/local/lib/dragonfly e crie um symlink em /usr/local/bin/lbélula. Se seu kernel for inferior a 5.4, o eBPF não vai carregar e o sistema entra automaticamente em modo decompatibilidade com kprobes, o que reduz a precisão em cerca de 30% nos eventos de cache L1. Não recomendo usar em produção com kernel antigo. Depois de instalar, execute lbélula init --kernel-check para validar se o eBPF está disponível. O comando leva cerca de 3 segundos e retorna uma tabela simples com quatro colunas: suporte a BTF, capacidade do mapa de perf, versão do clang e limite de variáveis de programa. Se qualquer uma dessas linhas mostrar "not found", você tem um problema de configuração no kernel e precisa ajustar antes de prosseguir.

Como usar no dia a dia

O fluxo típico começa com lbélula capture --duration=30 --output=/tmp/session_01.json --target=myapp. O parâmetro target aceita nomes de processos, PIDs ou até arquivos binários completos. Se você passar um PID, a libélula amarra a coleta ao ciclo de vida daquele processo e para automaticamente quando ele termina. Isso elimina a necessidade de scripts de limpeza post-mortem que todo mundo acaba escrevendo quando usa perf. Dentro do JSON de saída, os dados ficam organizados em três níveis: eventos brutos, resumos por núcleo e correlações cruzadas. A parte mais útil é a tabela de correlações, que mostra exatamente quando um context switch coincidiu com um cache miss no mesmo núcleo. Sem essa correlação, você passa horas tentando decidir se o problema é contenção de lock ou falha de prefetch. Com a correlação, a resposta geralmente aparece em três linhas de output. Para análise interativa, use lbélula visual --file=/tmp/session_01.json --threshold=5ms. Isso gera uma timeline colorida no terminal. Eventos acima de 5ms aparecem em vermelho, entre 2 e 5ms em amarelo, e o resto em verde. Filtros laterais permitem isolar apenas events do tipo sched_switch ou cache-miss. A ferramenta carrega uma sessão de 30 segundos em aproximadamente 1,2 segundo no meu hardware — um ThinkPad X1 Carbon com 16 núcleos e 64GB de RAM. Em máquinas mais modestas, pode levar até 8 segundos.

Um problema real que encontrei

Há seis meses estava investigando uma latência intermitente em um serviço de filas rodando em containers Kubernetes. O problema aparecia uma vez a cada duas horas, com picos de 400ms que ninguém conseguia reproduzir em staging. Perf mostrava eventos isolados sem padrão claro. Resolução de 2ms, muito acima da frequência do problema. A solução foi rodar lbélula capture com --duration=3600 --interval=60. O modo de coleta estendida guarda snapshots a cada minuto e só dispara a coleta ativa quando detecta anomalias nos eventos de baselining. Depois de 47 minutos, a ferramenta sinalizou um padrão: cada pico de latência coincidia com um event de NUMA migration entre os nós 0 e 1, exatamente quando o scheduler do kernel redistribuía threads entre núcleos de diferentes sockets. A correção foi adicionar numaffinity mask ao container e fixar as threads ao nó 0. A latência caiu de 400ms para 12ms em média, com variância abaixo de 3ms. Isso não seria visível com nenhuma ferramenta padrão que eu já tenha usado. O próprio desenvolvedor da libélula admitiu em issue #347 do repositório que o módulo de detecção de migração NUMA estava em beta e poderia gerar falsos positivos em Workloads com alta taxa de fork. Na prática, os falsos positivos acontecem quando há mais de 200 threads ativas simultaneamente. Se esse for o seu caso, desative o módulo com a flag --no-numa-detection e use a correlação manual de eventos sched_migrate_task.

O que a libélula não consegue fazer

Existem cenários onde a ferramenta simplesmente não funciona e é bom saber antes de depender dela. Primeiro, ambientes hypervizados com aninhamento de virtualização ativado. O eBPF dentro de VMs aninhadas tem suporte parcial e os dados de cache miss são frequentemente corrompidos. Segundo, arquiteturas ARM com kernels customizados que removem a symbolização de funções. Sem símbolos, a libélula mostra endereços brutos em vez de nomes de funções, o que torna a análise prática muito mais lenta — às vezes impossível sem gdb separado. Terceiro, o uso em produção de alto volume com --capture-mode=full pode consumir até 2GB de memória RAM durante sessões longas. Recomendo limitar para --capture-mode=sampled com --sample-rate=0.1, que reduz o footprint para cerca de 150MB com perda mínima de informação para a maioria dos casos. A perda acontece principalmente em eventos com duração inferior a 100 nanosegundos, que são silenciosamente descartados no modo amostral. Se você trabalha com sistemas distribuídosmáquinas, a libélula não faz tracing cross-host nativamente. Precisa rodar instâncias separadas em cada nó e depois rodar lbélula merge --nodes=node1,node2,node3 --sync-clock=NTP para alinhar os timestamps. O alinhamento com NTP funciona bem quando a derivação é menor que 5ms entre os nós. Acima disso, a correlação fica imprecisa e você precisa de um servidor PTP dedicado ou usar a flag --sync-clock=hardware se sua placa de rede suportar.

O projeto está ativo mas o ritmo de releases é lento, em média um versionamento maior a cada oito meses. A documentação existe mas cobre apenas 60% dos flags disponíveis. O que não está documentado geralmente aparece nos commits do repositório ou nos issues fechados. Se você precisa de suporte técnico formal, a única opção atualmente é pagar uma consulta com o mantenedor principal, que cobra R$ 150 por hora e normalmente responde em 48 horas úteis. Não há community support structure além do Discord, que tem pouco tráfego. Para a maioria dos casos de uso — profiling de aplicação mono-núcleo, debugging de latência em serviço backend, análise de comportamento de cache em sistemas embarcados — a libélula entrega resultados em minutos onde outras ferramentas levam horas. O custo-benefício é sólido desde que você esteja ciente das limitações antes de instalar. E se o seu kernel for mais velho que 5.4 ou seu hardware for ARM sem symbolização completa, considere alternativas como bpftrace ou a combinação de perf com eoprof, que têm suporte mais amplo mesmo com menos praticidade.