Extending the Perfetto UI

Perfetto offers several ways to extend and customize the UI. The right choice depends on what you want to do and who you want to share it with.

Which approach should I use?

graph TD Start["How do I extend the Perfetto UI?"] Q1{"Do you want simple things?
(queries, pinning tracks,
selecting events, etc.)"} Start --> Q1 Q2{"For yourself or
to share with others?"} Q3{"Are you OK contributing
your changes upstream?"} Q1 -->|Yes| Q2 Q1 -->|No| Q3 Out1["Use Macros +
Startup Commands"] Out2["Use Extension Servers"] Q2 -->|For myself| Out1 Q2 -->|To share| Out2 Out3["Contribute a
UI Plugin Upstream"] Q4{"Do you work
at Google?"} Q3 -->|Yes| Out3 Q3 -->|No| Q4 Out4["Please speak to us"] Out5["Fork Perfetto &
maintain your own instance"] Q4 -->|Yes| Out4 Q4 -->|No| Out5 Out6["Use Plugins for
UI-affecting changes"] Out7["Use Embedder for
central infra
(analytics, branding, etc.)"] Out5 --> Out6 Out5 --> Out7 click Out1 "/docs/visualization/ui-automation" "Commands and Macros" click Out2 "/docs/visualization/extension-servers" "Extension Server Setup" click Out3 "/docs/contributing/ui-plugins" "UI Plugins" click Out4 "https://github.com/google/perfetto/issues" "Open an issue" click Out6 "/docs/contributing/ui-plugins" "UI Plugins" %% Styling style Start fill:#6b9ae8,color:#fff,stroke:none style Q1 fill:#ece5ff,stroke:#d0c4eb,color:#333 style Q2 fill:#ece5ff,stroke:#d0c4eb,color:#333 style Q3 fill:#ece5ff,stroke:#d0c4eb,color:#333 style Q4 fill:#ece5ff,stroke:#d0c4eb,color:#333 style Out1 fill:#36a265,color:#fff,stroke:none style Out2 fill:#36a265,color:#fff,stroke:none style Out3 fill:#36a265,color:#fff,stroke:none style Out4 fill:#ece5ff,stroke:#d0c4eb,color:#333 style Out5 fill:#ece5ff,stroke:#d0c4eb,color:#333 style Out6 fill:#ef991c,color:#fff,stroke:none style Out7 fill:#ef991c,color:#fff,stroke:none

Commands, startup commands, and macros

Commands are individual UI actions (pin a track, run a query, create a debug track). Startup commands run automatically every time you open a trace. Macros are named sequences of commands you trigger manually from the command palette.

These are configured locally in Settings and are the simplest way to customize your own workflow. No server or sharing infrastructure needed.

See Commands and Macros for how to set these up, and the Commands Automation Reference for the full list of available commands.

Extension servers

Extension servers are HTTP(S) endpoints that distribute macros, SQL modules, and proto descriptors to the Perfetto UI. They are the recommended way for teams to share reusable trace analysis workflows — instead of everyone copy-pasting JSON, you host extensions on a server and anyone with access can load them.

The easiest way to get started is to fork a GitHub template repository and push your extensions there. The Perfetto UI can load directly from GitHub repos.

See Extension Servers for how they work and how to set one up.

Plugins

Plugins are TypeScript modules that run inside the Perfetto UI and can add new tracks, tabs, commands, and visualizations. Unlike macros and extension servers (which are declarative), plugins can execute code and deeply integrate with the UI.

If you want to contribute a plugin upstream, see UI Plugins.

Forking Perfetto

If you need changes that go beyond what plugins, macros, and extension servers offer — such as custom branding, analytics integration, or deep infrastructure changes — you can fork Perfetto and maintain your own instance. Within a fork, you can use the embedder API for central infrastructure concerns (analytics, branding) and plugins for UI-affecting changes.