Go Performance

Go Performance Patterns

Resource Routing

• scripts/bench-compare.sh - Run when comparing benchmark results, saving baselines, or producing JSON benchmark metadata.
• references/BENCHMARKS.md - Read when writing benchmarks, using benchstat, or profiling with pprof.
• references/STRING-OPTIMIZATION.md - Read when optimizing string conversion, concatenation, or byte/string boundaries.

Performance-specific guidelines apply only to the hot path. Don't prematurely optimize—focus these patterns where they matter most.

---

Prefer strconv over fmt

When converting primitives to/from strings, strconv is faster than fmt:

s := strconv.Itoa(rand.Int()) // ~2x faster than fmt.Sprint()

---

Avoid Repeated String-to-Byte Conversions

Convert a fixed string to []byte once outside the loop:

data := []byte("Hello world")
for b.Loop() { // Go 1.24+; use b.N loops only for older Go
    w.Write(data) // ~7x faster than []byte("...") each iteration
}

---

Prefer Specifying Container Capacity

Specify container capacity where possible to allocate memory up front. This minimizes subsequent allocations from copying and resizing as elements are added.

Map Capacity Hints

Provide capacity hints when initializing maps with make():

m := make(map[string]os.DirEntry, len(files))

Note: Unlike slices, map capacity hints do not guarantee complete preemptive allocation—they approximate the number of hashmap buckets required.

Slice Capacity

Provide capacity hints when initializing slices with make(), particularly when appending:

data := make([]int, 0, size)

Unlike maps, slice capacity is not a hint—the compiler allocates exactly that much memory. Subsequent append() operations incur zero allocations until capacity is reached.

The capacity version is ~12x faster due to zero reallocations during append.

---

Pass Values

Don't pass pointers as function arguments just to save a few bytes. If a function refers to its argument x only as *x throughout, then the argument shouldn't be a pointer.

func process(s string) { // not *string — strings are small fixed-size headers
    fmt.Println(s)
}

Common pass-by-value types: string, io.Reader, small structs.

Exceptions:

• Large structs where copying is expensive
• Small structs that might grow in the future

---

String Concatenation

Choose the right strategy based on complexity:

---

Benchmarking and Profiling

Always measure before and after optimizing. Use Go's built-in benchmark framework and profiling tools.

go test -bench=. -benchmem -count=10 ./...

Validation: After applying optimizations, run bash scripts/bench-compare.sh to measure the actual impact. Only keep optimizations with measurable improvement.

---

Quick Reference

---

Related Skills

• Data structures: See go-data-structures when choosing between slices, maps, and arrays, or understanding allocation semantics
• Declaration patterns: See go-declarations when using make with capacity hints or initializing maps and slices
• Concurrency: See go-concurrency when parallelizing work across goroutines or using sync.Pool for buffer reuse
• Style principles: See go-style-core when deciding whether an optimization is worth the readability cost

Benchmark Methodology

Contents

• Writing Benchmarks
• Running Benchmarks
• Interpreting Results
• Using benchstat for Comparison
• Benchmark Examples from Performance Patterns
• Profiling with pprof
• Common Mistakes

Writing Benchmarks

Go benchmarks use the testing.B type and live in _test.go files. Function names must start with Benchmark. On Go 1.24+, prefer b.Loop().

func BenchmarkStrconv(b *testing.B) {
    for b.Loop() {
        s := strconv.Itoa(rand.Int())
        _ = s
    }
}

func BenchmarkFmtSprint(b *testing.B) {
    for b.Loop() {
        s := fmt.Sprint(rand.Int())
        _ = s
    }
}

Key rules:

• Use b.Loop() on Go 1.24+; use for i := 0; i < b.N; i++ only when

maintaining older Go versions

• Assign results to a variable (or _) to prevent the compiler from

optimizing away the call

• Use b.ResetTimer() after expensive setup that shouldn't be measured
• Use b.ReportAllocs() or the -benchmem flag for allocation tracking

Sub-benchmarks

func BenchmarkConvert(b *testing.B) {
    for _, size := range []int{10, 100, 1000} {
        b.Run(fmt.Sprintf("size=%d", size), func(b *testing.B) {
            data := make([]byte, size)
            b.ResetTimer()
            for b.Loop() {
                _ = string(data)
            }
        })
    }
}

---

Running Benchmarks

# Run all benchmarks in a package
go test -bench=. ./...

# Run specific benchmark with memory stats
go test -bench=BenchmarkStrconv -benchmem ./...

# Run with count for statistical significance
go test -bench=. -benchmem -count=10 ./...

The -benchmem flag reports allocations per operation. The -count flag runs each benchmark N times for statistical significance.

---

Interpreting Results

BenchmarkStrconv-8     18705042    64.2 ns/op    16 B/op    1 allocs/op
BenchmarkFmtSprint-8    8249536   143.0 ns/op    16 B/op    2 allocs/op

---

Using benchstat for Comparison

benchstat compares benchmark results statistically. Install it and save benchmark output to files:

# Install benchstat
go install golang.org/x/perf/cmd/benchstat@latest

# Run benchmarks and save results
go test -bench=. -benchmem -count=10 ./... > old.txt

# Make changes, then run again
go test -bench=. -benchmem -count=10 ./... > new.txt

# Compare results
benchstat old.txt new.txt

Interpreting benchstat Output

name          old time/op    new time/op    delta
Strconv-8     64.2ns ± 2%    61.8ns ± 1%   -3.74%  (p=0.001 n=10+10)

• delta: Percentage change (negative = faster)
• p-value: Statistical significance (p < 0.05 is significant)
• n: Number of valid samples used

Tips:

• Always use -count=10 or higher for reliable results
• A small p-value confirms the change is real, not noise
• If benchstat shows ~ (tilde), the difference is not statistically

significant

---

Benchmark Examples from Performance Patterns

strconv vs fmt

Repeated Byte Conversions

func BenchmarkRepeatedConversion(b *testing.B) {
    var buf bytes.Buffer
    for b.Loop() {
        buf.Write([]byte("Hello world"))
    }
}

func BenchmarkSingleConversion(b *testing.B) {
    var buf bytes.Buffer
    data := []byte("Hello world")
    for b.Loop() {
        buf.Write(data)
    }
}

Slice Capacity

func BenchmarkNoCapacity(b *testing.B) {
    for b.Loop() {
        data := make([]int, 0)
        for k := 0; k < 1000; k++ {
            data = append(data, k)
        }
    }
}

func BenchmarkWithCapacity(b *testing.B) {
    for b.Loop() {
        data := make([]int, 0, 1000)
        for k := 0; k < 1000; k++ {
            data = append(data, k)
        }
    }
}

---

Profiling with pprof

Use pprof to identify bottlenecks before optimizing. Benchmarks measure improvement; pprof finds where to improve.

CPU Profiling

# Generate a CPU profile from benchmarks
go test -bench=BenchmarkHotPath -cpuprofile=cpu.prof ./...

# Analyze with pprof
go tool pprof cpu.prof

Common pprof commands:

(pprof) top10          # Top 10 functions by CPU time
(pprof) list funcName  # Annotated source for a function
(pprof) web            # Interactive graph in browser

Memory Profiling

# Generate a memory profile
go test -bench=BenchmarkHotPath -memprofile=mem.prof ./...

# Analyze allocations
go tool pprof -alloc_space mem.prof

HTTP Profiling for Running Services

import _ "net/http/pprof"

func main() {
    go func() {
        log.Println(http.ListenAndServe("localhost:6060", nil))
    }()
    // ... application code ...
}

Access profiles at http://localhost:6060/debug/pprof/.

Profiling Workflow

1. Benchmark the suspected hot path 2. Profile with pprof to confirm where time is spent 3. Optimize using patterns from this skill 4. Re-benchmark to verify improvement with benchstat 5. Re-profile to check for new bottlenecks

---

Common Mistakes

Ignoring the benchmark loop

The testing framework adjusts iteration counts to get stable timing. Using a fixed iteration count produces meaningless results:

// Bad: Ignores the benchmark loop, so the framework can't calibrate
func BenchmarkFixed(b *testing.B) {
    for i := 0; i < 1000; i++ {
        doWork()
    }
}

// Good: Use b.Loop on Go 1.24+
func BenchmarkCorrect(b *testing.B) {
    for b.Loop() {
        doWork()
    }
}

Not preventing compiler elision

If the result of a function call is unused, the compiler may optimize the call away entirely. Assign results to a package-level variable:

// Bad: Compiler may optimize away the call
func BenchmarkElided(b *testing.B) {
    for b.Loop() {
        expensiveFunc()
    }
}

// Good: Assign to package-level var to prevent elision
var benchResult int

func BenchmarkKept(b *testing.B) {
    var r int
    for b.Loop() {
        r = expensiveFunc()
    }
    benchResult = r
}

String Optimization Patterns

strconv vs fmt

When converting primitives to/from strings, strconv is faster than fmt because fmt uses reflection and handles arbitrary types.

Benchmark snippets use b.Loop(), available in Go 1.24 and newer. For older Go versions, use for i := 0; i < b.N; i++.

Bad:

for b.Loop() {
    s := fmt.Sprint(rand.Int())
}

Good:

for b.Loop() {
    s := strconv.Itoa(rand.Int())
}

Benchmark comparison:

Common conversions:

---

Repeated String-to-Byte Conversions

Do not create byte slices from a fixed string repeatedly. Instead, perform the conversion once and capture the result.

Bad:

for b.Loop() {
    w.Write([]byte("Hello world"))
}

Good:

data := []byte("Hello world")
for b.Loop() {
    w.Write(data)
}

Benchmark comparison:

The good version is ~7x faster because it avoids allocating a new byte slice on each iteration.

---

String Concatenation

Choose the right string building strategy based on complexity.

Use + for Simple Cases

key := "projectid: " + p

The + operator is efficient for a small, fixed number of strings. The compiler can often optimize adjacent string literals.

Use fmt.Sprintf for Formatting

// Good: clear formatting
str := fmt.Sprintf("%s [%s:%d]-> %s", src, qos, mtu, dst)

// Bad: + with manual conversions
str := src.String() + " [" + qos.String() + ":" + strconv.Itoa(mtu) + "]-> " + dst.String()

When writing to an io.Writer, use fmt.Fprintf directly instead of building a temporary string with fmt.Sprintf.

Use strings.Builder for Piecemeal Construction

strings.Builder takes amortized linear time, whereas repeated + or fmt.Sprintf take quadratic time when building a large string:

b := new(strings.Builder)
for i, d := range digitsOfPi {
    fmt.Fprintf(b, "the %d digit of pi is: %d\n", i, d)
}
str := b.String()

Use Backticks for Constant Multi-line Strings

// Good: raw string literal
usage := `Usage:

custom_tool [args]`

// Bad: concatenation with escape sequences
usage := "" +
    "Usage:\n" +
    "\n" +
    "custom_tool [args]"

Strategy Summary