Skip to content

Commit 7de22ca

Browse files
GrackerGracker
committed
docs: catalog reproducible trace cases
1 parent cb02107 commit 7de22ca

10 files changed

Lines changed: 1047 additions & 1 deletion

File tree

‎.github/workflows/verify.yml‎

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
name: Verify trace catalog
2+
3+
on:
4+
push:
5+
branches: [master]
6+
pull_request:
7+
workflow_dispatch:
8+
9+
permissions:
10+
contents: read
11+
12+
jobs:
13+
verify:
14+
runs-on: ubuntu-latest
15+
steps:
16+
- uses: actions/checkout@v4
17+
- uses: actions/setup-python@v5
18+
with:
19+
python-version: "3.11"
20+
- name: Validate metadata, hashes, and archive boundaries
21+
run: python3 scripts/validate_catalog.py
22+
- name: Unit tests
23+
run: python3 -m unittest discover -s tests -v

‎.gitignore‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,2 @@
1+
__pycache__/
2+
*.py[cod]

‎CONTRIBUTING.md‎

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
# Contributing trace cases
2+
3+
Read [DATA_POLICY.md](DATA_POLICY.md) before adding data.
4+
5+
1. Use a stable kebab-case case ID and describe one reproducible scenario.
6+
2. Add explicit provenance, capture time, license, consent, privacy review,
7+
sanitization review, publication status, and article URLs to both the case
8+
and every artifact.
9+
3. Record `content_format` separately from `packaging`. A zipped Perfetto trace
10+
remains `perfetto-protobuf` content with `zip` packaging.
11+
4. For ZIP files, record compressed size, total uncompressed size, and member
12+
count. Do not include absolute paths, `..`, encrypted members, or archive
13+
bombs.
14+
5. Run:
15+
16+
```bash
17+
python3 scripts/validate_catalog.py
18+
python3 -m unittest discover -s tests -v
19+
git diff --check
20+
```
21+
22+
Unknown legacy metadata must stay `null` or `pending`; never invent a device,
23+
capture date, permission, or review result to make validation green.

‎DATA_POLICY.md‎

Lines changed: 39 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,39 @@
1+
# Trace data policy
2+
3+
This repository contains historical Perfetto, Systrace HTML, and ART method
4+
trace attachments used by Android Performance articles. Trace data can contain
5+
package names, process/thread names, file paths, build fingerprints, account
6+
identifiers, or other device/user context.
7+
8+
## Existing artifacts
9+
10+
`catalog.json` records the known state of every artifact. `license: null`,
11+
`consent: null`, or a `pending` review means that the historical record is
12+
unknown; it does not grant additional permission to copy, redistribute, or use
13+
third-party data. Repository visibility is not a blanket data license.
14+
15+
The existing binary artifacts are intentionally unchanged by the cataloging
16+
work. Their hashes make later review auditable. If provenance or authorization
17+
cannot be established, update the catalog before changing publication status.
18+
19+
## New artifacts
20+
21+
A new contribution must document:
22+
23+
- who captured or supplied it and when;
24+
- the capture owner or permission basis;
25+
- the data license or explicit redistribution terms;
26+
- privacy and sanitization review results;
27+
- all related article URLs;
28+
- content format, packaging, byte sizes, archive members, and SHA-256.
29+
30+
Do not contribute credentials, tokens, account identifiers, personal messages,
31+
private file paths, proprietary app data, or traces you are not authorized to
32+
publish. Prefer a minimal Perfetto protobuf capture over legacy self-contained
33+
HTML, and capture a purpose-built demo when possible.
34+
35+
## Code and documentation
36+
37+
`LICENSE-CODE` applies only to the repository's original documentation,
38+
catalog schema, validation code, tests, and workflow. It does not relicense any
39+
trace/archive artifact or linked article.

‎LICENSE-CODE‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
MIT License
2+
3+
Copyright (c) 2026 Gracker
4+
5+
Permission is hereby granted, free of charge, to any person obtaining a copy
6+
of this software and associated documentation files (the "Software"), to deal
7+
in the Software without restriction, including without limitation the rights
8+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9+
copies of the Software, and to permit persons to whom the Software is
10+
furnished to do so, subject to the following conditions:
11+
12+
The above copyright notice and this permission notice shall be included in all
13+
copies or substantial portions of the Software.
14+
15+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21+
SOFTWARE.

‎README.md‎

Lines changed: 78 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1 +1,78 @@
1-
# SystraceForBlog
1+
# Trace for Blog (SystraceForBlog)
2+
3+
[简体中文](README.zh-CN.md)
4+
5+
Perfetto, legacy Systrace HTML, and ART method-trace case files used by
6+
[Android Performance](https://www.androidperformance.com/) articles. The legacy
7+
repository name is preserved because published articles link to its directories.
8+
9+
<!-- android-performance-ecosystem:start -->
10+
## Android performance ecosystem
11+
12+
This repository is one part of the [Android Performance Ecosystem](https://github.com/Gracker/android-performance-ecosystem): an optional path from instrumentation and capture to analysis, system knowledge, and reproducible cases.
13+
14+
| Stage | Project | Purpose | Address |
15+
| --- | --- | --- | --- |
16+
| Instrument | [TraceFix](https://github.com/Gracker/TraceFix) | Inject app-side android.os.Trace sections at build time so method work is visible at runtime. | [GitHub](https://github.com/Gracker/TraceFix) |
17+
| Capture and measure | [Perfetto Tools](https://github.com/Gracker/perfetto-tools) | Capture repeatable Perfetto traces and collect FPS or Simpleperf measurements. | [GitHub](https://github.com/Gracker/perfetto-tools) |
18+
| Analyze | [SmartPerfetto](https://github.com/Gracker/SmartPerfetto) | Investigate traces with an AI-assisted Web UI, CLI, reports, sessions, comparisons, and evidence workflow. | [GitHub](https://github.com/Gracker/SmartPerfetto) |
19+
| Agent analysis | [Perfetto Skills](https://github.com/Gracker/Perfetto-Skills) | Give agents a portable Perfetto analysis Skill for Android, Linux, and Chromium, with selected assets synchronized through pinned workflows. | [GitHub](https://github.com/Gracker/Perfetto-Skills) |
20+
| Learn | [Android Performance Blog](https://github.com/Gracker/Gracker.github.io) | Teach Perfetto and Systrace analysis through articles, system explanations, and case studies. | [GitHub](https://github.com/Gracker/Gracker.github.io) · [Website](https://www.androidperformance.com/) |
21+
| System knowledge | Android Internal Wiki | An alpha knowledge base for Android mechanisms from App to Framework, Native, and Kernel. | **Coming soon** |
22+
| Reproduce | [Trace for Blog (SystraceForBlog)](https://github.com/Gracker/SystraceForBlog) | Provide the Perfetto, Systrace, and related case files used by articles for hands-on reproduction. | [GitHub](https://github.com/Gracker/SystraceForBlog) |
23+
<!-- android-performance-ecosystem:end -->
24+
25+
## Case catalog
26+
27+
[`catalog.json`](catalog.json) is the machine-readable inventory. It covers all
28+
15 existing artifacts with byte size, SHA-256, content format, packaging,
29+
article mapping, provenance, license/consent state, and privacy/sanitization
30+
review state.
31+
32+
| Case ID | Area | Artifacts | Related article |
33+
| --- | --- | --- | --- |
34+
| `perfetto-aosp-demo-scroll` | Scrolling / rendering | 1 Perfetto protobuf | [MainThread and RenderThread](https://www.androidperformance.com/2025/08/02/Android-Perfetto-07-MainThread-And-RenderThread/) |
35+
| `perfetto-wechat-moments-jank` | Scrolling jank | Perfetto protobuf + ZIP copy | Not recorded |
36+
| `systrace-main-render-wangzhe` | MainThread / RenderThread | Systrace HTML ZIP + ART method trace | [Article](https://www.androidperformance.com/2019/11/06/Android-Systrace-MainThread-And-RenderThread/) |
37+
| `systrace-main-render-flutter-wanandroid` | Flutter rendering | Systrace HTML ZIP + ART method trace | [Article](https://www.androidperformance.com/2019/11/06/Android-Systrace-MainThread-And-RenderThread/) |
38+
| `systrace-binder-app-launch` | Binder | 1 Systrace HTML ZIP | [Article](https://www.androidperformance.com/2019/12/06/Android-Systrace-Binder/) |
39+
| `systrace-input-launcher-scroll` | Input | 1 Systrace HTML ZIP | [Article](https://www.androidperformance.com/2019/11/04/Android-Systrace-Input/) |
40+
| `systrace-input-list-jank` | Input / jank | 1 Systrace HTML ZIP | [Article](https://www.androidperformance.com/2019/11/04/Android-Systrace-Input/) |
41+
| `systrace-smooth-launchers` | Scrolling smoothness | 3 Systrace HTML ZIPs | [Series](https://www.androidperformance.com/2021/04/24/android-systrace-smooth-in-action-1/) |
42+
| `systrace-twitter-jank` | Scrolling jank | 1 Systrace HTML ZIP | Not recorded |
43+
| `systrace-triple-buffer` | Buffering / rendering | 1 ZIP containing 5 Systrace HTML files | [Article](https://www.androidperformance.com/2019/12/15/Android-Systrace-Triple-Buffer/) |
44+
45+
## Use a case
46+
47+
Analyze a Perfetto protobuf with SmartPerfetto:
48+
49+
```bash
50+
smp run "Android_Perfetto/demo_app_aosp_scroll.perfetto-trace" "Analyze scrolling jank"
51+
```
52+
53+
Or ask an agent with Perfetto Skills to use
54+
`$perfetto-performance-analysis` on the same file. Legacy `*.html.zip` files are
55+
self-contained Systrace pages: inspect the archive first, extract locally, then
56+
open the HTML in a browser. ART `*.trace` files are method traces, not Perfetto
57+
protobufs.
58+
59+
## Data boundary
60+
61+
All current artifacts are historical. Their original license, consent, privacy
62+
review, or sanitization record was not preserved, so the catalog deliberately
63+
uses `null` and `pending`. Public visibility does not create a blanket data
64+
license. Read [DATA_POLICY.md](DATA_POLICY.md) before using or contributing data.
65+
`LICENSE-CODE` covers only original documentation and validation code, not the
66+
trace/archive artifacts or linked articles.
67+
68+
## Verify
69+
70+
```bash
71+
python3 scripts/validate_catalog.py
72+
python3 -m unittest discover -s tests -v
73+
git diff --check
74+
```
75+
76+
The validator checks inventory completeness, hashes, sizes, required provenance
77+
fields, safe relative paths, ZIP member paths, encryption, decompressed size,
78+
member count, and compression ratio without extracting archives to disk.

‎README.zh-CN.md‎

Lines changed: 73 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,73 @@
1+
# Trace for Blog (SystraceForBlog)
2+
3+
[English](README.md)
4+
5+
本仓库保存 [Android Performance](https://www.androidperformance.com/) 文章使用的
6+
Perfetto、旧版 Systrace HTML 和 ART method trace 案例。历史文章已经大量引用原仓库名和
7+
目录，因此继续保留 `SystraceForBlog` 名称，对外展示为 Trace for Blog。
8+
9+
<!-- android-performance-ecosystem:start -->
10+
## Android 性能分析生态
11+
12+
本仓库属于 [Android Performance Ecosystem](https://github.com/Gracker/android-performance-ecosystem)：它把可选插桩、采集、分析、系统知识与可复现案例连接成一套完整路径。
13+
14+
| 阶段 | 项目 | 作用 | 地址 |
15+
| --- | --- | --- | --- |
16+
| 插桩 | [TraceFix](https://github.com/Gracker/TraceFix) | 在编译期注入 App 侧 android.os.Trace section，让方法执行在运行时 Trace 中可见。 | [GitHub](https://github.com/Gracker/TraceFix) |
17+
| 采集与测量 | [Perfetto Tools](https://github.com/Gracker/perfetto-tools) | 抓取可复现的 Perfetto Trace，并采集 FPS 或 Simpleperf 测量结果。 | [GitHub](https://github.com/Gracker/perfetto-tools) |
18+
| 分析 | [SmartPerfetto](https://github.com/Gracker/SmartPerfetto) | 通过 AI 辅助 Web UI、CLI、报告、会话、对比和证据工作流分析 Trace。 | [GitHub](https://github.com/Gracker/SmartPerfetto) |
19+
| Agent 分析 | [Perfetto Skills](https://github.com/Gracker/Perfetto-Skills) | 为 Agent 提供可移植的 Android、Linux、Chromium Perfetto 分析 Skill，并通过固定版本流程同步选定资产。 | [GitHub](https://github.com/Gracker/Perfetto-Skills) |
20+
| 学习 | [Android Performance Blog](https://github.com/Gracker/Gracker.github.io) | 通过文章、系统原理和案例复盘讲解 Perfetto 与 Systrace 分析。 | [GitHub](https://github.com/Gracker/Gracker.github.io) · [网站](https://www.androidperformance.com/) |
21+
| 系统知识 | Android Internal Wiki | 处于 alpha 阶段的 Android 系统知识库，覆盖 App、Framework、Native 与 Kernel 机制。 | **Coming soon** |
22+
| 复现 | [Trace for Blog (SystraceForBlog)](https://github.com/Gracker/SystraceForBlog) | 提供文章使用的 Perfetto、Systrace 及相关案例文件，支持动手复现。 | [GitHub](https://github.com/Gracker/SystraceForBlog) |
23+
<!-- android-performance-ecosystem:end -->
24+
25+
## 案例目录
26+
27+
[`catalog.json`](catalog.json) 是机器可读的事实源。它覆盖现有 15 个 artifact，记录
28+
字节大小、SHA-256、内容格式、打包方式、文章映射、来源、授权/同意状态，以及隐私和
29+
脱敏审核状态。
30+
31+
| Case ID | 领域 | 文件 | 对应文章 |
32+
| --- | --- | --- | --- |
33+
| `perfetto-aosp-demo-scroll` | 滑动 / 渲染 | 1 个 Perfetto protobuf | [MainThread 和 RenderThread](https://www.androidperformance.com/2025/08/02/Android-Perfetto-07-MainThread-And-RenderThread/) |
34+
| `perfetto-wechat-moments-jank` | 滑动卡顿 | Perfetto protobuf + ZIP 副本 | 未记录 |
35+
| `systrace-main-render-wangzhe` | 主线程 / 渲染线程 | Systrace HTML ZIP + ART method trace | [文章](https://www.androidperformance.com/2019/11/06/Android-Systrace-MainThread-And-RenderThread/) |
36+
| `systrace-main-render-flutter-wanandroid` | Flutter 渲染 | Systrace HTML ZIP + ART method trace | [文章](https://www.androidperformance.com/2019/11/06/Android-Systrace-MainThread-And-RenderThread/) |
37+
| `systrace-binder-app-launch` | Binder | 1 个 Systrace HTML ZIP | [文章](https://www.androidperformance.com/2019/12/06/Android-Systrace-Binder/) |
38+
| `systrace-input-launcher-scroll` | Input | 1 个 Systrace HTML ZIP | [文章](https://www.androidperformance.com/2019/11/04/Android-Systrace-Input/) |
39+
| `systrace-input-list-jank` | Input / 卡顿 | 1 个 Systrace HTML ZIP | [文章](https://www.androidperformance.com/2019/11/04/Android-Systrace-Input/) |
40+
| `systrace-smooth-launchers` | 滑动流畅度 | 3 个 Systrace HTML ZIP | [系列文章](https://www.androidperformance.com/2021/04/24/android-systrace-smooth-in-action-1/) |
41+
| `systrace-twitter-jank` | 滑动卡顿 | 1 个 Systrace HTML ZIP | 未记录 |
42+
| `systrace-triple-buffer` | Buffer / 渲染 | 1 个 ZIP，内含 5 个 Systrace HTML | [文章](https://www.androidperformance.com/2019/12/15/Android-Systrace-Triple-Buffer/) |
43+
44+
## 使用案例
45+
46+
用 SmartPerfetto 分析 Perfetto protobuf：
47+
48+
```bash
49+
smp run "Android_Perfetto/demo_app_aosp_scroll.perfetto-trace" "分析滑动卡顿"
50+
```
51+
52+
也可以让安装了 Perfetto Skills 的 Agent 对同一文件使用
53+
`$perfetto-performance-analysis`。旧版 `*.html.zip` 是自包含 Systrace 页面：先检查
54+
压缩包，再在本机解压并用浏览器打开 HTML。ART `*.trace` 是 method trace，不是
55+
Perfetto protobuf。
56+
57+
## 数据边界
58+
59+
当前文件都是历史资产，原始许可证、发布同意、隐私审核和脱敏记录没有完整保留下来，
60+
所以清单明确使用 `null` 与 `pending`，不会为了“看起来完整”伪造元数据。仓库公开不等于
61+
获得统一的数据许可证。使用或贡献前请读 [DATA_POLICY.md](DATA_POLICY.md)。
62+
`LICENSE-CODE` 只覆盖本仓新增文档和校验代码，不覆盖 Trace、压缩包或链接文章。
63+
64+
## 验证
65+
66+
```bash
67+
python3 scripts/validate_catalog.py
68+
python3 -m unittest discover -s tests -v
69+
git diff --check
70+
```
71+
72+
校验器会检查目录覆盖、哈希、大小、来源必填字段、安全相对路径、ZIP member 路径、加密、
73+
解压总量、member 数量和压缩比，并且不会把压缩包解压到磁盘。

0 commit comments

Comments
 (0)