Documentation
¶
Overview ¶
Package debug provides debug server wiring and diagnostic endpoints for go-service.
This package wires an optional HTTP debug server that can expose operational and profiling endpoints. It is intended to be enabled in development and operations environments and disabled otherwise.
What this package provides ¶
At a high level, the debug subsystem consists of:
- A debug HTTP server (`Server`) that runs independently from the main service server.
- A debug router (`debug/http.ServeMux`) used to register endpoints.
- Built-in endpoint registrations installed through `Register`.
`Register` is the public front door for endpoint registration. The debug module wiring uses it to install the built-in handlers onto the debug mux, and callers that construct a debug server manually should use it instead of depending on endpoint implementation packages.
Configuration and enablement ¶
Debug configuration is optional. By convention across go-service config types, a nil `*debug.Config` (or nil embedded config) is treated as "disabled", and `NewServer` returns (nil, nil) when disabled.
TLS ¶
When TLS is enabled for the debug server, the package uses `config/server.NewConfig` to resolve `crypto/tls/config.Config` source strings and build the runtime `*crypto/tls.Config` assigned to the underlying HTTP server.
Start with `Module`, `NewServer`, and `Register`.
Index ¶
Constants ¶
This section is empty.
Variables ¶
var Module = di.Module( di.Constructor(http.NewServeMux), di.Constructor(NewServer), di.Register(Register), )
Module wires the debug subsystem into Fx/Dig.
It provides:
a debug router (`*debug/http.ServeMux`) via `http.NewServeMux`,
the debug server (`*debug.Server`) via `NewServer` (returns nil when disabled), and
`Register`, the front door for optional debug endpoint registration:
statsviz under /debug/statsviz
pprof under /debug/pprof
fgprof under /debug/fgprof
psutil under /debug/psutil
Register attaches handlers to the debug mux only when the debug server is enabled. The mux is then used by the debug server when it is enabled via configuration.
Functions ¶
func Register ¶ added in v2.481.0
func Register(params RegisterParams) error
Register installs the built-in debug endpoint handlers when cfg is enabled.
This is the public front door for debug endpoint registration. It registers pprof, fgprof, psutil, and statsviz handlers on Mux. When Config is nil or disabled, Register returns without installing handlers or starting any endpoint-owned background work.
Types ¶
type Config ¶
Config configures the debug server.
It embeds `config/server.Config` to reuse common server settings such as address, timeout, TLS configuration, and server-specific options.
Optional pointers and "enabled" semantics ¶
This config is intentionally optional. By convention across go-service configuration types, a nil *Config is treated as "debug disabled". The embedded `*server.Config` is also optional; IsEnabled returns true only when both the outer *Config and the embedded *server.Config are non-nil/enabled.
This allows services to omit the debug config entirely to disable the debug server.
type RegisterParams ¶ added in v2.481.0
type RegisterParams struct {
di.In
// Lifecycle owns endpoint resources that need shutdown, such as statsviz.
Lifecycle di.Lifecycle
// Config enables or disables debug endpoint registration.
Config *Config
// Content resolves response encoders for content-backed debug endpoints.
Content *content.Content
// Mux is the debug mux where handlers are registered.
Mux *http.ServeMux
// Name is the service name used to prefix debug routes.
Name env.Name
}
RegisterParams defines dependencies for registering built-in debug endpoints.
It is an Fx parameter struct (`di.In`) used to install the built-in debug handlers on the debug mux when debug is enabled.
type Server ¶
type Server struct {
*httpserver.Service
}
Server wraps the managed debug HTTP service.
The embedded *httpserver.Service provides lifecycle integration and start/stop behavior. This wrapper adds a nil-safe accessor via GetService.
func NewServer ¶
func NewServer(params ServerParams) (*Server, error)
NewServer constructs the debug Server when enabled.
Disabled behavior: if params.Config is nil/disabled, NewServer returns (nil, nil).
Enabled behavior:
- constructs an HTTP server using the configured timeout and debug mux,
- builds the net/http server config (address and optional TLS), and
- wraps it in a managed service ("debug") that integrates with DI lifecycle/shutdown.
Failure behavior:
- TLS configuration errors (when TLS is enabled) are returned, and
- underlying service construction errors are returned.
Errors are prefixed with "debug" for easier attribution. If the configured address uses an ephemeral port such as `localhost:0`, the actual bound listener address is available from the returned server's service (`server.GetService().String()`) after construction. params.Config.Address remains the configured value.
func (*Server) GetService ¶ added in v2.26.0
func (s *Server) GetService() *httpserver.Service
GetService returns the underlying service.
It is nil-safe: if the receiver is nil (e.g. debug server disabled and not constructed), GetService returns nil.
type ServerParams ¶
type ServerParams struct {
di.In
Shutdowner di.Shutdowner
Mux *debug.ServeMux
Config *Config
Logger *logger.Logger
FS *os.FS
}
ServerParams defines dependencies for constructing the debug server.
It is intended for dependency injection (Fx/Dig). `NewServer` uses these dependencies to build an HTTP debug service and register lifecycle/shutdown behavior.
Fields:
- Shutdowner: used by the underlying service wiring to coordinate process shutdown.
- Mux: the debug HTTP mux where debug endpoints (pprof/fgprof/statsviz/psutil/etc.) are registered.
- Config: enables and configures the debug server (address/timeout/TLS/options).
- Logger: used by the underlying HTTP service wrapper.
- FS: filesystem used to resolve TLS source strings when TLS is enabled.
Source Files
Directories
¶
| Path | Synopsis |
|---|---|
|
Package http provides debug HTTP routing helpers for go-service.
|
Package http provides debug HTTP routing helpers for go-service. |
|
internal
|
|
|
fgprof
Package fgprof provides Fx wiring to expose fgprof profiling over HTTP.
|
Package fgprof provides Fx wiring to expose fgprof profiling over HTTP. |
|
pprof
Package pprof provides Fx wiring to expose net/http/pprof profiling endpoints.
|
Package pprof provides Fx wiring to expose net/http/pprof profiling endpoints. |
|
psutil
Package psutil provides a debug endpoint that returns host/process system statistics.
|
Package psutil provides a debug endpoint that returns host/process system statistics. |
|
statsviz
Package statsviz provides Fx wiring to expose statsviz diagnostics over HTTP.
|
Package statsviz provides Fx wiring to expose statsviz diagnostics over HTTP. |