Perfetto for Debian
===================

Perfetto Services
-----------------

The perfetto package installs two systemd services required for system-wide
tracing:

 * traced.service: The unprivileged central tracing service.
 * traced_probes.service: The privileged daemon for kernel data sources (e.g. ftrace).

These services are NOT started automatically upon installation.

To start them immediately and enable them on boot:
  $ sudo systemctl enable --now traced traced-probes

User Permissions (Recommended)
------------------------------

To record traces without `sudo` and avoid creating root-owned output files,
add your user to the `perfetto` group:

  $ sudo usermod -aG perfetto $USER

You must log out and log back in (or run `newgrp perfetto` in the current shell)
for this change to take effect.

Quickstart Workflows
--------------------

Ensure services are running (see above).
NOTE: These examples assume you have added your user to the `perfetto` group.
If not, you must prefix `perfetto` commands with `sudo`.

Workflow 1: Basic 10-second System Trace
Records CPU scheduling, frequency, idle states and power events for a fixed duration.

1. Record the trace:
   $ perfetto -o trace.pftrace -t 10s sched freq idle power

2. Analyze the trace:
   Open https://ui.perfetto.dev/ in your web browser, click "Open trace file",
   and select the resulting `trace.pftrace` file.
   (See "Analyzing Traces" below for more options).

Workflow 2: Background Tracing (Manual Start/Stop)
Use this when you don't know the exact duration beforehand. We use
`--background-wait` to ensure tracing is fully active before returning control.

1. Start recording in the background:
   $ perfetto -o background.pftrace --background-wait sched freq idle power

2. Perform the actions you want to capture on the system.

3. Stop recording safely:
   Simply killing the perfetto process can result in an incomplete trace file if
   it is still flushing data to disk. Use `inotifywait` to wait for the file
   to be fully written and closed:

   $ pkill -INT perfetto && inotifywait -e close_write background.pftrace

4. Analyze the trace:
   Open https://ui.perfetto.dev/ and load `background.pftrace`.
   (See "Analyzing Traces" below for more options).

Workflow 3: Advanced Trace with Configuration File
For complex traces (multiple data sources, specific buffer sizes), use a
text-based configuration file.

1. Create a configuration file (e.g., trace_config.pbtxt):

    duration_ms: 5000
    buffers: {
        size_kb: 63488
        fill_policy: DISCARD
    }
    data_sources: {
        config {
            name: "linux.ftrace"
            ftrace_config {
                ftrace_events: "sched/sched_switch"
                ftrace_events: "power/cpu_frequency"
            }
        }
    }

2. Run perfetto using this configuration:
   $ perfetto --txt -c trace_config.pbtxt -o advanced_trace.pftrace

3. Analyze the trace:
   See "Analyzing Traces" below.

Analyzing Traces
----------------

Beyond the standard Web UI, Perfetto provides advanced tools for programmatic
and SQL-based analysis of trace files.

* **Web UI**: The easiest method for visual inspection. Open
  https://ui.perfetto.dev/ in a browser and load your trace file.

* **Python API**: Best for automated analysis using Pandas/Dataframes.
  Install: `$ pip3 install perfetto`
  Usage:
    from perfetto.trace_processor import TraceProcessor
    tp = TraceProcessor(trace='trace.pftrace')
    for row in tp.query('SELECT ts, name FROM slice LIMIT 5'):
        print(row.ts, row.name)
  Details: https://perfetto.dev/docs/analysis/trace-processor-python

* **Trace Processor (Native Binary)**: High-performance interactive SQL shell.
  Usage:
    $ ./trace_processor trace.pftrace
    > SELECT ts, name FROM slice LIMIT 5;
  Details: https://perfetto.dev/docs/analysis/trace-processor

Documentation
-------------

* Main Website: https://perfetto.dev
* Trace Config Docs: https://perfetto.dev/docs/concepts/config