# V2 Service Observability

`@oshun/metrics` and `@oshun/tracing` are required from day one for every
package under `apps/v2/` and for the Unreal `V2Services` module. The
observability path is off rollback: it can emit counters, histograms, spans, and
outage status, but it cannot affect deterministic gameplay state or simulation.

## Node Service Contract

- Every `apps/v2/*/package.json` declares direct workspace dependencies on
  `@oshun/metrics` and `@oshun/tracing`.
- `@v2/oshun-adapter` creates the default service registry through
  `createRegistry` and creates consumer spans through `createLightweightTracer`.
- Shared metric labels include the V2 service package, event type, reaction
  kind, and residency zone where available.
- Handler duration is measured through Prometheus histograms and event handling
  is wrapped in OpenTelemetry-style spans.

## Unreal Module Contract

`V2Services` exposes `FV2ServiceObservabilityBinding` records for both
`apps/v2/*` and `V2/ue/Source/V2Services`. Each binding pins:

- metrics package: `@oshun/metrics`
- tracing package: `@oshun/tracing`
- metrics domain: `EV2OshunDomain::Metrics`
- tracing domain: `EV2OshunDomain::Tracing`
- `bRequiredFromDayOne: true`
- `bMayInfluenceRollback: false`

The default gRPC channel manager still routes metrics and tracing through their
own Oshun domains, so service outage state is visible without coupling the
observability path to rollback.

## Verification

`V2/ue/Tools/check-v2-service-observability.py` checks every V2 service package,
the lockfile, `@v2/oshun-adapter`, `V2Services`, docs, TODO entry, and CI
workflow. The existing V2Services automation spec also validates the
observability bindings.