PerfettoSQL standard library

VIEW Tracks are a fundamental concept in trace processor and represent a "timeline" for events of the same type and with the same context. See https://perfetto.dev/docs/analysis/trace-processor#tracks for a more detailed explanation, with examples.

VIEW

VIEW Contains the frequency values that the CPUs on the device are capable of running at.

VIEW This table holds slices with kernel thread scheduling information. These slices are collected when the Linux "ftrace" data source is used with the "sched/switch" and "sched/wakeup*" events enabled.

The rows in this table will always have a matching row in the |thread_state| table with |thread_state.state| = 'Running'

VIEW

VIEW This table contains the scheduling state of every thread on the system during the trace.

The rows in this table which have |state| = 'Running', will have a corresponding row in the |sched_slice| table.

VIEW Contains 'raw' events from the trace for some types of events. This table only exists for debugging purposes and should not be relied on in production usecases (i.e. metrics, standard library etc.)

VIEW Contains all the ftrace events in the trace. This table exists only for debugging purposes and should not be relied on in production usecases (i.e. metrics, standard library etc). Note also that this table might be empty if raw ftrace parsing has been disabled.

VIEW

VIEW

VIEW

VIEW

VIEW Contains slices from userspace which explains what threads were doing during the trace.

VIEW Contains instant events from userspace which indicates what happened at a single moment in time.

VIEW

VIEW

VIEW

VIEW Arbitrary key-value pairs which allow adding metadata to other, strongly typed tables. Note: for a given row, only one of |int_value|, |string_value|, |real_value| will be non-null.

VIEW

TABLE

Returns BOOL: Whether ancestor_id slice is an ancestor of descendant_id.

Returns LONG: Start of the trace in nanoseconds.

Returns LONG: End of the trace in nanoseconds.

Returns LONG: Duration of the trace in nanoseconds.

Returns: Expr,

Returns: Expr,

Returns: Expr,

VIEW

TABLE All app cold starts with information about their cold start reason: broadcast, service, activity or provider.

TABLE Time elapsed between the latest user start and the specific end event like package startup(ex carlauncher) or previous user stop.

VIEW

VIEW

VIEW View of human readable battery stats counter-based states. These are recorded by BatteryStats as a bitmap where each 'category' has a unique value at any given time.

VIEW View of slices derived from battery_stats events. Battery stats records all events as instants, however some may indicate whether something started or stopped with a '+' or '-' prefix. Events such as jobs, top apps, foreground apps or long wakes include these details and allow drawing slices between instant events found in a trace.

For example, we may see an event like the following on 'battery_stats.top':

This view will find the associated start ('+top') with the matching suffix (everything after the '=') to construct a slice. It computes the timestamp and duration from the events and extract the details as follows:

Returns STRING: The human-readable name for the counter value.

VIEW

VIEW Aggregated thread_states on the client and server side per binder txn This builds on the data from |_sync_binder_metrics_by_txn| and for each end (client and server) of the transaction, it returns the aggregated sum of all the thread state durations. The |thread_state_type| column represents whether a given 'aggregated thread_state' row is on the client or server side. 'binder_txn' is client side and 'binder_reply' is server side.

VIEW Aggregated blocked_functions on the client and server side per binder txn This builds on the data from |_sync_binder_metrics_by_txn| and for each end (client and server) of the transaction, it returns the aggregated sum of all the kernel blocked function durations. The |thread_state_type| column represents whether a given 'aggregated blocked_function' row is on the client or server side. 'binder_txn' is client side and 'binder_reply' is server side.

TABLE Breakdown binder transactions per txn. It returns data about the client and server ends of every binder transaction async.

Returns a DAG of all outgoing binder txns from a process. The roots of the graph are the threads making the txns and the graph flows from: thread -> server_process -> AIDL interface -> AIDL method. The weights of each node represent the wall execution time in the server_process.

Returns a DAG of all incoming binder txns from a process. The roots of the graph are the clients making the txns and the graph flows from: client_process -> AIDL interface -> AIDL method. The weights of each node represent the wall execution time in the server_process.

Returns a graph of all binder txns in a trace. The nodes are client_process and server_process. The weights of each node represent the wall execution time in the server_process.

TABLE

TABLE

TABLE Stores the mapping of a cpu to its cluster type - e.g. little, medium, big. This cluster type is determined by initially using cpu_capacity from sysfs and grouping clusters with identical capacities, ordered by size. In the case that capacities are not present, max frequency is used instead. If nothing is avaiable, NULL is returned.

TABLE

TABLE

VIEW

TABLE

VIEW

Returns BOOL: True when the jank type represents sf jank

Returns BOOL: True when the jank type represents app jank

TABLE The amount by which each frame missed of hit its deadline. Negative if the deadline was not missed. Frames are considered janky if overrun is positive. Calculated as the difference between the end of the expected_frame_timeline_slice and actual_frame_timeline_slice for the frame. Availability: from S (API 31). For Googlers: more details in go/android-performance-metrics-glossary.

TABLE

TABLE App Vsync delay for a frame. The time between the VSYNC-app signal and the start of Choreographer work. Calculated as time difference between the actual frame start (from actual_frame_timeline_slice) and start of the Choreographer#doFrame slice. For Googlers: more details in go/android-performance-metrics-glossary.

TABLE How much time did the frame take across the UI Thread + RenderThread. Calculated as sum of app VSYNC delay Choreographer#doFrame slice duration and summed durations of all DrawFrame slices associated with this frame. Availability: from N (API 24). For Googlers: more details in go/android-performance-metrics-glossary.

TABLE Aggregated stats of the frame.

For Googlers: more details in go/android-performance-metrics-glossary.

TABLE

TABLE All of the DrawFrame slices with their frame id and render thread. There might be multiple DrawFrames slices for a single vsync (frame id). This happens when we are drawing multiple layers (e.g. status bar and notifications).

TABLE All slices related to one frame. Aggregates Choreographer#doFrame, DrawFrame, actual_frame_timeline_slice and expected_frame_timeline_slice slices. See https://perfetto.dev/docs/data-sources/frametimeline for details.

Returns first frame after the provided timestamp. The returning table has at most one row.

TABLE

TABLE

TABLE

TABLE

TABLE Tracks for GPU work period events originating from the power/gpu_work_period Linux ftrace tracepoint.

This tracepoint is usually only available on selected Android devices.

TABLE All input events with round trip latency breakdown. Input delivery is socket based and every input event sent from the OS needs to be ACK'ed by the app. This gives us 4 subevents to measure latencies between:

1. Input dispatch event sent from OS.
2. Input dispatch event received in app.
3. Input ACK event sent from app.
4. Input ACk event received in OS.

VIEW

VIEW

VIEW

TABLE

TABLE Track dmabuf allocations, re-attributing gralloc allocations to their source (if binder transactions to gralloc are recorded).

TABLE Table containing all the Android heap graphs in the trace converted to a shortest-path tree and then aggregated by class name.

This table contains a "flamegraph-like" representation of the contents of the heap graph.

TABLE All reachable heap graph objects, their immediate dominators and summary of their dominated sets. The heap graph dominator tree is calculated by stdlib graphs.dominator_tree. Each reachable object is a node in the dominator tree, their immediate dominator is their parent node in the tree, and their dominated set is all their descendants in the tree. All size information come from the heap_graph_object prelude table.

TABLE Class-level breakdown of the java heap. Per type name aggregates the object stats and the dominator tree stats.

TABLE Process memory and it's OOM adjuster scores. Detects transitions, each new interval means that either the memory or OOM adjuster score of the process changed.

TABLE

TABLE

TABLE Note that we only span join the duration where the lock was actually held and contended. This can be less than the duration the lock was 'waited on' when a different waiter acquired the lock earlier than the first waiter.

VIEW Aggregated thread_states on the 'blocking thread', the thread holding the lock. This builds on the data from |android_monitor_contention_chain| and for each contention slice, it returns the aggregated sum of all the thread states on the blocking thread.

Note that this data is only available for the first waiter on a lock.

VIEW Aggregated blocked_functions on the 'blocking thread', the thread holding the lock. This builds on the data from |android_monitor_contention_chain| and for each contention, it returns the aggregated sum of all the kernel blocked function durations on the blocking thread.

Note that this data is only available for the first waiter on a lock.

Returns STRING: Blocking thread

Returns INT: Blocking thread tid

Returns STRING: Blocking thread

Extracts a shortened form of the blocking method name from a slice name. The shortened form discards the parameter and return types. Returns STRING: Blocking thread

Returns STRING: Blocking thread

Extracts a shortened form of the monitor contention blocked method name from a slice name. The shortened form discards the parameter and return types. Returns STRING: Blocking thread

Returns INT: Count of waiters on the lock

Returns STRING: Blocking thread

Returns STRING: Blocking thread

Returns a DAG of all Java lock contentions in a process. Each node in the graph is a <thread:Java method> pair. Each edge connects from a node waiting on a lock to a node holding a lock. The weights of each node represent the cumulative wall time the node blocked other nodes connected to it.

VIEW

VIEW

Converts an oom_adj score Integer to String sample name. One of: cached, background, job, foreground_service, bfgs, foreground and system. Returns STRING: Returns the sample bucket based on the oom score.

Converts an oom_adj score Integer to String bucket name. Deprecated: use android_oom_adj_score_to_bucket_name instead. Returns STRING: Returns the oom_adj bucket.

TABLE Android power rails counters data. For details see: https://perfetto.dev/docs/data-sources/battery-counters#odpm NOTE: Requires dedicated hardware - table is only populated on Pixels.

TABLE

TABLE

TABLE

Some slice names have params in them. This functions removes them to make it possible to aggregate by name. Some examples are:

• Lock/monitor contention slices. The name includes where the lock contention is in the code. That part is removed.
• DrawFrames/ooFrame. The name also includes the frame number.
• Apk/oat/dex loading: The name of the apk is removed Returns STRING: Simplified name.

TABLE Blended thread state and slice breakdown blocking app startups.

Each row blames a unique period during an app startup with a reason derived from the slices and thread states on the main thread.

Some helpful events to enables are binder transactions, ART, am and view.

TABLE All activity startups in the trace by startup id. Populated by different scripts depending on the platform version/contents.

TABLE Maps a startup to the set of processes that handled the activity start.

The vast majority of cases should be a single process. However it is possible that the process dies during the activity startup and is respawned.

VIEW Maps a startup to the set of threads on processes that handled the activity start.

VIEW All the slices for all startups in trace.

Generally, this view should not be used. Instead, use one of the view functions related to the startup slices which are created from this table.

Returns duration of startup for slice name.

Sums duration of all slices of startup with provided name. Returns INT: Sum of duration.

Returns duration of startup for slice name on main thread.

Sums duration of all slices of startup with provided name only on main thread. Returns INT: Sum of duration.

TABLE Startup metric defintions, which focus on the observable time range: TTID - Time To Initial Display

• https://developer.android.com/topic/performance/vitals/launch-time#time-initial
• end of first RenderThread.DrawFrame - bindApplication TTFD - Time To Full Display
• https://developer.android.com/topic/performance/vitals/launch-time#retrieve-TTFD
• end of next RT.DrawFrame, after reportFullyDrawn called - bindApplication Googlers: see go/android-performance-metrics-glossary for details.

VIEW Statsd atoms.

A subset of the slice table containing statsd atom instant events.

TABLE Table of suspended and awake slices.

Selects either the minimal or full ftrace source depending on what's available, marks suspended periods, and complements them to give awake periods.

VIEW

VIEW

VIEW

VIEW

VIEW

TABLE Defines slices for all of the individual scrolls in a trace based on the LatencyInfo-based scroll definition.

NOTE: this view of top level scrolls is based on the LatencyInfo definition of a scroll, which differs subtly from the definition based on EventLatencies. TODO(b/278684408): add support for tracking scrolls across multiple Chrome/ WebView instances. Currently gesture_scroll_id unique within an instance, but is not unique across multiple instances. Switching to an EventLatency based definition of scrolls should resolve this.

VIEW The CPU power transitions in the trace. Power states are encoded as non-negative integers, with zero representing full-power operation and positive values representing increasingly deep sleep states.

On ARM systems, power state 1 represents the WFI (Wait For Interrupt) sleep state that the CPU enters while idle.

TABLE The Linux scheduler slices that executed immediately after a CPU power up.

TABLE A table holding the slices that executed within the scheduler slice that ran on a CPU immediately after power-up.

VIEW

TABLE

TABLE All scroll-related events (frames) including gesture scroll updates, begins and ends with respective scroll ids and start/end timestamps, regardless of being presented. This includes pinches that were presented. See b/315761896 for context on pinches.

Returns INT: The event_latency_id of the EventLatency slice with the type GESTURE_SCROLL_BEGIN that is the closest to ts.

TABLE

TABLE A helper view on top of the histogram events emitted by Chrome. Requires "disabled-by-default-histogram_samples" Chrome category.

TABLE All critical user interaction events, including type and table with associated metrics.

Returns hardware class of the device, often use to find device brand and model. Returns STRING: Hardware class name.

TABLE

TABLE

TABLE The scrolling offsets and predictor jank values for the actual (applied) scroll events.

TABLE

VIEW

Function to retrieve the thread id of the thread on a particular process if there are any slices during a particular EventLatency slice duration; this upid/thread combination refers to a cause of Scroll Jank.

TABLE Selects EventLatency slices that correspond with janks in a scroll. This is based on the V3 version of scroll jank metrics.

VIEW Frame presentation interval is the delta between when the frame was supposed to be presented and when it was actually presented.

TABLE

TABLE

TABLE Grabs all gesture updates with respective scroll ids and start/end timestamps, regardless of being presented.

TABLE Scroll updates, corresponding to all input events that were converted to a presented scroll update.

TABLE Associate every trace_id with it's perceived delta_y on the screen after prediction.

TABLE

TABLE

TABLE Group all gestures presented at the same timestamp together in a single row.

TABLE View contains all chrome presented frames during gesture updates while calculating delay since last presented which usually should equal to |VSYNC_INTERVAL| if no jank is present.

TABLE Calculate |VSYNC_INTERVAL| as the lowest vsync seen in the trace or the minimum delay between frames larger than zero.

TODO(~M130): Remove the lowest vsync since we should always have vsync_interval_ms.

TABLE

TABLE

TABLE Finds all causes of jank for all janky frames, and a cause of sub jank if the cause of jank was GPU related.

TABLE

TABLE Dividing missed frames over total frames to get janky frame percentage. This represents the v3 scroll jank metrics. Reflects Event.Jank.DelayedFramesPercentage UMA metric.

TABLE

VIEW

Given two slice Ids A and B, find the maximum difference between the durations of it's direct children with matching names for example if slice A has children named (X, Y, Z) with durations of (10, 10, 5) and slice B has children named (X, Y) with durations of (9, 9), the function will return the slice id of the slice named Z that is A's child, as no matching slice named Z was found under B, making 5 - 0 = 5 the maximum delta between both slice's direct children Returns LONG: The slice id of the breakdown that has the maximum duration delta.

TABLE The raw coordinates and pixel offsets for all input events which were part of a scroll.

TABLE The scrolling offsets for the actual (applied) scroll events. These are not necessarily inclusive of all user scroll events, rather those scroll events that are actually processed.

Extract mojo information for the long-task-tracking scenario for specific names. For example, LongTaskTracker slices may have associated IPC metadata, or InterestingTask slices for input may have associated IPC to determine whether the task is fling/etc.

TABLE Augmented slices for Speedometer measurements. These are the intervals of time Speedometer uses to compute the final score. There are two intervals that are measured for every test: sync and async

TABLE Slice that covers one Speedometer iteration. Depending on the Speedometer version these slices might need to be estimated as older versions of Speedometer to not emit marks for this interval. The metrics associated are the same ones Speedometer would output, but note we use ns precision (Speedometer uses ~100us) so the actual values might differ a bit.

Returns DOUBLE: Speedometer score

Returns INT: Renderer main utid

TABLE Augmented slices for Speedometer measurements. These are the intervals of time Speedometer uses to compute the final score. There are two intervals that are measured for every test: sync and async sync is the time between the start and sync-end marks, async is the time between the sync-end and async-end marks.

TABLE Slice that covers one Speedometer iteration. This slice is actually estimated as a default Speedometer run will not emit marks to cover this interval. The metrics associated are the same ones Speedometer would output, but note we use ns precision (Speedometer uses ~100us) so the actual values might differ a bit. Also note Speedometer returns the values in ms these here and in ns.

Returns DOUBLE: Speedometer 2.1 score

Returns INT: Renderer main utid

TABLE Augmented slices for Speedometer measurements. These are the intervals of time Speedometer uses to compute the final score. There are two intervals that are measured for every test: sync and async.

TABLE Slice that covers one Speedometer iteration. The metrics associated are the same ones Speedometer would output, but note we use ns precision (Speedometer uses ~100us) so the actual values might differ a bit.

Returns DOUBLE: Speedometer 3 score

Returns INT: Renderer main utid

TABLE

VIEW A list of slices corresponding to operations on interesting (non-generic) Chrome Java views. The view is considered interested if it's not a system (ContentFrameLayout) or generic library (CompositorViewHolder) views.

TODO(altimin): Add "columns_from slice" annotation. TODO(altimin): convert this to EXTEND_TABLE when it becomes available.

VIEW

VIEW A list of "Chrome tasks": top-level execution units (e.g. scheduler tasks / IPCs / system callbacks) run by Chrome. For a given thread, the slices corresponding to these tasks will not intersect.

TABLE A simple table that checks the time between VSync (this can be used to determine if we're refreshing at 90 FPS or 60 FPS).

Note: In traces without the "Java" category there will be no VSync TraceEvents and this table will be empty.

Function: compute the average Vysnc interval of the gesture (hopefully this would be either 60 FPS for the whole gesture or 90 FPS but that isnt always the case) on the given time segment. If the trace doesnt contain the VSync TraceEvent we just fall back on assuming its 60 FPS (this is the 1.6e+7 in the COALESCE which corresponds to 16 ms or 60 FPS). Returns FLOAT: The average vsync interval on this time segment or 1.6e+7, if trace doesn't contain the VSync TraceEvent.

TABLE Chrome web content interactions (InteractionToFirstPaint), including associated high-level metrics and properties.

Multiple events may occur for the same interaction; each row in this table represents the primary (longest) event for the interaction.

Web content interactions are discrete, as opposed to sustained (e.g. scrolling); and only occur with the web content itself, as opposed to other parts of Chrome (e.g. omnibox). Interaction events include taps, clicks, keyboard input (typing), and drags.

For a given counter timeline (e.g. a single counter track), returns intervals of time where the counter has the same value.

Intervals are computed in a "forward-looking" way. That is, if a counter changes value at some timestamp, it's assumed it just reached that value and it should continue to have that value until the next value change. The final value is assumed to hold until the very end of the trace.

For example, suppose we have the following data:

Then this macro will generate the following intervals:

Returns: TableOrSubquery, Table with the schema (id UINT32, ts UINT64, dur UINT64, track_id UINT64, value DOUBLE, next_value DOUBLE, delta_value DOUBLE).

Dumps all trace data as a Firefox profile json string See Profile in https://github.com/firefox-devtools/profiler/blob/main/src/types/profile.js Also https://firefox-source-docs.mozilla.org/tools/profiler/code-overview.html

You would probably want to download the generated json and then open at https://https://profiler.firefox.com You can easily do this from the UI via the following SQL SELECT CAST(export_to_firefox_profile() AS BLOB) AS profile; The result will have a link for you to download this json as a file. Returns STRING: Json profile

Given a table containing a directed flow-graph and an entry node, computes the "dominator tree" for the graph. See [1] for an explanation of what a dominator tree is.

[1] https://en.wikipedia.org/wiki/Dominator_(graph_theory)

Example usage on traces containing heap graphs:

Returns: TableOrSubquery, The returned table has the schema (node_id UINT32, dominator_node_id UINT32). |node_id| is the id of the node from the input graph and |dominator_node_id| is the id of the node in the input flow-graph which is the "dominator" of |node_id|.

Partitions a tree into a forest of trees based on a given grouping key in a structure-preserving way.

Specifically, for each tree in the output forest, all the nodes in that tree have the same ancestors and descendants as in the original tree iff that ancestor/descendent belonged to the same group.

Example: Input

Or as a graph:

Possible output (order of rows is implementation-defined)

Or as a forest:

Returns: TableOrSubquery, The returned table has the schema (id UINT32, parent_id UINT32, group_key UINT32).

Computes the "reachable" set of nodes in a directed graph from a given set of starting nodes by performing a depth-first search on the graph. The returned nodes are structured as a tree with parent-child relationships corresponding to the order in which nodes were encountered by the DFS.

While this macro can be used directly by end users (hence being public), it is primarily intended as a lower-level building block upon which higher level functions/macros in the standard library can be built.

Example usage on traces containing heap graphs:

Returns: TableOrSubquery, The returned table has the schema (node_id UINT32, parent_node_id UINT32). |node_id| is the id of the node from the input graph and |parent_node_id| is the id of the node which was the first encountered predecessor in a DFS search of the graph.

Computes the "reachable" set of nodes in a directed graph from a given starting node by performing a breadth-first search on the graph. The returned nodes are structured as a tree with parent-child relationships corresponding to the order in which nodes were encountered by the BFS.

While this macro can be used directly by end users (hence being public), it is primarily intended as a lower-level building block upon which higher level functions/macros in the standard library can be built.

Example usage on traces containing heap graphs:

Returns: TableOrSubquery, The returned table has the schema (node_id UINT32, parent_node_id UINT32). |node_id| is the id of the node from the input graph and |parent_node_id| is the id of the node which was the first encountered predecessor in a BFS search of the graph.

Computes the next sibling node in a directed graph. The next node under a parent node is determined by on the |sort_key|, which should be unique for every node under a parent. The order of the next sibling is undefined if the |sort_key| is not unique.

Example usage:

Returns: TableOrSubquery, The returned table has the schema (node_id UINT32, next_node_id UINT32). |node_id| is the id of the node from the input graph and |next_node_id| is the id of the node which is its next sibling.

Computes the "reachable" set of nodes in a directed graph from a set of starting (root) nodes by performing a depth-first search from each root node on the graph. The search is bounded by the sum of edge weights on the path and the root node specifies the max weight (inclusive) allowed before stopping the search. The returned nodes are structured as a tree with parent-child relationships corresponding to the order in which nodes were encountered by the DFS. Each row also has the root node from which where the edge was encountered.

While this macro can be used directly by end users (hence being public), it is primarily intended as a lower-level building block upon which higher level functions/macros in the standard library can be built.

Example usage on traces with sched info:

Returns: TableOrSubquery, The returned table has the schema (root_node_id, node_id UINT32, parent_node_id UINT32). |root_node_id| is the id of the starting node under which this edge was encountered. |node_id| is the id of the node from the input graph and |parent_node_id| is the id of the node which was the first encountered predecessor in a DFS search of the graph.

Compute the distribution of the overlap of the given intervals over time.

Each interval is a (ts, dur) pair and the overlap represented as a (ts, value) counter, with the value corresponding to the number of intervals that overlap the given timestamp and interval until the next timestamp. Returns: TableOrSubquery, The returned table has the schema (ts INT64, value UINT32). |ts| is the timestamp when the number of open segments changed. |value| is the number of open segments.

TABLE Counter information for each frequency change for each CPU. Finds each time region where a CPU frequency is constant.

TABLE Counter information for each idle state change for each CPU. Finds each time region where a CPU idle state is constant.

TABLE

TABLE Counter information for sysfs cpuidle states. Tracks the percentage of time spent in each state between two timestamps, by dividing the incremental time spent in one state, by time all CPUS spent in any state.

TABLE

Returns a table of process utilization per given period. Utilization is calculated as sum of average utilization of each CPU in each period, which is defined as a multiply of |interval|. For this reason first and last period might have lower then real utilization.

Returns a table of process utilization per second. Utilization is calculated as sum of average utilization of each CPU in each period, which is defined as a multiply of |interval|. For this reason first and last period might have lower then real utilization.

TABLE

TABLE Table with system utilization per second. Utilization is calculated by sum of average utilization of each CPU every second. For this reason first and last second might have lower then real utilization.

TABLE Aggregated CPU statistics for whole trace. Results in only one row.

TABLE