Athena Observability Crate

crates/athena-observability is the portability seam for Athena metrics state, gateway telemetry helpers, and runtime-light logging sinks. The crate is intentionally Actix-free: it owns reusable observability contracts and helpers that can be shared by the server, workers, and future tooling without pulling in AppState or route handlers.

What Lives Here Today

• Shared in-memory MetricsState plus route/status classification helpers.
• Duration and value summary types used by Prometheus rendering.
• Gateway log contracts like LoggedRequest, auth/completion contexts, and log rows.
• Redaction helpers for headers, query strings, and JSON payloads.
• Structured gateway operation tracing helpers.
• ClientStatsBatcher for batched writes to client statistics tables.
• Optional Linux NDJSON file logging for gateway request, operation, and API-key auth logs.

What Still Stays In athena_rs

• Actix handlers like GET /metrics.
• Runtime snapshot queries that read live database state for Prometheus export.
• Athena-specific request logging orchestration that reads HttpRequest, headers, and app config.
• Schema-aware log insertion and realtime registry writes.
• Bootstrap wiring that decides which sinks and registries are enabled.

Current Extraction Rule

Use athena-observability when code is about metrics state, telemetry contracts, redaction, tracing, or sink mechanics and can run without Actix route types or AppState.

Keep code in athena_rs when it needs:

• Actix request or response types
• route handlers or middleware wiring
• app-specific config and registry lookups
• Athena schema metadata or logging-table compatibility checks
• direct orchestration of database-backed request log writes

Near-Term Direction

The next observability slices should keep tightening this boundary:

1. Move more reusable gateway log batching primitives behind crate-owned traits.
2. Leave thin runtime adapters in src/api/metrics.rs and src/utils/request_logging.rs.
3. Extract longer-lived exporter/runtime shells only once the future Actix crate owns the HTTP surface.