O cliente Prometheus expõe métricas em um formato que o servidor coleta. Uma boa métrica responde a uma pergunta operacional, como taxa de erros ou duração de uma operação, sem carregar dados pessoais.

O modelo é pull: em intervalos configurados, o Prometheus consulta um endpoint HTTP e registra uma amostra de cada série. Uma série é definida pelo nome da métrica e pelo conjunto completo de labels. Mudar qualquer valor de label cria outra série. Essa propriedade torna as consultas expressivas, mas também explica por que cardinalidade precisa ser planejada antes da instrumentação.

Escolher o tipo correto

python -m pip install prometheus-client
from prometheus_client import Counter, Histogram

REQUISICOES = Counter(
    "app_requisicoes_total",
    "Total de requisições",
    ["metodo", "resultado"],
)
DURACAO = Histogram(
    "app_requisicao_duracao_segundos",
    "Duração da requisição",
    ["rota"],
)


def processar() -> None:
    with DURACAO.labels(rota="/pedidos").time():
        executar()
    REQUISICOES.labels(metodo="POST", resultado="sucesso").inc()

Counter mede eventos acumulados. Gauge representa valor atual. Histogram distribui observações em buckets e permite calcular quantis no servidor. Escolha buckets próximos da expectativa real de latência.

Um Counter deve representar eventos que acumulam, como requisições ou falhas. O cliente acrescenta o sufixo _total na exposição quando apropriado. Não use counter para um valor que diminui. Um Gauge atende quantidade de trabalhos ativos, temperatura ou tamanho atual de uma fila, mas pode ser difícil de agregar entre réplicas se o significado não estiver claro.

Um Histogram mantém contagens cumulativas por limite, além de soma e total de observações. Isso permite calcular quantis no PromQL e agregar instâncias. Um Summary calcula estatísticas no cliente; quantis produzidos por instâncias diferentes não podem ser agregados da mesma forma. Para latência distribuída, Histogram costuma ser uma escolha mais flexível.

Modelar uma métrica antes de implementá-la

Comece pela pergunta e pela consulta que responderá. Para taxa de erros HTTP, você precisa de um counter com resultado ou código agrupado. Para latência, precisa de um histogram e buckets alinhados aos objetivos de serviço. Para fila acumulada, um gauge pode representar o valor atual, enquanto counters de entradas e saídas ajudam a explicar a tendência.

Use nomes com unidade e tipo claros:

  • _seconds para duração em segundos;
  • _bytes para tamanho;
  • _total para contadores;
  • prefixo da aplicação ou subsistema para evitar colisões.

Não codifique a label no nome, como pedidos_post_sucesso_total, se as dimensões formam um conjunto pequeno e útil. Também não crie labels que nunca serão usadas em consultas ou alertas. Cada dimensão multiplica o número possível de séries.

Definir buckets pelo objetivo operacional

Os buckets padrão raramente representam todos os serviços. Se um endpoint deve responder em até 300 ms, inclua limites ao redor dessa região e cubra a cauda esperada:

from prometheus_client import Histogram

LATENCIA = Histogram(
    "checkout_duracao_segundos",
    "Duração do checkout",
    ["resultado"],
    buckets=(0.05, 0.1, 0.2, 0.3, 0.5, 1.0, 2.0, 5.0),
)

Buckets demais multiplicam séries; poucos limites escondem a distribuição. Analise dados reais e ajuste em uma mudança planejada. Alterar buckets reinicia a continuidade lógica das séries correspondentes, portanto documente a mudança em dashboards e regras.

Para medir a fração abaixo de 300 ms, use a taxa do bucket le="0.3" dividida pela taxa de _count. Para percentis aproximados, histogram_quantile opera sobre as taxas dos buckets. A precisão depende dos limites: o servidor interpola dentro do bucket, não recupera os valores individuais.

Expor o endpoint com segurança

O pacote oferece start_http_server para scripts e workers simples:

from prometheus_client import start_http_server

start_http_server(8000, addr="127.0.0.1")

Em aplicações web, use a integração adequada ao servidor WSGI ou ASGI e mantenha um único endpoint /metrics. Não inicie um servidor adicional em cada worker sem compreender o modelo multiprocess. Restrinja a interface de escuta e permita acesso somente ao scraper ou à rede de monitoramento. TLS e autenticação podem ficar no proxy ou service mesh, conforme a infraestrutura.

O endpoint não deve receber tráfego público por conveniência. Mesmo sem credenciais explícitas, métricas revelam nomes de rotas, dependências, versões em alguns coletores e padrões de carga. Não coloque secrets em labels ou descrições e evite que parâmetros de requisição cheguem aos nomes.

Compreender processos e workers

Em um processo único, o registry padrão reúne as métricas e os coletores de runtime. Em servidores com vários processos, cada worker mantém memória própria. Somar ou expor apenas um deles produz dados incompletos. O modo multiprocess do cliente usa arquivos em um diretório compartilhado e exige configuração no ciclo de vida do servidor.

Consulte a documentação da integração antes de habilitá-lo: defina o diretório antes de importar a aplicação, limpe-o no início de uma implantação e marque processos mortos conforme o servidor. Não reutilize o diretório entre duas instâncias. Algumas métricas e funcionalidades têm limitações nesse modo. Se a arquitetura permitir, um worker por processo e coleta individual pode ser mais simples.

Jobs muito curtos não ficam disponíveis tempo suficiente para scrape. O Pushgateway atende um conjunto restrito de jobs batch em nível de serviço. Não o use como substituto geral do modelo pull nem envie uma série por execução. Agrupe pela identidade estável do job e deixe que o gateway reflita o último resultado significativo.

Controlar labels e cardinalidade

Controlar labels e acesso

Labels devem ter conjunto pequeno e previsível. Não use URL completa, mensagem de erro, e-mail, token ou ID de usuário. Normalize rotas como /pedidos/{id} para não criar uma série por recurso.

Estime o limite antes de publicar: métodos × rotas × resultados × réplicas × buckets. Dez rotas, quatro resultados, cinco réplicas e dez buckets já produzem centenas de séries apenas para um histogram. IDs de usuário ou textos livres tornam o conjunto praticamente ilimitado.

Inicialize combinações esperadas quando a ausência de série poderia confundir um alerta. Um counter sem observações ainda não existe para aquela label. Criar previamente um pequeno conjunto, como resultado="sucesso" e resultado="erro", faz o zero aparecer. Não pré-crie combinações grandes.

Evite labels redundantes que o Prometheus já adiciona no alvo, como host ou ambiente, salvo quando a arquitetura exige. Labels estáticas de infraestrutura geralmente pertencem à configuração de scrape ou ao service discovery, não ao código da aplicação.

Testar a instrumentação

Use um CollectorRegistry isolado para não misturar métricas globais no teste:

from prometheus_client import CollectorRegistry, Counter, generate_latest

registry = CollectorRegistry()
eventos = Counter("teste_eventos_total", "Eventos", registry=registry)
eventos.inc()

texto = generate_latest(registry).decode("utf-8")
assert "teste_eventos_total 1.0" in texto

Teste o comportamento, não apenas a existência do nome. Verifique se sucesso e falha incrementam exatamente uma vez, se o timer encerra em exceções e se os valores de labels pertencem ao conjunto permitido. Um teste de endpoint deve conferir content type e acesso de rede conforme a aplicação.

Na revisão, procure instrumentação no caminho errado. Incrementar antes de concluir uma operação pode contar sucesso quando houve exceção. Medir somente o bloco interno pode omitir espera relevante. Defina claramente o início e o fim do que a métrica representa.

Proteja o endpoint de métricas conforme a rede e a infraestrutura. Mesmo sem segredos, nomes de serviços e padrões de tráfego são informações operacionais. Teste se as métricas aparecem após a ação esperada e se falhas também são contabilizadas.

Combine métricas com traces do OpenTelemetry e logs estruturados. Não duplique cada campo em todos os sinais.

A documentação oficial do Prometheus Python Client e as práticas oficiais de nomes de métricas, consultadas em 22 de julho de 2026, descrevem tipos, exportação, integrações e convenções. O principal cuidado de design é a cardinalidade: poucas labels bem escolhidas produzem métricas mais sustentáveis.