# KBX Runtime Observability v9

## Correlation

Web client sends `X-Correlation-Id`. `KbxCorrelationMiddleware` preserves it as the ASP.NET Core trace identifier, echoes it in the response, enriches the logging scope, and adds it to the current Activity.

The same correlation value should flow into:

`HTTP → FastEndpoint → Application Command → DB/Audit → Outbox → Hangfire → external integration`.

A user-facing unexpected error exposes only this reference value. Support and operations can then search Serilog/OpenTelemetry without exposing stack traces or SQL to the user.

## Recommended OpenTelemetry dimensions

Low-cardinality dimensions:

- `kbx.screen.id`
- module
- operation type
- result category
- exception code
- runtime mode

High-cardinality business identifiers should not become metric labels. Order IDs, phone numbers and addresses belong in appropriately protected traces/logs only when operationally necessary.

## Alerting

Telegram/operations alerts should be produced from aggregated operational conditions, not every individual client validation error. Good candidates:

- sustained 5xx rate
- Outbox backlog age
- Hangfire failed-job growth
- WMS authoritative scan latency threshold breach
- DB pool exhaustion
- repeated integration failures
- runtime incident entering `read-only`

User-facing runtime notices and operator alerts are related but not identical. An internal alert does not automatically justify a blocking banner for every user.
