背景

在阅读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 的平台）：

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

# 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。

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

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

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

---

调试 GPU 性能

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

> 这个工作负载是 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):

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

# 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.

> 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.

> 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

相关skil的链接地址
https://github.com/google/perfetto/blob/main/ai/skills/README.md

看一下相关的README.md 内容如下：

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:

1. 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.
2. 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:

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:

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实战开发干货，请关注下面“千里马学框架”