google官方Perfetto 中使用 AI相关skill

背景

在阅读Perfetto的官方文档时候发现有更新一个关于Perfetto使用ai分析的部分，这里把他进行转载分享一下。

在 Perfetto 中使用 AI

本文介绍如何在 Perfetto 中使用 AI 辅助 trace 分析，包括安装、临时 trace 分析、GPU 性能调试等。

Perfetto 为编程 Agent 提供了 agentskills.io 技能。它教会 Agent 如何调用 trace_processor、编写 PerfettoSQL、在 Android 上采集 trace，并按照指导工作流进行 Android 内存和 GPU 分析。每个安装包都捆绑了 trace_processor 包装器，因此不需要单独的二进制文件。

其设计在 RFC-0025 和 RFC-0026 中有描述。

安装

Agent	安装命令
Claude Code	`/plugin marketplace add google/perfetto@ai-agents`
Codex	`codex plugin marketplace add google/perfetto --ref ai-agents`
OpenCode	在 `opencode.json` 中添加：`"skills": { "urls": ["https://raw.githubusercontent.com/google/perfetto/ai-agents/plugins/perfetto/skills"] }`
其他（Antigravity、Cursor......）	使用下面的后备安装器

对于任何其他 Agent，使用后备安装器（任何带有 Python 3 的平台）：

bash 复制代码

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

bash 复制代码

# Windows（使用 curl.exe，而非 PowerShell 的 curl 别名）
curl.exe -fsSL https://get.perfetto.dev/agents-install | python - --target <path>

传入 --agent <claude|codex|opencode|antigravity|pi> 而非 --target，可安装到该 Agent 的默认目录中。

要在团队中共享此设置，将 --target 指向仓库中的按 Agent 目录（例如 .claude/skills/），并将结果提交。

安装结果

临时 trace 分析

提及一个 trace 文件并提出你的问题；Agent 会加载 trace、探查 schema，并为你编写 PerfettoSQL。

text 复制代码

> 加载 ~/traces/startup.pftrace，告诉我前两秒内哪些线程
  使用了最多的 CPU。

> 在 trace.pftrace 中找出 com.example.myapp 的不可中断
  睡眠的主要原因。

对于 Android 特定的工作流（内存泄漏调试、集群级 heap dump 聚类、trace 采集），参见"在 Android 实战指南中使用 AI"。

调试 GPU 性能

引导式工作流，回答"这个工作负载是 GPU 瓶颈还是主机瓶颈？"，然后深入分析问题所在的任一侧。目前最深入的 Counter 支持是 NVIDIA/CUDA。

text 复制代码

> 这个工作负载是 GPU 瓶颈还是主机瓶颈？trace 文件位于
  ~/traces/game.pftrace。

> GPU 看起来很忙但工作负载很慢。在 gpu.pftrace 中，
  时钟是否被降频或加速缓慢？

> 哪些 kernel 主导了这个 CUDA trace，它们是计算瓶颈还是
  内存瓶颈？

Agent 会盘点 GPU、将时间线分为繁忙与空闲时间（将空闲间隙归因于主机侧原因）、检查 DVFS 升频或热降频，对于计算工作负载还会根据硬件的计算和内存上限对 kernel 进行分类。

贡献

要编写或修改技能，请参见 ai/skills/README.md。

来源: 在 Perfetto 中使用 AI - Perfetto Tracing Docs - https://gugu-perf.github.io/perfetto-docs-zh-cn/docs/getting-started/using-ai.html

原始英文文档: Using AI in Perfetto - https://perfetto.dev/docs/getting-started/using-ai

英文原本部分

How to use AI-assisted trace analysis in Perfetto, including installation, ad-hoc trace analysis, and GPU performance debugging.

NOTE : Googlers: use go/perfetto-ai-skills and go/perfetto-ai-skills-android-memory instead of this page.

Perfetto ships an agentskills.io skill for coding agents. It teaches an agent to invoke trace_processor, write PerfettoSQL, record traces on Android, and follow guided workflows for Android memory and GPU analysis. Each install bundles a trace_processor wrapper, so no separate binary is needed.

The design is described in RFC-0025 and RFC-0026.

Install

Agent	Install
Claude Code	`/plugin marketplace add google/perfetto@ai-agents`
Codex	`codex plugin marketplace add google/perfetto --ref ai-agents`
OpenCode	Add to `opencode.json`: `"skills": { "urls": ["https://raw.githubusercontent.com/google/perfetto/ai-agents/plugins/perfetto/skills"] }`
Other (Antigravity, Cursor, ...)	Use the fallback installer (below)

For any other agent, use the fallback installer (any platform with Python 3):

bash 复制代码

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

bash 复制代码

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

Pass --agent <claude|codex|opencode|antigravity|pi> instead of --target to install into that agent's default directory.

To share the setup with your team, point --target at a per-agent directory in your repo (for example .claude/skills/) and commit the result.

Ad-hoc trace analysis

Mention a trace file and ask your question; the agent loads the trace, discovers the schema, and writes the PerfettoSQL for you.

text 复制代码

> Load ~/traces/startup.pftrace and tell me which threads used the most CPU
  in the first two seconds.

> Find the top causes of uninterruptible sleep for com.example.myapp in
  trace.pftrace.

For Android-specific workflows (memory leak debugging, fleet-wide heap dump clustering, trace recording), see "Using AI in the Android cookbook".

Debugging GPU performance

Guided workflows answering "is this workload GPU-bound or host-bound?", then drilling into whichever side is the problem. Deepest counter support is NVIDIA/CUDA today.

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?

The agent inventories the GPUs, splits the timeline into busy vs idle time (attributing idle gaps to host-side causes), checks for DVFS ramp or thermal throttling, and for compute workloads classifies kernels against the hardware's compute and memory ceilings.

Contributing

To author or modify a skill, see ai/skills/README.md.

Source: Using AI with Perfetto - Perfetto Tracing Docs - https://perfetto.dev/docs/getting-started/using-ai

Perfetto Skills

This directory holds a single skill : model-agnostic instructions

that teach an AI agent how to do something useful with Perfetto. A

skill is how Perfetto and the teams that use it encode the knowledge

an expert would share when sitting next to a colleague --- what to look

at, which tables to query, what good queries look like, and how to

interpret the results.

The format follows the Agent Skills

convention: a skill is a directory containing a SKILL.md with YAML

frontmatter (name, description) and a markdown body. Any tool that

implements the convention --- Claude Code, Gemini CLI, OpenAI Codex ---

can load it.

This is part of the ecosystem described in

RFC-0025: AI in Perfetto

and RFC-0026.

One skill, a router, and reusable files

Everything Perfetto ships is consolidated into one skill,

ai/skills/perfetto/. Its entry point is a lean router; the actual

knowledge lives in reference and workflow files the router dispatches

to and loads on demand. This keeps a single, broad description in

the agent's context budget instead of many sibling skills competing to

match, and lets each piece be loaded only when the task needs it.

复制代码

ai/skills/perfetto/
├── SKILL-template.md            # the router (see below --- NOT named SKILL.md)
├── infra-references/
│   └── querying.md              # how to run trace_processor + PerfettoSQL
├── environment-references/
│   └── setup.md                 # $SKILL_ROOT + the bundled trace_processor
└── workflows/
    └── android_memory/
        ├── heap_dump.md
        ├── heap_dump_cluster.md
        ├── heap_dump_caching_optimizer.md
        └── scripts/             # SQL/Python shipped with these workflows

Three kinds of file:

workflows/<domain>/*.md --- entry points the router dispatches
to : domain-specific guided investigations (a heap dump on Android,
jank on Chrome, ...). Group related workflows in a <domain>/
subfolder. A workflow is self-contained --- it carries its own queries
and any helper scripts under a sibling scripts/ dir.
infra-references/*.md --- domain-agnostic mechanics a workflow
(or an ad-hoc request) pulls in: how to query a trace, etc.
environment-references/*.md --- environment setup: what to set
$SKILL_ROOT to and how to invoke the bundled trace_processor.

The source tree is a build input, not a drop-in

Unlike a normal Agent Skill, this tree is not directly loadable.

Two source-only conventions mean it has to pass through the bundler

(tools/release/build_ai_agents.py) before any agent can load it:

SKILL-template.md, not SKILL.md. The router is named so a
discovery layer scanning for SKILL.md will not pick up the
unassembled source tree. The bundler renames it to SKILL.md.
No bin/trace_processor in source. The setup doc points every
trace_processor invocation at $SKILL_ROOT/bin/trace_processor,
but that wrapper is not checked in here --- the bundler copies it in
from tools/trace_processor at build time, so every install
(plugin or fallback) carries a working binary inside the skill.

Every agent gets the identical assembled skill. See

ai/extensions/README.md for how the

assembled bundle reaches end users.

Reference other files by `$SKILL_ROOT`-anchored path

Every path a file mentions --- links to other skill files, and the

helper scripts a workflow runs --- is written as $SKILL_ROOT/<path>,

where <path> is relative to the skill root (the directory holding

SKILL.md) and never relative to the file doing the referencing. So

from workflows/android_memory/heap_dump.md:

markdown 复制代码

follow `$SKILL_ROOT/infra-references/querying.md` first, then come back here.

Not ../../infra-references/querying.md (file-relative), and not a

bare infra-references/querying.md either. Likewise a helper script is

$SKILL_ROOT/workflows/android_memory/scripts/cluster_paths.py, and a

trace_processor invocation spells the full path:

sh 复制代码

trace_processor query --query-file \
  $SKILL_ROOT/workflows/android_memory/scripts/triage_dominator_path.sql TRACE_FILE

$SKILL_ROOT is the one anchor that makes this unambiguous. The skill

is loaded from a plugin/install directory that is not the agent's

working directory (that's the user's workspace, where the trace lives),

so a bare relative path would resolve against the wrong place.

environment-references/setup.md --- the always-required first read ---

tells the agent to set $SKILL_ROOT to the directory it loaded

SKILL.md from, and to put the bundled $SKILL_ROOT/bin on the

session's PATH so bare trace_processor commands work. Once it's set,

every $SKILL_ROOT/... path resolves the same way regardless of the

working directory, whether the agent is opening a referenced markdown

file or passing a script to the shell.

The router (SKILL-template.md) sits at the skill root, so its

$SKILL_ROOT/... links have no intermediate ../; every other file

speaks the same path language. A file can move between subfolders

without rewriting its outgoing links (only references to it change).

更多fw实战开发干货，请关注下面"千里马学框架"

google官方Perfetto 中使用 AI相关skill

背景

在 Perfetto 中使用 AI

安装

临时 trace 分析

调试 GPU 性能

贡献

英文原本部分

Install

Ad-hoc trace analysis

Debugging GPU performance

Contributing

Perfetto Skills

One skill, a router, and reusable files

The source tree is a build input, not a drop-in

Reference other files by $SKILL_ROOT-anchored path

Reference other files by `$SKILL_ROOT`-anchored path