execute_sql
Execute custom PerfettoSQL queries against a loaded trace to perform aggregations, joins, or analyses not covered by dedicated tools.
Instructions
Run a PerfettoSQL query against the loaded trace and return rows as columnar JSON. Read-only against trace data; SQLite operates in-memory per session. Aggregates are strongly preferred over raw row data; results are capped at 5000 rows.
Use when: composing analyses not covered by the dedicated tools — custom aggregations, joins across stdlib modules, or queries against base tables (slice, thread, process, sched).
Don't use for: questions the dedicated chrome_* tools answer — they return the same data with the JOIN shape already correct. Don't hand-roll slice scans with LIKE '%x%' patterns when a stdlib module covers the data; INCLUDE PERFETTO MODULE chrome.tasks is faster and the joins are pre-baked.
Parameters: sql is a single PerfettoSQL statement (the INCLUDE PERFETTO MODULE foo; and SELECT ... can be in the same call). Optional output shaping (head/limit, columns_only, summary, include_row_count, max_string_len) only changes what this tool returns; it does not rewrite the SQL. Blob cells render as blob:hex:<hex>. String results may be redacted by the server privacy policy before they are returned, preserving diagnostic structure while masking sensitive URL/header/cookie/path values. Requires load_trace to have run first.
Empty rows means the query matched nothing — distinct from a SQL error, which is returned as an error string with a hint pointing at the most likely cause (missing module, missing column, missing table).
Reference docs (fetch when you need exact column names or function signatures): https://perfetto.dev/docs/analysis/stdlib-docs (24 stdlib packages — chrome / android / sched / slices / linux / wattson / v8 / ...; use per-package anchors like #package-chrome), https://perfetto.dev/docs/analysis/perfetto-sql-syntax (syntax).
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| sql | Yes | SQL query to execute (PerfettoSQL syntax). | |
| head | No | Agent-friendly alias for `limit`: return only the first N decoded rows. This trims returned rows only; it does not rewrite the SQL. Mutually exclusive with `limit`. Accepts both numbers and numeric strings. | |
| limit | No | Optional output row cap. This trims returned rows only; it does not rewrite or limit the SQL that trace_processor executes. Mutually exclusive with `head`. Accepts both numbers and numeric strings. | |
| summary | No | Return column names, row-count metadata, and a small sample of rows. Defaults to 10 sample rows unless `head` or `limit` is provided. | |
| trace_id | No | Optional trace id returned by `load_trace`. Omit to use the active trace. | |
| columns_only | No | Return only column names and row-count metadata; omit row values. | |
| max_string_len | No | Optional per-string-cell character cap applied to returned rows only. Accepts both numbers and numeric strings. Must be > 0 when set. | |
| include_row_count | No | Include decoded row-count metadata with a row-returning shaped response. |