agentleFS
Sign inStart free
narenaryannarenaryan/agent-skills/skills/go/go-pprof-profiling/SKILL.md

go-pprof-profiling

Skill0 starsChanged 39 days agoMITView on GitHub

Use when profiling Go programs with pprof — CPU hotspots, allocation rates, GC pressure, lock contention, or goroutine leaks; covers profile types (cpu/heap/block/mutex/goroutine), go tool pprof interactive commands, flat vs cum, differential profiles with -base, and sample_index for inuse vs alloc

The file

We split this skill into the rules it gives an agent

2 rules. About 0 are common, 0 are distinctive, and 2 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈0

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 2

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    Use -diff_base when run durations differ — it compares rates, not absolutes.

    line 61
  2. Very specific:

    Heap sampling misses small hot allocations: default rate 512 KB. Set runtime.MemProfileRate = 1 in tests only.

    line 65

≈ “Common” is an estimate: at least 1 in 5 of the 350,495 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Go pprof Profiling

Sampling profiler. Flat = samples in the function itself; cum = samples in the function plus everything it called. Heap is approximate (1 sample per ~512 KB by default) — small hot allocations vanish.

Profile types

ProfileEndpointMeasures
cpu/debug/pprof/profile?seconds=30wall-clock samples at 100 Hz
heap/debug/pprof/heaplive + cumulative allocations
goroutine/debug/pprof/goroutineall goroutine stacks (leak hunt)
block/debug/pprof/blocktime blocked on sync primitives
mutex/debug/pprof/mutexcontention on Lock/Unlock
trace/debug/pprof/trace?seconds=5full execution trace (go tool trace)

Block/mutex are off by default — enable at startup:

runtime.SetBlockProfileRate(1)       // every blocking event
runtime.SetMutexProfileFraction(1)   // every contention event

Install endpoints: import _ "net/http/pprof" then serve on localhost:6060.

Heap sample index

-sample_index=UnitsUse for
alloc_spacebytes allocated (lifetime)GC pressure, hotspots
alloc_objectsallocations (lifetime)churn count
inuse_spacelive bytes (default)heap footprint
inuse_objectslive objectsleak candidates

Allocation hotspots are invisible in the default inuse_space view — switch to alloc_objects.

Interactive commands

CommandWhat
top / top -cumrank by flat / cumulative
list FuncREsource lines with sample counts
weblist FuncREsource + disasm in browser
peek FuncREcallers and callees
focus=RE / ignore=RE / hide=REregex filter on stack
tagfocus=k=vfilter on profile labels
nodefraction=0.05hide nodes <5% cumulative

Differential profiling

go tool pprof -base v1.pb.gz v2.pb.gz         # subtract; negatives = improvements
go tool pprof -diff_base v1.pb.gz v2.pb.gz    # subtract then normalize to zero total
go tool pprof -http=localhost:8080 -base v1 v2

Use -diff_base when run durations differ — it compares rates, not absolutes.

Pitfalls

  • Heap sampling misses small hot allocations: default rate 512 KB. Set runtime.MemProfileRate = 1 in tests only.
  • Inlining hides callees: inlined functions vanish; samples attribute to the caller. Use list for per-line, or //go:noinline while profiling.
  • -http binds all interfaces: pass -http=localhost:8080 or the UI is exposed externally.
  • CPU frequency scaling skews timing: pin governor to performance for reproducible CPU profiles.
  • Unoptimized binary: -gcflags=all=-N -l produces misleading hotspots — profile optimized builds only.
  • -base with different sample rates: heap profiles must share MemProfileRate, or the diff is meaningless.
  • goroutine profile is stop-the-world: expensive on busy servers.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

Check your setup, free