48 lines
1.9 KiB
Markdown
48 lines
1.9 KiB
Markdown
# Operability
|
|
|
|
## Diagnostics
|
|
|
|
Use `readiness()` for dependency checks and `operability_snapshot()` for
|
|
runtime counters and invariant checks. The snapshot currently reports store
|
|
readiness, audit correlation completeness, outbox diagnostic availability, and
|
|
counts for users, accounts, tenant accounts, memberships, applications,
|
|
catalogs, profile values, audit records, and pending outbox events.
|
|
|
|
## Structured Logs
|
|
|
|
Use `structured_log_context(correlation_id=..., tenant=..., actor=...)` as the
|
|
base log envelope. Adapters should add transport details around that envelope
|
|
without dropping correlation id or tenant.
|
|
|
|
## Metrics
|
|
|
|
`GET /metrics` exposes Prometheus text containing the binary
|
|
`user_engine_ready` dependency gauge and bounded aggregate
|
|
`user_engine_records{kind=...}` counters. It does not expose identity values,
|
|
emails, tenant names, correlation identifiers, credential material, or raw
|
|
outbox payloads. Keep this route cluster-internal and authorize ingress only
|
|
from the selected monitoring workload.
|
|
|
|
## Outbox Drain
|
|
|
|
`outbox_diagnostics()` reports pending event count, event type counts, and the
|
|
oldest pending correlation id. A real outbox drain adapter should publish
|
|
events idempotently by `event_id`, retain `correlation_id`, and only mark
|
|
delivery after the sink acknowledges receipt.
|
|
|
|
## Cache Status
|
|
|
|
`ClaimsEnrichmentProjectionCache.status()` reports entry count and cached
|
|
tenant, application, and user keys. Token issuers must invalidate affected
|
|
users after profile, membership, or catalog changes before minting enriched
|
|
claims.
|
|
|
|
## Runbook Checks
|
|
|
|
1. Run `make test-conformance`.
|
|
2. Confirm `readiness().ready` is true.
|
|
3. Confirm `operability_snapshot().issues` is empty.
|
|
4. Confirm pending outbox events are either drained or expected for the local
|
|
environment.
|
|
5. Confirm production identity adapters reject local, expired, and
|
|
missing-tenant claims.
|