Como Nomear seus Atributos de Span

By Juraci Paixão Kröhling (OllyGarden) | Wednesday, August 27, 2025

Sejam bem-vindos à segunda parte da nossa série sobre boas práticas de nomenclatura no OpenTelemetry. Em nossa publicação anterior, exploramos como nomear trechos utilizando o padrão {verbo} {objeto}. Hoje, vamos mergulhar nos atributos de trecho (span) — os dados contextuais ricos que transformam seus rastros (traces) de simples registros de operação em poderosas ferramentas de depuração (debugging) e análise.

Este guia é direcionado para desenvolvedores que estão:

Instrumentando suas próprias aplicações com trechos e atributos personalizados
Enriquecendo a telemetria além do que a auto-instrumentação fornece
Criando bibliotecas que outros irão instrumentar

As decisões de nomenclatura que você tomar para os atributos impactam diretamente a usabilidade e manutenibilidade dos seus dados de observabilidade. Vamos acertar isso desde o início.

Comece com as convenções semânticas

Aqui está a regra mais importante, que vai economizar seu tempo e melhorar a interoperabilidade: se existir uma convenção semântica do OpenTelemetry e a semântica corresponder ao seu caso de uso, use-a.

Não se trata apenas de conveniência — é sobre construir telemetria que se integra perfeitamente ao ecossistema mais amplo do OpenTelemetry. Quando você usa nomes de atributos padronizados, seus dados funcionam automaticamente com dashboards existentes, regras de alerta e ferramentas de análise.

Quando a semântica corresponde, use a convenção

Necessidade	Convenção semântica	Por quê
Método de requisição HTTP	`http.request.method`	Padronizado em toda instrumentação HTTP
Nome da coleção do banco de dados	`db.collection.name`	Funciona com ferramentas de monitoramento de banco de dados
Identificação do serviço	`service.name`	Atributo essencial para correlação de serviços
Endereço do par da rede	`network.peer.address`	Padrão para depuração em nível de rede
Classificação de erro	`error.type`	Permite análise de erros consistente

O princípio fundamental correspondência semântica em vez de preferência de nomenclatura. Mesmo que você prefira database_table em vez de db.collection.name, utilize a convenção semântica quando ela descrever seus dados com precisão.

Quando a semântica não corresponde, não force

Resista à tentação de usar as convenções semânticas incorretamente:

Não faça isso	Por que está errado
Usar `db.collection.name` para nome de arquivo	Arquivos e coleções de banco de dados são conceitos diferentes
Usar `http.request.method` para ações de negócio	“approve_payment” não é um método HTTP
Usar `user.id` para ID de transação	Usuários e transações são entidades diferentes

Usar convenções semânticas incorretamente é pior do que criar atributos personalizados — isso gera confusão e quebra ferramentas que esperam a semântica padrão.

A regra de ouro: domínio primeiro, nunca empresa primeiro

Quando precisar de atributos personalizados além das convenções semânticas, o princípio mais crítico é: comece com o domínio ou tecnologia, nunca com o nome da sua empresa ou aplicação.

Esse princípio parece óbvio, mas é constantemente violado na indústria. Veja por que ele é importante e como aplicá-lo corretamente.

Por que nomes baseados em empresa falham

Nome de atributo incorreto	Problemas
`og.user.id`	Prefixo da empresa polui o namespace global
`myapp.request.size`	Específico da aplicação, não reutilizável
`acme.inventory.count`	Dificulta a correlação com atributos padrão
`shopify_store.product.sku`	Vincula de forma desnecessária o conceito a um vendedor

Estas abordagens criam atributos que são:

Difíceis de correlacionar entre equipes e organizações
Impossível de reutilizar em diferentes contextos
Vinculados a um vendedor e inflexível
Inconsistente com os objetivos de interoperabilidade do OpenTelemetry

Casos de sucesso com domínio primeiro

Nome de atributo correto	Por que funciona
`user.id`	Conceito universal, neutro a fornecedores
`request.size`	Reutilizável em diferentes aplicações
`inventory.count`	Conceito claro e específico de domínio
`product.sku`	Terminologia padrão de e-commerce
`workflow.step.name`	Conceito genérico de gestão de processos

Esta abordagem cria atributos que são universalmente compreensíveis, reutilizáveis por outros que enfrentam problemas semelhantes e preparados para o futuro.

Entendendo a estrutura: pontos e underscores

Os nomes de atributos no OpenTelemetry seguem um padrão estrutural específico que equilibra legibilidade e consistência. Entender esse padrão auxilia na criação de atributos que pareçam naturais junto às convenções semânticas.

Use pontos para separação hierárquica

Pontos (.) separam componentes hierárquicos, seguindo o padrão: {domínio}.{componente}.{propriedade}

Exemplos de convenções semânticas:

http.request.method - domínio HTTP, componente de requisição, propriedade do método
db.collection.name - domínio de banco de dados, componente de coleção, propriedade do nome
service.instance.id - domínio de serviço, componente de instância, propriedade do ID

Utilize underscores para componentes com múltiplas palavras

Quando um único componente contém múltiplas palavras, utilize underscores (_):

http.response.status_code - “status_code” é um componente lógico único
system.memory.usage_percent - “usage_percent” é um conceito de medição

Crie hierarquias mais profundas quando necessário

Você pode aninhar ainda mais quando isso acrescenta clareza:

http.request.body.size
k8s.pod.label.{key}
messaging.kafka.message.key

Cada nível deve representar um limite conceitual significativo.

Namespaces reservados: o que você nunca deve usar

Certos namespaces são estritamente reservados, e violar essas regras pode comprometer seus dados de telemetria.

O namespace `otel.*` está fora dos limites

O prefixo otel.* é reservado exclusivamente para a especificação do OpenTelemetry. Este prefixo é utilizado para expressar conceitos do OpenTelemetry em formatos de telemetria que não os suportam nativamente.

Os atributos reservados otel.* incluem:

otel.scope.name - Nome do escopo de instrumentação
otel.status_code - Código de estado do trecho
otel.span.sampling_result - Decisão de amostragem (sampling)

Nunca crie atributos com prefixo otel.. Quaisquer adições a este namespace devem ser aprovadas como parte da especificação do OpenTelemetry.

Outros atributos reservados

A especificação também reserva os seguintes nomes de atributos:

error.type
exception.message, exception.stacktrace, exception.type
server.address, server.port
service.name
telemetry.sdk.language, telemetry.sdk.name, telemetry.sdk.version
url.scheme

Padrões de convenções semânticas

A melhor maneira de desenvolver intuição para boas práticas de nomenclatura é estudando as convenções semânticas do OpenTelemetry. Elas representam milhares de horas de trabalho de design por especialistas em observabilidade.

Padrões de organização por domínio

Observe como as convenções semânticas se organizam em torno de domínios claros:

Domínios de infraestrutura

service.* - Identidade e metadados do serviço
host.* - Informações de host/máquina
container.* - Informações de execução do contêiner
process.* - Processos do sistema operacional

Domínios de comunicação

http.* - Especificidades do protocolo HTTP
network.* - Informações da camada de rede
rpc.* - Atributos de chamadas remotas (RPC)
messaging.* - Sistemas de fila de mensagens

Domínios de dados

db.* - Operações de banco de dados
url.* - Componentes de URL

Padrões universais de propriedades

Em todos os domínios, surgem padrões consistentes para propriedades comuns:

Propriedades de identidade

.name - Identificadores legíveis para humanos (service.name, container.name)
.id - Identificadores do sistema (container.id, process.pid)
.version - Informações de versão (service.version)
.type - Classificação (messaging.operation.type, error.type)

Propriedades de rede

.address - Endereços de rede (server.address, client.address)
.port - Números de porta (server.port, client.port)

Propriedades de medição

.size - Medições em bytes (http.request.body.size)
.count - Quantidades (messaging.batch.message_count)
.duration - Medições de tempo (http.server.request.duration)

Ao criar domínios personalizados, siga estes mesmos padrões. Para gestão de estoque, considere:

inventory.item.name
inventory.item.id
inventory.location.address
inventory.batch.count

Criando domínios personalizados com segurança

Às vezes, sua lógica de negócio exige atributos fora das convenções semânticas existentes. Isso é normal — o OpenTelemetry não pode cobrir todos os domínios de negócios possíveis.

Diretrizes para domínios personalizados seguros

Escolha nomes descritivos e genéricos que outros possam reutilizar.
Evite terminologia específica da empresa no nome do domínio.
Siga os padrões hierárquicos estabelecidos pelas convenções semânticas.
Considere se seu domínio pode se tornar uma convenção semântica no futuro.

Exemplos de atributos personalizados bem projetados

Domínio	Atributos bons	Por que funcionam
Negócio	`payment.method`, `order.status`	Conceitos de negócio claros e reutilizáveis
Logística	`inventory.location`, `shipment.carrier`	Específicos de domínio, mas transferíveis
Processo	`workflow.step.name`, `approval.status`	Gestão de processos genérica
Conteúdo	`document.format`, `media.codec`	Conceitos de conteúdo universais

A exceção rara: Quando prefixos fazem sentido

Em casos raros, você pode precisar utilizar prefixos de empresa ou aplicação. Isso geralmente acontece quando seu atributo personalizado pode conflitar com atributos de outras fontes em um sistema distribuído.

Considere prefixos quando:

Seu atributo pode conflitar com atributos de fornecedores em um sistema distribuído.
Você está instrumentando tecnologia proprietária, específica da sua empresa.
Você está capturando detalhes de implementação interna que não devem ser generalizados.

Para a maioria dos atributos de lógica de negócio, mantenha o padrão “domínio primeiro” (domain-first).

Seu plano de ação

Nomear bem os atributos de trechos cria dados de telemetria que são manuteníveis, interoperáveis e valiosos em toda a sua organização. Aqui está seu roteiro:

Sempre verifique as convenções semânticas primeiro - Use-as quando a semântica corresponder.
Comece pelo domínio, nunca pela empresa - Crie atributos neutros a fornecedores.
Respeite os namespaces reservados - Evite otel.*, especialmente.
Siga os padrões hierárquicos - Utilize pontos e underscores de forma consistente.
Construa pensando em reutilização - Vá além das suas necessidades atuais.

Seguindo estes princípios, você não estará apenas resolvendo os desafios de instrumentação hoje — estará contribuindo para um ecossistema de observabilidade mais coerente e interoperável, que beneficia a todos.

Na próxima publicação desta série, mudaremos o foco de trechos para métricas — explorando como nomear as medições quantitativas que nos dizem como nossos sistemas estão performando, e por que os mesmos princípios de separação e “domínio primeiro” se aplicam aos números que mais importam.

Last modified August 29, 2025: [pt] Translate 'How to Name Your Span Attributes' blog post (#7618) (ac52f4a8)