Fighting Game · Guides & deep dives

V2 Service Observability

kind, and residency zone where available.

3sections1 minread
Markdown source
On this page

@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.