🚧 Work in progress: this documentation is still being written and reviewed. Check details against the source code.

Callback timing reports

Generate Markdown timing reports from recorded ROS callback traces using pandas and tracetools_analysis.

src.beambot.scripts.perf_trace_summarize · Source

Task execution · Guide · Symbol index

How it is used

Use main() to read an existing ros2_tracing CTF directory and produce a Markdown report. collect_callback_stats() builds the underlying table; the other helpers format the report. No robot or ROS node is started by this script.

Interpret the values as callback execution durations and cumulative callback time. They are not message transport latency or end-to-end task duration; overlapping callbacks can contribute time concurrently.

Start here

Callable	Purpose
main	Load a CTF trace, compute callback statistics and emit top cumulative-time callbacks, p95 callbacks with at least three samples, and owner rollups.
collect_callback_stats	For callback objects present in the trace instances table, collect duration statistics and resolve symbols/owners with fallbacks for missing registration data.

Example

From a sourced workspace, summarise an existing trace:

ros2 run beambot perf_trace_summarize.py trace_session --out report.md

The report lists the top 20 entries in each table by default. --out replaces an existing report at that path.

Functions

main()

Load a CTF trace, compute callback statistics and emit top cumulative-time callbacks, p95 callbacks with at least three samples, and owner rollups.

Entry point · Source

main() -> int

Returns: 0 after report output, 1 for no callback data, 2 for missing trace path.

Errors: Trace load/process and report-write errors propagate; argparse handles CLI syntax. –top is not range-checked and inherits pandas.head behavior.

Side effects: Reads trace files, prints progress to stderr and writes Markdown to stdout or overwrites –out.

collect_callback_stats()

For callback objects present in the trace instances table, collect duration statistics and resolve symbols/owners with fallbacks for missing registration data.

Function · Source

collect_callback_stats(util: Ros2DataModelUtil) -> pd.DataFrame

Parameter	Meaning
util	Ros2DataModelUtil with callback_instances, callback_symbols, duration and owner lookup support.

Returns: DataFrame with symbol, owner, count, mean_s, p50_s, p95_s, max_s, total_s; all duration columns are seconds. No valid callbacks yields an empty DataFrame without fixed columns.

Errors: Duration lookup Exceptions skip that callback; missing symbol KeyError/AttributeError uses a synthetic name; owner lookup Exceptions use (unknown). Duration conversion/aggregation errors propagate.

Side effects: Reads trace data and allocates a DataFrame; no ROS runtime work.

Referenced in source (1)

• main — src.beambot.scripts.perf_trace_summarize

Internal callbacks and helpers

format_duration()

Convert a timedelta or numeric seconds into microseconds below one millisecond, milliseconds below one second, otherwise seconds.

Internal helper · Source

format_duration(td: pd.Timedelta | np.timedelta64 | float) -> str

Parameter	Meaning
td	pandas.Timedelta, NumPy timedelta64 or float-convertible seconds.

Returns: Formatted string: one decimal for us, two for ms or s. Negative values also follow the us branch.

Errors: Invalid timedelta/numeric conversion errors propagate; no finite-value validation.

Side effects: Pure formatting.

Example

assert format_duration(0.00025) == "250.0 us"
assert format_duration(0.25) == "250.00 ms"
assert format_duration(2) == "2.00 s"

Referenced in source (2)

• main — src.beambot.scripts.perf_trace_summarize
• md_table — src.beambot.scripts.perf_trace_summarize

truncate()

Preserve text within width, otherwise keep width-1 characters and append a Unicode ellipsis.

Internal helper · Source

truncate(text: str, width: int) -> str

Parameter	Meaning
text	String to shorten.
width	Nominal character count; zero/negative widths still return an ellipsis for most nonempty input.

Returns: Original or truncated string; character count rather than display-column width.

Errors: Nonstring inputs/invalid width types can raise.

Example

assert truncate("abcdef", 4) == "abc…"
assert truncate("abc", 3) == "abc"

Referenced in source (1)

• md_table — src.beambot.scripts.perf_trace_summarize

md_table()

Render selected DataFrame columns as a Markdown table, formatting float columns ending in _s as durations and truncating headers/text.

Internal helper · Source

md_table(df: pd.DataFrame, columns: list[tuple[str, str, int]]) -> str

Parameter	Meaning
df	DataFrame whose rows contain all named source columns.
columns	Sequence of (column_name, header_text, character_width) tuples.

Returns: Markdown table string without a trailing newline. Integer cells are not truncated; pipes/newlines in strings are not escaped.

Errors: Missing columns and formatting/type errors propagate.

Side effects: Creates text only.

Referenced in source (1)

• main — src.beambot.scripts.perf_trace_summarize