# Como criar dashboards de uso e métricas para consumo da API de CPF > Crie dashboards para monitorar o consumo da API de CPF em tempo real. Visualize métricas de uso, latência e erros com exemplos práticos. **Publicado:** 14/04/2025 **Autor:** Redação CPFHub.io **URL:** https://cpfhub.io/blog/criar-dashboards-uso-metricas-consumo-api-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: | Métrica | Tipo | Frequência de coleta | Alerta quando | |---|---|---|---| | Total de requisições | Contador | Cada chamada | > limite mensal | | Taxa de sucesso | Percentual | A cada minuto | < 95% | | Latência média | Gauge | Cada chamada | > 1200ms | | Latência P95 | Gauge | A cada minuto | > 2000ms | | Erros por tipo | Contador | Cada chamada | > 5% do total | | Consumo de cota | Gauge | A cada hora | > 80% | | Custo extra acumulado | Gauge | A cada hora | > R$ 5,00 | | Cache hit rate | Percentual | A cada minuto | < 50% | | Consultas excedentes | Contador | Cada chamada além da cota | Qualquer valor > 0 | --- ## Coletando métricas com Python Implemente um coletor de métricas que intercepta todas as chamadas à API: ```python 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](https://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](https://prometheus.io/) 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. ### Leia também - [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 monitorar consumo e cotas de APIs gratuitas de CPF](https://cpfhub.io/blog/monitorar-consumo-cotas-apis-gratuitas-cpf) - [Como configurar alertas de limite de uso em APIs gratuitas de CPF](https://cpfhub.io/blog/configurar-alertas-limite-uso-apis-gratuitas-cpf) - [API de CPF grátis para desenvolvedores: como começar em 5 minutos](https://cpfhub.io/blog/api-cpf-gratis-desenvolvedores-comecar-5-minutos) --- ## 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](https://www.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.