simple-python-audit 1.3.0

Ferramenta de profiling com widget flutuante, exportação CSV e servidor de gerenciamento de logs.

Simple Python Audit Tool 🚀

Ferramenta completa para medição de performance e auditoria de variáveis para Python.

📦 Instalação

pip install .
# Ou via GitHub
pip install git+https://github.com/sadson/simple_python_audit.git

🎯 Como Usar

from simple_python_audit import profile

@profile(
    html=True,
    trace=True,
    deep=True,
    print_terminal=True,
    save_csv=True,
    output_path="/tmp/simple_python_audit_perf",
)
def meu_metodo_lento(self):
    # Seu código aqui

Parâmetros do decorador

Parâmetro	Padrão	Descrição
html	False	Gera relatório interativo em HTML com widget flutuante
trace	False	Rastreia chamadas de funções e coleta métricas por função
deep	False	Aumenta granularidade do profiler (intervalo de 0,0001 s em vez de 0,001 s)
print_terminal	False	Imprime tabela de métricas formatada no terminal ao final da execução
save_csv	False	Salva os dados em arquivos CSV prontos para análise com pandas/IA
output_path	"/tmp/simple_python_audit_perf"	Diretório onde os relatórios (HTML e CSV) serão gravados

---

📊 Saída no Terminal (print_terminal=True)

Exibe uma tabela formatada diretamente no stdout ao término da função:

==============================================================
  AUDIT: meu_metodo_lento  |  1.2345s
==============================================================
  CPU Total:             0.4567s
  CPU Usage:             37.0%
  Memory Current:        12.345 MB
  Memory Peak:           15.678 MB
  Memory Avg/Call:       2.34 KB/call
  Total Calls Traced:    1234
--------------------------------------------------------------
  Top Functions by CPU Time:
  Function                        Calls     Total       Avg      Peak
  meu_metodo_lento                    1   1.2300s  1.23000s  1.23000s
  _query                             42   0.4500s  0.01071s  0.02100s
  ...
--------------------------------------------------------------
  Top Functions by Memory:
  Function                        Calls   Total KB   Avg KB  Peak KB
  _query                             42     512.30    12.20    48.50
  ...

---

💾 Exportação CSV (save_csv=True)

Gera dois arquivos CSV em output_path, ideais para carregar em um DataFrame do pandas, alimentar uma IA ou construir dashboards.

AUDIT_{func}_{timestamp}_summary.csv

Uma linha por execução com as métricas globais da chamada. Acumulando múltiplas execuções é possível rastrear regressões de performance ao longo do tempo.

Coluna	Tipo	Descrição
timestamp	int	Unix timestamp da execução
func_name	str	Nome da função decorada
duration_s	float	Tempo total de execução (segundos)
cpu_total_s	float	Tempo de CPU consumido (segundos)
cpu_pct	float	Percentual de uso de CPU
mem_current_mb	float	Memória alocada ao final (MB)
mem_peak_mb	float	Pico de memória durante a execução (MB)
mem_avg_kb_per_call	float	Média de memória por chamada de função (KB)
total_calls_traced	int	Total de chamadas de função rastreadas

AUDIT_{func}_{timestamp}_trace.csv

Uma linha por função rastreada (requer trace=True). Permite identificar os gargalos com precisão.

Coluna	Tipo	Descrição
timestamp	int	Unix timestamp — chave para junção com summary
func_name	str	Nome da função decorada
called_function	str	Nome da função rastreada
call_count	int	Número de chamadas
total_time_s	float	Tempo total acumulado (segundos)
avg_time_s	float	Tempo médio por chamada (segundos)
peak_time_s	float	Pico de tempo em uma única chamada (segundos)
total_mem_kb	float	Memória total alocada (KB)
avg_mem_kb	float	Memória média por chamada (KB)
peak_mem_kb	float	Pico de memória em uma única chamada (KB)

Exemplo de análise com pandas

import pandas as pd
import glob

# Carregar todos os resumos de execuções
summary = pd.concat([pd.read_csv(f) for f in glob.glob("/tmp/simple_python_audit_perf/*_summary.csv")])
summary["timestamp"] = pd.to_datetime(summary["timestamp"], unit="s")
summary.sort_values("timestamp").plot(x="timestamp", y="duration_s", title="Evolução do tempo de execução")

# Carregar trace de uma execução específica
trace = pd.read_csv("/tmp/simple_python_audit_perf/AUDIT_meu_metodo_lento_1234567890_trace.csv")
trace.sort_values("total_time_s", ascending=False).head(10)

---

🌐 Relatório HTML (html=True)

Gera um arquivo AUDIT_{func}_{timestamp}.html com um widget flutuante interativo contendo:

• Painel de rastreamento (🚀): tabela de chamadas de função com busca em tempo real
• Painel de métricas (📊): cards de CPU e memória, tabelas de CPU e memória por função

---

🛠️ Servidor de Auditoria

Interface web para visualizar e gerenciar os arquivos de relatório gerados.

# Via linha de comando
simple-python-audit-server --port 8080 --dir /tmp/simple_python_audit_perf

# Via Python
from simple_python_audit import start_server
start_server(port=8080, directory="/tmp/simple_python_audit_perf")

---

🔗 Integração com Odoo

Ao instalar em um ambiente com Odoo, o decorador profile é injetado automaticamente em odoo.api:

from odoo import api

@api.profile(html=True, trace=True, print_terminal=True, save_csv=True)
def action_processar(self):
    ...