Observabilidade

Estado

Base técnica integrada em 31/08/2026 pela Issue #102 e PR #103. A API consegue exportar métricas e traces por OTLP quando configurada. Collector, armazenamento, painéis, alertas e resposta operacional ainda não existem.

OpenTelemetry foi adotado como padrão vendor-neutral. A exportação permanece desabilitada por padrão para que desenvolvimento, testes e containers não dependam de uma plataforma externa.

Sinais disponíveis

• traces das requisições ASP.NET Core;
• métricas HTTP do ASP.NET Core;
• métricas do runtime .NET;
• nome estável do serviço e versão do assembly;
• exportação OTLP para um collector compatível.

/health, /health/live e /health/ready não geram traces. Os probes continuam funcionando normalmente e as métricas HTTP permanecem disponíveis.

Configuração

Quando existir um collector acessível:

OTEL_ENABLED=true
OTEL_SERVICE_NAME=controle-acesso-veiculos-api
OTEL_EXPORTER_OTLP_ENDPOINT=http://otel-collector:4317

O endpoint é obrigatório quando a exportação está ativa. URLs com credenciais, query string ou fragmento são rejeitadas. Headers de autenticação devem ser injetados pelo mecanismo de segredos do ambiente.

Limites de privacidade

• logs não são exportados por esta integração;
• corpos, tokens, headers de autorização e SQL não são instrumentados;
• valores de query string permanecem redigidos;
• a API rejeita o startup se alguém tentar desativar essa redação;
• novos atributos ou instrumentação de banco exigem nova revisão de privacidade.

O que falta para homologação e produção

• escolher e proteger o collector e o armazenamento;
• definir TLS, autenticação, rede e rotação de credenciais;
• confirmar retenção e acesso à telemetria;
• criar painéis e alertas;
• medir carga e calibrar sampling, cardinalidade e custo;
• definir responsáveis e integrar alertas à resposta a incidentes;
• testar a API com collector disponível e indisponível.

Os indicadores iniciais para homologação são readiness, proporção de HTTP 5xx, duração por rota normalizada, CPU, memória, GC e ausência de telemetria. Limites e SLOs só devem ser aprovados depois de medir o ambiente real.

O guia técnico versionado no repositório é a fonte revisável: Observabilidade da API.