Skip to content
LaktaLakta

Debug Actuator

pkg/debug/actuator mounts a Spring-Actuator-equivalent introspection surface — modules, startup timing, routes, health, build info, config, pprof, expvar, goroutine dump, DI graph, and live log-level control — on its own private loopback SyncModule listener. Every dependency is optional, so an absent source makes its endpoint return 501 rather than fail boot.

Setup

Section titled “Setup”

The module is disabled by default and binds to 127.0.0.1:6060. Enable it via config or WithEnabled:

lakta.NewRuntime(
    config.NewModule(
        config.WithConfigDirs(".", "./config"),
        config.WithArgs(os.Args[1:]),
    ),
    tint.NewModule(),
    slog.NewModule(),
    otel.NewModule(),
    health.NewModule(),
    actuator.NewModule(
        actuator.WithEnabled(true),
    ),
)

Sources such as *lakta.RuntimeInfo, *health.Health, *koanf.Koanf, the routes registry, and the slog LevelController are resolved from DI during Init. Whatever is present is exposed; whatever is missing degrades gracefully.

Endpoints

Section titled “Endpoints”

All paths are relative to BasePath (default /debug). Endpoints marked with auth require the WithAuth middleware to pass — see Production hardening.

Path Auth Description
GET /modules Module metadata: init order, provides/requires, lifecycle, state
GET /startup Init waterfall with per-module and total durations
GET /config Config values (redacted); add ?provenance=1 for key origins
GET /routes Registered routes across all fiber instances
GET /info Build info: Go version, main module, dependency versions
GET /health Delegates to the health module handler
GET /di DI graph; ?format=mermaid (default) or ?format=dot
GET /goroutine ✓ Full goroutine stack dump
GET /vars ✓ expvar published variables
GET /pprof/* ✓ Standard net/http/pprof surface (index, profile, trace, symbol)
POST /loggers ✓ Set the default log level: debug, info, warn, or error

The /vars, /pprof, and /loggers groups can be toggled off entirely via the endpoints config block.

Production hardening

Section titled “Production hardening”

This module exposes sensitive runtime internals, so its defaults are fail-closed:

  • Disabled by default — enabled is false until you opt in.
  • Loopback-bound — binds 127.0.0.1 by default; localhost-only is not sufficient safety inside a container.
  • Sensitive endpoints always require auth — /goroutine, /vars, /pprof/*, and /loggers are gated on every bind, including loopback. Without WithAuth, they reject all requests with 401.
  • Non-loopback refuses to start without auth — binding a public address without WithAuth fails boot. Set allow_insecure: true to downgrade the refusal to a warning (sensitive endpoints still reject).
  • Values masked by default — show_values: never renders matched config leaves as ******. Choose always or when_authorized, and extend the redaction key set with redact_patterns.
  • pprof duration cap — a ?seconds= above 30 on /pprof/profile and /pprof/trace is rejected to close the unbounded-CPU-profile DoS vector.
actuator.NewModule(
    actuator.WithEnabled(true),
    actuator.WithAuth(myJWTMiddleware), // fiber.Handler gating sensitive endpoints
)

Use WithMount to serve the endpoints under an existing fiber router instead of a private listener — an escape hatch that inherits the host router’s own middleware and exposure.

Configuration Reference

Section titled “Configuration Reference”

Config path: modules.debug.actuator.<name>

enabledbool

enabled gates the whole module; when false Init/Start are no-ops. Default false

envLAKTA_MODULES__DEBUG__ACTUATOR__<NAME>__ENABLED
hoststringdefault: 127.0.0.1

host to bind the private actuator listener. Default 127.0.0.1

envLAKTA_MODULES__DEBUG__ACTUATOR__<NAME>__HOST
portuint16default: 6060

port to bind. Default 6060

envLAKTA_MODULES__DEBUG__ACTUATOR__<NAME>__PORT
base_pathstringdefault: /debug

basePath prefixes every endpoint. Default /debug

envLAKTA_MODULES__DEBUG__ACTUATOR__<NAME>__BASE_PATH
show_valuesstringdefault: never

showValues controls config-value masking: never|always|when_authorized

envLAKTA_MODULES__DEBUG__ACTUATOR__<NAME>__SHOW_VALUES
redact_patterns[]string

redactPatterns extends (does not replace) the default key-redaction set

envLAKTA_MODULES__DEBUG__ACTUATOR__<NAME>__REDACT_PATTERNS
endpointsendpoints toggles optional endpoint groups. All default true
endpoints.pprofbooldefault: true
envLAKTA_MODULES__DEBUG__ACTUATOR__<NAME>__ENDPOINTS__PPROF
endpoints.expvarbooldefault: true
envLAKTA_MODULES__DEBUG__ACTUATOR__<NAME>__ENDPOINTS__EXPVAR
endpoints.uibooldefault: true
envLAKTA_MODULES__DEBUG__ACTUATOR__<NAME>__ENDPOINTS__UI
endpoints.loggersbooldefault: true
envLAKTA_MODULES__DEBUG__ACTUATOR__<NAME>__ENDPOINTS__LOGGERS
allow_insecurebool

allowInsecure downgrades the fail-closed security refusals (non-loopback

envLAKTA_MODULES__DEBUG__ACTUATOR__<NAME>__ALLOW_INSECURE

Code-only options

Section titled “Code-only options”

These options can only be set in Go code via With*() functions, not via config files or environment variables.

OptionTypeDescription
WithMount(...)fiber.Routermounts endpoints under the caller's router instead of a private
WithAuth(...)sets the auth middleware gating sensitive endpoints (code-only)