debugsrv

Documentation

Overview

Package debugsrv serves operational endpoints — net/http/pprof profiles plus optional metrics and health handlers — on a separate, internal-only listener or as a handler attached to an existing router.

Keeping pprof and metrics off the public application port avoids exposing profiling and internal signals to the internet; bind Addr to localhost or a cluster-internal interface and scrape it from your metrics/ops tooling. The endpoints live at several fixed top-level paths (Paths): /debug/pprof/, /metrics, /healthz, /readyz, /startupz, /version. The metrics, health, startup and version routes are only mounted when their handler (or value) is supplied in Config.

debugsrv is the "status server" brick of the server kit: it builds on the shared httpserver core (the same http.Handler-on-a-listener Runnable that backs the REST and gRPC-gateway servers), so all of them supervise and drain together under one worker.Group.

Standalone server

New returns a *Server implementing worker.Runnable (Start/Stop/Name), so it joins a supervisor alongside the REST/gRPC servers and shuts down with them:

grp.Add(debugsrv.New(debugsrv.Config{
	Addr:           "localhost:6060",
	MetricsHandler: m.Handler(),
	Liveness:       health.Liveness(),
	Readiness:      health.Readiness(time.Second, dbCheck),
}))

Attached to the application router

Handler returns the routes as a single http.Handler. Because the endpoints live at several fixed top-level paths, register the one handler at each of them (Paths) rather than under a single prefix:

dh := debugsrv.Handler(debugsrv.Config{MetricsHandler: m.Handler()})
for _, p := range debugsrv.Paths {
	appRouter.Handle(p, dh)
}

*Server also implements http.Handler (ServeHTTP delegates to the same routes), so the same instance can run standalone via Start or be reused as a handler.

Attach the debug routes WITHOUT the per-request timeout/size-limit middleware — pprof profile/trace handlers run for many seconds and a request timeout would cut them off.

Config

Config fields (only Addr is required for the standalone server):

• Addr: listen address, e.g. "localhost:6060".
• ReadHeaderTimeout: bounds reading request headers (default 5s) to avoid Slowloris-style stalls on the debug port.
• ShutdownTimeout: bounds graceful shutdown when Stop's ctx has no deadline (default 10s).
• Logger: receives start/stop lines; defaults to slog.Default().
• MetricsHandler: when set, served at /metrics.
• Liveness: when set, served at /healthz.
• Readiness: when set, served at /readyz.
• Startup: when set, served at /startupz (Kubernetes startup probe).
• Version: when non-nil, encoded as JSON at /version (build/version info).

Index

• Variables
• func Handler(cfg Config) http.Handler
• type Config
• type Server
  • func New(cfg Config) *Server
  • func (s *Server) ServeHTTP(w http.ResponseWriter, r *http.Request)

Variables

var Paths = []string{"/debug/pprof/", "/metrics", "/healthz", "/readyz", "/startupz", "/version"}

Paths are the top-level patterns Handler serves. An application that attaches the handler to its own router registers it at each of these.

Functions

func Handler

func Handler(cfg Config) http.Handler

Handler builds the debug endpoints — pprof under /debug/pprof/ plus the optional metrics, health, startup and version endpoints from cfg — as a single http.Handler.

This is the idiomatic primitive: serve it on a standalone listener (New wraps it) or attach it to an application router. Because the endpoints live at several fixed top-level paths (/metrics and /healthz by Prometheus/k8s convention, /debug/pprof/ with pprof's own links), attach the one handler at each of those patterns (Paths) rather than under a single prefix:

dh := debugsrv.Handler(cfg)
for _, p := range debugsrv.Paths {
	appRouter.Handle(p, dh) // outside the per-request timeout middleware
}

Types

type Config

type Config struct {
	// Addr is the listen address, e.g. "localhost:6060".
	Addr string
	// ReadHeaderTimeout bounds reading request headers (default 5s) to avoid
	// Slowloris-style stalls on the debug port.
	ReadHeaderTimeout time.Duration
	// ShutdownTimeout bounds graceful shutdown when Stop's context has no
	// deadline (default 10s).
	ShutdownTimeout time.Duration
	// Logger receives start/stop lines; defaults to slog.Default().
	Logger *slog.Logger
	// MetricsHandler, when set, is served at /metrics.
	MetricsHandler http.Handler
	// Liveness, when set, is served at /healthz.
	Liveness http.Handler
	// Readiness, when set, is served at /readyz.
	Readiness http.Handler
	// Startup, when set, is served at /startupz (Kubernetes startup probe). Pass
	// health.Liveness() for an always-OK probe, or a custom check.
	Startup http.Handler
	// Version, when non-nil, is encoded as JSON at /version — typically a small
	// struct or map of build info (name, version, commit, build date, env).
	Version any
}

Config configures a debug Server. Only Addr is required.

type Server

type Server struct {
	*httpserver.Server
	// contains filtered or unexported fields
}

Server serves the debug endpoints on its own listener. It embeds an httpserver.Server (so it is a worker.Runnable via Start/Stop/Name) and also implements http.Handler, so it can run standalone or be reused as a handler.

func New

func New(cfg Config) *Server

New builds a debug Server from cfg. The returned server is not listening until Start is called.

func (*Server) ServeHTTP

func (s *Server) ServeHTTP(w http.ResponseWriter, r *http.Request)

ServeHTTP implements http.Handler, so the debug endpoints can be reused as a handler (mounted, tested, or wrapped) as well as run standalone via Start.