feat(logging): split application/output logs using stderr/stdout (#607)

Signed-off-by: Chris Gianelloni <wolf31o2@blinklabs.io>

Author: wolf31o2

README.md

@@ -99,8 +99,43 @@ transaction:
 }
 ```
 
-Each event is output individually. The log output prints each event to stdout
-using Go's standard `slog` logging library.
+Each event is output individually. The log output supports two formats:
+
+- **text** (default) — human-readable, one line per event:
+
+  ```text
+  2026-02-07 09:18:40 BLOCK        slot=12345678  block=9876543  hash=abcd1234abcd1234abcd1234abcd1234abcd1234abcd1234abcd1234abcd1234 era=Conway  txs=5 size=1234
+  2026-02-07 09:18:41 TX           slot=12345678  block=9876543  tx=deadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeef fee=180000 inputs=2 outputs=3
+  2026-02-07 09:18:42 ROLLBACK     slot=12345678  hash=aabbccddaabbccddaabbccddaabbccddaabbccddaabbccddaabbccddaabbccdd
+  2026-02-07 09:18:43 GOVERNANCE   slot=12345678  block=9876543  tx=1234abcd1234abcd1234abcd1234abcd1234abcd1234abcd1234abcd1234abcd proposals=1 votes=2 certs=1
+  ```
+
+- **json** — newline-delimited JSON, one JSON object per event (suitable for
+  piping to `jq` or other tooling):
+
+  ```json
+  {"type":"chainsync.block","timestamp":"2026-02-07T09:18:40Z","context":{"blockNumber":9876543,"slotNumber":12345678},"payload":{"blockHash":"abc12345..."}}
+  ```
+
+Select the format with `--output-log-format`:
+
+```bash
+adder --output-log-format json
+```
+
+Event data is written to **stdout** and application logs are written to
+**stderr**. This means you can capture only event output:
+
+```bash
+# Save events to a file, see app logs in terminal
+adder > events.txt
+
+# Pipe events to jq, suppress app logs
+adder --output-log-format json 2>/dev/null | jq .
+
+# See only app logs, discard event data
+adder > /dev/null
+```
 
 ## Configuration
 
@@ -123,6 +158,7 @@ Flags:
                                       specifies the TCP address of the node to connect to
 ...
       --output string                 output plugin to use, 'list' to show available (default "log")
+      --output-log-format string      output format: "text" or "json" (default "text")
       --output-log-level string       specifies the log level to use (default "info")
   -h, --help                          help for adder
 ```
@@ -181,6 +217,7 @@ plugins:
   output:
     log:
       level: info
+      format: text
 ```
 
 ## Filtering

internal/logging/kugoCustomLogger.go

@@ -63,8 +63,8 @@ func convertKVs(kvs []ogmigo.KeyValue) []any {
 }
 
 func NewKugoCustomLogger(level LogLevel) *KugoCustomLogger {
-	// Create a new slog logger that logs to stdout using JSON format
-	handler := slog.NewJSONHandler(os.Stdout, nil)
+	// Create a new slog logger that logs to stderr using JSON format
+	handler := slog.NewJSONHandler(os.Stderr, nil)
 	logger := slog.New(handler)
 
 	return &KugoCustomLogger{

internal/logging/logging.go

@@ -24,7 +24,7 @@ import (
 
 // defaultLogger returns a non-nil logger so globalLogger is never nil at declaration (satisfies nilaway).
 func defaultLogger() *slog.Logger {
-	return slog.New(slog.NewJSONHandler(os.Stdout, &slog.HandlerOptions{
+	return slog.New(slog.NewJSONHandler(os.Stderr, &slog.HandlerOptions{
 		Level: slog.LevelInfo,
 	})).With("component", "main")
 }
@@ -47,7 +47,7 @@ func Configure() {
 		level = slog.LevelInfo
 	}
 
-	handler := slog.NewJSONHandler(os.Stdout, &slog.HandlerOptions{
+	handler := slog.NewJSONHandler(os.Stderr, &slog.HandlerOptions{
 		ReplaceAttr: func(groups []string, a slog.Attr) slog.Attr {
 			if a.Key == slog.TimeKey {
 				// Format the time attribute to use RFC3339 or your custom format

output/log/log.go

@@ -15,73 +15,144 @@
 package log
 
 import (
+	"encoding/json"
 	"fmt"
-	"log/slog"
+	"os"
 
 	"github.com/blinklabs-io/adder/event"
 	"github.com/blinklabs-io/adder/internal/logging"
 	"github.com/blinklabs-io/adder/plugin"
 )
 
+const (
+	FormatText = "text"
+	FormatJSON = "json"
+)
+
 type LogOutput struct {
-	errorChan    chan error
-	eventChan    chan event.Event
-	logger       plugin.Logger
-	outputLogger *slog.Logger
-	level        string
+	errorChan chan error
+	eventChan chan event.Event
+	doneChan  chan struct{}
+	logger    plugin.Logger
+	format    string
 }
 
 func New(options ...LogOptionFunc) *LogOutput {
 	l := &LogOutput{
-		level: "info",
+		format: FormatText,
 	}
 	for _, option := range options {
 		option(l)
 	}
 	if l.logger == nil {
 		l.logger = logging.GetLogger()
 	}
-
-	// Use the provided *slog.Logger if available, otherwise fall back to global logger
-	if providedLogger, ok := l.logger.(*slog.Logger); ok {
-		l.outputLogger = providedLogger.With("type", "event")
-	} else {
-		l.outputLogger = logging.GetLogger().With("type", "event")
-	}
 	return l
 }
 
 // Start the log output
 func (l *LogOutput) Start() error {
 	l.eventChan = make(chan event.Event, 10)
 	l.errorChan = make(chan error)
+	l.doneChan = make(chan struct{})
+	// Capture channels locally to avoid races with Stop()
+	eventChan := l.eventChan
+	doneChan := l.doneChan
 	go func() {
-		for {
-			evt, ok := <-l.eventChan
-			// Channel has been closed, which means we're shutting down
-			if !ok {
-				return
-			}
-			switch l.level {
-			case "info":
-				l.outputLogger.Info("", "event", fmt.Sprintf("%+v", evt))
-			case "warn":
-				l.outputLogger.Warn("", "event", fmt.Sprintf("%+v", evt))
-			case "error":
-				l.outputLogger.Error("", "event", fmt.Sprintf("%+v", evt))
+		defer close(doneChan)
+		for evt := range eventChan {
+			switch l.format {
+			case FormatJSON:
+				l.writeJSON(evt)
 			default:
-				// Use INFO level if log level isn't recognized
-				l.outputLogger.Info("", "event", fmt.Sprintf("%+v", evt))
+				l.writeText(evt)
 			}
 		}
 	}()
 	return nil
 }
 
+// writeText writes events in a human-readable format to stdout.
+func (l *LogOutput) writeText(evt event.Event) {
+	ts := evt.Timestamp.Format("2006-01-02 15:04:05")
+
+	var line string
+	switch payload := evt.Payload.(type) {
+	case event.BlockEvent:
+		ctx, _ := evt.Context.(event.BlockContext)
+		line = fmt.Sprintf(
+			"%s %-12s slot=%-10d block=%-8d hash=%s era=%-7s txs=%d size=%d",
+			ts, "BLOCK",
+			ctx.SlotNumber, ctx.BlockNumber,
+			payload.BlockHash,
+			ctx.Era,
+			payload.TransactionCount,
+			payload.BlockBodySize,
+		)
+	case event.TransactionEvent:
+		ctx, _ := evt.Context.(event.TransactionContext)
+		line = fmt.Sprintf(
+			"%s %-12s slot=%-10d block=%-8d tx=%s fee=%d inputs=%d outputs=%d",
+			ts, "TX",
+			ctx.SlotNumber, ctx.BlockNumber,
+			ctx.TransactionHash,
+			payload.Fee,
+			len(payload.Inputs), len(payload.Outputs),
+		)
+	case event.RollbackEvent:
+		line = fmt.Sprintf(
+			"%s %-12s slot=%-10d hash=%s",
+			ts, "ROLLBACK",
+			payload.SlotNumber,
+			payload.BlockHash,
+		)
+	case event.GovernanceEvent:
+		ctx, _ := evt.Context.(event.GovernanceContext)
+		certs := len(payload.DRepCertificates) +
+			len(payload.VoteDelegationCertificates) +
+			len(payload.CommitteeCertificates)
+		line = fmt.Sprintf(
+			"%s %-12s slot=%-10d block=%-8d tx=%s proposals=%d votes=%d certs=%d",
+			ts, "GOVERNANCE",
+			ctx.SlotNumber, ctx.BlockNumber,
+			ctx.TransactionHash,
+			len(payload.ProposalProcedures),
+			len(payload.VotingProcedures),
+			certs,
+		)
+	default:
+		line = fmt.Sprintf(
+			"%s %-12s %+v",
+			ts, evt.Type, evt.Payload,
+		)
+	}
+
+	fmt.Fprintln(os.Stdout, line)
+}
+
+// writeJSON writes events as newline-delimited JSON to stdout.
+// Errors are written to stderr to avoid corrupting the JSON stream.
+func (l *LogOutput) writeJSON(evt event.Event) {
+	data, err := json.Marshal(evt)
+	if err != nil {
+		fmt.Fprintf(
+			os.Stderr,
+			"error: failed to marshal event: %v\n",
+			err,
+		)
+		return
+	}
+	os.Stdout.Write(append(data, '\n'))
+}
+
 // Stop the log output
 func (l *LogOutput) Stop() error {
 	if l.eventChan != nil {
 		close(l.eventChan)
+		// Wait for the goroutine to finish processing
+		if l.doneChan != nil {
+			<-l.doneChan
+		}
 		l.eventChan = nil
 	}
 	if l.errorChan != nil {