Skip to content

tsdb:Optimize LabelValues API performance (#14551)#18069

Merged
bboreham merged 1 commit intoprometheus:mainfrom
mishraa-G:optimize-label-api
Feb 16, 2026
Merged

tsdb:Optimize LabelValues API performance (#14551)#18069
bboreham merged 1 commit intoprometheus:mainfrom
mishraa-G:optimize-label-api

Conversation

@mishraa-G
Copy link

@mishraa-G mishraa-G commented Feb 12, 2026

tsdb: Optimize LabelValues for sparse intersections (Fixes #14551)

Description

This PR optimizes the FindIntersectingPostings function to improve the performance of LabelValues queries when matchers are involved.

The Problem:
In scenarios where a matcher selects a range of IDs that is disjoint from or far ahead of the current candidate postings (e.g., matcher is at ID 1,000,000 but the candidate is at ID 0), the previous implementation would call Next() on the candidate roughly 1,000,000 times to catch up. This resulted in O(N) complexity where N is the number of non-matching IDs, causing significant performance degradation and even timeouts for large datasets.

The Solution:
I've updated FindIntersectingPostings to use Seek() on the candidate instead of Next(). This allows the iterator to skip non-matching ranges efficiently (O(log N)), aligning the performance of LabelValues with the much faster Series API for equivalent queries.

Benchmarks

I created a reproduction benchmark BenchmarkLabelValues_SlowPath to simulate the issue (dense candidates, sparse matcher).

Results:

  • Before Optimization: The benchmark would timeout or take >1ms per operation.
  • After Optimization: The benchmark completes in ~1290 ns/op (verified locally).
Screenshot 2026-02-12 at 3 35 55 PM

Verification

  • Ran go test ./tsdb/index/... to ensure no regressions in the index package.
  • Verified manually that LabelValues returns correct results with the optimization applied.

Which issue(s) does the PR fix:

Fixes #14551

Does this PR introduce a user-facing change?

[PERF] tsdb: Optimize LabelValues intersection performance for matchers

Copy link
Member

@bboreham bboreham left a comment

Choose a reason for hiding this comment

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

Thanks for this.

If it's not in the first postings, I would expect seek() to examine further postings until it finds one with the target or reaches the end.

I expect it still works in your implementation because you're calling it from a loop that will call it again. But this is not the standard behaviour of seek(). Maybe calling it something else would be fine.

@mishraa-G
Copy link
Author

Thanks for this.

If it's not in the first postings, I would expect seek() to examine further postings until it finds one with the target or reaches the end.

I expect it still works in your implementation because you're calling it from a loop that will call it again. But this is not the standard behaviour of seek(). Maybe calling it something else would be fine.

I'll rename it to seekHead or updateHead to make it clear it's only operating on the top element. ig seekHead sounds better?

@bboreham
Copy link
Member

I'll rename it to seekHead or updateHead to make it clear it's only operating on the top element. ig seekHead sounds better?

Yes, ok with seekHead.

@bboreham
Copy link
Member

BTW there is a tool benchstat which will analyze the differences before and after.
https://pkg.go.dev/golang.org/x/perf/cmd/benchstat

@bboreham
Copy link
Member

I created a reproduction benchmark BenchmarkLabelValues_SlowPath

Why not use BenchmarkLabelValuesWithMatchers ?

If you have a good reason to need a new benchmark, please include this in your PR.

@mishraa-G
Copy link
Author

I created a reproduction benchmark BenchmarkLabelValues_SlowPath

Why not use BenchmarkLabelValuesWithMatchers ?

If you have a good reason to need a new benchmark, please include this in your PR.

the existing one covers the high-overlap case (like 90% match) where Next() already flies, so it wouldn't catch this regression. The new one specifically hits that "sparse" case where the matcher is way ahead, which was causing the timeouts in #14551. Figured it's worth keeping to lock in the fix for that scenario.

@bboreham
Copy link
Member

I have now studied the actual algorithmic change you made; it's a great find. Thanks again.
I can fix up the cosmetic stuff if you don't have time. Let me know.

@mishraa-G
Copy link
Author

I have now studied the actual algorithmic change you made; it's a great find. Thanks again. I can fix up the cosmetic stuff if you don't have time. Let me know.

Happy to know u liked the changes, i would like to modify the stuff on my own this time although it might take 3-4hrs as am currently engaged with one thing but surely i will do it

@mishraa-G mishraa-G force-pushed the optimize-label-api branch 5 times, most recently from 613665b to 27983fa Compare February 14, 2026 09:23
@mishraa-G
Copy link
Author

hey @bboreham i renamed seek to seekHead so it's less confusing, and I nuked that unused next() method entirely (plus updated the tests to use seekHead instead).
Also tidied up the comments and fixed a few lint issues in the benchmark file while I was at it. The benchmark itself is now properly set up for dense candidates (100k series for one label value), and the results are looking solid~846ns/op.

…#14551)

Signed-off-by: Divyansh Mishra <divyanshmishra@Divyanshs-MacBook-Air-3.local>
@mishraa-G
Copy link
Author

mishraa-G commented Feb 16, 2026

I have now studied the actual algorithmic change you made; it's a great find. Thanks again. I can fix up the cosmetic stuff if you don't have time. Let me know.

Hey @bboreham, just a reminder to check out this PR

@bboreham
Copy link
Member

the existing one covers the high-overlap case (like 90% match) where Next() already flies, so it wouldn't catch this regression.

I get a pretty good speedup on the existing benchmark:

goos: darwin
goarch: arm64
pkg: github.com/prometheus/prometheus/tsdb
cpu: Apple M2
                          │   before    │               after                │
                          │   sec/op    │   sec/op     vs base               │
LabelValuesWithMatchers-8   2.718m ± 4%   1.408m ± 3%  -48.20% (p=0.002 n=6)

But yours is a bigger percentage:

                       │     before     │               after                │
                       │     sec/op     │   sec/op     vs base               │
LabelValues_SlowPath-8   919901.0n ± 2%   836.6n ± 2%  -99.91% (p=0.002 n=6)

Copy link
Member

@bboreham bboreham left a comment

Choose a reason for hiding this comment

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

Great, code change is very clean now.

I didn't study the new benchmark closely.

@bboreham bboreham merged commit b908cc4 into prometheus:main Feb 16, 2026
53 of 54 checks passed
@codesome codesome mentioned this pull request Feb 17, 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.

Label API is much slower than equivalent series API

2 participants