Utilities API

See also

For complete class and member documentation, see the API Reference.

Composable processing utilities. For usage examples, see Utilities.

Base Classes

All utilities inherit from UtilityBase, which provides tag introspection, context management, and naming. Two derived templates define the process() contract:

• Utility<I, O, Tags...> — materialized output: process() returns CoroTask<O>

• StreamingUtility<I, Batch, Tags...> — streaming output: process() returns AsyncGenerator<Batch>

        classDiagram
    class UtilityBase~I, Tags~ {
        +has_tag~Tag~() bool
        +get_tag~Tag~() Tag
        +get_name() string
        +set_name(string)
        #context() CoroScope
    }
    class Utility~I, O, Tags~ {
        +process(I) CoroTask~O~
    }
    class StreamingUtility~I, Batch, Tags~ {
        +process(I) AsyncGenerator~Batch~
    }
    UtilityBase <|-- Utility
    UtilityBase <|-- StreamingUtility
    

UtilityBase

Shared base for all utilities. Provides tag introspection (has_tag<>, get_tag<>), context management (context() for NeedsContext utilities), and name/type signature generation.

Utility (Materialized)

For utilities that compute a single result. process() returns CoroTask<O> — the caller co_awaits the result.

StreamingUtility

For utilities that yield results incrementally. process() returns AsyncGenerator<Batch> — the caller iterates with co_await gen.next().

Batch structs typically provide a to_arrow() method for Arrow conversion (e.g., ViewReaderBatch::to_arrow(), AggregationBatch::to_arrow()).

// Consuming a StreamingUtility
ViewReaderUtility reader;
auto gen = reader.process(input);
while (auto batch = co_await gen.next()) {
    // Use C++ data directly
    for (const auto& event : batch->events) { ... }

    // Or convert to Arrow
    auto arrow = batch->to_arrow();
}

Module Reference

Each module below has detailed class documentation in the API Reference:

Module	Description	API Reference
Call Tree	Build hierarchical call trees from DFTracer traces	Call Tree
Filesystem	Directory scanning utilities	Filesystem
File I/O	File reading, writing, chunk writing, async line generators	File I/O
Compression	Streaming zlib compression (GZIP, ZLIB, DEFLATE)	Generic Composites
Text	Line splitting, filtering, text processing	Text Processing
Hash	FNV1a, std::hash, MT-safe hasher utilities	Hash Utilities
Statistics	DDSketch (percentiles), Log2Histogram (distributions)	DFTracer Statistics
Indexer	Bloom filter indexes, manifests, provenance tracking	Indexer
Reader	Streaming trace file reader with index support	Reader
Views	View definitions and predicate-based event filtering	DFTracer Views & Predicates
Aggregation	Time-bucketed aggregation pipeline with Arrow output	DFTracer Aggregation Pipeline
Comparator	Baseline vs variant trace comparison with Cohen’s d	DFTracer Comparator
Reorganization	Parallel event routing and chunked output	DFTracer Reorganization
Replay	Replay I/O operations from traces	Replay