# Golang Profile Cpu

> Analyze a Go CPU profile (pprof). Runs go tool pprof to extract hot functions, 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-cpu` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add tomevault-io/golang-profile-cpu`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/golang-profile-cpu/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-cpu

---


# CPU Profile Analysis

## Step 1 — Obtain the Profile

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

If they don't have one, run the **golang-pprof-collect** skill with profile type `cpu` 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 CPU time:**
```
// turbo
go tool pprof -top <profile_path>
```

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

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

**Peek at top cumulative functions (shows callers/callees inline):**
```
// turbo
go tool pprof -peek=<top_cum_function> <profile_path>
```

## Step 3 — Analyze and Report

Produce a structured analysis with these sections:

### Summary
- Total CPU sample duration and sample count
- Profile timestamp and binary info

### Top CPU Consumers (flat)
Table: rank, function, flat time, flat%, cum time, cum%

### Top Cumulative Consumers
Functions that are expensive in aggregate even if individually cheap — identifies hot call paths.

### Concurrency & Lock Contention Indicators
Flag `runtime.` functions that indicate contention:
- `runtime.mallocgc` — allocation-heavy
- `runtime.gcBgMarkWorker` — GC pressure (cross-reference with heap profile)
- `runtime.lock` / `runtime.unlock` — lock contention
- `runtime.futex` / `runtime.semacquire` — synchronization waits
- `runtime.chanrecv` / `runtime.chansend` — channel bottlenecks

### Call Chain Analysis
For the top 3-5 consumers, trace the cumulative call chain to identify which top-level operation is responsible.

### Actionable Findings
For each major consumer, suggest:
- Whether the CPU usage is expected given the workload
- Algorithmic improvements (caching results, reducing serialization, batching)
- Concurrency improvements (reducing lock scope, sharding, buffered channels)
- Config knobs that may reduce pressure

### Follow-up Commands
Suggest additional pprof commands:
- `-focus` / `-ignore` for drilling into specific subsystems
- Flamegraph: `go tool pprof -http=:9090 <profile_path>`
- Diff between two CPU profiles: `go tool pprof -base=<baseline> <current>`

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