holoscan::DataFlowTracker

Beta

The DataFlowTracker class is used to track the data flow metrics for different paths between the root operators and leaf operators.

This class is used by the developers to get the metrics data for flow during the execution of the application and at the end of it.

This class uses mutex locks on metric properties so that multiple threads on multiple operators can update the metrics without conflicts.

#include <holoscan/dataflow_tracker.hpp>

Constructors

DataFlowTracker

holoscan::DataFlowTracker::DataFlowTracker()

Destructor

~DataFlowTracker

holoscan::DataFlowTracker::~DataFlowTracker()

Methods

set_skip_starting_messages

void holoscan::DataFlowTracker::set_skip_starting_messages(
    uint64_t num
)

Set the number of messages to skip at the beginning of the execution.

This does not affect the log file or the number of source messages metric.

Parameters

num

uint64_t

The number of messages to skip.

set_skip_latencies

void holoscan::DataFlowTracker::set_skip_latencies(
    int threshold
)

Set the threshold latency for which the end-to-end latency calculations will be done.

Any latency strictly less than the threshold latency will be ignored.

This does not affect the log file or the number of source messages metric.

Parameters

threshold

int

The threshold latency in milliseconds.

set_discard_last_messages

void holoscan::DataFlowTracker::set_discard_last_messages(
    uint64_t num
)

Set the number of messages to discard at the end of the execution.

This does not affect the log file or the number of source messages metric.

Parameters

num

uint64_t

The number of messages to discard.

set_limited_tracking

void holoscan::DataFlowTracker::set_limited_tracking(
    bool limited_tracking
)

Set the limited tracking option which enables tracking only at root and leaf operators.

This also means that distinction between paths are ignored if multiple paths have the same root and leaf operators.

Parameters

limited_tracking

bool

The boolean value to set the limited tracking option. True enables tracking only at root and leaf operators.

limited_tracking

bool holoscan::DataFlowTracker::limited_tracking() const

Get whether the limited tracking option is enabled or not.

Returns: false if limited tracking is not enabled.

enable_logging

void holoscan::DataFlowTracker::enable_logging(
    std::string filename = kDefaultLogfileName,
    uint64_t num_buffered_messages = kDefaultNumBufferedMessages
)

Enable message logging at the end of the every execution of a leaf Operator.

A path consisting of an array of tuples in the form of (an Operator name, message receive timestamp, message publish timestamp) is logged in a file. The logging does not take into account the number of message to skip or discard or the threshold latency.

This function buffers a number of lines set by the num_buffered_messages parameter before flushing the buffer to the log file.

Parameters

filename

std::stringDefaults to kDefaultLogfileName

The name of the log file.

num_buffered_messages

uint64_tDefaults to kDefaultNumBufferedMessages

The number of messages to be buffered before flushing the buffer to the log file.

print

void holoscan::DataFlowTracker::print() const

Print the result of the data flow tracking in pretty-printed format to the standard output.

get_num_paths

int holoscan::DataFlowTracker::get_num_paths()

Return the number of tracked paths.

Returns: The number of tracked paths.

get_path_strings

std::vector<std::string> holoscan::DataFlowTracker::get_path_strings()

Return an array of strings which are path names.

Each path name is a comma-separated list of Operator names in a path. The paths are agnostic to the edges between two Operators.

Returns: An array of the path names.

get_metric

Return the value of a metric m for a given path

Return the value of a metric

double holoscan::DataFlowTracker::get_metric(
    const std::string &pathstring,
    holoscan::DataFlowMetric metric
)

Return the value of a metric m for a given path.

If m is DataFlowMetric::kNumSrcMessages, then the function returns -1.

Returns: The value of the metric m for the given path.

Parameters

pathstring

const std::string &

The path name string for which the metric is being queried.

metric

holoscan::DataFlowMetric

The metric to be queried.

end_logging

void holoscan::DataFlowTracker::end_logging()

Write out the remaining messages from the log buffer and close the ofstream.

generate_frame_number

uint64_t holoscan::DataFlowTracker::generate_frame_number(
    const std::string &operator_name
)

Generate a new frame number for a root operator.

Returns: The new frame number for the operator

Parameters

operator_name

const std::string &

The name of the root operator

reset_frame_numbers

void holoscan::DataFlowTracker::reset_frame_numbers()

Reset frame numbers for all operators.

set_port_frame_number

void holoscan::DataFlowTracker::set_port_frame_number(
    const std::string &operator_name,
    const std::string &port_name,
    uint64_t frame_number
)

Set frame number for a specific operator port (for NVTX display).

Parameters

operator_name

const std::string &

The name of the root operator

port_name

const std::string &

The name of the output port

frame_number

uint64_t

The frame number to set

get_port_frame_numbers

std::map<std::string, uint64_t> holoscan::DataFlowTracker::get_port_frame_numbers(
    const std::string &operator_name
) const

Get port-specific frame numbers for an operator (for NVTX display).

Returns: Map of operator-port keys to their frame numbers (e.g., “tx-out1” -> 1)

Parameters

operator_name

const std::string &

The name of the operator

add_probe_operator

void holoscan::DataFlowTracker::add_probe_operator(
    const std::string &operator_name
)

Add a probe operator by name.

If the operator name is already registered as a probe operator, a warning message will be logged.

Parameters

operator_name

const std::string &

The name of the operator to register as a probe operator.

update_latency

void holoscan::DataFlowTracker::update_latency(
    const std::string &pathstring,
    double current_latency
)

Update the tracker with the current latency for a given path.

The function internally takes care of skipping beginning messages or discarding last messages.

This function is not intended to be called by the developers. However, they may choose to update the latencies manually to account for some external overheads.

Parameters

pathstring

const std::string &

The path name string for which the latency is being updated.

current_latency

double

The current latency value.

update_source_messages_number

void holoscan::DataFlowTracker::update_source_messages_number(
    const std::string &source,
    uint64_t num
)

Update the tracker with the number of published messages for a given source Operator.

This function is not intended to be called by the developers. However, they may choose to update the number of messages externally.

Parameters

source

const std::string &

The name of the source in the form of [OperatorName->OutputName].

num

uint64_t

The new number of published messages.

write_to_logfile

void holoscan::DataFlowTracker::write_to_logfile(
    const std::string &text
)

Writes to a log file only if file logging is enabled.

Otherwise, the function does nothing. It also takes care of buffering the messages and flushing them to the log file periodically.

Parameters

text

const std::string &

The new text to be written to the log file.

add_root_op

void holoscan::DataFlowTracker::add_root_op(
    Operator *op
)

The following are internal functions to be used by the GXFExecutor to add root/leaf/probe operators to the tracker after the operators are initialized by GXF.

add_leaf_op

void holoscan::DataFlowTracker::add_leaf_op(
    Operator *op
)

add_probe_op

void holoscan::DataFlowTracker::add_probe_op(
    Operator *op
)

finalize_probe

void holoscan::DataFlowTracker::finalize_probe()

is_root_codelet

std::optional<Operator *> holoscan::DataFlowTracker::is_root_codelet(
    int64_t codelet_cid
) const

is_leaf_codelet

std::optional<Operator *> holoscan::DataFlowTracker::is_leaf_codelet(
    int64_t codelet_cid
) const

is_probe_codelet

std::optional<Operator *> holoscan::DataFlowTracker::is_probe_codelet(
    int64_t codelet_cid
) const

check_probe_op_name

bool holoscan::DataFlowTracker::check_probe_op_name(
    const std::string &operator_name
) const

Checks if the operator name is added by calling add_probe_operator(std::string).

Returns: true if the operator name was added by calling add_probe_operator(std::string), false otherwise.

Parameters

operator_name

const std::string &

The name of the operator to check.

remove_probe_op_name

void holoscan::DataFlowTracker::remove_probe_op_name(
    const std::string &operator_name
)

Member variables

Name	Type	Description
`root_ops_`	`std::map< int64_t, Operator * >`
`leaf_ops_`	`std::map< int64_t, Operator * >`
`probe_ops_`	`std::map< int64_t, Operator * >`
`probe_op_names_`	`std::unordered_set< std::string >`	Set of probe operator names.
`is_limited_tracking`	`bool`	The variable is used to indicate whether tracking is performed only at the root and leaf operators, and intermediate operators are not timestamped.
`source_messages_`	`std::map< std::string, uint64_t >`	The map of source names to the number of published messages.
`source_messages_mutex_`	`std::mutex`	The mutex for the source_messages_.
`all_path_metrics_`	`std::map< std::string, std::shared_ptr< holoscan::PathMetrics > >`	The map of path names to the path metrics.
`all_path_metrics_mutex_`	`std::mutex`	The mutex for the all_path_metrics_.
`operator_counters_`	`std::map< std::string, uint64_t >`	Simple per-operator frame counters for generation.
`port_frame_numbers_`	`std::map< std::string, uint64_t >`	Map of operator-port combinations to their frame numbers (for NVTX display).
`port_frame_numbers_mutex_`	`std::mutex`	The mutex for both maps above.
`num_start_messages_to_skip_`	`uint64_t`	The number of messages to skip at the beginning of the execution of an application graph.
`latency_threshold_`	`int`	The latency threshold in milliseconds below which we need to ignore latencies for end-to-end latency calculations.
`num_last_messages_to_discard_`	`uint64_t`	The number of messages to discard at the end of the execution of an application graph.
`is_file_logging_enabled_`	`bool`	The variable to indicate if file logging is enabled.
`logger_filename_`	`std::string`	The name of the log file.
`num_buffered_messages_`	`uint64_t`	The number of messages to be buffered before flushing the buffer to the log file.
`logger_ofstream_`	`std::ofstream`	The output file stream for the log file.
`buffered_messages_`	`std::vector< std::string >`	The buffer for the log file.
`buffered_messages_mutex_`	`std::mutex`	The mutex for the buffered_messages_.
`logfile_messages_`	`uint64_t`	The number of messages logged to the log file, used for writing to the log file.