# Como criar um dashboard de monitoramento para consumo de API de CPF > Aprenda a criar um dashboard para monitorar o consumo, latência e erros da sua integração com API de consulta de CPF. **Publicado:** 17/07/2025 **Autor:** Redação CPFHub.io **URL:** https://cpfhub.io/blog/criar-dashboard-monitoramento-consumo-api-cpf --- Um dashboard de monitoramento para API de CPF centraliza métricas de consumo, latência e erros em um único painel, dando visibilidade operacional para agir antes que problemas cheguem aos usuários. Com as ferramentas certas — Redis para coleta, Flask para endpoints e Grafana para visualização — você monta essa estrutura em poucas horas. A [ANPD](https://www.gov.br/anpd) recomenda que o tratamento de dados pessoais inclua controles de acesso e registro de operações, e o dashboard cumpre exatamente esse papel. ## Introdução Integrar uma API de CPF é apenas o primeiro passo. Para garantir que tudo funcione corretamente em produção, você precisa de visibilidade sobre o consumo, a latência e os erros. Um dashboard de monitoramento permite identificar problemas rapidamente, controlar custos e planejar a evolução da integração. --- ## Métricas essenciais para monitorar Antes de construir o dashboard, defina quais métricas são relevantes: | Métrica | Descrição | Por que importa | | --- | --- | --- | | Total de consultas | Quantidade de chamadas à API | Controle de consumo e custos | | Consultas por hora/dia | Distribuição temporal | Identificar picos de uso | | Taxa de sucesso | Porcentagem de respostas 200 | Saúde da integração | | Taxa de erro | Porcentagem de 4xx e 5xx | Identificar problemas | | Latência média | Tempo médio de resposta | Performance do fluxo | | P95 de latência | 95º percentil de latência | Detectar degradações | | Consultas consumidas | Consultas usadas no mês | Projeção de custo mensal | --- ## Coletando métricas com middleware O primeiro passo é instrumentar cada chamada à API para registrar métricas. Veja um exemplo em Python: ```python import requests import time import json from datetime import datetime class CPFHubMonitor: def __init__(self, api_key, redis_client): self.api_key = api_key self.redis = redis_client self.session = requests.Session() self.session.headers.update({ 'x-api-key': api_key, 'Accept': 'application/json' }) def consultar(self, cpf): inicio = time.perf_counter() status_code = None erro = None try: response = self.session.get( f'https://api.cpfhub.io/cpf/{cpf}', timeout=15 ) status_code = response.status_code resultado = response.json() except requests.exceptions.Timeout: status_code = 0 erro = 'timeout' resultado = None except Exception as e: status_code = 0 erro = str(e) resultado = None finally: fim = time.perf_counter() latencia_ms = (fim - inicio) * 1000 self._registrar_metrica(cpf, status_code, latencia_ms, erro) return resultado def _registrar_metrica(self, cpf, status_code, latencia_ms, erro): agora = datetime.utcnow() dia = agora.strftime('%Y-%m-%d') hora = agora.strftime('%Y-%m-%d:%H') pipe = self.redis.pipeline() # Contadores totais pipe.incr(f'cpf:total:{dia}') pipe.incr(f'cpf:hora:{hora}') # Contadores por status pipe.incr(f'cpf:status:{status_code}:{dia}') # Latencia (lista para calcular percentis) pipe.rpush(f'cpf:latencia:{dia}', latencia_ms) # TTL de 7 dias para limpeza automatica pipe.expire(f'cpf:total:{dia}', 604800) pipe.expire(f'cpf:hora:{hora}', 604800) pipe.expire(f'cpf:status:{status_code}:{dia}', 604800) pipe.expire(f'cpf:latencia:{dia}', 604800) if erro: pipe.rpush(f'cpf:erros:{dia}', json.dumps({ 'cpf': cpf, 'erro': erro, 'timestamp': agora.isoformat() })) pipe.execute() ``` --- ## Gerando dados para o dashboard Com as métricas coletadas, crie endpoints para alimentar o dashboard: ```python import numpy as np from flask import Flask, jsonify app = Flask(__name__) @app.route('/api/dashboard/resumo') def resumo(): dia = datetime.utcnow().strftime('%Y-%m-%d') total = int(r.get(f'cpf:total:{dia}') or 0) sucesso = int(r.get(f'cpf:status:200:{dia}') or 0) erros_400 = int(r.get(f'cpf:status:400:{dia}') or 0) erros_500 = int(r.get(f'cpf:status:500:{dia}') or 0) latencias = [float(x) for x in r.lrange(f'cpf:latencia:{dia}', 0, -1)] return jsonify({ 'data': dia, 'total_consultas': total, 'sucesso': sucesso, 'taxa_sucesso': round(sucesso / max(total, 1) * 100, 2), 'erros': { 'bad_request': erros_400, 'servidor': erros_500 }, 'latencia': { 'media': round(np.mean(latencias), 2) if latencias else 0, 'p50': round(np.percentile(latencias, 50), 2) if latencias else 0, 'p95': round(np.percentile(latencias, 95), 2) if latencias else 0, 'p99': round(np.percentile(latencias, 99), 2) if latencias else 0 } }) ``` --- ## Dashboard com Grafana Se você já usa Grafana, pode enviar as métricas via Prometheus ou InfluxDB. Um exemplo usando a biblioteca `prometheus_client` em Python: ```python from prometheus_client import Counter, Histogram, start_http_server # Metricas Prometheus consultas_total = Counter( 'cpfhub_consultas_total', 'Total de consultas a API CPFHub', ['status_code'] ) latencia_histogram = Histogram( 'cpfhub_latencia_segundos', 'Latencia das consultas em segundos', buckets=[0.1, 0.25, 0.5, 0.75, 1.0, 1.5, 2.0, 5.0, 10.0] ) def consultar_cpf_com_metricas(cpf): headers = { 'x-api-key': 'SUA_CHAVE_DE_API', 'Accept': 'application/json' } with latencia_histogram.time(): response = requests.get( f'https://api.cpfhub.io/cpf/{cpf}', headers=headers, timeout=15 ) consultas_total.labels(status_code=response.status_code).inc() return response.json() # Expor metricas na porta 9090 start_http_server(9090) ``` No Grafana, configure o Prometheus como data source e crie painéis para: * **Taxa de requisições por minuto** -- `rate(cpfhub_consultas_total[5m])` * **Latência P95** -- `histogram_quantile(0.95, cpfhub_latencia_segundos_bucket)` * **Taxa de erro** -- `rate(cpfhub_consultas_total{status_code!="200"}[5m])` --- ## Monitorando o consumo mensal Acompanhe o consumo em relação ao volume do seu plano para projetar custos. A CPFHub.io não bloqueia consultas ao atingir o limite — consultas excedentes são cobradas a R$0,15 cada, então o dashboard serve para controlar gastos, não para evitar bloqueios: | Plano | Limite mensal | Alerta de custo sugerido | | --- | --- | --- | | Gratuito | 50 consultas | 80% (40 consultas) | | Pro | 1.000 consultas | 80% (800 consultas) | | Corporativo | Personalizado | 80% do limite acordado | ```python def verificar_consumo(redis_client, limite_mensal): mes_atual = datetime.utcnow().strftime('%Y-%m') # Somar todos os dias do mes chaves = redis_client.keys(f'cpf:total:{mes_atual}-*') total_mes = sum(int(redis_client.get(k) or 0) for k in chaves) percentual = (total_mes / limite_mensal) * 100 return { 'consumido': total_mes, 'limite': limite_mensal, 'percentual': round(percentual, 2), 'alerta_custo': percentual >= 80 } ``` --- ## Painéis recomendados Para um dashboard completo, inclua: * **Consultas por hora** -- Gráfico de barras mostrando distribuição temporal. * **Taxa de sucesso (gauge)** -- Indicador visual de saúde (verde > 99%, amarelo > 95%, vermelho < 95%). * **Latência P95 (linha)** -- Evolução temporal da latência. * **Erros por tipo** -- Pizza ou barras empilhadas (400, 401, 500). * **Consumo mensal** -- Barra de progresso com alerta de custo. * **Últimos erros** -- Tabela com os erros mais recentes para investigação. --- ## Perguntas frequentes ### Quais métricas são mais importantes em um dashboard de API de CPF? As mais críticas são taxa de sucesso (respostas 200), latência P95 e volume de consultas por dia. A taxa de sucesso abaixo de 99% indica problema de integração; o P95 acima de 1,5s sugere degradação de performance. O volume diário permite projetar o custo mensal antes que o excedente se acumule. ### Como o dashboard ajuda a controlar os custos da API? A CPFHub.io cobra R$0,15 por consulta excedente ao limite do plano — a API não bloqueia. Um painel de consumo mensal com alerta em 80% do limite avisa com antecedência suficiente para ajustar o volume de consultas ou fazer upgrade de plano antes de acumular custo extra. ### Com que frequência devo coletar métricas da API de CPF? Colete por requisição, não por sondagem. O middleware de instrumentação registra latência e status a cada chamada, sem overhead significativo. Para o dashboard, agregue por hora para tendências e por dia para controle de custo — dados por minuto são úteis apenas durante investigação de incidentes. ### É necessário usar Grafana para monitorar a API de CPF? Não. O endpoint `/api/dashboard/resumo` do exemplo em Flask já entrega os dados para qualquer frontend — um painel em HTML simples com Chart.js ou Recharts atende bem projetos menores. Grafana é recomendado quando você já tem stack Prometheus/InfluxDB ou precisa de alertas automáticos por e-mail ou Slack. ### Leia também - [API de CPF grátis para desenvolvedores: como começar em 5 minutos](https://cpfhub.io/blog/api-cpf-gratis-desenvolvedores-comecar-5-minutos) - [SLA de API de CPF: níveis de disponibilidade e o que exigir do seu provedor](https://cpfhub.io/blog/sla-api-cpf-niveis-disponibilidade) - [Como medir a latência da API de CPF e otimizar a performance](https://cpfhub.io/blog/como-medir-a-latencia-da-api-de-cpf-e-otimizar-a-performance) - [Diferença entre validação de CPF e consulta de CPF: quando usar cada uma](https://cpfhub.io/blog/diferenca-entre-validacao-de-cpf-e-consulta-de-cpf-quando-usar-cada-uma) --- ## Conclusão Um dashboard de monitoramento transforma dados brutos em visibilidade acionável. Com métricas de consumo, latência e erros, você opera sua integração com a API de CPF de forma proativa, identificando problemas antes que afetem seus usuários e controlando custos antes que o excedente surpreenda. Cadastre-se em [cpfhub.io](https://www.cpfhub.io/) — 50 consultas mensais gratuitas, sem cartão de crédito.