Como criar um dashboard de monitoramento para consumo de API de 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 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:

Coletando métricas com middleware

O primeiro passo é instrumentar cada chamada à API para registrar métricas. Veja um exemplo em 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:

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:

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:

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.

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 — 50 consultas mensais gratuitas, sem cartão de crédito.