Skip to content

Instantly share code, notes, and snippets.

@thimslugga

thimslugga/install-perfetto-on-fedora-al2023.md

Created July 10, 2026 14:12
Show Gist options

  • Select an option

    Learn more about clone URLs
  • Save thimslugga/0cc293de100b4d4857941feb27e201ad to your computer and use it in GitHub Desktop.

Select an option

Learn more about clone URLs
Save thimslugga/0cc293de100b4d4857941feb27e201ad to your computer and use it in GitHub Desktop.
Download ZIP
Install Perfetto on Fedora and Amazon Linux 2023
Raw
install-perfetto-on-fedora-al2023.md

Installing Perfetto on Fedora and Amazon Linux 2023

  • On Fedora, the simplest path is sudo dnf install perfetto (official RPM, currently perfetto-49.0-1.fc42 and perfetto-49.0-5.fc45 in Rawhide), which installs traced, traced_probes, the perfetto CLI, and ready-made systemd units.
  • On Amazon Linux 2023, there is no perfetto package in the core repos or SPAL, so download the prebuilt tracebox from get.perfetto.dev (a single statically linked binary) or build from source.
  • For trace analysis on either distro, download the trace_processor wrapper from get.perfetto.dev or python3 -m pip install perfetto; the AL2023 glibc (exactly glibc-2.34-52.amzn2023) meets the prebuilt trace_processor_shell requirement (GLIBC_2.34) with zero headroom.
  • Trace visualization uses ui.perfetto.dev, which processes the trace entirely in your browser (nothing is uploaded unless you click "Share", which only works for Googlers); you can self-host the same UI on any static web server.

Key Findings

What Perfetto is: separate components

Perfetto is not one tool but a suite. The pieces a non-Android Linux user cares about:

  • traced - the tracing service daemon (the "session daemon"). It owns the trace buffers and routes config from consumers to producers.
  • traced_probes - the producer that reads ftrace and polls /proc and /sys ("probes and ftrace-interop daemon").
  • perfetto - the command line consumer client that starts/stops a tracing session and writes the output file.
  • trace_processor_shell (aka trace_processor) - the SQLite-based query engine for analyzing traces offline; also serves the UI's backend over HTTP.
  • Perfetto UI - the web timeline viewer at ui.perfetto.dev; can be self-hosted.
  • tracebox - an all-in-one binary that bundles traced, traced_probes, the perfetto client, traced_relay, traced_perf, and more (like busybox/toybox). This is the easiest way to trace on a plain server.
  • Python bindings - the perfetto package on PyPI, providing the TraceProcessor Python API.
  • traceconv - trace format conversion tool (Perfetto to JSON, systrace, text, pprof, etc.).

The mental model: think of traced as a database server, traced_probes as a data-collecting agent that feeds it, and perfetto as the client that issues a "record this" command. tracebox is all three rolled into one, like a self-contained appliance.

Fedora: official RPM exists

Fedora ships an official perfetto package. As of this research it is version 49.0 (perfetto-49.0-1.fc42, and perfetto-49.0-5.fc45 in Rawhide), also packaged in Fedora 43 and 44. The Fedora changelog records the 49.0 import: "Update to 49.0 (fedora#2335926)" by Jonathan Steffan, dated 2025-01-18. The package installs:

  • /usr/bin/perfetto, /usr/bin/traced, /usr/bin/traced_probes
  • systemd units /usr/lib/systemd/system/traced.service and traced-probes.service
  • sysusers.d and tmpfiles.d config that create the traced user and the traced-consumer/traced-producer groups
  • example configs under /usr/share/perfetto/configs/ (scheduling.cfg, ftrace.cfg, sys_stats.cfg, and about two dozen others)
  • a man page perfetto.1

Note: the Fedora base perfetto package does not ship trace_processor_shell or tracebox (the RPM file list shows only perfetto, traced, traced_probes). For analysis you still grab trace_processor from get.perfetto.dev or PyPI. There are related packages perfetto-libs and perfetto-sdk.

Amazon Linux 2023: no package, use prebuilts or build

AL2023 does not carry perfetto in its core repos, and SPAL (Supplementary Packages for Amazon Linux, the EPEL9-derived repo that went GA on 2025-11-18) does not carry it either. AL2023 does not support the traditional EPEL. So on AL2023 you either download prebuilts or build from source.

Good news for prebuilts: tracebox is statically linked, so it runs regardless of AL2023's glibc. The trace_processor_shell prebuilt is dynamically linked and needs glibc >= 2.34; AL2023 ships exactly glibc-2.34-52.amzn2023, so it works, but with no margin.

For building from source, AL2023 has ninja-build (1.10.2) in the core repo, plus gcc/gcc-c++/python3/git, so a source build works. Perfetto's tools/install-build-deps fetches its own hermetic clang, gn, and ninja, so you do not strictly need system gn (which AL2023 lacks anyway).

Details

Prebuilt binaries from get.perfetto.dev

Three prebuilts are published behind https://get.perfetto.dev/:

  • https://get.perfetto.dev/tracebox - the all-in-one recording binary (native, statically linked)
  • https://get.perfetto.dev/trace_processor - a thin Python wrapper that downloads and caches the correct native trace_processor_shell under ~/.local/share/perfetto/prebuilts on first use
  • https://get.perfetto.dev/traceconv - a thin Python wrapper that similarly fetches the native traceconv binary

The underlying native binaries live at https://commondatastorage.googleapis.com/perfetto-luci-artifacts/vXX/linux-amd64/<binary> and .../linux-arm64/<binary>. GitHub releases (github.com/google/perfetto/releases) publish linux-amd64 and linux-arm64 tarballs containing the native binaries.

Install pattern (works on both distros):

# Recording binary (static, portable)
curl -LO https://get.perfetto.dev/tracebox
chmod +x tracebox
sudo mv tracebox /usr/local/bin/

# Analysis binary wrapper (needs python3 + network on first run)
curl -LO https://get.perfetto.dev/trace_processor
chmod +x trace_processor
sudo mv trace_processor /usr/local/bin/

The Python wrappers require Python 3 and download the native binary on first use. If you are offline or air-gapped, download the native trace_processor_shell directly from the commondatastorage.googleapis.com URL for your version and arch (for example .../v51.2/linux-amd64/trace_processor_shell).

glibc compatibility (critical for AL2023)

  • tracebox is described by Perfetto's docs as follows: "As per Perfetto v16, the tracebox binary bundles together all the binaries you need in a single statically linked executable (a bit like toybox or busybox), which makes it easy to copy and run on different machines." It therefore does not depend on the host glibc version, which is why it is the recommended way to copy Perfetto onto arbitrary machines.
  • trace_processor_shell and traceconv are dynamically linked. The current prebuilts require GLIBC_2.33 and GLIBC_2.34. This is documented in google/perfetto issue #937 ("tool traceconv and trace_processor can not find GLIBC_2.33 and GLIBC_2.34"), with the verbatim error: trace_processor_shell: /lib/x86_64-linux-gnu/libc.so.6: version 'GLIBC_2.33' not found ... version 'GLIBC_2.34' not found (required by ... trace_processor_shell). A Perfetto maintainer replied that systems older than glibc 2.33 (released 2021) cannot run the prebuilts and must build from source.
  • AL2023 ships glibc-2.34-52.amzn2023 (a core toolchain package supported through the AL2023 end-of-life of 2028-03-15), so the prebuilt trace_processor_shell runs. But this is exactly at the floor: if a future Perfetto release bumps the requirement to glibc 2.35+, AL2023 prebuilts would break, and you would fall back to pip install perfetto or building from source.
  • Fedora 42/43/44 all ship glibc newer than 2.34, so no issue there.

Building from source (both distros)

Steps are identical; only the prerequisite install command differs.

Fedora prerequisites:

sudo dnf install -y git python3 gcc gcc-c++ ninja-build

AL2023 prerequisites:

sudo dnf install -y git python3 gcc gcc-c++ tar gzip findutils ninja-build

Then:

git clone https://github.com/google/perfetto.git
cd perfetto
tools/install-build-deps
tools/gn gen --args='is_debug=false' out/linux
tools/ninja -C out/linux tracebox traced traced_probes perfetto trace_processor_shell traceconv

tools/install-build-deps downloads a hermetic clang toolchain plus prebuilt gn and ninja, so the build does not use the system compiler by default. The primary development repo moved to GitHub in March 2025; android.googlesource.com/platform/external/perfetto is now a read-only mirror. You can clone a specific tag with git clone --branch vXX.X --depth 1 https://github.com/google/perfetto.git.

For QEMU/virtualized environments, note that prebuilt and release binaries are built with aggressive optimizations; a default virtual CPU may throw illegal-instruction crashes, so pass -cpu host to QEMU.

Recording a trace on a plain x86_64 server

The fastest path uses tracebox in autostart mode (it starts and tears down traced/traced_probes for you):

# 10-second capture of scheduling switches
sudo tracebox -t 10s -o trace_file.perfetto-trace sched/sched_switch

With a config file (recommended for anything real). Edit with vi:

vi config.pbtx

Minimal config capturing ftrace scheduling plus process stats:

duration_ms: 10000
buffers {
  size_kb: 63488
  fill_policy: RING_BUFFER
}
data_sources {
  config {
    name: "linux.ftrace"
    ftrace_config {
      ftrace_events: "sched/sched_switch"
      ftrace_events: "sched/sched_wakeup"
      ftrace_events: "power/cpu_frequency"
    }
  }
}
data_sources {
  config {
    name: "linux.process_stats"
    process_stats_config {
      scan_all_processes_on_start: true
      proc_stats_poll_ms: 1000
    }
  }
}

Run it:

sudo tracebox -c config.pbtx --txt -o trace_file.perfetto-trace

The --txt flag tells tracebox the config is textproto rather than a binary protobuf. ftrace requires root (or CAP_SYS_ADMIN), so use sudo.

tracefs / ftrace on AL2023 EC2 instances

Perfetto's ftrace data source reads tracefs, normally mounted at /sys/kernel/tracing. The AL2023 kernel (the 6.1 and 6.12 LTS lines, sourced from kernel.org) is built with ftrace enabled, so tracefs is present. Verify and, if needed, mount:

# Check tracefs is available
grep tracefs /proc/filesystems
mount | grep tracefs

# Mount if not present
sudo mount -t tracefs tracefs /sys/kernel/tracing

On kernels before 4.1 the path was /sys/kernel/debug/tracing; AL2023 kernels are far newer so /sys/kernel/tracing applies. Recording ftrace requires root/CAP_SYS_ADMIN regardless of distro.

Verifying the install

tracebox --version
trace_processor --version

Then record a 10-second trace (above) and either:

  • Open ui.perfetto.dev, click "Open trace file", and load trace_file.perfetto-trace, or
  • Query locally:
trace_processor trace_file.perfetto-trace
> SELECT ts, dur, name FROM slice LIMIT 10;

The UI runs fully in-browser using JavaScript and WebAssembly. Per Perfetto's docs: "The Perfetto UI runs fully locally, in-browser using JavaScript + WebAssembly. The trace file is not uploaded anywhere by default, unless you explicitly click on the 'Share' link" - and the docs add that the Share link is available only to Googlers. This confirms the local-processing claim.

Self-hosting the Perfetto UI

If you do not want to use the hosted UI:

git clone https://github.com/google/perfetto.git
cd perfetto
tools/install-build-deps --ui
ui/build
# Dev server on http://localhost:10000
ui/run-dev-server

ui/build produces a static bundle in ui/out/dist/ that you can serve from any static web server (nginx, Apache, python3 -m http.server). The Perfetto team explicitly states the UI can be built and hosted on any static server. For very large traces, run trace_processor trace.pftrace --httpd (or the newer trace_processor server http) locally and the hosted or self-hosted UI will auto-detect the local instance on port 9001 and offload parsing to it, bypassing the browser's ~2GB WASM memory limit.

Systemd integration

The Fedora RPM ships traced.service and traced-probes.service plus sysusers/tmpfiles config out of the box, so on Fedora you just:

sudo systemctl enable --now traced traced-probes
perfetto -c config.pbtx --txt -o trace.perfetto-trace

On AL2023 (prebuilt or source), no unit files are installed, so write your own. The source tree contains reference init material, but for a server you typically author minimal units. Example (edit with vi):

/etc/systemd/system/traced.service:

[Unit]
Description=Perfetto tracing service
After=network.target

[Service]
ExecStart=/usr/local/bin/tracebox traced
Restart=on-failure
User=root

[Install]
WantedBy=multi-user.target

/etc/systemd/system/traced-probes.service:

[Unit]
Description=Perfetto ftrace/probes producer
After=traced.service
Requires=traced.service

[Service]
ExecStart=/usr/local/bin/tracebox traced_probes
Restart=on-failure
User=root

[Install]
WantedBy=multi-user.target

Then:

sudo systemctl daemon-reload
sudo systemctl enable --now traced traced-probes

When traced and traced_probes run as system services, use the plain perfetto consumer (or tracebox perfetto) rather than tracebox autostart, so it connects to the existing system sockets.

Python API

python3 -m pip install perfetto

The PyPI package is named perfetto (confirmed; it publishes 0.x releases). Basic usage:

from perfetto.trace_processor import TraceProcessor
tp = TraceProcessor(trace='trace_file.perfetto-trace')
for row in tp.query('SELECT ts, dur, name FROM slice LIMIT 10'):
    print(row.ts, row.dur, row.name)

It can also connect to a running trace_processor --httpd instance via TraceProcessor(addr='localhost:9001'), and results convert to a pandas DataFrame with .as_pandas_dataframe() (requires numpy and pandas). On AL2023 this is the more robust analysis path because the wrapper pairs with a matching binary and sidesteps the glibc-floor fragility of the standalone native shell.

Recommendations

  1. Fedora, quick start: sudo dnf install perfetto, then sudo systemctl enable --now traced traced-probes, record with the perfetto client, and add trace_processor from get.perfetto.dev for analysis. This gives you distro-maintained daemons and systemd units for free.
  2. AL2023, quick start (recommended): curl -LO https://get.perfetto.dev/tracebox && chmod +x tracebox && sudo mv tracebox /usr/local/bin/. Use tracebox autostart for ad-hoc traces. Add trace_processor for analysis; it works on glibc 2.34.
  3. AL2023 / AL2023-minimal containers: bake the static tracebox into the image (single binary, no glibc worries). For analysis inside the container, prefer pip install perfetto over the native shell to avoid the glibc-floor fragility. Ensure the container has access to the host's /sys/kernel/tracing and runs with sufficient privileges (CAP_SYS_ADMIN) to use ftrace.
  4. For a persistent tracing service on AL2023: write the two systemd units above. Switch to source-built binaries only if you need a specific version or hit a glibc-floor break in a future release.
  5. Analysis at scale or in scripts: use the Python perfetto package and its TraceProcessor SQL API; for multi-GB traces, run trace_processor --httpd and connect the UI to it.

Thresholds that change the recommendation: If a future Perfetto release requires glibc >= 2.35, stop using the native trace_processor_shell prebuilt on AL2023 and switch to pip install perfetto or a source build. If AWS adds perfetto to SPAL or the core repos, prefer the packaged version for its systemd integration. If you need the UI offline or internal, self-host the static bundle rather than depending on ui.perfetto.dev.

Common gotchas and troubleshooting

  • "Failed to connect to the traced socket" / "Unable to connect to the system tracing service as a consumer": the traced daemon is not running, or you are pointing at the wrong socket. With tracebox autostart this should not happen; with system services, ensure traced is up. Default sockets on Linux are /tmp/perfetto-producer and /tmp/perfetto-consumer, overridable via PERFETTO_PRODUCER_SOCK_NAME / PERFETTO_CONSUMER_SOCK_NAME.
  • tracebox autostart vs system daemon socket mismatch: tracebox autostart uses a private socket namespace by default (reported as @traced-p-NUMBER/@traced-c-NUMBER) to avoid clashing with a system traced. Pass --system-sockets to force it onto the standard system sockets if you need an SDK-instrumented app to connect to the same service.
  • Missing /sys/kernel/tracing: mount tracefs (see above) and confirm the kernel has ftrace (it does on AL2023 and Fedora).
  • Non-root permissions: ftrace needs root/CAP_SYS_ADMIN. To let a non-root user act as consumer/producer, traced supports --set-socket-permissions <prod_group>:<prod_mode>:<cons_group>:<cons_mode> to set socket group ownership and mode. The Fedora package creates traced-producer/traced-consumer groups for exactly this purpose.
  • GLIBC version errors on trace_processor_shell: means the host glibc is older than 2.34; build from source or use pip install perfetto. Not an issue on Fedora; on AL2023 it works but is at the floor.
  • Version skew: tracebox and trace_processor should ideally be the same Perfetto version. The trace format itself is forward/backward compatible (there is no version number in the file), and trace_processor imports older formats, so mild skew is usually fine, but match versions when debugging odd parsing.
  • Illegal instruction crashes under QEMU: pass -cpu host (prebuilts are compiled with optimizations for a modern CPU).
  • SELinux: Fedora runs SELinux enforcing; AL2023 runs SELinux permissive by default. On a plain Linux server (not Android) Perfetto is not confined by a dedicated SELinux policy the way it is on Android, so denials are uncommon, but if you relocate binaries or sockets and hit AVC denials, check ausearch -m avc and restore contexts with restorecon.

Alternatives and adjacent tooling

  • perf, bpftrace, bcc-tools are the classic Linux tracing/profiling stacks. bcc is available in AL2023 core (version 0.26.0).
  • Perfetto's trace_processor can ingest other formats, not just Perfetto traces: Linux perf.data, ftrace text, Chrome JSON (Trace Event Format), Firefox profiler format, and more. This means you can record with perf and still analyze/visualize in the Perfetto UI and SQL engine, or convert your own tracer's output to Chrome JSON (open it with the open_trace_in_ui helper) and view it in Perfetto.

Caveats

  • The "tracebox is statically linked" statement is Perfetto's own documentation wording; it was not independently verified here with ldd/file, though it is consistent with tracebox's stated portability.
  • The glibc 2.34 requirement for trace_processor_shell reflects the current release era; Perfetto's glibc floor has risen over time (it was around 2.28/2.29 in older releases), so AL2023 compatibility has essentially zero headroom.
  • The absence of perfetto and gn in AL2023 core repos and SPAL is a negative finding based on package-listing searches, not an explicit AWS statement of exclusion.
  • Fedora package version 49.0 is current as of this research; Fedora may update it. Check dnf info perfetto for the installed version.
  • The Fedora RPM file listing does not include trace_processor_shell or tracebox; if a future Fedora update adds them, prefer the packaged versions.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment