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
using	Formatter = std::function< void(std::ostream &, std::vector< Stat > const &)>
	Type alias for a statistics formatting function. More...

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

	Statistics (RmmResourceAdaptor *mr)
	Constructs a Statistics object with memory profiling enabled. More...

	Statistics (Statistics const &)=delete

Statistics &	operator= (Statistics const &)=delete

	Statistics (Statistics &&o) noexcept
	Move constructor. More...

Statistics &	operator= (Statistics &&o) noexcept
	Move assignment operator. More...

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...

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...

bool	exist_report_entry_name (std::string const &name) const
	Check whether a report entry name already has a formatter registered. More...

void	register_formatter (std::string const &name, Formatter formatter)
	Register a formatter for a single named statistic. More...

void	register_formatter (std::string const &report_entry_name, std::vector< std::string > const &stat_names, Formatter formatter)
	Register a formatter that takes multiple named statistics. 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)
	Construct from configuration options. More...

static std::shared_ptr< Statistics >	disabled ()
	Returns a shared pointer to a disabled (no-op) Statistics 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 can be accumulated and retrieved without registering a formatter. Examples: "spill-time", "spill-bytes".
Report entry name: the label of a formatted line in report(), passed to register_formatter(). An entry may aggregate one or more stats. For the single-stat overload of register_formatter(), the report entry name and stat name are identical. Example: "spill" (aggregating "spill-bytes" and "spill-time").

Statistics stats;
 
// Register a multi-stat formatter under a single report entry name.
stats.register_formatter(
    "spill",                              // report entry name
    {"spill-bytes", "spill-time"},        // stat names
    [](std::ostream& os, auto const& s) {
        os << format_nbytes(s[0].value()) << " in " << format_duration(s[1].value());
    }
);
 
stats.add_bytes_stat("spill-bytes", 1024);
stats.add_duration_stat("spill-time", 0.5);
 
auto s = stats.get_stat("spill-bytes");  // retrieve without formatter
std::cout << stats.report();

Definition at line 62 of file statistics.hpp.

Member Typedef Documentation

◆ Formatter

using rapidsmpf::Statistics::Formatter = std::function<void(std::ostream&, std::vector<Stat> const&)>

Type alias for a statistics formatting function.

The formatter receives all the named stats it declared interest in as a vector.

Definition at line 267 of file statistics.hpp.

Constructor & Destructor Documentation

◆ Statistics() [1/3]

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/3]

rapidsmpf::Statistics::Statistics ( RmmResourceAdaptor * mr )

Constructs a Statistics object with memory profiling enabled.

Automatically enables both statistics and memory profiling.

Parameters

mr	Pointer to a memory resource used for memory profiling. Must remain valid for the lifetime of the returned object.

Exceptions

std::invalid_argument If mr is the nullptr.

◆ Statistics() [3/3]

rapidsmpf::Statistics::Statistics ( Statistics && o )

inlinenoexcept

Move constructor.

Parameters

o	The Statistics object to move from.

Definition at line 116 of file statistics.hpp.

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 that formats values as human-readable byte sizes if no formatter is already registered for 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 that formats values as time durations in seconds if no formatter is already registered for name, then adds seconds to the named statistic.

Parameters

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

◆ 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.

Parameters

name	Name of the statistic.
value	Value to add.

◆ clear()

void rapidsmpf::Statistics::clear ( )

Clears all statistics.

Note: Memory profiling records and registered formatters are not cleared.

◆ 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.

◆ 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 139 of file statistics.hpp.

◆ exist_report_entry_name()

bool rapidsmpf::Statistics::exist_report_entry_name ( std::string const & name ) const

Check whether a report entry name already has a formatter registered.

Intended as a cheap pre-check before constructing arguments to register_formatter().

Note: The result may be outdated by the time it is acted upon. This method should only be used as an optimization hint to avoid unnecessary work, never for correctness decisions. Once this method returns true for a given name it will never return false again, because formatters cannot be unregistered.

Parameters

name	Report entry name to look up.

Returns: True if a formatter is registered under name, otherwise false.

◆ from_options()

static std::shared_ptr<Statistics> rapidsmpf::Statistics::from_options	(	RmmResourceAdaptor *	mr,
		config::Options	options
	)

static

Construct from configuration options.

Parameters

mr	Pointer to a memory resource used for memory profiling. Must remain valid for the lifetime of the returned object.
options	Configuration options.

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.

◆ operator=()

Statistics& rapidsmpf::Statistics::operator= ( Statistics && o )

inlinenoexcept

Move assignment operator.

Parameters

o	The Statistics object to move from.

Returns: Reference to this updated instance.

Definition at line 127 of file statistics.hpp.

◆ 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.

◆ register_formatter() [1/2]

void rapidsmpf::Statistics::register_formatter	(	std::string const &	name,
		Formatter	formatter
	)

Register a formatter for a single named statistic.

If a formatter is already registered under name, this call has no effect. The formatter is only invoked during report() if the named statistic has been recorded.

Parameters

name	Report entry name (also used as the stat name to collect).
formatter	Function used to format this statistic when reporting.

◆ register_formatter() [2/2]

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

Register a formatter that takes multiple named statistics.

If a formatter is already registered under report_entry_name, this call has no effect. The formatter is invoked during report() only if all stats in stat_names have been recorded; if any are missing the entry reads "No data collected".

Parameters

report_entry_name	Report entry name.
stat_names	Names of the stats to collect and pass to the formatter.
formatter	Function called with all collected stats during reporting.

◆ report()

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

Generates a formatted report of all collected statistics.

Every registered formatter always produces an entry. If all its required statistics have been recorded the formatter renders the values; otherwise the entry reads "No data collected". Statistics not covered by any formatter are shown as plain numeric values. 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.

◆ 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). Registered formatters, which produce human-readable strings such as "1.0 KiB" or "3.5 ms" in the text report, are not applied so that the output remains machine-parseable with consistent numeric types.

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 Typedef Documentation

◆ Formatter

Constructor & Destructor Documentation

◆ Statistics() [1/3]

◆ Statistics() [2/3]

◆ Statistics() [3/3]

Member Function Documentation

◆ add_bytes_stat()

◆ add_duration_stat()

◆ add_stat()

◆ clear()

◆ create_memory_recorder()

◆ disabled()

◆ enabled()

◆ exist_report_entry_name()

◆ from_options()

◆ get_memory_records()

◆ get_stat()

◆ is_memory_profiling_enabled()

◆ list_stat_names()

◆ operator=()

◆ record_alloc()

◆ record_copy()

◆ register_formatter() [1/2]

◆ register_formatter() [2/2]

◆ report()

◆ write_json() [1/2]

◆ write_json() [2/2]