O ngxtop é uma ferramenta robusta para monitoramento em tempo real de servidores Nginx. Ele processa logs de acesso do Nginx para exibir informações de desempenho de forma similar ao comando top do Linux. Este guia tem como objetivo auxiliar desenvolvedores na configuração rápida do ambiente de desenvolvimento do ngxtop e na resolução de obstáculos comuns, facilitando a utilização e personalização desta ferramenta valiosa.

Configuração Inicial

O ngxtop é desenvolvido em Python, tornando sua instalação direta via gerenciador de pacotes pip.

Instalação Básica

Para a instalação padrão, execute o seguinte comando:

pip install ngxtop

É importante notar que o ngxtop foi primariamente testado com Python 2, mas é compatível com Python 3. Em sistemas onde Python 3 é a versão padrão, pode ser necessário usar pip3:

pip3 install ngxtop

Instalação via Código-Fonte

Para contribuir com o projeto ou realizar desenvolvimentos a partir do código-fonte, clone o repositório e instale:

git clone https://github.com/ngxtop/ngxtop.git
cd ngxtop
python setup.py install

Principais Desafios e Suas Soluções

Durante a configuração ou uso do ngxtop, alguns problemas podem surgir. Abaixo estão 10 cenários comuns e suas respectivas soluções.

Erro: "ImportError: No module named tabulate"

Descrição: Este erro indica a ausência da biblioteca tabulate, uma dependência essencial para o ngxtop.

Solução: Instale a biblioteca tabulate:

pip install tabulate

Problema: Arquivo de log Nginx não encontrado

Descrição: O ngxtop tenta automaitcamente localizar o arquivo de log do Nginx. Se falhar, um erro será exibido.

Solução: Especifique o caminho do arquivo de log manualmente utilizando o parâmetro -l:

ngxtop -l /var/log/nginx/access.log

Problema: Formato do log inconsistente ou não reconhecido

Descrição: Se o formato do log do Nginx não corresponder aos padrões esperados (como combined ou common), o ngxtop terá dificuldade em analisá-lo.

Solução: Defina o formato de log apropriado com o parâmetro -f. Formatos suportados incluem combined (padrão), common e caddy (para JSON do Caddy).

ngxtop -f common

Problema: Permissões de leitura insuficientes para o arquivo de log

Descrição: O usuário atual não possui as permissões necessárias para ler o arquivo de log do Nginx.

Solução: Garanta que o usuário tenha permissão de leitura ou execute o ngxtop com privilégios de superusuário:

sudo ngxtop

Erro: "nginx config file not found"

Descrição: O ngxtop não conseguiu localizar o arquivo de configuração principal do Nginx, que pode ser necessário para algumas funcionalidades.

Solução: Forneça o caminho do arquivo de configuração do Nginx usando o parâmetro -c:

ngxtop -c /etc/nginx/nginx.conf

Problema: Incompatibilidade de versão do Python

Descrição: Embora ngxtop seja compatível com Python 3, alguns módulos ou comportamentos podem causar problemas se o ambiente não for configurado corretamente.

Solução: Se você estiver executando em Python 3 e encontrar erros, pode ser útil tentar executar com Python 2 ou instalar pacotes de compatibilidade para Python 3, como future:

pip install future

Problema: Ausência de dados no monitoramento em tempo real

Descrição: O ngxtop não exibe novas entradas de log mesmo quando o Nginx está ativo.

Solução: Verifique se o parâmetro --no-follow foi acidentalmente usado. Este parâmetro faz com que o ngxtop processe apenas o conteúdo de log existente e não monitore novas linhas. O comportamento padrão é seguir novas entradas.

# Para processar apenas conteúdo existente (não seguir novas entradas)
ngxtop --no-follow

Problema: Dados de estatísticas imprecisos ou com latência

Descrição: As estatísticas exibidas podem não refletir as condições mais recentes ou podem ser atualizadas com pouca frequência.

Solução: Ajuste o intervalo de atualização dos relatórios. Use o parâmetro -t para definir um tempo de intervalo menor (em segundos):

ngxtop -t 1

Problema: Necessidade de analisar logs de um servidor remoto

Descrição: Você precisa monitorar logs de Nginx hospedados em um servidor diferente do qual o ngxtop está sendo executado.

Solução: Utilize SSH para redirecionar o fluxo de log do servidor remoto para o ngxtop local:

ssh usuario@servidor_remoto tail -f /var/log/nginx/access.log | ngxtop

Problema: Definição de métricas de monitoramento personalizadas

Descrição: As métricas padrão do ngxtop não são suficientes e você precisa visualizar dados específicos, como os IPs mais ativos.

Solução: Aproveite os recursos de consulta avançada do ngxtop. Por exemplo, para listar os endereços IP que mais acessaram o servidor:

ngxtop top remote_addr

Funcionalidades Essenciais e Exemplos de Uso

O ngxtop oferece diversas opções para análise e visualização de logs.

Visão de Monitoramento Padrão

Ao executar o ngxtop sem parâmetros, você obtém uma visão geral em tempo real, incluindo contagem de requisições, bytes enviados e estatísticas de códigos de status HTTP.

ngxtop

Estatísticas de Endereços IP

Para identificar os IPs de clientes que mais interagem com seu servidor:

ngxtop top remote_addr

Filtragem de Requisições com Erro

É possível filtrar logs com base em critérios específicos, como códigos de status 4xx ou 5xx, e exibir informações relevantes para essas requisições:

ngxtop -i 'status >= 400' print request status http_referer

Análise de Logs Apache

O ngxtop não se limita ao Nginx; ele pode processar logs de outros servidores web, como Apache, usando formatos de log comuns:

ngxtop -f common -l /var/log/apache2/access.log

Nota: Certifique-se de ajustar o caminho do log para sua instalação Apache.

Processamento de Logs Caddy JSON

Para usuários do Caddy Server, o ngxtop pode analisar diretamente logs no formato JSON:

ngxtop -l /var/log/caddy/access.log -f caddy

Extensão e Adaptação do ngxtop

Para desenvolvedores ou aqueles que precisam de maior controle, o ngxtop permite personalização e extensão.

Estrutura do Projeto

Os principais componentes do ngxtop estão organizados da seguinte forma no diretório raiz do projeto:

• ngxtop/ngxtop.py: Ponto de entrada principal da aplicação.
• ngxtop/config_parser.py: Módulo responsável pela interpretação de arquivos de configuração.
• ngxtop/utils.py: Contém funções utilitárias e auxiliares.
• tests/: Diretório dedicado aos testes unitários e de integração.

Formatos de Log Personalizados

Caso o Nginx utilize um formato de log não padrão, você pode especificá-lo diretamente via linha de comando:

ngxtop -f '$remote_addr [$time_local] "$request" $status $body_bytes_sent "$http_referer" "$http_user_agent"'

Essa flexibilidade permite que o ngxtop se adapte a praticamente qualquer configuração de log do Nginx.