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:

-- Include all tables/views/functions from the android.startup.startups -- module in the standard library. INCLUDE PERFETTO MODULE android.startup.startups; -- Use the android_startups table defined in the android.startup.startups -- module. SELECT * FROM android_startups;

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

Name Import Description
trace_bounds N/A 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.
android_anrs android.anrs List of all ANRs that occurred in the trace (one row per ANR).
android_app_process_starts android.app_process_starts All app cold starts with information about their cold start reason: broadcast, service, activity or provider.
android_battery_charge android.battery Battery charge at timestamp.
android_battery_stats_state android.battery_stats 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 android.battery_stats 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.
android_binder_metrics_by_process android.binder Count Binder transactions per process.
android_sync_binder_thread_state_by_txn android.binder 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 android.binder 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 android.binder Breakdown binder transactions per txn. It returns data about the client and server ends of every binder transaction async.
android_device_name android.device Extract name of the device based on metadata from the trace.
android_dvfs_counters android.dvfs Dvfs counter with duration.
android_dvfs_counter_stats android.dvfs Aggregates dvfs counter slice for statistic.
android_dvfs_counter_residency android.dvfs Aggregates dvfs counter slice for residency
android_frames_overrun android.frames.per_frame_metrics 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 android.frames.per_frame_metrics How much time did the frame's Choreographer callbacks take.
android_app_vsync_delay_per_frame android.frames.per_frame_metrics 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 android.frames.per_frame_metrics 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 android.frames.per_frame_metrics Aggregated stats of the frame.
android_frames_choreographer_do_frame android.frames.timeline All of the Choreographer#doFrame slices with their frame id.
android_frames_draw_frame android.frames.timeline 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 android.frames.timeline 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.
android_freezer_events android.freezer All frozen processes and their frozen duration.
android_garbage_collection_events android.garbage_collection All Garbage collection events with a breakdown of the time spent and heap reclaimed.
android_input_events android.input 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_job_scheduler_events android.job_scheduler All scheduled jobs and their latencies.
android_monitor_contention android.monitor_contention Contains parsed monitor contention slices.
android_monitor_contention_chain android.monitor_contention Contains parsed monitor contention slices with the parent-child relationships.
android_monitor_contention_chain_thread_state android.monitor_contention 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 android.monitor_contention 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.
android_monitor_contention_chain_blocked_functions_by_txn android.monitor_contention 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.
android_network_packets android.network_packets Android network packet events (from android.network_packets data source).
android_oom_adj_intervals android.oom_adjuster All oom adj state intervals across all processes along with the reason for the state update.
android_power_rails_counters android.power_rails Android power rails counters.
android_process_metadata android.process_metadata Data about packages running on the process.
android_screenshots android.screenshots Screenshot slices, used in perfetto UI.
android_service_bindings android.services All service bindings from client app to server app.
android_startups android.startup.startups All activity startups in the trace by startup id. Populated by different scripts depending on the platform version/contents.
android_startup_processes android.startup.startups Maps a startup to the set of processes that handled the activity start.
android_startup_threads android.startup.startups Maps a startup to the set of threads on processes that handled the activity start.
android_thread_slices_for_all_startups android.startup.startups All the slices for all startups in trace.
android_statsd_atoms android.statsd Statsd atoms.
android_suspend_state android.suspend Table of suspended and awake slices.
chrome_scrolls chrome.chrome_scrolls Defines slices for all of the individual scrolls in a trace based on the LatencyInfo-based scroll definition.
chrome_scrolling_intervals chrome.chrome_scrolls Defines slices for all of scrolls intervals in a trace based on the scroll definition in chrome_scrolls. Note that scrolls may overlap (particularly in cases of jank/broken traces, etc); so scrolling intervals are not exactly the same as individual scrolls.
chrome_cpu_power_slice chrome.cpu_powerups 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.
chrome_cpu_power_first_sched_slice_after_powerup chrome.cpu_powerups The Linux scheduler slices that executed immediately after a CPU power up.
chrome_cpu_power_post_powerup_slice chrome.cpu_powerups 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 chrome.cpu_powerups The first top-level slice that ran after a CPU power-up.
chrome_event_latency_stage_descriptions chrome.event_latency_description Source of truth of the descriptions of EventLatency stages.
chrome_histograms chrome.histograms A helper view on top of the histogram events emitted by Chrome. Requires "disabled-by-default-histogram_samples" Chrome category.
chrome_interactions chrome.interactions All critical user interaction events, including type and table with associated metrics.
chrome_page_loads chrome.page_loads Chrome page loads, including associated high-level metrics and properties.
chrome_scroll_jank_cause_descriptions chrome.scroll_jank.scroll_jank_cause_map Source of truth of the descriptions of EventLatency-based scroll jank causes.
chrome_scroll_jank_causes_with_event_latencies chrome.scroll_jank.scroll_jank_cause_map Combined description of scroll jank cause and associated event latency stage.
chrome_janky_event_latencies_v3 chrome.scroll_jank.scroll_jank_intervals 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 chrome.scroll_jank.scroll_jank_intervals Frame presentation interval is the delta between when the frame was supposed to be presented and when it was actually presented.
chrome_scroll_stats chrome.scroll_jank.scroll_jank_intervals Scroll jank frame presentation stats for individual scrolls.
chrome_scroll_jank_intervals_v3 chrome.scroll_jank.scroll_jank_intervals Defines slices for all of janky scrolling intervals in a trace.
chrome_gesture_scroll_updates chrome.scroll_jank.scroll_jank_v3 Grabs all gesture updates with respective scroll ids and start/end timestamps, regardless of being coalesced.
chrome_presented_gesture_scrolls chrome.scroll_jank.scroll_jank_v3 Scroll updates, corresponding to all input events that were converted to a presented scroll update.
chrome_scroll_updates_with_deltas chrome.scroll_jank.scroll_jank_v3 Associate every trace_id with it's perceived delta_y on the screen after prediction.
chrome_gesture_scroll_event_latencies chrome.scroll_jank.scroll_jank_v3 Extract event latency timestamps, to later use it for joining with gesture scroll updates, as event latencies don't have trace ids associated with it.
chrome_full_frame_view chrome.scroll_jank.scroll_jank_v3 Join presented gesture scrolls with their respective event latencies based on |LatchToSwapEnd| timestamp, as it's the end timestamp for both the gesture scroll update slice and the LatchToSwapEnd slice.
chrome_full_frame_delta_view chrome.scroll_jank.scroll_jank_v3 Join deltas with EventLatency data.
chrome_merged_frame_view chrome.scroll_jank.scroll_jank_v3 Group all gestures presented at the same timestamp together in a single row.
chrome_frame_info_with_delay chrome.scroll_jank.scroll_jank_v3 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 chrome.scroll_jank.scroll_jank_v3 Calculate |VSYNC_INTERVAL| as the lowest delay between frames larger than zero. TODO(b/286222128): Emit this data from Chrome instead of calculating it.
chrome_janky_frames_no_cause chrome.scroll_jank.scroll_jank_v3 Filter the frame view only to frames that had missed vsyncs.
chrome_janky_frames_no_subcause chrome.scroll_jank.scroll_jank_v3 Janky frame information including the jank cause.
chrome_janky_frames chrome.scroll_jank.scroll_jank_v3 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 chrome.scroll_jank.scroll_jank_v3 Counting all unique frame presentation timestamps.
chrome_janky_frames_percentage chrome.scroll_jank.scroll_jank_v3 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 chrome.scroll_jank.scroll_jank_v3 Number of frames and janky frames per scroll.
chrome_causes_per_scroll chrome.scroll_jank.scroll_jank_v3 Scroll jank causes per scroll.
chrome_deltas_presented_frame_scroll_update_ids chrome.scroll_jank.scroll_offsets All of the presented frame scroll update ids.
chrome_scroll_input_offsets chrome.scroll_jank.scroll_offsets The raw coordinates and pixel offsets for all input events which were part of a scroll. This includes input events that were converted to scroll events which were presented (_non_coalesced_scrolls) and scroll events which were coalesced (_coalesced_deltas).
chrome_presented_scroll_offsets chrome.scroll_jank.scroll_offsets 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_speedometer_measure chrome.speedometer 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_iteration chrome.speedometer 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.
chrome_startups chrome.startups Chrome startups, including launch cause.
chrome_java_views chrome.tasks 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.
chrome_scheduler_tasks chrome.tasks A list of tasks executed by Chrome scheduler.
chrome_tasks chrome.tasks 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 chrome.vsync_intervals 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).
chrome_web_content_interactions chrome.web_content_interactions Chrome web content interactions (InteractionToFirstPaint), including associated high-level metrics and properties.
cpu_core_types cpu.cpus All of the CPUs with their core type as a descriptive size ('little', 'mid', 'big', etc).
cpu_freq_counters cpu.freq Counter information for each frequency change for each CPU. Finds each time region where a CPU frequency is constant.
cpu_idle_counters cpu.idle Counter information for each idle state change for each CPU. Finds each time region where a CPU idle state is constant.
linux_cpu_idle_stats linux.cpu_idle Aggregates cpu idle statistics per core.
memory_heap_graph_dominator_tree memory.heap_graph_dominator_tree 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.
pkvm_hypervisor_events pkvm.hypervisor Events when CPU entered hypervisor.
sched_previous_runnable_on_thread sched.runnable Previous runnable slice on the same thread. For each "Running" thread state finds: - previous "Runnable" (or runnable preempted) state. - previous uninterrupted "Runnable" state with a valid waker thread.
sched_runnable_thread_count sched.thread_level_parallelism The count of runnable threads over time.
sched_active_cpu_count sched.thread_level_parallelism The count of active CPUs over time.
sched_time_in_state_for_thread sched.time_in_state The time a thread spent in each scheduling state during it's lifetime.
sched_percentage_of_time_in_state sched.time_in_state Summary of time spent by thread in each scheduling state, in percentage ([0, 100] ranges). Sum of all states might be smaller than 100, as those values are rounded down.
sched_utilization_per_second sched.utilization.system 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.
thread_slice_cpu_time slices.cpu_time Time each thread slice spent running on CPU. Requires scheduling data to be available in the trace.
thread_slice slices.with_context All thread slices with data about thread, thread track and process. Where possible, use available view functions which filter this view.
process_slice slices.with_context All process slices with data about process track and process. Where possible, use available view functions which filter this view.
v8_isolate v8.jit A V8 Isolate instance. A V8 Isolate represents an isolated instance of the V8 engine.
v8_js_script v8.jit Represents a script that was compiled to generate code. Some V8 code is generated out of scripts and will reference a V8Script other types of code will not (e.g. builtins).
v8_wasm_script v8.jit Represents one WASM script.
v8_js_function v8.jit Represents a v8 Javascript function.
wattson_system_states wattson.system_state The final system state for the CPU subsystem, which has all the information needed by Wattson to estimate energy for the CPU subsystem.

Functions

Name Import Return type Description
slice_is_ancestor N/A BOOL Given two slice ids, returns whether the first is an ancestor of the second.
trace_start N/A LONG Fetch start of the trace.
trace_end N/A LONG Fetch end of the trace.
trace_dur N/A LONG Fetch duration of the trace.
android_battery_stats_counter_to_string android.battery_stats STRING Converts a battery_stats counter value to human readable string.
android_extract_android_monitor_contention_blocking_thread android.monitor_contention STRING Extracts the blocking thread from a slice name
android_extract_android_monitor_contention_blocking_tid android.monitor_contention INT Extracts the blocking thread tid from a slice name
android_extract_android_monitor_contention_blocking_method android.monitor_contention STRING Extracts the blocking method from a slice name
android_extract_android_monitor_contention_short_blocking_method android.monitor_contention STRING Extracts a shortened form of the blocking method name from a slice name. The shortened form discards the parameter and return types.
android_extract_android_monitor_contention_blocked_method android.monitor_contention STRING Extracts the monitor contention blocked method from a slice name
android_extract_android_monitor_contention_short_blocked_method android.monitor_contention STRING Extracts a shortened form of the monitor contention blocked method name from a slice name. The shortened form discards the parameter and return types.
android_extract_android_monitor_contention_waiter_count android.monitor_contention INT Extracts the number of waiters on the monitor from a slice name
android_extract_android_monitor_contention_blocking_src android.monitor_contention STRING Extracts the monitor contention blocking source location from a slice name
android_extract_android_monitor_contention_blocked_src android.monitor_contention STRING Extracts the monitor contention blocked source location from a slice name
android_oom_adj_score_to_bucket_name android.oom_adjuster STRING Converts an oom_adj score Integer to String bucket name.
android_standardize_slice_name android.slices STRING 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
android_sum_dur_for_startup_and_slice android.startup.startups INT Returns duration of startup for slice name.
android_sum_dur_on_main_thread_for_startup_and_slice android.startup.startups INT Returns duration of startup for slice name on main thread.
chrome_hardware_class chrome.metadata STRING Returns hardware class of the device, often use to find device brand and model.
chrome_get_v3_jank_cause_id chrome.scroll_jank.scroll_jank_v3_cause LONG 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
chrome_calculate_avg_vsync_interval chrome.vsync_intervals FLOAT 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).
cpu_guess_core_type cpu.size STRING Guess size of CPU. On some multicore devices the cores are heterogeneous and divided into two or more 'sizes'. In a typical case a device might have 8 cores of which 4 are 'little' (low power & low performance) and 4 are 'big' (high power & high performance). This functions attempts to map a given CPU index onto the relevant descriptor. For homogeneous systems this returns NULL.
memory_heap_graph_super_root_fn memory.heap_graph_dominator_tree INT The assigned id of the "super root". Since a Java heap graph is a "forest" structure, we need to add a imaginary "super root" node which connects all the roots of the forest into a single connected component, so that the dominator tree algorithm can be performed.
sched_state_to_human_readable_string sched.states STRING Translates a single-letter scheduling state to a human-readable string.
sched_state_io_to_human_readable_string sched.states STRING Translates a single-letter scheduling state and IO wait information to a human-readable string.
time_from_ns time.conversion INT Returns the provided nanosecond duration, which is the default representation of time durations in trace processor. Provided for consistency with other functions.
time_from_us time.conversion INT Converts a duration in microseconds to nanoseconds, which is the default representation of time durations in trace processor.
time_from_ms time.conversion INT Converts a duration in millseconds to nanoseconds, which is the default representation of time durations in trace processor.
time_from_s time.conversion INT Converts a duration in seconds to nanoseconds, which is the default representation of time durations in trace processor.
time_from_min time.conversion INT Converts a duration in minutes to nanoseconds, which is the default representation of time durations in trace processor.
time_from_hours time.conversion INT Converts a duration in hours to nanoseconds, which is the default representation of time durations in trace processor.
time_from_days time.conversion INT Converts a duration in days to nanoseconds, which is the default representation of time durations in trace processor.
time_to_ns time.conversion INT Returns the provided nanosecond duration, which is the default representation of time durations in trace processor. Provided for consistency with other functions.
time_to_us time.conversion INT Converts a duration in nanoseconds to microseconds. Nanoseconds is the default representation of time durations in trace processor.
time_to_ms time.conversion INT Converts a duration in nanoseconds to millseconds. Nanoseconds is the default representation of time durations in trace processor.
time_to_s time.conversion INT Converts a duration in nanoseconds to seconds. Nanoseconds is the default representation of time durations in trace processor.
time_to_min time.conversion INT Converts a duration in nanoseconds to minutes. Nanoseconds is the default representation of time durations in trace processor.
time_to_hours time.conversion INT Converts a duration in nanoseconds to hours. Nanoseconds is the default representation of time durations in trace processor.
time_to_days time.conversion INT Converts a duration in nanoseconds to days. Nanoseconds is the default representation of time durations in trace processor.

Table functions

Name Import Description
android_binder_outgoing_graph android.binder 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.
android_binder_incoming_graph android.binder 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.
android_binder_graph android.binder 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.
android_first_frame_after android.frames.timeline Returns first frame after the provided timestamp. The returning table has at most one row.
android_monitor_contention_graph android.monitor_contention 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.
android_slices_for_startup_and_slice_name android.startup.startups Given a startup id and GLOB for a slice name, returns matching slices with data.
android_binder_transaction_slices_for_startup android.startup.startups Returns binder transaction slices for a given startup id with duration over threshold.
chrome_select_scroll_jank_cause_thread chrome.scroll_jank.scroll_jank_cause_utils 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.
chrome_select_long_task_slices chrome.scroll_jank.utils 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.
sched_active_cpu_count_for_core_type sched.thread_level_parallelism The count of active CPUs with a given core type over time.
sched_time_in_state_for_thread_in_interval sched.time_in_state Time the thread spent each state in a given interval.
sched_time_in_state_and_cpu_for_thread_in_interval sched.time_in_state Time the thread spent each state and cpu in a given interval.
sched_time_in_state_for_cpu_in_interval sched.time_in_state Time spent by CPU in each scheduling state in a provided interval.
sched_process_utilization_per_period sched.utilization.process 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.
sched_process_utilization_per_second sched.utilization.process 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.
sched_utilization_per_period sched.utilization.system Returns a table of system 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.
sched_thread_utilization_per_period sched.utilization.thread Returns a table of thread 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.
sched_thread_utilization_per_second sched.utilization.thread Returns a table of thread 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.

Macros

Name Import Description
cast_int N/A Casts |value| to INT.
cast_double N/A Casts |value| to DOUBLE.
cast_string N/A Casts |value| to STRING.
counter_leading_intervals counters.intervals For a given counter timeline (e.g. a single counter track), returns intervals of time where the counter has the same value.
graph_dominator_tree graphs.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.
tree_structural_partition_by_group graphs.partition Partitions a tree into a forest of trees based on a given grouping key in a structure-preserving way.
graph_reachable_dfs graphs.search Computes the "reachable" set of nodes in a directed graph from a given starting node 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.
graph_next_sibling graphs.search 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.
graph_reachable_weight_bounded_dfs graphs.search 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.
intervals_overlap_count intervals.overlap Compute the distribution of the overlap of the given intervals over time.

Module: prelude

Views/Tables

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.

Column Type Description

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.

Argument Type Description
ancestor_id LONG Id of the potential ancestor slice.
descendant_id LONG Id of the potential descendant slice.

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,

Argument Type Description
value Expr Query or subquery that will be cast.

cast_double Casts |value| to DOUBLE.

Returns: Expr,

Argument Type Description
value Expr Query or subquery that will be cast.

cast_string Casts |value| to STRING.

Returns: Expr,

Argument Type Description
value Expr Query or subquery that will be cast.

Module: android

android.anrs

Views/Tables

android_anrs, VIEW

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

Column Type Description
process_name STRING Name of the process that triggered the ANR.
pid INT PID of the process that triggered the ANR.
upid INT UPID of the process that triggered the ANR.
error_id STRING UUID of the ANR (generated on the platform).
ts INT Timestamp of the ANR.
subject STRING Subject line of the 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.

Column Type Description
start_id INT Slice id of the bindApplication slice in the app. Uniquely identifies a process start.
id INT Slice id of intent received in the app.
track_id INT Track id of the intent received in the app.
process_name STRING Name of the process receiving the intent.
pid INT Pid of the process receiving the intent.
upid INT Upid of the process receiving the intent.
intent STRING Intent action or component responsible for the cold start.
reason STRING Process start reason: activity, broadcast, service or provider.
proc_start_ts INT Timestamp the process start was dispatched from system_server.
proc_start_dur INT Duration to dispatch the process start from system_server.
bind_app_ts INT Timestamp the bindApplication started in the app.
bind_app_dur INT Duration to complete bindApplication in the app.
intent_ts INT Timestamp the Intent was received in the app.
intent_dur INT Duration to handle intent in the app.
total_dur INT Total duration from proc_start dispatched to intent completed.

android.battery

Views/Tables

android_battery_charge, VIEW

Battery charge at timestamp.

Column Type Description
ts INT Timestamp.
current_avg_ua INT Current average micro ampers.
capacity_percent INT Current capacity percentage.
charge_uah INT Current charge in micro ampers.
current_ua INT Current micro ampers.

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.

Column Type Description
ts INT Timestamp in nanoseconds.
dur INT The duration the state was active.
track_name STRING The name of the counter track.
value INT The counter value as a number.
value_name STRING The counter value as a human-readable string.

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':

-top=10215:"com.google.android.apps.nexuslauncher"

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:

track_name='battery_stats.top' str_value='com.google.android.apps.nexuslauncher' int_value=10215
Column Type Description
ts INT Timestamp in nanoseconds.
dur INT The duration the state was active.
track_name STRING The name of the counter track.
str_value STRING String value.
int_value INT Int value.

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.

Argument Type Description
track STRING The counter track name (e.g. 'battery_stats.audio').
value FLOAT The counter value.

android.binder

Views/Tables

android_binder_metrics_by_process, VIEW

Count Binder transactions per process.

Column Type Description
process_name INT Name of the process that started the binder transaction.
pid INT PID of the process that started the binder transaction.
slice_name STRING Name of the slice with binder transaction.
event_count INT Number of binder transactions in process in slice.

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.

Column Type Description
binder_txn_id INT slice id of the binder txn
client_ts INT Client timestamp
client_tid INT Client tid
binder_reply_id INT slice id of the binder reply
server_ts INT Server timestamp
server_tid INT Server tid
thread_state_type STRING whether thread state is on the txn or reply side
thread_state STRING a thread_state that occurred in the txn
thread_state_dur INT aggregated dur of the |thread_state| in the txn
thread_state_count INT aggregated count of the |thread_state| in the txn

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.

Column Type Description
binder_txn_id INT slice id of the binder txn
client_ts INT Client ts
client_tid INT Client tid
binder_reply_id INT slice id of the binder reply
server_ts INT Server ts
server_tid INT Server tid
thread_state_type STRING whether thread state is on the txn or reply side
blocked_function STRING blocked kernel function in a thread state
blocked_function_dur INT aggregated dur of the |blocked_function| in the txn
blocked_function_count INT aggregated count of the |blocked_function| in the txn

android_binder_txns, TABLE

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

Column Type Description
aidl_name STRING name of the binder interface if existing.
aidl_ts INT Timestamp the binder interface name was emitted. Proxy to 'ts' and 'dur' for async txns.
aidl_dur INT Duration of the binder interface name. Proxy to 'ts' and 'dur' for async txns.
binder_txn_id INT slice id of the binder txn.
client_process STRING name of the client process.
client_thread STRING name of the client thread.
client_upid INT Upid of the client process.
client_utid INT Utid of the client thread.
client_tid INT Tid of the client thread.
client_pid INT Pid of the client thread.
is_main_thread BOOL Whether the txn was initiated from the main thread of the client process.
client_ts INT timestamp of the client txn.
client_dur INT wall clock dur of the client txn.
binder_reply_id INT slice id of the binder reply.
server_process STRING name of the server process.
server_thread STRING name of the server thread.
server_upid INT Upid of the server process.
server_utid INT Utid of the server thread.
server_tid INT Tid of the server thread.
server_pid INT Pid of the server thread.
server_ts INT timestamp of the server txn.
server_dur INT wall clock dur of the server txn.
client_oom_score INT oom score of the client process at the start of the txn.
server_oom_score INT oom score of the server process at the start of the reply.
is_sync BOOL whether the txn is synchronous or async (oneway).
client_monotonic_dur INT monotonic clock dur of the client txn.
server_monotonic_dur INT monotonic clock dur of the server txn.
client_package_version_code INT Client package version_code.
server_package_version_code INT Server package version_code.
is_client_package_debuggable INT Whether client package is debuggable.
is_server_package_debuggable INT Whether server package is debuggable.

Functions

Argument Type Description
Argument Type Description
-------- ---- -----------
Argument Type Description
-------- ---- -----------

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.

Column Type Description
pprof BYTES Pprof of outgoing binder txns.

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.

Column Type Description
pprof BYTES Pprof of incoming binder txns.

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.

Column Type Description
pprof BYTES Pprof of binder txns.

android.device

Views/Tables

android_device_name, TABLE

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

Column Type Description
name STRING Device name.

android.dvfs

Views/Tables

android_dvfs_counters, VIEW

Dvfs counter with duration.

Column Type Description
name STRING Counter name.
ts INT Timestamp when counter value changed.
value INT Counter value.
dur INT Counter duration.

android_dvfs_counter_stats, TABLE

Aggregates dvfs counter slice for statistic.

Column Type Description
name STRING Counter name on which all the other values are aggregated on.
max INT Max of all counter values for the counter name.
min INT Min of all counter values for the counter name.
dur INT Duration between the first and last counter value for the counter name.
wgt_avg FLOAT Weighted avergate of all the counter values for the counter name.

android_dvfs_counter_residency, VIEW

Aggregates dvfs counter slice for residency

Column Type Description
name STRING Counter name.
value INT Counter value.
dur INT Counter duration.
pct FLOAT Counter duration as a percentage of total duration.

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.

Column Type Description
frame_id INT Frame id.
overrun INT Difference between expected and actual frame ends. Positive if frame didn't miss deadline.

android_frames_ui_time, TABLE

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

Column Type Description
frame_id INT Frame id
ui_time INT UI time duration

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.

Column Type Description
frame_id INT Frame id
app_vsync_delay INT App VSYNC delay.

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.

Column Type Description
frame_id INT Frame id
app_vsync_delay INT Difference between actual timeline of the frame and Choreographer#doFrame. See android_app_vsync_delay_per_frame table for more details.
do_frame_dur INT Duration of Choreographer#doFrame slice.
draw_frame_dur INT Duration of DrawFrame slice. Summed duration of all DrawFrame slices, if more than one. See android_frames_draw_frame for more details.
cpu_time INT CPU time across the UI Thread + RenderThread.

android_frame_stats, TABLE

Aggregated stats of the frame.

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

Column Type Description
frame_id INT Frame id.
overrun INT The amount by which each frame missed of hit its deadline. See android_frames_overrun for details.
cpu_time INT How much time did the frame take across the UI Thread + RenderThread.
ui_time INT How much time did the frame's Choreographer callbacks take.
was_jank BOOL Was frame janky.
was_slow_frame BOOL CPU time of the frame took over 20ms.
was_big_jank BOOL CPU time of the frame took over 50ms.
was_huge_jank BOOL CPU time of the frame took over 200ms.

android.frames.timeline

Views/Tables

android_frames_choreographer_do_frame, TABLE

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

Column Type Description
id INT slice.id
frame_id INT Frame id
ui_thread_utid INT Utid of the UI thread

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

Column Type Description
id INT slice.id
frame_id INT Frame id
render_thread_utid INT Utid of the render thread

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.

Column Type Description
frame_id INT Frame id.
ts INT Timestamp of the frame. Start of the frame as defined by the start of "Choreographer#doFrame" slice and the same as the start of the frame in `actual_frame_timeline_slice .
dur INT Duration of the frame, as defined by the duration of the corresponding actual_frame_timeline_slice duration.
do_frame_id INT slice.id of "Choreographer#doFrame" slice.
draw_frame_id INT slice.id of "DrawFrame" slice.
actual_frame_timeline_id INT slice.id from actual_frame_timeline_slice
expected_frame_timeline_id INT slice.id from expected_frame_timeline_slice
render_thread_utid INT utid of the render thread.
ui_thread_utid INT utid of the UI thread.

Functions

Argument Type Description

Table Functions

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

ts | INT | Timestamp.

Column Type Description
frame_id INT Frame id.
ts INT Start of the frame, the timestamp of the "Choreographer#doFrame" slice.
dur INT Duration of the frame.
do_frame_id INT slice.id of "Choreographer#doFrame" slice.
draw_frame_id INT slice.id of "DrawFrame" slice.
actual_frame_timeline_id INT slice.id from actual_frame_timeline_slice
expected_frame_timeline_id INT slice.id from expected_frame_timeline_slice
render_thread_utid INT utid of the render thread.
ui_thread_utid INT utid of the UI thread.

android.freezer

Views/Tables

android_freezer_events, TABLE

All frozen processes and their frozen duration.

Column Type Description
upid INT Upid of frozen process
pid INT Pid of frozen process
ts INT Timestamp process was frozen.
dur INT Duration process was frozen for.
unfreeze_reason_int INT Unfreeze reason Integer.
unfreeze_reason_str INT Unfreeze reason String.

android.garbage_collection

Views/Tables

android_garbage_collection_events, TABLE

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

Column Type Description
tid INT Tid of thread running garbage collection.
pid INT Pid of process running garbage collection.
utid INT Utid of thread running garbage collection.
upid INT Upid of process running garbage collection.
thread_name INT Name of thread running garbage collection.
process_name INT Name of process running garbage collection.
gc_type STRING Type of garbage collection.
is_mark_compact INT Whether gargage collection is mark compact or copying.
reclaimed_mb INT MB reclaimed after garbage collection.
min_heap_mb INT Minimum heap size in MB during garbage collection.
max_heap_mb INT Maximum heap size in MB during garbage collection.
gc_id INT Garbage collection id.
gc_ts INT Garbage collection timestamp.
gc_dur INT Garbage collection wall duration.
gc_running_dur INT Garbage collection duration spent executing on CPU.
gc_runnable_dur INT Garbage collection duration spent waiting for CPU.
gc_unint_io_dur INT Garbage collection duration spent waiting in the Linux kernel on IO.
gc_unint_non_io_dur INT Garbage collection duration spent waiting in the Linux kernel without IO.
gc_int_dur INT Garbage collection duration spent waiting in interruptible sleep.

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.
Column Type Description
dispatch_latency_dur INT Duration from input dispatch to input received.
handling_latency_dur INT Duration from input received to input ACK sent.
ack_latency_dur INT Duration from input ACK sent to input ACK recieved.
total_latency_dur INT Duration from input dispatch to input event ACK received.
tid INT Tid of thread receiving the input event.
thread_name INT Name of thread receiving the input event.
pid INT Pid of process receiving the input event.
process_name INT Name of process receiving the input event.
event_type INT Input event type. See InputTransport.h: InputMessage#Type
event_seq INT Input event sequence number, monotonically increasing for an event channel and pid.
event_channel INT Input event channel name.
dispatch_track_id INT Thread track id of input event dispatching thread.
dispatch_ts INT Timestamp input event was dispatched.
dispatch_dur INT Duration of input event dispatch.
receive_track_id INT Thread track id of input event receiving thread.
receive_ts INT Timestamp input event was received.
receive_dur INT Duration of input event receipt.

android.job_scheduler

Views/Tables

android_job_scheduler_events, TABLE

All scheduled jobs and their latencies.

Column Type Description
job_id INT Id of the scheduled job assigned by the app developer.
uid INT Uid of the process running the scheduled job.
package_name STRING Package name of the process running the scheduled job.
job_service_name STRING Service component name of the scheduled job.
track_id INT Thread track id of the job scheduler event slice.
id INT Slice id of the job scheduler event slice.
ts INT Timestamp the job was scheduled.
dur INT Duration of the scheduled job.

android.monitor_contention

Views/Tables

android_monitor_contention, TABLE

Contains parsed monitor contention slices.

Column Type Description
blocking_method None Name of the method holding the lock.
blocked_methhod None Name of the method trying to acquire the lock.
short_blocking_method None Blocking_method without arguments and return types.
short_blocked_method None Blocked_method without arguments and return types.
blocking_src None File location of blocking_method in form filename:linenumber.
blocked_src None File location of blocked_method in form filename:linenumber.
waiter_count None Zero indexed number of threads trying to acquire the lock.
blocking_utid None Utid of thread holding the lock.
blocking_thread_name None Thread name of thread holding the lock.
upid None Upid of process experiencing lock contention.
process_name None Process name of process experiencing lock contention.
id None Slice id of lock contention.
ts None Timestamp of lock contention start.
dur None Wall clock duration of lock contention.
monotonic_dur None Monotonic clock duration of lock contention.
track_id None Thread track id of blocked thread.
is_blocked_main_thread None Whether the blocked thread is the main thread.
is_blocking_main_thread None Whether the blocking thread is the main thread.
binder_reply_id None Slice id of binder reply slice if lock contention was part of a binder txn.
binder_reply_ts None Timestamp of binder reply slice if lock contention was part of a binder txn.
binder_reply_tid None Tid of binder reply slice if lock contention was part of a binder txn.

android_monitor_contention_chain, TABLE

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

Column Type Description
parent_id None Id of monitor contention slice blocking this contention.
blocking_method None Name of the method holding the lock.
blocked_methhod None Name of the method trying to acquire the lock.
short_blocking_method None Blocking_method without arguments and return types.
short_blocked_method None Blocked_method without arguments and return types.
blocking_src None File location of blocking_method in form filename:linenumber.
blocked_src None File location of blocked_method in form filename:linenumber.
waiter_count None Zero indexed number of threads trying to acquire the lock.
blocking_utid None Utid of thread holding the lock.
blocking_thread_name None Thread name of thread holding the lock.
upid None Upid of process experiencing lock contention.
process_name None Process name of process experiencing lock contention.
id None Slice id of lock contention.
ts None Timestamp of lock contention start.
dur None Wall clock duration of lock contention.
monotonic_dur None Monotonic clock duration of lock contention.
track_id None Thread track id of blocked thread.
is_blocked_main_thread None Whether the blocked thread is the main thread.
is_blocking_main_thread None Whether the blocking thread is the main thread.
binder_reply_id None Slice id of binder reply slice if lock contention was part of a binder txn.
binder_reply_ts None Timestamp of binder reply slice if lock contention was part of a binder txn.
binder_reply_tid None Tid of binder reply slice if lock contention was part of a binder txn.
child_id None Id of monitor contention slice blocked by this contention.

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.

Column Type Description
parent_id None Id of slice blocking the blocking_thread.
blocking_method None Name of the method holding the lock.
blocked_methhod None Name of the method trying to acquire the lock.
short_blocking_method None Blocking_method without arguments and return types.
short_blocked_method None Blocked_method without arguments and return types.
blocking_src None File location of blocking_method in form filename:linenumber.
blocked_src None File location of blocked_method in form filename:linenumber.
waiter_count None Zero indexed number of threads trying to acquire the lock.
blocking_utid None Utid of the blocking |thread_state|.
blocking_thread_name None Thread name of thread holding the lock.
upid None Upid of process experiencing lock contention.
process_name None Process name of process experiencing lock contention.
id None Slice id of lock contention.
ts None Timestamp of the blocking |thread_state|.
dur None Wall clock duration of lock contention.
monotonic_dur None Monotonic clock duration of lock contention.
track_id None Thread track id of blocked thread.
is_blocked_main_thread None Whether the blocked thread is the main thread.
is_blocking_main_thread None Whether the blocking thread is the main thread.
binder_reply_id None Slice id of binder reply slice if lock contention was part of a binder txn.
binder_reply_ts None Timestamp of binder reply slice if lock contention was part of a binder txn.
binder_reply_tid None Tid of binder reply slice if lock contention was part of a binder txn.
state None Thread state of the blocking thread.
blocked_function None Blocked kernel function of the blocking thread.

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.

Column Type Description
id INT Slice id of the monitor contention.
thread_state STRING A |thread_state| that occurred in the blocking thread during the contention.
thread_state_dur INT Total time the blocking thread spent in the |thread_state| during contention.
thread_state_count INT Count of all times the blocking thread entered |thread_state| during the contention.

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.

Column Type Description
id INT Slice id of the monitor contention.
blocked_function STRING Blocked kernel function in a thread state in the blocking thread during the contention.
blocked_function_dur INT Total time the blocking thread spent in the |blocked_function| during the contention.
blocked_function_count INT Count of all times the blocking thread executed the |blocked_function| during the contention.

Functions

android_extract_android_monitor_contention_blocking_thread

Extracts the blocking thread from a slice name

Returns: STRING, Blocking thread

Argument Type Description
slice_name STRING Name of slice

android_extract_android_monitor_contention_blocking_tid

Extracts the blocking thread tid from a slice name

Returns: INT, Blocking thread tid

Argument Type Description
slice_name STRING Name of slice

android_extract_android_monitor_contention_blocking_method

Extracts the blocking method from a slice name

Returns: STRING, Blocking thread

Argument Type Description
slice_name STRING Name of slice

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

Argument Type Description
slice_name STRING Name of slice

android_extract_android_monitor_contention_blocked_method

Extracts the monitor contention blocked method from a slice name

Returns: STRING, Blocking thread

Argument Type Description
slice_name STRING Name of slice

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

Argument Type Description
slice_name STRING Name of slice

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

Argument Type Description
slice_name STRING Name of slice

android_extract_android_monitor_contention_blocking_src

Extracts the monitor contention blocking source location from a slice name

Returns: STRING, Blocking thread

Argument Type Description
slice_name STRING Name of slice

android_extract_android_monitor_contention_blocked_src

Extracts the monitor contention blocked source location from a slice name

Returns: STRING, Blocking thread

Argument Type Description
slice_name STRING Name of slice
Argument Type Description

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.

Column Type Description
pprof BYTES Pprof of lock graph.

android.network_packets

Views/Tables

android_network_packets, VIEW

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

Column Type Description
ts INT Timestamp in nanoseconds.
dur INT Duration (non-zero only in aggregate events)
track_name STRING The track name (interface and direction)
package_name STRING Traffic package source (or uid=$X if not found)
iface STRING Traffic interface name (linux interface name)
direction STRING Traffic direction ('Transmitted' or 'Received')
packet_count INT Number of packets in this event
packet_length INT Number of bytes in this event (wire size)
packet_transport STRING Transport used for traffic in this event
packet_tcp_flags INT TCP flags used by tcp frames in this event
socket_tag STRING The Android traffic tag of the network socket
socket_uid INT The Linux user id of the network socket
local_port INT The local port number (for udp or tcp only)
remote_port INT The remote port number (for udp or tcp only)
packet_icmp_type INT 1-byte ICMP type identifier.
packet_icmp_code INT 1-byte ICMP code identifier.

android.oom_adjuster

Views/Tables

android_oom_adj_intervals, TABLE

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

Column Type Description
ts INT Timestamp the oom_adj score of the process changed
dur INT Duration until the next oom_adj score change of the process.
score INT oom_adj score of the process.
bucket STRING oom_adj bucket of the process.
upid INT Upid of the process having an oom_adj update.
process_name STRING Name of the process having an oom_adj update.
oom_adj_id INT Slice id of the latest oom_adj update in the system_server.
oom_adj_ts INT Timestamp of the latest oom_adj update in the system_server.
oom_adj_dur INT Duration of the latest oom_adj update in the system_server.
oom_adj_track_id INT Track id of the latest oom_adj update in the system_server
oom_adj_thread_name STRING Thread name of the latest oom_adj update in the system_server.
oom_adj_reason STRING Reason for the latest oom_adj update in the system_server.
oom_adj_trigger STRING Trigger for the latest oom_adj update in the system_server.

Functions

android_oom_adj_score_to_bucket_name

Converts an oom_adj score Integer to String bucket name.

Returns: STRING, Returns the oom_adj bucket.

Argument Type Description
value INT oom_adj score.
android_appid INT android_app id of the process.

android.power_rails

Views/Tables

android_power_rails_counters, TABLE

Android power rails counters.

Column Type Description
id INT counter.id
ts INT Counter timestamp.
power_rail_name INT Power rail name. From counter_track.name.
value DOUBLE Power rails counter value in micro watts.

android.process_metadata

Views/Tables

android_process_metadata, TABLE

Data about packages running on the process.

Column Type Description
upid INT Process upid.
process_name STRING Process name.
uid INT Android app UID.
shared_uid BOOL Whether the UID is shared by multiple packages.
package_name STRING Name of the packages running in this process.
version_code INT Package version code.
debuggable INT Whether package is debuggable.

android.screenshots

Views/Tables

android_screenshots, TABLE

Screenshot slices, used in perfetto UI.

Column Type Description
id INT Slice id.
ts INT Slice timestamp.
dur INT Slice duration, should be typically 0 since screeenshot slices are of instant type.
name STRING Slice name.

android.services

Views/Tables

android_service_bindings, TABLE

All service bindings from client app to server app.

Column Type Description
client_oom_score INT OOM score of client process making the binding.
client_process STRING Name of client process making the binding.
client_thread STRING Name of client thread making the binding.
client_pid INT Pid of client process making the binding.
client_tid INT Tid of client process making the binding.
client_upid INT Upid of client process making the binding.
client_utid INT Utid of client thread making the binding.
client_ts INT Timestamp the client process made the request.
client_dur INT Duration of the client binding request.
server_oom_score INT OOM score of server process getting bound to.
server_process STRING Name of server process getting bound to
server_thread STRING Name of server thread getting bound to.
server_pid INT Pid of server process getting bound to.
server_tid INT Tid of server process getting bound to.
server_upid INT Upid of server process getting bound to.
server_utid INT Utid of server process getting bound to.
server_ts INT Timestamp the server process got bound to.
server_dur INT Duration of the server process handling the binding.
token STRING Unique binder identifier for the Service binding.
act STRING Intent action name for the service binding.
cmp STRING Intent component name for the service binding.
flg STRING Intent flag for the service binding.
bind_seq INT Monotonically increasing id for the service binding.

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:

Returns: STRING, Simplified name.

Argument Type Description
name STRING The raw slice 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.

Column Type Description
startup_id INT Startup id.
ts INT Timestamp of startup start.
ts_end INT Timestamp of startup end.
dur INT Startup duration.
package STRING Package name.
startup_type STRING Startup type.

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.

Column Type Description
startup_id INT Startup id.
upid INT Upid of process on which activity started.
startup_type INT Type of the startup.

android_startup_threads, VIEW

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

Column Type Description
startup_id INT Startup id.
ts INT Timestamp of start.
dur INT Duration of startup.
upid INT Upid of process involved in startup.
utid INT Utid of the thread.
thread_name STRING Name of the thread.
is_main_thread BOOL Thread is a main thread.

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.

Column Type Description
startup_ts INT Timestamp of startup.
startup_ts_end INT Timestamp of startup end.
startup_id INT Startup id.
utid INT UTID of thread with slice.
thread_name STRING Name of thread.
is_main_thread BOOL Whether it is main thread.
arg_set_id INT Arg set id.
slice_id INT Slice id.
slice_name STRING Name of slice.
slice_ts INT Timestamp of slice start.
slice_dur INT Slice duration.

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.

Argument Type Description
startup_id LONG Startup id.
slice_name STRING Slice name.

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.

Argument Type Description
startup_id LONG Startup id.
slice_name STRING Slice name.
Argument Type Description
Argument Type Description
-------- ---- -----------

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.

Column Type Description
slice_name STRING Name of the slice.
slice_ts INT Timestamp of start of the slice.
slice_dur INT Duration of the slice.
thread_name STRING Name of the thread with the slice.
arg_set_id INT Arg set id.

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.

Column Type Description
id INT Slice id.
slice_dur INT Slice duration.
thread_name STRING Name of the thread with slice.
process STRING Name of the process with slice.
arg_set_id INT Arg set id.
is_main_thread BOOL Whether is main thread.

android.statsd

Views/Tables

android_statsd_atoms, VIEW

Statsd atoms.

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

Column Type Description
id INT Unique identifier for this slice.
type STRING The name of the "most-specific" child table containing this row.
ts INT The timestamp at the start of the slice (in nanoseconds).
dur INT The duration of the slice (in nanoseconds).
arg_set_id INT The id of the argument set associated with this slice.
thread_instruction_count INT The value of the CPU instruction counter at the start of the slice. This column will only be populated if thread instruction collection is enabled with track_event.
thread_instruction_delta INT The change in value of the CPU instruction counter between the start and end of the slice. This column will only be populated if thread instruction collection is enabled with track_event.
track_id INT The id of the track this slice is located on.
category STRING The "category" of the slice. If this slice originated with track_event, this column contains the category emitted. Otherwise, it is likely to be null (with limited exceptions).
name STRING The name of the slice. The name describes what was happening during the slice.
depth INT The depth of the slice in the current stack of slices.
stack_id INT A unique identifier obtained from the names of all slices in this stack. This is rarely useful and kept around only for legacy reasons.
parent_stack_id INT The stack_id for the parent of this slice. Rarely useful.
parent_id INT The id of the parent (i.e. immediate ancestor) slice for this slice.
thread_ts INT The thread timestamp at the start of the slice. This column will only be populated if thread timestamp collection is enabled with track_event.
thread_dur INT The thread time used by this slice. This column will only be populated if thread timestamp collection is enabled with track_event.

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.

Column Type Description
ts INT Timestamp
dur INT Duration
power_state STRING 'awake' or 'suspended'

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.

Column Type Description
id INT The unique identifier of the scroll.
ts INT The start timestamp of the scroll.
dur INT The duration of the scroll.
gesture_scroll_begin_ts INT The earliest timestamp of the InputLatency::GestureScrollBegin for the corresponding scroll id.
gesture_scroll_end_ts INT The earliest timestamp of the InputLatency::GestureScrollEnd for the corresponding scroll id.

chrome_scrolling_intervals, VIEW

Defines slices for all of scrolls intervals in a trace based on the scroll definition in chrome_scrolls. Note that scrolls may overlap (particularly in cases of jank/broken traces, etc); so scrolling intervals are not exactly the same as individual scrolls.

Column Type Description
id INT The unique identifier of the scroll interval. This may span multiple scrolls if they overlap.
scroll_ids STRING Comma-separated list of scroll ids that are included in this interval.
ts INT The start timestamp of the scroll interval.
dur INT The duration of the scroll interval.

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.

Column Type Description
ts INT The timestamp at the start of the slice.
dur INT The duration of the slice.
cpu INT The CPU on which the transition occurred
power_state INT The power state that the CPU was in at time 'ts' for duration 'dur'.
previous_power_state INT The power state that the CPU was previously in.
powerup_id INT A unique ID for the CPU power-up.

chrome_cpu_power_first_sched_slice_after_powerup, TABLE

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

Column Type Description
ts INT The timestamp at the start of the slice.
dur INT The duration of the slice.
cpu INT The cpu on which the slice executed.
sched_id INT Id for the sched_slice table.
utid INT Unique id for the thread that ran within the slice.
previous_power_state INT The CPU's power state before this slice.
powerup_id INT A unique ID for the 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.

Column Type Description
ts None Timestamp of the resulting slice
dur None Duration of the slice.
cpu None The CPU the sched slice ran on.
utid None Unique thread id for the slice.
sched_id None 'id' field from the sched_slice table.
type None From the sched_slice table, always 'sched_slice'.
end_state None The ending state for the sched_slice
priority None The kernel thread priority
slice_id None Id of the top-level slice for this (sched) slice.

chrome_cpu_power_first_toplevel_slice_after_powerup, VIEW

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

Column Type Description
slice_id INT ID of the slice in the slice table.
previous_power_state INT The power state of the CPU prior to power-up.

chrome.event_latency_description

Views/Tables

chrome_event_latency_stage_descriptions, TABLE

Source of truth of the descriptions of EventLatency stages.

Column Type Description
name STRING The name of the EventLatency stage.
description STRING A description of the EventLatency stage.

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.

Column Type Description
name STRING The name of the histogram.
value INT The value of the histogram sample.
ts INT Alias of |slice.ts|.
thread_name STRING Thread name.
utid INT Utid of the thread.
tid INT Tid of the thread.
process_name STRING Process name.
upid INT Upid of the process.
pid INT Pid of the process.

chrome.interactions

Views/Tables

chrome_interactions, TABLE

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

Column Type Description
scoped_id INT Identifier of the interaction; this is not guaranteed to be unique to the table - rather, it is unique within an individual interaction type. Combine with type to get a unique identifier in this table.
type STRING Type of this interaction, which together with scoped_id uniquely identifies this interaction. Also corresponds to a SQL table name containing more details specific to this type of interaction.
name STRING Interaction name - e.g. 'PageLoad', 'Tap', etc. Interactions will have unique metrics stored in other tables.
ts INT Timestamp of the CUI event.
dur INT Duration of the CUI event.

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.

Column Type Description
id INT ID of the navigation and Chrome browser process; this combination is unique to every individual navigation.
navigation_id INT ID of the navigation associated with the page load (i.e. the cross-document navigation in primary main frame which created this page's main document). Also note that navigation_id is specific to a given Chrome browser process, and not globally unique.
navigation_start_ts INT Timestamp of the start of navigation.
fcp INT Duration between the navigation start and the first contentful paint event (web.dev/fcp).
fcp_ts INT Timestamp of the first contentful paint.
lcp INT Duration between the navigation start and the largest contentful paint event (web.dev/lcp).
lcp_ts INT Timestamp of the largest contentful paint.
dom_content_loaded_event_ts INT Timestamp of the DomContentLoaded event: https://developer.mozilla.org/en-US/docs/Web/API/Document/DOMContentLoaded_event
load_event_ts INT Timestamp of the window load event: https://developer.mozilla.org/en-US/docs/Web/API/Window/load_event
mark_fully_loaded_ts INT Timestamp of the page self-reporting as fully loaded through the performance.mark('mark_fully_loaded') API.
mark_fully_visible_ts INT Timestamp of the page self-reporting as fully visible through the performance.mark('mark_fully_visible') API.
mark_interactive_ts INT Timestamp of the page self-reporting as fully interactive through the performance.mark('mark_interactive') API.
url STRING URL at the page load event.
browser_upid INT The unique process id (upid) of the browser process where the page load occurred.

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.

Column Type Description
event_latency_stage STRING The name of the EventLatency stage.
cause_process STRING The process where the cause of scroll jank occurred.
cause_thread STRING The thread where the cause of scroll jank occurred.
cause_description STRING A description of the cause of scroll jank.

chrome_scroll_jank_causes_with_event_latencies, VIEW

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

Column Type Description
name STRING The name of the EventLatency stage.
description STRING Description of the EventLatency stage.
cause_process STRING The process name that may cause scroll jank.
cause_thread STRING The thread name that may cause scroll jank. The thread will be on the cause_process.
cause_description STRING Description of the cause of scroll jank on this process and thread.

chrome.scroll_jank.scroll_jank_cause_utils

Functions

Argument Type Description

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.

Column Type Description
utid INT The utid associated with

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.

Column Type Description
id INT The slice id.
ts INT The start timestamp of the slice.
dur INT The duration of the slice.
track_id INT The track_id for the slice.
name STRING The name of the slice (EventLatency).
cause_of_jank STRING The stage of EventLatency that the caused the jank.
sub_cause_of_jank STRING The stage of cause_of_jank that caused the jank.
delayed_frame_count INT How many vsyncs this frame missed its deadline by.
frame_jank_ts INT The start timestamp where frame presentation was delayed.
frame_jank_dur INT The duration in ms of the delay in frame presentation.

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.

Column Type Description
id INT Unique id.
ts INT The start timestamp of the slice.
dur INT The duration of the slice.
delayed_frame_count INT How many vsyncs this frame missed its deadline by.
cause_of_jank INT The stage of EventLatency that the caused the jank.
sub_cause_of_jank INT The stage of cause_of_jank that caused the jank.
event_latency_id INT The id of the associated event latency in the slice table.

chrome_scroll_stats, VIEW

Scroll jank frame presentation stats for individual scrolls.

Column Type Description
scroll_id INT Id of the individual scroll.
frame_count INT The number of frames in the scroll.
missed_vsyncs INT The number of missed vsyncs in the scroll.
presented_frame_count INT The number presented frames in the scroll.
janky_frame_count INT The number of janky frames in the scroll.
janky_frame_percent FLOAT The % of frames that janked in the scroll.

chrome_scroll_jank_intervals_v3, TABLE

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

Column Type Description
id INT The unique identifier of the janky interval.
ts INT The start timestamp of the janky interval.
dur INT The duration of the janky interval.

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

Column Type Description
ts INT The start timestamp of the scroll.
dur INT The duration of the scroll.
id INT Slice id for the scroll.
scroll_update_id INT The id of the scroll update event.
scroll_id INT The id of the scroll.
is_coalesced BOOL Whether this input event was coalesced.

chrome_presented_gesture_scrolls, TABLE

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

Column Type Description
id INT Minimum slice id for input presented in this frame, the non coalesced input.
ts INT The start timestamp for producing the frame.
dur INT The duration between producing and presenting the frame.
last_coalesced_input_ts INT The timestamp of the last input that arrived and got coalesced into the frame.
scroll_update_id INT The id of the scroll update event, a unique identifier to the gesture.
scroll_id INT The id of the ongoing scroll.

chrome_scroll_updates_with_deltas, TABLE

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

Column Type Description
scroll_update_id INT The id of the scroll update event.
delta_y INT The perceived delta_y on the screen post prediction.

chrome_gesture_scroll_event_latencies, TABLE

Extract event latency timestamps, to later use it for joining with gesture scroll updates, as event latencies don't have trace ids associated with it.

Column Type Description
ts INT Start timestamp for the EventLatency.
event_latency_id INT Slice id of the EventLatency.
dur INT Duration of the EventLatency.
input_latency_end_ts INT End timestamp for input aka the timestamp of the LatchToSwapEnd substage.
presentation_timestamp INT Frame presentation timestamp aka the timestamp of the SwapEndToPresentationCompositorFrame substage.
event_type INT EventLatency event type.

chrome_full_frame_view, TABLE

Join presented gesture scrolls with their respective event latencies based on |LatchToSwapEnd| timestamp, as it's the end timestamp for both the gesture scroll update slice and the LatchToSwapEnd slice.

Column Type Description
id INT ID of the frame.
ts INT Start timestamp of the frame.
last_coalesced_input_ts INT The timestamp of the last coalesced input.
scroll_id INT ID of the associated scroll.
scroll_update_id INT ID of the associated scroll update.
event_latency_id INT ID of the associated EventLatency.
dur INT Duration of the associated EventLatency.
presentation_timestamp INT Frame presentation timestamp.

chrome_full_frame_delta_view, TABLE

Join deltas with EventLatency data.

Column Type Description
id INT ID of the frame.
ts INT Start timestamp of the frame.
scroll_id INT ID of the associated scroll.
scroll_update_id INT ID of the associated scroll update.
last_coalesced_input_ts INT The timestamp of the last coalesced input.
delta_y INT The perceived delta_y on the screen post prediction.
event_latency_id INT ID of the associated EventLatency.
dur INT Duration of the associated EventLatency.
presentation_timestamp INT Frame presentation timestamp.

chrome_merged_frame_view, VIEW

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

Column Type Description
id INT ID of the frame.
max_start_ts INT The timestamp of the last coalesced input.
min_start_ts INT The earliest frame start timestamp.
scroll_id INT ID of the associated scroll.
scroll_update_id INT ID of the associated scroll update.
encapsulated_scroll_ids INT All scroll updates associated with the frame presentation timestamp.
total_delta INT Sum of all perceived delta_y values at the frame presentation timestamp.
segregated_delta_y INT Lists all of the perceived delta_y values at the frame presentation timestamp.
event_latency_id INT ID of the associated EventLatency.
dur INT Maximum duration of the associated EventLatency.
presentation_timestamp INT Frame presentation timestamp.

chrome_frame_info_with_delay, VIEW

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.

Column Type Description
id INT gesture scroll slice id.
max_start_ts INT OS timestamp of the last touch move arrival within a frame.
min_start_ts INT OS timestamp of the first touch move arrival within a frame.
scroll_id INT The scroll which the touch belongs to.
scroll_update_id INT ID of the associated scroll update.
encapsulated_scroll_ids INT Trace ids of all frames presented in at this vsync.
total_delta INT Summation of all delta_y of all gesture scrolls in this frame.
segregated_delta_y INT All delta y of all gesture scrolls comma separated, summing those gives |total_delta|.
event_latency_id INT Event latency id of the presented frame.
dur INT Duration of the EventLatency.
presentation_timestamp INT Timestamp at which the frame was shown on the screen.
delay_since_last_frame INT Time elapsed since the previous frame was presented, usually equals |VSYNC| if no frame drops happened.
delay_since_last_input INT Difference in OS timestamps of inputs in the current and the previous frame.
prev_event_latency_id INT The event latency id that will be used as a reference to determine the jank cause.

chrome_vsyncs, VIEW

Calculate |VSYNC_INTERVAL| as the lowest delay between frames larger than zero. TODO(b/286222128): Emit this data from Chrome instead of calculating it.

Column Type Description
vsync_interval INT The lowest delay between frames larger than zero.

chrome_janky_frames_no_cause, VIEW

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

Column Type Description
delay_since_last_frame INT Time elapsed since the previous frame was presented, will be more than |VSYNC| in this view.
event_latency_id INT Event latency id of the presented frame.
vsync_interval INT Vsync interval at the time of recording the trace.
hardware_class STRING Device brand and model.
scroll_id INT The scroll corresponding to this frame.
prev_event_latency_id INT The event latency id that will be used as a reference to determine the jank cause.

chrome_janky_frames_no_subcause, VIEW

Janky frame information including the jank cause.

Column Type Description
delay_since_last_frame INT Time elapsed since the previous frame was presented, will be more than |VSYNC| in this view.
event_latency_id INT Event latency id of the presented frame.
vsync_interval INT Vsync interval at the time of recording the trace.
hardware_class STRING Device brand and model.
scroll_id INT The scroll corresponding to this frame.
prev_event_latency_id INT The event latency id that will be used as a reference to determine the jank cause.
cause_id INT Id of the slice corresponding to the offending stage.

chrome_janky_frames, VIEW

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

Column Type Description
cause_of_jank INT The reason the Vsync was missed.
sub_cause_of_jank INT Further breakdown if the root cause was GPU related.
delay_since_last_frame INT Time elapsed since the previous frame was presented, will be more than |VSYNC| in this view.
event_latency_id INT Event latency id of the presented frame.
vsync_interval INT Vsync interval at the time of recording the trace.
hardware_class STRING Device brand and model.
scroll_id INT The scroll corresponding to this frame.

chrome_unique_frame_presentation_ts, VIEW

Counting all unique frame presentation timestamps.

Column Type Description
presentation_timestamp INT The unique frame presentation timestamp.

chrome_janky_frames_percentage, VIEW

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

Column Type Description
delayed_frame_percentage FLOAT The percent of missed frames relative to total frames - aka the percent of janky frames.

chrome_frames_per_scroll, VIEW

Number of frames and janky frames per scroll.

Column Type Description
scroll_id INT The ID of the scroll.
num_frames INT The number of frames in the scroll.
num_janky_frames INT The number of delayed/janky frames.
scroll_jank_percentage INT The percentage of janky frames relative to total frames.

chrome_causes_per_scroll, VIEW

Scroll jank causes per scroll.

Column Type Description
scroll_id INT The ID of the scroll.
max_delay_since_last_frame INT The maximum time a frame was delayed after the presentation of the previous frame.
vsync_interval INT The expected vsync interval.
scroll_jank_causes BYTES A proto amalgamation of each scroll jank cause including cause name, sub cause and the duration of the delay since the previous frame was presented.

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.

Argument Type Description
janky_slice_id LONG The slice id of the parent slice that we want to cause among it's children.
prev_slice_id LONG The slice id of the parent slice that's the reference in comparison to |janky_slice_id|.

chrome.scroll_jank.scroll_offsets

Views/Tables

chrome_deltas_presented_frame_scroll_update_ids, VIEW

All of the presented frame scroll update ids.

Column Type Description
scroll_update_id INT A scroll update id that was included in the presented frame. There may be zero, one, or more.
id INT Slice id

chrome_scroll_input_offsets, TABLE

The raw coordinates and pixel offsets for all input events which were part of a scroll. This includes input events that were converted to scroll events which were presented (_non_coalesced_scrolls) and scroll events which were coalesced (_coalesced_deltas).

Column Type Description
scroll_update_id INT Trace id associated with the scroll.
ts INT Timestamp the of the scroll input event.
delta_y INT The delta in raw coordinates between this scroll update event and the previous.
offset_y INT The pixel offset of this scroll update event compared to the previous one.

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.

Column Type Description
scroll_update_id INT Trace Id associated with the scroll.
ts INT Presentation timestamp.
delta_y INT The delta in coordinates as processed by Chrome between this scroll update event and the previous.
offset_y INT The pixel offset of this scroll update (the presented frame) compared to the previous one.

chrome.scroll_jank.utils

Functions

Argument Type Description

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.

Column Type Description
interface_name STRING Name of the interface of the IPC call.
ipc_hash INT Hash of the IPC call.
message_type STRING Message type (e.g. reply).
id INT The slice id.

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 sync is the time between the start and sync-end marks, async is the time between the sync-end and async-end marks.

Column Type Description
iteration INT Speedometer iteration the mark belongs to.
suite_name STRING Suite name
test_name STRING Test name
measure_type STRING Type of the measure (sync or async)
ts INT Start timestamp of the measure
dur INT Duration of the measure

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

Column Type Description
iteration INT Speedometer iteration.
ts INT Start timestamp of the iteration
dur INT Duration of the iteration
total INT Total duration of the measures in this iteration
mean INT Average suite duration for this iteration.
geomean INT Geometric mean of the suite durations for this iteration.
score INT Speedometer score for this iteration (The total score for a run in the average of all iteration scores).

chrome.startups

Views/Tables

chrome_startups, TABLE

Chrome startups, including launch cause.

Column Type Description
id INT Unique ID
activity_id INT Chrome Activity event id of the launch.
name STRING Name of the launch start event.
startup_begin_ts INT Timestamp that the startup occurred.
first_visible_content_ts INT Timestamp to the first visible content.
launch_cause STRING Launch cause. See Startup.LaunchCauseType in chrome_track_event.proto.
browser_upid INT Process ID of the Browser where the startup occurred.

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.

Column Type Description
filtered_name STRING Name of the view.
is_software_screenshot BOOL Whether this slice is a part of non-accelerated capture toolbar screenshot.
is_hardware_screenshot BOOL Whether this slice is a part of accelerated capture toolbar screenshot.
slice_id INT Slice id.

chrome_scheduler_tasks, VIEW

A list of tasks executed by Chrome scheduler.

Column Type Description
id INT Slice id.
type STRING Type.
name STRING Name of the task.
ts INT Timestamp.
dur INT Duration.
utid INT Utid of the thread this task run on.
thread_name STRING Name of the thread this task run on.
upid INT Upid of the process of this task.
process_name STRING Name of the process of this task.
track_id INT Same as slice.track_id.
category STRING Same as slice.category.
depth INT Same as slice.depth.
parent_id INT Same as slice.parent_id.
arg_set_id INT Same as slice.arg_set_id.
thread_ts INT Same as slice.thread_ts.
thread_dur INT Same as slice.thread_dur.
posted_from STRING Source location where the PostTask was called.

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.

Column Type Description
id INT Id for the given task, also the id of the slice this task corresponds to.
name STRING Name for the given task.
task_type STRING Type of the task (e.g. "scheduler").
thread_name STRING Thread name.
utid INT Utid.
process_name STRING Process name.
upid INT Upid.
ts INT Alias of |slice.ts|.
dur INT Alias of |slice.dur|.
track_id INT Alias of |slice.track_id|.
category INT Alias of |slice.category|.
arg_set_id INT Alias of |slice.arg_set_id|.
thread_ts INT Alias of |slice.thread_ts|.
thread_dur INT Alias of |slice.thread_dur|.
full_name STRING STRING Legacy alias for |name|.

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.

Column Type Description
slice_id INT Slice id of the vsync slice.
ts INT Timestamp of the vsync slice.
dur INT Duration of the vsync slice.
track_id INT Track id of the vsync slice.
time_to_next_vsync INT Duration until next vsync arrives.

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.

Argument Type Description
begin_ts LONG Interval start time.
end_ts LONG Interval end time.

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.

Column Type Description
id INT Unique id for this interaction.
ts INT Start timestamp of the event. Because multiple events may occur for the same interaction, this is the start timestamp of the longest event.
dur INT Duration of the event. Because multiple events may occur for the same interaction, this is the duration of the longest event.
interaction_type STRING The interaction type.
total_duration_ms INT The total duration of all events that occurred for the same interaction.
renderer_upid INT The process id this event occurred on.

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:

ts=0, value=10, track_id=1 ts=0, value=10, track_id=2 ts=10, value=10, track_id=1 ts=10, value=20, track_id=2 ts=20, value=30, track_id=1 [end of trace at ts = 40]

Then this macro will generate the following intervals:

ts=0, dur=20, value=10, track_id=1 ts=20, dur=10, value=30, track_id=1 ts=0, dur=10, value=10, track_id=2 ts=10, dur=30, value=20, track_id=2

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

Argument Type Description
counter_table TableOrSubquery A table/view/subquery corresponding to a "counter-like" table. This table must have the columns "id" and "ts" and "track_id" and "value" corresponding to an id, timestamp, counter track_id and associated counter value.

Module: cpu

cpu.cpus

Views/Tables

cpu_core_types, TABLE

All of the CPUs with their core type as a descriptive size ('little', 'mid', 'big', etc).

Column Type Description
cpu_index INT Index of the CPU.
size STRING A descriptive size ('little', 'mid', 'big', etc) or NULL if we have insufficient information.

cpu.freq

Views/Tables

cpu_freq_counters, TABLE

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

Column Type Description
id INT Counter id.
track_id INT Joinable with 'counter_track.id'.
ts LONG Starting timestamp of the counter
dur INT Duration in which counter is constant and frequency doesn't change.
freq INT Frequency in kHz of the CPU that corresponds to this counter. NULL if not found or undefined.
cpu INT CPU that corresponds to this counter.

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.

Column Type Description
id INT Counter id.
track_id INT Joinable with 'counter_track.id'.
ts LONG Starting timestamp of the counter.
dur INT Duration in which the counter is contant and idle state doesn't change.
idle INT Idle state of the CPU that corresponds to this counter. An idle state of -1 is defined to be active state for the CPU, and the larger the integer, the deeper the idle state of the CPU. NULL if not found or undefined.
cpu INT CPU that corresponds to this counter.

cpu.size

Functions

cpu_guess_core_type

Guess size of CPU. On some multicore devices the cores are heterogeneous and divided into two or more 'sizes'. In a typical case a device might have 8 cores of which 4 are 'little' (low power & low performance) and 4 are 'big' (high power & high performance). This functions attempts to map a given CPU index onto the relevant descriptor. For homogeneous systems this returns NULL.

Returns: STRING, A descriptive size ('little', 'mid', 'big', etc) or NULL if we have insufficient information.

Argument Type Description
cpu_index INT Index of the CPU whose size we will guess.

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:

CREATE PERFETTO VIEW dominator_compatible_heap_graph AS -- Extract the edges from the heap graph which correspond to references -- between objects. SELECT owner_id AS source_node_id, owned_id as dest_node_id FROM heap_graph_reference JOIN heap_graph_object owner on heap_graph_reference.owner_id = owner.id WHERE owned_id IS NOT NULL AND owner.reachable UNION ALL -- Since a Java heap graph is a "forest" structure, we need to add a dummy -- "root" node which connects all the roots of the forest into a single -- connected component. SELECT (SELECT max(id) + 1 FROM heap_graph_object) as source_node_id, id FROM heap_graph_object WHERE root_type IS NOT NULL; SELECT * FROM graph_dominator_tree!( dominator_compatible_heap_graph, (SELECT max(id) + 1 FROM heap_graph_object) );

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

Argument Type Description
graph_table TableOrSubquery A table/view/subquery corresponding to a directed flow-graph on which the dominator tree should be computed. This table must have the columns "source_node_id" and "dest_node_id" corresponding to the two nodes on either end of the edges in the graph. Note: the columns must contain uint32 similar to ids in trace processor tables (i.e. the values should be relatively dense and close to zero). The implementation makes assumptions on this for performance reasons and, if this criteria is not, can lead to enormous amounts of memory being allocated. Note: this means that the graph must be a single fully connected component with |root_node_id| (see below) being the "entry node" for this component. Specifically, all nodes must be reachable by following paths from the root node. Failing to adhere to this property will result in undefined behaviour. If working with a "forest"-like structure, a dummy node should be added which links all the roots of the forest together into a single component; an example of this can be found in the heap graph example query above.
root_node_id Expr The entry node to |graph_table| which will be the root of the dominator tree.

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 id | parent_id | group_key ---+-----------+-------- 1 | NULL | 1 2 | 1 | 1 3 | 2 | 2 4 | 2 | 2 5 | 4 | 1 6 | 4 | 3 7 | 4 | 2

Or as a graph: 1 (1) / 2 (1) /
3 (2) 4 (2)
5 (1) /
6 (3) 7 (2)

Possible output (order of rows is implementation-defined) id | parent_id | group_key ---+-----------+------- 1 | NULL | 1 2 | 1 | 1 3 | NULL | 2 4 | NULL | 2 5 | 2 | 1 6 | NULL | 3 7 | 4 | 2

Or as a forest: 1 (1) 3 (2) 4 (2) 6 (3) | | 2 (1) 7 (2) | 5 (1)

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

Argument Type Description
tree_table TableOrSubquery A table/view/subquery corresponding to a tree which should be partitioned. This table must have the columns "id", "parent_id" and "group_key". Note: the columns must contain uint32 similar to ids in trace processor tables (i.e. the values should be relatively dense and close to zero). The implementation makes assumptions on this for performance reasons and, if this criteria is not, can lead to enormous amounts of memory being allocated.

graphs.search

Macros

graph_reachable_dfs Computes the "reachable" set of nodes in a directed graph from a given starting node 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:

-- Compute the reachable nodes from the first heap root. SELECT * FROM graph_reachable_dfs!( ( SELECT owner_id AS source_node_id, owned_id as dest_node_id FROM heap_graph_reference WHERE owned_id IS NOT NULL ), (SELECT id FROM heap_graph_object WHERE root_type IS NOT NULL LIMIT 1) );

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.

Argument Type Description
graph_table TableOrSubquery A table/view/subquery corresponding to a directed graph on which the reachability search should be performed. This table must have the columns "source_node_id" and "dest_node_id" corresponding to the two nodes on either end of the edges in the graph. Note: the columns must contain uint32 similar to ids in trace processor tables (i.e. the values should be relatively dense and close to zero). The implementation makes assumptions on this for performance reasons and, if this criteria is not, can lead to enormous amounts of memory being allocated.
start_node_id Expr The start node to |graph_table| which will be the root of the reachability tree.

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:

-- Compute the next sibling: SELECT * FROM graph_next_sibling!( ( SELECT id AS node_id, parent_id AS node_parent_id, ts AS sort_key FROM slice ) );

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.

Argument Type Description
graph_table TableOrSubquery A table/view/subquery corresponding to a directed graph for which to find the next sibling. This table must have the columns "node_id", "node_parent_id" and "sort_key".

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:

-- Compute the reachable nodes from a sched wakeup chain INCLUDE PERFETTO MODULE sched.thread_executing_spans; SELECT * FROM graph_reachable_dfs_bounded !( ( SELECT id AS source_node_id, COALESCE(parent_id, id) AS dest_node_id, id - COALESCE(parent_id, id) AS edge_weight FROM _wakeup_chain ), ( SELECT id AS root_node_id, id - COALESCE(prev_id, id) AS root_target_weight FROM _wakeup_chain ));

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.

Argument Type Description
graph_table TableOrSubquery A table/view/subquery corresponding to a directed graph on which the reachability search should be performed. This table must have the columns "source_node_id" and "dest_node_id" corresponding to the two nodes on either end of the edges in the graph and an "edge_weight" corresponding to the weight of the edge between the node. Note: the columns must contain uint32 similar to ids in trace processor tables (i.e. the values should be relatively dense and close to zero). The implementation makes assumptions on this for performance reasons and, if this criteria is not, can lead to enormous amounts of memory being allocated.
root_table TableOrSubquery A table/view/subquery corresponding to start nodes to |graph_table| which will be the roots of the reachability trees. This table must have the columns "root_node_id" and "root_target_weight" corresponding to the starting node id and the max weight allowed on the tree. Note: the columns must contain uint32 similar to ids in trace processor tables (i.e. the values should be relatively dense and close to zero). The implementation makes assumptions on this for performance reasons and, if this criteria is not, can lead to enormous amounts of memory being allocated.
is_target_weight_floor Expr Whether the target_weight is a floor weight or ceiling weight. If it's floor, the search stops right after we exceed the target weight, and we include the node that pushed just passed the target. If ceiling, the search stops right before the target weight and the node that would have pushed us passed the target is not included.

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.

Argument Type Description
segments TableOrSubquery Table or subquery containing interval data.
ts_column ColumnName Column containing interval starts (usually ts).
dur_column ColumnName Column containing interval durations (usually dur).

Module: linux

linux.cpu_idle

Views/Tables

linux_cpu_idle_stats, TABLE

Aggregates cpu idle statistics per core.

Column Type Description
cpu INT CPU core number.
state INT CPU idle state (C-states).
count INT The count of entering idle state.
dur INT Total CPU core idle state duration in nanoseconds.
avg_dur INT Average CPU core idle state duration in nanoseconds.
idle_percent FLOAT Idle state percentage of non suspend time (C-states + P-states).

Module: memory

memory.heap_graph_dominator_tree

Views/Tables

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

Column Type Description
id INT Heap graph object id.
idom_id INT Immediate dominator object id of the object.
dominated_obj_count INT Count of all objects dominated by this object, self inclusive.
dominated_size_bytes INT Total self_size of all objects dominated by this object, self inclusive.
dominated_native_size_bytes INT Total native_size of all objects dominated by this object, self inclusive.
depth INT Depth of the object in the dominator tree. Depth of root objects are 1.

Functions

memory_heap_graph_super_root_fn

The assigned id of the "super root". Since a Java heap graph is a "forest" structure, we need to add a imaginary "super root" node which connects all the roots of the forest into a single connected component, so that the dominator tree algorithm can be performed.

Returns: INT, The assigned id of the "super root".

Module: pkvm

pkvm.hypervisor

Views/Tables

pkvm_hypervisor_events, VIEW

Events when CPU entered hypervisor.

Column Type Description
slice_id INT Id of the corresponding slice in slices table.
cpu INT CPU that entered hypervisor.
ts INT Timestamp when CPU entered hypervisor (in nanoseconds).
dur INT How much time CPU spent in hypervisor (in nanoseconds).
reason STRING Reason for entering hypervisor (e.g. host_hcall, host_mem_abort), or NULL if unknown.

Module: sched

sched.runnable

Views/Tables

sched_previous_runnable_on_thread, TABLE

Previous runnable slice on the same thread. For each "Running" thread state finds:

Column Type Description
id INT thread_state.id id.
prev_runnable_id INT Previous runnable thread_state.id.
prev_wakeup_runnable_id INT Previous runnable thread_state.id with valid waker thread.

sched.states

Functions

sched_state_to_human_readable_string

Translates a single-letter scheduling state to a human-readable string.

Returns: STRING, Humanly readable string representing the scheduling state of the kernel thread. The individual characters in the string mean the following: R (runnable), S (awaiting a wakeup), D (in an uninterruptible sleep), T (suspended), t (being traced), X (exiting), P (parked), W (waking), I (idle), N (not contributing to the load average), K (wakeable on fatal signals) and Z (zombie, awaiting cleanup).

Argument Type Description
short_name STRING An individual character string representing the scheduling state of the kernel thread at the end of the slice.

sched_state_io_to_human_readable_string

Translates a single-letter scheduling state and IO wait information to a human-readable string.

Returns: STRING, A human readable string with information about the scheduling state and IO wait.

Argument Type Description
sched_state STRING An individual character string representing the scheduling state of the kernel thread at the end of the slice.
io_wait BOOL A (posssibly NULL) boolean indicating, if the device was in uninterruptible sleep, if it was an IO sleep.

sched.thread_level_parallelism

Views/Tables

sched_runnable_thread_count, TABLE

The count of runnable threads over time.

Column Type Description
ts INT Timestamp when the runnable thread count changed to the current value.
runnable_thread_count INT Number of runnable threads, covering the range from this timestamp to the next row's timestamp.

sched_active_cpu_count, TABLE

The count of active CPUs over time.

Column Type Description
ts INT Timestamp when the number of active CPU changed.
active_cpu_count INT Number of active CPUs, covering the range from this timestamp to the next row's timestamp.

Functions

Argument Type Description

Table Functions

sched_active_cpu_count_for_core_type The count of active CPUs with a given core type over time.

core_type | STRING | Type of the CPU core as reported by GUESS_CPU_SIZE. Usually 'big', 'mid' or 'little'.

Column Type Description
ts LONG Timestamp when the number of active CPU changed.
active_cpu_count LONG Number of active CPUs, covering the range from this timestamp to the next row's timestamp.

sched.time_in_state

Views/Tables

sched_time_in_state_for_thread, TABLE

The time a thread spent in each scheduling state during it's lifetime.

Column Type Description
utid INT Utid of the thread.
total_runtime INT Total runtime of thread.
state STRING One of the scheduling states of kernel thread.
time_in_state INT Total time spent in the scheduling state.
percentage_in_state INT Percentage of time thread spent in scheduling state in [0-100] range.

sched_percentage_of_time_in_state, TABLE

Summary of time spent by thread in each scheduling state, in percentage ([0, 100] ranges). Sum of all states might be smaller than 100, as those values are rounded down.

Column Type Description
utid INT Utid of the thread.
running INT Percentage of time thread spent in running ('Running') state in [0, 100] range.
runnable INT Percentage of time thread spent in runnable ('R') state in [0, 100] range.
runnable_preempted INT Percentage of time thread spent in preempted runnable ('R+') state in [0, 100] range.
sleeping INT Percentage of time thread spent in sleeping ('S') state in [0, 100] range.
uninterruptible_sleep INT Percentage of time thread spent in uninterruptible sleep ('D') state in [0, 100] range.
other INT Percentage of time thread spent in other ('T', 't', 'X', 'Z', 'x', 'I', 'K', 'W', 'P', 'N') states in [0, 100] range.

Functions

Argument Type Description
Argument Type Description
-------- ---- -----------
Argument Type Description
-------- ---- -----------

Table Functions

sched_time_in_state_for_thread_in_interval Time the thread spent each state in a given interval.

ts | INT | The start of the interval. dur | INT | The duration of the interval. utid | INT | The utid of the thread.

Column Type Description
state INT Thread state (from the thread_state table). Use sched_state_to_human_readable_string function to get full name.
io_wait BOOL A (posssibly NULL) boolean indicating, if the device was in uninterruptible sleep, if it was an IO sleep.
blocked_function INT Some states can specify the blocked function. Usually NULL.
dur INT Total time spent with this state, cpu and blocked function.

sched_time_in_state_and_cpu_for_thread_in_interval Time the thread spent each state and cpu in a given interval.

ts | INT | The start of the interval. dur | INT | The duration of the interval. utid | INT | The utid of the thread.

Column Type Description
state INT Thread state (from the thread_state table). Use sched_state_to_human_readable_string function to get full name.
io_wait BOOL A (posssibly NULL) boolean indicating, if the device was in uninterruptible sleep, if it was an IO sleep.
cpu INT Id of the CPU. Use cpu_guess_core_type to get the CPU size (little/mid/big).
blocked_function INT Some states can specify the blocked function. Usually NULL.
dur INT Total time spent with this state, cpu and blocked function.

sched_time_in_state_for_cpu_in_interval Time spent by CPU in each scheduling state in a provided interval.

cpu | INT | CPU id. ts | INT | Interval start. dur | INT | Interval duration.

Column Type Description
end_state STRING End state. From sched.end_state.
dur INT Duration in state.

sched.utilization.process

Functions

Argument Type Description
Argument Type Description
-------- ---- -----------

Table Functions

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

Column Type Description
ts INT Timestamp of start of a second.
utilization DOUBLE Sum of average utilization over period. Note: as the data is normalized, the values will be in the [0, 1] range.
unnormalized_utilization DOUBLE Sum of average utilization over all CPUs over period. Note: as the data is unnormalized, the values will be in the [0, cpu_count] range.

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

Column Type Description
ts INT Timestamp of start of a second.
utilization DOUBLE Sum of average utilization over period. Note: as the data is normalized, the values will be in the [0, 1] range.
unnormalized_utilization DOUBLE Sum of average utilization over all CPUs over period. Note: as the data is unnormalized, the values will be in the [0, cpu_count] range.

sched.utilization.system

Views/Tables

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

Column Type Description
ts INT Timestamp of start of a second.
utilization DOUBLE Sum of average utilization over period. Note: as the data is normalized, the values will be in the [0, 1] range.
unnormalized_utilization DOUBLE Sum of average utilization over all CPUs over period. Note: as the data is unnormalized, the values will be in the [0, cpu_count] range.

Functions

Argument Type Description

Table Functions

sched_utilization_per_period Returns a table of system 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.

Column Type Description
ts INT Timestamp of start of a second.
utilization DOUBLE Sum of average utilization over period. Note: as the data is normalized, the values will be in the [0, 1] range.
unnormalized_utilization DOUBLE Sum of average utilization over all CPUs over period. Note: as the data is unnormalized, the values will be in the [0, cpu_count] range.

sched.utilization.thread

Functions

Argument Type Description
Argument Type Description
-------- ---- -----------

Table Functions

sched_thread_utilization_per_period Returns a table of thread 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. utid | INT | Utid of the thread.

Column Type Description
ts INT Timestamp of start of a second.
utilization DOUBLE Sum of average utilization over period. Note: as the data is normalized, the values will be in the [0, 1] range.
unnormalized_utilization DOUBLE Sum of average utilization over all CPUs over period. Note: as the data is unnormalized, the values will be in the [0, cpu_count] range.

sched_thread_utilization_per_second Returns a table of thread 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.

utid | INT | Utid of the thread.

Column Type Description
ts INT Timestamp of start of a second.
utilization DOUBLE Sum of average utilization over period. Note: as the data is normalized, the values will be in the [0, 1] range.
unnormalized_utilization DOUBLE Sum of average utilization over all CPUs over period. Note: as the data is unnormalized, the values will be in the [0, cpu_count] range.

Module: slices

slices.cpu_time

Views/Tables

thread_slice_cpu_time, TABLE

Time each thread slice spent running on CPU. Requires scheduling data to be available in the trace.

Column Type Description
id INT Slice id.
cpu_time INT Duration of the time the slice was running.

slices.with_context

Views/Tables

thread_slice, VIEW

All thread slices with data about thread, thread track and process. Where possible, use available view functions which filter this view.

Column Type Description
id INT Alias for slice.id.
type STRING Alias for slice.type.
ts INT Alias for slice.ts.
dur INT Alias for slice.dur.
category STRING Alias for slice.category.
name STRING Alias for slice.name.
track_id INT Alias for slice.track_id.
track_name STRING Alias for thread_track.name.
thread_name STRING Alias for thread.name.
utid INT Alias for thread.utid.
tid INT Alias for thread.tid
process_name STRING Alias for process.name.
upid INT Alias for process.upid.
pid INT Alias for process.pid.
depth INT Alias for slice.depth.
parent_id INT Alias for slice.parent_id.
arg_set_id INT Alias for slice.arg_set_id.
thread_ts INT Alias for slice.thread_ts.
thread_dur INT Alias for slice.thread_dur.

process_slice, VIEW

All process slices with data about process track and process. Where possible, use available view functions which filter this view.

Column Type Description
id INT Alias for slice.id.
type STRING Alias for slice.type.
ts INT Alias for slice.ts.
dur INT Alias for slice.dur.
category STRING Alias for slice.category.
name STRING Alias for slice.name.
track_id INT Alias for slice.track_id.
track_name STRING Alias for process_track.name.
process_name STRING Alias for process.name.
upid INT Alias for process.upid.
pid INT Alias for process.pid.
depth INT Alias for slice.depth.
parent_id INT Alias for slice.parent_id.
arg_set_id INT Alias for slice.arg_set_id.
thread_ts INT Alias for slice.thread_ts.
thread_dur INT Alias for slice.thread_dur.

Module: stack_trace

Module: time

time.conversion

Functions

time_from_ns

Returns the provided nanosecond duration, which is the default representation of time durations in trace processor. Provided for consistency with other functions.

Returns: INT, Time duration in nanoseconds.

Argument Type Description
nanos INT Time duration in nanoseconds.

time_from_us

Converts a duration in microseconds to nanoseconds, which is the default representation of time durations in trace processor.

Returns: INT, Time duration in nanoseconds.

Argument Type Description
micros INT Time duration in microseconds.

time_from_ms

Converts a duration in millseconds to nanoseconds, which is the default representation of time durations in trace processor.

Returns: INT, Time duration in nanoseconds.

Argument Type Description
millis INT Time duration in milliseconds.

time_from_s

Converts a duration in seconds to nanoseconds, which is the default representation of time durations in trace processor.

Returns: INT, Time duration in nanoseconds.

Argument Type Description
seconds INT Time duration in seconds.

time_from_min

Converts a duration in minutes to nanoseconds, which is the default representation of time durations in trace processor.

Returns: INT, Time duration in nanoseconds.

Argument Type Description
minutes INT Time duration in minutes.

time_from_hours

Converts a duration in hours to nanoseconds, which is the default representation of time durations in trace processor.

Returns: INT, Time duration in nanoseconds.

Argument Type Description
hours INT Time duration in hours.

time_from_days

Converts a duration in days to nanoseconds, which is the default representation of time durations in trace processor.

Returns: INT, Time duration in nanoseconds.

Argument Type Description
days INT Time duration in days.

time_to_ns

Returns the provided nanosecond duration, which is the default representation of time durations in trace processor. Provided for consistency with other functions.

Returns: INT, Time duration in nanoseconds.

Argument Type Description
nanos INT Time duration in nanoseconds.

time_to_us

Converts a duration in nanoseconds to microseconds. Nanoseconds is the default representation of time durations in trace processor.

Returns: INT, Time duration in microseconds.

Argument Type Description
nanos INT Time duration in nanoseconds.

time_to_ms

Converts a duration in nanoseconds to millseconds. Nanoseconds is the default representation of time durations in trace processor.

Returns: INT, Time duration in milliseconds.

Argument Type Description
nanos INT Time duration in nanoseconds.

time_to_s

Converts a duration in nanoseconds to seconds. Nanoseconds is the default representation of time durations in trace processor.

Returns: INT, Time duration in seconds.

Argument Type Description
nanos INT Time duration in nanoseconds.

time_to_min

Converts a duration in nanoseconds to minutes. Nanoseconds is the default representation of time durations in trace processor.

Returns: INT, Time duration in minutes.

Argument Type Description
nanos INT Time duration in nanoseconds.

time_to_hours

Converts a duration in nanoseconds to hours. Nanoseconds is the default representation of time durations in trace processor.

Returns: INT, Time duration in hours.

Argument Type Description
nanos INT Time duration in nanoseconds.

time_to_days

Converts a duration in nanoseconds to days. Nanoseconds is the default representation of time durations in trace processor.

Returns: INT, Time duration in days.

Argument Type Description
nanos INT Time duration in nanoseconds.

Module: v8

v8.jit

Views/Tables

v8_isolate, VIEW

A V8 Isolate instance. A V8 Isolate represents an isolated instance of the V8 engine.

Column Type Description
v8_isolate_id UINT Unique V8 isolate id.
upid UINT Process the isolate was created in.
internal_isolate_id UINT Internal id used by the v8 engine. Unique in a process.
embedded_blob_code_start_address LONG Absolute start address of the embedded code blob.
embedded_blob_code_size LONG Size in bytes of the embedded code blob.
code_range_base_address LONG Base address of the code range if the isolate defines one.
code_range_size LONG Size of a code range if the isolate defines one.
shared_code_range LONG Whether the code range for this Isolate is shared with others in the same process. There is at max one such shared code range per process.
embedded_blob_code_copy_start_address LONG Used when short builtin calls are enabled, where embedded builtins are copied into the CodeRange so calls can be nearer.

v8_js_script, VIEW

Represents a script that was compiled to generate code. Some V8 code is generated out of scripts and will reference a V8Script other types of code will not (e.g. builtins).

Column Type Description
v8_js_script_id UINT Unique V8 JS script id.
v8_isolate_id UINT V8 isolate this script belongs to (joinable with v8_isolate.v8_isolate_id).
internal_script_id UINT Script id used by the V8 engine.
script_type STRING Script type.
name STRING Script name.
source STRING Actual contents of the script.

v8_wasm_script, VIEW

Represents one WASM script.

Column Type Description
v8_wasm_script_id UINT Unique V8 WASM script id.
v8_isolate_id UINT V8 Isolate this script belongs to (joinable with v8_isolate.v8_isolate_id).
internal_script_id UINT Script id used by the V8 engine.
url STRING URL of the source.
source STRING Actual contents of the script.

v8_js_function, VIEW

Represents a v8 Javascript function.

Column Type Description
v8_js_function_id UINT Unique V8 JS function id.
name STRING Function name.
v8_js_script_id UINT Script where the function is defined (joinable with v8_js_script.v8_js_script_id).
is_toplevel BOOL Whether this function represents the top level script.
kind STRING Function kind (e.g. regular function or constructor).
line UINT Line in script where function is defined. Starts at 1.
col UINT Column in script where function is defined. Starts at 1.

Module: wattson

wattson.system_state

Views/Tables

wattson_system_states, TABLE

The final system state for the CPU subsystem, which has all the information needed by Wattson to estimate energy for the CPU subsystem.

Column Type Description
ts LONG Starting timestamp of the current counter where system state is constant.
dur INT Duration of the current counter where system state is constant.
l3_hit_count INT Number of L3 hits the current system state.
l3_miss_count INT Number of L3 misses in the current system state.
freq_0 INT Frequency of CPU0.
idle_0 INT Idle state of CPU0.
freq_1 INT Frequency of CPU1.
idle_1 INT Idle state of CPU1.
freq_2 INT Frequency of CPU2.
idle_2 INT Idle state of CPU2.
freq_3 INT Frequency of CPU3.
idle_3 INT Idle state of CPU3.
freq_4 INT Frequency of CPU4.
idle_4 INT Idle state of CPU4.
freq_5 INT Frequency of CPU5.
idle_5 INT Idle state of CPU5.
freq_6 INT Frequency of CPU6.
idle_6 INT Idle state of CPU6.
freq_7 INT Frequency of CPU7.
idle_7 INT Idle state of CPU7.
suspended BOOL Flag indicating if current system state is suspended.