7.9 KiB
7.9 KiB
📚 Referência Técnica
Stack de Tecnologias
| Componente | Tecnologia | Versão | Função |
|---|---|---|---|
| API | Python Flask | 2.3.3 | Servidor HTTP |
| Web Server | Gunicorn | 21.2.0 | WSGI HTTP Server |
| HTTP Client | Requests | 2.31.0 | Cliente HTTP |
| Configuration | python-dotenv | 1.0.0 | Gerenciar variáveis de env |
| Metrics | prometheus-client | 0.17.1 | Exporte de métricas |
| Container | Docker | latest | Containerização |
| Orchestration | Docker Compose | 3.8 | Orquestração |
| Monitoring | Prometheus | latest | Time series DB |
| Visualization | Grafana | latest | Dashboards |
Arquitetura de Arquivos
monitoramento_atendimento/
├── src/
│ ├── app.py # Flask app principal
│ ├── api_client.py # Cliente PersonalizeIT API
│ ├── data_formatter.py # Formatting dados em 3 formatos
│ └── config.py # Gerenciar configurações
│
├── config/
│ └── .env.example # Template de env vars
│
├── grafana/
│ └── provisioning/
│ ├── datasources/ # Config datasources
│ │ └── datasources.yml
│ └── dashboards/ # Config dashboards
│ ├── dashboard-provider.yml
│ └── monitoring-dashboard.json
│
├── docker-compose.yml # Orquestração 3 containers
├── Dockerfile # Build da app Python
├── prometheus.yml # Config Prometheus
├── requirements.txt # Dependências Python
├── .gitignore # Git ignore config
├── .env.local # Variaveis locais (exemplo)
│
├── README.md # Documentação principal
├── QUICKSTART.md # Início rápido 3 passos
├── INSTALL.md # Guia de instalação
├── ARCHITECTURE.md # Explicação arquitetura
├── EXAMPLES.md # Exemplos de uso
└── TROUBLESHOOTING.md # Debug & FAQ
Environment Variables
# API Configuration
API_BASE_URL=https://api-personalizeit.zapplataforma.chat
API_LOGIN_ENDPOINT=/auth/login
API_TICKETS_ENDPOINT=/tickets
# Credentials (REQUIRED)
API_USERNAME=seu_email@exemplo.com
API_PASSWORD=sua_senha
# Flask Config
FLASK_PORT=5000
FLASK_HOST=0.0.0.0
DEBUG=False
# Refresh interval (seconds)
REFRESH_INTERVAL=30
# Queue IDs (comma-separated)
QUEUE_IDS=-1,1,2,3,4,5,7
Endpoints REST
| Método | Path | Resposta | Uso |
|---|---|---|---|
| GET | / | JSON status | Verificar app |
| GET | /health | JSON health | Health check |
| GET | /api/tickets | JSON tickets | Grafana JSON DS |
| GET | /api/summary | JSON stats | Resumo dados |
| GET | /api/timeseries | JSON time series | Time series |
| GET | /metrics | Text Prometheus | Prometheus scrape |
Fluxo de Requisição
1. Cliente HTTP (Grafana/curl)
↓
2. Flask app.py
- Recebe GET request
- Chama update_tickets()
↓
3. APIClient.login()
- POST /auth/login
- Recebe bearer token
- Configura header Authorization
↓
4. APIClient.get_all_tickets()
- GET /tickets com params
- Loop por páginas
- Junta resultados
↓
5. DataFormatter.*()
- Formata conforme tipo
- JSON / Prometheus / TimeSeries
↓
6. Flask app.py
- Retorna response formatada
- Content-Type apropriado
↓
7. Cliente recebe dados
- JSON → Parse browser/Grafana
- Prometheus → Prometheus scrape
Cache Strategy
# Em app.py
last_update = None
cached_tickets = []
cached_json = None
cached_metrics = None
CACHE_DURATION = timedelta(seconds=Config.REFRESH_INTERVAL)
# Lógica:
if last_update is None or (now - last_update) > CACHE_DURATION:
# Atualizar do servidor
# Refrescar cache
last_update = now
else:
# Retornar cache
Error Handling
try:
# Fazer algo
response = requests.get(url)
except requests.exceptions.RequestException as e:
# Log erro
logger.error(f"Error: {str(e)}")
except Exception as e:
# Log error genérico
logger.error(f"Unexpected error: {str(e)}")
finally:
# Cleanup if needed
Docker Compose Services
services:
monitoring-api:
image: Python 3.11
ports: 5000:5000
env_file: .env
networks: monitoring
grafana:
image: grafana/grafana:latest
ports: 3000:3000
volumes: grafana-storage
networks: monitoring
depends_on: monitoring-api
prometheus:
image: prom/prometheus:latest
ports: 9090:9090
volumes: prometheus-storage
networks: monitoring
depends_on: monitoring-api
Prometheus Scrape Config
scrape_configs:
- job_name: 'monitoring-api'
static_configs:
- targets: ['monitoring-api:5000']
metrics_path: '/metrics'
scrape_interval: 30s
Métricas Prometheus Expostas
ticket_duration_seconds{ticket_id="...", contact_name="...", status="...", queue="..."} <valor>
tickets_total <número>
ticket_duration_seconds_avg <número>
Grafana Datasources
JSON API
- Type: JSON API
- URL: http://monitoring-api:5000
- Method: GET
- Query format: JSON
Prometheus
- Type: Prometheus
- URL: http://prometheus:9090
- Access: Server
Performance Characteristics
| Métrica | Valor | Notas |
|---|---|---|
| Latência API | < 500ms | Com cache |
| Atualização dados | 30s | Configurável |
| Consumo memória | ~150MB | Grafana + API |
| Espaço storage | Mínimo | Sem DB persistência |
| Concorrência | 4 workers | Gunicorn configurável |
| Max tickets | 1000+ | Depende de endpoints |
Segurança
HTTPS/TLS
- SSL verificado em api_client.py
- Adicionar proxy reverso para Grafana
Authentication
- Bearer token na API PersonalizeIT
- Admin credentials Grafana (alterar padrão)
Data Protection
- .env não versionado
- Variáveis de ambiente isoladas
- Logs não expõem senhas
Logging
Nível INFO (padrão)
2026-02-09 12:30:00,000 - api_client - INFO - Successfully authenticated
2026-02-09 12:30:01,000 - api_client - INFO - Successfully fetched tickets
Nível DEBUG (com DEBUG=True)
2026-02-09 12:30:00,000 - api_client - DEBUG - Request URL: ...
2026-02-09 12:30:00,500 - api_client - DEBUG - Response: {"tickets": [...]}
Testing
# Unit test exemplo
import unittest
from api_client import APIClient
class TestAPIClient(unittest.TestCase):
def test_login(self):
client = APIClient()
assert client.login() == True
assert client.token is not None
CI/CD
GitHub Actions (exemplo)
name: Test
on: [push]
jobs:
test:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v2
- name: Run tests
run: python -m pytest
- name: Build Docker
run: docker build .
Backup & Recovery
Dados Grafana
# Backup
docker-compose exec grafana grafana-cli admin export-dashboard --file /backup/dashboard.json
# Restore
docker-compose exec grafana grafana-cli admin import-dashboard --from /backup/dashboard.json
Dados Prometheus
# Backup
docker cp prometheus:/prometheus /backup/prometheus-data
# Restore
docker cp /backup/prometheus-data prometheus:/prometheus
Troubleshooting Checklist
- Docker rodando (
docker ps) - .env configurado
- API PersonalizeIT acessível
- Credenciais válidas
- Portas não em uso (3000, 5000, 9090)
- Volumes com espaço
- Network docker criada
- Logs sem erros críticos