Skip to content

feat(api): add GET /vm/kvm-stats for KVM binary statistics - #6366

Draft
lisasgoh wants to merge 1 commit into
firecracker-microvm:mainfrom
lisasgoh:feat/kvm-stats-endpoint
Draft

lisasgoh wants to merge 1 commit into
firecracker-microvm:mainfrom
lisasgoh:feat/kvm-stats-endpoint

Conversation

@lisasgoh

@lisasgoh lisasgoh commented Oct 30, 2026 •

Copy link
Copy Markdown
Contributor

Closes #6288

Changes

Serve KVM's binary statistics (KVM_GET_STATS_FD, Linux 5.14+) for the VM and each vCPU. Each statistic carries the kind and unit KVM declares for it, named as in QEMU's query-stats, and histograms such as halt_wait_hist are returned in full: debugfs only has per-VM sums and reads histograms as their first bucket.

The stats descriptors are opened when the vCPUs are created, before the VMM thread's seccomp filter is installed, and read with pread64 on each request, which the VMM filter now allows. Values are running totals since the vCPUs were created, so they start from zero after a snapshot is loaded.

Reason

When a VM is slow, we want to know where its vCPUs spent their time: running guest code, exiting to KVM, halted, or halt-polling. KVM counts this per vCPU and, since Linux 5.14, exposes it through binary stats (KVM_GET_STATS_FD), including histograms such as halt_wait_hist. Firecracker's metrics only cover the exits that reach Firecracker itself (vcpu.exit_mmio_, vcpu.exit_io_).

License Acceptance

By submitting this pull request, I confirm that my contribution is made under
the terms of the Apache 2.0 license. For more information on following Developer
Certificate of Origin and signing off your commits, please check
CONTRIBUTING.md.

PR Checklist

  • I have read and understand CONTRIBUTING.md.
  • I have run tools/devtool checkbuild --all to verify that the PR passes
    build checks on all supported architectures.
  • I have run tools/devtool checkstyle --no-clippy to verify that the PR
    passes the automated style checks.
  • I have described what is done in these changes, why they are needed, and
    how they are solving the problem in a clear and encompassing way.
  • I have updated any relevant documentation (both in code and in the docs)
    in the PR.
  • I have mentioned all user-facing changes in CHANGELOG.md.
  • If a specific issue led to this PR, this PR closes the issue.
  • When making API changes, I have followed the
    Runbook for Firecracker API changes.
  • I have tested all new and changed functionalities in unit tests and/or
    integration tests.
  • I have linked an issue to every new TODO.

  • This functionality cannot be added in rust-vmm.

Serve KVM's binary statistics (KVM_GET_STATS_FD, Linux 5.14+) for the
VM and each vCPU. Each statistic carries the kind and unit KVM declares
for it, named as in QEMU's query-stats, and histograms such as
halt_wait_hist are returned in full: debugfs only has per-VM sums and
reads histograms as their first bucket.

The stats descriptors are opened when the vCPUs are created, before the
VMM thread's seccomp filter is installed, and read with pread64 on each
request, which the VMM filter now allows. Values are running totals
since the vCPUs were created, so they start from zero after a snapshot
is loaded.

Signed-off-by: Lisa Goh <[email protected]>
@JamesC1305 JamesC1305 self-assigned this Nov 2, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

[Feature Request] Emit KVM binary stats (KVM_GET_STATS_FD) per vCPU as part of metrics

2 participants