| # Trace Processor `report` Subcommand |
| |
| **Authors:** @lalitm |
| |
| **Status:** Draft |
| |
| > **Note:** This document is a thought experiment exploring a possible future |
| > direction for trace_processor_shell. It is NOT a proposal for immediate |
| > implementation. The goal is to capture the design space and solicit feedback. |
| |
| ## Motivation |
| |
| Perfetto traces are rich, multi-dimensional datasets. Today, extracting a |
| useful summary requires either: |
| |
| 1. Loading the trace in the UI and clicking around. |
| 2. Writing ad-hoc SQL queries against trace_processor. |
| 3. Authoring `TraceSummarySpec` textprotos for the `summarize` subcommand. |
| |
| None of these serve the "I just collected a trace, what's in it?" use case |
| well. Users coming from `perf report` expect to point a tool at a data file |
| and immediately see an opinionated, useful summary — no query authoring, no |
| spec files, no UI. |
| |
| This gap is especially felt by: |
| |
| - **CLI power users** who want quick triage without leaving the terminal. |
| - **AI tools** that need structured trace summaries to reason about |
| performance. |
| - **CI pipelines** that want a human-readable (or machine-parseable) trace |
| summary as a build artifact. |
| |
| The Firefox Profiler project is exploring a similar direction with their |
| experimental `pq` CLI tool (PR 5663 in the firefox-devtools/profiler repo), |
| which provides opinionated per-dimension views of profiling data from the |
| command line. |
| |
| ## Decision |
| |
| Pending |
| |
| ## Design |
| |
| ### Relationship to `summarize` |
| |
| `report` is a higher-level, opinionated cousin of `summarize`: |
| |
| - **`summarize`** is the general-purpose engine — users author custom |
| `TraceSummarySpec` protos to define exactly what to compute. |
| - **`report`** ships built-in specs that produce useful defaults across |
| known trace dimensions. |
| |
| Under the hood, `report` is built entirely on top of the summarization |
| machinery. Each dimension's report is a pre-authored `TraceSummarySpec` that |
| gets fed into the same engine that `summarize` uses. |
| |
| ### Built-in spec embedding |
| |
| Report specs are authored as human-readable textproto files in the source tree |
| (e.g. `src/trace_processor/shell/report_specs/*.textproto`). A build rule |
| converts these to binary proto and embeds them as byte arrays in the binary, |
| following the existing `perfetto_cc_proto_descriptor` pattern used for metric |
| and trace descriptors. This means: |
| |
| - Zero file I/O at runtime — specs are baked into the binary. |
| - Specs are human-editable in the source tree. |
| - The same build infrastructure that handles descriptor embedding is reused. |
| |
| ### CLI surface |
| |
| ``` |
| trace_processor_shell report [dimension] [FLAGS] <trace_file> |
| ``` |
| |
| When no dimension is specified, produce an overview covering all applicable |
| dimensions (skipping those with no data in the trace). When a dimension is |
| specified, produce a detailed per-dimension report. |
| |
| #### Dimensions |
| |
| | Dimension | Description | |
| | ---------------- | -------------------------------------------------- | |
| | `slices` | Slice aggregations (wall duration, count, max) | |
| | `stack-samples` | CPU profiling samples (self/total time) | |
| | `heap-profile` | Heap allocation profiling (bytes, count) | |
| | `heap-dump` | Heap snapshot analysis (retained size, objects) | |
| | `scheduling` | Thread scheduling (CPU time, runnable, wait time) | |
| |
| #### Output format flags |
| |
| ``` |
| --format text|json Output format (default: text). |
| ``` |
| |
| - **`text`**: Human-readable tables, similar to `perf report --stdio`. |
| - **`json`**: Structured JSON object, for tool/AI consumption. |
| |
| #### Scoping flags |
| |
| These filter the report to a subset of the trace data: |
| |
| ``` |
| --pid <pid> Scope to a specific process ID. |
| --process <name> Scope to a process by name. |
| --tid <tid> Scope to a specific thread ID. |
| --thread <name> Scope to a thread by name. |
| --track <name> Scope to a track by name. |
| --cpu <cpu> Scope to a specific CPU. |
| --time <start>,<end> Scope to a time range. |
| Accepts raw nanoseconds or human-friendly |
| format (e.g. 2.7s,3.1s). |
| ``` |
| |
| Scoping flags are translated into structured query filters and |
| `interval_intersect` clauses in the underlying `TraceSummarySpec`, using the |
| existing DSL primitives — no raw SQL WHERE clauses. |
| |
| #### Aggregation control |
| |
| ``` |
| --top <N> Number of entries per section (default: 10). |
| ``` |
| |
| ### Overview output |
| |
| When invoked without a dimension, the overview produces a one-line trace |
| context followed by per-dimension aggregated highlights. |
| |
| Example (`--format text`): |
| |
| ``` |
| Trace: 12.3s | Android 14 | Pixel 7 Pro | 12 processes | 48 threads | 156 tracks |
| |
| Slices (12.3M total): |
| Name Count Total dur % of trace Max dur |
| Choreographer#doFrame 83.2k 4.1s 33.2% 128ms |
| DrawFrame 83.1k 3.5s 28.4% 96ms |
| measure 41.6k 890ms 7.2% 42ms |
| layout 41.6k 620ms 5.0% 38ms |
| dequeueBuffer 24.9k 310ms 2.5% 12ms |
| eglSwapBuffers 24.9k 280ms 2.3% 8ms |
| RenderThread::draw 24.9k 240ms 1.9% 6ms |
| BinderTransaction 12.1k 180ms 1.5% 52ms |
| animation 8.3k 120ms 1.0% 4ms |
| inflate 2.1k 95ms 0.8% 18ms |
| |
| Stack Samples (3.2k total): |
| Function Self% Total% Samples |
| art::Thread::RunRootClock 18.2% 42.1% 583 |
| __epoll_pwait 12.1% 12.1% 387 |
| art::interpreter::Execute 8.4% 31.2% 269 |
| ... |
| |
| Scheduling: |
| Thread CPU time Runnable Sleeping % of trace |
| RenderThread 3.2s 120ms 8.9s 26.0% |
| mali-cmar-backe 1.8s 45ms 10.4s 14.6% |
| HeapTaskDaemon 890ms 12ms 11.3s 7.2% |
| ... |
| |
| Heap Profile: (not present in trace) |
| Heap Dump: (not present in trace) |
| ``` |
| |
| ### Per-dimension detail |
| |
| Per-dimension reports provide a deeper view. For example, |
| `tp report slices <trace>` would show the same columns as the overview but |
| with a higher default `--top` and potentially additional breakdowns (e.g. |
| per-thread grouping). |
| |
| The exact content of per-dimension reports is left as an open question for |
| now. As noted below, the call-tree views for stack samples (top-down / |
| bottom-up, as seen in `perf report` and the Firefox Profiler's `pq` tool) |
| are a natural fit here but the exact interaction model needs more thought. |
| |
| ### Per-dimension column definitions |
| |
| #### Slices |
| |
| Default aggregation key: slice name. |
| |
| | Column | Description | |
| | ------------ | ---------------------------------------------------- | |
| | Name | Slice name | |
| | Count | Number of instances | |
| | Total dur | Sum of wall durations across all instances | |
| | % of trace | Total duration as percentage of trace duration | |
| | Max dur | Maximum single-instance duration (outlier detection) | |
| |
| #### Stack Samples |
| |
| Modeled after `perf report --stdio`. |
| |
| | Column | Description | |
| | --------- | ------------------------------------------------------- | |
| | Function | Function name (symbol) | |
| | Self% | Samples where this function is at the top of the stack | |
| | Total% | Samples where this function appears anywhere in stack | |
| | Samples | Absolute sample count | |
| |
| #### Heap Profile |
| |
| Same shape as stack samples but with bytes instead of sample count. |
| |
| | Column | Description | |
| | ------------ | ---------------------------------------------------- | |
| | Allocator | Allocation site / function | |
| | Self bytes | Bytes allocated directly by this function | |
| | Total bytes | Bytes allocated by this function and its callees | |
| | Count | Number of allocations | |
| | Avg size | Average allocation size | |
| |
| #### Heap Dump |
| |
| Point-in-time memory snapshot. |
| |
| | Column | Description | |
| | ------------- | --------------------------------------------------- | |
| | Type/Alloc | Type or allocator | |
| | Retained size | Total retained memory | |
| | Live objects | Count of live objects | |
| |
| #### Scheduling |
| |
| Per-thread scheduling summary. |
| |
| | Column | Description | |
| | ------------ | ---------------------------------------------------- | |
| | Thread | Thread name | |
| | CPU time | Total time spent running on a CPU | |
| | Runnable | Total time in runnable state (waiting for CPU) | |
| | Sleeping | Total time sleeping | |
| | % of trace | CPU time as percentage of trace duration | |
| |
| ### Sources of inspiration |
| |
| - **`perf report`** (Linux perf): Opinionated defaults, hierarchical views, |
| sort-by-overhead, `--stdio` output. The gold standard for "point at data, |
| get useful summary." |
| - **Firefox Profiler `pq`**: CLI profile querying with per-dimension |
| formatters, top-down/bottom-up call trees, scoping via time ranges, dual |
| human/JSON output (PR 5663 in the firefox-devtools/profiler repo). |
| - **`pprof`** (Go): `-top`, `-text` views for CPU/heap profiles. Ergonomic |
| top-N function summaries. |
| - **`heaptrack`** (KDE): CLI heap profile summaries — peak consumption, top |
| allocators, leak candidates. |
| |
| ## Alternatives considered |
| |
| ### Ship report specs as external files |
| |
| Pro: |
| |
| * Users can inspect and modify specs without rebuilding. |
| |
| Con: |
| |
| * Requires distributing spec files alongside the binary. |
| * File discovery and path resolution adds complexity. |
| * Embedded binary protos are zero-overhead and follow existing precedent |
| (metric descriptors, trace descriptors). |
| |
| ### Hardcode aggregation queries in C++ |
| |
| Pro: |
| |
| * No proto serialization overhead. |
| |
| Con: |
| |
| * Loses the declarative nature of the summarization DSL. |
| * Cannot be reused by the `summarize` subcommand. |
| * Harder to maintain and review. |
| |
| ### Combine with `summarize` |
| |
| Pro: |
| |
| * One subcommand to learn. |
| |
| Con: |
| |
| * `summarize` is for custom specs; overloading it with opinionated defaults |
| muddies its purpose. |
| * Different flag surfaces (scoping flags vs spec paths) would conflict. |
| |
| ## Open questions |
| |
| * **Per-dimension drill-down interaction model:** For stack samples, top-down |
| and bottom-up call trees (à la `perf report` and Firefox Profiler's `pq` |
| tool) are a natural fit. Should these be sub-sub-commands |
| (`tp report stack-samples top-down <trace>`), flags |
| (`--view top-down`), or sections within the same output? |
| * **Exact per-dimension report content:** The overview columns are defined |
| above. The detailed per-dimension reports may include additional breakdowns |
| (e.g. per-thread slice grouping, per-process scheduling). Exact content |
| TBD. |
| * **Spec authoring:** The built-in specs need to be written against the |
| existing PerfettoSQL stdlib tables and modules. The exact table/module |
| references for each dimension need to be determined. |
| * **Trace metadata extraction:** The one-line context line (OS, device, |
| duration, process/thread/track counts) may require queries outside the |
| summarization DSL. How to handle this cleanly? |
