agentpprof-flamegraph

Name: agentpprof-flamegraph
Author: eunomia-bpf

534stars72forks

How to install agentpprof-flamegraph?

eunomia-bpf/agentsight/agentpprof-flamegraph

$npx -y skills add eunomia-bpf/agentsight --skill agentpprof-flamegraph

Installs into the current project.

Summary

Generate semantic flamegraphs from local AI agent sessions using agentpprof with iterative tag rule development.

Files · 1

View on GitHub

SKILL.md

1	# agentpprof Flamegraph Generation
2
3	## Goal
4
5	Generate meaningful flamegraphs from local Codex/Claude Code sessions by iteratively developing tag rules that achieve high prompt coverage.
6
7	## Workflow
8
9	### 1. Initial Discovery
10
11	Run agentpprof without rules to see diagnostics:
12
13	```bash
14	agentpprof \
15	--project-root /path/to/project \
16	--view tokens \
17	-o initial.json \
18	--format json \
19	--include-previews
20	```
21
22	The output includes:
23	- `tagging.total_prompts`: total prompts found
24	- `tagging.unmatched_prompts`: prompts without tags
25	- `tagging.unmatched_samples`: sample unmatched prompts (up to 20)
26	- `tagging.hint`: suggested next step
27
28	### 2. Analyze Unmatched Prompts
29
30	Look at `unmatched_samples` to identify patterns:
31	- Common keywords or phrases
32	- Chinese/English patterns
33	- Action types (review, debug, git, etc.)
34	- Project-specific terminology
35
36	### 3. Develop Tag Rules
37
38	Add `--tag-rule` arguments iteratively:
39
40	```bash
41	agentpprof \
42	--project-root /path/to/project \
43	--tag-rule 'prompt:review=(?i)review\|审核\|check' \
44	--tag-rule 'prompt:debug=(?i)fix\|bug\|error\|broken' \
45	--tag-rule 'prompt:git=(?i)commit\|push\|pull\|git' \
46	--view tokens \
47	-o iter1.folded
48	```
49
50	Rule syntax: `KIND:TAG=REGEX`
51	- KIND: `prompt`, `session`, `llm`, or `all`
52	- TAG: lowercase word, 3-12 letters (semantic, not vague)
53	- REGEX: case-insensitive patterns with `(?i)`
54
55	Avoid vague tags like `task`, `work`, `misc`, `thing`, `stuff`, `other` — they don't convey semantic meaning and won't aggregate well. Use specific tags like `debug`, `review`, `paper`, `naming` that describe the activity.
56
57	Never use catch-all rules like `prompt:misc=.` or `llm:other=.` — they defeat the purpose of semantic tagging by lumping everything together. If you can't classify an item, leave it unmatched and add more specific rules.
58
59	Never use placeholder tags like `llm:placeholder`, `llm:response`, `prompt:other` — they indicate that the tagging rules are incomplete. If you see placeholder tags dominating the distribution, investigate why the content isn't being classified properly. Common causes:
60	- Parser limitations (e.g., `"claude response"` preview means the actual response content wasn't extracted)
61	- Rules ordered incorrectly (more specific rules should come before general ones)
62	- Missing rules for common patterns
63
64	### 4. Check Coverage
65
66	Each run shows diagnostics and warnings:
67	```
68	Warning: 150/1000 prompts unmatched. Add prompt tag rules.
69	```
70
71	Check detailed coverage:
72	```bash
73	agentpprof --project-root . -o out.json --format json 2>&1 \| jq '.tagging'
74	```
75
76	Definition of "well-tagged":
77	- Target: All three categories must have `< 5%` unmatched
78	- `prompts.unmatched / prompts.total < 5%`
79	- `sessions.unmatched / sessions.total < 5%`
80	- `llm_calls.unmatched / llm_calls.total < 5%`
81
82	Distribution quality metrics:
83	- Tag count: 10-20 categories ideal (<5 too coarse, >25 too fragmented)
84	- Top-1 share: <40% (no single tag should dominate)
85	- Top-3 share: <70% (diversity across categories)
86	- Entropy: >0.7 normalized (evenly distributed)
87
88	The tool prints detailed distribution analysis:
89	```
90	Distribution (12 prompt tags, 2620 total): top1=35.5%, top3=58.2%, top5=72.1%, entropy=0.78
91	Top tags:
92	1. prompt:review = 931 (35.5%)
93	2. prompt:query = 228 (8.7%)
94	3. prompt:discuss = 173 (6.6%)
95	4. prompt:edit = 156 (6.0%)
96	5. prompt:code = 194 (7.4%)
97	```
98
99	Warnings are shown if metrics are poor:
100	```
101	Warning: prompt:misc dominates (55.2%). Target: top1 < 40%. Split into sub-categories.
102	Warning: low entropy (0.45). Distribution is uneven. Target: entropy > 0.7.
103	```
104
105	Spot-check unmatched samples:
106	```bash
107	jq '.tagging.unmatched_samples \| map(select(.kind == "prompt")) \| .[0:10]' out.json
108	```
109
110	If unmatched prompts share patterns, add rules. Continue iterating until ALL categories have < 5% unmatched. Avoid vague catch-all tags like `misc` — use specific semantic tags that describe the activity.
111
112	### 5. Generate Final Flamegraphs
113
114	```bash
115	for view in tokens files network; do
116	agentpprof \
117	--project-root /path/to/project \
118	"${TAG_RULES[@]}" \
119	--view "$view" \
120	--svg-width 1200 \
121	-o "project-${view}.svg"
122	done
123	```
124
125	SVG width: Use `--svg-width` to adjust flamegraph width (default: 1200px). Narrower widths (800-1000) improve readability for deep flamegraphs; wider (1600-2000) for shallow ones with many tags.
126
127	## Views
128
129	\| View \| Width means \| Use for \|
130	\|------\|-------------\|---------\|
131	\| `tokens` \| Token count \| Where did model budget go? \|
132	\| `files` \| File effect count \| Which paths were touched? \|
133	\| `network` \| Network effect count \| Which doma

People who liked this also viewed

6 picks

Type

lark-openapi-explorer飞书/Lark 原生 OpenAPI 探索：从官方文档库中挖掘未经 CLI 封装的原生 OpenAPI 接口。当用户的需求无法被现有 lark-* skill 或 lark-cli 已注册命令满足，需要查找并调用原生飞书 OpenAPI 时使用。SkillsJul 2026378k16k
lark-skill-maker创建 lark-cli 的自定义 Skill。当用户需要把飞书 API 操作封装成可复用的 Skill（包装原子 API 或编排多步流程）时使用。SkillsJul 2026377k16k
azure-cost-optimizationOfficial agent plugin providing skills and MCP server configurations for Azure scenarios.SkillsJul 2026209k1.3k
vercel-react-native-skillsVercel's official collection of agent skillsSkillsJul 2026172k29k
mcp-builderGuide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate externaSkillsJul 202693k163k
gws-sharedgws CLI: Shared patterns for authentication, global flags, and output formatting.SkillsJul 202653k30k

agentpprof-flamegraph

534stars72forks

View on GitHub

How to install agentpprof-flamegraph?

eunomia-bpf/agentsight/agentpprof-flamegraph

$npx -y skills add eunomia-bpf/agentsight --skill agentpprof-flamegraph

Installs into the current project.

Summary

Generate semantic flamegraphs from local AI agent sessions using agentpprof with iterative tag rule development.

Files · 1

View on GitHub

SKILL.md

1	# agentpprof Flamegraph Generation
2
3	## Goal
4
5	Generate meaningful flamegraphs from local Codex/Claude Code sessions by iteratively developing tag rules that achieve high prompt coverage.
6
7	## Workflow
8
9	### 1. Initial Discovery
10
11	Run agentpprof without rules to see diagnostics:
12
13	```bash
14	agentpprof \
15	--project-root /path/to/project \
16	--view tokens \
17	-o initial.json \
18	--format json \
19	--include-previews
20	```
21
22	The output includes:
23	- `tagging.total_prompts`: total prompts found
24	- `tagging.unmatched_prompts`: prompts without tags
25	- `tagging.unmatched_samples`: sample unmatched prompts (up to 20)
26	- `tagging.hint`: suggested next step
27
28	### 2. Analyze Unmatched Prompts
29
30	Look at `unmatched_samples` to identify patterns:
31	- Common keywords or phrases
32	- Chinese/English patterns
33	- Action types (review, debug, git, etc.)
34	- Project-specific terminology
35
36	### 3. Develop Tag Rules
37
38	Add `--tag-rule` arguments iteratively:
39
40	```bash
41	agentpprof \
42	--project-root /path/to/project \
43	--tag-rule 'prompt:review=(?i)review\|审核\|check' \
44	--tag-rule 'prompt:debug=(?i)fix\|bug\|error\|broken' \
45	--tag-rule 'prompt:git=(?i)commit\|push\|pull\|git' \
46	--view tokens \
47	-o iter1.folded
48	```
49
50	Rule syntax: `KIND:TAG=REGEX`
51	- KIND: `prompt`, `session`, `llm`, or `all`
52	- TAG: lowercase word, 3-12 letters (semantic, not vague)
53	- REGEX: case-insensitive patterns with `(?i)`
54
55	Avoid vague tags like `task`, `work`, `misc`, `thing`, `stuff`, `other` — they don't convey semantic meaning and won't aggregate well. Use specific tags like `debug`, `review`, `paper`, `naming` that describe the activity.
56
57	Never use catch-all rules like `prompt:misc=.` or `llm:other=.` — they defeat the purpose of semantic tagging by lumping everything together. If you can't classify an item, leave it unmatched and add more specific rules.
58
59	Never use placeholder tags like `llm:placeholder`, `llm:response`, `prompt:other` — they indicate that the tagging rules are incomplete. If you see placeholder tags dominating the distribution, investigate why the content isn't being classified properly. Common causes:
60	- Parser limitations (e.g., `"claude response"` preview means the actual response content wasn't extracted)
61	- Rules ordered incorrectly (more specific rules should come before general ones)
62	- Missing rules for common patterns
63
64	### 4. Check Coverage
65
66	Each run shows diagnostics and warnings:
67	```
68	Warning: 150/1000 prompts unmatched. Add prompt tag rules.
69	```
70
71	Check detailed coverage:
72	```bash
73	agentpprof --project-root . -o out.json --format json 2>&1 \| jq '.tagging'
74	```
75
76	Definition of "well-tagged":
77	- Target: All three categories must have `< 5%` unmatched
78	- `prompts.unmatched / prompts.total < 5%`
79	- `sessions.unmatched / sessions.total < 5%`
80	- `llm_calls.unmatched / llm_calls.total < 5%`
81
82	Distribution quality metrics:
83	- Tag count: 10-20 categories ideal (<5 too coarse, >25 too fragmented)
84	- Top-1 share: <40% (no single tag should dominate)
85	- Top-3 share: <70% (diversity across categories)
86	- Entropy: >0.7 normalized (evenly distributed)
87
88	The tool prints detailed distribution analysis:
89	```
90	Distribution (12 prompt tags, 2620 total): top1=35.5%, top3=58.2%, top5=72.1%, entropy=0.78
91	Top tags:
92	1. prompt:review = 931 (35.5%)
93	2. prompt:query = 228 (8.7%)
94	3. prompt:discuss = 173 (6.6%)
95	4. prompt:edit = 156 (6.0%)
96	5. prompt:code = 194 (7.4%)
97	```
98
99	Warnings are shown if metrics are poor:
100	```
101	Warning: prompt:misc dominates (55.2%). Target: top1 < 40%. Split into sub-categories.
102	Warning: low entropy (0.45). Distribution is uneven. Target: entropy > 0.7.
103	```
104
105	Spot-check unmatched samples:
106	```bash
107	jq '.tagging.unmatched_samples \| map(select(.kind == "prompt")) \| .[0:10]' out.json
108	```
109
110	If unmatched prompts share patterns, add rules. Continue iterating until ALL categories have < 5% unmatched. Avoid vague catch-all tags like `misc` — use specific semantic tags that describe the activity.
111
112	### 5. Generate Final Flamegraphs
113
114	```bash
115	for view in tokens files network; do
116	agentpprof \
117	--project-root /path/to/project \
118	"${TAG_RULES[@]}" \
119	--view "$view" \
120	--svg-width 1200 \
121	-o "project-${view}.svg"
122	done
123	```
124
125	SVG width: Use `--svg-width` to adjust flamegraph width (default: 1200px). Narrower widths (800-1000) improve readability for deep flamegraphs; wider (1600-2000) for shallow ones with many tags.
126
127	## Views
128
129	\| View \| Width means \| Use for \|
130	\|------\|-------------\|---------\|
131	\| `tokens` \| Token count \| Where did model budget go? \|
132	\| `files` \| File effect count \| Which paths were touched? \|
133	\| `network` \| Network effect count \| Which doma

People who liked this also viewed

6 picks

Type