# Golang Pprof Collect

> Collect a Go pprof profile from a running process. Handles Kubernetes port-forwarding, endpoint discovery, and file validation. Supports all pprof profile types (cpu, heap, goroutine, mutex, block, trace, etc.). Use when this capability is needed.

- Skill: `tomevault-io/golang-pprof-collect` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add tomevault-io/golang-pprof-collect`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/golang-pprof-collect/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Product & Planning
- Author: tomevault-io (https://skillmd.com/u/tomevault-io)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/tomevault-io/golang-pprof-collect

---


# Collect a Go pprof Profile

## Step 1 — Determine Profile Type and Endpoint

Ask the user:
1. **Profile type** — one of: `cpu`, `heap`, `goroutine`, `mutex`, `block`, `trace`, `threadcreate`, `allocs`. Default: `heap`.
2. **Do they already have the profile file?** If yes, get the absolute path and stop — this skill is complete.
3. **pprof endpoint URL** (e.g., `http://localhost:8082/debug/pprof/<type>`).

## Step 2 — Kubernetes Port-Forward (if needed)

If the target is running in Kubernetes:

1. Ask for **namespace**, **pod name**, and **metrics port** (the port exposing `/debug/pprof`).
2. Ask for a **local port** (default: same as metrics port).
3. Start the port-forward:
   ```
   kubectl port-forward -n <namespace> <pod> <local-port>:<metrics-port>
   ```
4. Update the endpoint URL to `http://localhost:<local-port>/debug/pprof/<type>`.

## Step 3 — Collect the Profile

Set the output filename: `<type>-<timestamp>.pb.gz` (e.g., `cpu-20250520T1345Z.pb.gz`).

Use whichever tool is available on the system. Prefer `curl`; fall back to alternatives if unavailable.

### CPU profiles (duration-based)
Ask for **duration in seconds** (default: 30). Warn the user the request will block for this duration.
```
# curl
curl -sK -o <output_file> "<endpoint_url>?seconds=<duration>"

# wget
wget -q -O <output_file> "<endpoint_url>?seconds=<duration>"

# go tool pprof (fetches and saves interactively — also opens analysis)
go tool pprof -proto -output <output_file> "<endpoint_url>?seconds=<duration>"

# HTTPie
http --download --output <output_file> "<endpoint_url>?seconds=<duration>"
```

### Heap, mutex, block, allocs, threadcreate profiles (instant snapshot)
```
# curl
curl -sK -o <output_file> "<endpoint_url>"

# wget
wget -q -O <output_file> "<endpoint_url>"

# go tool pprof
go tool pprof -proto -output <output_file> "<endpoint_url>"

# HTTPie
http --download --output <output_file> "<endpoint_url>"
```

### Goroutine profiles
Collect the pb.gz:
```
# curl
curl -sK -o <output_file> "<endpoint_url>"

# wget
wget -q -O <output_file> "<endpoint_url>"

# go tool pprof
go tool pprof -proto -output <output_file> "<endpoint_url>"

# HTTPie
http --download --output <output_file> "<endpoint_url>"
```

Also collect a debug=2 text dump (better for leak detection — shows goroutine IDs, ages, and states):
```
# curl
curl -sK -o goroutine-debug2-<timestamp>.txt "<endpoint_url>?debug=2"

# wget
wget -q -O goroutine-debug2-<timestamp>.txt "<endpoint_url>?debug=2"

# HTTPie
http --download --output goroutine-debug2-<timestamp>.txt "<endpoint_url>?debug=2"
```

### Trace profiles (duration-based)
Ask for **duration in seconds** (default: 5).
```
# curl
curl -sK -o <output_file> "<endpoint_url>?seconds=<duration>"

# wget
wget -q -O <output_file> "<endpoint_url>?seconds=<duration>"

# go tool pprof
go tool pprof -proto -output <output_file> "<endpoint_url>?seconds=<duration>"

# HTTPie
http --download --output <output_file> "<endpoint_url>?seconds=<duration>"
```

## Step 4 — Validate

1. Confirm the output file exists and is non-empty:
   ```
   // turbo
   ls -la <output_file>
   ```
2. If the file is empty or missing, report the error and suggest checking:
   - Is the endpoint correct?
   - Is the port-forward still running?
   - Does the process have pprof enabled (`import _ "net/http/pprof"`)?
3. Report the absolute path of the collected file(s) to the user.

---
> Source: [rumstead/golang-pprof-skills](https://github.com/rumstead/golang-pprof-skills) — distributed by [TomeVault](https://tomevault.io).
<!-- tomevault:4.0:skill_md:2026-06-16 -->