commit 52791b718ccf06f61397a80d9c7e05fa73688b24 Author: luiscarlosjp Date: Mon Feb 9 17:14:40 2026 -0300 first commit diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..0371319 --- /dev/null +++ b/.gitignore @@ -0,0 +1,43 @@ +.env +.env.local +.env*.local +__pycache__/ +*.py[cod] +*$py.class +*.so +.Python +build/ +develop-eggs/ +dist/ +downloads/ +eggs/ +.eggs/ +lib/ +lib64/ +parts/ +sdist/ +var/ +wheels/ +pip-wheel-metadata/ +share/python-wheels/ +*.egg-info/ +.installed.cfg +*.egg +MANIFEST +.vscode/ +.idea/ +*.log +node_modules/ +.DS_Store +*.swp +*.swo +*~ +.venv +venv/ +ENV/ +env/ +.cache/ +*.sqlite +*.db +.coverage +htmlcov/ diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md new file mode 100644 index 0000000..51f99b3 --- /dev/null +++ b/ARCHITECTURE.md @@ -0,0 +1,136 @@ +# 🏗️ Arquitetura + +## Fluxo de Dados + +``` +PersonalizeIT API + ↓ + (login) + ↓ + API Client + (bearer token) + ↓ +(busca tickets) + ↓ +PersonalizeIT API + (tickets) + ↓ +Data Formatter + ↓ + ┌──────────┬──────────┐ + ↓ ↓ ↓ + JSON Prometheus TimeSeries + ↓ ↓ ↓ + (JSON) (Metrics) (TS) + ↓ ↓ ↓ + └────────┬─────────┘ + ↓ + Flask API + ↓ ↓ + JSON Prometheus + API Endpoint + ↓ ↓ + ┌──────┬──────┐ + ↓ ↓ ↓ +Grafana Prom Bash + ↓ ↓ Scripts + Dash Alert + ↓ ↓ + UI Notifi- + cações + +``` + +## Componentes + +### 📡 API Client (`api_client.py`) +- Autenticação na PersonalizeIT API +- Gerenciamento baseado em bearer token +- Busca de tickets com filtros +- Tratamento de erros e retry + +### 🔄 Data Formatter (`data_formatter.py`) +- Formata dados em 3 formatos: + - **JSON**: Para datasources JSON do Grafana + - **Prometheus**: Métricas no padrão Prometheus + - **TimeSeries**: Dados agregados por tempo + +### 🌐 Flask App (`app.py`) +Endpoints principais: +- `GET /` - Status +- `GET /health` - Health check +- `GET /api/tickets` - Tickets em JSON +- `GET /metrics` - Métricas Prometheus +- `GET /api/summary` - Resumo estatístico +- `GET /api/timeseries` - Série temporal + +### 📊 Grafana +- Visualização dos dados +- 2 Datasources: + - Prometheus (para gráficos) + - JSON API (para tabelas) +- Dashboard pré-configurado + +### 🔥 Prometheus +- Scraping de métricas +- Storage de time series +- Alerting baseado em regras + +## Configuração + +``` +.env +├── API_BASE_URL +├── API_USERNAME +├── API_PASSWORD +├── FLASK_PORT +├── REFRESH_INTERVAL +└── QUEUE_IDS +``` + +## Cache e Refresh + +- **Refresh Interval**: Por padrão 30s (configurável em .env) +- **Cache**: Dados em memória entre requisições +- **Atualização**: Automática na primeira requisição após expiração + +## Escalabilidade + +Para produção: + +``` +┌─────────────────────────┐ +│ Reverse Proxy │ +│ (nginx/caddy) │ +└────────────┬────────────┘ + ↓ +┌─────────────────────────┐ +│ Load Balancer │ +└────────────┬────────────┘ + ┌──────┴──────┐ + ↓ ↓ + [Api 1] [Api 2] + ↓ ↓ + └──────┬──────┘ + ↓ + Redis Cache + ↓ + PostgreSQL DB + (histórico opcional) +``` + +## Segurança + +- ✅ SSL/TLS para conexão com API +- ✅ Bearer token para autenticação +- ✅ Senhas em variáveis de ambiente (.env) +- ✅ Health checks automáticos +- ✅ Timeout em requisições + +## Monitoramento + +O próprio sistema pode ser monitorado com: +- Status HTTP endpoints +- Logs estruturados +- Prometheus metrics da app +- Health checks do Docker diff --git a/Dockerfile b/Dockerfile new file mode 100644 index 0000000..1e0638b --- /dev/null +++ b/Dockerfile @@ -0,0 +1,29 @@ +FROM python:3.11-slim + +WORKDIR /app + +# Install system dependencies +RUN apt-get update && apt-get install -y \ + curl \ + gcc \ + && rm -rf /var/lib/apt/lists/* + +# Copy requirements +COPY requirements.txt . + +# Install Python dependencies +RUN pip install --no-cache-dir -r requirements.txt + +# Copy application +COPY src/ . +COPY config/.env* ./ + +# Expose port +EXPOSE 5000 + +# Health check +HEALTHCHECK --interval=30s --timeout=10s --start-period=40s --retries=3 \ + CMD curl -f http://localhost:5000/health || exit 1 + +# Run application +CMD ["gunicorn", "--bind", "0.0.0.0:5000", "--workers", "4", "--timeout", "120", "app:app"] diff --git a/EXAMPLES.md b/EXAMPLES.md new file mode 100644 index 0000000..98de4b1 --- /dev/null +++ b/EXAMPLES.md @@ -0,0 +1,273 @@ +# 🔍 Exemplos de Uso + +## API REST da Aplicação + +### 1. Verificar Status +```bash +curl -X GET http://localhost:5000/ +``` + +**Resposta:** +```json +{ + "status": "running", + "version": "1.0.0", + "timestamp": "2026-02-09T12:30:00.000000", + "endpoints": { + "health": "/health", + "json": "/api/tickets", + "prometheus": "/metrics", + "timeseries": "/api/timeseries" + } +} +``` + +### 2. Health Check +```bash +curl -X GET http://localhost:5000/health +``` + +**Resposta:** +```json +{ + "status": "healthy", + "cached_tickets": 10, + "last_update": "2026-02-09T12:30:00.000000" +} +``` + +### 3. Buscar Tickets (JSON) +```bash +curl -X GET http://localhost:5000/api/tickets | jq '.' +``` + +**Resposta (reformatada):** +```json +{ + "timestamp": "2026-02-09T12:30:00.000000", + "total_tickets": 10, + "tickets": [ + { + "id": 26459, + "contact_name": "Júlia Donelli", + "duration_seconds": 56, + "duration_formatted": "00:00:56", + "status": "pending", + "queue": "EQUIPAMENTO EM MANUTENÇÃO", + "contact_number": "555199448030", + "created_at": "2026-02-09T12:13:11.000Z", + "updated_at": "2026-02-09T12:14:07.000Z", + "whatsapp_name": "PersonalizeIT" + } + ] +} +``` + +### 4. Resumo Estatístico +```bash +curl -X GET http://localhost:5000/api/summary | jq '.' +``` + +**Resposta:** +```json +{ + "total_tickets": 10, + "average_duration_seconds": 1234.5, + "max_duration_seconds": 1651623, + "min_duration_seconds": 56, + "total_duration_seconds": 12345, + "timestamp": "2026-02-09T12:30:00.000000", + "contacts": [ + "Júlia Donelli", + "Atendimento Grafica Almeida", + "ADICOM POLYTEK" + ] +} +``` + +### 5. Métricas Prometheus +```bash +curl -X GET http://localhost:5000/metrics +``` + +**Resposta:** +``` +# HELP ticket_duration_seconds Duration of ticket in seconds +# TYPE ticket_duration_seconds gauge +ticket_duration_seconds{ticket_id="26459",contact_name="Júlia Donelli",status="pending",queue="EQUIPAMENTO EM MANUTENÇÃO"} 56 +ticket_duration_seconds{ticket_id="26363",contact_name="Atendimento Grafica Almeida",status="pending",queue="EQUIPAMENTO EM MANUTENÇÃO"} 15003 + +# HELP tickets_total Total number of pending tickets +# TYPE tickets_total gauge +tickets_total 10 + +# HELP ticket_duration_seconds_avg Average ticket duration in seconds +# TYPE ticket_duration_seconds_avg gauge +ticket_duration_seconds_avg 1234.50 +``` + +### 6. Série Temporal +```bash +curl -X GET http://localhost:5000/api/timeseries | jq '.' +``` + +## Queries do Grafana + +### Com Prometheus Datasource + +**Todos os tickets por contato:** +```promql +ticket_duration_seconds +``` + +**Média de duração:** +```promql +avg(ticket_duration_seconds) +``` + +**Máximo por contato (últimas 5 min):** +```promql +max_over_time(ticket_duration_seconds[5m]) +``` + +**Total de tickets:** +```promql +tickets_total +``` + +**Tickets demorados (mais de 1 hora = 3600 segundos):** +```promql +ticket_duration_seconds > 3600 +``` + +### Com JSON API Datasource + +**Todos os tickets:** +```json +{ + "data": "tickets" +} +``` + +**Apenas resumo:** +```json +{ + "data": "total_tickets" +} +``` + +## Python requests + +```python +import requests + +# URL base +BASE_URL = "http://localhost:5000" + +# 1. Health check +response = requests.get(f"{BASE_URL}/health") +print(response.json()) + +# 2. Buscar tickets +response = requests.get(f"{BASE_URL}/api/tickets") +tickets = response.json()["tickets"] +for ticket in tickets: + print(f"{ticket['contact_name']}: {ticket['duration_formatted']}") + +# 3. Resumo +response = requests.get(f"{BASE_URL}/api/summary") +summary = response.json() +print(f"Total: {summary['total_tickets']}") +print(f"Média: {summary['average_duration_seconds']:.2f}s") +print(f"Máximo: {summary['max_duration_seconds']}s") + +# 4. Processar métricas Prometheus +response = requests.get(f"{BASE_URL}/metrics") +print(response.text) +``` + +## Bash scripts + +### Monitorar atendimentos +```bash +#!/bin/bash + +while true; do + clear + echo "=== Monitoramento de Atendimento ===" + echo "" + curl -s http://localhost:5000/api/summary | jq '.tickets[] | "\(.contact_name): \(.duration_formatted)"' + echo "" + sleep 30 +done +``` + +### Enviar para webhook +```bash +#!/bin/bash + +# Buscar dados +DATA=$(curl -s http://localhost:5000/api/summary) + +# Enviar para webhook +curl -X POST \ + -H 'Content-Type: application/json' \ + -d "$DATA" \ + https://seu-webhook.com/monitoramento +``` + +## Integração com Ferramentas Externas + +### Slack Alertas +```bash +# Via Grafana Notification Channel +# Grafana → Alerts → Notification channels → Slack +# Mensagem quando tempo > 1 hora +``` + +### PagerDuty +```bash +# Via Prometheus alertas +# Crie arquivo alerts.yml: +groups: + - name: tickets + rules: + - alert: AtendimentoDemorado + expr: ticket_duration_seconds > 3600 + for: 5m +``` + +### Email +```bash +# Configure notificações no Grafana +# Grafana → Alerts → Notification channels → Email +``` + +## Debug + +### Ver logs em tempo real +```bash +docker-compose logs -f monitoring-api +``` + +### Testar conectividade com API PersonalizeIT +```bash +curl -X POST \ + -H 'Content-Type: application/json' \ + -d '{"email":"seu@email.com","password":"sua_senha"}' \ + https://api-personalizeit.zapplataforma.chat/auth/login +``` + +### Verificar variáveis de ambiente +```bash +docker-compose exec monitoring-api env | grep API +``` + +### Acessar console do container +```bash +docker-compose exec monitoring-api /bin/bash +python3 +>>> from api_client import APIClient +>>> client = APIClient() +>>> client.login() +``` diff --git a/INSTALL.md b/INSTALL.md new file mode 100644 index 0000000..fb3cc11 --- /dev/null +++ b/INSTALL.md @@ -0,0 +1,151 @@ +# 📦 Guia de Instalação + +## ⚙️ Pré-requisitos + +- Docker Desktop (com Docker Compose incluído) +- Linux, macOS ou Windows WSL2 +- Credenciais válidas para a API PersonalizeIT + +## 🚀 Instalação Rápida (3 passos) + +### Passo 1: Configurar Credenciais + +```bash +# Abra o arquivo .env +nano .env +``` + +Edite com suas credenciais: +```env +API_USERNAME=seu_email@exemplo.com +API_PASSWORD=sua_senha +``` + +### Passo 2: Iniciar os Serviços + +```bash +# Dar permissão de execução aos scripts +chmod +x setup.sh test-api.sh + +# Executar setup (opcional, mas recomendado) +./setup.sh + +# Ou iniciar diretamente +docker-compose up -d +``` + +### Passo 3: Acessar os Serviços + +- **Grafana**: http://localhost:3000 (admin/admin) +- **API**: http://localhost:5000 +- **Prometheus**: http://localhost:9090 + +## 🧪 Verificar Funcionamento + +```bash +# Testar a API +./test-api.sh + +# Ou manualmente +curl http://localhost:5000/health +curl http://localhost:5000/api/summary +``` + +## 🛑 Parar os Serviços + +```bash +docker-compose down +``` + +## 🚪 Configurar Datasource no Grafana + +### Opção A: JSON Datasource (Para Tabelas) + +1. Grafana → Configuration → Data Sources → Add data source +2. Selecione "JSON API" +3. URL: `http://monitoring-api:5000` +4. Click "Save & Test" + +### Opção B: Prometheus (Para Gráficos) + +1. Grafana → Configuration → Data Sources → Add data source +2. Selecione "Prometheus" +3. URL: `http://prometheus:9090` +4. Click "Save & Test" + +## 📊 Dashboard Pré-configurado + +Um dashboard chamado "Monitoramento de Atendimento" já foi criado e deve aparecer automaticamente em Dashboards → Browse. + +Se o dashboard não aparecer, você pode importá-lo manualmente: + +1. Grafana → Create → Import +2. Copie o conteúdo de `grafana/provisioning/dashboards/monitoring-dashboard.json` +3. Click "Load" + +## 🔧 Troubleshooting + +### "Connection refused" +```bash +# Verificar status dos containers +docker-compose ps + +# Reiniciar tudo +docker-compose restart +``` + +### "Failed to authenticate" +```bash +# Verificar logs da API +docker-compose logs monitoring-api + +# Verificar credenciais em .env +cat .env | grep API_ +``` + +### Sem dados no Grafana +```bash +# Testar endpoint diretamente +curl http://localhost:5000/api/summary + +# Se vazio, verificar logs +docker-compose logs -f monitoring-api +``` + +## 📱 Usar em Produção + +1. **Configure HTTPS**: Use nginx/caddy como reverse proxy +2. **Credenciais seguras**: Use secrets do Docker Compose +3. **Volumes persistentes**: Configure para Grafana e Prometheus +4. **Backups**: Configure backup automático do Grafana + +### Exemplo docker-compose para produção: + +```yaml +services: + monitoring-api: + # ... adicionar secrets + restart: always + + grafana: + volumes: + - grafana-storage:/var/lib/grafana + restart: always + + prometheus: + volumes: + - prometheus-storage:/prometheus + restart: always +``` + +## 📚 Documentação Adicional + +- [README.md](README.md) - Documentação completa +- [API Endpoints](README.md#-endpoints-disponíveis) +- [Criação de Dashboards](README.md#-criar-dashboard-no-grafana) + +## 💡 Dicas + +- Atualize o refresh interval em `.env` para ajustar frequência de coleta +- Configure alertas no Grafana baseado em limites de tempo de atendimento +- Exporte dashboards para compartilhar com equipe diff --git a/QUICKSTART.md b/QUICKSTART.md new file mode 100644 index 0000000..2b86165 --- /dev/null +++ b/QUICKSTART.md @@ -0,0 +1,96 @@ +# 🎯 Quick Start + +## 1️⃣ Clone ou acesse o projeto +```bash +cd /home/luis/monitoramento_atendimento +``` + +## 2️⃣ Configure sua credencial +```bash +# Editar .env com suas credenciais +nano .env +``` + +Alterar: +```env +API_USERNAME=seu_email@exemplo.com +API_PASSWORD=sua_senha +``` + +## 3️⃣ Inicie os containers +```bash +docker-compose up -d +``` + +Isso iniciará automaticamente: +- 🐍 API Python Flask (porta 5000) +- 📊 Grafana (porta 3000) +- 🔥 Prometheus (porta 9090) + +## 4️⃣ Acesse os serviços + +| Serviço | URL | Login | +|---------|-----|-------| +| Grafana | http://localhost:3000 | admin / admin | +| API | http://localhost:5000 | - | +| Prometheus | http://localhost:9090 | - | + +## 5️⃣ Teste a API +```bash +./test-api.sh +``` + +Ou manualmente: +```bash +curl http://localhost:5000/api/summary +``` + +## 6️⃣ Configure Datasources no Grafana + +### Para visualizar dados em GRÁFICOS: +1. Configuration → Data Sources → Add data source +2. Selecione **Prometheus** +3. URL: `http://prometheus:9090` +4. Save & Test + +### Para visualizar dados em TABELAS: +1. Configuration → Data Sources → Add data source +2. Selecione **JSON API** +3. URL: `http://monitoring-api:5000` +4. Save & Test + +## 7️⃣ Crie seu Dashboard + +### Opção A: Usar Dashboard Pré-pronto +- Vá para Dashboards → Browse +- Procure por "Monitoramento de Atendimento" + +### Opção B: Criar Novo Dashboard Manual + +**Painel de Tabela:** +- New Panel → Table +- Data Source: JSON API +- Query: Select field → tickets +- Transform → Organize fields → Selecione: contact_name, duration_formatted + +**Painel de Gráfico:** +- New Panel → Time series +- Data Source: Prometheus +- Metrics: `ticket_duration_seconds` + +## ❓ Problemas? + +```bash +# Ver logs +docker-compose logs -f monitoring-api + +# Reiniciar +docker-compose restart + +# Recriar tudo do zero +docker-compose down -v +docker-compose up -d +``` + +## 📖 Mais informações +Veja [README.md](README.md) para documentação completa. diff --git a/README.md b/README.md new file mode 100644 index 0000000..b3e0adc --- /dev/null +++ b/README.md @@ -0,0 +1,207 @@ +# Monitoramento de Atendimento - Grafana Integration + +Sistema de integração entre a plataforma PersonalizeIT e o Grafana para monitoramento em tempo real de tickets de atendimento. + +## 📋 Funcionalidades + +- ✅ Autenticação automática na API PersonalizeIT +- ✅ Coleta de tickets com nome da pessoa e tempo de atendimento +- ✅ Três formatos de dados disponíveis: + - **JSON** - Para Grafana JSON Datasource + - **Prometheus** - Para scraping com Prometheus + - **Time Series** - Para visualizações de série temporal +- ✅ Cache inteligente com refresh automático +- ✅ Endpoints de health check e resumo +- ✅ Docker Compose completo com Grafana e Prometheus +- ✅ Suporte a SSL/TLS + +## 🚀 Início Rápido + +### 1. Clonar/Preparar o projeto +```bash +cd /home/luis/monitoramento_atendimento +``` + +### 2. Configurar credenciais +```bash +cp config/.env.example .env +``` + +Edite o arquivo `.env` com suas credenciais: +```env +API_USERNAME=seu_email@exemplo.com +API_PASSWORD=sua_senha +``` + +### 3. Executar com Docker Compose +```bash +docker-compose up -d +``` + +Isso irá iniciar: +- **Api (Flask)** em `http://localhost:5000` +- **Grafana** em `http://localhost:3000` (admin/admin) +- **Prometheus** em `http://localhost:9090` + +### 4. Verificar saúde da API +```bash +curl http://localhost:5000/health +``` + +## 📊 Endpoints Disponíveis + +### `/` - Status da aplicação +```bash +curl http://localhost:5000/ +``` + +### `/health` - Health check +```bash +curl http://localhost:5000/health +``` + +### `/api/tickets` - JSON com tickets +```bash +curl http://localhost:5000/api/tickets +``` + +**Resposta:** +```json +{ + "timestamp": "2026-02-09T12:30:00.000000", + "total_tickets": 10, + "tickets": [ + { + "id": 26459, + "contact_name": "Júlia Donelli", + "duration_seconds": 56, + "duration_formatted": "00:00:56", + "status": "pending", + "queue": "EQUIPAMENTO EM MANUTENÇÃO", + "contact_number": "555199448030" + } + ] +} +``` + +### `/metrics` - Prometheus metrics +```bash +curl http://localhost:5000/metrics +``` + +### `/api/timeseries` - Dados de série temporal +```bash +curl http://localhost:5000/api/timeseries +``` + +### `/api/summary` - Resumo estatístico +```bash +curl http://localhost:5000/api/summary +``` + +## 🔧 Configuração de Datasource no Grafana + +### Opção 1: Usar JSON Datasource (Recomendado para tabelas) + +1. Acesse Grafana em `http://localhost:3000` +2. Vá para **Configuration > Data Sources > Add data source** +3. Selecione **JSON API** +4. Configure: + - **URL**: `http://monitoring-api:5000/api/tickets` + - **Access**: Server + +### Opção 2: Usar Prometheus (Recomendado para gráficos) + +1. Acesse Grafana em `http://localhost:3000` +2. Vá para **Configuration > Data Sources > Add data source** +3. Selecione **Prometheus** +4. Configure: + - **URL**: `http://prometheus:9090` + - **Access**: Server + +## 📈 Criar Dashboard no Grafana + +### Painel com Tabela de Atendimentos + +1. **Novo Dashboard** → **Add Panel** +2. **Query**: Use datasource JSON +3. **Transform**: Adicione transformação para selecionar campos `contact_name` e `duration_formatted` +4. **Visualization**: Selecione `Table` + +### Painel com Gráfico de Duração + +1. **Novo Dashboard** → **Add Panel** +2. **Query**: Use datasource Prometheus +3. **Metrics**: Selecione `ticket_duration_seconds` +4. **Visualization**: Selecione `Stat` ou `Time series` + +## 🐛 Troubleshooting + +### Erro: "Failed to authenticate with API" +- Verifique se `API_USERNAME` e `API_PASSWORD` estão corretos +- Confirme se a API está acessível: `curl https://api-personalizeit.zapplataforma.chat/auth/login` + +### Erro: "Connection refused" +- Verifique se os containers estão em execução: `docker-compose ps` +- Reinicie os containers: `docker-compose restart` + +### Sem dados no Grafana +- Verifique logs da API: `docker-compose logs monitoring-api` +- Teste endpoint diretamente: `curl http://localhost:5000/api/summary` + +## 📝 Logs + +Ver logs da aplicação: +```bash +docker-compose logs -f monitoring-api +``` + +Ver logs do Grafana: +```bash +docker-compose logs -f grafana +``` + +## 🛑 Parar os containers +```bash +docker-compose down +``` + +## 🗂️ Estrutura do Projeto + +``` +monitoramento_atendimento/ +├── src/ +│ ├── app.py # Aplicação Flask +│ ├── api_client.py # Cliente da API +│ ├── data_formatter.py # Formatação de dados +│ └── config.py # Configurações +├── config/ +│ └── .env.example # Template de variáveis +├── docker-compose.yml # Orquestração Docker +├── Dockerfile # Build da aplicação +├── prometheus.yml # Configuração Prometheus +├── requirements.txt # Dependências Python +└── README.md # Este arquivo +``` + +## 🔐 Segurança + +- As credenciais são gerenciadas via arquivo `.env` (não versionado) +- A API usa Bearer token para autenticação +- SSL/TLS é verificado por padrão +- Health checks garantem disponibilidade + +## 🚀 Para Produção + +1. Configure variáveis de ambiente adequadamente +2. Use `gunicorn` ao invés de servidor Flask padrão (já configurado no Dockerfile) +3. Configure HTTPS reverse proxy (nginx/caddy) +4. Use volume persistente para Grafana +5. Configure backup de datasources do Grafana + +## 📞 Suporte + +Para mais informações, consulte: +- [Documentação PersonalizeIT API](https://api-personalizeit.zapplataforma.chat) +- [Documentação Grafana](https://grafana.com/docs) +- [Documentação Prometheus](https://prometheus.io/docs) diff --git a/TECHNICAL.md b/TECHNICAL.md new file mode 100644 index 0000000..4fbeb69 --- /dev/null +++ b/TECHNICAL.md @@ -0,0 +1,319 @@ +# 📚 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 + +```env +# 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 + +```python +# 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 + +```python +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 + +```yaml +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 + +```yaml +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="..."} +tickets_total +ticket_duration_seconds_avg +``` + +## 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 + +```bash +# 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) +```yaml +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 +```bash +# 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 +```bash +# 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 + +## Referências + +- [Dockerfile best practices](https://docs.docker.com/develop/dev-best-practices/dockerfile_best-practices/) +- [Flask production deployment](https://flask.palletsprojects.com/en/2.3.x/deploying/) +- [Prometheus integration](https://prometheus.io/docs/instrumenting/writing_exporters/) +- [Grafana data sources](https://grafana.com/docs/grafana/latest/datasources/) diff --git a/TROUBLESHOOTING.md b/TROUBLESHOOTING.md new file mode 100644 index 0000000..5301dab --- /dev/null +++ b/TROUBLESHOOTING.md @@ -0,0 +1,304 @@ +# 🛠️ Troubleshooting & FAQ + +## ❌ Problemas Comuns + +### 1. "Connection refused" ao acessar http://localhost:3000 + +**Causa**: Containers não estão rodando ou porta já está em uso + +```bash +# Verificar status +docker-compose ps + +# Se não estiver rodando +docker-compose up -d + +# Se porta já está em uso +lsof -i :3000 +kill -9 +docker-compose down +docker-compose up -d +``` + +### 2. Grafana mostra "Data source is not responding" + +**Causa**: Datasource não consegue conectar à API + +```bash +# Verificar se API está rodando +docker-compose logs monitoring-api + +# Verificar conectividade do container Grafana +docker-compose exec grafana ping monitoring-api + +# Reiniciar API +docker-compose restart monitoring-api +``` + +### 3. API retorna "Failed to authenticate" + +**Causa**: Credenciais inválidas ou API PersonalizeIT indisponível + +```bash +# Verificar credenciais +cat .env | grep API_ + +# Testar login manualmente +curl -X POST \ + -H 'Content-Type: application/json' \ + -d '{"email":"seu_email@exemplo.com","password":"sua_senha"}' \ + https://api-personalizeit.zapplataforma.chat/auth/login + +# Verificar logs +docker-compose logs monitoring-api | grep -i "authent" +``` + +### 4. "ENOENT: no such file or directory, open '.env'" + +**Causa**: Arquivo .env não foi criado + +```bash +# Criar .env a partir do exemplo +cp config/.env.example .env + +# Editar com credenciais +nano .env +``` + +### 5. Prometheus mostra "Unhealthy Target" + +**Causa**: Prometheus não consegue scrape da API + +```bash +# Verificar URL no prometheus.yml +# Deve ser: http://monitoring-api:5000/metrics + +# Verificar se métrica está acessível +curl http://localhost:5000/metrics + +# Se vazio, significa sem dados. Tudo ok. +``` + +### 6. "permission denied" ao executar setup.sh + +**Causa**: Script sem permissão de execução + +```bash +chmod +x setup.sh test-api.sh +./setup.sh +``` + +### 7. Docker Compose "service not found" + +**Causa**: Nomes dos serviços estão incorretos + +```yaml +# Verifique os nomes em docker-compose.yml +# Devem ser: monitoring-api, grafana, prometheus +``` + +### 8. "Disk space insufficient" + +**Causa**: Volumes do Docker muito grande + +```bash +# Ver tamanho dos volumes +docker volume ls +docker system df + +# Limpar volumes não usados +docker volume prune + +# Remover dados históricos +docker-compose down -v +docker-compose up -d +``` + +## ⚙️ Otimizações + +### Melhorar Performance + +1. **Aumentar intervalo de refresh** (se dados menos atualizados ok) +```env +REFRESH_INTERVAL=60 # Era 30s +``` + +2. **Limitar quantidade de tickets** +```bash +# Na query da API, adicionar paginação +# Módulo API Client já suporta limitação +``` + +3. **Usar Redis para cache** +```bash +# Adicionar ao docker-compose.yml +# Depois modificar app.py para usar Redis +``` + +### Reduzir Consumo de Memória + +1. **Usar volume para dados do Grafana** +```yaml +volumes: + - grafana-storage:/var/lib/grafana +``` + +2. **Limitar workers do Gunicorn** +```dockerfile +CMD ["gunicorn", "--workers", "2", "--bind", "0.0.0.0:5000", "app:app"] +``` + +## 📊 Monitoramento do Próprio Sistema + +### Métricas da API +```bash +# Ver saúde da API +curl http://localhost:5000/health + +# Ver CPU e memória do container +docker stats monitoring-api +``` + +### Métricas do Grafana +```bash +# Ver logs do Grafana +docker-compose logs grafana + +# Ver consumo +docker stats grafana +``` + +### Métricas do Prometheus +```bash +# Verificar targets +curl http://localhost:9090/api/v1/targets + +# Verificar health +curl http://localhost:9090/-/healthy +``` + +## 🔐 Segurança + +### Checklist de Segurança + +- ✅ .env não está commitado (verificar .gitignore) +```bash +cat .gitignore | grep .env +``` + +- ✅ Senhas não estão em logs +```bash +docker-compose logs | grep -i password +# Não deve encontrar nada +``` + +- ✅ HTTPS configurado (se em produção) +```bash +# Usar reverse proxy com SSL +``` + +- ✅ Firewall configurado +```bash +# Apenas portas 3000 e 5000 acessíveis +``` + +## 📝 Logs e Debug + +### Ativar debug mode +```env +DEBUG=True # Em .env +``` + +### Ver logs completos +```bash +# Tempo real +docker-compose logs -f + +# Últimas 100 linhas +docker-compose logs --tail 100 + +# Apenas da API +docker-compose logs -f monitoring-api +``` + +### Exportar logs +```bash +docker-compose logs > debug.log +cat debug.log +``` + +### Log level em Python +```python +# Em app.py, modificar: +logging.basicConfig(level=logging.DEBUG) # Era INFO +``` + +## 🔄 Resetar Tudo + +```bash +# Parar todos os containers +docker-compose down + +# Remover volumes (dados históricos) +docker-compose down -v + +# Remover imagens +docker-compose down -v --rmi all + +# Reconstruir +docker-compose build --no-cache + +# Reiniciar +docker-compose up -d +``` + +## 📞 Quando Nada Funciona + +1. **Verificar Docker** +```bash +docker --version +docker run hello-world +``` + +2. **Verificar conectividade** +```bash +ping -c 1 api-personalizeit.zapplataforma.chat +curl https://api-personalizeit.zapplataforma.chat/auth/login +``` + +3. **Recriar do zero** +```bash +docker-compose down -v --rmi all +rm -rf grafana-storage prometheus-storage +rm .env +cp config/.env.example .env +# Configure .env +docker-compose up -d +``` + +4. **Buscar ajuda** +```bash +# Coletar informações +docker-compose ps > info.txt +docker-compose logs >> info.txt +curl http://localhost:5000/health >> info.txt +# Compartilhar info.txt +``` + +## 🚀 Performance Tips + +| Problema | Solução | +|----------|---------| +| Lento | Aumentar REFRESH_INTERVAL | +| Alto consumo memória | Reduzir workers gunicorn | +| Muitos dados | Fazer paginação ou filtrar | +| Sem dados | Verificar credenciais | +| Timeouts | Aumentar timeout em api_client.py | +| Erros de conexão | Verificar firewall/proxy | + +## 📚 Documentação Referência + +- [Docker Docs](https://docs.docker.com/) +- [Flask Docs](https://flask.palletsprojects.com/) +- [Grafana Docs](https://grafana.com/docs/) +- [Prometheus Docs](https://prometheus.io/docs/) diff --git a/config/.env.example b/config/.env.example new file mode 100644 index 0000000..b831ba5 --- /dev/null +++ b/config/.env.example @@ -0,0 +1,19 @@ +# API Configuration +API_BASE_URL=https://api-personalizeit.zapplataforma.chat +API_LOGIN_ENDPOINT=/auth/login +API_TICKETS_ENDPOINT=/tickets + +# Login Credentials (provide your credentials) +API_USERNAME=seu_email@exemplo.com +API_PASSWORD=sua_senha + +# Flask Configuration +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 diff --git a/docker-compose.yml b/docker-compose.yml new file mode 100644 index 0000000..bdd5749 --- /dev/null +++ b/docker-compose.yml @@ -0,0 +1,74 @@ +version: '3.8' + +services: + # Python Flask API for Grafana data source + monitoring-api: + build: . + container_name: monitoring-api + ports: + - "5000:5000" + environment: + - API_BASE_URL=https://api-personalizeit.zapplataforma.chat + - API_USERNAME=${API_USERNAME} + - API_PASSWORD=${API_PASSWORD} + - FLASK_PORT=5000 + - FLASK_HOST=0.0.0.0 + - DEBUG=False + - REFRESH_INTERVAL=5 + - QUEUE_IDS=-1,1,2,3,4,5,7 + volumes: + - ./.env:/app/.env:ro + networks: + - monitoring + restart: unless-stopped + healthcheck: + test: ["CMD", "curl", "-f", "http://localhost:5000/health"] + interval: 30s + timeout: 10s + retries: 3 + start_period: 40s + + # Grafana for visualization + grafana: + image: grafana/grafana:latest + container_name: grafana + ports: + - "3000:3000" + environment: + - GF_SECURITY_ADMIN_PASSWORD=admin + - GF_SECURITY_ADMIN_USER=admin + - GF_USERS_ALLOW_SIGN_UP=false + volumes: + - grafana-storage:/var/lib/grafana + - ./grafana/provisioning:/etc/grafana/provisioning:ro + networks: + - monitoring + restart: unless-stopped + depends_on: + - monitoring-api + + # Prometheus for scraping metrics (optional) + prometheus: + image: prom/prometheus:latest + container_name: prometheus + ports: + - "9090:9090" + volumes: + - ./prometheus.yml:/etc/prometheus/prometheus.yml:ro + - prometheus-storage:/prometheus + command: + - '--config.file=/etc/prometheus/prometheus.yml' + - '--storage.tsdb.path=/prometheus' + networks: + - monitoring + restart: unless-stopped + depends_on: + - monitoring-api + +volumes: + grafana-storage: + prometheus-storage: + +networks: + monitoring: + driver: bridge diff --git a/grafana/provisioning/dashboards/dashboard-provider.yml b/grafana/provisioning/dashboards/dashboard-provider.yml new file mode 100644 index 0000000..32e1479 --- /dev/null +++ b/grafana/provisioning/dashboards/dashboard-provider.yml @@ -0,0 +1,12 @@ +apiVersion: 1 + +providers: + - name: 'Monitoring Dashboards' + orgId: 1 + folder: '' + type: file + disableDeletion: false + updateIntervalSeconds: 10 + allowUiUpdates: true + options: + path: /etc/grafana/provisioning/dashboards diff --git a/grafana/provisioning/dashboards/monitoring-dashboard.json b/grafana/provisioning/dashboards/monitoring-dashboard.json new file mode 100644 index 0000000..56dbfaa --- /dev/null +++ b/grafana/provisioning/dashboards/monitoring-dashboard.json @@ -0,0 +1,167 @@ +{ + "annotations": { + "list": [ + { + "builtIn": 1, + "datasource": "-- Grafana --", + "enable": true, + "hide": true, + "iconColor": "rgba(0, 211, 255, 1)", + "name": "Annotations & Alerts", + "type": "dashboard" + } + ] + }, + "editable": true, + "gnetId": null, + "graphTooltip": 0, + "id": null, + "links": [], + "panels": [ + { + "datasource": "Prometheus", + "fieldConfig": { + "defaults": { + "custom": { + "align": "center", + "displayMode": "auto", + "inspect": false + }, + "mappings": [], + "thresholds": { + "mode": "absolute", + "steps": [ + { + "color": "green", + "value": null + } + ] + } + }, + "overrides": [ + { + "matcher": { + "id": "byName", + "options": "contact_name" + }, + "properties": [ + { + "id": "custom.displayMode", + "value": "color-background" + }, + { + "id": "unit", + "value": "short" + } + ] + }, + { + "matcher": { + "id": "byName", + "options": "TEMPO" + }, + "properties": [ + { + "id": "unit", + "value": "durationms" + }, + { + "id": "decimals", + "value": 0 + } + ] + } + ] + }, + "gridPos": { + "h": 12, + "w": 24, + "x": 0, + "y": 0 + }, + "id": 4, + "options": { + "footer": { + "countRows": false, + "fields": "", + "reducer": [ + "sum" + ], + "show": false + }, + "showHeader": true, + "sortBy": [ + { + "displayName": "TEMPO", + "desc": true + } + ] + }, + "pluginVersion": "8.0.0", + "targets": [ + { + "expr": "ticket_duration_milliseconds", + "format": "table", + "instant": true, + "refId": "A" + } + ], + "title": "Atendimentos - Nome e Tempo", + "transformations": [ + { + "id": "organize", + "options": { + "excludeByName": { + "Time": true, + "instance": true, + "job": true, + "status": true, + "ticket_id": true, + "__name__": true, + "Value": true, + "ticket_duration_milliseconds": true + }, + "indexByName": { + "contact_name": 0, + "queue": 1, + "duration_formatted": 2 + }, + "renameByName": { + "contact_name": "PESSOA", + "queue": "TAG", + "duration_formatted": "TEMPO" + } + } + }, + { + "id": "convertFieldType", + "options": { + "conversions": [], + "fields": {} + } + } + ], + "type": "table" + } + ], + "refresh": "5s", + "schemaVersion": 27, + "style": "dark", + "tags": [ + "monitoring", + "tickets", + "atendimento" + ], + "templating": { + "list": [] + }, + "time": { + "from": "now-6h", + "to": "now" + }, + "timepicker": {}, + "timezone": "", + "title": "Monitoramento de Atendimento", + "uid": "monitoring-tickets", + "version": 1 +} diff --git a/grafana/provisioning/datasources/datasources.yml b/grafana/provisioning/datasources/datasources.yml new file mode 100644 index 0000000..2d864ad --- /dev/null +++ b/grafana/provisioning/datasources/datasources.yml @@ -0,0 +1,10 @@ +apiVersion: 1 + +datasources: + - name: Prometheus + type: prometheus + access: proxy + url: http://prometheus:9090 + isDefault: true + version: 1 + editable: true diff --git a/prometheus.yml b/prometheus.yml new file mode 100644 index 0000000..3d9d8e1 --- /dev/null +++ b/prometheus.yml @@ -0,0 +1,11 @@ +global: + scrape_interval: 5s + evaluation_interval: 5s + +scrape_configs: + - job_name: 'monitoring-api' + static_configs: + - targets: ['monitoring-api:5000'] + metrics_path: '/metrics' + scrape_interval: 5s + scrape_timeout: 4s diff --git a/requirements.txt b/requirements.txt new file mode 100644 index 0000000..19b468d --- /dev/null +++ b/requirements.txt @@ -0,0 +1,6 @@ +Flask==2.3.3 +requests==2.31.0 +python-dotenv==1.0.0 +werkzeug==2.3.7 +gunicorn==21.2.0 +prometheus-client==0.17.1 diff --git a/setup.sh b/setup.sh new file mode 100644 index 0000000..aebbfa7 --- /dev/null +++ b/setup.sh @@ -0,0 +1,72 @@ +#!/bin/bash + +# Script para setup inicial do projeto + +set -e + +echo "🚀 Iniciando setup do projeto de Monitoramento de Atendimento" +echo "" + +# Verificar se Docker está instalado +if ! command -v docker &> /dev/null; then + echo "❌ Docker não está instalado. Por favor, instale Docker primeiro." + exit 1 +fi + +echo "✅ Docker encontrado" + +# Verificar se docker-compose está instalado +if ! command -v docker-compose &> /dev/null; then + echo "❌ Docker Compose não está instalado. Por favor, instale Docker Compose primeiro." + exit 1 +fi + +echo "✅ Docker Compose encontrado" + +# Copiar arquivo .env +if [ ! -f ".env" ]; then + echo "" + echo "📝 Criando arquivo .env..." + cp config/.env.example .env + echo "✅ Arquivo .env criado" + echo "" + echo "🔧 IMPORTANTE: Edite o arquivo .env com suas credenciais:" + echo " API_USERNAME=seu_email@exemplo.com" + echo " API_PASSWORD=sua_senha" + echo "" + read -p "Pressione ENTER após configurar o arquivo .env" +else + echo "✅ Arquivo .env já existe" +fi + +# Validar credenciais +if ! grep -q "API_USERNAME=seu_email" .env && ! grep -q "API_PASSWORD=sua_senha" .env; then + echo "" + echo "🐳 Iniciando containers..." + docker-compose up -d + + echo "" + echo "✅ Arquivos criados com sucesso!" + echo "" + echo "📊 URLs dos serviços:" + echo " API: http://localhost:5000" + echo " Grafana: http://localhost:3000 (admin/admin)" + echo " Prometheus: http://localhost:9090" + echo "" + echo "🔗 Endpoints da API:" + echo " GET / - Status da aplicação" + echo " GET /health - Health check" + echo " GET /api/tickets - JSON com tickets" + echo " GET /api/summary - Resumo estatístico" + echo " GET /api/timeseries - Dados de série temporal" + echo " GET /metrics - Prometheus metrics" + echo "" + echo "📚 Próximos passos:" + echo " 1. Acesse http://localhost:3000 (Grafana)" + echo " 2. Faça login com admin/admin" + echo " 3. Configure os datasources conforme README.md" + echo " 4. Crie dashboards para visualizar os dados" + echo "" +else + echo "⚠️ Configure as credenciais no arquivo .env primeiro!" +fi diff --git a/src/api_client.py b/src/api_client.py new file mode 100644 index 0000000..9277544 --- /dev/null +++ b/src/api_client.py @@ -0,0 +1,171 @@ +import requests +import logging +from typing import Optional, Dict, Any, List +from config import Config + +logger = logging.getLogger(__name__) + +class APIClient: + """Client for interacting with the PersonalizeIT API""" + + def __init__(self): + self.base_url = Config.API_BASE_URL + self.token = None + self.session = requests.Session() + self.session.verify = True # Verify SSL certificates + + def login(self) -> bool: + """ + Authenticate with the API and obtain a bearer token + + Returns: + bool: True if authentication was successful, False otherwise + """ + try: + login_url = f"{self.base_url}{Config.API_LOGIN_ENDPOINT}" + + payload = { + "email": Config.API_USERNAME, + "password": Config.API_PASSWORD + } + + logger.info(f"Attempting to authenticate at {login_url}") + response = self.session.post( + login_url, + json=payload, + timeout=10 + ) + + if response.status_code == 200: + data = response.json() + self.token = data.get('token') or data.get('access_token') + + if self.token: + logger.info("Successfully authenticated") + self._set_auth_header() + return True + else: + logger.error("Token not found in login response") + return False + else: + logger.error(f"Login failed with status code {response.status_code}: {response.text}") + return False + + except requests.exceptions.RequestException as e: + logger.error(f"Error during login: {str(e)}") + return False + + def _set_auth_header(self): + """Set the authorization header with the bearer token""" + if self.token: + self.session.headers.update({ + 'Authorization': f'Bearer {self.token}', + 'Content-Type': 'application/json' + }) + + def get_tickets(self, + page_number: int = 1, + status: str = 'pending', + sort_dir: str = 'DESC', + queue_ids: Optional[List[int]] = None, + is_group: bool = False) -> Optional[Dict[str, Any]]: + """ + Fetch tickets from the API + + Args: + page_number: Page number (default: 1) + status: Ticket status filter (default: 'pending') + sort_dir: Sort direction (default: 'DESC') + queue_ids: List of queue IDs to filter (default: from Config) + is_group: Whether to fetch group tickets (default: False) + + Returns: + dict: Response data if successful, None otherwise + """ + if not self.token: + logger.error("Not authenticated. Please login first.") + return None + + try: + import json + + if queue_ids is None: + queue_ids = Config.get_queue_ids_list() + + tickets_url = f"{self.base_url}{Config.API_TICKETS_ENDPOINT}" + + # Format queueIds as JSON string for API compatibility + params = { + 'pageNumber': page_number, + 'status': status, + 'showAll': 'false', + 'queueIds': json.dumps(queue_ids), + 'tagIds': '[]', + 'isGroup': 'true' if is_group else 'false', + 'sortDir': sort_dir, + 'isSearching': 'false' + } + + logger.info(f"Fetching tickets from {tickets_url} with params: {params}") + response = self.session.get( + tickets_url, + params=params, + timeout=15 + ) + + if response.status_code == 200: + logger.info(f"Successfully fetched tickets") + return response.json() + else: + logger.error(f"Failed to fetch tickets: {response.status_code} - {response.text}") + return None + + except requests.exceptions.RequestException as e: + logger.error(f"Error fetching tickets: {str(e)}") + return None + + def get_all_tickets(self) -> List[Dict[str, Any]]: + """ + Fetch all pending tickets and group tickets + + Returns: + list: List of ticket dictionaries + """ + all_tickets = [] + + # Fetch pending tickets + logger.info("Fetching pending tickets...") + page = 1 + while True: + result = self.get_tickets(page_number=page, status='pending', is_group=False) + + if not result or not result.get('tickets'): + break + + all_tickets.extend(result.get('tickets', [])) + + if not result.get('hasMore', False): + break + + page += 1 + + logger.info(f"Fetched {len(all_tickets)} pending tickets") + + # Fetch group tickets + logger.info("Fetching group tickets...") + page = 1 + while True: + result = self.get_tickets(page_number=page, status='group', is_group=True) + + if not result or not result.get('tickets'): + break + + all_tickets.extend(result.get('tickets', [])) + + if not result.get('hasMore', False): + break + + page += 1 + + logger.info(f"Total tickets fetched (pending + group): {len(all_tickets)}") + return all_tickets diff --git a/src/app.py b/src/app.py new file mode 100644 index 0000000..efc7260 --- /dev/null +++ b/src/app.py @@ -0,0 +1,205 @@ +import logging +import os +from datetime import datetime, timedelta +from flask import Flask, jsonify, Response +from api_client import APIClient +from data_formatter import DataFormatter +from config import Config + +# Configure logging +logging.basicConfig( + level=logging.INFO, + format='%(asctime)s - %(name)s - %(levelname)s - %(message)s' +) +logger = logging.getLogger(__name__) + +app = Flask(__name__) + +# Global variables for caching +last_update = None +cached_tickets = [] +cached_json = None +cached_metrics = None +CACHE_DURATION = timedelta(seconds=Config.REFRESH_INTERVAL) + +def update_tickets(): + """Update cached tickets from API""" + global last_update, cached_tickets, cached_json, cached_metrics + + now = datetime.now() + + # Only update if cache is expired or first run + if last_update is None or (now - last_update) > CACHE_DURATION: + try: + logger.info("Updating ticket data from API...") + client = APIClient() + + # Login + if not client.login(): + logger.error("Failed to authenticate with API") + return False + + # Fetch tickets + cached_tickets = client.get_all_tickets() + + # Format data + cached_json = DataFormatter.format_tickets_for_json(cached_tickets) + cached_metrics = DataFormatter.format_for_prometheus(cached_tickets) + + last_update = now + logger.info(f"Successfully updated {len(cached_tickets)} tickets") + return True + except Exception as e: + logger.error(f"Error updating tickets: {str(e)}") + return False + + return True + +@app.route('/') +def index(): + """Health check endpoint""" + return jsonify({ + 'status': 'running', + 'version': '1.0.0', + 'timestamp': datetime.now().isoformat(), + 'endpoints': { + 'health': '/health', + 'json': '/api/tickets', + 'prometheus': '/metrics', + 'timeseries': '/api/timeseries' + } + }) + +@app.route('/health') +def health(): + """Health check endpoint""" + try: + update_tickets() + return jsonify({ + 'status': 'healthy', + 'cached_tickets': len(cached_tickets), + 'last_update': last_update.isoformat() if last_update else None + }), 200 + except Exception as e: + logger.error(f"Health check failed: {str(e)}") + return jsonify({ + 'status': 'unhealthy', + 'error': str(e) + }), 500 + +@app.route('/api/tickets') +def get_tickets(): + """ + Get tickets as JSON for Grafana JSON datasource + Useful for displaying data in Grafana tables and dashboards + """ + try: + if not update_tickets(): + return jsonify({'error': 'Failed to fetch tickets'}), 500 + + if cached_json is None: + return jsonify({'error': 'No data available'}), 204 + + return jsonify(cached_json), 200 + except Exception as e: + logger.error(f"Error in /api/tickets: {str(e)}") + return jsonify({'error': str(e)}), 500 + +@app.route('/metrics') +def metrics(): + """ + Prometheus metrics endpoint + Can be scraped by Prometheus or used directly in Grafana + """ + try: + if not update_tickets(): + return Response('# Error: Failed to fetch tickets\n', mimetype='text/plain'), 500 + + if cached_metrics is None: + return Response('# No data available\n', mimetype='text/plain'), 204 + + return Response(cached_metrics, mimetype='text/plain'), 200 + except Exception as e: + logger.error(f"Error in /metrics: {str(e)}") + return Response(f'# Error: {str(e)}\n', mimetype='text/plain'), 500 + +@app.route('/api/timeseries') +def timeseries(): + """ + Get time series data for Grafana time series visualization + """ + try: + if not update_tickets(): + return jsonify({'error': 'Failed to fetch tickets'}), 500 + + time_series = DataFormatter.format_for_timeseries(cached_tickets) + return jsonify(time_series), 200 + except Exception as e: + logger.error(f"Error in /api/timeseries: {str(e)}") + return jsonify({'error': str(e)}), 500 + +@app.route('/api/summary') +def summary(): + """ + Get summary statistics for tickets + """ + try: + if not update_tickets(): + return jsonify({'error': 'Failed to fetch tickets'}), 500 + + if not cached_tickets: + return jsonify({ + 'total_tickets': 0, + 'average_duration': 0, + 'max_duration': 0, + 'min_duration': 0 + }), 200 + + durations = [t.get('duration', 0) for t in cached_tickets] + + return jsonify({ + 'total_tickets': len(cached_tickets), + 'average_duration_seconds': sum(durations) / len(durations), + 'max_duration_seconds': max(durations), + 'min_duration_seconds': min(durations), + 'total_duration_seconds': sum(durations), + 'timestamp': datetime.now().isoformat(), + 'contacts': list(set(t.get('contact', {}).get('name') for t in cached_tickets)) + }), 200 + except Exception as e: + logger.error(f"Error in /api/summary: {str(e)}") + return jsonify({'error': str(e)}), 500 + +@app.errorhandler(404) +def not_found(error): + """Handle 404 errors""" + return jsonify({'error': 'Endpoint not found'}), 404 + +@app.errorhandler(500) +def internal_error(error): + """Handle 500 errors""" + logger.error(f"Internal server error: {str(error)}") + return jsonify({'error': 'Internal server error'}), 500 + +if __name__ == '__main__': + try: + # Validate configuration + Config.validate() + + logger.info("Starting Grafana Monitoring Service...") + logger.info(f"API Base URL: {Config.API_BASE_URL}") + logger.info(f"Refresh Interval: {Config.REFRESH_INTERVAL} seconds") + logger.info(f"Queue IDs: {Config.QUEUE_IDS}") + + # Start Flask app + app.run( + host=Config.FLASK_HOST, + port=Config.FLASK_PORT, + debug=Config.DEBUG + ) + except ValueError as e: + logger.error(f"Configuration error: {str(e)}") + exit(1) + except Exception as e: + logger.error(f"Fatal error: {str(e)}") + exit(1) diff --git a/src/config.py b/src/config.py new file mode 100644 index 0000000..51e0aa1 --- /dev/null +++ b/src/config.py @@ -0,0 +1,39 @@ +import os +from dotenv import load_dotenv + +# Load environment variables from .env file +load_dotenv() + +class Config: + """Configuration class for the Grafana monitoring service""" + + # API Configuration + API_BASE_URL = os.getenv('API_BASE_URL', 'https://api-personalizeit.zapplataforma.chat') + API_LOGIN_ENDPOINT = os.getenv('API_LOGIN_ENDPOINT', '/auth/login') + API_TICKETS_ENDPOINT = os.getenv('API_TICKETS_ENDPOINT', '/tickets') + + # Login Credentials + API_USERNAME = os.getenv('API_USERNAME', '') + API_PASSWORD = os.getenv('API_PASSWORD', '') + + # Flask Configuration + FLASK_PORT = int(os.getenv('FLASK_PORT', 5000)) + FLASK_HOST = os.getenv('FLASK_HOST', '0.0.0.0') + DEBUG = os.getenv('DEBUG', 'False').lower() == 'true' + + # Refresh interval in seconds + REFRESH_INTERVAL = int(os.getenv('REFRESH_INTERVAL', 30)) + + # Queue IDs + QUEUE_IDS = os.getenv('QUEUE_IDS', '-1,1,2,3,4,5,7') + + @staticmethod + def get_queue_ids_list(): + """Convert comma-separated queue IDs to list of integers""" + return [int(q.strip()) for q in Config.QUEUE_IDS.split(',')] + + @staticmethod + def validate(): + """Validate that required configuration is provided""" + if not Config.API_USERNAME or not Config.API_PASSWORD: + raise ValueError("API_USERNAME and API_PASSWORD must be set in environment variables") diff --git a/src/data_formatter.py b/src/data_formatter.py new file mode 100644 index 0000000..67748aa --- /dev/null +++ b/src/data_formatter.py @@ -0,0 +1,267 @@ +import logging +from typing import List, Dict, Any +from datetime import datetime + +logger = logging.getLogger(__name__) + +class DataFormatter: + """Formats ticket data for Grafana consumption""" + + @staticmethod + def format_tickets_for_json(tickets: List[Dict[str, Any]]) -> Dict[str, Any]: + """ + Format tickets as JSON for Grafana + + Args: + tickets: List of ticket dictionaries from API + + Returns: + dict: Formatted data structure for Grafana + """ + formatted_tickets = [] + now = datetime.now() + + for ticket in tickets: + try: + # Handle None values safely + contact = ticket.get('contact') or {} + queue = ticket.get('queue') or {} + whatsapp = ticket.get('whatsapp') or {} + tags = ticket.get('tags', []) + group_tags = ticket.get('groupTags', []) + + contact_name = contact.get('name', 'Unknown') + ticket_id = ticket.get('id') + status = ticket.get('status') + created_at = ticket.get('createdAt') + updated_at = ticket.get('updatedAt') + + # Try to get queue name, or use tags/groupTags if available + queue_name = queue.get('name', 'No Queue') + if queue_name == 'No Queue': + # Try groupTags first - format is "id||name||color" + if group_tags: + if isinstance(group_tags, str) and '||' in group_tags: + parts = group_tags.split('||') + if len(parts) >= 2: + queue_name = parts[1] + elif isinstance(group_tags, list) and len(group_tags) > 0: + if isinstance(group_tags[0], dict): + queue_name = group_tags[0].get('tag', {}).get('name', 'No Queue') + else: + queue_name = str(group_tags[0]) + # Then try tags + elif tags and isinstance(tags, list) and len(tags) > 0: + if isinstance(tags[0], dict): + queue_name = tags[0].get('name', 'No Queue') + else: + queue_name = str(tags[0]) + elif isinstance(tags, str): + queue_name = tags + + # Calculate duration dynamically from createdAt to now + duration = 0 + if created_at: + try: + created_datetime = datetime.fromisoformat(created_at.replace('Z', '+00:00')) + # If timezone-aware, convert to naive for subtraction + if created_datetime.tzinfo is not None: + created_datetime = created_datetime.replace(tzinfo=None) + duration = int((now - created_datetime).total_seconds()) + except (ValueError, AttributeError): + duration = 0 + + # Skip tickets with "EQUIPAMENTO EM MANUTENÇÃO" queue + if 'EQUIPAMENTO EM MANUTENÇÃO' in queue_name: + continue + + # Format duration as HH:MM:SS + hours = duration // 3600 + minutes = (duration % 3600) // 60 + seconds = duration % 60 + duration_formatted = f"{hours:02d}:{minutes:02d}:{seconds:02d}" + + formatted_tickets.append({ + 'id': ticket_id, + 'contact_name': contact_name, + 'duration_seconds': duration, + 'duration_formatted': duration_formatted, + 'status': status, + 'queue': queue_name, + 'created_at': created_at, + 'updated_at': updated_at, + 'contact_number': contact.get('number', ''), + 'whatsapp_name': whatsapp.get('name', ''), + }) + except Exception as e: + logger.error(f"Error formatting ticket {ticket.get('id')}: {str(e)}") + continue + + return { + 'timestamp': datetime.now().isoformat(), + 'total_tickets': len(formatted_tickets), + 'tickets': formatted_tickets + } + + @staticmethod + def format_for_prometheus(tickets: List[Dict[str, Any]]) -> str: + """ + Format tickets as Prometheus metrics + + Args: + tickets: List of ticket dictionaries from API + + Returns: + str: Prometheus format metrics + """ + metrics = [] + + # Add help text + metrics.append("# HELP ticket_duration_milliseconds Duration of ticket in milliseconds") + metrics.append("# TYPE ticket_duration_milliseconds gauge") + + # Add metrics for each ticket + now = datetime.now() + for ticket in tickets: + try: + # Handle None values safely + contact = ticket.get('contact') or {} + queue = ticket.get('queue') or {} + tags = ticket.get('tags', []) + group_tags = ticket.get('groupTags', []) + + # Try to get queue name, or use tags/groupTags if available + queue_name = queue.get('name', 'no_queue') + if queue_name == 'no_queue': + # Try groupTags first - format is "id||name||color" + if group_tags: + if isinstance(group_tags, str) and '||' in group_tags: + parts = group_tags.split('||') + if len(parts) >= 2: + queue_name = parts[1] + elif isinstance(group_tags, list) and len(group_tags) > 0: + if isinstance(group_tags[0], dict): + queue_name = group_tags[0].get('tag', {}).get('name', 'no_queue') + else: + queue_name = str(group_tags[0]) + # Then try tags + elif tags and isinstance(tags, list) and len(tags) > 0: + if isinstance(tags[0], dict): + queue_name = tags[0].get('name', 'no_queue') + else: + queue_name = str(tags[0]) + elif isinstance(tags, str): + queue_name = tags + + # Skip tickets with "EQUIPAMENTO EM MANUTENÇÃO" queue + if 'EQUIPAMENTO EM MANUTENÇÃO' in queue_name: + continue + + contact_name = contact.get('name', 'unknown').replace('"', '\\"') + ticket_id = ticket.get('id') + status = ticket.get('status', 'unknown') + queue_name = queue_name.replace('"', '\\"') + + # Calculate duration dynamically from createdAt to now + duration = 0 + created_at = ticket.get('createdAt') + if created_at: + try: + created_datetime = datetime.fromisoformat(created_at.replace('Z', '+00:00')) + # If timezone-aware, convert to naive for subtraction + if created_datetime.tzinfo is not None: + created_datetime = created_datetime.replace(tzinfo=None) + duration = int((now - created_datetime).total_seconds()) + except (ValueError, AttributeError): + duration = 0 + + # Format duration as MM:SS for display + minutes = duration // 60 + seconds = duration % 60 + duration_formatted = f"{minutes}:{seconds:02d}s" + + # Create metric with labels including formatted duration, use milliseconds for the value + labels = f'ticket_id="{ticket_id}",contact_name="{contact_name}",status="{status}",queue="{queue_name}",duration_formatted="{duration_formatted}"' + metrics.append(f'ticket_duration_milliseconds{{{labels}}} {duration * 1000}') + except Exception as e: + logger.error(f"Error formatting Prometheus metric for ticket {ticket.get('id')}: {str(e)}") + continue + + # Add summary metrics + metrics.append("\n# HELP tickets_total Total number of pending tickets") + metrics.append("# TYPE tickets_total gauge") + metrics.append(f"tickets_total {len(tickets)}") + + # Average duration + if tickets: + avg_duration = sum(t.get('duration', 0) for t in tickets) / len(tickets) + metrics.append("\n# HELP ticket_duration_seconds_avg Average ticket duration in seconds") + metrics.append("# TYPE ticket_duration_seconds_avg gauge") + metrics.append(f"ticket_duration_seconds_avg {avg_duration:.2f}") + + return "\n".join(metrics) + + @staticmethod + def format_for_timeseries(tickets: List[Dict[str, Any]]) -> List[Dict[str, Any]]: + """ + Format tickets as time series data for Grafana + + Args: + tickets: List of ticket dictionaries from API + + Returns: + list: Time series formatted data + """ + time_series = [] + now = datetime.now() + + # Group by contact name + contacts = {} + for ticket in tickets: + # Handle None values safely + contact = ticket.get('contact') or {} + queue = ticket.get('queue') or {} + + queue_name = queue.get('name', 'No Queue') + + # Skip tickets with "EQUIPAMENTO EM MANUTENÇÃO" queue + if 'EQUIPAMENTO EM MANUTENÇÃO' in queue_name: + continue + + contact_name = contact.get('name', 'Unknown') + + # Calculate duration dynamically from createdAt to now + duration = 0 + created_at = ticket.get('createdAt') + if created_at: + try: + created_datetime = datetime.fromisoformat(created_at.replace('Z', '+00:00')) + # If timezone-aware, convert to naive for subtraction + if created_datetime.tzinfo is not None: + created_datetime = created_datetime.replace(tzinfo=None) + duration = int((now - created_datetime).total_seconds()) + except (ValueError, AttributeError): + duration = 0 + + if contact_name not in contacts: + contacts[contact_name] = { + 'duration': 0, + 'count': 0, + 'tickets': [] + } + + contacts[contact_name]['duration'] += duration + contacts[contact_name]['count'] += 1 + contacts[contact_name]['tickets'].append(ticket.get('id')) + + # Format as time series + for contact_name, data in contacts.items(): + time_series.append({ + 'target': contact_name, + 'datapoints': [ + [data['duration'], int(now.timestamp() * 1000)], + [data['count'], int(now.timestamp() * 1000)] + ] + }) + + return time_series diff --git a/test-api.sh b/test-api.sh new file mode 100644 index 0000000..e1b2be4 --- /dev/null +++ b/test-api.sh @@ -0,0 +1,40 @@ +#!/bin/bash + +# Script para testar os endpoints da API + +API_URL="${1:-http://localhost:5000}" + +echo "🧪 Testando API em $API_URL" +echo "" + +# Teste 1: Status +echo "1️⃣ Testando status da aplicação..." +curl -s "$API_URL/" | python3 -m json.tool +echo "" +echo "" + +# Teste 2: Health check +echo "2️⃣ Testando health check..." +curl -s "$API_URL/health" | python3 -m json.tool +echo "" +echo "" + +# Teste 3: Summary +echo "3️⃣ Testando resumo estatístico..." +curl -s "$API_URL/api/summary" | python3 -m json.tool +echo "" +echo "" + +# Teste 4: Tickets (apenas primeiras linhas) +echo "4️⃣ Testando tickets (JSON)..." +curl -s "$API_URL/api/tickets" | python3 -m json.tool | head -50 +echo "" +echo "" + +# Teste 5: Metrics +echo "5️⃣ Testando métricas (Prometheus)..." +curl -s "$API_URL/metrics" | head -20 +echo "" +echo "" + +echo "✅ Testes concluídos!"