vllm-omni/docs/design/module/observability.md

title, kind, status, owners, primary_code_paths, related_code_paths, depends_on, validation_paths, upstream_refs, last_reviewed

title	kind	status	owners	primary_code_paths	related_code_paths	depends_on	validation_paths	upstream_refs	last_reviewed
Observability	module	draft	@lishunyang12 @vraiti	vllm_omni/metrics/**	vllm_omni/engine/** vllm_omni/entrypoints/**	engine_orchestration.md	tests/metrics/**	vllm.v1.metrics	2026-07-16

Observability

Observability defines stable metrics, logs, and correlation fields for tracing a request across entrypoints, orchestration, stages, and workers.

Candidate invariants

OBS-INV-001: Request correlation survives stage boundaries

Rule: Logs and metrics for the same request SHOULD carry a stable request identifier and stage identity.

OBS-INV-002: Metric meaning is stable

Rule: A metric's unit, labels, aggregation, and lifecycle MUST be documented; changing any of them is a contract change.

OBS-INV-003: Labels are bounded

Rule: Metrics MUST NOT use request IDs, prompts, outputs, or other unbounded values as labels.

Safe-change guide

Test registration, label sets, units, lifecycle resets, and representative multi-stage emission.