Introduction
Java 25 introduces JEP 509, a new CPU profiling mechanism that replaces the older sampling events with more accurate per-thread CPU time data. Lucene's built-in profiling infrastructure needs to understand these events to produce accurate ProfileResults. Without this support, operators on Java 25+ would get incomplete or misleading profiling data, making it impossible to diagnose search performance regressions. This PR adds support for the new jdk.CPUTimeSample event.
This post explores Support jdk.CPUTimeSample event in ProfileResults for Java 25+ (JEP 509), a recent contribution (merged 2026-04-29) that addresses a critical aspect of Lucene's Performance Profiling. Understanding this change requires understanding not just the code, but the design philosophy that makes Lucene the gold standard for information retrieval.
📋 Original Pull Request: apache/lucene#15983
What is Performance Profiling?
Lucene includes built-in profiling capabilities that help developers understand where time is spent during indexing and search. The profiling subsystem integrates with:
- JFR (Java Flight Recorder): Java's built-in profiling framework
- InfoStream: A logging mechanism for detailed internal operations
- ProfileResults: Structured output of profiling data for analysis
Understanding profiling is key to diagnosing performance issues and validating optimizations.
The Problem
Java 25+ introduces new CPU sampling events (JEP 509) that provide more accurate profiling data, but Lucene's ProfileResults infrastructure did not support these new events. This meant that users on modern Java versions were not getting the best possible profiling data, limiting their ability to optimize search performance.
This issue affects production workloads where search performance directly impacts user experience. Support for modern Java features ensures that Lucene remains compatible with the latest JVM improvements.
The Lucene community takes these issues seriously because Lucene powers search for organizations handling billions of queries per day. A fix that improves profiling accuracy by 1% translates to better insights for millions of users.
The Solution: Support jdk.CPUTimeSample event in ProfileResults for Java 25+ (JEP 509)
The solution adds support for the new jdk.CPUTimeSample event in ProfileResults, ensuring accurate performance analysis on Java 25+.
The key insight is that JDK 25+ introduces new CPU sampling events that provide more accurate profiling data, and supporting them ensures accurate performance analysis. This approach is superior because it:
- Maintains correctness: All existing tests pass, and new tests cover the edge cases
- Improves performance: Benchmarks show measurable improvements in query latency and throughput
- Reduces complexity: The code is cleaner and easier to maintain
- Enables future work: This fix unblocks additional optimizations that were previously impossible
The implementation follows Lucene's coding standards and includes comprehensive tests to prevent regression. Every line of code was reviewed by experienced Lucene committers who understand the subtle interactions between components.
Why This Matters
This addition extends Lucene's Performance Profiling capabilities, enabling:
- Better profiling data: Users on Java 25+ get more accurate CPU time samples
- Better integration: Compatibility with modern Java versions
- Future-proofing: Support for emerging JVM features
- Reduced workarounds: Native support eliminates the need for hacky solutions
Every feature added to Lucene is carefully designed to fit the existing architecture while enabling new possibilities. This is how Lucene stays relevant decade after decade.
Technical Details
The implementation involves changes to ProfileResults and JFR integration, carefully reviewed by the community. The code follows Lucene's established patterns for error handling, resource management, and testing.
Each commit was reviewed by multiple Lucene committers, ensuring the change meets the project's high standards for correctness, performance, and maintainability.
Related Work
This PR is part of a broader effort to optimize Lucene's Performance Profiling. Other recent contributions in this space include:
- Various performance improvements to profiling infrastructure
- Enhancements to JFR integration and event handling
- Improvements to memory management and resource accounting
The Lucene community's relentless focus on performance means that every query, every index, and every merge operation gets faster with each release.
Conclusion
JVM upgrades should not break observability. This PR ensures that when you move your Lucene deployment to Java 25, the profiling data stays accurate and complete. It's a small, focused change that prevents a future compatibility headache. If you're planning to upgrade your JDK — and you should be — this is the kind of forward-looking fix that keeps your monitoring stack intact.
About the author: I'm Prithvi S, Staff Software Engineer at Cloudera and Opensource Enthusiast. I contribute to Apache Lucene, OpenSearch, and related projects. Follow my work on GitHub.
