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.
- Optional endpoint registrations provided by subpackages (e.g. pprof, fgprof, statsviz, psutil).
The actual endpoints are registered via the debug module wiring (see `Module`) which composes the subpackages and installs their handlers onto the debug mux.
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 config is enabled for the debug server, the server loads the configured certificate and key material using go-service "source strings" and constructs a `*crypto/tls.Config` via `crypto/tls.NewConfig`.
Start with `Module` and `NewServer`.
Index ¶
Constants ¶
This section is empty.
Variables ¶
var Module = di.Module( di.Constructor(http.NewServeMux), di.Constructor(NewServer), di.Register(statsviz.Register), di.Register(pprof.Register), di.Register(fgprof.Register), di.Register(psutil.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
registrations for optional debug endpoints:
statsviz under /debug/statsviz
pprof under /debug/pprof
fgprof under /debug/fgprof
psutil under /debug/psutil
The endpoint registrations attach handlers to the debug mux. The mux is then used by the debug server when it is enabled via configuration.
Functions ¶
This section is empty.
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 Server ¶
Server wraps the managed debug HTTP service.
The embedded *server.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:
- parses the configured timeout,
- constructs an HTTP server using the 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:
- invalid timeout configuration panics via time.MustParseDuration,
- TLS configuration errors (when TLS is enabled) are returned, and
- underlying service construction errors are returned.
Errors are prefixed with "debug" for easier attribution.
func (*Server) GetService ¶ added in v2.26.0
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 certificate/key source strings when TLS is enabled.
Source Files
Directories
¶
| Path | Synopsis |
|---|---|
|
Package fgprof provides Fx wiring to expose fgprof profiling over HTTP.
|
Package fgprof provides Fx wiring to expose fgprof profiling over HTTP. |
|
Package http provides debug HTTP routing helpers for go-service.
|
Package http provides debug HTTP routing helpers for go-service. |
|
Package pprof provides Fx wiring to expose net/http/pprof profiling endpoints.
|
Package pprof provides Fx wiring to expose net/http/pprof profiling endpoints. |
|
Package psutil provides a debug endpoint that returns host/process system statistics.
|
Package psutil provides a debug endpoint that returns host/process system statistics. |
|
Package statsviz provides Fx wiring to expose statsviz diagnostics over HTTP.
|
Package statsviz provides Fx wiring to expose statsviz diagnostics over HTTP. |