Merge pull request #11 from domonda/struct-field-modifiers

feat: tag-driven struct field logging with omit/redact modifiers

Author: ungerik

README.md

@@ -34,7 +34,7 @@ Fast and feature-rich structured logging library for Go
 - [Advanced Features](#advanced-features)
   - [Custom Colorizers](#custom-colorizers)
   - [Call Stack Logging](#call-stack-logging)
-  - [Redacting Sensitive Data](#redacting-sensitive-data)
+  - [Struct Field Logging: Tags and Modifiers](#struct-field-logging-tags-and-modifiers)
   - [Custom Levels](#custom-levels)
   - [Level Filtering](#level-filtering)
   - [Parsing Log Timestamps](#parsing-log-timestamps)
@@ -55,6 +55,7 @@ Fast and feature-rich structured logging library for Go
 
 - **High Performance**: Zero-allocation logging for JSON, text, and complex fields (error, time.Time)
 - **Structured Logging**: Type-safe field methods for all Go primitives including native time.Time and UUID
+- **Tag-driven Struct Logging**: `StructFields` and `TaggedStructFields` honor `golog`, `log`, and `json` tags with `omitempty`, `omitzero`, `omitnull`, and `redact` modifiers. `encoding/json`-compatible where applicable
 - **Multiple Output Formats**: JSON and human-readable text output
 - **Terminal Auto-Detection**: Automatically switches between colored text (TTY) and JSON (non-TTY)
 - **Configurable Log Levels**: TRACE, DEBUG, INFO, WARN, ERROR, FATAL with flexible filtering
@@ -497,30 +498,95 @@ defer func() {
 }()
 ```
 
-### Redacting Sensitive Data
+### Struct Field Logging: Tags and Modifiers
 
-Use the `golog:"redact"` struct tag to automatically redact sensitive fields when logging structs:
+`StructFields` and `TaggedStructFields` walk a struct via reflection and log
+each matching field as an attribute. They are driven entirely by struct tags,
+with modifiers that mirror `encoding/json.Marshal` semantics plus a handful of
+golog-specific additions.
+
+#### Tag resolution
+
+`StructFields(s)` looks for tags in this order — **first match wins**:
+
+1. `golog:"..."`
+2. `log:"..."`
+3. `json:"..."`
+
+Only the first tag present on a field is consulted. Other tags on the same field
+are ignored. Fields with **none** of those tags are skipped entirely (this is a
+deliberate difference from `encoding/json.Marshal`, which would use the Go field
+name: golog errs on the side of not leaking untagged internal fields into logs).
+
+`TaggedStructFields(s, "json")` does the same with a single caller-chosen tag.
+
+**Wildcard escape hatch:** passing the empty string as the key tag,
+`TaggedStructFields(s, "")`, matches every exported field with no rename and no
+modifiers — every field is logged under its Go name, struct tags ignored. Use
+this when you want to dump a struct wholesale and you don't care about per-field
+tags. (`StructFields(s)` deliberately stays strict tag-driven; the wildcard is
+opt-in.)
+
+#### Tag value grammar
+
+Each tag value is `name,mod1,mod2,...`:
+
+| Tag value                    | Log key       | Notes                                     |
+|------------------------------|---------------|-------------------------------------------|
+| `"field_name"`               | `field_name`  | explicit name                             |
+| `""`                         | Go field name | empty → fall back to field name            |
+| `",omitempty"`               | Go field name | empty name with modifier → fall back       |
+| `"-"` (bare, no comma)       | *skipped*     | only the bare form skips                  |
+| `"-,..."` (comma follows)    | `-`           | literal field name `-` + modifiers        |
+
+Whitespace around the name and each modifier is trimmed. Unknown modifier
+tokens are ignored silently, so `json:"name,omitnull"` is a valid tag for both
+`encoding/json.Marshal` (which ignores `omitnull`) and golog (which honors it).
+
+#### Modifiers
+
+| Modifier    | Suppress when…                                                                 |
+|-------------|---------------------------------------------------------------------------------|
+| `omitempty` | `false`, `0`, nil pointer/interface, empty array/slice/map/string. Exactly matches `encoding/json.Marshal`. Does **not** catch zero structs or `time.Time{}`. |
+| `omitzero`  | The type's `IsZero() bool` method returns true, **or** the value is the Go zero value (via `reflect.Value.IsZero`). Catches `time.Time{}` and any zero struct. Strict superset of `encoding/json`'s Go 1.24 `omitzero`. Both value-receiver and pointer-receiver `IsZero` methods are honored. |
+| `omitnull`  | The type's `IsNull() bool` method returns true. Falls back to `omitzero` semantics when the type has no `IsNull` method. Use for nullable wrappers (`golog.Timestamp`, `sql.NullString`, `uu.NullableID`) where "null" is richer than "all bytes zero". Both value-receiver and pointer-receiver `IsNull` methods are honored. |
+| `redact`    | (not a suppression modifier) — replaces the value with `"***REDACTED***"` before it reaches the writer. Also spelled `redacted`. Suppression modifiers win over redact: `json:",redact,omitempty"` on an empty string emits nothing, not the marker. |
+
+Modifiers OR together — any passing check suppresses the field.
+
+#### Complete example
 
 ```go
 type User struct {
-    ID       int    `json:"id"`
-    Username string `json:"username"`
-    Password string `json:"password" golog:"redact"`
-    APIKey   string `json:"api_key"  golog:"redact"`
+    ID        int             `json:"id"`
+    Name      string          `json:"name,omitempty"`
+    APIKey    string          `json:",redact"`
+    CreatedAt time.Time       `json:"created_at,omitzero"`
+    DeletedAt golog.Timestamp `json:"deleted_at,omitnull"`
+    Internal  string          // no json/log/golog tag → never logged
 }
 
 user := User{
-    ID:       123,
-    Username: "john_doe",
-    Password: "secret123",
-    APIKey:   "sk-abc123",
+    ID:        123,
+    Name:      "john_doe",
+    APIKey:    "sk-abc123",
+    CreatedAt: time.Now(),
+    // DeletedAt left as zero Timestamp
+    Internal:  "debug-only",
 }
 
-log.Info("User logged in").StructFields(user).Log()
-// Output: ... id=123 username="john_doe" password="***REDACTED***" api_key="***REDACTED***"
+log.Info("user").TaggedStructFields(user, "json").Log()
+// Output: ... id=123 name="john_doe" APIKey="***REDACTED***" created_at="2026-04-14T..."
+// (DeletedAt suppressed by omitnull, Internal never considered.)
 ```
 
-The `golog:"redact"` tag works with both `StructFields()` and `TaggedStructFields()` methods.
+> **Breaking changes in this release**
+>
+> - `golog:"redact"` (bare, single token) **no longer triggers redaction** — under the unified parser it names the field `"redact"`. Migrate to `golog:",redact"` (or combine with other modifiers: `golog:",redact,omitempty"`).
+> - `StructFields(s)` on an untagged struct now logs **nothing**. Previously it logged every exported field by its Go name. The cleanest replacement is `TaggedStructFields(s, "")`, the wildcard escape hatch documented above. Per-field, you can also add an empty tag like `json:""` or `golog:""` to opt in.
+> - `TaggedStructFields(s, "json")` with `json:""` now logs the field (Go field name), previously it skipped. This is `encoding/json.Marshal` parity.
+
+`omitnull` vs `omitzero`, concretely: `sql.NullString{Valid: false, String: ""}` and `sql.NullString{Valid: true, String: ""}` are both the reflect zero value, but only the first is actually null. `omitnull` with a proper `IsNull` method distinguishes the two; `omitzero` cannot.
 
 ### Custom Levels
 

message.go

@@ -10,7 +10,6 @@ import (
 	"go/token"
 	"net/http"
 	"reflect"
-	"strings"
 	"time"
 	"unicode/utf8"
 )
@@ -385,24 +384,56 @@ func (m *Message) tryWriteInterface(w Writer, val reflect.Value) (written bool)
 	return false
 }
 
-// StructFields calls Any(fieldName, fieldValue) for every exported struct field.
-// Fields with the tag `golog:"redact"` will have their value replaced with "***REDACTED***".
+// StructFields logs each exported field of strct whose struct tag matches,
+// in order, one of "golog", "log", "json". The first tag present on a field
+// determines both the log key and which modifiers apply; other tags on the
+// same field are ignored.
+//
+// Fields with no tag from that list are not logged. To log a field under its
+// Go field name, give it an empty tag value such as `json:""` or `golog:""`.
+//
+// Supported modifiers (comma-separated after the name):
+//   - omitempty — suppress the field when its value is empty per
+//     encoding/json semantics (false, 0, nil pointer/interface, empty
+//     array/slice/map/string).
+//   - omitzero — suppress when the value is zero. Calls IsZero() bool if
+//     the type implements it (so time.Time{} is suppressed), else falls
+//     back to reflect.Value.IsZero().
+//   - omitnull — suppress when the value is null. Calls IsNull() bool if
+//     the type implements it (so zero golog.Timestamp is suppressed),
+//     else falls back to omitzero semantics.
+//   - redact (also spelled "redacted") — replace the value with
+//     "***REDACTED***" in the log output. Suppression modifiers win over
+//     redact: `json:",redact,omitempty"` on an empty string emits nothing,
+//     not the redaction marker.
+//
+// Unknown modifier tokens are ignored silently, matching encoding/json's
+// forward-compat posture.
+//
+// Breaking change vs. earlier versions: the bare form `golog:"redact"`
+// no longer triggers redaction — under the new unified parser it would
+// name the field "redact" in the log. Migrate to `golog:",redact"`.
 func (m *Message) StructFields(strct any) *Message {
 	if m == nil || strct == nil {
 		return m
 	}
-	m.structFields(reflect.ValueOf(strct), "")
+	m.structFields(reflect.ValueOf(strct), "golog", "log", "json")
 	return m
 }
 
-// TaggedStructFields calls Any(fieldTag, fieldValue) for every exported struct field
-// that has the passed keyTag with the tag value not being empty or "-".
-// Tag values are only considered until the first comma character,
-// so `tag:"hello_world,omitempty"` will result in the fieldTag "hello_world".
-// Fields with the following tags will be ignored: `keyTag:"-"`, `keyTag:""` `keyTag:",xxx"`
-// where keyTag is the passed keyTag parameter.
-// Fields with the tag `golog:"redact"` will have their value replaced with "***REDACTED***"
-// (unless keyTag is "golog", in which case the tag value is used as the field key).
+// TaggedStructFields logs each exported field of strct that carries the
+// given keyTag. It follows the same tag-value grammar and modifier set as
+// [Message.StructFields]; see that method's documentation for details.
+//
+// Fields without the keyTag are not logged. Fields where the keyTag value is
+// exactly "-" are skipped. A tag value with an empty name segment (e.g.
+// `json:""` or `json:",omitempty"`) falls back to the Go field name, matching
+// encoding/json.Marshal.
+//
+// Passing the empty string as keyTag is a wildcard: every exported field is
+// logged under its Go field name, regardless of whether it carries any
+// struct tag. This restores the pre-tag-driven "log every exported field"
+// behavior for callers that want it — `TaggedStructFields(s, "")`.
 func (m *Message) TaggedStructFields(strct any, keyTag string) *Message {
 	if m == nil || strct == nil {
 		return m
@@ -411,7 +442,7 @@ func (m *Message) TaggedStructFields(strct any, keyTag string) *Message {
 	return m
 }
 
-func (m *Message) structFields(v reflect.Value, keyTag string) {
+func (m *Message) structFields(v reflect.Value, keyTags ...string) {
 	for v.Kind() == reflect.Pointer {
 		if v.IsNil() {
 			return
@@ -421,27 +452,63 @@ func (m *Message) structFields(v reflect.Value, keyTag string) {
 	t := v.Type()
 	for i := 0; i < t.NumField(); i++ {
 		field := t.Field(i)
-		switch {
-		case field.Anonymous:
-			m.structFields(v.Field(i), keyTag)
-		case token.IsExported(field.Name):
-			var (
-				key   = field.Name
-				value = v.Field(i).Interface()
-			)
-			if keyTag != "golog" && strings.TrimSpace(field.Tag.Get("golog")) == "redact" {
-				value = "***REDACTED***"
+
+		if field.Anonymous {
+			m.structFields(v.Field(i), keyTags...)
+			continue
+		}
+		if !token.IsExported(field.Name) {
+			continue
+		}
+
+		// Find the first keyTag that "matches" this field. Lookup (not
+		// Get) so that an explicit empty tag value like `json:""` counts
+		// as present.
+		//
+		// An empty string in keyTags is a wildcard: it matches every
+		// exported field with an empty raw tag value (which the caller
+		// later substitutes with the Go field name). This gives callers
+		// a way to dump a struct wholesale under Go field names, e.g.
+		// `TaggedStructFields(s, "")` for log-everything, or
+		// `structFields(v, "json", "")` for "prefer json tag, fall back
+		// to Go field name".
+		var rawTag string
+		var found bool
+		for _, kt := range keyTags {
+			if kt == "" {
+				found = true
+				rawTag = ""
+				break
 			}
-			if keyTag != "" {
-				key = field.Tag.Get(keyTag)
-				key, _, _ = strings.Cut(key, ",")
-				key = strings.TrimSpace(key)
-				if key == "" || key == "-" {
-					continue
-				}
+			if tv, ok := field.Tag.Lookup(kt); ok {
+				rawTag = tv
+				found = true
+				break
 			}
-			m.Any(key, value)
 		}
+		if !found {
+			continue
+		}
+
+		d := parseStructFieldDirectives(rawTag)
+		if d.skip {
+			continue
+		}
+		if d.key == "" {
+			d.key = field.Name
+		}
+
+		fv := v.Field(i)
+		if shouldOmitStructField(fv, d) {
+			continue
+		}
+
+		if d.redact {
+			m.Str(d.key, "***REDACTED***")
+			continue
+		}
+
+		m.Any(d.key, fv.Interface())
 	}
 }