Traces (opcional): suporte OpenTelemetry (Node e Python) com feature flag e spans padronizados

[4lessandrodev]

Visão geral

Adicionar suporte opcional a tracing distribuído para futura fase de pipeline/análise, sem obrigar dependências no MVP.

Contexto

O roadmap prevê pipeline com múltiplas etapas. Tracing ajuda correlacionar etapas com run_id e investigar gargalos, mas deve ser opcional.

Descrição

Implementar feature flag OTEL_ENABLED (ou similar).

Node:

• iniciar tracer provider
• criar spans http.server e catalog.search (se o app usar helper)

Python:

• criar spans pipeline.stage.<name>

Regras:

• atributos: request_id, run_id, service.version, catalog_version
• sem PII
• seguir span_names.yaml do core-contracts

Testes:

• quando OTEL desligado, não quebra
• quando ligado, spans são criados (mock exporter)

Impacto

Prepara evolução para fase 2+ sem refatoração massiva. Mantém modularidade e controle por feature flag.

Referências

• https://github.com/OpenAudit-Brasil/openaudit-observability/blob/main/README.md
• https://github.com/OpenAudit-Brasil/openaudit-core-contracts
• https://github.com/OpenAudit-Brasil/About/blob/main/ROADMAP.md

Definição de pronto

• Feature flag implementada
• Spans padronizados criados quando habilitado
• Testes básicos de não-regressão passam
• Docs explicam como habilitar

Tags

• priority:low
• type:feature
• area:tracing
• area:observability