> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.nvidia.com/holoscan/sdk-user-guide/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.nvidia.com/holoscan/sdk-user-guide/_mcp/server.

# holoscan::DataFlowTracker

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

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.

```cpp showLineNumbers={false}
#include <holoscan/dataflow_tracker.hpp>
```

---

## Constructors

### DataFlowTracker \[#dataflowtracker]

```cpp showLineNumbers={false}
holoscan::DataFlowTracker::DataFlowTracker()
```

### Destructor \[#destructor]

### \~DataFlowTracker

```cpp showLineNumbers={false}
holoscan::DataFlowTracker::~DataFlowTracker()
```

---

## Methods

### set\_skip\_starting\_messages \[#setskipstartingmessages]

```cpp showLineNumbers={false}
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 \[#setskiplatencies]

```cpp showLineNumbers={false}
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 \[#setdiscardlastmessages]

```cpp showLineNumbers={false}
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 \[#setlimitedtracking]

```cpp showLineNumbers={false}
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 \[#limitedtracking]

```cpp showLineNumbers={false}
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 \[#enablelogging]

```cpp showLineNumbers={false}
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](operator).

A path consisting of an array of tuples in the form of (an [Operator](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::string` — default: kDefaultLogfileName

The name of the log file.

---

**`num_buffered_messages`** `uint64_t` — default: kDefaultNumBufferedMessages

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

---

### print \[#print]

```cpp showLineNumbers={false}
void holoscan::DataFlowTracker::print() const
```

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

### get\_num\_paths \[#getnumpaths]

```cpp showLineNumbers={false}
int holoscan::DataFlowTracker::get_num_paths()
```

Return the number of tracked paths.

**Returns:** The number of tracked paths.

### get\_path\_strings \[#getpathstrings]

```cpp showLineNumbers={false}
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](operator) names in a path. The paths are agnostic to the edges between two Operators.

**Returns:** An array of the path names.

### get\_metric \[#getmetric]

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

```cpp showLineNumbers={false}
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.

---

#### Return the value of a metric

```cpp showLineNumbers={false}
std::map<std::string, uint64_t> holoscan::DataFlowTracker::get_metric(
    holoscan::DataFlowMetric metric = DataFlowMetric::kNumSrcMessages
)
```

Return the value of a metric.

The metric must be DataFlowMetric::kNumSrcMessages.

**Returns:** The map of source names to the number of published messages.

**Parameters**

**`metric`** `holoscan::DataFlowMetric` — default: DataFlowMetric::kNumSrcMessages

The metric to be queried.

---

### end\_logging \[#endlogging]

```cpp showLineNumbers={false}
void holoscan::DataFlowTracker::end_logging()
```

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

### generate\_frame\_number \[#generateframenumber]

```cpp showLineNumbers={false}
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 \[#resetframenumbers]

```cpp showLineNumbers={false}
void holoscan::DataFlowTracker::reset_frame_numbers()
```

Reset frame numbers for all operators.

### set\_port\_frame\_number \[#setportframenumber]

```cpp showLineNumbers={false}
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 \[#getportframenumbers]

```cpp showLineNumbers={false}
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](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 \[#addprobeoperator]

```cpp showLineNumbers={false}
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 \[#updatelatency]

```cpp showLineNumbers={false}
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 \[#updatesourcemessagesnumber]

```cpp showLineNumbers={false}
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](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 \[#writetologfile]

```cpp showLineNumbers={false}
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 \[#addrootop]

```cpp showLineNumbers={false}
void holoscan::DataFlowTracker::add_root_op(
    const std::shared_ptr<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 \[#addleafop]

```cpp showLineNumbers={false}
void holoscan::DataFlowTracker::add_leaf_op(
    const std::shared_ptr<Operator> &op
)
```

### add\_probe\_op \[#addprobeop]

```cpp showLineNumbers={false}
void holoscan::DataFlowTracker::add_probe_op(
    const std::shared_ptr<Operator> &op
)
```

### finalize\_probe \[#finalizeprobe]

```cpp showLineNumbers={false}
void holoscan::DataFlowTracker::finalize_probe()
```

### is\_root\_codelet \[#isrootcodelet]

```cpp showLineNumbers={false}
std::optional<Operator *> holoscan::DataFlowTracker::is_root_codelet(
    int64_t codelet_cid
) const
```

### is\_leaf\_codelet \[#isleafcodelet]

```cpp showLineNumbers={false}
std::optional<Operator *> holoscan::DataFlowTracker::is_leaf_codelet(
    int64_t codelet_cid
) const
```

### is\_probe\_codelet \[#isprobecodelet]

```cpp showLineNumbers={false}
std::optional<Operator *> holoscan::DataFlowTracker::is_probe_codelet(
    int64_t codelet_cid
) const
```

### check\_probe\_op\_name \[#checkprobeopname]

```cpp showLineNumbers={false}
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 \[#removeprobeopname]

```cpp showLineNumbers={false}
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](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.                                                                    |