first commit

This commit is contained in:
2026-02-09 17:14:40 -03:00
commit 52791b718c
22 changed files with 2651 additions and 0 deletions

43
.gitignore vendored Normal file
View File

@@ -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/

136
ARCHITECTURE.md Normal file
View File

@@ -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

29
Dockerfile Normal file
View File

@@ -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"]

273
EXAMPLES.md Normal file
View File

@@ -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()
```

151
INSTALL.md Normal file
View File

@@ -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

96
QUICKSTART.md Normal file
View File

@@ -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.

207
README.md Normal file
View File

@@ -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)

319
TECHNICAL.md Normal file
View File

@@ -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="..."} <valor>
tickets_total <número>
ticket_duration_seconds_avg <número>
```
## Grafana Datasources
### JSON API
- Type: JSON API
- URL: http://monitoring-api:5000
- Method: GET
- Query format: JSON
### Prometheus
- Type: Prometheus
- URL: http://prometheus:9090
- Access: Server
## Performance Characteristics
| Métrica | Valor | Notas |
|---------|-------|-------|
| Latência API | < 500ms | Com cache |
| Atualização dados | 30s | Configurável |
| Consumo memória | ~150MB | Grafana + API |
| Espaço storage | Mínimo | Sem DB persistência |
| Concorrência | 4 workers | Gunicorn configurável |
| Max tickets | 1000+ | Depende de endpoints |
## Segurança
### HTTPS/TLS
- SSL verificado em api_client.py
- Adicionar proxy reverso para Grafana
### Authentication
- Bearer token na API PersonalizeIT
- Admin credentials Grafana (alterar padrão)
### Data Protection
- .env não versionado
- Variáveis de ambiente isoladas
- Logs não expõem senhas
## Logging
### Nível INFO (padrão)
```
2026-02-09 12:30:00,000 - api_client - INFO - Successfully authenticated
2026-02-09 12:30:01,000 - api_client - INFO - Successfully fetched tickets
```
### Nível DEBUG (com DEBUG=True)
```
2026-02-09 12:30:00,000 - api_client - DEBUG - Request URL: ...
2026-02-09 12:30:00,500 - api_client - DEBUG - Response: {"tickets": [...]}
```
## Testing
```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/)

304
TROUBLESHOOTING.md Normal file
View File

@@ -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 <PID>
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/)

19
config/.env.example Normal file
View File

@@ -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

74
docker-compose.yml Normal file
View File

@@ -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

View File

@@ -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

View File

@@ -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
}

View File

@@ -0,0 +1,10 @@
apiVersion: 1
datasources:
- name: Prometheus
type: prometheus
access: proxy
url: http://prometheus:9090
isDefault: true
version: 1
editable: true

11
prometheus.yml Normal file
View File

@@ -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

6
requirements.txt Normal file
View File

@@ -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

72
setup.sh Normal file
View File

@@ -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

171
src/api_client.py Normal file
View File

@@ -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

205
src/app.py Normal file
View File

@@ -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)

39
src/config.py Normal file
View File

@@ -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")

267
src/data_formatter.py Normal file
View File

@@ -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

40
test-api.sh Normal file
View File

@@ -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!"