Agent skill

PlotJuggler 4 Perf Profiling

by PlotJuggler in PlotJuggler/PlotJuggler

Guides CPU profiling of PlotJuggler 4 on Linux with perf: count first, record cheaply with LBR, then read per-thread, flat, flamegraph or time-window views.

MPL-2.0Auto-check: notesDevelopment

Install PlotJuggler 4 Perf Profiling

skills CLI
$ npx skills add PlotJuggler/PlotJuggler --skill perf-profile -a claude-code

Project install by default; add -g for ~/.claude/skills/.

GitHub CLI
$ gh skill install PlotJuggler/PlotJuggler perf-profile --agent claude-code

Project scope by default; add --scope user for a personal install. Needs GitHub CLI 2.90.0 or later (public preview).

Manual copy
$ git clone --depth 1 https://github.com/PlotJuggler/PlotJuggler.git skills-src && mkdir -p .claude/skills && cp -r skills-src/.claude/skills/perf-profile .claude/skills/perf-profile && rm -rf skills-src

Use ~/.claude/skills/ instead of .claude/skills for a personal install. The folder must contain SKILL.md.

Claude Code skills documentation · loads skills from .claude/skills/

Facts

Skill name
perf-profile
GitHub stars
6.2k
Token cost
~1.6k tokens
SKILL.md length
657 words
Files
2
Skills in repo
4
Repo updated
First seen
Licence
MPL-2.0

At a glance

Guides CPU profiling of PlotJuggler 4 on Linux with perf: count first, record cheaply with LBR, then read per-thread, flat, flamegraph or time-window views.

  • Works in 7 steps: Environment (non-negotiable) → 5 — Count before you sample → Attach and record (default: LBR) → …
  • Plot zooming in PlotJuggler 4 feels sluggish or drops frames
  • SKILL.md covers Overview, Step -1 — Cheap wall-clock A/B…, Step 0 — Environment… and Step 0.5 — Count before you…, plus 6 more sections
  • Runs Shell scripts from its folder

What it does

This skill sets the rules for investigating performance problems in PlotJuggler 4 on Linux, such as sluggish plot zooming, dropped frames, GUI jank, a slower file load or startup, or a suspected regression from a commit. Its recorded failure modes include a 523 MB DWARF perf.data where every report took minutes, a hybrid-CPU event split that hid half the samples, and DWARF stacks that unwound to nothing through stripped Qt. The governing rule is to count first, record cheaply in a single view, unwind exactly once and never re-process.

The steps start with a wall-clock comparison of the same headless load on two builds, since a regression claim is settled by a number rather than a profile. Environment setup, live counting with perf top and perf stat, and recording with perf record follow, using a prime sampling frequency of 997, LBR call graphs and the process pinned to the performance cores so only one PMU is involved. A views.sh helper is included for the per-thread, flat, flamegraph and time-window views.

The recipes are written around the author's own hybrid-core Intel laptop and assume perf_event_paranoid is 1 or lower, otherwise sudo is needed, so CPU ranges and settings may need adjusting on another machine.

When your agent uses it

  • Plot zooming in PlotJuggler 4 feels sluggish or drops frames
  • A file load or startup got slower after a particular commit
  • Turning a perf.data recording into per-thread, flat or flamegraph views
  • Deciding whether a suspected regression is real before capturing a profile

Example prompts

  • “Zooming in PlotJuggler 4 stutters on this layout. Profile it with perf.”
  • “Startup of plotjuggler4 got slower after yesterday's merge. Check whether the regression is real before profiling.”
  • “Give me a flamegraph and a per-thread view from the recording in ~/pjperf.”

Requirements

  • Linux with perf installed
  • A built plotjuggler4 binary
  • perf_event_paranoid at 1 or lower, or sudo

Workflow steps

7 steps, taken from the step headings in SKILL.md.

  1. Environment (non-negotiable)
  2. 5 — Count before you sample
  3. Attach and record (default: LBR)
  4. The ONE unwind pass
  5. Views (text processing only from here)
  6. Off-CPU when on-CPU explains nothing
  7. Interpretation checklist (Qt-specific), stop at first match

What it can do on your machine

Read from SKILL.md and the folder at commit 346dee6. It shows what the files ask for, not the result of running them.

  • Tool permissions

    Pre-approves nothing: there is no allowed-tools line, so your agent's usual permission prompts apply.

    From allowed-tools in the SKILL.md frontmatter.

  • Runs code

    Ships script files (Shell), which the agent can run.

    From the folder's file list and the shell code blocks in SKILL.md.

  • Network

    No URLs in SKILL.md.

    From URLs in SKILL.md, links to its own repository left out.

  • Credentials

    Names no API keys, tokens, secrets or passwords.

    From names ending in _API_KEY, _TOKEN, _SECRET, _KEY or _PASSWORD in SKILL.md.

Context cost

PlotJuggler 4 Perf Profiling loads about 1.6k tokens when it runs. Until then it costs about 91 tokens; SKILL.md has 657 words of instructions outside code blocks.

Always · name and description, kept in context so the agent knows when to use it
~91
When it runs · the whole SKILL.md, loaded when a task matches
~1.6k

Estimates: characters ÷ 4, the usual rule of thumb; real counts depend on the model's tokenizer. Scripts and assets cost tokens only if the agent reads them.

Safety

Auto-check: notes

The automated check noted patterns worth knowing about, such as sudo or a known installer.

  • NoteRuns commands with sudoSKILL.md:20
    `sudo sysctl kernel.perf_event_paranoid=1` for the session.
  • NoteRuns commands with sudoSKILL.md:92
    `sudo offcputime-bpfcc -df -p "$PID" 30` — sudo prompts: hand it to the user.

Automated static check — not a guarantee. Review scripts before installing. It scans the text of SKILL.md for risky patterns (piping downloads into a shell, reading credential files, hidden Unicode, destructive commands); files beside SKILL.md are not scanned.

SKILL.md

The full file from PlotJuggler/PlotJuggler at commit 346dee6, republished under its MPL-2.0 licence (© PlotJuggler). 657 words, ~1,586 tokens.

Download SKILL.mdSave it as .claude/skills/perf-profile/SKILL.md (or your agent's skills folder). This skill also uses 1 other file; get the full folder from GitHub.
name
perf-profile
description
Use for ANY PJ4 performance question on Linux — sluggish plot zooming, dropped frames, GUI jank, a file-load or startup that "got slower", a suspected perf regression from a commit, "why is this slow" — before running `perf record`/`perf report` on plotjuggler4, or when a perf.data recording needs per-thread, flat, flamegraph or time-window views.

CPU profiling PJ4 with perf

Overview

Recorded failure modes: a 523 MB DWARF perf.data where every perf report took minutes; the hybrid-CPU event split silently hiding half the samples behind | head; DWARF user-stacks unwinding to nothing through stripped Qt while LBR resolved full chains (paintGL → QOpenGL2PaintEngineEx → libgallium). The rule: count first, record cheap and single-view, unwind exactly once, never re-process.

This machine: perf 7.0.12, i7-13700H hybrid (cpu_core = CPUs 0-11, cpu_atom = 12-19), Arch LBR depth 32 on both PMUs, tracefs root-only, sudo prompts. Check cat /proc/sys/kernel/perf_event_paranoid first: the recipes below assume ≤1; at ≥3 (the Debian/Ubuntu default) even user-space sampling of your own PID needs sudo or sudo sysctl kernel.perf_event_paranoid=1 for the session.

Step -1 — Cheap wall-clock A/B before any capture

A suspected regression ("load went from 11 s to 38 s since PR #N") is settled by a number, not a profile. Run the same headless load on both builds first; profile only if the delta is real:

bash
/usr/bin/time -v ./build/pj_app/plotjuggler4 --nosplash --layout <layout.pj4.xml> --exit-after-layout
#   -> "Elapsed (wall clock)" + "Maximum resident set size"; repeat on a worktree at the suspect base

Step 0 — Environment (non-negotiable)

bash
export DEBUGINFOD_URLS=          # Qt is stripped + absent from Ubuntu's server: leaving
                                 # this set re-queries the network every report (TTL 600s)
OUT=~/pjperf/$(date +%Y%m%d-%H%M%S); mkdir -p "$OUT"    # /home, NEVER /tmp (tmpfs=RAM)

Step 0.5 — Count before you sample

bash
PID=$(pgrep -x plotjuggler4)
perf top -p "$PID" -F 997                 # live triage, no file
perf stat -p "$PID" -I 1000               # this CPU emits TopdownL1 + IPC for free;
                                          # watch context-switches/s spike at the jank

Step 1 — Attach and record (default: LBR)

bash
taskset -acp 0-11 "$PID"   # pin to P-cores -> ONE PMU -> no hybrid split (unpin to re-verify)
perf record -F 997 --call-graph lbr -N --switch-events -p "$PID" -o "$OUT/rec.data"
  • -F 997 — prime; never 999/1000 (aliases with 60/120/144 Hz refresh → skewed samples).
  • lbr — no frame pointers needed; unwinds through stripped Qt/Mesa; ~20× smaller files.
  • -N — don't copy the ~380 MB binary into ~/.debug; repeated runs fill the disk.
  • --switch-events — free, unprivileged off-CPU timeline (gaps in hotspot's per-thread view).
  • Need >32 frames or a main()-rooted flame graph → --call-graph dwarf,8192 -F 499 instead.
  • Ask for ONE tight interaction (~10-20 s); note wall-clock start/stop for windowing.
  • Few samples? perf record -vv shows the configured freq/period.

Step 2 — The ONE unwind pass

bash
perf script -i "$OUT/rec.data" --header --no-inline \
    -F comm,tid,time,event,ip,sym,dso > "$OUT/all.script"

--inline is on by default and is a top analysis cost — always --no-inline. Sanity-check the events present (two cpu_* lines = the hybrid split is live): grep -oE 'cpu_(core|atom)/[a-z]+/[A-Za-z]*|task-clock' "$OUT/all.script" | sort | uniq -c

Step 3 — Views (text processing only from here)

views.sh beside this file: per-second histogram, per-thread counts, flat leaves, per-TID leaves, time-window cut. Interactive: ~/Apps/hotspot-v1.6.0-x86_64.AppImage "$OUT/rec.data" (per-thread timeline, drag a time range). Folded stacks without Perl: perf report -i "$OUT/rec.data" --no-inline --stdio -g folded,0 (,0 — the default 0.5% threshold silently drops the tail). Caveat: LBR's 32-frame ceiling truncates outer frames, so flame graphs render disconnected towers (hot sub-trees, still readable); record DWARF when a rooted flame graph matters. Never pipe perf report through head — each event section prints separately and you'll read only the first.

Show full SKILL.md (268 more words)Show less

Step 4 — Off-CPU when on-CPU explains nothing

Flat profile but frames still drop → the jank is a wait. --switch-events shows it as gaps in hotspot's GUI-thread band. For the switch-out stacks without root (context-switches is a software event): perf record -e context-switches -c 1 -g --call-graph lbr -p "$PID". Real wait-duration stacks need sudo offcputime-bpfcc -df -p "$PID" 30 — sudo prompts: hand it to the user.

Step 5 — Interpretation checklist (Qt-specific), stop at first match

  1. Which thread? PJ4 names none of its threads (comm = plotjuggler4 for all); named ones are foreign: <app>:gdrv0 = Mesa glthread, QDBusConnection, FFmpeg workers. Kernel frames print as raw 0xffffffff… (kptr_restrict) — ignorable.
  2. GUI thread ≥ ~90% busy, leaves in Qwt/QPainter/paint code → event-loop saturation. On the GL paint engine any per-point QPainter call is the classic cause: path stroking CPU-triangulates, pixmap blits convert+re-upload textures (fresh cacheKey per QPixmap::toImage). Batch the geometry instead.
  3. GUI thread idle but janky → off-CPU (Step 4): swapBuffers/vsync, QMutex, I/O.
  4. Heavy gdrv0/libgallium → driver-side; cross-check ./run.sh --apitrace.
  5. Workers hot, GUI starved → record with --latency, report --latency (parallelism-weighted overhead finds the serialized critical path).

Do NOT try here (verified dead ends)

  • perf record -a, tracepoints (sched:*, --filter), perf sched, perf trace, perf probe — all root-only on this box (perf_event_paranoid ≥1 + tracefs 0700).
  • perf record --off-cpu — perf built without BPF skeletons; flag parses, then refuses.
  • Hunting libunwind — DWARF unwinding here goes through libdw (libunwind: OFF is fine).
  • Rebuilding Qt with frame pointers — LBR already unwinds through Qt; don't.

Performance claims need numbers (see verify-live): before/after sample share of the named symbol, or replot rate ≤60 Hz — and say which views actually ran.

© PlotJuggler, MPL-2.0. Rendered from Markdown: HTML in the file is shown as text, images as links, and headings moved down two levels. Raw file

Files

SKILL.md and 1 other file in .claude/skills/perf-profile of PlotJuggler/PlotJuggler.

  • SKILL.md
  • views.sh

Open the folder on GitHubat commit 346dee6

Compare with similar skills

PlotJuggler 4 Perf Profiling next to the 5 skills that share the most tags, products or categories with it. Stars are the repository's; “used in” counts other GitHub owners with a copy.

PlotJuggler 4 Perf Profiling compared with similar skills
SkillStarsUsed inTokensAuto-checkLicenceRepo updated
PlotJuggler 4 Perf Profiling this skillPlotJuggler/PlotJuggler6.2k—~1.6kAutomated safety check: NotesMPL-2.0
The Art of Debuggingstas00/the-art-of-debugging1.7k—~6.1kAutomated safety check: NotesCC-BY-SA-4.0
Dotnet Debuggingnovotnyllc/dotnet-artisan233—~2.1kAutomated safety check: PassMIT
Kernel Debugging Advancedmohitmishra786/low-level-dev-skills253—~855Automated safety check: PassMIT
Cmux Debugging Guidemanaflow-ai/cmux28k1 repos~1.1kAutomated safety check: PassCustom licence
Electron Heap Snapshot Analysiskeybase/client9.3k—~875Automated safety check: PassBSD-3-Clause

Similar skills

  • The Art of Debugging

    stas00/the-art-of-debugging

    Condensed debugging method and tool recipes for Unix, Python and PyTorch programs: crashes, hangs, segfaults, wrong output, CUDA OOM, NaN values and slowness.

    1.7k GitHub stars~6.1k tokensUpdated today
    DevelopmentAuto-check: notes
  • Dotnet Debugging

    novotnyllc/dotnet-artisan

    Debugs Windows and Linux/macOS applications (native, .NET/CLR, mixed-mode) with WinDbg MCP (crash dumps, !analyze, !syncblk, !dlk, !runaway, !dumpheap, !gcroot, BSOD), dotnet-dump, lldb with SOS…

    233 GitHub stars~2.1k tokensUpdated 1 mo ago
    DevelopmentAuto-check passed
  • Kernel Debugging Advanced

    mohitmishra786/low-level-dev-skills

    Advanced kernel debugging skill for ftrace, trace-cmd, perf, kprobes, kgdb, and crash analysis.

    253 GitHub stars~855 tokensUpdated 3 mo ago
    DevelopmentAuto-check passed
  • Cmux Debugging Guide

    manaflow-ai/cmux

    Covers debug logging, the Debug menu, profiling rules and runtime pitfalls for working on the cmux macOS terminal app.

    28k GitHub starsUsed in 1 repo~1.1k tokens
    DevelopmentAuto-check passed
  • Analyzes V8, Chrome and Electron .heapsnapshot files with Node scripts to find memory leaks, detached DOM nodes and the retainer paths that keep objects alive.

    9.3k GitHub stars~875 tokensUpdated today
    DevelopmentAuto-check passed
  • Issue Fix

    mono/SkiaSharp

    Fix bugs in SkiaSharp C bindings. An agent skill from mono/SkiaSharp.

    5.6k GitHub stars~5.1k tokensUpdated today
    DevelopmentAuto-check passed

More from PlotJuggler/PlotJuggler

  • PlotJuggler 3 to 4 Porting

    PlotJuggler/PlotJuggler

    Directs porting of widgets, dialogs, panels and transforms from PlotJuggler 3 to PlotJuggler 4 by lifting the original files intact and rebinding only the data paths.

    6.2k GitHub stars~1.1k tokensUpdated 6 days ago
    Auto-check passed
  • PlotJuggler Ship Check

    PlotJuggler/PlotJuggler

    Runs a gated finish-line checklist before committing a PlotJuggler PJ4 change: build proof, red-test triage, hooks, docs freshness and a diff self-review.

    6.2k GitHub stars~1.3k tokensUpdated 6 days ago
    Auto-check passed
  • PlotJuggler Live Verification

    PlotJuggler/PlotJuggler

    Confirms that a change to PlotJuggler 4 really works in the running app by proving the rebuild, launching with real data and measuring the result.

    6.2k GitHub stars~956 tokensUpdated 6 days ago
    Auto-check passed

Works with

Categories

Questions about PlotJuggler 4 Perf Profiling

What does PlotJuggler 4 Perf Profiling do?

Guides CPU profiling of PlotJuggler 4 on Linux with perf: count first, record cheaply with LBR, then read per-thread, flat, flamegraph or time-window views. This skill sets the rules for investigating performance problems in PlotJuggler 4 on Linux, such as sluggish plot zooming, dropped frames, GUI jank, a slower file load or startup, or a suspected regression from a commit.data where every report took minutes, a hybrid-CPU event split that hid half the samples, and DWARF stacks that unwound to nothing through stripped Qt.

When should I use PlotJuggler 4 Perf Profiling?

PlotJuggler 4 Perf Profiling fits situations like: plot zooming in PlotJuggler 4 feels sluggish or drops frames; A file load or startup got slower after a particular commit; turning a perf.data recording into per-thread, flat or flamegraph views; deciding whether a suspected regression is real before capturing a profile.

How do I install PlotJuggler 4 Perf Profiling in Claude Code?

Run `npx skills add PlotJuggler/PlotJuggler --skill perf-profile -a claude-code`. Or copy the skill folder (.claude/skills/perf-profile in PlotJuggler/PlotJuggler) into .claude/skills/perf-profile in your project. Claude Code loads it when a task matches its description.

How do I install PlotJuggler 4 Perf Profiling in Codex?

Run `npx skills add PlotJuggler/PlotJuggler --skill perf-profile -a codex`. Or copy the skill folder (.claude/skills/perf-profile in PlotJuggler/PlotJuggler) into .agents/skills/perf-profile in your project. Codex loads it when a task matches its description.

Can I use PlotJuggler 4 Perf Profiling in Cursor, Gemini CLI or GitHub Copilot?

Cursor, Gemini CLI, GitHub Copilot and OpenCode also load SKILL.md folders. With the skills CLI, run `npx skills add PlotJuggler/PlotJuggler --skill perf-profile -a cursor` (or -a gemini-cli, github-copilot or opencode for the others). To copy it by hand, put the folder in .cursor/skills/perf-profile, .gemini/skills/perf-profile, .github/skills/perf-profile and .opencode/skills/perf-profile in your project.

What does PlotJuggler 4 Perf Profiling need to run?

Going by SKILL.md and its folder, PlotJuggler 4 Perf Profiling needs a shell for the scripts in its folder. Our summary lists: Linux with perf installed; A built plotjuggler4 binary; perf_event_paranoid at 1 or lower, or sudo.

Does PlotJuggler 4 Perf Profiling access the network?

SKILL.md contains no URLs. Any network use would come from the scripts or tools the agent runs. This is read from the text; nothing was executed.

Is PlotJuggler 4 Perf Profiling safe to install?

Our automated static check of SKILL.md found notes only (runs commands with sudo), nothing it rates as a warning. It is not a guarantee. Review the folder before installing.

What licence does PlotJuggler 4 Perf Profiling use?

PlotJuggler 4 Perf Profiling is published under the MPL-2.0 licence (the repository's licence). It allows redistribution, so the full SKILL.md is shown on this page.

How many tokens does PlotJuggler 4 Perf Profiling use?

About 1.6k tokens (SKILL.md is roughly 6.3k characters). Agents keep only the skill's name and description in context until a task matches; then they load SKILL.md in full.

What are the alternatives to PlotJuggler 4 Perf Profiling?

Skills that share tags, products or a category with PlotJuggler 4 Perf Profiling: The Art of Debugging (stas00/the-art-of-debugging, 1.7k stars), Dotnet Debugging (novotnyllc/dotnet-artisan, 233 stars), Kernel Debugging Advanced (mohitmishra786/low-level-dev-skills, 253 stars) and Cmux Debugging Guide (manaflow-ai/cmux, 28k stars). The comparison table on this page puts their stars, adoption, token cost, safety result and licence side by side.

Who maintains PlotJuggler 4 Perf Profiling?

PlotJuggler (a GitHub organization) maintains it in PlotJuggler/PlotJuggler, which has 6,233 GitHub stars. The repository holds 4 skills in this directory. The repository was last updated on October 1, 2026.

Source: PlotJuggler/PlotJuggler on GitHub. Facts on this page come from the repository at the commit we read; the author's words are quoted as theirs.