zapcore: Add PreWriteHook for transforming entries before write (#1534)

This adds a new CheckPreWriteHook type and a Before method on
CheckedEntry that allows transforming the Entry and Fields before they
are written to any registered Cores.

The existing CheckWriteHook (set via After/WithFatalHook) only runs
*after* cores have already written the entry, which means it cannot
modify what gets logged. PreWriteHook fills that gap: it runs before any
Core.Write call, allowing callers to enrich, redact, or reshape log
entries and fields in a composable way.

Multiple pre-write hooks run in the order they were added. Like other
CheckedEntry methods, Before is safe to call on nil references.

Author: sywhang

zapcore/entry.go

@@ -201,6 +201,14 @@ func (a CheckWriteAction) OnWrite(ce *CheckedEntry, _ []Field) {
 
 var _ CheckWriteHook = CheckWriteAction(0)
 
+// CheckPreWriteHook is a function that transforms an Entry and its Fields
+// before they are written to cores. Register one on a CheckedEntry with the
+// Before method.
+//
+// Pre-write hooks run in the order they were added, before any Core's Write
+// method is called. They may modify the Entry and Fields freely.
+type CheckPreWriteHook func(Entry, []Field) (Entry, []Field)
+
 // CheckedEntry is an Entry together with a collection of Cores that have
 // already agreed to log it.
 //
@@ -213,6 +221,7 @@ type CheckedEntry struct {
 	dirty       bool // best-effort detection of pool misuse
 	after       CheckWriteHook
 	cores       []Core
+	before      []CheckPreWriteHook
 }
 
 func (ce *CheckedEntry) reset() {
@@ -225,6 +234,10 @@ func (ce *CheckedEntry) reset() {
 		ce.cores[i] = nil
 	}
 	ce.cores = ce.cores[:0]
+	for i := range ce.before {
+		ce.before[i] = nil
+	}
+	ce.before = ce.before[:0]
 }
 
 // Write writes the entry to the stored Cores, returns any errors, and returns
@@ -253,9 +266,14 @@ func (ce *CheckedEntry) Write(fields ...Field) {
 	}
 	ce.dirty = true
 
+	ent := ce.Entry
+	for i := range ce.before {
+		ent, fields = ce.before[i](ent, fields)
+	}
+
 	var err error
 	for i := range ce.cores {
-		err = multierr.Append(err, ce.cores[i].Write(ce.Entry, fields))
+		err = multierr.Append(err, ce.cores[i].Write(ent, fields))
 	}
 	if err != nil && ce.ErrorOutput != nil {
 		_, _ = fmt.Fprintf(
@@ -295,6 +313,18 @@ func (ce *CheckedEntry) Should(ent Entry, should CheckWriteAction) *CheckedEntry
 	return ce.After(ent, should)
 }
 
+// Before adds a pre-write hook that transforms the Entry and Fields before
+// they are written to any registered Cores. Multiple hooks run in the order
+// they were added. It's safe to call this on nil CheckedEntry references.
+func (ce *CheckedEntry) Before(ent Entry, hook CheckPreWriteHook) *CheckedEntry {
+	if ce == nil {
+		ce = getCheckedEntry()
+		ce.Entry = ent
+	}
+	ce.before = append(ce.before, hook)
+	return ce
+}
+
 // After sets this CheckEntry's CheckWriteHook, which will be called after this
 // log entry has been written. It's safe to call this on nil CheckedEntry
 // references.

zapcore/entry_test.go

@@ -147,3 +147,82 @@ type customHook struct {
 func (c *customHook) OnWrite(_ *CheckedEntry, _ []Field) {
 	c.called = true
 }
+
+func TestCheckedEntryBefore(t *testing.T) {
+	t.Run("nil is safe", func(t *testing.T) {
+		var ce *CheckedEntry
+		ce = ce.Before(Entry{Message: "hello"}, func(ent Entry, fields []Field) (Entry, []Field) {
+			ent.Message = "modified"
+			return ent, fields
+		})
+		assert.NotNil(t, ce)
+		assert.Equal(t, "hello", ce.Entry.Message)
+	})
+
+	t.Run("modifies entry and fields", func(t *testing.T) {
+		core := &recordingCore{}
+		var ce *CheckedEntry
+		ce = ce.AddCore(Entry{Message: "original"}, core)
+		ce = ce.Before(Entry{}, func(ent Entry, fields []Field) (Entry, []Field) {
+			ent.Message = "modified"
+			fields = append(fields, Field{Key: "added", Type: StringType, String: "value"})
+			return ent, fields
+		})
+		ce.Write(Field{Key: "initial", Type: StringType, String: "v"})
+
+		assert.Equal(t, "modified", core.entry.Message)
+		assert.Len(t, core.fields, 2)
+		assert.Equal(t, "initial", core.fields[0].Key)
+		assert.Equal(t, "added", core.fields[1].Key)
+	})
+
+	t.Run("multiple hooks chain in order", func(t *testing.T) {
+		core := &recordingCore{}
+		var ce *CheckedEntry
+		ce = ce.AddCore(Entry{Message: "start"}, core)
+		ce = ce.Before(Entry{}, func(ent Entry, fields []Field) (Entry, []Field) {
+			ent.Message = ent.Message + "-first"
+			return ent, fields
+		})
+		ce = ce.Before(Entry{}, func(ent Entry, fields []Field) (Entry, []Field) {
+			ent.Message = ent.Message + "-second"
+			return ent, fields
+		})
+		ce.Write()
+
+		assert.Equal(t, "start-first-second", core.entry.Message)
+	})
+
+	t.Run("hooks reset on pool reuse", func(t *testing.T) {
+		core := &recordingCore{}
+		var ce *CheckedEntry
+		ce = ce.AddCore(Entry{Message: "first"}, core)
+		ce = ce.Before(Entry{}, func(ent Entry, fields []Field) (Entry, []Field) {
+			ent.Message = "hooked"
+			return ent, fields
+		})
+		ce.Write()
+		assert.Equal(t, "hooked", core.entry.Message)
+
+		// Get a new entry from the pool — hooks should be cleared.
+		ce2 := getCheckedEntry()
+		assert.Empty(t, ce2.before)
+		putCheckedEntry(ce2)
+	})
+}
+
+// recordingCore captures the last entry and fields written to it.
+type recordingCore struct {
+	entry  Entry
+	fields []Field
+}
+
+func (c *recordingCore) Enabled(Level) bool                              { return true }
+func (c *recordingCore) With([]Field) Core                               { return c }
+func (c *recordingCore) Check(ent Entry, ce *CheckedEntry) *CheckedEntry { return ce.AddCore(ent, c) }
+func (c *recordingCore) Sync() error                                     { return nil }
+func (c *recordingCore) Write(ent Entry, fields []Field) error {
+	c.entry = ent
+	c.fields = fields
+	return nil
+}