s6.utils.profiler

Profiling utilities for Sense Core.

Collects lightweight timing information and exports it in two formats:

  • Chrome/Perfetto Trace Events (via s6.schema.trace.TraceEvent) for interactive timeline inspection.

  • A human‑readable “frames” export that groups nested traces per execution frame and is convenient for offline statistics.

The primary surface is Profiler, which offers context managers for scoped timings (trace), a frame context (frame), a function decorator, and exporters. See process_frames() for computing summary stats from the frames export.

s6.utils.profiler.process_frames(filename)

Parse a frames metrics file and compute sub-trace durations.

Accepts either the combined JSON produced by Profiler.export_metrics() (with a top-level frames list) or a legacy JSONL file with one frame per line. Durations are computed by matching begin/end events of the same name and depth within each frame.

Parameters:

filename (str) – Path to the metrics file (combined JSON or legacy JSONL).

Returns:

Mapping from event full path to a list of durations in milliseconds.

Return type:

dict[str, list[float]]

s6.utils.profiler.get_percentile(sorted_values, p)

Compute a percentile with linear interpolation.

Parameters:

  • sorted_values (list[float]) – Sequence sorted in non-decreasing order.

  • p (float) – Percentile in [0, 100].

Returns:

The interpolated percentile value, or None if the input is empty.

Return type:

float | None

s6.utils.profiler.compute_statistics(durations)

Aggregate descriptive statistics for each event.

For every event key, computes min/max/mean/median, standard deviation, variance, common percentiles, interquartile range, count/total, and the mean of the fastest/slowest 5% samples.

Parameters:

durations (dict[str, list[float]]) – Mapping from event name to a list of durations in milliseconds.

Returns:

A mapping from event name to a statistics dict containing keys such as min_ms, max_ms, average_ms, median_ms, p5_ms, p25_ms, p75_ms, p95_ms, iqr_ms, best_5pct_avg_ms, worst_5pct_avg_ms, count, and total_ms.

Return type:

dict[str, dict[str, float | int | None]]

s6.utils.profiler.main()

Example entry-point that prints per-scope timing stats.

Reads frames.log.jsonl from the current working directory, computes statistics via process_frames() and compute_statistics(), and prints a human-readable report. Intended for ad‑hoc inspection.

class s6.utils.profiler.Profiler

Bases: object

Simple profiler with nested scopes and frame grouping.

  • trace(name, remark=None) creates a timed scope; users can attach metadata while inside the scope.

  • frame() groups all nested traces to represent a single execution cycle (e.g., a render or processing frame).

  • trace_function decorates a callable to measure its runtime.

  • export writes Chrome Trace Events.

  • export_metrics writes a combined JSON with session metadata, optional per-scope remarks, and a frames list suitable for offline analysis.

The profiler keeps a global event list and a per‑frame buffer when a frame context is active. Timestamps are relative to process start and exported in microseconds for Chrome traces and milliseconds in the human‑readable view.

classmethod enable_logging()

Enable verbose debug logging for scope durations.

classmethod disable_logging()

Disable verbose debug logging for scope durations.

classmethod trace(name: str = '', remark: str = None)

Create a timed scope.

Parameters:

  • name (str, default "") – Identifier for the trace scope.

  • remark (str | None, optional) – Optional descriptive label associated with this specific scope instance. Stored in the metrics export under a full scope path.

Returns:

A context manager that records begin/end events and lets callers attach metadata via Profiler._Timer.attach().

Return type:

Profiler._Timer

classmethod trace_function(func)

Decorator that measures the runtime of func.

The function body executes inside Profiler.trace() with the scope name set to func.__name__.

Parameters:

func (Callable) – Function to wrap.

Returns:

A wrapped function with identical signature.

Return type:

Callable

classmethod export(filename='trace.json')

Write Chrome Trace Events to filename.

Parameters:

filename (str, default "trace.json") – Output path for the Chrome/Perfetto trace JSON.

classmethod metadata(**kwargs)

Attach key–value metadata to the current session.

The data is included under the metadata key in Profiler.export_metrics() and intended for run configuration, environment info, or other contextual details.

classmethod export_metrics(filename: str)

Export session‑level data and per‑frame traces as JSON.

The output contains: - metadata: Session metadata dict attached via metadata(). - remarks: Optional mapping from full scope path to remark string. - frames: A list where each frame has keys frame_id,

start_time_ms, end_time_ms, duration_ms, and traces.

Parameters:

filename (str) – Path to the output file.

classmethod frame()

Group nested traces into a single execution frame.

All trace events generated while inside the context are captured and exported in the human‑readable frames list by Profiler.export_metrics().

Returns:

A context manager representing the active frame.

Return type:

Profiler._Frame