# Golang Profile Heap

> Analyze a Go heap profile (pprof). Runs go tool pprof to extract top consumers, call graphs, and actionable findings. Requires a .pb.gz file — use golang-pprof-collect to obtain one. Use when this capability is needed.

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

---


# Heap Profile Analysis

## Step 1 — Obtain the Profile

Ask the user for the absolute path to a heap profile file (`.pb.gz`).

If they don't have one, run the **golang-pprof-collect** skill with profile type `heap` to collect it first, then return here with the file path.

## Step 2 — Extract Profile Data

Run these `go tool pprof` commands against the `.pb.gz` file. Capture all output for analysis.

**Top by flat inuse_space (default):**
```
// turbo
go tool pprof -top -inuse_space <profile_path>
```

**Top by cumulative inuse_space:**
```
// turbo
go tool pprof -top -cum -inuse_space <profile_path>
```

**Top by inuse_objects (object count pressure):**
```
// turbo
go tool pprof -top -inuse_objects <profile_path>
```

**Top by alloc_space (total allocations over lifetime):**
```
// turbo
go tool pprof -top -alloc_space <profile_path>
```

**Text call graph for the top flat consumer:**
After identifying the top function from flat inuse_space, run:
```
// turbo
go tool pprof -text -focus=<top_function_package_prefix> -inuse_space <profile_path>
```

## Step 3 — Analyze and Report

Produce a structured analysis with these sections:

### Summary
- Total inuse memory, total objects
- Profile timestamp and binary info

### Top Consumers (inuse_space flat)
Table: rank, function, flat MB, flat%, cum MB, cum%

### Hot Allocation Paths (alloc_space)
Identify functions with high alloc_space but low inuse_space — these indicate high churn / GC pressure.

### Object Count Pressure (inuse_objects)
Flag functions holding large numbers of small objects — these stress the GC scanner.

### Call Chain Analysis
For the top 3-5 consumers, trace the cumulative call chain and identify:
- Which top-level operation drives the allocation (e.g., sync, reconcile, cache refresh)
- Whether the allocation is retained (leak-like) vs transient

### Actionable Findings
For each major consumer, suggest:
- Whether it's expected or anomalous
- Possible mitigations (pooling, reducing copy, caching, streaming, config knobs)
- If it's in a third-party library, note that and suggest upstream or wrapper-level fixes

### Follow-up Commands
Suggest any additional pprof commands that would help (e.g., `-focus`, `-ignore`, diff between two profiles, flamegraph via `go tool pprof -http=:9090`).

---
> 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 -->