2.8 KiB
Runtime Environment and Tracing SSOT
Goal
Finish BOOT-002 by removing the remaining independent runtime-profile vocabularies from tracing and capability validation.
Canonical runtime vocabulary
shared-contract RuntimeEnvironment remains the only shipped runtime-environment vocabulary:
- local
- dev
- prod
The runtime-remediation design explicitly says STAGING is not a shipped runtime environment until a separate runtime environment is introduced. Therefore tracing must not independently advertise staging as a deployable profile.
Tracing rule
TracingSampleRateResolver maps RuntimeEnvironment values, not raw profile strings:
- PROD -> 0.01
- DEV -> 1.0
- LOCAL -> 1.0
A valid APP_TRACING_SAMPLE_RATE override still wins. An unknown/test/profileless context falls back to 1.0 for the resolver, but it is not renamed to local. The shipped application cannot reach profileless tracing because RuntimeEnvironmentProfileValidator runs before tracing defaulting and rejects a missing/unknown runtime profile.
TracingSamplingRateGauge is registered only when exactly one RuntimeEnvironment resolves. Slice/test contexts without a deployable runtime environment do not emit a misleading runtime-profile gauge.
Capability validation
CapabilityDependencyValidator keys GraphQL deployment-mode policy by RuntimeEnvironment rather than duplicated local/dev/prod string literals.
Contract cleanup
The stale tracing-only staging=10% contract is removed from:
- tracing tests;
- env registry comments;
- metrics registry profile allowlist/cardinality;
- observability config comments;
- README tracing documentation.
This is a contract correction, not the addition of a new environment. Generic uses of the word staging for deployment pipelines, data staging areas, or migration posture are unrelated and remain unchanged.
Verified result
- RuntimeEnvironment remains the only shipped local/dev/prod runtime vocabulary.
- TracingSampleRateResolver derives defaults from RuntimeEnvironment; there is no tracing-only staging branch and profileless/test/unknown callers are not renamed to local.
- TracingConfig publishes tracing.sampling.rate only when exactly one deployable RuntimeEnvironment resolves; profileless slice contexts publish no runtime-profile gauge.
- CapabilityDependencyValidator keys GraphQL deployment-mode policy by RuntimeEnvironment.
- metrics.yaml and env-keys.yaml pin tracing defaults to prod=0.01 and dev/local=1.0 with a three-value profile tag cardinality.
- No production path in the reviewed application/fileserver/httpclient/object-storage scope defines its own prod/production vocabulary; profile decisions delegate to RuntimeEnvironment.
- Focused RuntimeEnvironment, tracing, GraphQL-policy and distributed-tracing contract tests: PASS.
- app-bootstrap Spotless, full test and architectureTest: PASS.
- git diff --check: PASS.