Crate time_graph

time-graph provides always-on profiling for your code, allowing to record the execution time of functions, spans inside these functions and the full call graph of spans and functions at run-time.

Core concepts

There are two main concepts in this crate: CallSite identify a single call site in the source, usually a full function. One can then create a Span from any callsite, representing a single execution of the code. When executed, the Span will its elapsed time, and store it in the global call graph.

Controlling data collection

By default, no data is collected until you call enable_data_collection to start collecting timing data. Once you are done running your code, you can extract collected data with get_full_graph, and possibly clear all collected data using clear_collected_data.

Overhead and limitations

When data collection is disabled, this crate adds an overheard around 10 ns when calling a function or entering a span. With data collection enabled, this crate adds an overhead around 100 ns when calling a function or entering a span.

This makes this crate only useful for gathering profiling data on function/spans taking at least 1 µs to execute.

Crate features

This crate has two cargo features:

• json: enables json output format for the full call graph
• table: enables pretty-printing the full call graph to a table using term-table

Macros

callsite

Create a new CallSite with the given name at the current source location.

spanned

Run a block of code inside a new span

Structs

CallSite

A CallSite identify uniquely a location in the source code, and record multiple attributes associated with this location.

FullCallGraph

Full call graph including execution time and number of calls between functions/spans.

Span

A Span records a single execution of code associated with a CallSite.

SpanGuard

When a SpanGuard is dropped, it saves the execution time of the corresponding span in the global call graph.

TimedSpan

TimedSpan contains all data related to a single function or span inside the global call graph.

Functions

clear_collected_data

Clear the global call graph from all data

enable_data_collection

Enable/disable data collection

get_full_graph

Get a copy of the call graph as currently known

traverse_registered_callsite

Execute the given function on all call sites we know about.

Attribute Macros

instrument

Instruments a function to create and enter a time-graph span every time the function is called.