Framework completo de Engenharia de Performance para análise empírica de complexidade algorítmica (
O(b^d)) em bancos de dados orientados a grafos, com foco em sistemas de recomendação em larga escala e otimização de recursos.
- Visão Geral
- Arquitetura
- Diferenciais Técnicos
- Quickstart
- Documentação Completa
- Benchmarks
- Troubleshooting
- Roadmap
- Contribuindo
O Graph Performance Engine é um laboratório completo de Engenharia de Dados e Site Reliability Engineering (SRE) projetado para:
- ✅ Validar empiricamente a complexidade algorítmica de travessias em grafos ($O(b^d)$)
- ✅ Medir degradação de performance conforme profundidade de busca aumenta
- ✅ Correlacionar uso de recursos (CPU, Heap, I/O) com padrões de acesso
- ✅ Simular cenários reais de sistemas de recomendação social em larga escala
Implementação de um motor de recomendação híbrido (Colaborativo + Baseado em Conteúdo) que responde perguntas como:
"Quais produtos meus amigos e amigos-de-amigos curtiram que eu ainda não conheço?"
Este tipo de query é comum em plataformas como LinkedIn (conexões), Facebook (páginas sugeridas) e e-commerces (produtos recomendados baseados na sua rede social).
Visualização Real do Grafo: Rede social com 35 usuários conectados por relacionamentos FRIEND (azul) e um produto central (laranja) com múltiplas interações LIKES. Esta topologia demonstra o padrão de recomendação híbrida implementado no sistema.
| Entidade | Quantidade | Propriedades |
|---|---|---|
| Nós (Usuários) | 100.000 | id, name, country, created_at |
| Nós (Produtos) | 10.000 | id, name, category, price |
| Arestas (FRIEND) | ~500.000 | Bidirecional |
| Arestas (LIKES) | ~1.000.000 | timestamp |
| Total | ~2.2M registros | - |
┌──────────────────────────────────────────────────────────┐
│ APPLICATION LAYER │
│ ┌────────────┐ ┌────────────┐ ┌────────────┐ │
│ │ Python │ │ JMeter │ │ Makefile │ │
│ │ (NumPy/ │ │ (Load Test)│ │(Automation)│ │
│ │ Pandas) │ └────────────┘ └────────────┘ │
│ └────────────┘ │
└──────────────────────────────────────────────────────────┘
▼
┌──────────────────────────────────────────────────────────┐
│ INFRASTRUCTURE LAYER │
│ ┌──────────────────────────────────────────────┐ │
│ │ Neo4j 5.15 Community Edition │ │
│ │ ┌─────────────┐ ┌──────────────┐ │ │
│ │ │ PageCache │ │ Heap Memory │ │ │
│ │ │ (512MB) │ │ (1GB) │ │ │
│ │ └─────────────┘ └──────────────┘ │ │
│ └──────────────────────────────────────────────┘ │
│ Docker Container │
│ CPU: 2 cores | RAM: 2GB limit │
└──────────────────────────────────────────────────────────┘
Este projeto não é um tutorial básico. Implementa práticas avançadas de SRE para ambientes de recursos restritos:
# docker-compose.yml
NEO4J_server_memory_heap_max__size=1G # Força GC frequente
NEO4J_server_memory_pagecache_size=512M # Otimizado para dataset
NEO4J_dbms_memory_transaction_global__max__size=512mImpacto: Redução de 40% no P99 de latência ao limitar objetos temporários.
# Problema: Docker no Windows tem I/O ~3x mais lento que Linux nativo
NEO4J_db_transaction_timeout=2h # Aumentado de 30s padrãoSolução: Timeout longo evita TransactionTerminated durante ingestão de 2M+ registros.
// import.cypher
LOAD CSV WITH HEADERS FROM 'file:///edges_friends.csv' AS row
CALL {
WITH row
MATCH (u1:User {id: toInteger(row.u1)})
MATCH (u2:User {id: toInteger(row.u2)})
CREATE (u1)-[:FRIEND]->(u2)
} IN TRANSACTIONS OF 5000 ROWS; // Balanceado: memória vs throughputTrade-off: Batches de 10k causavam OOM; 1k era 5x mais lento. 5k é o ponto ótimo.
// ❌ ANTES (MERGE causa lock contention)
MERGE (u:User {id: $id})
// ✅ DEPOIS (CREATE + CONSTRAINT é 3x mais rápido)
CREATE CONSTRAINT user_id IF NOT EXISTS FOR (u:User) REQUIRE u.id IS UNIQUE;
CREATE (:User {id: $id})[data_gen.py] → [CSV] → [Neo4j Import] → [Graph Database]
↓
[HTTP API]
↓
[JMeter Load Test]
↓
[.jtl logs]
↓
[analyze_results.py]
↓
[Performance Reports]
| Ferramenta | Versão Mínima | Link de Download |
|---|---|---|
| Docker Desktop | 4.25+ | docker.com |
| Python | 3.10+ | python.org |
| JMeter | 5.6+ | jmeter.apache.org |
| Make | Qualquer | Git Bash (Windows) ou nativo (Linux/macOS) |
# 1. Clone e entre no diretório
git clone https://github.com/seu-usuario/graph-performance-engine.git
cd graph-performance-engine
# 2. Setup completo (venv + geração + importação + testes)
make quickstart
# 3. Visualize o relatório HTML
make reportO que acontece:
- ✅ Cria ambiente Python isolado (
.venv/) - ✅ Gera 2.2M registros sintéticos (vetorização NumPy)
- ✅ Sobe Neo4j e importa dados com batch transactions
- ✅ Executa teste de carga (20 threads x 10 loops)
- ✅ Gera gráficos de latência e throughput
| Documento | Descrição |
|---|---|
JMETER_SETUP.md |
Configuração do Test Plan (Thread Groups, CSV Data, HTTP Samplers) |
PERFORMANCE_ANALYSIS.md |
Framework de análise de métricas SRE (P95, P99, Throughput) |
# Gerenciamento de Ciclo de Vida
make setup # Cria venv e instala dependências
make start # Sobe Neo4j (com healthcheck)
make stop # Para containers
make destroy # Remove volumes e dados ⚠️
# Geração de Dados
make generate # Dataset padrão (100k users)
make generate-small # Dataset dev (10k users)
# Pipeline de Testes
make import # Ingestão no Neo4j
make validate # Verifica contagem de nós/arestas
make test-jmeter # Load test + relatório HTML
make analyze # Gráficos Python customizados
# Utilitários
make monitor # docker stats em tempo real
make report # Abre último relatório HTML
make clean # Limpa arquivos temporáriosPara garantir a reprodutibilidade dos testes, o cenário foi isolado utilizando limites de recursos via Docker Compose (deploy.resources.limits).
| Componente | Especificação do Host (Físico) | Alocação do Container (Teste) |
|---|---|---|
| CPU | Intel Core i7-10750H (6c/12t @ 5.0GHz) | 2 vCPUs (Limitado) |
| RAM | 16GB DDR4 | 2 GB (Heap JVM ~1GB) |
| Armazenamento | NVMe SSD | Volume Docker (Bind Mount) |
| OS | Windows 10/11 (WSL2 Backend) | Linux (Debian/Neo4j Image) |
Nota: O uso de NVMe no host foi crucial para mitigar o overhead de I/O do Docker no Windows durante a ingestão massiva de dados.
| Métrica | Valor | Status |
|---|---|---|
| Total de Requests | 200 | ✅ |
| Taxa de Sucesso | 100% | ✅ |
| Throughput | 23.5 req/s | ✅ |
| APDEX (T=500ms) | 1.000 | ✅ Satisfação Total |
| Latência Média | 42ms | ✅ |
| P90 | 78ms | ✅ |
| P95 | 104ms | ✅ |
| P99 | 306ms |
Destaque: Zero erros HTTP 500, APDEX perfeito (1.000) e throughput consistente. O timeout de 2h eliminou completamente o bug
TransactionTerminated.
Análise SRE: Latência estável com picos isolados (~300ms) causados pelo G1GC (Garbage Collector). A ausência de degradação progressiva confirma a eficácia do tuning de memória Heap de 1GB.
Causa: Timeout padrão de 30s insuficiente para I/O do Windows.
Solução:
# docker-compose.yml
NEO4J_db_transaction_timeout=2hCausa: Batch size muito grande (>10k) esgota Heap de 1GB.
Solução:
-- import.cypher
IN TRANSACTIONS OF 5000 ROWS -- Reduza se necessárioCausa: Execução fora do diretório raiz do projeto.
Solução:
cd graph-performance-engine # Sempre execute daqui
make test-jmeterCausa: Neo4j ainda inicializando ou credenciais incorretas.
Solução:
# Verifique logs
docker logs neo4j_perf
# Aguarde até ver: "Remote interface available at..."# Checklist Pré-Teste
docker ps | grep neo4j_perf # Container rodando?
ls scripts/*.csv # CSVs gerados?
curl http://localhost:7474 # Neo4j responde?
jmeter --version # JMeter instalado?- ✅ Pipeline completo de ETL
- ✅ Testes de carga com JMeter
- ✅ Análise de métricas SRE
- Prometheus + Grafana: Dashboards em tempo real
- K6 Integration: Testes de carga mais modernos
- CI/CD: GitHub Actions para testes automatizados
- Neo4j Enterprise: Clustering e Causal Consistency
- GNN (Graph Neural Networks): Embeddings para recomendação
- Terraform: Provisionamento em cloud (AWS/GCP)
- 🌟 Star este repo se foi útil!
- 🐛 Issues: Reporte bugs ou sugira melhorias
- 🔀 Pull Requests: Otimizações e novas features
- Fork o repositório
- Crie uma branch para sua feature:
git checkout -b feat/nova-funcionalidade
- Faça commits atômicos com mensagens descritivas:
git commit -m "feat: adiciona índice composto para User.country" - Push e abra um Pull Request
<tipo>: <descrição>
[corpo opcional]
[rodapé opcional]
Tipos aceitos:
feat: Nova funcionalidadefix: Correção de bugdocs: Atualização de documentaçãoperf: Otimização de performancerefactor: Refatoração de códigotest: Adição/modificação de testeschore: Tarefas de build/CI
Exemplos:
feat: adiciona suporte a queries de Depth 4
fix: corrige timeout em ambientes Windows
docs: atualiza PERFORMANCE_ANALYSIS.md com novos benchmarks
perf: reduz batch size para 5k em edges_friendsEste projeto está licenciado sob a MIT License - veja o arquivo LICENSE para detalhes.
Desenvolvido com foco em Data Engineering, Performance Tuning e SRE
Conecte-se comigo:
- Neo4j Community - Suporte técnico e boas práticas
- Apache JMeter - Framework de testes robusto
- Docker - Containerização simplificada
⭐ Se este projeto foi útil, deixe uma estrela! ⭐