refactor(guest-agent): conventional metric names, old ones kept for one release - #1103
Merged
Conversation
kvinwang
force-pushed
the
refactor/metrics-prefixes
branch
from
August 23, 2026 08:56
36e13f4 to
e2e67c8
Compare
kvinwang
changed the title
…ne release The `/metrics` template predates any conventions and broke several at once -- no application prefix on `system_*`/`disk_*` (the most collision-prone words available), a `_total` suffix on gauges (`system_memory_total`, `disk_total_size`), which every Prometheus tool reads as a counter, missing `_bytes`/`_seconds` unit suffixes, four separate info gauges where one `_info` metric with labels is the idiom, and a percentage where conventions want a 0-1 ratio. The new `dstack_guest_*` series fix all of that. The old names keep being emitted verbatim, marked deprecated in their HELP text: this endpoint is tenant-facing (`public_sysinfo`), so the dashboards it feeds are not ours to break -- they get one release cycle to move. The gateway (`dstack_gateway_*`) and KMS (`dstack_kms_*_total`) expositions already carry compliant prefixes and are untouched.
kvinwang
force-pushed
the
refactor/metrics-prefixes
branch
from
August 23, 2026 13:30
e2e67c8 to
ddb77b0
Compare
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Content-wise independent of the gateway PRs and already based on
next; GitHub's stack tracking keeps the base pinned to #1102's branch until that merges, after which this retargets tonextautomatically. The visible diff is the guest-agent commit alone either way.Problem
The guest agent's
/metricstemplate predates any naming conventions and breaks several at once:system_os_name/_os_version/_kernel_version/_cpu_model(4 gauges)dstack_guest_info{os_name=,os_version=,kernel_version=,cpu_model=} 1system_memory_total,system_swap_total,disk_total_size_totalon a gauge — reads as a counter to every Prometheus tool; no unit suffixdstack_guest_memory_total_bytes,dstack_guest_swap_total_bytes,dstack_guest_disk_total_bytessystem_memory_used/free/available,system_swap_used/free,disk_free_size,disk_used_sizedstack_guest_{memory,swap,disk}_*_bytessystem_uptimedstack_guest_uptime_secondssystem_load_average_1m/5m/15mload1dstack_guest_load1/5/15system_num_cpusdstack_guest_cpusdisk_usage_percentagedstack_guest_disk_used_ratiosystem_*/disk_*are also the most collision-prone words available for an exposition scraped next to other exporters.Compatibility
This endpoint is tenant-facing (
public_sysinfo), so the dashboards it feeds are not ours to break. Every old series is still emitted verbatim, its HELP marked(deprecated: use dstack_guest_...), with removal announced for a future release.The gateway (
dstack_gateway_*) and KMS (dstack_kms_*_total) expositions already carry compliant application prefixes and are untouched.Verification
cargo test -p dstack-guest-agent— 76 passed; the template is embedded at build time, so compiling is validatingcargo test -p dstack-gateway— 285 passed (untouched, run to confirm)