Observability
Shared observability instrumentation standard (Track H1). Defines the two unauthenticated, tailnet-scoped exposition endpoints every service serves (GET /metrics Prometheus text; GET /health liveness), the Fix-157 label-cardinality/PII policy that is a MANDATORY SDK default, the structured-log JSON schema, and the OTLP tracing env contract. ZERO new store — emits to the existing substrate one-pane (Prometheus/VictoriaMetrics · Alloy→Loki · Tempo/OTLP · GlitchTip). Full policy: standard.md.
- Group: Governance & platform
- Contract:
contracts/observability/v1/openapi.yaml - Public access: none — internal-only capability. It is NOT exposed on the public API gateway (
https://api.vagarylabs.com); it is reachable only inside the fleet (container/tailnet) by first-party callers. There is no customer-facing endpoint to call.
Endpoints
| Method | Path | Summary |
|---|---|---|
GET | /metrics | Prometheus text-exposition of this service's registry (BFT fail-open — never 5xx) |
GET | /health | Liveness probe (Uptime-Kuma + container healthcheck target) |
Schemas
Health
| Field | Type | Description |
|---|---|---|
status | string | liveness marker |
service | string | this service's canonical name |
LabelPolicy
The Fix-157 / D24 label-cardinality + PII-redaction policy — a MANDATORY default of the SDK. A raw per-user identifier is NEVER a label; correlate via an 8-char SHA256 prefix; keep <100 unique values per label; the route label is normalized (IDs/tokens/emails → placeholders). See standard.md.
| Field | Type | Description |
|---|---|---|
forbidden_raw_labels | array | identifiers that MUST NOT appear raw as a metric label |
hashed_label_suffix | string | an 8-char SHA256 prefix label carries this suffix (e.g. api_key_id_hash) |
route_normalization | boolean | the route label collapses UUIDs/ObjectIds/emails/tokens/numeric+alnum ids to :id/:token/:email |
max_series_per_label | integer | target steady-state cardinality cap per label |
tenant_label | string | I6 product-tier tenant label — bounded + PII-safe; used ONLY where per-org series are bounded |
StructuredLogEntry
the canonical JSON log line shape (Alloy→Loki parses); sensitive fields are redacted
| Field | Type | Description |
|---|---|---|
ts | string | |
level | string | |
service | string | |
msg | string | |
trace_id | string | active OTel trace_id (32-char hex) when a span is active |
span_id | string | |
organization_id | string | I6 tenant |
extra | object | structured context (sensitive keys redacted) |
AlertRule
alert-rules-as-data — the shape converges; the ALERT_RULES content stays product-local
| Field | Type | Description |
|---|---|---|
name | string | |
expression | string | PromQL that fires when truthy |
severity | string | |
for_duration | string | Prometheus duration (e.g. 5m) |
annotations | object | |
labels | object |
Generated by scripts/gen-capability-docs.py from contracts/observability/v1/openapi.yaml — the contract IS the source of truth; edit the contract, not this page.