Call Tree¶

Namespace: dftracer::utils::call_tree

class CallTree¶

Simple, clean API for working with call trees from DFTracer traces.

Usage:

CallTree tree;
tree.load_from_directory("/path/to/traces");
tree.generate();
tree.print_depth_first();
auto nodes = tree.get_nodes_depth_first();
auto stats = tree.get_statistics();
tree.save_to_file("output.calltree");

Public Functions

CallTree()¶: Constructor

~CallTree()¶: Destructor

CallTree(const CallTree&) = delete¶

CallTree &operator=(const CallTree&) = delete¶

CallTree(CallTree&&) noexcept¶

CallTree &operator=(CallTree&&) noexcept¶

bool load_from_directory(const std::string &trace_dir, const std::string &pattern = "*.pfw.gz")¶

Specify trace directory path Automatically finds all .gz compressed trace files in the directory

Parameters:

trace_dir – Path to directory containing trace files
pattern – Optional file pattern (default: “*.pfw.gz”)

Returns:

true if directory exists and files found, false otherwise

bool generate()¶

Generate call tree from loaded traces Reads all trace files and builds the in-memory call tree structure

Returns:: true if successful, false otherwise

void print_depth_first(int max_depth = 0) const¶: Print depth-first tree to stdout. max_depth=0 means unlimited.

std::vector<CallTreeNodeInfo> get_nodes_depth_first() const¶

CallTreeStats get_statistics() const¶

Get aggregate statistics about the call tree

Returns:: Statistics structure with aggregate information

void print_statistics() const¶: Print aggregate statistics to stdout

bool is_generated() const¶

Check if call tree has been generated

Returns:: true if generate() completed successfully

size_t get_num_trace_files() const¶

Get number of trace files loaded

Returns:: Number of trace files

void clear()¶: Clear all data and reset to initial state

std::vector<std::uint32_t> get_process_ids() const¶

Get all unique process IDs in the call tree

Returns:: Vector of process IDs

std::vector<std::uint32_t> get_thread_ids(std::uint32_t pid) const¶

Get all thread IDs for a specific process

Parameters:: pid – Process ID
Returns:: Vector of thread IDs

std::vector<CallTreeNodeInfo> get_root_nodes(std::uint32_t pid, std::uint32_t tid) const¶

Get root nodes for a specific process/thread combination

Parameters:

pid – Process ID
tid – Thread ID

Returns:

Vector of root node information

std::vector<CallTreeNodeInfo> get_all_nodes() const¶

Get all nodes in the tree

Returns:: Vector of all node information

CallTreeNodeInfo get_node_by_id(std::uint64_t id) const¶

Get a specific node by ID

Parameters:: id – Node ID
Returns:: Node information (empty if not found)

internal::CallTree &internal_tree()¶: Direct access to the underlying internal::CallTree. Use with the save_binary / save_arrow coroutines in mpi/serializable.h. Returns a reference; callers must keep the CallTree alive while it’s in use.

const internal::CallTree &internal_tree() const¶

source

struct CallTreeNodeInfo¶

Simple node information structure for public API Contains basic information about a node without complex internals

Public Functions

inline CallTreeNodeInfo()¶

Public Members

std::uint64_t id¶

std::string name¶

std::string category¶

std::uint64_t start_time_us¶

std::uint64_t duration_us¶

int level¶

std::uint64_t parent_id¶

size_t num_children¶

std::vector<std::uint64_t> children_ids¶

std::unordered_map<std::string, std::string> args¶

source

struct CallTreeStats¶

Aggregate statistics about the call tree

Public Functions

inline CallTreeStats()¶

Public Members

size_t total_nodes¶

size_t num_levels¶

size_t num_leaf_nodes¶

size_t num_processes¶

int max_depth¶

size_t unique_processes¶

std::vector<double> avg_time_per_level_us¶

std::vector<size_t> nodes_per_level¶

source

class MPICallTreeBuilder¶

Public Functions

explicit MPICallTreeBuilder(const MPICallTreeConfig &config)¶

~MPICallTreeBuilder()¶

MPICallTreeBuilder(const MPICallTreeBuilder&) = delete¶

MPICallTreeBuilder &operator=(const MPICallTreeBuilder&) = delete¶

MPICallTreeBuilder(MPICallTreeBuilder&&) noexcept¶

MPICallTreeBuilder &operator=(MPICallTreeBuilder&&) noexcept¶

void add_trace_files(const std::vector<std::string> &files)¶

void add_trace_directory(const std::string &directory, const std::string &pattern = "*.pfw.gz")¶

coro::CoroTask<bool> discover_pids(CoroScope *scope)¶

coro::CoroTask<bool> build(CoroScope *scope)¶

coro::CoroTask<bool> hierarchy(CoroScope *scope)¶

coro::CoroTask<bool> write(CoroScope *scope, std::string output_path, std::string staging_dir, bool gzip)¶

coro::CoroTask<bool> merge(std::string output_path, std::string staging_dir, bool gzip, bool keep_staging)¶

inline int rank() const¶

inline int world_size() const¶

inline const std::vector<std::string> &trace_files() const¶

inline const std::set<std::uint32_t> &all_pids() const¶

inline const std::set<std::uint32_t> &assigned_pids() const¶

inline internal::CallTree &local_tree()¶

inline const internal::CallTree &local_tree() const¶

source

struct MPICallTreeConfig¶

Configuration for MPI call tree generation

Public Members

std::string output_file¶

std::string file_pattern = "*.pfw.gz"¶

bool use_indexer = true¶

bool verbose = false¶

bool summary_only = false¶

std::size_t num_threads = 0¶

std::uint64_t checkpoint_size = 0¶

source

struct MPICallTreeResult¶

Result from MPI call tree generation

Public Members

bool success = false¶

std::size_t total_pids = 0¶

std::size_t local_pids = 0¶

std::size_t total_events = 0¶

std::size_t local_events = 0¶

double elapsed_time_s = 0.0¶

std::string error_message¶