master/docs/003-observability-via-interfaces.md

003 Observability Via Interfaces

Context

• Logging, metrics, and tracing are required, but inner layers must stay independent from OpenTelemetry.
• The project needs request logging and metrics middleware.

Decision

• Define observability interfaces in usecase/interface.py.
• Implement those interfaces with OpenTelemetry adapters in adapter/otel/.
• Use request logging middleware and metrics middleware in the FastAPI adapter.
• Do not add a custom trace middleware by default.
• Use standard ASGI/FastAPI OpenTelemetry instrumentation for request spans.

Consequences

• Usecases stay portable and framework-agnostic.
• Trace behavior remains consistent with OpenTelemetry defaults.
• Extra span enrichment can be added later without changing inner-layer contracts.