Métricas na Observabilidade: tipos, séries temporais e OpenTelemetry

Autor: Pedro Tebaldi PM do KeepGreen| Revisão técnica: Ednilson Correa SRE

Publicado dez/2025Atualizado ago/2026

No OpenTelemetry, as métricas nascem de três instrumentos: Counter, Gauge e Histogram. Cada um mede uma coisa diferente e cobra um preço diferente em séries temporais. Antes deles, porém, vale fixar o lugar da métrica entre os pilares da observabilidade. Enquanto os logs narram o evento e os traces mapeiam a requisição, a métrica mede o sistema ao longo do tempo.

Em ambientes de produção modernos, métricas são a primeira camada de detecção de problemas. Um spike de latência, uma queda de throughput ou um aumento de taxa de erro — todos aparecem nas métricas antes que qualquer usuário abra um ticket de suporte. Portanto, a velocidade e a granularidade da coleta determinam diretamente o MTTD de um time.

Este guia mostra os três instrumentos em código, o que muda no nome ao exportar para o Prometheus e quanto cada um custa em séries. Tudo medido em laboratório, com as versões declaradas.

O que são métricas na observabilidade?

Métricas são medidas numéricas do comportamento e estado de um sistema, coletadas ao longo do tempo. Cada ponto de dado é um par (timestamp, valor) associado a um conjunto de labels que descrevem o contexto da medição — qual serviço, qual instância, qual endpoint.

Diferentemente dos logs — que capturam eventos discretos com texto completo — métricas são otimizadas para armazenamento e análise matemática. Uma métrica de latência não armazena o detalhe de cada requisição: armazena a distribuição estatística (p95, p99) sobre janelas de tempo configuráveis.

Tipos de métricas

Counter (Contador)

Counter é o valor que só cresce e nunca diminui. Servem de exemplo o total de requisições recebidas, o total de erros e o total de bytes transmitidos. Na análise, o que importa é a taxa de mudança — “quantas requisições por segundo?” —, não o valor absoluto.

Em Prometheus, counters terminam convencionalmente com _total: http_requests_total, errors_total. Já o operador rate() converte o counter em uma taxa por segundo sobre uma janela de tempo.

Gauge (Medidor)

Gauge é o valor que sobe e desce livremente. Uso atual de CPU, memória disponível e número de conexões abertas entram nessa categoria. Ou seja, o gauge representa o estado de um recurso num momento específico.

Gauges são a métrica mais intuitiva e, ao mesmo tempo, a mais propensa a gerar fadiga de alertas com thresholds estáticos. Um CPU de 90% durante um job agendado é normal; o mesmo valor fora desse horário é uma anomalia.

Histogram

Histogram distribui os valores observados em buckets predefinidos. Para latência, é o instrumento ideal. Em vez de guardar o tempo de cada requisição, ele conta quantas ficaram abaixo de cada fronteira: 0.05s, 0.1s, 0.5s, 1s e assim por diante.

Com o histogram, você calcula percentis como p95 e p99, as métricas de latência mais relevantes para SLOs. Dessa forma, a experiência dos usuários mais lentos aparece, em vez de sumir atrás da média.

Summary

Similar ao histogram, mas calcula os quantis no cliente em vez de no servidor de métricas. Tem menor overhead no servidor mas não permite agregar quantis de múltiplas instâncias — limitação importante em ambientes com múltiplas réplicas do mesmo serviço.

Séries temporais e labels

Toda métrica vive no backend como série temporal: uma sequência de pontos (timestamp, valor) associada a um conjunto de labels. Ou seja, a combinação do nome da métrica com seus labels define uma série única.

Por exemplo, http_requests_total com os labels method="GET" e status="200" é uma série diferente de http_requests_total com method="POST" e status="500".

Entre os fatores de performance de um sistema de métricas, o principal é a cardinalidade de labels. Isto é, o número de combinações únicas possíveis. Labels de alta cardinalidade, como user_id ou request_id, criam milhões de séries e sobrecarregam o storage. Por isso, o padrão é usar labels de baixa cardinalidade: método HTTP, código de status, nome do serviço, região.

 
No papel, porém, cardinalidade é fácil de subestimar. No laboratório da OpServices, quatro instrumentos e 600 pedidos processados produziram 267 séries temporais. Contá-las leva um comando:

curl -s localhost:8890/metrics | grep -v '^#' \
  | cut -d'{' -f1 | sort | uniq -c | sort -rn

    190 pedidos_por_cliente_total
     64 pedido_duracao_milliseconds_bucket
      4 pedidos_processados_total
      4 pedido_duracao_milliseconds_sum
      4 pedido_duracao_milliseconds_count
      1 target_info
      1 fila_tamanho

O rótulo cliente_id, sozinho, respondeu por 190 das 267 séries. Em outras palavras, 71% do custo veio de um campo que ninguém consulta em dashboard. Em contrapartida, os três instrumentos de negócio, com rótulos de baixa cardinalidade, somaram 77 séries.

Daí sai uma régua defensável: rótulo cujo número de valores distintos cresce junto com o tráfego não é rótulo, é log. Por exemplo, identificador de pedido, de cliente, de sessão e de requisição pertencem ao trace ou ao log, onde a busca é indexada.

Os 4 Sinais de Ouro e os métodos USE e RED

Como conjunto mínimo de métricas para todo serviço, o SRE do Google definiu os 4 Sinais de Ouro: latência (tempo de resposta), tráfego (volume de requisições), erros (taxa de falhas) e saturação (quão próximo do limite o sistema está).

Para infraestrutura, o método USE — Utilization, Saturation, Errors — fornece um framework equivalente. Já em serviços orientados a requisições, o método RED — Rate, Errors, Duration — simplifica os 4 Sinais de Ouro. Não à toa, domina as arquiteturas de microsserviços.

OpenTelemetry e a padronização de métricas

OpenTelemetry define uma API e um SDK de métricas agnósticos ao backend. Assim, instrumentar com OpenTelemetry Metrics permite exportar os mesmos dados para Prometheus, Datadog, Grafana Mimir ou qualquer outro backend, sem alterar o código.

Além da API, o OpenTelemetry publica convenções semânticas para métricas: nomes e labels padronizados para tipos comuns de serviço, como HTTP, banco de dados e mensageria. Dessa forma, serviços diferentes passam a falar o mesmo vocabulário, e dashboards e alertas viram peça reutilizável na organização.

 
Até aqui, a teoria. Vejamos os três instrumentos em código, no laboratório da OpServices. As versões: SDK Python 1.44.0 do OpenTelemetry e Collector 0.139.0, em 29 de agosto de 2026.

from opentelemetry import metrics
from opentelemetry.exporter.otlp.proto.http.metric_exporter import OTLPMetricExporter
from opentelemetry.sdk.metrics import MeterProvider
from opentelemetry.sdk.metrics.export import PeriodicExportingMetricReader

leitor = PeriodicExportingMetricReader(
    OTLPMetricExporter(endpoint="http://otel-collector-metricas:4318/v1/metrics"),
    export_interval_millis=5000,
)
metrics.set_meter_provider(MeterProvider(metric_readers=[leitor]))
medidor = metrics.get_meter("opservices.laboratorio", "1.0.0")

# COUNTER -- so cresce.
pedidos = medidor.create_counter(
    name="pedidos.processados",
    unit="{pedido}",
    description="Total de pedidos processados pela API",
)

# UPDOWNCOUNTER -- sobe e desce. E o gauge acumulado do OpenTelemetry.
fila = medidor.create_up_down_counter(
    name="fila.tamanho",
    unit="{item}",
    description="Pedidos aguardando processamento na fila",
)

# HISTOGRAM -- distribuicao, para percentil.
duracao = medidor.create_histogram(
    name="pedido.duracao",
    unit="ms",
    description="Tempo de processamento de um pedido",
)

# A cada pedido:
fila.add(1, {"servico": "loja-api"})
pedidos.add(1, {"metodo": metodo, "status": status})
duracao.record(ms, {"metodo": metodo, "status": status})
fila.add(-1, {"servico": "loja-api"})

Repare que o código não menciona Prometheus em nenhuma linha. Ele declara apenas o instrumento, a unidade e a descrição; quem decide o destino é o exportador.

Do outro lado do Collector, no entanto, os nomes não chegam iguais. Esta é a saída real do endpoint do exporter, depois de 600 pedidos processados:

# HELP pedidos_processados_total Total de pedidos processados pela API
# TYPE pedidos_processados_total counter
pedidos_processados_total{job="loja-api",metodo="GET",status="200",…} 384
pedidos_processados_total{job="loja-api",metodo="GET",status="500",…} 16
pedidos_processados_total{job="loja-api",metodo="POST",status="200",…} 192
pedidos_processados_total{job="loja-api",metodo="POST",status="500",…} 8

# TYPE fila_tamanho gauge
fila_tamanho{job="loja-api",servico="loja-api",…} 0

# TYPE pedido_duracao_milliseconds histogram
pedido_duracao_milliseconds_bucket{metodo="GET",status="200",…,le="5"} 306
pedido_duracao_milliseconds_bucket{metodo="GET",status="200",…,le="10"} 383
pedido_duracao_milliseconds_bucket{metodo="GET",status="200",…,le="25"} 384
pedido_duracao_milliseconds_bucket{metodo="GET",status="200",…,le="+Inf"} 384
pedido_duracao_milliseconds_sum{metodo="GET",status="200",…} 678.2331009453628
pedido_duracao_milliseconds_count{metodo="GET",status="200",…} 384

Três regras aparecem aí. O ponto vira sublinhado, porque o Prometheus não aceita ponto no nome. Além disso, o counter ganha o sufixo _total, que o código nunca escreveu. Por fim, a unidade ms entra no nome como _milliseconds, enquanto a unidade de anotação {pedido} fica de fora.

Um alerta escrito com o nome OTel, portanto, não casa com série nenhuma no Prometheus. A tabela abaixo resume o que o exportador fez com cada instrumento e quanto cada um custou em séries.

Ainda sobre o histogram, os buckets merecem atenção à parte. Com as fronteiras padrão do SDK, 306 das 384 observações de GET/200 caíram no primeiro bucket útil, o de 5 ms. Assim, abaixo disso não há resolução alguma, e o p95 só pode ser localizado entre 5 e 10 ms. Em serviço de latência baixa, portanto, definir as fronteiras à mão deixa de ser refinamento e vira pré-requisito.

Conclusão

Métricas são o pilar de velocidade da observabilidade — o tipo de dado mais eficiente para detectar anomalias em tempo real e alimentar alertas de alta qualidade. Juntos, counters, gauges e histogramas cobrem o monitoramento de qualquer serviço, da latência de APIs ao uso de recursos de infraestrutura.

Na prática, a chave está na disciplina de labels: baixa cardinalidade, campos consistentes e alinhamento com as convenções semânticas do OpenTelemetry. Com essas bases, as métricas se correlacionam com logs e traces e completam o tripé de observabilidade. Se quiser estruturar essa disciplina no seu ambiente, fale com nossos especialistas.