performance-profiling

Files (1)

• SKILL.md

SKILL.md (first lines)

# Performance Profiling

## Core Principle: Measure First

Never optimize without data. Gut-feeling optimization leads to wasted effort on non-bottlenecks. Always follow this sequence:

1. Define a measurable performance goal (e.g., "page load under 2 seconds on 3G").
2. Measure current performance with appropriate tooling.
3. Identify the actual bottleneck from profiling data.
4. Apply a targeted fix.
5. Re-measure to confirm improvement.
6. Repeat until the goal is met.

## Bottleneck Categories

Before diving into tools, classify the bottleneck you are investigating:

| Category | Symptoms | Key Metrics | Common Causes |
|----------|----------|-------------|---------------|
| CPU | High CPU usage, slow computation | CPU time, flame graph hot paths | Tight loops, unoptimized algorithms, excessive parsing |
| Memory | Growing memory footprint, OOM errors | Heap size, allocation rate, GC pauses | Memory leaks, large object graphs, unbounded caches |
| I/O (Disk) | Slow reads/writes, high iowait | IOPS, throughput, latency | Synchronous file ops, missing buffering, excessive logging |
| Network | High latency, timeouts | RTT, TTFB, bandwidth utilization | Chatty APIs, missing compression, no connection reuse |
| Database | Slow queries, connection exhaustion | Query time, lock contention, pool usage | Missing indexes, N+1 queries, full table scans |

## Browser Performance Profiling

### Chrome DevTools Performance Tab

Use the Performance tab to capture a runtime profile:

1. Open DevTools (`Cmd+Option+I` / `Ctrl+Shift+I`).
2. Go to the **Performance** tab.
3. Click **Record**, perform the user action, then **Stop**.
4. Analyze the flame chart for long tasks (anything over 50ms blocks the main thread).
5. Check the **Summary** pane for a breakdown of Scripting, Rendering, Painting, and Idle time.

Key things to look for:

- Long Tasks (red corners in the timeline) blocking user interaction.
- Layout thrashing — repeated forced reflows from interleaved reads and writes.
- Excessive paint regions — use the **Rendering** drawer to enable Paint Flashing.

### Core Web Vitals

| Metric | What It Measures | Good | Needs Improvement | Poor |
|--------|-----------------|------|-------------------|------|
| LCP (Largest Contentful Paint) | Loading performance | <= 2.5s | <= 4.0s | > 4.0s |
| FID (First Input Delay) | Interactivity | <= 100ms | <= 300ms | > 300ms |
| INP (Interaction to Next Paint) | Responsiveness | <= 200ms | <= 500ms | > 500ms |
| CLS (Cumulative Layout Shift) | Visual stability | <= 0.1 | <= 0.25 | > 0.25 |

Common fixes by metric:

- **LCP**: Optimize the critical rendering path, preload hero images, use `fetchpriority="high"` on LCP elements, server-side render above-the-fold content.
- **FID / INP**: Break up long tasks with `requestIdleCallback` or `scheduler.yield()`, defer non-critical JavaScript, use web workers for heavy computation.
- **CLS**: Set explicit `width` and `height` on images and embeds, avoid injecting content above existing content, use `transform` animations instead of layout-triggering properties.

### Lighthouse

Run Lighthouse audits from DevTools, CLI, or CI:

```bash
# CLI usage
npx lighthouse https://example.com --output=json --output-path=./report.json

# CI-friendly with budget assertions
npx lighthouse https://example.com --budget-path=./budget.json
```

Example performance budget file (`budget.json`):

```json
[
  {
    "resourceSizes": [
      { "resourceType": "script", "budget": 300 },
      { "resourceType": "image", "budget": 200 },
      { "resourceType": "total", "budget": 800 }
    ],
    "resourceCounts": [
      { "resourceType": "third-party", "budget": 5 }
    ]
  }
]
```

## Backend Profiling

### Flame Graphs

Flame graphs visualize call stacks with width proportional to time spent. Generate them for your runtime:

```bash
# Node.js — built-in profiler
node --prof app.js
node --prof-process isolate-*.log > processed.txt

# Node.js — 0x for flame graphs
npx 0x app.js

# Python — py-spy (no code changes needed)
py-spy record -o profile.svg -- python app.py

# Go — built-in pprof
import _ "net/http/pprof"
# then visit http://localhost:6060/debug/pprof/profile?seconds=30
go tool pprof -http=:8080 profile.pb.gz
```

### Database Query Analysis

Always use `EXPLAIN` (or `EXPLAIN ANALYZE`) before optimizing queries:

```sql
-- PostgreSQL
EXPLAIN ANALYZE
SELECT u.name, COUNT(o.id)
FROM users u

From Claude-Code-Community-Ireland/claude-code-resources, MIT.

More from Claude-Code-Community-Ireland/claude-code-resources