Métricas são a base quantitativa da observabilidade - os números que mostram como o sistema está funcionando.
Este é o terceiro artigo da série sobre convenções de nomenclatura no OpenTelemetry - nas partes anteriores, já vimos como nomear corretamente os spans e como enriquecê-los com atributos. Agora é hora de falar sobre como nomear métricas de forma clara e útil.
Ao contrário dos spans, que contam histórias sobre eventos, as métricas mostram dados quantitativos: quanto, com que frequência, com que rapidez.
Mas - e isso é importante - nomes bem pensados para métricas são tão cruciais quanto para spans. E os mesmos princípios se aplicam: o “quem” pertence aos atributos, não ao nome.
O que podemos aprender com sistemas tradicionais
Antes de falar sobre o OpenTelemetry, vejamos como as métricas eram nomeadas anteriormente.
Por exemplo, no Kubernetes, é comum encontrar padrões como:
scheduler_schedule_attempts_total
container_cpu_usage_seconds_total
kubelet_volume_stats_used_bytes
Há um padrão claro aqui: componente + recurso + ação + unidade.
Ou seja, o nome da métrica já inclui o nome do serviço. Isso fazia sentido em modelos de dados antigos, com pouco contexto disponível.
No entanto, esse método traz vários problemas:
- duplicação de métricas entre serviços, poluindo o backend de observabilidade;
- impossibilidade de agregar valores entre componentes;
- nomes fortemente acoplados a serviços específicos;
- cada novo serviço exige novos nomes de métricas.
Erro principal: nome do serviço dentro do nome da métrica
A principal regra do OpenTelemetry:
não inclua o nome do serviço no nome da métrica.
Por exemplo, imagine que você tem um serviço de pagamentos. É tentador criar métricas como:
payment.latency.p95
payment.error.rate
Mas isso está errado.
O nome do serviço já está disponível no contexto - no atributo service.name.
Forma correta:
http.server.request.duration (service.name=payment)
error.rate (service.name=payment)
Por que isso é melhor?
Porque agora você pode agregar dados de todos os serviços facilmente:
sum(transaction.count{service.name="payment"}) # Apenas do serviço payment
Se o nome do serviço estivesse “embutido” na métrica, seria necessário criar consultas separadas para cada serviço.
O modelo de contexto do OpenTelemetry
No OpenTelemetry, o contexto não fica escondido no nome - ele é estruturado em múltiplos níveis:
recursos, escopo (instrumentation scope) e atributos.
Abordagem tradicional (estilo Prometheus):
user_service_auth_latency_milliseconds{endpoint="/login",region="us-east"}
inventory_service_db_query_seconds{table="products",operation="select"}
Abordagem OpenTelemetry:
- Resource: service.name=payment, deployment.environment.name=prod
- Attributes: method=credit_card, status=success
auth.duration
- Resource: service.name=user
- Attributes: endpoint=/login, region=us-east
- Unit: ms
db.client.operation.duration
- Resource: service.name=inventory
- Attributes: db.sql.table=products, db.operation=select
- Unit: s
Esse formato segue a especificação do OpenTelemetry, onde o contexto é distribuído entre camadas em vez de ser “achatado” no nome.
Unidades de medida não fazem parte do nome
Da mesma forma: unidades de medida não devem aparecer no nome da métrica.
Antes era assim:
memory_usage_bytes
throughput_requests_per_second
No OpenTelemetry, as unidades são especificadas separadamente:
system.memory.usage {unit: By}
http.server.request.rate {unit: {request}/s}
Vantagens:
- nomes limpos e legíveis, sem sufixos desnecessários;
- suporte ao padrão UCUM (Unified Code for Units of Measure);
- conversão automática de unidades nas plataformas de observabilidade;
- compatibilidade com todas as ferramentas OpenTelemetry.
Boas práticas de nomenclatura
Ao definir um nome de métrica, use o formato {verbo}.{objeto} - o mesmo usado para spans.
- Foque na ação, não em quem a executa.
- Não inclua o nome do serviço.
- Não adicione unidades ao nome.
- Siga as convenções semânticas do OpenTelemetry.
| Correto | Incorreto |
|---|---|
| http.server.request.duration | payment_http_requests_ms |
| db.client.operation.duration | user_service_db_queries_seconds |
| transaction.count | payment_transaction_total |
| messaging.client.sent.messages | order_service_messages_sent_total |
Vantagens de nomes limpos
- Agregação entre serviços: uma única consulta como sum(transaction.count) retorna dados de todos os serviços.
- Dashboards universais: o mesmo painel funciona para todos os microsserviços - basta filtrar por service.name.
- Menos ruído no namespace: em vez de centenas de nomes semelhantes, há apenas um (request.count), e o contexto é definido por atributos.
- Conversão automática de unidades: uma métrica request.duration com unit=ms pode ser exibida em segundos ou milissegundos.
- Compatibilidade entre instrumentação manual e automática: todas as métricas seguem o mesmo padrão semântico.
Erros comuns
- Incluir versão ou ambiente no nome: user_service_v2_latency quebra após o deploy da v3.
- Vincular nomes a infraestrutura: node_42_memory_usage perde sentido com escalabilidade dinâmica.
- Usar prefixos de ambiente (prod_, staging_) dificulta comparações.
- Colocar tecnologia no nome (nodejs_payment_memory) torna a métrica incorreta após troca de stack.
- Misturar domínios de negócio e técnicos: ecommerce_cpu_usage é um mau exemplo.
O contexto variável (versão, ambiente, instância) deve estar em atributos, não no nome.
Conclusão
Uma métrica bem nomeada é um presente para o seu “eu” do futuro.
Ela torna os dados observáveis, os dashboards reutilizáveis e os incidentes mais fáceis de compreender.
O princípio é simples:
Todo o resto - versão, serviço, ambiente - deve estar nos atributos.
Perguntas frequentes (FAQ)
- Por que é importante nomear métricas corretamente?
Um bom nome facilita a análise de dados e a criação de dashboards reutilizáveis. Métricas bem nomeadas podem ser facilmente agregadas e filtradas entre serviços. - Por que não incluir o nome do serviço na métrica?
No OpenTelemetry, o nome do serviço está no atributo service.name. Colocá-lo no nome cria duplicação e dificulta a agregação entre serviços. - Devo incluir unidades no nome?
Não. O OpenTelemetry armazena as unidades como metadados, permitindo conversões automáticas (por exemplo, segundos → milissegundos). - Qual é o formato correto para nomes de métricas?
Use um formato curto e claro: {ação}.{objeto}. Exemplo: http.server.request.duration em vez de payment_http_requests_ms. - Posso usar meus próprios nomes?
Sim, mas é recomendado seguir as convenções semânticas do OpenTelemetry para garantir compatibilidade. - Como evitar problemas ao migrar de sistemas antigos?
Separe nome e contexto: mantenha o nome limpo e coloque detalhes (serviço, ambiente, versão) como atributos. Isso simplifica a migração e unifica dashboards. - E métricas específicas de tecnologias, como PostgreSQL?
Use atributos ou escopos. Exemplo: db.client.operation.duration com db.system=postgresql. - Qual é a regra principal para nomear métricas?
O nome deve descrever o que é medido - não quem mede. O restante vai nos atributos.