Tracks statistics across rapidsmpf operations. More...

#include <statistics.hpp>

Classes
struct	MemoryRecord
	Holds memory profiling information for a named scope. More...

class	MemoryRecorder
	RAII-style object for scoped memory usage tracking. More...

class	Stat
	Represents a single tracked statistic. More...

Public Types
enum class	Formatter : std::uint8_t { Default = 0 , Bytes , Duration , HitRate , MemoryThroughput , _Count }
	Identifies a predefined formatter used by `report()`. More...

Public Member Functions
	Statistics (bool enabled=true)
	Constructs a Statistics object without memory profiling. More...

	Statistics (RmmResourceAdaptor mr, std::shared_ptr< PinnedMemoryResource > pinned_mr=PinnedMemoryResource::Disabled)
	Constructs a Statistics object with memory profiling enabled. More...

	Statistics (Statistics const &)=delete

Statistics &	operator= (Statistics const &)=delete

	Statistics (Statistics &&)=delete

Statistics &	operator= (Statistics &&)=delete

bool	enabled () const noexcept
	Checks if statistics tracking is enabled. More...

void	enable () noexcept
	Enable statistics tracking for this instance.

void	disable () noexcept
	Disable statistics tracking for this instance.

std::string	report (std::string const &header="Statistics:") const
	Generates a formatted report of all collected statistics. More...

void	write_json (std::ostream &os) const
	Writes a JSON representation of all collected statistics to a stream. More...

void	write_json (std::filesystem::path const &filepath) const
	Writes a JSON report of all collected statistics to a file. More...

std::shared_ptr< Statistics >	copy () const
	Creates a deep copy of this Statistics object. More...

std::vector< std::uint8_t >	serialize () const
	Serializes the stats and report entries to a binary byte vector. More...

Stat	get_stat (std::string const &name) const
	Retrieves a statistic by name. More...

void	add_stat (std::string const &name, double value)
	Adds a numeric value to the named statistic. More...

void	add_report_entry (std::string const &report_entry_name, std::initializer_list< std::string_view > stat_names, Formatter formatter)
	Associate a formatter with one or more named statistics for report rendering. More...

void	add_report_entry (std::string const &report_entry_name, std::vector< std::string > stat_names, Formatter formatter)
	Associate a formatter with one or more named statistics for report rendering. More...

void	add_bytes_stat (std::string const &name, std::size_t nbytes)
	Adds a byte count to the named statistic. More...

void	add_duration_stat (std::string const &name, Duration seconds)
	Adds a duration to the named statistic. More...

void	record_copy (MemoryType src, MemoryType dst, std::size_t nbytes, StreamOrderedTiming &&timing)
	Record byte count and wall-clock duration for a memory copy operation. More...

void	record_alloc (MemoryType mem_type, std::size_t nbytes, StreamOrderedTiming &&timing)
	Record size and wall-clock duration for a buffer allocation. More...

std::vector< std::string >	list_stat_names () const
	Get the names of all statistics. More...

void	clear ()
	Clears all statistics. More...

bool	is_memory_profiling_enabled () const
	Checks whether memory profiling is enabled. More...

MemoryRecorder	create_memory_recorder (std::string name)
	Creates a scoped memory recorder for the given name. More...

std::unordered_map< std::string, MemoryRecord > const &	get_memory_records () const
	Retrieves all memory profiling records stored by this instance. More...

Static Public Member Functions
static std::shared_ptr< Statistics >	from_options (RmmResourceAdaptor mr, config::Options options, std::shared_ptr< PinnedMemoryResource > pinned_mr=PinnedMemoryResource::Disabled)
	Construct from configuration options. More...

static std::shared_ptr< Statistics >	disabled ()
	Returns a shared pointer to a disabled (no-op) Statistics instance. More...

static std::shared_ptr< Statistics >	deserialize (std::span< std::uint8_t const > data)
	Deserializes a Statistics object from a binary byte vector. More...

static std::shared_ptr< Statistics >	merge (std::span< std::shared_ptr< Statistics > const > stats)
	Merge a set of Statistics into a new instance. More...

Detailed Description

Tracks statistics across rapidsmpf operations.

Two naming concepts are used throughout this class:

Stat name: identifies an individual Stat accumulator, as passed to add_stat(), get_stat(), add_bytes_stat(), and add_duration_stat(). Stats are pure numeric accumulators with no associated rendering information. Examples: "spill-time", "spill-bytes".
Report entry name: the label of a formatted line in report(), passed to add_report_entry(). An entry names one or more stats and a Formatter that selects how those stats are rendered. When the entry covers a single stat, the report entry name and stat name are typically identical. Example: "spill" (aggregating "spill-bytes" and "spill-time").

Formatters are a fixed, predefined set (see Statistics::Formatter).

Statistics stats;
 
// Associate two stats with a predefined multi-stat formatter.
stats.add_report_entry(
    "copy-device-to-host",                // report entry name
    {"copy-device-to-host-bytes",
     "copy-device-to-host-time",
     "copy-device-to-host-stream-delay"},
    Statistics::Formatter::MemoryThroughput
);
 
stats.add_bytes_stat("spill-bytes", 1024);    // helper: registers Bytes entry
stats.add_duration_stat("spill-time", 0.5s);  // helper: registers Duration entry
 
auto s = stats.get_stat("spill-bytes");  // retrieve without formatter
std::cout << stats.report();

Definition at line 71 of file statistics.hpp.

Member Enumeration Documentation

◆ Formatter

enum rapidsmpf::Statistics::Formatter : std::uint8_t

strong

Identifies a predefined formatter used by report().

Each formatter consumes a fixed number of Stat entries and renders them into a human-readable string.

Available formatters (examples):

Default (1 stat): "123"
Bytes (1 stat): "1.2 GiB | avg 300 MiB"
Duration (1 stat): "2.5 ms | avg 600 us"
HitRate (1 stat): "42/100 (hits/lookups)"
MemoryThroughput (3 stats: bytes, time, stream-delay), where stream-delay is the wall-clock gap between CPU submission and GPU execution of the operation: "1.2 GiB | 2.5 ms | 480 GiB/s | avg-stream-delay 10 us"

_Count is an internal sentinel — always keep it last.

Enumerator
_Count	Sentinel; must remain last.

Definition at line 99 of file statistics.hpp.

Constructor & Destructor Documentation

◆ Statistics() [1/2]

rapidsmpf::Statistics::Statistics ( bool enabled = true )

Constructs a Statistics object without memory profiling.

Parameters

enabled If true, enables tracking of statistics. If false, all operations are no-ops.

◆ Statistics() [2/2]

rapidsmpf::Statistics::Statistics	(	RmmResourceAdaptor	mr,
		std::shared_ptr< PinnedMemoryResource >	pinned_mr = `PinnedMemoryResource::Disabled`
	)

Constructs a Statistics object with memory profiling enabled.

Automatically enables both statistics and memory profiling.

Parameters

mr	The RMM resource adaptor used for memory profiling.
pinned_mr	Optional pinned host memory resource for profiling; defaults to `PinnedMemoryResource::Disabled`.

Member Function Documentation

◆ add_bytes_stat()

void rapidsmpf::Statistics::add_bytes_stat	(	std::string const &	name,
		std::size_t	nbytes
	)

Adds a byte count to the named statistic.

Registers a Formatter::Bytes report entry named name if no report entry already exists under that name, then adds nbytes to the named statistic.

Parameters

name	Name of the statistic.
nbytes	Number of bytes to add.

◆ add_duration_stat()

void rapidsmpf::Statistics::add_duration_stat	(	std::string const &	name,
		Duration	seconds
	)

Adds a duration to the named statistic.

Registers a Formatter::Duration report entry named name if no report entry already exists under that name, then adds seconds to the named statistic.

Parameters

name	Name of the statistic.
seconds	Duration in seconds to add.

◆ add_report_entry() [1/2]

void rapidsmpf::Statistics::add_report_entry	(	std::string const &	report_entry_name,
		std::initializer_list< std::string_view >	stat_names,
		Formatter	formatter
	)

Associate a formatter with one or more named statistics for report rendering.

First-wins: if a report entry is already registered under report_entry_name, this call has no effect. The entry appears in report() as a single line; if any stat it references is missing, the line reads "No data collected".

Parameters

report_entry_name	Report entry name.
stat_names	Names of the stats this entry aggregates. Caller is responsible for passing the number of stats the chosen `formatter` expects; a mismatch surfaces as `std::out_of_range` when `report()` renders the entry.
formatter	Predefined formatter to render the entry with.

◆ add_report_entry() [2/2]

void rapidsmpf::Statistics::add_report_entry	(	std::string const &	report_entry_name,
		std::vector< std::string >	stat_names,
		Formatter	formatter
	)

Associate a formatter with one or more named statistics for report rendering.

First-wins: if a report entry is already registered under report_entry_name, this call has no effect. The entry appears in report() as a single line; if any stat it references is missing, the line reads "No data collected".

Parameters

report_entry_name	Report entry name.
stat_names	Names of the stats this entry aggregates. Caller is responsible for passing the number of stats the chosen `formatter` expects; a mismatch surfaces as `std::out_of_range` when `report()` renders the entry.
formatter	Predefined formatter to render the entry with.

Overload for callers whose stat names come from a runtime container (e.g. the Python bindings).

◆ add_stat()

void rapidsmpf::Statistics::add_stat	(	std::string const &	name,
		double	value
	)

Adds a numeric value to the named statistic.

Creates the statistic if it doesn't exist. Does not associate any formatter with the stat — use add_report_entry() (or a helper like add_bytes_stat()) for that.

Parameters

name	Name of the statistic.
value	Value to add.

◆ clear()

void rapidsmpf::Statistics::clear ( )

Clears all statistics.

Note: Memory profiling records and report entries are not cleared.

◆ copy()

std::shared_ptr<Statistics> rapidsmpf::Statistics::copy ( ) const

Creates a deep copy of this Statistics object.

Note: Memory records are not copied.

Returns: A shared pointer to the new copy.

◆ create_memory_recorder()

MemoryRecorder rapidsmpf::Statistics::create_memory_recorder ( std::string name )

Creates a scoped memory recorder for the given name.

If memory profiling is not enabled, returns a no-op recorder.

Parameters

name	Name of the scope.

Returns: A MemoryRecorder instance.

◆ deserialize()

static std::shared_ptr<Statistics> rapidsmpf::Statistics::deserialize ( std::span< std::uint8_t const > data )

static

Deserializes a Statistics object from a binary byte vector.

Note: The resulting object has no memory records.

Parameters

data	The serialized statistics data.

Returns: A shared pointer to the reconstructed Statistics object.

Exceptions

std::invalid_argument If the data is malformed or truncated.

◆ disabled()

static std::shared_ptr<Statistics> rapidsmpf::Statistics::disabled ( )

static

Returns a shared pointer to a disabled (no-op) Statistics instance.

Useful when you need to pass a Statistics reference but do not want to collect any data.

Returns: A shared pointer to a Statistics instance with tracking disabled.

◆ enabled()

bool rapidsmpf::Statistics::enabled ( ) const

inlinenoexcept

Checks if statistics tracking is enabled.

Returns: True if statistics tracking is active, otherwise False.

Definition at line 170 of file statistics.hpp.

◆ from_options()

static std::shared_ptr<Statistics> rapidsmpf::Statistics::from_options	(	RmmResourceAdaptor	mr,
		config::Options	options,
		std::shared_ptr< PinnedMemoryResource >	pinned_mr = `PinnedMemoryResource::Disabled`
	)

static

Construct from configuration options.

Parameters

mr	The RMM resource adaptor used for memory profiling.
options	Configuration options.
pinned_mr	Optional pinned host memory resource for profiling; defaults to `PinnedMemoryResource::Disabled`.

Returns: A shared pointer to the constructed Statistics instance.

◆ get_memory_records()

std::unordered_map<std::string, MemoryRecord> const& rapidsmpf::Statistics::get_memory_records ( ) const

Retrieves all memory profiling records stored by this instance.

Returns: A reference to a map from record name to memory usage data.

◆ get_stat()

Stat rapidsmpf::Statistics::get_stat ( std::string const & name ) const

Retrieves a statistic by name.

Parameters

name	Name of the statistic.

Returns: The requested statistic.

◆ is_memory_profiling_enabled()

bool rapidsmpf::Statistics::is_memory_profiling_enabled ( ) const

Checks whether memory profiling is enabled.

Returns: True if memory profiling is active, otherwise False.

◆ list_stat_names()

std::vector<std::string> rapidsmpf::Statistics::list_stat_names ( ) const

Get the names of all statistics.

Returns: A vector of all statistic names.

◆ merge()

static std::shared_ptr<Statistics> rapidsmpf::Statistics::merge ( std::span< std::shared_ptr< Statistics > const > stats )

static

Merge a set of Statistics into a new instance.

For each stat name present across the inputs, the result contains the summed count, summed value, and the maximum of the recorded maxima. The result's enabled() is true if any input is enabled. Memory records are not merged.

Report entries are unified by name. If multiple inputs contain the same report-entry name, their Formatter and stat_names must match; otherwise, this function throws std::invalid_argument to prevent silent rendering inconsistencies (especially across serialize/deserialize boundaries).

Parameters

stats Non-empty span of non-null Statistics instances to merge.

Returns: A new Statistics instance containing the merged data.

Exceptions

std::invalid_argument If stats is empty, contains a null pointer, or if inputs disagree on the formatter or stat-name set for a shared report entry.

◆ record_alloc()

void rapidsmpf::Statistics::record_alloc	(	MemoryType	mem_type,
		std::size_t	nbytes,
		StreamOrderedTiming &&	timing
	)

Record size and wall-clock duration for a buffer allocation.

Records three statistics entries for "alloc-{memtype}":

"-bytes" — the number of bytes allocated.
"-time" — the allocation duration, recorded in stream order.
"-stream-delay" — time between CPU submission and GPU execution, recorded in stream order.

All three entries are aggregated into a single combined report line showing total bytes, total time, throughput, and average stream delay.

Parameters

mem_type	Memory type of the allocation.
nbytes	Number of bytes allocated.
timing	A `StreamOrderedTiming` constructed just before the allocation was issued. Its `stop_and_record()` is called here.

◆ record_copy()

void rapidsmpf::Statistics::record_copy	(	MemoryType	src,
		MemoryType	dst,
		std::size_t	nbytes,
		StreamOrderedTiming &&	timing
	)

Record byte count and wall-clock duration for a memory copy operation.

Records three statistics entries for "copy-{src}-to-{dst}":

"-bytes" — the number of bytes copied.
"-time" — the copy duration, recorded in stream order.
"-stream-delay" — time between CPU submission and GPU execution of the copy, recorded in stream order.

All three entries are aggregated into a single combined report line under the name "copy-{src}-to-{dst}", showing total bytes, total time, bandwidth, and average stream delay.

Parameters

src	Source memory type.
dst	Destination memory type.
nbytes	Number of bytes copied.
timing	A `StreamOrderedTiming` that should be started just before the copy was enqueued on the stream. Its `stop_and_record()` is called here to enqueue the stop callback.

◆ report()

std::string rapidsmpf::Statistics::report ( std::string const & header = "Statistics:" ) const

Generates a formatted report of all collected statistics.

Every registered report entry always produces a line. If all the stats it references have been recorded, the entry's Formatter renders the values; otherwise the line reads "No data collected". Statistics not covered by any report entry are shown with Formatter::Default (raw numeric value, optionally annotated with the count). All entries are sorted alphabetically.

Note: If any statistics are collected via stream-ordered timing (e.g. through record_copy()), all relevant CUDA streams must be synchronized before calling this method. Otherwise, some timing statistics may not yet have been recorded, causing entries to read "No data collected" or imprecise statistics.

Parameters

header Header line prepended to the report.

Returns: Formatted statistics report.

◆ serialize()

std::vector<std::uint8_t> rapidsmpf::Statistics::serialize ( ) const

Serializes the stats and report entries to a binary byte vector.

Note: Memory records are not serialized.

Returns: A vector of bytes containing the serialized statistics.

◆ write_json() [1/2]

void rapidsmpf::Statistics::write_json ( std::filesystem::path const & filepath ) const

Writes a JSON report of all collected statistics to a file.

Parameters

filepath Path to the output file. Created or overwritten.

Exceptions

std::ios_base::failure If the file cannot be opened or writing fails.

◆ write_json() [2/2]

void rapidsmpf::Statistics::write_json ( std::ostream & os ) const

Writes a JSON representation of all collected statistics to a stream.

Values are written as raw numbers (count, sum, max). Formatter metadata is not emitted — use report() for the human-readable rendering.

Parameters

os	Output stream to write to.

Exceptions

std::invalid_argument If any stat name or memory record name contains characters that require JSON escaping (double quotes, backslashes, or ASCII control characters 0x00–0x1F).

The documentation for this class was generated from the following file:

/__w/rapidsmpf/rapidsmpf/cpp/include/rapidsmpf/statistics.hpp

Classes

Public Types

Public Member Functions

Static Public Member Functions

Detailed Description

Member Enumeration Documentation

◆ Formatter

Constructor & Destructor Documentation

◆ Statistics() [1/2]

◆ Statistics() [2/2]

Member Function Documentation

◆ add_bytes_stat()

◆ add_duration_stat()

◆ add_report_entry() [1/2]

◆ add_report_entry() [2/2]

◆ add_stat()

◆ clear()

◆ copy()

◆ create_memory_recorder()

◆ deserialize()

◆ disabled()

◆ enabled()

◆ from_options()

◆ get_memory_records()

◆ get_stat()

◆ is_memory_profiling_enabled()

◆ list_stat_names()

◆ merge()

◆ record_alloc()

◆ record_copy()

◆ report()

◆ serialize()

◆ write_json() [1/2]

◆ write_json() [2/2]