v0.14.0

• Deprecation Warnings Activated: All legacy .h forwarding headers (e.g., perfcpp/sampler.h, perfcpp/event_counter.h) now emit a compile-time #pragma message warning directing users to the .hpp replacements introduced in v0.13.0. The old headers will be removed in v1.0. If you see a deprecation message, replace the include with the .hpp variant (e.g., #include <perfcpp/sampler.hpp>).
• CGroup Monitoring: Added support for monitoring all tasks belonging to a cgroup (container). Configure a perf::CGroupMonitor (constructed from a path, a cgroup name, a SharedFileDescriptor, or a UniqueFileDescriptor) and pass it to Config::cgroup(). Requires a specific CPU core (CpuCore::Any is rejected) and CAP_PERFMON or perf_event_paranoid <= 0. See the recording documentation.
• Sampler Input Validation: Opening a sampler with an invalid period or frequency now raises an exception immediately. Period must be greater than zero; frequency must be between 1 and the kernel's perf_event_max_sample_rate limit.
• RAPL Energy Measurement Example: Added an example program demonstrating how to measure energy consumption of a code segment using the built-in watts-pkg, watts-cores, and watts-ram metrics.
• Bugfixes:
  • perf::CpuCore now accepts std::uint16_t as a CPU core id
  • Fixed multiple event codes in the event library across AMD Zen5 and Intel Panther Lake

v0.13.1

• Configurable Sampling Triggers: Typed triggers now fully support hardware-specific configuration:
  • Intel: perf::MemoryLoads supports configurable min_latency for PEBS load latency filtering. perf::MemoryStores and perf::MemoryLoadsAux provide type-safe alternatives to string-based mem-stores and mem-loads-aux triggers. String-based triggers remain available and documented.
  • AMD: perf::IbsOp and perf::IbsFetch now build their counter configuration directly from hardware capabilities, fully supporting is_uop, is_l3_miss_only, and is_rand flags. String-based trigger variants (ibs_op_uops, ibs_op_l3missonly, ibs_op_uops_l3missonly, ibs_fetch_l3missonly) still work but are no longer documented. Use typed triggers for full configurability.
• Fixed-Function PMC Scheduling: On Intel processors, the built-in events instructions, cycles, cpu-cycles, and ref-cycles are now automatically scheduled to dedicated pinned groups. This prevents the kernel scheduler from placing fixed-function PMC events alongside generic events, which would distort multiplexing ratios. Fixed groups do not count against the generic PMC limit.
• Fixed PMC Detection: Added HardwareInfo::physical_fixed_performance_counters_per_logical_core(), which reads the number of fixed-function performance counters on Intel.
• Built-in Event: Added ref-cycles (reference cycles at a fixed frequency, unaffected by turbo boost or power-saving states) to the built-in hardware event list.
• Bugfixes:
  • Fixed out-of-bounds access when reading live counter values.
  • Fixed wrong parsing order for throttle events in the sample decoder.
  • Fixed sample decoder always reporting a data access source even when none was available (e.g., when sampling stores on Intel hardware).
  • Fixed various decoding bugs and hardened the sample decoder against malformed records.
  • Adding events to an already-opened EventCounter now raises an exception instead of silently failing.

v0.13.0

• Header Restructuring: Headers have been reorganized into counter/, sample/, metric/, analyzer/, and util/ subdirectories and renamed from .h to .hpp. The previous .h headers remain as forwarding includes with deprecation notices and will be removed in v1.0.
• Breaking: EventCounter::add() and start() (including Sampler::start() and all multi-thread/core variants) now return void instead of bool. Errors are communicated via exceptions; the return values were unused.
• Compile Flag for AUX Buffer Support: Added PERFCPP_NO_SAMPLE_AUX compile flag to disable auxiliary buffer sampling on systems with Linux kernels older than 5.5 that lack PERF_SAMPLE_AUX support. Thanks to @rconnorlawson.
• Perf File Export: Fixed bugs in perf format when materializing samples into file that can be read via perf [mem] report.
• NMI Watchdog Detection: Hardware counter detection now accounts for the NMI watchdog permanently consuming one hw-PMU counter, fixing incorrect counter counts on systems with the watchdog enabled.
• RAPL Power Metrics: Added built-in watts-pkg, watts-cores, and watts-ram metrics for measuring power consumption via RAPL energy counters (see the documentation).
• Conan Package: Added Conan 2.x package recipe for easier integration.
• Config Setter Naming: Standardized Config setter naming — setters no longer use the is_ prefix (e.g., pinned(bool) instead of is_pinned(bool)). The old is_pinned(bool) and is_debug(bool) setters are deprecated and will be removed in v1.0.
• SampleResult CSV Export: Added SampleResult::to_csv() returning a std::string, complementing the existing file-based overload.
• Per-Element Results: Added result_of_thread(thread_id), result_of_process(process_id), and result_of_core(core_id) to query individual results from MultiThreadEventCounter, MultiProcessEventCounter, and MultiCoreEventCounter. Process and core variants return std::optional<CounterResult> since the ID may not be present.
• Documentation: Rewrote and restructured all documentation pages for consistency, conciseness, and correctness. Documentation is now hosted at jmuehlig.github.io/perf-cpp.

v0.12.6

• CSV Export: Samples can now be exported to CSV format using SampleResult::to_csv(), enabling custom analysis with statistical tools, spreadsheets, or data processing pipelines (see the documentation).
• Flamegraphs: Samples can be exported to flamegraphs via SampleResult::to_flamegraphs(std::string&&) (see the documentation).
• Fine-Grained Sampling Configuration: The sampling API now provides more granular control over which data fields are recorded. Previously coarse-grained options have been split into specific setters, allowing precise selection of hardware-specific metrics. See the sampling documentation for more information. New setters include:
  • Physical Instruction Pointer (AMD IBS Fetch PMU only)
  • Instruction Type (AMD IBS Op PMU for Return and Branch types)
  • Branch Type (AMD IBS Op PMU only)
  • Instruction Latency (Intel: instruction retirement cycles; AMD IBS Op PMU: uOp tag-to-retirement, completion-to-retirement, tag-to-completion; AMD IBS Fetch PMU: fetch latency)
  • Instruction Cache (AMD IBS Fetch PMU only)
  • Instruction TLB (AMD IBS Fetch PMU only)
  • Instruction Fetch (AMD IBS Fetch PMU only)
  • Data TLB Page Size (AMD IBS Op PMU only)
  • Data TLB Latency (AMD IBS Op PMU only)
  • Data Access Width (AMD IBS Op PMU only)
  • Data Access Misalignment Penalty (AMD IBS Op PMU only)
  • MHB/MAB Allocations (AMD IBS Op PMU only)
  • Auxiliary Values
• Added perf::Config::include_host(bool) to enable excluding host events when counting hardware events in virtual machines (see the documentation).
• Added perf::Config::is_pinned(bool) to enable pinning events to the PMU (see the documentation).

v0.12.5

• Bugfix: The library could not compile for specific Linux kernels (see #10).
• Symbol Translation: Improved translation from instruction pointer to symbol.

v0.12.4

• Bugfix: The library crashed when events loaded from an external CSV file contained empty spaces (see #8). Thanks to @Liteom.
• Bugfix: The library could not compile for specific Linux kernels not providing PERF_MEM_LVLNUM_UNC and PERF_MEM_SNOOPX_PEER (see #7). Thanks to @Raphalex46 for pointing out.
• Perf Data Export: Samples can now be written as perf data files using Sampler::to_perf_file(), enabling analysis with standard perf ecosystem tools like perf report (see the documentation). Note that this feature is experimental.

v0.12.3

This update simplifies the handling of counter definitions by introducing a default instance.

• Default Counter Definitions: Supplying a user-defined perf::CounterDefinition to each perf::EventCounter or perf::Sampler is no longer required. If none is provided, a default instance is used automatically. Custom definitions now extend the default set of events instead of duplicating them.

v0.12.2

• Metric Functions: Metrics now support built-in functions such as ratio(A, B) and sum(A, B, C, ...), enabling more expressive and reusable formulas (see the documentation).
• Optimized Compile-time Event Injection: The generated runtime event registration class is now only created if it does not already exist, reducing unnecessary recompilation.
• Improved Live Event Accuracy: Live event values now account for partial runtime durations via time scaling, improving accuracy when counters were not active for the full measurement window.

v0.12.1

• Automatic Event Discovery on ARM: Hardware event types are now automatically detected on ARM architectures when initializing a perf::CounterDefinition instance.
• Hardware Counter Introspection: The number of available physical performance counters per logical core, along with the number of events each counter can multiplex, is now determined automatically when creating a perf::EventCounter.
• Recursive and Scientific Metrics: Metric expressions can now reference other metrics recursively. Support for scientific notation (e.g., 1e5) in formula-based metrics has also been added.

v0.12.0

This release expands symbolic analysis capabilities, introduces FlameGraph generation, and improves hardware event management through both runtime and compile-time support.

• Symbol Resolution: Instruction pointers captured during sampling can now be resolved to function names using perf::SymbolResolver (see the documentation).
• FlameGraph Export: Sampling data can be converted into formats compatible with visualization tools such as Brendan Gregg's FlameGraph, Speedscope, and flamegraph.com using perf::analyzer::FlameGraphGenerator (see the documentation).
• Built-in Event Definitions: A set of x86-specific hardware events is now bundled in events/x86 and can be loaded at runtime using perf::CounterDefinition. This serves as an alternative to the make perf-list target.
• Compile-time Event Injection: Processor-specific event definitions can now be embedded directly at build time by configuring CMake with -DGEN_PROCESSOR_EVENTS=1. These are immediately available via perf::CounterDefinition (see the documentation).
• Automatic Event Discovery: Additional event types–including RAPL energy counters and AMD IO MMU events–are now automatically detected during the creation of a perf::CounterDefinition instance (issue #6).