Padrão de Telemetria (OpenTelemetry)

Status

Aprovado

Contexto

Para garantir consistência e correlação entre Métricas, Traces e Logs, é necessário padronizar como os serviços expõem seus atributos de telemetria.

Decisão

Aplicações e serviços de negócio devem expor os seguintes atributos no OTEL_RESOURCE_ATTRIBUTES e/ou Labels do Docker. Infraestrutura base pode ter requisitos simplificados.

Atributos Obrigatórios

Atributo	Descrição	Exemplo
service.namespace	Produto ou domínio	example, pagesaude
service.name	Nome lógico do serviço	auth-service
service.type	Tipo do serviço	backend, frontend, db
deployment.environment.name	Ambiente de deploy (semconv OTel atual)	local, prod, stg
service.instance.id	Identidade única da instância	example-auth-service-1

Regras de Container

1. NÃO use container_name: Permita que o Docker/Orchestrator atribua nomes para suportar escala horizontal (replicas).
2. Defina o Nome do Projeto: Use name: <project> no compose.yaml para garantir prefixos previsíveis.
3. Formatação: No compose.yaml, OTEL_RESOURCE_ATTRIBUTES deve ser uma string única separada por vírgulas, sem quebras de linha (key=val,key2=val2).

---

Labels de Observabilidade

Para consistência no Prometheus, Grafana, Loki e Tempo, o label canônico de ambiente é environment (valores: prod, stg, local, ops):

Label	Valor Exemplo
environment	prod

O Alloy Gateway normaliza o atributo deployment.environment.name para o label environment e descarta aliases (env, deployment_environment). O Tempo faz o mesmo para span metrics via dimension_mappings. Regras Prometheus, dashboards e alertas devem filtrar por environment — nunca por env.

Notas: - Labels como host_name são injetadas automaticamente pelo Grafana Alloy. - Aplicações ainda na convenção antiga (deployment.environment) seguem funcionando: o gateway aceita as duas formas. Migrar para deployment.environment.name em novas integrações.