go-optimization-guide: a pattern catalog for Go services, and the benchmark harness behind it

A guide, not a library: what the repository actually contains

The Go Optimization Guide is described in the README as a collection of technical articles designed to help you build faster, more efficient Go applications, with the stated audience being developers of high-throughput APIs, microservices and distributed systems. The promise is practical optimization patterns, real-world examples and insight into Go performance.

What that means in the tree is worth being precise about. The repository is mostly Markdown: docs/ holds the article sources, mkdocs.yml and config.yaml drive the site build, and the root README is a short contributor guide rather than a product description. The primary language of the project is Markdown, and the licence is CC-BY-4.0, which is a content licence rather than a software licence. There is no importable package here, no versioned API and no release artefact.

Two supporting pieces break that pattern. There is a go.mod and a go.sum at the root, and a perf-tracking/ directory. The module path is github.com/astavonin/go-optimization-guide, and it requires golang.org/x/exp and golang.org/x/sync directly, which tells you the Go code in the repository is runnable rather than illustrative. The indirect dependencies in that same file are the more revealing part: quic-go, google/pprof, ginkgo, go.uber.org/mock, x/net, x/crypto, x/tools and x/mod. A QUIC implementation, a profiling library and a mocking framework together suggest the repository measures network and protocol behaviour under a test harness rather than merely printing numbers in prose.

The site is published at goperf.dev, and the README links to it as the primary entry point.

Building the site locally with env.sh and mkdocs serve

The contributing workflow is documented in enough detail to be reproducible, which is unusual and useful for a documentation project. The site is built with MkDocs using the Material theme, and the README gives a two step local setup.

The first step runs a provided script that sets up a Python virtual environment and installs the dependencies:

source ./env.sh

The second step starts the local server:

mkdocs serve

After that the site is served at http://localhost:8000, and the README links to it directly. A live reload server means you can edit an article in docs/ and see the rendered result immediately, which is the whole point of running it locally rather than reading the published version.

The dependency list in requirements.txt shows what the site build actually needs: mkdocs and mkdocs-material for the core, plus mkdocs-glightbox for the image lightbox, mkdocs-git-revision-date-localized-plugin for dated revision notes in the page footer, mkdocs-include-markdown-plugin for pulling shared snippets into articles, and mkdocs-rss-plugin for a feed. The include plugin is a small but telling detail: it implies a set of snippets shared across multiple articles, which is a pattern for a guide that wants the same caveat or setup fragment to appear in several places without drifting.

The revision date plugin is the other one worth naming, because it means each page carries the date of the commit that last touched it. For an article collection where advice ages with the Go release cycle, that is more than decoration.

The perf-tracking directory is where the numbers would come from

The perf-tracking/ directory is the part of the repository that distinguishes this guide from a prose collection, and it deserves to be read before the articles rather than after.

The go.mod file is the evidence. The direct requirements are golang.org/x/exp and golang.org/x/sync, and the indirect list pulls in github.com/quic-go/quic-go at v0.52.0, github.com/google/pprof, github.com/onsi/ginkgo/v2, go.uber.org/mock, and the golang.org/x set of crypto, net, sys, tools and mod. pprof is Go's profiling library, so the harness can capture and compare profiles. Ginkgo is a test framework built for suites, and go.uber.org/mock is a mocking library, which is what you need to isolate the system under test from the network. quic-go is a QUIC implementation in Go, and its presence in the dependency graph suggests the guide measures protocol level behaviour, not just function call cost.

Taken together, those dependencies describe a benchmark harness that runs under a test suite, stubs out the environment it does not want to measure, profiles the parts it does, and can compare protocol implementations against each other. The module declares Go 1.24.0.

What the README does not say is how to run the harness. There is no documented command for the perf-tracking directory, no description of the scenarios it covers, and no statement about whether the results are recorded somewhere you can read. The directory name and the dependency graph are strong hints, but they are hints rather than instructions, and anyone planning to cite figures from this guide should confirm what the harness actually measures before repeating a number.

Why a guide rather than a profiler: the alternative approach

The obvious alternative to a curated pattern guide is to profile your own code. That is not a competing product so much as a different way of answering the same question, and understanding the difference explains what a guide is worth.

Profiling is a measurement of your system on your hardware, at the moment you run it. It tells you where time went in that request path, on that machine, with that data. It is authoritative for the code you have and blind to the code you have not written yet.

A guide is a catalogue of known-good approaches, written ahead of your problem. Its value is that it names the things you would not think of: the allocation patterns that matter in Go, the shape of a well-behaved server, the trade-off behind a particular concurrency decision. The cost is that its claims are context-free. A pattern that is right for a throughput-oriented service can be wrong for a low latency one, and only your own measurements settle that.

The pragmatic approach is to use both, and the order matters. Read the guide to know which questions to ask, then answer them with pprof on your own binary. The harness in perf-tracking is a third path, useful when you want a controlled comparison rather than a diagnosis, for example two protocol implementations measured under the same conditions. The go.mod dependency list already contains the pprof and ginkgo ingredients, so the repository itself assumes you will do the measuring part.

Maintenance, contribution flow, and the absence of releases

The repository is not archived and the last push was on 2026-09-05, so the content is being worked on rather than frozen. There are, however, no GitHub releases for this project, which is normal for a documentation site that is read at goperf.dev rather than installed. The way you consume a change is by reading the site or pulling the main branch.

The contribution path is stated plainly: open a pull request or create an issue in the repository to propose changes or suggest new topics. The presence of a .github/ directory alongside the publish-latest workflow badge at the top of the README indicates that publication runs from CI, and the workflow name publish-latest suggests the site is deployed from the latest state of the main branch rather than from a tagged release.

That arrangement has an upside and a downside. The upside is that there is no version skew between the guide and the site you read, and corrections land without a release process. The downside is that content can change under you: an article you linked to may be rewritten, and the per-page revision date from mkdocs-git-revision-date-localized-plugin is the only way to tell what changed when.

The licence is CC-BY-4.0, and it is a licence for content rather than for code. The repository carries a LICENSE file, and the README links to it. For reuse this distinction matters: quoting the prose in a design document or a blog post with attribution is what the licence is designed for, while the Go code under perf-tracking/ is a separate question that the repository does not spell out. If you intend to lift code from the harness into your own project, check the terms on that file directly.

What to check before you quote this guide in a design review

There is a version sensitivity problem that the repository does not discuss. A pattern guide about Go performance is only as current as the toolchain it was written against. The module requires Go 1.24.0, so the code in the repository targets a recent release, but the articles themselves span a period of time during which the Go runtime, the garbage collector and the standard library have all moved.

The practical consequence is that a recommendation such as a particular concurrency pattern or a particular buffer size needs checking against the Go version your service actually builds with, and against the standard library of that version. Nothing in the README dates individual articles, apart from the per-page revision date that the MkDocs plugin renders, and the homepage does not promise a compatibility matrix.

The same caution applies to the numbers. If an article quotes a measurement, that measurement came from a machine, a Go version and a workload the reader cannot see from the published page. The existence of perf-tracking suggests the figures are reproducible in principle, but the README does not document the commands, so a number quoted in a design review should be labelled as the guide's figure rather than as yours.

None of this makes the guide unusable. It makes it a source of hypotheses rather than a source of truth, and that is the correct relationship to have with a pattern catalog. The pattern is the part that transfers, the number is the part that belongs to your environment, and the profiler in your own binary is what decides between them.

Editorial conclusion

Adopt the Go Optimization Guide as a reference if your team writes Go services and wants concrete patterns to argue about, and if you are willing to verify each recommendation against your own measurements rather than applying it as a checklist. Do not adopt it as a dependency, because it is documentation and a benchmark directory rather than a library you import. Verify first that the patterns match the Go version your service builds with, that the perf-tracking harness runs on your hardware before you cite any of its numbers, and that the CC-BY-4.0 licence is acceptable for the way you intend to reuse the text.

Frequently asked questions

Official sources

1. astavonin/go-optimization-guide on GitHub
2. Issues
3. License: CC-BY-4.0
4. Project website
5. README