Convenções de Nomes

Nomear spans, métricas e atributos de forma consistente é fundamental para manter a observabilidade útil à medida que o sistema cresce. O OpenTelemetry define convenções semânticas (semantic conventions) que padronizam esses nomes. Neste guia, vamos ver como aplicá-las na prática.

Por que convenções importam?

Sem convenções:

Equipe A: span name = "query_database"
Equipe B: span name = "db.query"
Equipe C: span name = "mysql_select"

Com convenções:

Todas as equipes: span name = "SELECT minha_tabela"
                  atributo db.system = "mysql"
                  atributo db.operation.name = "SELECT"

Convenções consistentes permitem:

• Dashboards unificados — uma query funciona para todos os serviços
• Alertas genéricos — “latência de DB > 500ms” funciona em qualquer serviço
• Correlação entre times — todos falam a mesma língua de observabilidade
• Ferramentas automáticas — backends podem gerar visualizações automaticamente

Convenções semânticas do OpenTelemetry

O OpenTelemetry mantém um conjunto de convenções semânticas que definem nomes padrão para atributos comuns. Aqui estão as mais importantes:

Atributos de recurso (Resource)

Identificam quem está emitindo telemetria:

Atributo	Descrição	Exemplo
service.name	Nome do serviço	pedidos-api
service.version	Versão do serviço	1.2.3
service.namespace	Namespace/grupo	ecommerce
deployment.environment.name	Ambiente	production
host.name	Nome do host	pod-abc123
cloud.provider	Provedor cloud	aws
cloud.region	Região	sa-east-1

Cuidado

service.name é obrigatório. Se você não definir, o SDK vai usar um nome genérico como unknown_service que torna impossível filtrar por serviço.

Atributos HTTP

Para operações HTTP (tanto client quanto server):

Atributo	Descrição	Exemplo
http.request.method	Método HTTP	GET, POST
url.path	Path da URL	/api/pedidos
http.response.status_code	Status code	200, 500
server.address	Host do servidor	api.exemplo.com
http.route	Rota (com template)	/api/pedidos/{id}

Nomes de spans HTTP:

Para spans de servidor HTTP, use o formato:

{method} {http.route}

Exemplos:

• ✅ GET /api/pedidos/{id}
• ✅ POST /api/pedidos
• ❌ GET /api/pedidos/12345 (não use IDs no nome do span!)
• ❌ handleRequest (muito genérico)
• ❌ PedidosController.buscar (implementação, não operação)

Atributos de banco de dados

Atributo	Descrição	Exemplo
db.system	Tipo do banco	postgresql, mysql, redis
db.operation.name	Operação	SELECT, INSERT, findOne
db.collection.name	Tabela/collection	pedidos, usuarios
db.namespace	Database/schema	ecommerce

Nomes de spans de DB:

{db.operation.name} {db.collection.name}

Exemplos:

• ✅ SELECT pedidos
• ✅ INSERT pagamentos
• ❌ database query (muito genérico)
• ❌ SELECT * FROM pedidos WHERE id = 123 (não inclua a query completa no nome!)

Atributos de mensageria

Atributo	Descrição	Exemplo
messaging.system	Sistema	kafka, rabbitmq, sqs
messaging.operation.type	Operação	publish, receive, process
messaging.destination.name	Tópico/fila	pedidos-criados

Nomes de spans de mensageria:

{messaging.destination.name} {messaging.operation.type}

Exemplos:

• ✅ pedidos-criados publish
• ✅ pagamentos-processados receive

Nomes de spans customizados

Para instrumentação manual, siga estas regras:

Seja descritivo mas conciso

# ✅ Bom — descreve a operação de negócio
with tracer.start_as_current_span("processar_pagamento"):
    ...

# ✅ Bom — usa hierarquia com ponto
with tracer.start_as_current_span("pedido.validar_estoque"):
    ...

# ❌ Ruim — muito genérico
with tracer.start_as_current_span("process"):
    ...

# ❌ Ruim — muito específico (contém dados variáveis)
with tracer.start_as_current_span(f"processar_pagamento_{pedido_id}"):
    ...

Regras para nomes de spans

1. Use snake_case ou dot.notation — processar_pedido ou pedido.processar
2. Nunca inclua dados variáveis — IDs, valores, timestamps vão em atributos
3. Use verbos que descrevem a ação — validar, processar, enviar, calcular
4. Mantenha cardinalidade baixa — o nome do span deve ter poucas variações possíveis

Dados variáveis vão em atributos

# ✅ Correto — dados variáveis como atributos
with tracer.start_as_current_span("processar_pedido") as span:
    span.set_attribute("pedido.id", pedido_id)
    span.set_attribute("pedido.valor", valor_total)
    span.set_attribute("cliente.id", cliente_id)

# ❌ Errado — dados variáveis no nome do span
with tracer.start_as_current_span(f"processar_pedido_{pedido_id}"):
    ...

Por que isso importa? Backends de observabilidade agrupam spans pelo nome. Se cada span tem um nome único (porque contém um ID), você não consegue agregar métricas como “tempo médio para processar pedidos”.

Nomes de métricas

Formato

{namespace}.{objeto}.{ação}

Use pontos como separador e snake_case para cada parte:

• ✅ http.server.request.duration
• ✅ pedidos.processados.total
• ✅ estoque.consultas.latency
• ❌ HttpServerRequestDuration (não use camelCase)
• ❌ pedidos-processados (não use hífens)

Sufixos por tipo

Tipo de métrica	Sufixo sugerido	Exemplo
Counter	.total ou .count	pedidos.processados.total
Histogram (duração)	.duration	http.server.request.duration
Histogram (tamanho)	.size	http.server.response.body.size
Gauge	sem sufixo	system.cpu.utilization

Unidades

Sempre use unidades no nome ou como metadado da métrica:

• Duração: s (segundos) — o OpenTelemetry padroniza em segundos
• Tamanho: By (bytes)
• Contagem: sem unidade

Checklist prático

Antes de fazer merge de código com instrumentação nova, verifique:

• service.name está configurado em todos os serviços
• Nomes de spans não contêm dados variáveis (IDs, valores)
• Atributos seguem as convenções semânticas quando aplicável
• Métricas usam snake_case com separador de ponto
• Atributos de domínio têm prefixo do namespace (pedido.id, não id)
• Spans HTTP usam {method} {route} como nome
• Spans de DB usam {operation} {table} como nome

Referências

• Convenções Semânticas do OpenTelemetry — referência completa
• Naming Guidelines — regras gerais de nomenclatura
• HTTP Semantic Conventions — convenções HTTP
• Database Semantic Conventions — convenções de banco de dados