golang-profile-heap

name	golang-profile-heap
description	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.
version	1.0.0
category	performance-analysis
tags	["go","pprof","heap","memory","gc-pressure"]
tools	["go (go tool pprof)"]
inputs	["Heap profile file (.pb.gz)"]
outputs	["Top memory consumers (inuse_space, inuse_objects, alloc_space)","Hot allocation paths and GC pressure indicators","Call chain analysis","Actionable optimization recommendations"]
depends_on	["golang-pprof-collect (for profile collection)"]

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