debug

Documentation

Overview

Package debug runs an opt-in diagnostics HTTP server exposing Go runtime profiles (goroutine, heap, threadcreate, CPU, trace, …) plus a periodic runtime-stats log line, for chasing leaks and stalls.

Unlike net/http/pprof, this package registers nothing on http.DefaultServeMux: it builds the profile handlers directly from runtime/pprof + runtime/trace and serves them on its own mux, so importing it can never quietly attach profiling to a binary that happens to serve the default mux. The server only starts when Config.Addr is non-empty, so importing the package is otherwise inert.

Index

• func Handler() http.Handler
• func Start(ctx context.Context, cfg Config)
• type Config

Functions

func Handler

func Handler() http.Handler

Handler returns the diagnostics mux (profiles under /debug/pprof/), built from runtime/pprof + runtime/trace. Exported so callers can mount it on an existing admin server instead of using a dedicated listener.

func Start

func Start(ctx context.Context, cfg Config)

Start launches the diagnostics server on cfg.Addr (when non-empty) and a goroutine that logs goroutine / OS-thread / heap counts every cfg.StatsEvery. Both stop when ctx is cancelled. It is a no-op when cfg.Addr is empty.

WARNING: the endpoints are unauthenticated. Bind Addr to loopback or a private interface and never expose it publicly.

Types

type Config

type Config struct {
	// Addr is the listen address for the diagnostics HTTP server, e.g.
	// "127.0.0.1:6060" or ":6060". Empty disables everything (no
	// listener, no stats loop) — wire it from a per-app env var so it
	// stays off by default in production.
	Addr string
	// Log receives the startup line and the periodic runtime stats.
	// Defaults to slog.Default() when nil.
	Log *slog.Logger
	// StatsEvery is the runtime-stats logging interval. Defaults to 30s.
	StatsEvery time.Duration
}

Config configures the diagnostics server.