django-dev-insights 0.2.0

Real-time performance insights for Django development.

django-dev-insights

Insights de performance em tempo real, direto no seu terminal.

django-dev-insights é um middleware leve para Django que fornece um diagnóstico claro e imediato sobre a performance de cada requisição durante o desenvolvimento. Ele foi projetado para ser simples, não intrusivo e focado em expor os gargalos mais comuns: queries de banco de dados excessivas, duplicadas e lentas.

O Problema que Resolvemos

Em um projeto Django real, uma única página pode, sem querer, gerar dezenas ou centenas de queries ao banco de dados, resultando em tempos de carregamento de vários segundos. django-dev-insights foi criado e validado em um cenário de produção complexo, onde ajudou a:

• Reduzir o tempo de carregamento de uma página de 28 segundos para 3.8 segundos ao identificar e eliminar mais de 200 queries duplicadas.
• Otimizar uma página de 8 segundos para 1.8 segundos ao diagnosticar um problema de N+1 que só era visível com um grande volume de dados.

Esta ferramenta te dá os dados para transformar performance de "lenta" para "rápida".

Instalação

1. Instale o pacote via pip:

   pip install django-dev-insights
   

2. Adicione colorama, que é usado para a saída colorida no console:

   pip install colorama
   

Configuração Rápida

Para começar a usar, adicione o middleware ao seu arquivo settings.py. É crucial que ele seja o primeiro na sua lista de MIDDLEWARE para garantir que ele meça o ciclo de vida completo da requisição.

django-dev-insights

Insights de performance em tempo real, direto no seu terminal (focado para desenvolvimento).

django-dev-insights \x00e9 um middleware leve para Django que fornece diagn\x00f3sticos por requisi\x00e7\x00e3o: tempo total, queries ao DB, queries duplicadas (N+1), queries lentas e mais. Foi projetado para ser simples, n\x00e3o intrusivo e configur\x00e1vel.

Principais features recentes

• v0.4.0: ConnectionCollector — detecta queries de setup (ex.: SET search_path, SELECT VERSION) por conex\x00e3o e aponta reaberturas de conex\x00e3o.
• v0.5.0: Tracebacks — captura stack traces para queries lentas/duplicadas/setup (opcional, ativado via configura\x00e7\x00e3o).

Essas features juntam informa\x00e7\x00f5es que permitem localizar n\x00e3o apenas "o que" est\x00e1 lento, mas tamb\x00e9m "de onde" vem a query no c\x00f3digo.

Instala\x00e7\x00e3o

1. Instale via pip:

pip install django-dev-insights

2. (Opcional) colorama \x00e9 usado para sa\x00edda colorida:

pip install colorama

Configura\x00e7\x00e3o r\x00e1pida

Adicione o middleware em settings.py. Para medir o ciclo completo da requisi\x00e7\x00e3o, posicione-o antes de middlewares que voc\x00ea quer observar. Se usa django-tenants, garanta que o Tenant middleware venha antes (veja abaixo).

# settings.py
MIDDLEWARE = [
    'dev_insights.middleware.DevInsightsMiddleware',
    # ... outros middlewares
]

Rode o servidor de desenvolvimento (python manage.py runserver) e voc\x00ea ver\x00e1 relat\x00f3rios por requisi\x00e7\x00e3o no terminal.

Como ler a sa\x00edda

Exemplo de sa\x00edda (resumida):

[DevInsights] Path: /usuarios/45 | Tempo Total: 4821.37ms | DB Queries: 36 | DB Tempo: 4120.5ms | !! DUPLICATAS: 12 !!
    [Duplicated SQLs]:
      -> (4x) SELECT ...
         Traceback:
         path/to/your/file.py:123 in some_view -> model.objects.filter(...)
    [Slow Queries (> 500ms)]:
      -> [732.1ms] SELECT ...
         Traceback:
         path/to/your/other.py:45 in slow_fn -> queryset
    [Connection Setup Queries]:
      -> default: 3 setup queries
         - SET search_path = 'clientschema','public'
           Traceback: path/to/middleware.py:30 in process_request -> set_tenant(...)

As linhas principais s\x00e3o coloridas (verde/amarelo/vermelho) conforme limites configur\x00e1veis.

Configura\x00e7\x00f5es dispon\x00edveis

Adicione DEV_INSIGHTS_CONFIG em settings.py para personalizar comportamentos. Exemplo com as op\x00e7\x00f5es mais relevantes:

DEV_INSIGHTS_CONFIG = {
    'THRESHOLDS': {
        'total_time_ms': {'warn': 1000, 'crit': 3000},
        'query_count': {'warn': 20, 'crit': 50},
        'duplicate_query_count': {'warn': 5, 'crit': 10},
    },
    'SLOW_QUERY_THRESHOLD_MS': 100,   # ms
    'ENABLE_TRACEBACKS': False,       # ativar captura de stack traces (DEBUG apenas)
    'TRACEBACK_DEPTH': 5,             # profundidade do traceback
    'ENABLED_COLLECTORS': ['db', 'connection'],  # quais coletores rodar
}

Notas importantes:

• ENABLE_TRACEBACKS deve ficar False por padr\x00e3o; habilite somente em desenvolvimento porque captura/format de stack aumenta o overhead.
• ENABLED_COLLECTORS permite desabilitar o ConnectionCollector se voc\x00ea n\x00e3o quiser relatar queries de setup.

Integra\x00e7\x00e3o com django-tenants / multi-tenant

Se seu projeto usa django-tenants (ou outra solu\x00e7\x00e3o por schemas), voc\x00ea provavelmente ver\x00e1 SQLs como SET search_path ... no log. Boas pr\x00e1ticas:

• Coloque o tenant middleware antes de qualquer middleware que acesse o DB (sessions, auth). Exemplo:

MIDDLEWARE = [
    'django_tenants.middleware.main.TenantMainMiddleware',
    'dev_insights.middleware.DevInsightsMiddleware',
    'django.middleware.security.SecurityMiddleware',
    'django.contrib.sessions.middleware.SessionMiddleware',
    'django.contrib.auth.middleware.AuthenticationMiddleware',
    # ...
]

• Se voc\x00ea ainda ver SET search_path repetido, habilite ENABLE_TRACEBACKS temporariamente para localizar o ponto do c\x00f3digo que est\x00e1 chamando a troca de schema.

Diagn\x00f3stico R\x00e1pido

• Habilite ENABLE_TRACEBACKS e TRACEBACK_DEPTH alto, reproduza a requisi\x00e7\x00e3o e observe o traceback que aponta para o arquivo/linha que disparou a SQL.
• Alternativamente, use um patch tempor\x00e1rio que loga stack imediatamente ao detectar SQLs contendo search_path (recomendado para investiga\x00e7\x00f5es locais curtas).

Boas pr\x00e1ticas

• Use DevInsights apenas com DEBUG = True (padr\x00e3o) — a coleta de queries depende de connection.queries do Django.
• Desabilite tracebacks e coletores quando n\x00e3o estiver depurando para reduzir overhead.

Contribui\x00e7\x00f5es

Contribui\x00e7\x00f5es s\x00e3o bem-vindas. Abra issues para bugs/feature requests ou pull requests com pequenas melhorias (tests, docs, coletores adicionais).