runtime Package Deep — Specification¶

1. Scope and authority¶

The exported runtime package is the user-facing surface of the Go runtime: the goroutine scheduler, the garbage collector, the memory allocator, the stack walker, the profiler hooks, and the symbol table all expose pieces of themselves through it. The package is governed by the Go 1 compatibility promise (https://go.dev/doc/go1compat): function signatures, type definitions, and documented semantics that ship in one Go release continue to compile and behave compatibly in every subsequent Go 1.x release. The Go team is explicit, however, that underlying behaviour is not frozen. Scheduler timing, the exact pacing of garbage collection, the contents of runtime.MemStats fields, the cost of runtime.Caller, and the size and layout of internal goroutine state are deliberately left free to evolve. Code that depends on runtime should depend on the documented signatures, not on the historical timings or numeric values returned by introspection helpers.

The runtime is implemented in Go and assembly across the src/runtime/... tree of the Go source repository; the exported package is one slice of that tree. The other slices — runtime/debug, runtime/pprof, runtime/trace, runtime/metrics, runtime/race, and runtime/cgo — sit beside the main package and expose specialised entry points (heap dumps, profiles, execution traces, structured metrics, race-detector hooks, cgo bridges) without polluting the core API. Together these packages form the runtime surface: everything a Go program can call to inspect or control the machinery that hosts it.

2. Primary specification¶

The authoritative documentation is the package reference on pkg.go.dev:

The Go 1 compatibility promise: https://go.dev/doc/go1compat. The runtime environment variable reference: https://pkg.go.dev/runtime#hdr-Environment_Variables. The GODEBUG reference: https://pkg.go.dev/runtime#hdr-Environment_Variables and the dedicated GODEBUG history page https://go.dev/doc/godebug.

3. Public API of the runtime package¶

3.1 Scheduling and goroutine control¶

3.2 Garbage collector control and introspection¶

3.3 Allocation and finalisation¶

3.4 Stack introspection¶

3.5 Profiling control (low-level)¶

These are the runtime hooks; runtime/pprof wraps them for normal use.

3.6 Build and environment introspection¶

3.7 Constants and variables¶

4. runtime/debug¶

Source: https://pkg.go.dev/runtime/debug; implementation in runtime/debug/... and runtime/mgc.go.

5. runtime/pprof¶

Source: https://pkg.go.dev/runtime/pprof; implementation in runtime/pprof/.... The package exposes named profiles, the CPU profile writer, and the labels API.

5.1 Built-in profile types¶

5.2 Functions¶

The pprof binary format is documented at https://github.com/google/pprof/blob/main/doc/README.md and consumed by the go tool pprof analyser.

6. runtime/trace¶

Source: https://pkg.go.dev/runtime/trace; implementation in runtime/trace/... and the runtime's tracing core in runtime/trace.go / runtime/traceback.go.

Traces are consumed by go tool trace; the binary format is internal but stable across a minor-version range. The Go 1.21 release rewrote the trace implementation (https://go.dev/blog/execution-traces-2024) for lower overhead and concurrent reader support.

7. runtime/metrics¶

Introduced in Go 1.16 as the long-term replacement for runtime.MemStats. Source: https://pkg.go.dev/runtime/metrics; design document https://go.googlesource.com/proposal/+/refs/heads/master/design/37112-runtime-metrics.md.

Metric naming convention: /path/to/metric:unit (for example /gc/heap/allocs:bytes, /sched/goroutines:goroutines, /sync/mutex/wait/total:seconds). New metrics may be added in any minor release; existing names and kinds are stable. The set of metrics in Go 1.22 is listed at https://pkg.go.dev/runtime/metrics#hdr-Supported_metrics; in practice the canonical enumeration is what runtime/metrics.All() returns at runtime.

8. runtime/race¶

Source: https://pkg.go.dev/runtime/race. The package is empty unless the binary is built with -race; the linker swaps in the race-detector runtime which is implemented on top of ThreadSanitizer (TSan, https://github.com/google/sanitizers/wiki/ThreadSanitizerCppManual).

Normal code does not call these; standard library primitives (sync.Mutex, channels, atomic) are already instrumented. The hooks exist for libraries that implement their own synchronisation in unsafe code (notably the runtime itself and a handful of database drivers).

9. runtime/cgo¶

Source: https://pkg.go.dev/runtime/cgo. The package is a bridge between Go and C: it is imported automatically by code that uses import "C", and is rarely useful as a direct import.

The cgo bridge itself — the calling convention, the goroutine-thread interaction, the rules for passing pointers across the boundary — is documented at https://pkg.go.dev/cmd/cgo. runtime/cgo is the runtime-side companion; the user-facing entry point is the special "C" pseudo-import.

10. runtime/coverage¶

Added in Go 1.20 (https://go.dev/doc/go1.20#cover). Source: https://pkg.go.dev/runtime/coverage.

Used by long-running services that want to emit incremental coverage data without exiting.

11. MemStats reference¶

ReadMemStats(*MemStats) populates the following fields. Field semantics are not promised stable; the field names and types are. The struct lives in runtime/mstats.go.

The Go 1.16+ replacement is runtime/metrics, which exposes the same information with named, stable metric IDs and unit suffixes. New work should use runtime/metrics; MemStats remains for compatibility.

12. GODEBUG knobs affecting runtime¶

GODEBUG is a comma-separated list of name=value pairs read at process start. The full reference: https://pkg.go.dev/runtime#hdr-Environment_Variables and https://go.dev/doc/godebug.

The set of knobs has grown across releases; new knobs land regularly and old ones are retired as the behaviours they gate become defaults.

13. Environment variables¶

14. Source file map¶

The runtime is in src/runtime in the Go source tree (https://github.com/golang/go/tree/master/src/runtime). The exported runtime package's user-facing entry points are spread across these files:

15. Compatibility¶

Go 1 compatibility (https://go.dev/doc/go1compat) covers:

• The set of exported identifiers in runtime, runtime/debug, runtime/pprof, runtime/trace, runtime/metrics, runtime/race, runtime/cgo. New identifiers may be added; existing ones do not disappear or change signature.
• The documented semantics of each function as written in the package documentation at the time it was released. Where the doc says "may", "should", "approximately", or names a default that "may change", that text is the boundary of the promise.
• The names and types of MemStats fields and GCStats fields.
• The named profile types in runtime/pprof (heap, goroutine, block, mutex, threadcreate, allocs).
• The on-disk format of pprof profiles and execution traces, at the level of "consumable by go tool pprof and go tool trace of the same minor version or newer".

What the promise explicitly does not cover:

• The exact numeric values returned by MemStats fields under any given workload; the GC pacer, allocator, and span layout evolve every release.
• The exact ordering and timing of finaliser execution, scheduling, and goroutine preemption.
• The exact contents of stack traces emitted by Stack and PrintStack; new lines may appear, formatting may change, the runtime may inline or de-inline frames.
• The exact set of runtime/metrics names; new names appear regularly, deprecated names remain available but may become aliases.
• The exact behaviour of GODEBUG knobs; knobs are added, removed, and have their defaults flipped across releases (the godebug history page records the changes).
• Performance characteristics: a function's signature does not promise it will be as cheap as it was in the previous release.

16. Notable proposals and releases¶

17. Bug reporting¶

The runtime is tracked in the main Go issue tracker at https://github.com/golang/go/issues. Issues affecting the runtime carry the runtime label (https://github.com/golang/go/labels/compiler%2Fruntime and https://github.com/golang/go/labels/runtime). Profile and trace issues frequently also carry pprof or Performance. Reports should include:

• go version output.
• GOOS, GOARCH, container/VM details if relevant.
• The GODEBUG setting and any non-default GOGC / GOMAXPROCS / GOMEMLIMIT.
• A minimum reproducer; if the bug is a crash, the full traceback with GOTRACEBACK=all or GOTRACEBACK=crash.
• For GC or scheduler regressions: a go tool trace capture and runtime/metrics snapshot or GODEBUG=gctrace=1,schedtrace=1000 output covering the regression window.

Security-sensitive issues go to security@golang.org rather than the public tracker; the process is described at https://go.dev/security/policy.

The runtime package is the small, stable, hand-curated public window into a large and deliberately fluid implementation. Its API is governed by the Go 1 promise; its behaviour is governed only by the documented contract. Senior use comes from knowing exactly where that boundary sits — which fields of MemStats are load-bearing, which runtime/metrics names are new in this release, which GODEBUG knobs have flipped defaults, which proposals are accepted but not yet shipped — and from preferring runtime/metrics for telemetry, runtime/pprof for profiling, runtime/trace for causality analysis, and runtime/debug.BuildInfo for binary provenance over reaching into raw runtime introspection.