nextcloud-activity-report/README.md

Suíte de Análise de Logs para Zabbix e NGINX

Este repositório contém uma suíte de scripts Python para análise avançada de logs de aplicações web. As ferramentas extraem dados de fontes como Zabbix e arquivos CSV do NGINX para gerar relatórios interativos em HTML, oferecendo insights sobre performance do sistema, auditoria de acesso de usuários e categorização de atividades.

---

As Ferramentas

A suíte é composta por três scripts principais, cada um com um objetivo específico:

1. performance-insights.py (O Analista de Performance)

Este script conecta-se à API do Zabbix para analisar a saúde técnica e a performance do sistema.

• O que faz? Mede a velocidade das respostas do servidor e identifica a frequência e o tipo de erros HTTP.
• Responde a perguntas como:
  • "Qual o tempo médio de resposta do sistema?"
  • "Quantas requisições foram rápidas, aceitáveis ou lentas?"
  • "Quais páginas ou arquivos estão gerando mais erros 404 (Não Encontrado)?"
• Resultado: Gera um relatório chamado relatorio_insights_AAAA-MM-DD.html com gráficos de pizza sobre a velocidade e status das requisições, além de tabelas com os principais erros.

2. audit-logins.py (O Auditor de Acesso)

Este script também utiliza a API do Zabbix, mas com foco em auditar o comportamento e o tempo de atividade dos usuários.

• O que faz? Identifica sessões de trabalho, calculando o início, o fim e a duração total da atividade de cada usuário em um dia.
• Responde a perguntas como:
  • "Quais usuários acessaram o sistema hoje?"
  • "A que horas cada pessoa começou e terminou de trabalhar?"
  • "Quanto tempo cada um ficou efetivamente online?"
• Resultado: Gera um relatório chamado relatorio_acesso_AAAA-MM-DD.html com uma linha do tempo interativa (gráfico de Gantt) e uma tabela que resume o tempo de serviço de cada colaborador.

3. relatorio-de-atividade.py (O Categorizador de Ações)

Diferente dos outros, este script analisa um arquivo de log NGINX em formato CSV para classificar os tipos de interação do usuário com o sistema.

• O que faz? Categoriza cada ação do usuário como "Ativa" (edição, upload), "Online" (navegação) ou "Outras" (sincronização em segundo plano).
• Responde a perguntas como:
  • "Qual o perfil de uso de cada colaborador? Ele passa mais tempo editando arquivos ou apenas navegando?"
  • "Quais os horários de pico para atividades produtivas (uploads, edições)?"
• Resultado: Gera um relatório único chamado painel_de_atividade_final.html com heatmaps de atividade, nuvens de ações e timelines detalhadas por tipo de ação.

---

Pré-requisitos

• Python 3.8+
• Fonte de Logs:
  • Para os scripts performance-insights.py e audit-logins.py: Acesso à API do Zabbix com um item que colete os logs da aplicação em formato JSON.
  • Para o script relatorio-de-atividade.py: Um arquivo de log access.log do NGINX exportado em formato CSV, conforme o log_format abaixo.
• Dependências Python: Todas as bibliotecas necessárias estão no arquivo requirements.txt.

Exemplo de log_format para relatorio-de-atividade.py

Adicione este formato à sua configuração do NGINX (nginx.conf):

log_format custom_csv escape=json
    '$time_iso8601,'
    '$remote_addr,'
    '"$http_user_agent",'
    '"$http_cookie",'
    '$status,'
    '$body_bytes_sent,'
    '$remote_user,'
    '$request_time,'
    '$upstream_response_time,'
    '"$request"';

access_log /var/log/nginx/seu-site.access.log custom_csv;

---

Instalação

1. Clone o Repositório

   git clone [URL_DO_SEU_REPO_GITEA]
   cd [NOME_DO_REPOSITORIO]
   

2. Crie e Ative um Ambiente Virtual (Recomendado)

   python3 -m venv venv
   source venv/bin/activate
   

3. Instale as Dependências Crie um arquivo requirements.txt com o seguinte conteúdo e depois execute o comando pip install.

   requirements.txt:

   pandas
   plotly
   py-zabbix
   matplotlib
   seaborn
   numpy
   scipy
   

   Comando de instalação:

   pip install -r requirements.txt
   

---

Como Utilizar

A execução varia dependendo do script que você deseja usar.

Para os Scripts de Zabbix (performance-insights.py e audit-logins.py)

Ambos os scripts compartilham os mesmos parâmetros de linha de comando para se conectar ao Zabbix.

Argumentos:

• --server: URL completa do seu servidor Zabbix.
• --token: Token da API do Zabbix para autenticação.
• --host: Nome do host no Zabbix (o nome técnico, não o visível).
• --item: Nome do item que contém os logs.
• --dias: (Opcional) Número de dias para analisar (padrão: 1, ou seja, o dia anterior).

Exemplo de execução para Performance:

python src/performance-insights.py --server "[https://zabbix.suaempresa.com.br/](https://zabbix.suaempresa.com.br/)" --token "seu_token_aqui" --host "nome_do_host" --item "nome_do_item_de_log" --dias 7

Exemplo de execução para Auditoria de Acesso:

python src/audit-logins.py --server "[https://zabbix.suaempresa.com.br/](https://zabbix.suaempresa.com.br/)" --token "seu_token_aqui" --host "nome_do_host" --item "nome_do_item_de_log"

Para o Script de Análise NGINX (relatorio-de-atividade.py)

Este script requer apenas o caminho para o arquivo de log em formato CSV.

Exemplo de execução:

python src/relatorio-de-atividade.py /caminho/para/seu/nginx_logs.csv

---

Licença

Este projeto está licenciado sob a Licença MIT. Veja o arquivo LICENSE para mais detalhes.