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 (github.com/alexfalkowski/go-service/v2/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 *Config (or nil embedded config) is treated as "disabled", and NewServer returns (nil, nil) when disabled.
When debug is enabled and no address is configured, the server binds to tcp://:6060. Production deployments should set an explicit address, TLS/mTLS, and network or policy controls appropriate for the environment.
TLS ¶
When TLS is enabled for the debug server, the package uses github.com/alexfalkowski/go-service/v2/config/server.NewConfig to resolve github.com/alexfalkowski/go-service/v2/crypto/tls/config.Config source strings and build the runtime *crypto/tls.Config assigned to the underlying HTTP server.
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 (*github.com/alexfalkowski/go-service/v2/debug/http.ServeMux) via [http.NewServeMux],
- the debug server (*Server) via NewServer (returns nil when disabled), and
- Register, the front door for optional debug endpoint registration.
Register installs statsviz, pprof, and fgprof handlers under their service-namespaced /<name>/debug/... routes.
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, 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 github.com/alexfalkowski/go-service/v2/config/server.Config to reuse common server settings such as address, timeout, TLS configuration, maximum inbound request-body size, 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
// 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,
- wraps the mux with the configured maximum inbound request-body size,
- 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 coordinates process shutdown from the debug service.
Shutdowner di.Shutdowner
// Mux registers debug HTTP endpoints.
Mux *debug.ServeMux
// Config enables and configures the debug server.
Config *Config
// Logger records debug HTTP service events.
Logger *logger.Logger
// FS resolves TLS source strings when TLS is enabled.
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.
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. |
|
statsviz
Package statsviz provides Fx wiring to expose statsviz diagnostics over HTTP.
|
Package statsviz provides Fx wiring to expose statsviz diagnostics over HTTP. |