golang-profile-goroutine

name	golang-profile-goroutine
description	Analyze a Go goroutine profile (pprof). Extracts goroutine counts, blocking stacks, and leak indicators. Requires a .pb.gz and/or debug=2 text dump — use golang-pprof-collect to obtain them.
version	1.0.0
category	performance-analysis
tags	["go","pprof","goroutine","concurrency","leak-detection"]
tools	["go (go tool pprof)"]
inputs	["Goroutine profile file (.pb.gz)","AND/OR debug=2 text dump (.txt)"]
outputs	["Goroutine count and state breakdown","Goroutine groups by stack signature","Leak indicators and growth analysis","Blocking and contention hotspots","Actionable fix recommendations"]
depends_on	["golang-pprof-collect (for profile collection)"]

Goroutine Profile Analysis

Step 1 — Obtain the Profile

Ask the user for the absolute path to a goroutine profile. They may have:

• A .pb.gz file (machine-parseable, used with go tool pprof)
• A debug=2 text dump (human-readable, shows goroutine IDs, ages, and states — better for leak detection)
• Both (preferred)

If they don't have either, run the golang-pprof-collect skill with profile type goroutine to collect them first. That skill will produce both the .pb.gz and debug=2 dump. Return here with the file path(s).

Step 2 — Extract Profile Data

If pb.gz is available:

Top goroutine stacks by count:

// turbo
go tool pprof -top <profile_path>

Top by cumulative (shows which entry points spawn the most goroutines):

// turbo
go tool pprof -top -cum <profile_path>

Text call graph:

// turbo
go tool pprof -text <profile_path>

If debug=2 text dump is available:

Read the file directly. Parse:

• Total goroutine count (first line: goroutine profile: total NNNN)
• Group goroutines by stack signature
• Note goroutine ages (N minutes in the header line)

Step 3 — Analyze and Report

Produce a structured analysis with these sections:

Summary

• Total goroutine count
• Breakdown by state: running, runnable, IO wait, chan receive, chan send, select, semacquire, sleep

Goroutine Groups (by stack)

Table: count, state, top stack frames (3-4 lines), likely purpose

Sort by count descending. Group identical stacks.

Leak Indicators

Flag goroutine groups that suggest leaks:

• High count + chan receive/select: Goroutines stuck waiting on channels that may never be signaled
• High count + IO wait on same address: Connection pool exhaustion or stuck HTTP requests
• Long-lived goroutines (debug=2 shows age): Goroutines running for hours/days that aren't expected to be long-lived
• Growing count between snapshots: If user provides two dumps, diff the counts

Blocking / Contention Hotspots

• Goroutines in semacquire / lock — contention on mutexes
• Goroutines in runtime.gopark via sync.(*Cond).Wait — condition variable waits
• Goroutines in runtime.netpollblock — network IO stalls

Actionable Findings

For each concerning group:

• Identify the code path responsible
• Suggest whether it's expected (e.g., watch goroutines, worker pools) or a leak
• Recommend fixes (context cancellation, bounded worker pools, timeouts)

Follow-up Commands

• Suggest collecting a second snapshot after N minutes and diffing to confirm growth
• Mutex profile: curl -sK -o mutex.pb.gz "<endpoint>/debug/pprof/mutex" if contention is suspected
• Block profile: curl -sK -o block.pb.gz "<endpoint>/debug/pprof/block" if blocking is suspected