[Metrics] Add --custom-histogram-buckets to override histogram bucket families by GuyStone · Pull Request #48867 · vllm-project/vllm · GitHub
Skip to content

[Metrics] Add --custom-histogram-buckets to override histogram bucket families - #48867

Merged
markmc merged 3 commits into
vllm-project:mainfrom
GuyStone:metrics/histogram-buckets-02-custom-override
Oct 1, 2026
Merged

markmc merged 3 commits into
vllm-project:mainfrom
GuyStone:metrics/histogram-buckets-02-custom-override

Conversation

@GuyStone

@GuyStone GuyStone commented Jul 16, 2026 •

Copy link
Copy Markdown
Contributor

Note

Stacked on #48866. GitHub cannot base a cross-fork PR on another fork branch, so this PR's diff necessarily includes #48866's two commits. To review only this PR's changes, use the incremental diff — histogram-buckets-01-consolidate...histogram-buckets-02-custom-override — or the last 3 commits (515a37f18, bfd031dcd, 5d493a5da). Once #48866 merges, the diff here collapses to just those commits.

[Metrics] Add --custom-histogram-buckets to override histogram bucket families

Purpose

Fixes #34370.

vllm serve Qwen/Qwen3-0.6B \
    --custom-histogram-buckets '{"request_latency": [0.01, 0.05, 0.1, 0.25, 0.5, 1.0, 5.0, 30.0]}'

Why this does not duplicate existing PRs

  • #34720 (@timon0305) added configurable metrics without consolidation.
  • #34564 (@timon0305) added per-metric flags and were closed after "changes requested" pointing to the consolidation plan; this PR implements the requested per-family design instead.

Essential Elements of an Effective PR Description Checklist
  • The purpose of the PR, such as "Fix some issue (link existing issues this PR will resolve)".
  • [] The test plan, such as providing test command.
  • [z] The test results, such as pasting the results comparison before and after, or e2e results
  • (Optional) The necessary documentation update, such as updating supported_models.md and examples for a new model.

@claude claude Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Claude Code Review

This pull request is from a fork — automated review is disabled. A repository maintainer can comment @claude review to run a one-time review.

@mergify

mergify Bot commented Jul 16, 2026

Copy link
Copy Markdown
Contributor

@mergify mergify Bot added documentation Improvements or additions to documentation v1 labels Jul 16, 2026
@mergify

mergify Bot commented Aug 14, 2026

Copy link
Copy Markdown
Contributor

This pull request has merge conflicts that must be resolved before it can be
merged. Please rebase the PR, @GuyStone.

https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks/syncing-a-fork

@mergify mergify Bot added the needs-rebase label Aug 14, 2026
@mergify mergify Bot removed the needs-rebase label Sep 9, 2026
@robertgshaw2-redhat robertgshaw2-redhat added the ready ONLY add when PR is ready to merge/full CI is needed label Sep 9, 2026
@robertgshaw2-redhat

Copy link
Copy Markdown
Collaborator

/ci run

@github-actions

github-actions Bot commented Sep 9, 2026

Copy link
Copy Markdown

✅ @GuyStone, CI is now available for this PR.

  • /ci run starts upstream CI; /amd-ci run starts AMD CI only.
  • /ci retry retries failed jobs in the CI build for the current PR head. If the current head has no CI build, it starts a new CI build for the current head containing only jobs that failed in the latest earlier CI build for this PR.
  • /amd-ci retry retries failed jobs in AMD CI for the current PR head. Use /amd-ci run when the current head has no AMD CI build.
  • /ci cancel cancels scheduled or running CI builds for this PR branch; /amd-ci cancel does the same for AMD CI only.

@github-actions

github-actions Bot commented Sep 9, 2026

Copy link
Copy Markdown

✅ Triggered Buildkite CI #87914 for commit ce38c83a3f4e.

@mergify

mergify Bot commented Sep 9, 2026

Copy link
Copy Markdown
Contributor

Hi @GuyStone, the pre-commit checks have failed. Please run:

uv pip install pre-commit>=4.5.1
pre-commit install
pre-commit run --all-files

Then, commit the changes and push to your branch.

For future commits, pre-commit will run automatically on changed files before each commit.

@mergify

mergify Bot commented Sep 11, 2026

Copy link
Copy Markdown
Contributor

This pull request has merge conflicts that must be resolved before it can be
merged. Please rebase the PR, @GuyStone.

https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks/syncing-a-fork

@mergify mergify Bot added the needs-rebase label Sep 11, 2026
@isacandrei

Copy link
Copy Markdown

+1 for this one. We also see the need for closer buckets in the 0 -> 300 ms range.

Is there any way I can help to push this forward?

@GuyStone
GuyStone force-pushed the metrics/histogram-buckets-02-custom-override branch from ce38c83 to 3486940 Compare September 24, 2026 17:38
@GuyStone

Copy link
Copy Markdown
Contributor Author

/ci run

@github-actions

Copy link
Copy Markdown

✅ Triggered Buildkite CI #91005 for commit 3486940f8331.

@mergify mergify Bot removed the needs-rebase label Sep 24, 2026
@github-actions

Copy link
Copy Markdown

❌ This PR is 1 commit behind upstream main. Your branch must contain every commit currently on upstream main. No new CI build was started. Merge or rebase onto the latest main, then rerun /ci run. To test this branch at your own risk, use /ci run --allow-stale.

@GuyStone

Copy link
Copy Markdown
Contributor Author

/ci run

@github-actions

Copy link
Copy Markdown

✅ Triggered Buildkite CI #91129 for commit 87472c47d217.

@isacandrei

Copy link
Copy Markdown

Hi folks, @GuyStone! Any chance we can get this in the next release? Anything I can do to help? I'm new to vLLM but I'd like to contribute.

@GuyStone

Copy link
Copy Markdown
Contributor Author

Hi folks, @GuyStone! Any chance we can get this in the next release? Anything I can do to help? I'm new to vLLM but I'd like to contribute.

Hi @isacandrei! Hopefully we can get this into the next release. The build is now green, so the next step is maintainer review and, assuming everything looks good, merging. I believe @markmc is going to help with the review.

@markmc markmc left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is really excellent, well done. And apologies that it took so long to be reviewed 👍

@github-actions

Copy link
Copy Markdown

❌ This PR is 1 commit behind upstream main. Your branch must contain every commit currently on upstream main. No new CI build was started. Merge or rebase onto the latest main, then rerun /ci run. To test this branch at your own risk, use /ci run --allow-stale.

@markmc
markmc force-pushed the metrics/histogram-buckets-02-custom-override branch from 5b8de81 to 79ce274 Compare September 30, 2026 15:46
@markmc

markmc commented Sep 30, 2026

Copy link
Copy Markdown
Member

/ci run

@github-actions

Copy link
Copy Markdown

✅ Triggered Buildkite CI #92191 for commit 79ce2746a66d.

@vllm-agent

vllm-agent commented Sep 30, 2026 •

Copy link
Copy Markdown
Collaborator

CI selector (shadow): 39 test steps (64 jobs) instead of 70 (90 jobs)

Shadow mode: this changes nothing about what CI runs. It shows what the evidence-based selector would pick for this PR, next to today's rules. How it works.

Feedback welcome: reply here if it would skip a step this change needs, or runs something unrelated.

steps (jobs) Today's rules Selector Would skip Would add
NVIDIA, CPU and others 70 (90) 39 (64) 47 (64) 16 (38)
AMD mirrors 66 (91) 28 (46) 47 (69) 9 (24)
Selector would run (39)
  • amd-kernels-mi355
  • basic-correctness-sleep-mode
  • cpu-language-generation-and-pooling-model-tests ×3
  • cpu-multi-modal-model-tests-n ×4
  • cpu-multimodal-config
  • distributed-compile-comm-4-gpus
  • distributed-dp-tests-2-gpus
  • distributed-dp-tests-4-gpus
  • distributed-model-tests-2-gpus ×3
  • distributed-torchrun-shutdown-tests-2-gpus
  • e2e-core-1-gpu
  • engine
  • engine-1-gpu
  • entrypoints-integration-api-server-openai-completion
  • entrypoints-integration-multimodal
  • entrypoints-unit-tests
  • examples
  • kernels-attention-test ×7
  • kernels-b200 ×3
  • kernels-root-misc-test-b200
  • language-models-tests-extra-standard ×2
  • language-models-tests-granite-l4-compatibility
  • language-models-tests-hybrid ×2
  • language-models-tests-standard
  • lora ×4
  • model-executor
  • multi-modal-models-standard-4-other-whisper
  • pipeline-context-parallelism-4-gpus
  • plugin-tests-2-gpus
  • pytorch-compilation-unit-tests
  • rayexecutorv2-4-gpus
  • spec-decode-draft-model ×4
  • v1-attention-b200 ×2
  • v1-attention-h100-mi300 ×2
  • v1-core
  • v1-executor-worker
  • v1-logits-oracle
  • v1-metrics-lmeval
  • v1-others-cpu
Would skip (today's rules run them) (47)
  • ascend-npu-test
  • async-engine-inputs-utils-worker
  • basic-correctness ×2
  • basic-correctness-cpu-offload
  • basic-correctness-cumem
  • basic-correctness-prefetch-offload
  • basic-models-test-other-cpu
  • basic-models-tests-initialization
  • basic-models-tests-other
  • benchmarks-cli-test
  • cpu-params-env-tokenizers-parser
  • cpu-reasoning-renderers
  • cpu-tool-parsers
  • distributed-compile-rpc-tests-2-gpus
  • e2e-core-large-memory
  • e2e-scheduling-1-gpu
  • elastic-ep-scaling-test
  • entrypoints-integration-api-server ×4
  • entrypoints-integration-api-server-generate
  • entrypoints-integration-api-server-openai-chat_completion
  • entrypoints-integration-llm
  • entrypoints-integration-pooling
  • entrypoints-integration-responses-api
  • entrypoints-integration-speech_to_text
  • jit-monitor-no-runtime-jit
  • kernels-fla-ops-test-b200
  • kernels-fusedmoe-layer-test-2-b200s
  • kernels-fusedmoe-layer-test-2-h100s
  • kernels-mhc-test-b200
  • kernels-moe-test ×5
  • metrics-tracing-2-gpus
  • multi-modal-models-standard-1-qwen2
  • multi-modal-models-standard-2-qwen3-gemma
  • multi-modal-models-standard-3-llava-qwen2-vl
  • multi-modal-processor ×4
  • multi-modal-processor-cpu ×4
  • pytorch-compilation-dynamic-shapes
  • pytorch-compilation-passes-unit-tests
  • pytorch-compilation-unit-tests-h100
  • pytorch-fullgraph-cudagraph-l4-compatibility
  • pytorch-fullgraph-test
  • regression
  • rust-frontend-distributed
  • v1-kv-connectors ×4
  • v1-kv-offload
  • v1-sample
  • v1-spec-decode
Would add (today's rules do not run them) (16)
  • amd-kernels-mi355 (code map)
  • cpu-multi-modal-model-tests-n ×4 (code map)
  • distributed-compile-comm-4-gpus (code map)
  • distributed-dp-tests-4-gpus (code map)
  • distributed-model-tests-2-gpus ×3 (code map)
  • entrypoints-unit-tests (code map)
  • examples (code map)
  • kernels-attention-test ×7 (code map)
  • kernels-b200 ×3 (code map)
  • language-models-tests-extra-standard ×2 (code map)
  • lora ×4 (code map)
  • plugin-tests-2-gpus (code map)
  • rayexecutorv2-4-gpus (code map)
  • spec-decode-draft-model ×4 (code map)
  • v1-attention-b200 ×2 (code map)
  • v1-attention-h100-mi300 ×2 (code map)
AMD mirrors: would skip (47)
  • async-engine-inputs-utils-worker
  • basic-correctness ×2
  • basic-correctness-cpu-offload
  • basic-correctness-cumem
  • basic-correctness-prefetch-offload
  • basic-models-test-other-cpu
  • basic-models-tests-initialization
  • basic-models-tests-other
  • benchmarks-cli-test
  • deepseek-v4-kernel-test-b200
  • distributed-compile-rpc-tests-2-gpus
  • e2e-core-large-memory
  • e2e-scheduling-1-gpu
  • entrypoints-integration-api-server ×4
  • entrypoints-integration-api-server-generate
  • entrypoints-integration-api-server-openai-chat_completion
  • entrypoints-integration-llm
  • entrypoints-integration-pooling
  • entrypoints-integration-responses-api
  • entrypoints-integration-speech_to_text
  • fault-tolerance-e2e-2xh100
  • jit-monitor-no-runtime-jit
  • kernels-fla-ops-test-b200
  • kernels-fp4-moe-test-b200
  • kernels-fusedmoe-layer-test-2-b200s
  • kernels-fusedmoe-layer-test-2-h100s
  • kernels-mhc-test-b200
  • kernels-moe-test ×5
  • kernels-quantization-test ×6
  • kernels-root-misc-test-b200
  • metrics-tracing-2-gpus
  • multi-modal-models-standard-1-qwen2
  • multi-modal-models-standard-2-qwen3-gemma
  • multi-modal-models-standard-3-llava-qwen2-vl
  • multi-modal-processor ×4
  • multi-modal-processor-cpu ×4
  • platform-tests
  • pytorch-compilation-dynamic-shapes
  • pytorch-compilation-passes-unit-tests
  • pytorch-compilation-unit-tests-h100
  • pytorch-fullgraph-test
  • regression
  • rust-frontend-distributed
  • v1-kv-connectors ×4
  • v1-kv-offload
  • v1-sample
  • v1-spec-decode
AMD mirrors: would add (9)
  • entrypoints-unit-tests (code map)
  • examples (code map)
  • kernels-attention-test ×7 (code map)
  • language-models-tests-extra-standard ×2 (code map)
  • lora ×4 (code map)
  • plugin-tests-2-gpus (code map)
  • spec-decode-draft-model ×4 (code map)
  • v1-attention-b200 ×2 (code map)
  • v1-attention-h100-mi300 ×2 (code map)

CI results (2026-09-30 16:52 UTC)

143 passed, 1 failed, 30 pending.
CI is still running; the picture below is not final.

No misses: every failed job the selector would skip was also failing on main.

  • computer-cpu-reasoning-plus-renderers: selector would skip it; also failing on main (cff08b461e, ff1b87cca2, 0f8b398158), pre-existing

8 changed files · base cff08b461e · head 79ce2746a6 · Python record: not used (/tmp/ci-infra-selector/buildkite/ci_selector/coverage-data/table.json.gz is table version 5, expected 7; re-merge it from the raw recordings) · kernel record: table 866fa13 (build 92059), map 866fa13 · not counted: 10 build steps, 5 A100 steps the generator no longer emits, 16 optional steps the selector would also run

@markmc

markmc commented Sep 30, 2026

Copy link
Copy Markdown
Member

Rebase to pick up #59476

GuyStone and others added 3 commits September 30, 2026 21:15
Add custom_histogram_buckets to ObservabilityConfig: a mapping from
bucket-family key to a replacement list of bucket upper bounds, exposed
on the CLI as --custom-histogram-buckets taking a JSON object. A present
family key replaces the default boundaries verbatim for every histogram
in that family; unset or unlisted families keep today's defaults, so
default metric output is unchanged.

Values are validated when the config is built: unknown family keys,
empty lists, boolean, non-finite, or non-positive bounds, and
non-strictly-increasing sequences are all rejected with messages naming
the field, the offending key or value, and the violated rule. Booleans
are rejected in a before-mode validator because pydantic would otherwise
silently coerce them to 1.0/0.0. histogram_buckets() gains an overrides
parameter and remains the single place bucket lists are resolved.

Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Signed-off-by: Guy Stone <guys@spotify.com>
Cover the validation matrix for custom_histogram_buckets (unknown
family, empty list, boolean, non-finite, non-positive, and
non-increasing bounds), override precedence in histogram_buckets(),
end-to-end application through PrometheusStatLogger with KV cache
metrics enabled, and the CLI round-trip including malformed JSON and
unknown-family rejection.

The end-to-end test overrides every family at once, each with a
distinct list, so a histogram left wired to its defaults because its
histogram_buckets() call is missing the overrides argument fails the
test rather than passing unnoticed.

Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Signed-off-by: Guy Stone <guys@spotify.com>
Describe the --custom-histogram-buckets option: a usage example, the
mapping from family keys to affected metrics, the validation rules, and
a warning that finer buckets multiply Prometheus time-series cardinality
per label combination.

Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Signed-off-by: Guy Stone <guys@spotify.com>
@markmc
markmc force-pushed the metrics/histogram-buckets-02-custom-override branch from 79ce274 to 0a6b43f Compare September 30, 2026 20:15
@markmc

markmc commented Sep 30, 2026

Copy link
Copy Markdown
Member

/ci run

@github-actions

Copy link
Copy Markdown

@markmc
markmc merged commit 37d6174 into vllm-project:main Oct 1, 2026
184 checks passed
michael-gpu pushed a commit to practical-inference/vllm-ampere-extended that referenced this pull request Oct 20, 2026
… families (vllm-project#48867)

The core engine histograms ship with default bucket boundaries tuned for
typical serving workloads. The `--custom-histogram-buckets` option replaces
the boundaries of one or more bucket families. Use it, for example, to track
sub-300ms latency SLOs with the request-phase histograms, whose smallest
default boundary is 0.3s.

Signed-off-by: Guy Stone <guys@spotify.com>
Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

documentation Improvements or additions to documentation ready ONLY add when PR is ready to merge/full CI is needed v1

Projects

Development

Successfully merging this pull request may close these issues.

[Feature]: Make Prometheus histogram buckets configurable

5 participants