RFC-0019: Trace Processor Parse Cache

[github-actions[bot]]

📄 RFC Doc: 0019-trace-processor-parse-cache.md

---

Trace Processor Parse Cache

Authors: @lalitm

Status: Superseded

For fast repeated queries, this proposal was replaced by
RFC-0031, which keeps a parsed trace
warm for repeated queries, including workflows using multiple Trace Processor
versions. For disk-based export and
reimport, it was replaced by the opaque streaming table export format in
#6839.

Problem

Loading large traces (multi-GB) into Trace Processor is slow. Parsing
protobuf trace data, sorting events, and populating tables can take minutes
for large traces. This cost is paid on every load, even when the trace
hasn't changed.

This is painful in several workflows:

1. Interactive analysis: Reopening the same trace in the UI after a page
   refresh or browser restart.
2. AI agents: Repeated open/query/close cycles on the same trace, where
   each cycle re-parses from scratch.
3. Iterative scripting: Python notebooks or scripts that create a new
   TraceProcessor instance on the same trace during development.

The parsed table representation is deterministic for a given trace + TP
version + flags. Re-parsing is pure waste when the inputs haven't changed.

Decision

Add a parse cache that serializes parsed tables into an opaque binary
format and transparently loads from cache on subsequent opens. The caching
logic lives entirely in the shell layer — the TP core remains IO-free.

Design

Cache format

The parse cache format is an internal implementation detail of Trace
Processor. It is not stable, not versioned for external consumers, and
carries no forwards or backwards compatibility guarantees. The format
may change between any two TP releases without notice.

Currently, the cache is a TAR archive of Arrow IPC files (one per intrinsic
table), reusing the existing ExportToArrow() / Arrow TAR import
infrastructure. This is a convenient implementation choice, not a public
contract.

A separate, stable Arrow export feature (with explicit versioning and
compatibility guarantees) will be provided independently for users who need
a durable, interoperable representation. The parse cache is not that — it
is purely an acceleration mechanism tied to a specific TP build.

Cache key

The cache is identified by:

SHA256(tp_version + sorted_relevant_global_flags + trace_identity)

Where trace_identity is:

Client	Identity
CLI shell	file path + size + mtime (from stat())
Browser/UI	File.name + File.size + File.lastModified
Python	file path + size + mtime (from os.stat())

This is fast to compute (no file content hashing) and sufficient for
practical invalidation. The chance of a false cache hit (different trace
content with identical name + size + mtime) is negligible.

"Relevant global flags" are those that affect parsing behavior:
--full-sort, --no-ftrace-raw, --crop-track-events, etc.

The inclusion of tp_version in the cache key means that upgrading TP
automatically invalidates all existing caches. This is intentional — schema
changes between versions make old caches unsafe to load.

Cache location

~/.cache/perfetto/parse-cache/<hash> by default, overridable via
--parse-cache-dir. The cache directory is created on first write.

CLI: --parse-cache global flag

trace_processor_shell --parse-cache query -c "SELECT ..." trace.pb

Behavior:

1. Compute cache key from the trace file's stat metadata + TP version +
   flags.
2. If a valid cache exists, read it and feed it to Parse() instead of
   the original trace. Skip to step 5.
3. Otherwise, read the original trace and feed it to Parse() as normal.
4. After parsing completes, start writing the parse cache in a background
   thread via ExportToArrow().
5. Execute the user's command (query, repl, serve, etc.).
6. On exit, wait for the background cache write to complete before
   terminating.

The background write means the first load has no added latency for queries.
The wait-on-exit means the cache is guaranteed to exist after the first
invocation completes.

CLI: parse-cache subcommand

For explicit cache management by human users:

# Create a parse cache for a trace
trace_processor_shell parse-cache create trace.pb

# Show cache status for a trace (exists, size, staleness)
trace_processor_shell parse-cache info trace.pb

# Delete cache for a specific trace
trace_processor_shell parse-cache clear trace.pb

# Delete all parse caches
trace_processor_shell parse-cache clear --all

RPC: /parse with trace identity

To support caching for RPC clients (UI, Python), the first /parse call
gains an optional trace_identity field:

message ParseRequest {
  optional bytes data = 1;
  // Optional. Sent only on the first /parse call. If the shell has a
  // valid parse cache for this identity, it loads from cache and ignores
  // subsequent /parse data.
  optional string trace_identity = 2;
}

message ParseResult {
  optional string error = 1;
  // If true, the shell loaded from cache. The client may skip sending
  // further /parse chunks. Old clients that ignore this field and
  // continue sending data are fine — the shell discards the bytes.
  optional bool skip_further_parse = 2;
}

Flow:

1. Client sends first /parse chunk with trace_identity set.
2. Shell checks cache:
   • Cache hit: Load cached data, respond with
     skip_further_parse = true. Discard data from this and all subsequent
     /parse calls.
   • Cache miss: Parse the data normally, respond with
     skip_further_parse = false. Continue accepting /parse chunks.
3. After notify_eof, if cache was missed, write cache in background.
4. Old clients that don't send trace_identity: no caching, existing
   behavior unchanged.
5. New clients that ignore skip_further_parse and keep sending: shell
   discards bytes, everything still works.

This is fully backwards compatible in both directions.

Python API

Caching is configured via TraceProcessorConfig:

from perfetto.trace_processor import TraceProcessor, TraceProcessorConfig

config = TraceProcessorConfig(parse_cache=True)
tp = TraceProcessor(trace="large.pb", config=config)

Implementation: parse_cache=True causes the Python wrapper to pass
--parse-cache to the shell subprocess. The Python client also sends
trace_identity (from os.stat()) on the first /parse call so the
shell can check its cache. If the response has skip_further_parse = true,
Python skips sending remaining chunks.

No explicit cache management API in Python. Users who want manual control
can use the CLI parse-cache subcommand.

What is NOT cached

• Derived state: Views, PerfettoSQL module outputs, and custom SQL are
  recomputed on top of the cached tables. This is expected and fast.
• Session-specific tables: __intrinsic_trace_file,
  __intrinsic_trace_import_logs, and similar metadata tables are excluded
  from the cache.
• Empty tables: Tables with zero rows are not written to the cache.
• Stdin/pipe traces: When there is no file identity (data piped from
  stdin or generated programmatically), caching is silently skipped.

Disk space

The cache size is roughly comparable to the parsed table data, which can be
a significant fraction of the original trace size. Mitigations:

• Caching is always opt-in (--parse-cache flag or parse-cache create).
  Users make a conscious choice to spend disk space.
• parse-cache info shows cache sizes.
• parse-cache clear --all provides easy cleanup.
• After writing, the shell prints the cache size as a courtesy:
  Parse cache written: 8.2 GB at ~/.cache/perfetto/parse-cache/a1b2c3

Concurrency

• Cache files are written atomically: write to a temporary file, then
  rename. This prevents partial reads from concurrent TP instances.
• Multiple TP instances loading the same trace simultaneously may each
  write a cache. The last rename wins, which is fine since the content is
  identical.

Architecture summary

+------------------+     +-------------------+     +---------------+
| Clients          |     | Shell layer       |     | TP core       |
|                  |     | (IO lives here)   |     | (IO-free)     |
|  CLI user        |---->|                   |     |               |
|  Browser/UI      |---->| Cache check/write |---->| Parse()       |
|  Python API      |---->| File I/O          |     | ExportToArrow |
|                  |     | Background thread |     |               |
+------------------+     +-------------------+     +---------------+

TP core provides the primitives (ExportToArrow, import via Parse). The
shell layer orchestrates caching. RPC clients provide trace identity
metadata. No caching logic in TP core or the RPC layer itself.

Alternatives considered

1. Cache in TP core

Add cache awareness to TraceProcessor directly (e.g., in
NotifyEndOfFile() or Config).

Pro:

• Single implementation covers all callers.

Con:

• Violates TP's IO-free design. Implicit file writes in a library are
  surprising and hard to control.
• TP doesn't know about file paths, mtime, or disk layout.

2. SQLite as cache format

Use the existing ExportTraceToDatabase() as the cache format instead.

Pro:

• Already implemented.
• Self-describing, queryable directly.

Con:

• Slower to load (SQL overhead, row-oriented).
• Larger on disk for numeric-heavy data.
• Not designed for fast bulk table restoration.

3. Automatic caching by default

Enable caching automatically without user opt-in.

Pro:

• Zero-friction fast reloads.

Con:

• Disk bloat can be tremendous and surprising. A 10 GB trace produces a
  comparably sized cache silently.
• Dangerous on servers, shared filesystems, CI environments.
• Users should make a conscious choice to spend disk space.

4. Content hashing for cache key

Use SHA256 of the full trace content as the cache key instead of
path + size + mtime.

Pro:

• Correct even if a file is modified without changing mtime.

Con:

• Hashing a multi-GB file is slow and defeats the purpose of caching.
• For RPC clients (browser), reading the full file just to compute a
  hash is wasteful.
• The mtime + size heuristic is sufficient in practice.

Open questions

• Should there be a maximum cache directory size with automatic eviction
  (LRU)? Or is manual parse-cache clear sufficient?
• Should parse-cache create support creating caches for multiple traces
  at once (e.g., parse-cache create *.pb)?
• For the UI: should the cache directory be configurable via the httpd
  endpoint, or is ~/.cache/perfetto/parse-cache/ always correct?

---

💬 Discussion Guidelines:

• This discussion is automatically synced with the RFC document
• Please provide constructive feedback and suggestions

[LalitMaganti]

This doc was subsequently replaced by #6234 for fast querying of traces across multiple trace-procesor versions.

Then for disk based exporting, it was replaced by #6839 where we now have an opaque (in practice, Apache Arrow) format for exporting data from trace processor and then reimporting it back.

[github-actions[bot]]

📝 RFC Document Updated

View changes: Commit History