Perfetto

https://perfetto.dev/docs
Admin
Perfetto is an open-source suite of SDKs, daemons, and tools for system and application tracing to...
Tokens:665,656
Snippets:4,332
Trust Score:9.3
Update:1 week ago
Show doc for...
Tokens:
Raw
### Start Linux recording with tracebox

Source: https://perfetto.dev/docs/getting-started/cpu-profiling

Starts a recording on Linux using the example config saved as /tmp/config.txtpb, outputting to /tmp/trace.pb. The trace can be opened in the Perfetto UI.

```bash
./tracebox -c /tmp/config.txtpb --txt -o /tmp/trace.pb
```

--------------------------------

### Start Android recording with record_android_trace

Source: https://perfetto.dev/docs/getting-started/cpu-profiling

Starts a recording on an Android device using the example config saved as /tmp/config.txtpb, outputting to /tmp/trace.pb. The recording stops after 10 seconds or with ctrl-c, and the script auto-opens the UI.

```bash
python3 record_android_trace -c /tmp/config.txtpb -o /tmp/trace.pb
```

--------------------------------

### Clone and setup Perfetto repository

Source: https://perfetto.dev/docs/contributing/getting-started

Clone the Perfetto repo, install dependencies (add --android to pull the Android NDK and emulator), and setup all build configs (add --android to generate Android build configs).

```bash
# Clone the Perfetto repo and enter the directory
git clone https://github.com/google/perfetto.git
cd perfetto

# Install dependencies
# Add --android to pull the Android NDK and emulator
tools/install-build-deps

# Setup all build configs
# Add --android to generate Android build configs
tools/setup_all_configs.py
```

--------------------------------

### server: HTTP, stdio, and unix RPC examples

Source: https://perfetto.dev/docs/reference/trace-processor-cli

Examples of starting trace_processor as an RPC server in HTTP, stdio, and unix modes, including pre-loading a trace, daemonizing, and killing a session.

```bash
# HTTP server, used by ui.perfetto.dev. Listens on port 9001 by default.
trace_processor server http 
# Pre-load a trace and serve it over HTTP.
trace_processor server http trace.pftrace 
# stdio server: length-prefixed RPC for tooling that embeds
# trace_processor as a subprocess.
trace_processor server stdio 
# Named unix-socket session: keeps the trace warm for repeated
# `query --remote <name>` calls (see the shell guide).
trace_processor server unix --name mysession --daemonize trace.pftrace 
# Stop a unix session by name or socket path.
trace_processor server kill mysession
```

--------------------------------

### Start dev server

Source: https://perfetto.dev/docs/contributing/ui-plugins

Starts the Perfetto UI dev server.

```bash
ui/run-dev-server
```

--------------------------------

### Build SDK examples with CMake

Source: https://perfetto.dev/docs/instrumentation/tracing-sdk

Build the SDK examples using CMake. Run these commands from the repository root after downloading or generating the SDK files.

```bash
cd examples/sdk
cmake -B build
cmake --build build
```

--------------------------------

### linux.process_stats configuration example

Source: https://perfetto.dev/docs/reference/traced_probes

Configuration for the linux.process_stats data source, enabling scanning all processes on start and setting a polling interval of 1000 ms.

```protobuf
data_sources: {
  config {
    name: "linux.process_stats"
    process_stats_config {
      scan_all_processes_on_start: true
      proc_stats_poll_ms: 1000
    }
  }
}
```

--------------------------------

### Install perfetto library

Source: https://perfetto.dev/docs/getting-started/converting

Install the perfetto Python library, which provides the necessary protobuf classes and builder utilities for generating traces.

```bash
pip install perfetto
```

--------------------------------

### Setup all configs if out directory is empty

Source: https://perfetto.dev/docs/contributing/common-tasks

If the out/ directory is empty, rerun tools/setup_all_configs.py to generate build configurations.

```bash
tools/setup_all_configs.py
```

--------------------------------

### Profile on Linux with heap_profile

Source: https://perfetto.dev/docs/instrumentation/heapprofd-api

Start a profile on Linux using heap_profile, protoc, and adb. Substitute $APP_NAME and $HEAP.

```bash
heap_profile android -n $APP_NAME --heaps $HEAP --print-config | \
 path/to/protoc --encode=perfetto.protos.TraceConfig perfetto_trace.proto | \
 adb shell perfetto -c - -o /data/misc/perfetto-traces/profile
```

--------------------------------

### Simple custom allocator example

Source: https://perfetto.dev/docs/instrumentation/heapprofd-api

A minimal custom allocator with my_malloc and my_free functions, used as a starting point for instrumentation.

```cpp
void* my_malloc(size_t size) {
  void* ptr = [code to somehow allocate get size bytes];
  return ptr;
}

void my_free(void* ptr) {
  [code to somehow free ptr]
}
```

--------------------------------

### Run tests on Android emulator

Source: https://perfetto.dev/docs/contributing/testing

Starts the built-in Android emulator after installing build dependencies. The emulator is supported on Linux and macOS.

```bash
tools/install-build-deps --android tools/run_android_emulator &
```

--------------------------------

### Install Perfetto AI skill with fallback installer (Windows)

Source: https://perfetto.dev/docs/getting-started/using-ai

Installs the Perfetto AI skill for any agent on Windows using the fallback installer. Requires Python 3. Use curl.exe, not the PowerShell curl alias. Use --target to specify the install directory or --agent to install into a specific agent's default directory.

```bash
# Windows (use curl.exe, not the PowerShell curl alias)
curl.exe -fsSL https://get.perfetto.dev/agents-install | python - --target <path>
```

--------------------------------

### Startup commands example: Pin CPU tracks and create a debug track

Source: https://perfetto.dev/docs/visualization/deep-linking-to-perfetto-ui

Pass startup commands in the startupCommands parameter as a URL-encoded JSON array. The commands execute automatically after the trace loads. This example pins CPU tracks and creates a debug track. The commands use the same JSON format as the UI automation documentation.

```javascript
// Example: Pin CPU tracks and create a debug track
const commands = [
  {id: 'dev.perfetto.PinTracksByRegex', args: ['.*CPU [0-3].*']},
  {
    id: 'dev.perfetto.AddDebugSliceTrack',
    args: [
      "SELECT ts, dur, name FROM slice WHERE name LIKE '%render%'",
      'Render Operations',
    ],
  },
];

const url = `https://ui.perfetto.dev/#!/?startupCommands=${encodeURIComponent(
  JSON.stringify(commands),
)}`;
```

--------------------------------

### GPU performance debugging prompts

Source: https://perfetto.dev/docs/getting-started/using-ai

Example prompts for guided GPU performance analysis. The agent inventories GPUs, splits timeline into busy vs idle time, checks for DVFS ramp or thermal throttling, and classifies kernels for compute workloads.

```text
> Is this workload GPU-bound or host-bound? The trace is at
  ~/traces/game.pftrace.
> The GPU looks busy but the workload is slow. Was the clock throttled or
  slow to ramp in gpu.pftrace?
> Which kernels dominate this CUDA trace, and are they compute-bound or
  memory-bound?
```

--------------------------------

### Install perfetto and pandas

Source: https://perfetto.dev/docs/analysis/batch-trace-processor

Install the perfetto Python library and its prerequisite pandas package using pip3.

```bash
pip3 install pandas       # prerequisite for Batch Trace Processor pip3 install perfetto
```

--------------------------------

### Start TraceProcessor server for UI acceleration

Source: https://perfetto.dev/docs/visualization/large-traces

Downloads and starts a native TraceProcessor server that the Perfetto UI can detect and use as an external accelerator. The UI probes http://127.0.0.1:9001 and prompts to use it via WebSocket. The classic --httpd invocation is still supported.

```bash
curl -LO https://get.perfetto.dev/trace_processor
chmod +x ./trace_processor
./trace_processor server http /path/to/trace.pftrace
```

--------------------------------

### linux.ftrace configuration example

Source: https://perfetto.dev/docs/reference/traced_probes

Configuration for the linux.ftrace data source, enabling ftrace events for sched_switch, cpu_idle, and sched_waking.

```protobuf
data_sources: {
  config {
    name: "linux.ftrace"
    ftrace_config {
      ftrace_events: "sched/sched_switch"
      ftrace_events: "power/cpu_idle"
      ftrace_events: "sched/sched_waking"
    }
  }
}
```

--------------------------------

### EXPERIMENTAL_PROFILE CPU profile example

Source: https://perfetto.dev/docs/analysis/builtin

Example of using EXPERIMENTAL_PROFILE with STACK_FROM_STACK_PROFILE_CALLSITE to generate a CPU profile. The query groups by perf_session_id and uses 'samples', 'count', and 1 as sample type, units, and value.

```sql
SELECT
  perf_session_id,
  EXPERIMENTAL_PROFILE(
    STACK_FROM_STACK_PROFILE_CALLSITE(callsite_id),
    'samples',
    'count',
    1) AS profile
FROM perf_sample
GROUP BY perf_session_id
```

--------------------------------

### Start tracing with Perfetto SDK (C++)

Source: https://perfetto.dev/docs/getting-started/in-app-tracing

Creates a trace configuration with a 1 MB buffer and a track_event data source, enabling only the 'rendering' category. Starts a tracing session and blocks until the trace is stopped. The tracing_session object must be kept alive for the duration of the trace.

```C++
// Create a trace configuration object. This is used to define the buffers,
// data sources, and other settings for the trace.
perfetto::TraceConfig cfg;

// Add a buffer to the config. Traces are written to this buffer in memory.
cfg.add_buffers()->set_size_kb(1024);  // 1 MB
// Add a data source to the config. This specifies what kind of data to
// collect. In this case, we're collecting track events.
auto* ds_cfg = cfg.add_data_sources()->mutable_config();
ds_cfg->set_name("track_event");

// Configure the track event data source. We can specify which categories of
// events to enable or disable.
perfetto::protos::gen::TrackEventConfig te_cfg;
te_cfg.add_disabled_categories("*");         // Disable all categories by default.
te_cfg.add_enabled_categories("rendering");  // Enable our "rendering" category.
ds_cfg->set_track_event_config_raw(te_cfg.SerializeAsString());

// Create a new tracing session.
std::unique_ptr<perfetto::TracingSession> tracing_session =
    perfetto::Tracing::NewTrace();

// Set up the tracing session with the configuration.
tracing_session->Setup(cfg);

// Start tracing. This will block until the trace is stopped.
tracing_session->StartBlocking();

// The tracing_session object must be kept alive for the duration of the
// trace.
// ...
```

--------------------------------

### linux.sysfs_power configuration example

Source: https://perfetto.dev/docs/reference/traced_probes

Configuration for the linux.sysfs_power data source, which does not have a specific configuration proto.

```protobuf
data_sources: {
  config {
    name: "linux.sysfs_power"
  }
}
```

--------------------------------

### Start traced_relay on guest

Source: https://perfetto.dev/docs/learning-more/multi-machine-tracing

Starts traced_relay on the guest, forwarding producer IPC frames to the host's relay endpoint. Expect a startup line like 'Started traced_relay, listening on /tmp/perfetto-producer, forwarding to <host-ip>:20001'.

```bash
PERFETTO_RELAY_SOCK_NAME=<host-ip>:20001 \
  tracebox traced_relay
```

--------------------------------

### Linux: Start background trace with perfetto

Source: https://perfetto.dev/docs/getting-started/periodic-trace-snapshots

Starts tracing using perfetto after ensuring traced and traced_probes are running. The --background flag returns immediately.

```bash
# Ensure traced and traced_probes are running, then:
perfetto -c snapshot_config.pbtxt --txt \
  --background -o /tmp/snapshot_bg
```

--------------------------------

### Linux: Start background trace with tracebox

Source: https://perfetto.dev/docs/getting-started/periodic-trace-snapshots

Starts tracing using tracebox with system sockets so later clone commands can connect. The --background flag returns immediately.

```bash
# tracebox starts traced and traced_probes automatically.
# --system-sockets lets later clone commands connect to this session.
./tracebox --system-sockets -c snapshot_config.pbtxt --txt \
  --background -o /tmp/snapshot_bg
```

--------------------------------

### Start docker-compose for Bigtrace

Source: https://perfetto.dev/docs/deployment/deploying-bigtrace-on-a-single-machine

Builds and starts containerised Orchestrator and Worker replicas using docker-compose. Use the standalone binary if needed.

```bash
cd infra/bigtrace/docker docker compose up # OR if using the docker compose standalone binary docker-compose up
```

--------------------------------

### Install Perfetto AI skill with fallback installer (macOS/Linux)

Source: https://perfetto.dev/docs/getting-started/using-ai

Installs the Perfetto AI skill for any agent on macOS or Linux using the fallback installer. Requires Python 3. Use --target to specify the install directory or --agent to install into a specific agent's default directory.

```bash
# macOS / Linux
curl -fsSL https://get.perfetto.dev/agents-install | python3 - --target <path>
```

--------------------------------

### CMake: Minimal build setup

Source: https://perfetto.dev/docs/getting-started/in-app-tracing

Basic CMake configuration for an executable that will be instrumented with Perfetto. Assumes the SDK files are in the perfetto/sdk folder.

```cmake
cmake_minimum_required(VERSION 3.13)
project(Example)

# Main executable
add_executable(example example.cc)
```

--------------------------------

### EXPERIMENTAL_PROFILE heap profile example

Source: https://perfetto.dev/docs/analysis/builtin

Example of using EXPERIMENTAL_PROFILE with CAT_STACKS and STACK_FROM_STACK_PROFILE_CALLSITE to generate a heap profile. The query filters allocations with size >= 0 and count >= 0, and includes both count and size sample types.

```sql
SELECT
  EXPERIMENTAL_PROFILE(
    CAT_STACKS(heap_name, STACK_FROM_STACK_PROFILE_CALLSITE(callsite_id)),
    'count',
    'count',
    count,
    'size',
    'bytes',
    size) AS profile
FROM heap_profile_allocation
WHERE size >= 0 AND count >= 0
```

--------------------------------

### Android: Push config and start background trace

Source: https://perfetto.dev/docs/getting-started/periodic-trace-snapshots

Pushes the config to the device and starts a background ring-buffer trace with perfetto. The --background flag returns immediately while tracing continues.

```bash
adb push snapshot_config.pbtxt /data/misc/perfetto-configs/
adb shell perfetto -c /data/misc/perfetto-configs/snapshot_config.pbtxt --txt \
  --background -o /data/misc/perfetto-traces/snapshot_bg
```

--------------------------------

### GN args example for Android

Source: https://perfetto.dev/docs/contributing/build-instructions

Example GN args to enter in the editor. Set target_os to 'android' only for Android builds; omit for linux, mac, or win. target_cpu can be 'arm', 'arm64', or 'x64'. is_debug is true or false. cc_wrapper is optional for ccache.

```gn
# Set only when building for Android, omit when building for linux, mac or win.
target_os = "android"
target_cpu = "arm" / "arm64" / "x64" 
is_debug = true / false
cc_wrapper = "ccache" # [Optional] speed up rebuilds with ccache.
```

--------------------------------

### Standard Analysis Setup

Source: https://perfetto.dev/docs/visualization/ui-automation

Comprehensive startup configuration that collapses all tracks, pins CPU tracks, expands frequency tracks, and creates a debug slice track with a pivot column for blocking functions.

```json
[   {     "id": "dev.perfetto.CollapseTracksByRegex",     "args": [".*"]   },   {     "id": "dev.perfetto.PinTracksByRegex",     "args": [".*CPU \\d+$"]   },   {     "id": "dev.perfetto.ExpandTracksByRegex",     "args": [".*freq.*"]   },   {     "id": "dev.perfetto.AddDebugSliceTrackWithPivot",     "args": [       "SELECT ts, blocked_function as name, dur FROM thread_state WHERE state = 'D' AND blocked_function IS NOT NULL",       "name",       "Blocking Functions"     ]   } ]
```

--------------------------------

### Get cold start reason for a process using UPID

Source: https://perfetto.dev/docs/getting-started/android-trace-analysis

Uses the android.app_process_starts module and time.conversion to get the cold start reason and intent for a specific UPID. The example uses upid = 844, which is a placeholder for the actual UPID obtained from the metadata query.

```sql
INCLUDE PERFETTO MODULE android.app_process_starts;
INCLUDE PERFETTO MODULE time.conversion;

SELECT
  process_name,
  upid,
  intent,
  reason,
  time_to_ms(total_dur)
FROM android_app_process_starts
WHERE upid = 844;
```

--------------------------------

### Wait for tracing session start

Source: https://perfetto.dev/docs/instrumentation/track-events

Example of using a session observer to wait for any tracing session to start, using a condition variable and the TrackEvent::IsEnabled() check.

```APIDOC
## Wait for tracing session start

### Description
Example of using a session observer to wait for any tracing session to start, using a condition variable and the TrackEvent::IsEnabled() check.

### Usage
```cpp
class Observer : public perfetto::TrackEventSessionObserver {
  public:
   Observer() { perfetto::TrackEvent::AddSessionObserver(this); }
   ~Observer() { perfetto::TrackEvent::RemoveSessionObserver(this); }

   void OnStart(const perfetto::DataSourceBase::StartArgs&) override {
     std::unique_lock<std::mutex> lock(mutex);
     cv.notify_one();
   }

   void WaitForTracingStart() {
     printf("Waiting for tracing to start...\n");
     std::unique_lock<std::mutex> lock(mutex);
     cv.wait(lock, [] { return perfetto::TrackEvent::IsEnabled(); });
     printf("Tracing started\n");
   }

   std::mutex mutex;
   std::condition_variable cv;
};

Observer observer;
observer.WaitForTracingStart();
```
```

--------------------------------

### Example TraceSummary output for memory_per_process template

Source: https://perfetto.dev/docs/analysis/trace-summary

Shows the structure of a TraceMetricV2Bundle with specs and rows for three metrics generated from a template.

```protobuf
# In TraceSummary's metric_bundles field:
metric_bundles {
  # The specs for all three metrics generated by the template.
  specs {
    id: "memory_per_process_min_rss_and_swap"
    dimensions: "process_name"
    value: "min_rss_and_swap"
    # ... query details ...
  }
  specs {
    id: "memory_per_process_max_rss_and_swap"
    dimensions: "process_name"
    value: "max_rss_and_swap"
    # ... query details ...
  }
  specs {
    id: "memory_per_process_avg_rss_and_swap"
    dimensions: "process_name"
    value: "avg_rss_and_swap"
    # ... query details ...
  }
  # Each row contains one set of dimensions and three values, corresponding
  # to the three metrics in `specs`.
  row {
    values { double_value: 100000 } # min
    values { double_value: 200000 } # max
    values { double_value: 123456.789 } # avg
    dimension { string_value: "com.example.app" }
  }
  row {
    values { double_value: 80000 } # min
    values { double_value: 150000 } # max
    values { double_value: 98765.432 } # avg
    dimension { string_value: "system_server" }
  }
  # ...
}
```

--------------------------------

### SwitchWorkspace command example

Source: https://perfetto.dev/docs/visualization/commands-automation-reference

Switches to an existing workspace by name. The workspace must exist before switching.

```json
{   "id": "dev.perfetto.SwitchWorkspace",   "args": ["Memory Analysis"] }
```

--------------------------------

### Initialize TraceProcessor with a trace file path

Source: https://perfetto.dev/docs/analysis/trace-processor-python

Initializes TraceProcessor with a trace file path, starting a new trace_processor instance.

```python
from perfetto.trace_processor import TraceProcessor

# Initialise TraceProcessor with a trace file path
tp = TraceProcessor(trace='trace.perfetto-trace')
```

--------------------------------

### CREATE PERFETTO MACRO examples

Source: https://perfetto.dev/docs/analysis/perfetto-sql-syntax

Examples of defining and using macros with no arguments, scalar arguments, and table arguments. Macros are expanded syntactically before execution. Note that simple constants and scalar functions are discouraged uses.

```sql
-- Create a macro taking no arguments. Note how the returned SQL fragment needs
-- to be wrapped in brackets to make it a valid SQL expression.
--
-- Note: this is a strongly discouraged use of macros as a simple SQL
-- function would also work here.
CREATE PERFETTO MACRO constant_macro() RETURNS Expr AS (SELECT 1);

-- Using the above macro. Macros are invoked by suffixing their names with !.
-- This is similar to how macros are invoked in Rust.
SELECT constant_macro!();

-- This causes the following SQL to be actually executed:
-- SELECT (SELECT 1);

-- A variant of the above. Again, strongly discouraged.
CREATE PERFETTO MACRO constant_macro_no_bracket() RETURNS Expr AS 2;

-- Using the above macro.
SELECT constant_macro_no_bracket!();

-- This causes the following SQL to be actually executed:
-- SELECT 2;

-- Creating a macro taking a single scalar argument and returning a scalar.
-- Note: again this is a strongly discouraged use of macros as functions can
-- also do this.
CREATE PERFETTO MACRO single_arg_macro(x Expr) RETURNS Expr AS (SELECT $x);
SELECT constant_macro!() + single_arg_macro!(100);

-- Creating a macro taking both a table and a scalar expression as an argument
-- and returning a table. Note again how the returned SQL statement is wrapped
-- in brackets to make it a subquery. This allows it to be used anywhere a
-- table or subquery is allowed.
--
-- Note: if tables are reused multiple times, it's recommended that they be
-- "cached" with a common-table expression (CTE) for performance reasons.
CREATE PERFETTO MACRO multi_arg_macro(x TableOrSubquery, y Expr) RETURNS TableOrSubquery AS (
  SELECT input_tab.input_col + $y
  FROM $x AS input_tab;
)
```

--------------------------------

### Profile on Windows with heap_profile

Source: https://perfetto.dev/docs/instrumentation/heapprofd-api

Start a profile on Windows using python, heap_profile, protoc, and adb. Requires Python 3.6 or later. Substitute %APP_NAME% and %HEAP%.

```bash
python /path/to/heap_profile android -n %APP_NAME% --heaps %HEAP% --print-config | ^
 path/to/protoc --encode=perfetto.protos.TraceConfig perfetto_trace.proto | ^
 adb shell perfetto -c - -o /data/misc/perfetto-traces/profile
```

--------------------------------

### Start native heap profiling with heap_profile android

Source: https://perfetto.dev/docs/getting-started/memory-profiling

Starts a native heap profile on an Android device using the android subcommand. The bare invocation without the subcommand is equivalent and kept for backwards compatibility.

```shell
python3 heap_profile android -n com.google.android.apps.nexuslauncher
```

--------------------------------

### Query process_slice view

Source: https://perfetto.dev/docs/analysis/perfetto-sql-getting-started

Use the process_slice view to get slices from process tracks with process context. This example filters by name LIKE 'MyEvent%'.

```sql
SELECT ts, dur, name, process_name, pid FROM process_slice WHERE name LIKE 'MyEvent%';
```

--------------------------------

### Periodic snapshots of com.example.app

Source: https://perfetto.dev/docs/reference/heap_profile-cli

Profiles com.example.app on Android with periodic 5-second snapshots using the -c flag.

```bash
tools/heap_profile android -n com.example.app -c 5000
```

--------------------------------

### Convert to pprof profile with output directory

Source: https://perfetto.dev/docs/quickstart/traceconv

Shows three example conversions to aggregated pprof profiles. The `profile` format writes one or more `.pb` files into a directory, so use `--output-dir` instead of a positional output path. Options include `--java-heap`, `--pid`, `--perf`, and `--timestamps`.

```bash
./trace_processor convert profile --output-dir ./profiles trace.perfetto-trace
```

```bash
./trace_processor convert profile --java-heap --pid 1234 --output-dir ./profiles trace.perfetto-trace
```

```bash
./trace_processor convert profile --perf --timestamps 1000000,2000000 --output-dir ./profiles trace.perfetto-trace
```

--------------------------------

### Query thread_slice view

Source: https://perfetto.dev/docs/analysis/perfetto-sql-getting-started

Use the thread_slice view to get slices from thread tracks with thread and process context. This example filters by name 'measure'.

```sql
SELECT ts, dur, name, thread_name, process_name, tid, pid FROM thread_slice WHERE name = 'measure';
```

--------------------------------

### Motivating example: ephemeral tab with command

Source: https://perfetto.dev/docs/contributing/ui-plugins

Shows a common pattern for ephemeral tabs: registering a command that creates and shows a new ephemeral tab. The tab is registered with a unique URI and shown immediately. The example includes a tab class, plugin registration, and a command handler.

```typescript
import m from 'mithril';
import {uuidv4} from '../../base/uuid';

class MyNameTab implements Tab {
  constructor(private name: string) {}
  render(): m.Children {
    return m('h1', `Hello, ${this.name}!`);
  }
  getTitle(): string {
    return 'My Name Tab';
  }
}

export default class implements PerfettoPlugin {
  static readonly id = 'com.example.MyPlugin';
  async onTraceLoad(trace: Trace): Promise<void> {
    trace.commands.registerCommand({
      id: 'com.example.MyPlugin#AddNewEphemeralTab',
      name: 'Add new ephemeral tab',
      callback: () => handleCommand(trace),
    });
  }
}

function handleCommand(trace: Trace): void {
  const name = prompt('What is your name');
  if (name) {
    const uri = `com.example.MyPlugin#MyName${uuidv4()}`;
    // This makes the tab available to perfetto
    trace.tabs.registerTab({
      isEphemeral: true,
      uri,
      content: new MyNameTab(name),
    });

    // This opens the tab in the tab bar
    trace.tabs.showTab(uri);
  }
}
```

--------------------------------

### linux.sys_stats configuration example

Source: https://perfetto.dev/docs/reference/traced_probes

Configuration for the linux.sys_stats data source, setting polling intervals for meminfo, vmstat, and stat.

```protobuf
data_sources: {
  config {
    name: "linux.sys_stats"
    sys_stats_config {
      meminfo_period_ms: 1000
      vmstat_period_ms: 1000
      stat_period_ms: 1000
    }
  }
}
```

--------------------------------

### TraceConfig with START_TRACING trigger and trigger_timeout_ms

Source: https://perfetto.dev/docs/concepts/config

Use this config to start tracing only when a trigger is hit. The trace stays idle until the trigger fires or the timeout expires. duration_ms cannot be used with triggered traces. The example starts recording when 'myapp_is_slow' is hit and stops after 5s, or ends after 30s if no trigger.

```protobuf
# If the "myapp_is_slow" is hit, the trace starts recording data and will be
# stopped after 5s.
trigger_config {
  trigger_mode: START_TRACING
  triggers {
    name: "myapp_is_slow"
    stop_delay_ms: 5000
  }
  # If no trigger is hit, the trace will end without having recorded any data
  # after 30s.
  trigger_timeout_ms: 30000
}

# The rest of the config is as usual.
buffers { ... }
data_sources { ... }
```

--------------------------------

### Run the devserver with ui/run-dev-server

Source: https://perfetto.dev/docs/contributing/ui-getting-started

Starts the devserver with live reload. Automatically builds the UI, so no need to run ui/build first. Navigate to http://localhost:10000/ to see changes. Restart the server if you made changes to Trace Processor.

```bash
# This will automatically build the UI. There is no need to manually run # ui/build before running ui/run-dev-server. ui/run-dev-server
```

--------------------------------

### Example: Building a Track Hierarchy

Source: https://perfetto.dev/docs/contributing/ui-plugins

Demonstrates how to create a TrackNode hierarchy, add child nodes, expand a group, and pin a track.

```APIDOC
## Example: Building a Track Hierarchy

### Description
Demonstrates how to create a TrackNode hierarchy, add child nodes, expand a group, and pin a track.

### Code Example
```javascript
// Assuming 'trace' is the Trace object and 'workspace' is trace.workspace
const parentGroup = new TrackNode({name: 'CPU Analysis'});
workspace.addChildLast(parentGroup);

const cpu0FreqTrack = new TrackNode({
  name: 'CPU 0 Frequency',
  uri: 'perfetto.CpuFrequency#cpu0', // Example URI
  sortOrder: 10,
});
parentGroup.addChildInOrder(cpu0FreqTrack);

const cpu1FreqTrack = new TrackNode({
  name: 'CPU 1 Frequency',
  uri: 'perfetto.CpuFrequency#cpu1', // Example URI
  sortOrder: 20,
});
parentGroup.addChildInOrder(cpu1FreqTrack);

parentGroup.expand(); // Show the CPU frequency tracks
cpu0FreqTrack.pin(); // Pin CPU 0 frequency track
```
```

--------------------------------

### Wait for any tracing session to start

Source: https://perfetto.dev/docs/instrumentation/track-events

Shows an Observer that registers itself with perfetto::TrackEvent::AddSessionObserver and provides a WaitForTracingStart method that blocks until tracing is enabled. The example creates an observer and calls WaitForTracingStart.

```cpp
class Observer : public perfetto::TrackEventSessionObserver {  public:   Observer() { perfetto::TrackEvent::AddSessionObserver(this); }   ~Observer() { perfetto::TrackEvent::RemoveSessionObserver(this); }    void OnStart(const perfetto::DataSourceBase::StartArgs&) override {     std::unique_lock<std::mutex> lock(mutex);     cv.notify_one();   }    void WaitForTracingStart() {     printf("Waiting for tracing to start...\n");     std::unique_lock<std::mutex> lock(mutex);     cv.wait(lock, [] { return perfetto::TrackEvent::IsEnabled(); });     printf("Tracing started\n");   }    std::mutex mutex;   std::condition_variable cv; };  Observer observer; observer.WaitForTracingStart();
```

--------------------------------

### Autostart mode general syntax

Source: https://perfetto.dev/docs/reference/tracebox

General syntax for using tracebox in autostart mode. It supports both simple and normal modes of perfetto's operation, plus a --system-sockets flag.

```text
tracebox [PERFETTO_OPTIONS] [TRACEBOX_OPTIONS] [EVENT_SPECIFIERS]
```

--------------------------------

### Get network bytes for a process using UID

Source: https://perfetto.dev/docs/getting-started/android-trace-analysis

Queries android_network_packets using a package_name in the format 'uid=$X' when package_name is not available. This example uses 'uid=12332' as a placeholder for the actual UID.

```sql
include perfetto module android.network_packets;

SELECT * FROM android_network_packets WHERE package_name = 'uid=12332';
```

--------------------------------

### Build and run Perfetto UI

Source: https://perfetto.dev/docs/contributing/getting-started

Build the Perfetto UI and run the dev server.

```bash
# Build the UI
ui/build

# Run the dev server
ui/run-dev-server
```

--------------------------------

### RunQueryAndShowTab command example

Source: https://perfetto.dev/docs/visualization/commands-automation-reference

Executes a PerfettoSQL query and displays results in a new query tab. The query is required; the title is optional.

```json
{   "id": "dev.perfetto.RunQueryAndShowTab",   "args": ["SELECT ts, dur, name FROM slice LIMIT 50"] }
```

--------------------------------

### graph_reachable_bfs: Compute reachable nodes from all heap roots

Source: https://perfetto.dev/docs/analysis/stdlib-docs

Example SQL query using the graph_reachable_bfs! macro on a heap graph. It selects edges from heap_graph_reference and start nodes from heap_graph_object where root_type is not null. The macro returns a table with columns node_id and parent_node_id.

```sql
-- Compute the reachable nodes from all heap roots.
SELECT * FROM graph_reachable_bfs!(
  (
    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)
);
```

--------------------------------

### Simple mode example: capture 10s trace of sched/sched_switch

Source: https://perfetto.dev/docs/reference/tracebox

Captures a 10-second trace of sched/sched_switch events in autostart mode. Output is written to trace_file.perfetto-trace.

```text
tracebox -t 10s -o trace_file.perfetto-trace sched/sched_switch
```

--------------------------------

### graph_reachable_dfs: Compute reachable nodes from heap roots

Source: https://perfetto.dev/docs/analysis/stdlib-docs

Example SQL query using the graph_reachable_dfs! macro on a heap graph. It selects edges from heap_graph_reference and start nodes from heap_graph_object where root_type is not null. The macro returns a table with columns node_id and parent_node_id.

```sql
-- 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)
);
```

--------------------------------

### Normal mode example: custom config file with tracebox

Source: https://perfetto.dev/docs/reference/tracebox

Creates a config.pbtx file with a 5-second trace of sched/sched_switch using a ring buffer, then runs tracebox with that config. The config is written via a heredoc and then passed to tracebox with --txt flag.

```text
cat <<EOF > config.pbtx
duration_ms: 5000
buffers {
  size_kb: 1024
  fill_policy: RING_BUFFER
}
data_sources {
  config {
    name: "linux.ftrace"
    ftrace_config {
      ftrace_events: "sched/sched_switch"
    }
  }
}
EOF

tracebox -c config.pbtx --txt -o custom_trace.perfetto-trace
```

--------------------------------

### TraceConfig with STOP_TRACING trigger for flight-recorder mode

Source: https://perfetto.dev/docs/concepts/config

Use this config to start tracing immediately and stop when a trigger is hit, enabling flight-recorder mode. The example stops after 1s when 'missed_frame' is hit, or ends after 30s if no trigger. Typically used with RING_BUFFER buffers.

```protobuf
# If the "missed_frame" is hit, the trace is stopped after 1s.
trigger_config {
  trigger_mode: STOP_TRACING
  triggers {
    name: "missed_frame"
    stop_delay_ms: 1000
  }
  # If no trigger is hit, the trace will end after 30s.
  trigger_timeout_ms: 30000
}

# The rest of the config is as usual.
buffers { ... }
data_sources { ... }
```

--------------------------------

### Run dumpsys meminfo on a process

Source: https://perfetto.dev/docs/case-studies/memory

Use adb shell dumpsys meminfo to get a high-level overview of memory usage for a specific process. The example targets com.android.systemui and shows the output including PSS, Private Dirty, and heap size columns.

```bash
$ adb shell dumpsys meminfo com.android.systemui
```

```text
 Applications Memory Usage (in Kilobytes):
Uptime: 2030149 Realtime: 2030149

** MEMINFO in pid 1974 [com.android.systemui] **
                    Pss  Private  Private  SwapPss      Rss     Heap     Heap     Heap
                  Total    Dirty    Clean    Dirty    Total     Size    Alloc     Free
                 ------   ------   ------   ------   ------   ------   ------   ------
   Native Heap    16840    16804        0     6764    19428    34024    25037     5553
   Dalvik Heap     9110     9032        0      136    13164    36444     9111    27333
  [more stuff...]
```

--------------------------------

### Create config.pbtx with heredoc and run record_android_trace

Source: https://perfetto.dev/docs/learning-more/android

Creates a trace config file using a bash heredoc and then runs record_android_trace with it. The config enables ftrace and process_stats data sources. Note: the --txt option is not available on Android P; use binary protobuf instead.

```bash
cat<<EOF>config.pbtx
duration_ms: 10000
buffers: {
    size_kb: 8960
    fill_policy: DISCARD
}
buffers: {
    size_kb: 1280
    fill_policy: DISCARD
}
data_sources: {
    config {
        name: "linux.ftrace"
        ftrace_config {
            ftrace_events: "sched/sched_switch"
            ftrace_events: "power/suspend_resume"
            ftrace_events: "sched/sched_process_exit"
            ftrace_events: "sched/sched_process_free"
            ftrace_events: "task/task_newtask"
            ftrace_events: "task/task_rename"
            ftrace_events: "ftrace/print"
            atrace_categories: "gfx"
            atrace_categories: "view"
            atrace_categories: "webview"
            atrace_categories: "camera"
            atrace_categories: "dalvik"
            atrace_categories: "power"
        }
    }
}
data_sources: {
    config {
        name: "linux.process_stats"
        target_buffer: 1
        process_stats_config {
            scan_all_processes_on_start: true
        }
    }
}
EOF
./record_android_trace -c config.pbtx -o trace_file.perfetto-trace
```

--------------------------------

### Register and use a feature flag in a Perfetto plugin

Source: https://perfetto.dev/docs/contributing/ui-plugins

Example plugin that registers a feature flag 'enableExperimentalTracks' in onActivate and checks it in onTraceLoad. The flag is devOnly and defaults to false. The register method returns a Flag object with get, set, isOverridden, reset, and overriddenState methods.

```typescript
import {Flag, FlagSettings} from '../../public/feature_flag'; // Adjust path as needed
import {App} from '../../public/app';
import {PerfettoPlugin} from '../../public/plugin';
import {Trace} from '../../public/trace';

export default class MyFeatureFlagPlugin implements PerfettoPlugin {
  static readonly id = 'com.example.MyFeatureFlagPlugin';
  private static enableExperimentalTracks: Flag;

  static onActivate(app: App): void {
    // Register a feature flag to control experimental tracks
    this.enableExperimentalTracks = app.featureFlags.register({
      id: `${this.id}#enableExperimentalTracks`,
      name: 'Enable Experimental Memory Tracks',
      defaultValue: false,
      description:
        'Enables experimental memory analysis tracks that show detailed heap allocations and memory pressure events. These tracks are under active development.',
      devOnly: true, // Only visible in development builds
    });

    // Register a command that's only available when the flag is enabled
    if (this.enableExperimentalTracks.get()) {
      app.commands.registerCommand({
        id: `${this.id}#analyzeMemoryLeaks`,
        name: 'Analyze potential memory leaks',
        callback: () => console.log('Running experimental leak detection...'),
      });
    }
  }

  async onTraceLoad(trace: Trace): Promise<void> {
    // Only add experimental tracks if the feature flag is enabled
    if (MyFeatureFlagPlugin.enableExperimentalTracks.get()) {
      // ... add the track ...
    }
  }
}
```

--------------------------------

### SQL query to retrieve Android logs

Source: https://perfetto.dev/docs/data-sources/android-log

Query the android_logs table joined with thread and process tables to get timestamp, thread id, process id, process name, priority, tag, and message. The output shows example rows with columns ts, tid, pid, process, prio, tag, msg.

```sql
select l.ts, t.tid, p.pid, p.name as process, l.prio, l.tag, l.msg from android_logs as l left join thread as t using(utid) left join process as p using(upid)
```

--------------------------------

### Convert to JSON, systrace, and text formats

Source: https://perfetto.dev/docs/quickstart/traceconv

Shows three example conversions: to Chrome JSON format, to systrace HTML, and to protobuf text format. Each command takes an input trace and writes to an output file.

```bash
./trace_processor convert json     trace.perfetto-trace trace.json
```

```bash
./trace_processor convert systrace trace.perfetto-trace trace.html
```

```bash
./trace_processor convert text     trace.perfetto-trace trace.textproto
```

--------------------------------

### Python Example: Merging by Key

Source: https://perfetto.dev/docs/reference/synthetic-track-event

Demonstrates how to create two tracks with different names but the same sibling_merge_key and merge them by setting sibling_merge_behavior to SIBLING_MERGE_BEHAVIOR_BY_SIBLING_MERGE_KEY.

```APIDOC
## Python Example: Merging by Key

### Description
Creates two tracks with different names but the same `sibling_merge_key` and sets their `sibling_merge_behavior` to `SIBLING_MERGE_BEHAVIOR_BY_SIBLING_MERGE_KEY` to instruct the UI to merge them into a single visual track.

### Code
```python
TRUSTED_PACKET_SEQUENCE_ID = 9004

# --- Define Track UUIDs ---
track1_uuid = 1
track2_uuid = 2

# Helper to define a TrackDescriptor
def define_custom_track(track_uuid, name, merge_key):
    packet = builder.add_packet()
    desc = packet.track_descriptor
    desc.uuid = track_uuid
    desc.name = name
    desc.sibling_merge_behavior = TrackDescriptor.SIBLING_MERGE_BEHAVIOR_BY_SIBLING_MERGE_KEY
    desc.sibling_merge_key = merge_key

# 1. Define the tracks with the same merge key
define_custom_track(track1_uuid, "HTTP GET", "conn-123")
define_custom_track(track2_uuid, "HTTP POST", "conn-123")

# Helper to add a slice event
def add_slice_event(ts, event_type, event_track_uuid, name=None):
    packet = builder.add_packet()
    packet.timestamp = ts
    packet.track_event.type = event_type
    packet.track_event.track_uuid = event_track_uuid
    if name:
        packet.track_event.name = name
    packet.trusted_packet_sequence_id = TRUSTED_PACKET_SEQUENCE_ID

# 2. Add events to the tracks
add_slice_event(ts=1000, event_type=TrackEvent.TYPE_SLICE_BEGIN, event_track_uuid=track1_uuid, name="GET /data")
add_slice_event(ts=1100, event_type=TrackEvent.TYPE_SLICE_END, event_track_uuid=track1_uuid)

add_slice_event(ts=1200, event_type=TrackEvent.TYPE_SLICE_BEGIN, event_track_uuid=track2_uuid, name="POST /submit")
add_slice_event(ts=1300, event_type=TrackEvent.TYPE_SLICE_END, event_track_uuid=track2_uuid)
```
```

--------------------------------

### Record Android trace with UI startup commands

Source: https://perfetto.dev/docs/visualization/ui-automation

Use this command to record an Android trace and automatically run UI startup commands when the trace opens. The commands pin tracks matching a regex and add a debug slice track with a pivot. All arguments must be strings.

```bash
./record_android_trace \
  --app com.example.app \
  --ui-startup-commands '[
    {"id":"dev.perfetto.PinTracksByRegex","args":[".*CPU.*"]},
    {"id":"dev.perfetto.AddDebugSliceTrackWithPivot","args":["SELECT ts, thread.name, dur FROM thread_state JOIN thread USING(utid) WHERE state = \"R\"","name","Runnable Time"]}
  ]'
```

--------------------------------

### Python: Define tracks and add asynchronous slice events

Source: https://perfetto.dev/docs/getting-started/converting

Use this Python code inside the populate_packets(builder) function of trace_converter_template.py to create multiple tracks with a common name (ASYNC_TRACK_GROUP_NAME) and add overlapping begin/end slice events. Each connection gets its own track with a unique UUID, and the common name groups them in the UI. The example defines three overlapping network connections with timestamps.

```python
# Common name for all individual connection tracks for UI grouping
    ASYNC_TRACK_GROUP_NAME = "HTTP Connections"
    # Helper to define a new track with a unique UUID
    def define_track(group_name):
        track_uuid = get_uuid()
        packet = builder.add_packet()
        packet.track_descriptor.uuid = track_uuid
        packet.track_descriptor.name = group_name
        return track_uuid

    # Helper to add a begin or end slice event to a specific track
    def add_slice_event(ts, event_type, event_track_uuid, name=None):
        packet = builder.add_packet()
        packet.timestamp = ts
        packet.track_event.type = event_type
        packet.track_event.track_uuid = event_track_uuid
        if name:
            packet.track_event.name = name
        packet.trusted_packet_sequence_id = TRUSTED_PACKET_SEQUENCE_ID

    # --- Network Connection 1 ---
    conn1_track_uuid = define_track(ASYNC_TRACK_GROUP_NAME)
    add_slice_event(ts=1000, event_type=TrackEvent.TYPE_SLICE_BEGIN, event_track_uuid=conn1_track_uuid, name="GET /data/config")
    add_slice_event(ts=1500, event_type=TrackEvent.TYPE_SLICE_END, event_track_uuid=conn1_track_uuid)

    # --- Network Connection 2 (Overlapping with Connection 1) ---
    conn2_track_uuid = define_track(ASYNC_TRACK_GROUP_NAME)
    add_slice_event(ts=1100, event_type=TrackEvent.TYPE_SLICE_BEGIN, event_track_uuid=conn2_track_uuid, name="POST /submit/form")
    add_slice_event(ts=2000, event_type=TrackEvent.TYPE_SLICE_END, event_track_uuid=conn2_track_uuid)

    # --- Network Connection 3 (Starts after 1 ends, overlaps with 2) ---
    conn3_track_uuid = define_track(ASYNC_TRACK_GROUP_NAME)
    add_slice_event(ts=1600, event_type=TrackEvent.TYPE_SLICE_BEGIN, event_track_uuid=conn3_track_uuid, name="GET /status/check")
    add_slice_event(ts=2200, event_type=TrackEvent.TYPE_SLICE_END, event_track_uuid=conn3_track_uuid)
```

--------------------------------

### Configure startup commands in iframe src

Source: https://perfetto.dev/docs/visualization/embedding-the-ui

Builds the iframe src URL with a URL-encoded JSON array of startup commands. The example pins CPU tracks using the command 'dev.perfetto.PinTracksByRegex'.

```javascript
const commands = [
  {id: 'dev.perfetto.PinTracksByRegex', args: ['.*CPU [0-3].*']},
];
const src =
  'https://ui.perfetto.dev/#!/?mode=embedded&startupCommands=' +
  encodeURIComponent(JSON.stringify(commands));
```

--------------------------------

### Install debug symbols on Fedora

Source: https://perfetto.dev/docs/learning-more/symbolization

Install debug symbols for a package on Fedora. The package is found with rpm -qf <path> and installed to /usr/lib/debug where it is found automatically.

```bash
dnf debuginfo-install <package>
```

--------------------------------

### Install debug symbols on Debian/Ubuntu

Source: https://perfetto.dev/docs/learning-more/symbolization

Install debug symbols for a package on Debian/Ubuntu. The package is found with dpkg -S <path> and installed to /usr/lib/debug where it is found automatically.

```bash
apt install <package>-dbgsym
```

--------------------------------

### Start workers command

Source: https://perfetto.dev/docs/design-docs/continuous-integration

Command to start the CI workers on GCE. Run from the repository root.

```bash
make -C /infra/ci start-workers
```
Tokens:
Raw