Add state dump functionality via SIGUSR1 signal

Author: alexandre-daubois

docs/prometheus-export.md

@@ -25,12 +25,22 @@ The `--daemon` flag disables the TUI and requires `--expose`. Ember polls the Ca
 ember --expose :9191 --daemon --addr http://caddy:2019
 ```
 
-Logs are written to stderr:
+Logs are written to stderr. Use `--log-format json` for structured JSON logs suitable for log aggregation:
 
+```bash
+ember --expose :9191 --daemon --log-format json
 ```
-ember daemon: exposing metrics on http://localhost:9191/metrics
+
+### State Dump via SIGUSR1
+
+Send `SIGUSR1` to a running daemon to dump the full state snapshot to stderr as JSON. This is useful for debugging without interrupting the process:
+
+```bash
+kill -USR1 $(pgrep ember)
 ```
 
+The dump includes threads, metrics, process info, and derived metrics. Not available on Windows.
+
 ## Exported Metrics
 
 ### FrankenPHP Thread Metrics

internal/app/daemon.go

@@ -54,6 +54,8 @@ func runDaemon(ctx context.Context, f fetcher.Fetcher, cfg *config) error {
 	ticker := time.NewTicker(cfg.interval)
 	defer ticker.Stop()
 
+	dumpCh := dumpSignal()
+
 	for {
 		select {
 		case <-ctx.Done():
@@ -66,6 +68,8 @@ func runDaemon(ctx context.Context, f fetcher.Fetcher, cfg *config) error {
 			return nil
 		case <-ticker.C:
 			poll()
+		case <-dumpCh:
+			dumpState(&state, log)
 		}
 	}
 }

internal/app/signal_unix.go

@@ -0,0 +1,59 @@
+//go:build !windows
+
+package app
+
+import (
+	"encoding/json"
+	"log/slog"
+	"math"
+	"os"
+	"os/signal"
+	"syscall"
+
+	"github.com/alexandre-daubois/ember/internal/fetcher"
+	"github.com/alexandre-daubois/ember/internal/model"
+)
+
+// dumpSignal returns a channel that receives a value each time SIGUSR1 is sent to the process.
+func dumpSignal() <-chan os.Signal {
+	ch := make(chan os.Signal, 1)
+	signal.Notify(ch, syscall.SIGUSR1)
+	return ch
+}
+
+func dumpState(state *model.State, log *slog.Logger) {
+	if state.Current == nil {
+		log.Info("dump requested but no data available yet")
+		return
+	}
+
+	out := buildJSONOutput(state.Current, state)
+	sanitizeForJSON(&out)
+	b, err := json.Marshal(out)
+	if err != nil {
+		log.Error("dump failed", "err", err)
+		return
+	}
+
+	log.Info("state dump (SIGUSR1)", "snapshot", string(b))
+}
+
+// sanitizeForJSON removes +Inf and NaN values that encoding/json cannot serialize.
+func sanitizeForJSON(out *jsonOutput) {
+	out.Metrics.DurationBuckets = sanitizeBuckets(out.Metrics.DurationBuckets)
+	for _, h := range out.Metrics.Hosts {
+		h.DurationBuckets = sanitizeBuckets(h.DurationBuckets)
+		h.TTFBBuckets = sanitizeBuckets(h.TTFBBuckets)
+	}
+}
+
+func sanitizeBuckets(buckets []fetcher.HistogramBucket) []fetcher.HistogramBucket {
+	clean := make([]fetcher.HistogramBucket, 0, len(buckets))
+	for _, b := range buckets {
+		if math.IsInf(b.UpperBound, 0) || math.IsNaN(b.UpperBound) {
+			continue
+		}
+		clean = append(clean, b)
+	}
+	return clean
+}

internal/app/signal_unix_test.go

@@ -0,0 +1,57 @@
+//go:build !windows
+
+package app
+
+import (
+	"bytes"
+	"log/slog"
+	"math"
+	"testing"
+	"time"
+
+	"github.com/alexandre-daubois/ember/internal/fetcher"
+	"github.com/alexandre-daubois/ember/internal/model"
+	"github.com/stretchr/testify/assert"
+)
+
+func TestDumpState_WithData(t *testing.T) {
+	snap := &fetcher.Snapshot{
+		Metrics: fetcher.MetricsSnapshot{
+			Workers:        map[string]*fetcher.WorkerMetrics{},
+			HasHTTPMetrics: true,
+			DurationBuckets: []fetcher.HistogramBucket{
+				{UpperBound: 0.005, CumulativeCount: 50},
+				{UpperBound: math.Inf(1), CumulativeCount: 100},
+			},
+		},
+		Process:   fetcher.ProcessMetrics{CPUPercent: 5.0, RSS: 64 * 1024 * 1024},
+		FetchedAt: time.Now(),
+	}
+	var state model.State
+	state.Update(snap)
+
+	var buf bytes.Buffer
+	log := slog.New(slog.NewTextHandler(&buf, nil))
+
+	dumpState(&state, log)
+
+	output := buf.String()
+	assert.Contains(t, output, "state dump")
+	assert.Contains(t, output, "cpuPercent")
+}
+
+func TestDumpState_NoData(t *testing.T) {
+	var state model.State
+
+	var buf bytes.Buffer
+	log := slog.New(slog.NewTextHandler(&buf, nil))
+
+	dumpState(&state, log)
+
+	assert.Contains(t, buf.String(), "no data")
+}
+
+func TestDumpSignal_ReturnsChannel(t *testing.T) {
+	ch := dumpSignal()
+	assert.NotNil(t, ch)
+}

internal/app/signal_windows.go

@@ -0,0 +1,19 @@
+//go:build windows
+
+package app
+
+import (
+	"log/slog"
+	"os"
+
+	"github.com/alexandre-daubois/ember/internal/model"
+)
+
+// dumpSignal returns a channel that never receives on Windows (no SIGUSR1 support).
+func dumpSignal() <-chan os.Signal {
+	return make(chan os.Signal)
+}
+
+func dumpState(_ *model.State, log *slog.Logger) {
+	log.Warn("state dump not supported on Windows")
+}