PerfettoSQL standard library

This page documents the PerfettoSQL standard library.

Introduction

The PerfettoSQL standard library is a repository of tables, views, functions and macros, contributed by domain experts, which make querying traces easier Its design is heavily inspired by standard libraries in languages like Python, C++ and Java.

Some of the purposes of the standard library include:

1. Acting as a way of sharing and commonly written queries without needing to copy/paste large amounts of SQL.
2. Raising the abstraction level when exposing data in the trace. Many modules in the standard library convert low-level trace concepts e.g. slices, tracks and into concepts developers may be more familar with e.g. for Android developers: app startups, binder transactions etc.

Standard library modules can be included as follows:

Prelude is a special module is automatically imported. It contains key helper tables, views and functions which are universally useful.

More information on importing modules is available in the syntax documentation for the INCLUDE PERFETTO MODULE statement.

Summary

Views/tables

Functions

Table functions

Macros

Module: prelude

Views/Tables

cpu, VIEW

Contains information about the CPUs on the device this trace was taken on.

cpu_available_frequencies, VIEW

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

sched_slice, 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'

thread_state, 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.

raw, 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.)

ftrace_event, 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.

experimental_sched_upid, VIEW

The sched_slice table with the upid column.

cpu_track, VIEW

Tracks which are associated to a single CPU.

cpu_counter_track, VIEW

Tracks containing counter-like events associated to a CPU.

trace_bounds, TABLE

Definition of trace_bounds table. The values are being filled by Trace Processor when parsing the trace. Can't be a Perfetto table because it has to be mutable. It is recommended to depend on the trace_start() and trace_end() functions rather than directly on trace_bounds.

Functions

slice_is_ancestor

Given two slice ids, returns whether the first is an ancestor of the second.

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

trace_start

Fetch start of the trace.

Returns: LONG, Start of the trace in nanoseconds.

trace_end

Fetch end of the trace.

Returns: LONG, End of the trace in nanoseconds.

trace_dur

Fetch duration of the trace.

Returns: LONG, Duration of the trace in nanoseconds.

Macros

cast_int Casts |value| to INT.

Returns: Expr,

cast_double Casts |value| to DOUBLE.

Returns: Expr,

cast_string Casts |value| to STRING.

Returns: Expr,

Module: android

android.anrs

Views/Tables

android_anrs, VIEW

List of all ANRs that occurred in the trace (one row per ANR).

android.app_process_starts

Views/Tables

android_app_process_starts, TABLE

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

android.auto.multiuser

Views/Tables

android_auto_multiuser_timing, TABLE

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

android_auto_multiuser_timing_with_previous_user_resource_usage, VIEW

This table extends android_auto_multiuser_timing table with previous user resource usage.

android.battery

Views/Tables

android_battery_charge, VIEW

Battery charge at timestamp.

android.battery_stats

Views/Tables

android_battery_stats_state, 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.

android_battery_stats_event_slices, 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:

Functions

android_battery_stats_counter_to_string

Converts a battery_stats counter value to human readable string.

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

android.binder

Views/Tables

android_binder_metrics_by_process, VIEW

Count Binder transactions per process.

android_sync_binder_thread_state_by_txn, 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.

android_sync_binder_blocked_functions_by_txn, 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.

android_binder_txns, TABLE

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

Functions

Table Functions

android_binder_outgoing_graph 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.

upid | INT | Upid of process to generate an outgoing graph for.

android_binder_incoming_graph 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.

upid | INT | Upid of process to generate an incoming graph for.

android_binder_graph 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.

min_client_oom_score | INT | Matches txns from client_processes greater than or equal to the OOM score. max_client_oom_score | INT | Matches txns from client_processes less than or equal to the OOM score. min_server_oom_score | INT | Matches txns to server_processes greater than or equal to the OOM score. max_server_oom_score | INT | Matches txns to server_processes less than or equal to the OOM score.

android.cpu.cluster_type

Views/Tables

android_cpu_cluster_mapping, 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.

android.device

Views/Tables

android_device_name, TABLE

Extract name of the device based on metadata from the trace.

android.dvfs

Views/Tables

android_dvfs_counters, VIEW

Dvfs counter with duration.

android_dvfs_counter_stats, TABLE

Aggregates dvfs counter slice for statistic.

android_dvfs_counter_residency, VIEW

Aggregates dvfs counter slice for residency

android.frames.jank_type

Functions

android_is_sf_jank_type

Categorizes whether the jank was caused by Surface Flinger

Returns: BOOL, True when the jank type represents sf jank

android_is_app_jank_type

Categorizes whether the jank was caused by the app

Returns: BOOL, True when the jank type represents app jank

android.frames.per_frame_metrics

Views/Tables

android_frames_overrun, TABLE

The amount by which each frame missed of hit its deadline. Positive if the deadline was not missed. Frames are considered janky if overrun is negative. 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.

android_frames_ui_time, TABLE

How much time did the frame's Choreographer callbacks take.

android_app_vsync_delay_per_frame, 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. NOTE: Sometimes because of data losses app_vsync_delay can be negative. The frames where it happens are filtered out. For Googlers: more details in go/android-performance-metrics-glossary.

android_cpu_time_per_frame, 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.

android_frame_stats, TABLE

Aggregated stats of the frame.

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

android.frames.timeline

Views/Tables

android_frames_choreographer_do_frame, TABLE

All of the Choreographer#doFrame slices with their frame id.

android_frames_draw_frame, 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).

android_frames, 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.

Functions

Table Functions

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

ts | INT | Timestamp.

android.freezer

Views/Tables

android_freezer_events, TABLE

All frozen processes and their frozen duration.

android.garbage_collection

Views/Tables

android_garbage_collection_events, TABLE

All Garbage collection events with a breakdown of the time spent and heap reclaimed.

android.gpu.frequency

Views/Tables

android_gpu_frequency, TABLE

GPU frequency counter per GPU.

android.gpu.memory

Views/Tables

android_gpu_memory_per_process, TABLE

Counter for GPU memory per process with duration.

android.input

Views/Tables

android_input_events, 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.

android_key_events, VIEW

Key events processed by the Android framework (from android.input.inputevent data source).

android_motion_events, VIEW

Motion events processed by the Android framework (from android.input.inputevent data source).

android_input_event_dispatch, VIEW

Input event dispatching information in Android (from android.input.inputevent data source).

android.job_scheduler

Views/Tables

android_job_scheduler_events, TABLE

All scheduled jobs and their latencies.

android.memory.dmabuf

Views/Tables

android_dmabuf_allocs, TABLE

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

android.memory.heap_graph.dominator_tree

Views/Tables

heap_graph_dominator_tree, 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.

android.memory.heap_graph.heap_graph_class_aggregation

Views/Tables

android_heap_graph_class_aggregation, TABLE

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

android.memory.process

Views/Tables

memory_oom_score_with_rss_and_swap_per_process, 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.

android.monitor_contention

Views/Tables

android_monitor_contention, TABLE

Contains parsed monitor contention slices.

android_monitor_contention_chain, TABLE

Contains parsed monitor contention slices with the parent-child relationships.

android_monitor_contention_chain_thread_state, 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.

android_monitor_contention_chain_thread_state_by_txn, 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.

android_monitor_contention_chain_blocked_functions_by_txn, 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.

Functions

android_extract_android_monitor_contention_blocking_thread

Extracts the blocking thread from a slice name

Returns: STRING, Blocking thread

android_extract_android_monitor_contention_blocking_tid

Extracts the blocking thread tid from a slice name

Returns: INT, Blocking thread tid

android_extract_android_monitor_contention_blocking_method

Extracts the blocking method from a slice name

Returns: STRING, Blocking thread

android_extract_android_monitor_contention_short_blocking_method

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

android_extract_android_monitor_contention_blocked_method

Extracts the monitor contention blocked method from a slice name

Returns: STRING, Blocking thread

android_extract_android_monitor_contention_short_blocked_method

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

android_extract_android_monitor_contention_waiter_count

Extracts the number of waiters on the monitor from a slice name

Returns: INT, Count of waiters on the lock

android_extract_android_monitor_contention_blocking_src

Extracts the monitor contention blocking source location from a slice name

Returns: STRING, Blocking thread

android_extract_android_monitor_contention_blocked_src

Extracts the monitor contention blocked source location from a slice name

Returns: STRING, Blocking thread

Table Functions

android_monitor_contention_graph 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.

upid | INT | Upid of process to generate a lock graph for.

android.network_packets

Views/Tables

android_network_packets, VIEW

Android network packet events (from android.network_packets data source).

android.oom_adjuster

Views/Tables

android_oom_adj_intervals, VIEW

All oom adj state intervals across all processes along with the reason for the state update.

Functions

android_oom_adj_score_to_bucket_name

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.

android_oom_adj_score_to_detailed_bucket_name

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.

android.power_rails

Views/Tables

android_power_rails_counters, 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.

android.process_metadata

Views/Tables

android_process_metadata, TABLE

Data about packages running on the process.

android.screenshots

Views/Tables

android_screenshots, TABLE

Screenshot slices, used in perfetto UI.

android.services

Views/Tables

android_service_bindings, TABLE

All service bindings from client app to server app.

android.slices

Functions

android_standardize_slice_name

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.

android.startup.startups

Views/Tables

android_startups, TABLE

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

android_startup_processes, 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.

android_startup_threads, VIEW

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

android_thread_slices_for_all_startups, 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.

Functions

android_sum_dur_for_startup_and_slice

Returns duration of startup for slice name.

Sums duration of all slices of startup with provided name.

Returns: INT, Sum of duration.

android_sum_dur_on_main_thread_for_startup_and_slice

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 Functions

android_slices_for_startup_and_slice_name Given a startup id and GLOB for a slice name, returns matching slices with data.

startup_id | INT | Startup id. slice_name | STRING | Glob of the slice.

android_binder_transaction_slices_for_startup Returns binder transaction slices for a given startup id with duration over threshold.

startup_id | INT | Startup id. threshold | DOUBLE | Only return slices with duration over threshold.

android.startup.time_to_display

Views/Tables

android_startup_time_to_display, 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.

android.statsd

Views/Tables

android_statsd_atoms, VIEW

Statsd atoms.

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

android.suspend

Views/Tables

android_suspend_state, 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.

android.winscope.inputmethod

Views/Tables

android_inputmethod_clients, VIEW

Android inputmethod clients state dumps (from android.inputmethod data source).

android_inputmethod_manager_service, VIEW

Android inputmethod manager service state dumps (from android.inputmethod data source).

android_inputmethod_service, VIEW

Android inputmethod service state dumps (from android.inputmethod data source).

android.winscope.viewcapture

Views/Tables

android_viewcapture, VIEW

Android viewcapture (from android.viewcapture data source).

android.winscope.windowmanager

Views/Tables

android_windowmanager, VIEW

Android WindowManager (from android.windowmanager data source).

Module: callstacks

Module: chrome

chrome.chrome_scrolls

Views/Tables

chrome_scrolls, 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.

chrome.cpu_powerups

Views/Tables

chrome_cpu_power_slice, 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.

chrome_cpu_power_first_sched_slice_after_powerup, TABLE

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

chrome_cpu_power_post_powerup_slice, TABLE

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

chrome_cpu_power_first_toplevel_slice_after_powerup, VIEW

The first top-level slice that ran after a CPU power-up.

chrome.event_latency

Views/Tables

chrome_event_latencies, TABLE

All EventLatency slices.

chrome_gesture_scroll_events, 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.

Functions

chrome_get_most_recent_scroll_begin_id

Extracts scroll id for the EventLatency slice at ts.

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

chrome.event_latency_description

Views/Tables

chrome_event_latency_stage_descriptions, TABLE

Source of truth of the descriptions of EventLatency stages.

chrome.histograms

Views/Tables

chrome_histograms, TABLE

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

chrome.interactions

Views/Tables

chrome_interactions, TABLE

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

chrome.metadata

Functions

chrome_hardware_class

Returns hardware class of the device, often use to find device brand and model.

Returns: STRING, Hardware class name.

chrome.page_loads

Views/Tables

chrome_page_loads, TABLE

Chrome page loads, including associated high-level metrics and properties.

chrome.scroll_interactions

Views/Tables

chrome_scroll_interactions, TABLE

Top level scroll events, with metrics.

chrome.scroll_jank.predictor_error

Views/Tables

chrome_predictor_error, TABLE

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

chrome.scroll_jank.scroll_jank_cause_map

Views/Tables

chrome_scroll_jank_cause_descriptions, TABLE

Source of truth of the descriptions of EventLatency-based scroll jank causes.

chrome_scroll_jank_causes_with_event_latencies, VIEW

Combined description of scroll jank cause and associated event latency stage.

chrome.scroll_jank.scroll_jank_cause_utils

Functions

Table Functions

chrome_select_scroll_jank_cause_thread 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.

event_latency_id | INT | The slice id of an EventLatency slice. process_type | STRING | The process type that the thread is on: one of 'Browser', 'Renderer' or 'GPU'. thread_name | STRING | The name of the thread.

chrome.scroll_jank.scroll_jank_intervals

Views/Tables

chrome_janky_event_latencies_v3, TABLE

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

chrome_janky_frame_presentation_intervals, VIEW

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

chrome_scroll_stats, TABLE

Scroll jank frame presentation stats for individual scrolls.

chrome_scroll_jank_intervals_v3, TABLE

Defines slices for all of janky scrolling intervals in a trace.

chrome.scroll_jank.scroll_jank_v3

Views/Tables

chrome_gesture_scroll_updates, TABLE

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

chrome_presented_gesture_scrolls, TABLE

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

chrome_scroll_updates_with_deltas, TABLE

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

chrome_full_frame_view, TABLE

Obtain the subset of input events that were fully presented.

chrome_full_frame_delta_view, TABLE

Join deltas with EventLatency data.

chrome_merged_frame_view, TABLE

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

chrome_frame_info_with_delay, 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.

chrome_vsyncs, 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.

chrome_janky_frames_no_cause, TABLE

Filter the frame view only to frames that had missed vsyncs.

chrome_janky_frames_no_subcause, TABLE

Janky frame information including the jank cause.

chrome_janky_frames, TABLE

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

chrome_unique_frame_presentation_ts, TABLE

Counting all unique frame presentation timestamps.

chrome_janky_frames_percentage, 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.

chrome_frames_per_scroll, TABLE

Number of frames and janky frames per scroll.

chrome_causes_per_scroll, VIEW

Scroll jank causes per scroll.

chrome.scroll_jank.scroll_jank_v3_cause

Functions

chrome_get_v3_jank_cause_id

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.

chrome.scroll_jank.scroll_offsets

Views/Tables

chrome_scroll_input_offsets, TABLE

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

chrome_presented_scroll_offsets, 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.

chrome.scroll_jank.utils

Functions

Table Functions

chrome_select_long_task_slices 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.

name | STRING | The name of slice.

chrome.speedometer

Views/Tables

chrome_speedometer_measure, 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

chrome_speedometer_iteration, 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.

Functions

chrome_speedometer_score

Returns the Speedometer score for all iterations in the trace

Returns: DOUBLE, Speedometer score

chrome.speedometer_2_1

Views/Tables

chrome_speedometer_2_1_measure, 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.

chrome_speedometer_2_1_iteration, 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.

Functions

chrome_speedometer_2_1_score

Returns the Speedometer 2.1 score for all iterations in the trace

Returns: DOUBLE, Speedometer 2.1 score

chrome.speedometer_3

Views/Tables

chrome_speedometer_3_measure, 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.

chrome_speedometer_3_iteration, 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.

Functions

chrome_speedometer_3_score

Returns the Speedometer 3 score for all iterations in the trace

Returns: DOUBLE, Speedometer 3 score

chrome.startups

Views/Tables

chrome_startups, TABLE

Chrome startups, including launch cause.

chrome.tasks

Views/Tables

chrome_java_views, 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.

chrome_scheduler_tasks, VIEW

A list of tasks executed by Chrome scheduler.

chrome_tasks, 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.

chrome.vsync_intervals

Views/Tables

chrome_vsync_intervals, 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.

Functions

chrome_calculate_avg_vsync_interval

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.

chrome.web_content_interactions

Views/Tables

chrome_web_content_interactions, 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.

Module: counters

counters.intervals

Macros

counter_leading_intervals 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).

Module: export

export.to_firefox_profile

Functions

export_to_firefox_profile

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

Module: graphs

graphs.dominator_tree

Macros

graph_dominator_tree 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|.

graphs.partition

Macros

tree_structural_partition_by_group 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).

graphs.search

Macros

graph_reachable_dfs 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.

graph_reachable_bfs 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.

graph_next_sibling 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.

graph_reachable_weight_bounded_dfs 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.

Module: intervals

intervals.overlap

Macros

intervals_overlap_count 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.

Module: linux

linux.cpu.frequency

Views/Tables

cpu_frequency_counters, TABLE

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

linux.cpu.idle

Views/Tables

cpu_idle_counters, TABLE

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

cpu_idle_stats, TABLE

Aggregates cpu idle statistics per core.

linux.cpu.utilization.process

Views/Tables

cpu_cycles_per_process, TABLE

Aggregated CPU statistics for each process.

Functions

Table Functions

cpu_process_utilization_per_period 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.

interval | INT | Length of the period on which utilization should be averaged. upid | INT | Upid of the process.

cpu_process_utilization_per_second 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.

upid | INT | Upid of the process.

linux.cpu.utilization.system

Views/Tables

cpu_utilization_per_second, 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.