feat: add pprof debug endpoint for runtime profiling (#127)

* feat: add pprof debug endpoint for runtime profiling

Adds optional pprof HTTP endpoint for runtime memory, CPU, and goroutine
profiling. Useful for debugging memory issues and performance analysis.

Configuration:
```yaml
pprof:
  enabled: true
  listen_addr: 127.0.0.1
  listen_port: 6060
```

Endpoints exposed:
- /debug/pprof/         - Index with links to all profiles
- /debug/pprof/heap     - Heap memory profile
- /debug/pprof/profile  - CPU profile (30s default)
- /debug/pprof/goroutine - Goroutine stack dumps
- /debug/pprof/trace    - Execution trace

Usage:
  go tool pprof http://127.0.0.1:6060/debug/pprof/heap

WARNING: Only enable in development/debugging scenarios, not production.

* fix: add graceful shutdown for pprof server

Use http.Server with Shutdown() instead of raw ListenAndServe to properly
shut down the pprof endpoint when the application exits.

* test: add PprofConfig unmarshal tests

- Test that pprof config is properly unmarshalled from YAML
- Test that pprof is disabled by default when not specified

Author: LaurenceJJones

cmd/root.go

@@ -6,6 +6,7 @@ import (
 	"fmt"
 	"net"
 	"net/http"
+	"net/http/pprof"
 	"os"
 	"os/signal"
 	"strings"
@@ -134,6 +135,45 @@ func Execute() error {
 		}()
 	}
 
+	// pprof debug endpoint for runtime profiling (memory, CPU, goroutines)
+	// WARNING: Only enable in development/debugging scenarios
+	if config.PprofConfig.Enabled {
+		pprofMux := http.NewServeMux()
+		pprofMux.HandleFunc("/debug/pprof/", pprof.Index)
+		pprofMux.HandleFunc("/debug/pprof/cmdline", pprof.Cmdline)
+		pprofMux.HandleFunc("/debug/pprof/profile", pprof.Profile)
+		pprofMux.HandleFunc("/debug/pprof/symbol", pprof.Symbol)
+		pprofMux.HandleFunc("/debug/pprof/trace", pprof.Trace)
+
+		listenOn := net.JoinHostPort(
+			config.PprofConfig.ListenAddress,
+			config.PprofConfig.ListenPort,
+		)
+
+		pprofServer := &http.Server{
+			Addr:    listenOn,
+			Handler: pprofMux,
+		}
+
+		g.Go(func() error {
+			log.Warnf("pprof debug endpoint enabled at %s/debug/pprof/ - DO NOT USE IN PRODUCTION", listenOn)
+			if err := pprofServer.ListenAndServe(); err != nil && !errors.Is(err, http.ErrServerClosed) {
+				return fmt.Errorf("pprof server error: %w", err)
+			}
+			return nil
+		})
+
+		g.Go(func() error {
+			<-ctx.Done()
+			log.Info("Shutting down pprof server...")
+			// Use background context since parent ctx is already canceled
+			shutdownCtx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
+			defer cancel()
+			//nolint:contextcheck // parent ctx is canceled, need fresh context for shutdown
+			return pprofServer.Shutdown(shutdownCtx)
+		})
+	}
+
 	dataSet := dataset.New()
 
 	g.Go(func() error {

config/crowdsec-spoa-bouncer.yaml

@@ -24,3 +24,11 @@ prometheus:
   enabled: false
   listen_addr: 127.0.0.1
   listen_port: 60601
+
+## pprof debug endpoint for runtime profiling
+## WARNING: Only enable for debugging, exposes internal runtime data
+## Endpoints: /debug/pprof/heap, /debug/pprof/profile, /debug/pprof/goroutine, etc.
+#pprof:
+#  enabled: false
+#  listen_addr: 127.0.0.1
+#  listen_port: 6060

pkg/cfg/config.go

@@ -18,6 +18,15 @@ type PrometheusConfig struct {
 	ListenPort    string `yaml:"listen_port"`
 }
 
+// PprofConfig configures the pprof debug endpoint for runtime profiling.
+// When enabled, exposes Go's pprof endpoints for memory, CPU, and goroutine profiling.
+// WARNING: Only enable in development/debugging scenarios, not in production.
+type PprofConfig struct {
+	Enabled       bool   `yaml:"enabled"`
+	ListenAddress string `yaml:"listen_addr"`
+	ListenPort    string `yaml:"listen_port"`
+}
+
 type BouncerConfig struct {
 	Logging          cslogging.LoggingConfig `yaml:",inline"`
 	Hosts            []*host.Host            `yaml:"hosts"`
@@ -26,6 +35,7 @@ type BouncerConfig struct {
 	ListenTCP        string                  `yaml:"listen_tcp"`
 	ListenUnix       string                  `yaml:"listen_unix"`
 	PrometheusConfig PrometheusConfig        `yaml:"prometheus"`
+	PprofConfig      PprofConfig             `yaml:"pprof"`
 }
 
 // MergedConfig() returns the byte content of the patched configuration file (with .yaml.local).

pkg/cfg/config_test.go

@@ -44,3 +44,35 @@ logging:
 	require.Error(t, err)
 	assert.Contains(t, err.Error(), "at least one listener")
 }
+
+func TestPprofConfigUnmarshal(t *testing.T) {
+	const configYAML = `
+log_mode: stdout
+listen_tcp: 0.0.0.0:9000
+pprof:
+  enabled: true
+  listen_addr: 127.0.0.1
+  listen_port: "6060"
+`
+
+	cfg, err := NewConfig(strings.NewReader(configYAML))
+
+	require.NoError(t, err)
+	assert.True(t, cfg.PprofConfig.Enabled)
+	assert.Equal(t, "127.0.0.1", cfg.PprofConfig.ListenAddress)
+	assert.Equal(t, "6060", cfg.PprofConfig.ListenPort)
+}
+
+func TestPprofConfigDefaults(t *testing.T) {
+	const configYAML = `
+log_mode: stdout
+listen_tcp: 0.0.0.0:9000
+`
+
+	cfg, err := NewConfig(strings.NewReader(configYAML))
+
+	require.NoError(t, err)
+	assert.False(t, cfg.PprofConfig.Enabled, "pprof should be disabled by default")
+	assert.Empty(t, cfg.PprofConfig.ListenAddress)
+	assert.Empty(t, cfg.PprofConfig.ListenPort)
+}