Add async-profiler skill for Java profiling 🤖🤖🤖 by vetler · Pull Request #1400 · github/awesome-copilot

vetler · 2026-04-15T08:59:39Z

What this adds

A skill for installing, running, and analyzing async-profiler for Java — a low-overhead sampling profiler that produces flamegraphs, JFR recordings, and allocation profiles.

Why it's useful

async-profiler is a niche, specialized tool with platform-specific quirks that frontier models don't reliably handle:

Exact asprof CLI flags and syntax
macOS-specific limitations (itimer vs perf_events, asprof stop -f output-path bug)
JVM flags required for accurate profiles (-XX:+UnlockDiagnosticVMOptions -XX:+DebugNonSafepoints)
Specific version/download URLs
How to interpret flamegraph patterns (GC pressure, N+1 Hibernate, lock contention)

Structure

skills/async-profiler/
├── SKILL.md                      # Entry point — routes to focused guides
├── README.md                     # Human-readable overview
├── references/
│   ├── setup.md                  # Installation and configuration
│   ├── profile.md                # Running profiling sessions
│   └── analyze.md                # Interpreting profiling output
└── scripts/
    ├── install.sh                # Platform auto-detect installer
    ├── run_profile.sh            # asprof wrapper with timestamped output
    ├── collect.sh                # Background start/stop collection
    └── analyze_collapsed.py      # Ranked self-time table for .collapsed files

Validation

npm run skill:validate ✅
npm run build ✅

github-actions · 2026-04-15T09:00:09Z

🔍 Skill Validator Results

✅ All checks passed

Scope	Checked
Skills	1
Agents	1
Total	2
Severity	Count
---	---:
❌ Errors	0
⚠️ Warnings	0
ℹ️ Advisories	0

Summary

Level	Finding
ℹ️	Found 1 skill(s)
ℹ️	[async-profiler] 📊 async-profiler: 1,491 BPE tokens [chars/4: 1,589] (detailed ✓), 12 sections, 3 code blocks
ℹ️	✅ All checks passed (1 skill(s))

Full validator output

```text Found 1 skill(s) [async-profiler] 📊 async-profiler: 1,491 BPE tokens [chars/4: 1,589] (detailed ✓), 12 sections, 3 code blocks ✅ All checks passed (1 skill(s)) ```

Copilot

Pull request overview

Adds a new async-profiler skill under skills/async-profiler/ to guide Java developers through installing async-profiler, running profiling sessions (including agent-friendly background capture), and analyzing outputs (flamegraphs/JFR/collapsed stacks), and registers the skill in docs/README.skills.md.

Changes:

Introduces async-profiler skill docs: setup, profiling workflows, and output analysis guidance.
Adds helper scripts for install/run/background collection plus a Python collapsed-stack analyzer.
Updates docs/README.skills.md to include the new skill entry.

Reviewed changes

Copilot reviewed 10 out of 10 changed files in this pull request and generated 9 comments.

Show a summary per file

File	Description
skills/async-profiler/SKILL.md	Skill entry-point and routing to setup/profile/analyze sub-guides.
skills/async-profiler/README.md	Human-readable overview and installation notes.
skills/async-profiler/setup/SKILL.md	Installation/configuration instructions and troubleshooting.
skills/async-profiler/profile/SKILL.md	How to run profiles, including `collect.sh` background workflows.
skills/async-profiler/analyze/SKILL.md	How to interpret flamegraphs/JFR/collapsed stacks.
skills/async-profiler/scripts/install.sh	Platform-detecting async-profiler installer.
skills/async-profiler/scripts/run_profile.sh	Convenience wrapper for one-shot profiles + (intended) JFR splitting.
skills/async-profiler/scripts/collect.sh	Start/stop/timed background collection workflow with JFR splitting.
skills/async-profiler/scripts/analyze_collapsed.py	CLI analyzer for `.collapsed` files.
docs/README.skills.md	Adds the skill to the repository skills index.

vetler

All 9 review comments have been addressed in an amended commit (3fa7ee5). Summary of changes:

python → python3 in run_profile.sh post-run guidance
from __future__ import annotations added to analyze_collapsed.py to restore Python 3.7+ compatibility (PEP 585 generics)
jfrconv --event alloc → jfrconv --alloc in analyze/SKILL.md
Install path comment in install.sh updated to ~/async-profiler-4.3
Bash syntax in collect.sh split_jfr: separated & local pid_X=$! onto two lines
asprof stop now passes -f "$jfr_path" so on Linux the JFR lands at the expected path; macOS sentinel workaround is unchanged
run_profile.sh comprehensive mode fixed to use --cpu/--alloc/--wall/--lock instead of --event cpu etc.
collect.sh timed docs corrected to -d 60 <PID> (flag before target)
Output filenames in profile/SKILL.md corrected to profile-cpu.html, profile-alloc.html, etc.

Copilot

Pull request overview

Copilot reviewed 10 out of 10 changed files in this pull request and generated 7 comments.

vetler · 2026-04-15T09:36:50Z

Fixed all 7 review comments:

profile/SKILL.md: Moved -maxdepth 8 before -name in all find examples (×2)
profile/SKILL.md: timed table already fixed in previous round
collect.sh: Moved -maxdepth 8 before predicates in JFR lookup (line ~230)
collect.sh: Fixed -maxdepth order in troubleshooting echo (line ~238)
collect.sh session_file(): Added UID and $XDG_RUNTIME_DIR support to prevent predictable tmp paths
run_profile.sh: Changed sed -n '2,/^$/p' → sed -n '2,/^[^#]/p' to stop at first non-comment line
run_profile.sh: Changed remaining python → python3 in single-event collapsed branch

Copilot

Pull request overview

Copilot reviewed 10 out of 10 changed files in this pull request and generated 4 comments.

vetler · 2026-04-15T09:47:44Z

Fixed 3 of 4 review comments; the 4th is already handled:

analyze_collapsed.py — list[tuple[...]] compatibility (no code change needed)
from __future__ import annotations (PEP 563, added in a prior commit) defers evaluation of all annotations in this module to strings at runtime. list[tuple[list[str], int]] in the return type of parse_collapsed() is therefore never evaluated on Python 3.7/3.8 and will not raise a SyntaxError.

analyze_collapsed.py — ZeroDivisionError when total_samples == 0
Added guard: matching_pct = 0.0 if total_samples == 0 else 100 * surviving / total_samples

run_profile.sh — missing $# check before $2 in option loop
Added [[ $# -ge 2 ]] || { echo "❌ Missing value for $1" >&2; exit 1; } before each $2 access for --event, --duration, --format, --output, --asprof.

collect.sh — missing $# check for -d/--duration and --asprof
Same guard added for both options.

Copilot

Copilot encountered an error and was unable to review this pull request. You can try again by re-requesting a review.

vetler · 2026-04-15T10:21:13Z

@all-contributors add @vetler for skills

allcontributors · 2026-04-15T10:21:16Z

@vetler

I couldn't determine any contributions to add, did you specify any contributions?
Please make sure to use valid contribution names.

vetler · 2026-04-15T10:22:00Z

@all-contributors add @vetler for 🧰

allcontributors · 2026-04-15T10:22:04Z

@vetler

I couldn't determine any contributions to add, did you specify any contributions?
Please make sure to use valid contribution names.

vetler · 2026-04-15T10:23:34Z

@all-contributors add @vetler for skill

allcontributors · 2026-04-15T10:23:38Z

@vetler

I couldn't determine any contributions to add, did you specify any contributions?
Please make sure to use valid contribution names.

Copilot

Pull request overview

Copilot reviewed 10 out of 10 changed files in this pull request and generated 5 comments.

Copilot

Pull request overview

Copilot reviewed 10 out of 10 changed files in this pull request and generated 3 comments.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Copilot

Pull request overview

Copilot reviewed 10 out of 10 changed files in this pull request and generated 4 comments.

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

Copilot

Pull request overview

Copilot reviewed 10 out of 10 changed files in this pull request and generated 2 comments.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Copilot

Pull request overview

Copilot reviewed 10 out of 10 changed files in this pull request and generated 3 comments.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Copilot

Pull request overview

Copilot reviewed 10 out of 10 changed files in this pull request and generated 2 comments.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Copilot

Pull request overview

Copilot reviewed 10 out of 10 changed files in this pull request and generated 3 comments.

Comments suppressed due to low confidence (1)

skills/async-profiler/references/setup.md:1

The manual install section hard-codes v4.3 URLs in multiple places. Since scripts/install.sh pins the version and will likely change over time, these URLs will become stale unless updated in lockstep. Consider either (a) using a <VERSION> placeholder and explicitly instructing readers to substitute the version used in scripts/install.sh, or (b) pointing readers to the GitHub Releases page for the current version rather than embedding version-specific URLs.

# async-profiler Setup

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Copilot

Pull request overview

Copilot reviewed 11 out of 11 changed files in this pull request and generated 1 comment.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Copilot

Pull request overview

Copilot reviewed 11 out of 11 changed files in this pull request and generated 3 comments.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Copilot

Pull request overview

Copilot reviewed 11 out of 11 changed files in this pull request and generated 2 comments.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Copilot

Pull request overview

Copilot reviewed 11 out of 11 changed files in this pull request and generated 3 comments.

+    # Note: on macOS, -f is silently ignored by asprof stop — handled below.
+    "$asprof" stop -f "$jfr_path" "$TARGET"
+    # Session file is removed only after the JFR is confirmed written (see end of block).
+
+    # ── macOS JFR path workaround ────────────────────────────────────────────
+    # On macOS, asprof stop ignores -f and writes the JFR to:
+    #   /var/folders/<hash>/T/<timestamp>_<pid>/<timestamp>.jfr
+    # Use the sentinel (created at 'start') to find the file via find -newer.
+    if [[ "$(uname)" == "Darwin" ]] && [[ -n "$sentinel" ]] && [[ -f "$sentinel" ]]; then
+        echo ""
+        echo "⚠️  macOS: -f is ignored by asprof stop — locating JFR in /var/folders..."


+        if [[ -n "$found_jfr" ]]; then
+            cp "$found_jfr" "$jfr_path"
+            rm -f "$sentinel"
+            echo "   Found: $found_jfr"
+            echo "   Copied to: $jfr_path"


+echo "   Output  : $OUTPUT"
+$THREADS && echo "   Threads : separate"
+echo ""
+echo "▶ ${CMD[*]}"


vetler requested a review from aaronpowell as a code owner April 15, 2026 08:59

Copilot AI review requested due to automatic review settings April 15, 2026 08:59

Copilot started reviewing on behalf of vetler April 15, 2026 09:00 View session

Copilot AI reviewed Apr 15, 2026

View reviewed changes

vetler force-pushed the add-async-profiler-skill-staged branch from e97338d to 3fa7ee5 Compare April 15, 2026 09:22

vetler commented Apr 15, 2026

View reviewed changes

vetler requested a review from Copilot April 15, 2026 09:28

Copilot started reviewing on behalf of vetler April 15, 2026 09:28 View session

Copilot AI reviewed Apr 15, 2026

View reviewed changes

vetler force-pushed the add-async-profiler-skill-staged branch from 3fa7ee5 to 7204e5b Compare April 15, 2026 09:36

vetler requested a review from Copilot April 15, 2026 09:38

Copilot started reviewing on behalf of vetler April 15, 2026 09:38 View session

Copilot AI reviewed Apr 15, 2026

View reviewed changes

Comment thread skills/async-profiler/scripts/analyze_collapsed.py

Comment thread skills/async-profiler/scripts/analyze_collapsed.py Outdated

Comment thread skills/async-profiler/scripts/run_profile.sh Outdated

Comment thread skills/async-profiler/scripts/collect.sh Outdated

vetler force-pushed the add-async-profiler-skill-staged branch from 7204e5b to fd6e431 Compare April 15, 2026 09:47

vetler requested a review from Copilot April 15, 2026 09:56

Copilot started reviewing on behalf of vetler April 15, 2026 09:57 View session

Copilot AI reviewed Apr 15, 2026

View reviewed changes

vetler requested a review from Copilot April 15, 2026 10:20

Copilot started reviewing on behalf of vetler April 15, 2026 10:21 View session

Copilot AI reviewed Apr 15, 2026

View reviewed changes

vetler force-pushed the add-async-profiler-skill-staged branch from fd6e431 to b334294 Compare April 15, 2026 10:30

Copilot AI reviewed May 2, 2026

View reviewed changes

Comment thread skills/async-profiler/scripts/collect.sh Outdated

Comment thread skills/async-profiler/scripts/run_profile.sh Outdated

Comment thread skills/async-profiler/scripts/collect.sh

vetler and others added 2 commits May 2, 2026 17:29

fix(async-profiler): remove unused base_dir

89d453c

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

fix(async-profiler): reject incompatible all-event formats

ffa6021

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

vetler requested a review from Copilot May 2, 2026 15:36

Copilot started reviewing on behalf of vetler May 2, 2026 15:37 View session

Copilot AI reviewed May 2, 2026

View reviewed changes

Comment thread skills/async-profiler/scripts/analyze_collapsed.py Outdated

Comment thread skills/async-profiler/SKILL.md

Comment thread skills/async-profiler/README.md

Comment thread skills/async-profiler/scripts/run_profile.sh Outdated

Potential fix for pull request finding

38a5bec

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

vetler requested a review from Copilot May 2, 2026 15:47

Copilot started reviewing on behalf of vetler May 2, 2026 15:48 View session

Copilot AI reviewed May 2, 2026

View reviewed changes

Comment thread skills/async-profiler/references/setup.md Outdated

Comment thread skills/async-profiler/scripts/collect.sh

fix(async-profiler): tighten troubleshooting and cleanup

cd1c4d2

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

vetler requested a review from Copilot May 2, 2026 15:57

Copilot started reviewing on behalf of vetler May 2, 2026 15:58 View session

Copilot AI reviewed May 2, 2026

View reviewed changes

Comment thread skills/async-profiler/scripts/install.sh

Comment thread skills/async-profiler/references/setup.md Outdated

Comment thread skills/async-profiler/scripts/run_profile.sh Outdated

fix(async-profiler): tighten path and stderr handling

8fe901b

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

vetler requested a review from Copilot May 2, 2026 19:00

Copilot started reviewing on behalf of vetler May 2, 2026 19:01 View session

Copilot AI reviewed May 2, 2026

View reviewed changes

Comment thread skills/async-profiler/scripts/analyze_collapsed.py Outdated

Comment thread skills/async-profiler/scripts/collect.sh

fix(async-profiler): handle invalid inputs more safely

d790d48

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

vetler requested a review from Copilot May 2, 2026 19:46

Copilot started reviewing on behalf of vetler May 2, 2026 19:46 View session

Copilot AI reviewed May 2, 2026

View reviewed changes

Comment thread skills/async-profiler/scripts/run_profile.sh Outdated

Comment thread skills/async-profiler/scripts/run_profile.sh Outdated

Comment thread skills/async-profiler/scripts/collect.sh Outdated

fix(async-profiler): align wrapper CLI with asprof

2526245

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Copilot AI reviewed May 2, 2026

View reviewed changes

Comment thread skills/async-profiler/references/setup.md Outdated

docs(async-profiler): fix attach troubleshooting example

237df2a

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Copilot AI reviewed May 2, 2026

View reviewed changes

Comment thread skills/async-profiler/scripts/install.sh

Comment thread skills/async-profiler/scripts/run_profile.sh

Comment thread skills/async-profiler/scripts/analyze_collapsed.py Outdated

fix(async-profiler): validate wrapper inputs earlier

bb2e8ca

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Copilot AI reviewed May 2, 2026

View reviewed changes

Comment thread skills/async-profiler/scripts/collect.sh

Comment thread skills/async-profiler/scripts/install.sh

fix(async-profiler): harden collect session state

f761acc

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Copilot AI reviewed May 2, 2026

View reviewed changes

Conversation

vetler commented Apr 15, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What this adds

Why it's useful

Structure

Validation

Uh oh!

github-actions Bot commented Apr 15, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🔍 Skill Validator Results

Summary

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

vetler left a comment

Choose a reason for hiding this comment

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

vetler commented Apr 15, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

vetler commented Apr 15, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Uh oh!

vetler commented Apr 15, 2026

Uh oh!

allcontributors Bot commented Apr 15, 2026

Uh oh!

vetler commented Apr 15, 2026

Uh oh!

allcontributors Bot commented Apr 15, 2026

Uh oh!

vetler commented Apr 15, 2026

Uh oh!

allcontributors Bot commented Apr 15, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

vetler commented Apr 15, 2026 •

edited

Loading

github-actions Bot commented Apr 15, 2026 •

edited

Loading