From 52791b718ccf06f61397a80d9c7e05fa73688b24 Mon Sep 17 00:00:00 2001 From: luiscarlosjp Date: Mon, 9 Feb 2026 17:14:40 -0300 Subject: [PATCH] first commit --- .gitignore | 43 +++ ARCHITECTURE.md | 136 ++++++++ Dockerfile | 29 ++ EXAMPLES.md | 273 +++++++++++++++ INSTALL.md | 151 +++++++++ QUICKSTART.md | 96 ++++++ README.md | 207 ++++++++++++ TECHNICAL.md | 319 ++++++++++++++++++ TROUBLESHOOTING.md | 304 +++++++++++++++++ config/.env.example | 19 ++ docker-compose.yml | 74 ++++ .../dashboards/dashboard-provider.yml | 12 + .../dashboards/monitoring-dashboard.json | 167 +++++++++ .../provisioning/datasources/datasources.yml | 10 + prometheus.yml | 11 + requirements.txt | 6 + setup.sh | 72 ++++ src/api_client.py | 171 ++++++++++ src/app.py | 205 +++++++++++ src/config.py | 39 +++ src/data_formatter.py | 267 +++++++++++++++ test-api.sh | 40 +++ 22 files changed, 2651 insertions(+) create mode 100644 .gitignore create mode 100644 ARCHITECTURE.md create mode 100644 Dockerfile create mode 100644 EXAMPLES.md create mode 100644 INSTALL.md create mode 100644 QUICKSTART.md create mode 100644 README.md create mode 100644 TECHNICAL.md create mode 100644 TROUBLESHOOTING.md create mode 100644 config/.env.example create mode 100644 docker-compose.yml create mode 100644 grafana/provisioning/dashboards/dashboard-provider.yml create mode 100644 grafana/provisioning/dashboards/monitoring-dashboard.json create mode 100644 grafana/provisioning/datasources/datasources.yml create mode 100644 prometheus.yml create mode 100644 requirements.txt create mode 100644 setup.sh create mode 100644 src/api_client.py create mode 100644 src/app.py create mode 100644 src/config.py create mode 100644 src/data_formatter.py create mode 100644 test-api.sh 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!"