Como criar dashboards de uso e métricas para consumo da API de CPF

Um dashboard de consumo da API de CPF mostra em tempo real quantas consultas foram realizadas, qual a latência média, quanto custa o uso acumulado e quando a cota mensal será esgotada — permitindo agir antes que o excedente gere surpresas na fatura.

Introdução

Monitorar o consumo de uma API de CPF sem um dashboard é como dirigir sem painel de instrumentos. Você sabe que está em movimento, mas desconhece a velocidade, o combustível restante e se há algum alerta ativo. Dashboards de uso fornecem visibilidade em tempo real sobre a saúde da integração, permitindo identificar problemas antes que impactem os usuários.

Métricas essenciais para monitorar

Defina quais métricas são importantes antes de construir o dashboard:

Coletando métricas com Python

Implemente um coletor de métricas que intercepta todas as chamadas à API:

import requests
import time
import json
from datetime import datetime
from collections import defaultdict
from statistics import mean, quantiles

CUSTO_EXCEDENTE_POR_CONSULTA = 0.15  # R$ 0,15 por consulta além da cota

class CPFMetricsCollector:
    def __init__(self, api_key: str, cota_mensal: int = 1000):
    self.api_key = api_key
    self.cota_mensal = cota_mensal
    self.metricas = {
    "total_requisicoes": 0,
    "sucessos": 0,
    "erros": defaultdict(int),
    "latencias": [],
    "cache_hits": 0,
    "cache_misses": 0,
    "por_hora": defaultdict(int),
    "consultas_excedentes": 0,
    "custo_extra_acumulado": 0.0
    }
    self.cache = {}

    def consultar(self, cpf: str) -> dict:
    cpf_limpo = cpf.replace(".", "").replace("-", "")
    hora_atual = datetime.now().strftime("%Y-%m-%d %H:00")
    self.metricas["por_hora"][hora_atual] += 1

    # Verificar cache
    if cpf_limpo in self.cache:
    self.metricas["cache_hits"] += 1
    return self.cache[cpf_limpo]

    self.metricas["cache_misses"] += 1
    self.metricas["total_requisicoes"] += 1

    # Rastrear consultas excedentes (cobrança de R$ 0,15/consulta extra)
    if self.metricas["total_requisicoes"] > self.cota_mensal:
    self.metricas["consultas_excedentes"] += 1
    self.metricas["custo_extra_acumulado"] += CUSTO_EXCEDENTE_POR_CONSULTA

    inicio = time.time()
    try:
    response = requests.get(
    f"https://api.cpfhub.io/cpf/{cpf_limpo}",
    headers={"x-api-key": self.api_key},
    timeout=10
    )
    latencia = (time.time() - inicio) * 1000
    self.metricas["latencias"].append(latencia)

    if response.status_code == 200 and response.json()["success"]:
    self.metricas["sucessos"] += 1
    dados = response.json()["data"]
    self.cache[cpf_limpo] = dados
    return dados
    else:
    self.metricas["erros"][f"http_{response.status_code}"] += 1
    except requests.Timeout:
    self.metricas["erros"]["timeout"] += 1
    except requests.ConnectionError:
    self.metricas["erros"]["connection"] += 1
    return None

    def gerar_dashboard(self) -> dict:
    total = self.metricas["total_requisicoes"]
    latencias = self.metricas["latencias"]

    dashboard = {
    "timestamp": datetime.now().isoformat(),
    "resumo": {
    "total_requisicoes": total,
    "taxa_sucesso": f"{(self.metricas['sucessos']/max(total,1))*100:.1f}%",
    "latencia_media": f"{mean(latencias):.0f}ms" if latencias else "N/A",
    "latencia_p95": f"{quantiles(latencias, n=20)[-1]:.0f}ms" if len(latencias) > 1 else "N/A",
    "cache_hit_rate": f"{(self.metricas['cache_hits']/max(self.metricas['cache_hits']+self.metricas['cache_misses'],1))*100:.1f}%",
    "consultas_excedentes": self.metricas["consultas_excedentes"],
    "custo_extra_acumulado": f"R$ {self.metricas['custo_extra_acumulado']:.2f}"
    },
    "erros": dict(self.metricas["erros"]),
    "uso_por_hora": dict(self.metricas["por_hora"])
    }
    return dashboard

    def imprimir_dashboard(self):
    d = self.gerar_dashboard()
    print("\n" + "=" * 50)
    print(" DASHBOARD DE USO - API CPF")
    print("=" * 50)
    print(f" Timestamp: {d['timestamp']}")
    print(f" Requisições: {d['resumo']['total_requisicoes']}")
    print(f" Taxa sucesso: {d['resumo']['taxa_sucesso']}")
    print(f" Latência média: {d['resumo']['latencia_media']}")
    print(f" Latência P95: {d['resumo']['latencia_p95']}")
    print(f" Cache hit rate: {d['resumo']['cache_hit_rate']}")
    print(f" Consultas excedentes: {d['resumo']['consultas_excedentes']}")
    print(f" Custo extra acumulado: {d['resumo']['custo_extra_acumulado']}")
    if d["erros"]:
    print(f" Erros: {json.dumps(d['erros'])}")
    print("=" * 50)

# Exemplo de uso
collector = CPFMetricsCollector("SUA_CHAVE_AQUI", cota_mensal=1000)
collector.consultar("12345678909")
collector.consultar("12345678909") # Cache hit
collector.consultar("98765432100")
collector.imprimir_dashboard()

Exportando métricas para ferramentas de visualização

Integre as métricas coletadas com plataformas de dashboard populares:

• Grafana + Prometheus -- exporte métricas no formato Prometheus e crie painéis interativos no Grafana com gráficos de série temporal
• Datadog -- utilize a biblioteca dogstatsd para enviar métricas customizadas diretamente ao Datadog
• CloudWatch -- em ambientes AWS, publique métricas customizadas com boto3 para visualização nativa
• ELK Stack -- envie logs estruturados para o Elasticsearch e crie visualizações no Kibana
• Google Sheets -- para equipes menores, exporte métricas diárias para uma planilha compartilhada

Painéis recomendados para o dashboard

Organize o dashboard em painéis temáticos para facilitar a análise:

• Painel de saúde -- taxa de sucesso, taxa de erro e status da API em um semáforo visual verde/amarelo/vermelho
• Painel de performance -- gráficos de latência média, P95 e P99 ao longo do tempo para identificar degradações
• Painel de consumo -- uso de cota atual, projeção de esgotamento e comparativo com meses anteriores
• Painel de custo -- consultas excedentes acumuladas no mês, custo extra projetado e histórico de faturamento
• Painel de eficiência -- cache hit rate, requisições por segundo e volume total por hora/dia
• Painel de alertas -- histórico de alertas disparados, tempo de resolução e tendências

Automatizando relatórios periódicos

Além do dashboard em tempo real, gere relatórios automáticos:

• Relatório diário -- resumo das métricas do dia enviado por e-mail às 8h para a equipe de operações
• Relatório semanal -- análise de tendências com comparativo semanal e recomendações de otimização
• Relatório mensal -- visão gerencial com projeção de custos, crescimento de uso e planejamento de capacidade
• Alerta em tempo real -- notificações imediatas quando métricas ultrapassam limiares críticos

Perguntas frequentes

Quais métricas são mais importantes para monitorar no dashboard de uma API de CPF?

As três métricas críticas são: taxa de sucesso (deve ficar acima de 95%), latência P95 (referência da CPFHub.io é ~900ms — alertar acima de 2s) e consumo de cota acumulado no mês. A partir de 80% da cota, é importante avaliar se o volume cresce linearmente — a API cobra R$ 0,15 por consulta excedente automaticamente, sem bloquear requisições.

Como o dashboard ajuda a controlar o custo com a API de CPF?

O dashboard rastreia o número de consultas excedentes — aquelas realizadas além do limite do plano contratado. No plano Pro (1.000 consultas/mês), cada consulta adicional custa R$ 0,15. Com um painel de custo extra acumulado atualizado em tempo real, a equipe pode decidir aumentar o plano ou ativar cache agressivo antes que o excedente se torne significativo. O faturamento é gerenciado em app.cpfhub.io/settings/billing.

Vale a pena implementar cache local para reduzir o consumo da API?

Sim, especialmente quando o mesmo CPF é consultado múltiplas vezes no mesmo fluxo. Um cache com TTL de 1 hora para CPFs já verificados pode reduzir o volume de chamadas à API em 30% a 60% dependendo do padrão de uso. O código de exemplo neste artigo já inclui uma implementação básica de cache em memória — para produção, considere Redis com expiração configurável.

Como detectar rapidamente quando a integração começa a degradar?

Configure alertas para três sinais de alerta precoce: latência P95 acima de 2.000ms, taxa de sucesso abaixo de 95%, e taxa de erros de timeout acima de 2% do total de requisições. Ferramentas como Prometheus e Grafana permitem criar alertas granulares com notificação por Slack, e-mail ou PagerDuty, garantindo que a equipe seja acionada antes do impacto chegar ao usuário final.

Conclusão

Dashboards de uso transformam dados brutos de consumo da API em insights acionáveis que protegem a saúde da integração e controlam custos. Com métricas bem definidas — especialmente consumo de cota e custo extra acumulado — coleta automatizada e visualizações claras, sua equipe mantém controle total sobre a operação. A CPFHub.io não bloqueia ao atingir o limite: cobra R$ 0,15 por consulta excedente, o que torna o monitoramento proativo ainda mais valioso para evitar surpresas no faturamento.

Cadastre-se em cpfhub.io — 50 consultas mensais gratuitas, sem cartão de crédito — e comece a monitorar sua integração com visibilidade total sobre consumo e custos.