Structured Fields

Events and contexts support typed field methods. All methods are safe to call on a nil receiver (disabled events are no-ops).

Event Fields

Field Shapes

A field normally renders as key=value. SetFieldShapes changes which tokens a named key renders - dropping the key, or wrapping the value - without touching how it is coloured:

clog.SetFieldShapes(clog.FieldShapeMap{
  "region": {OmitKey: true, Prefix: "(", Suffix: ")"},
  "branch": {OmitKey: true, Prefix: "@"},
})

clog.Info().Str("region", "emea").Str("queue", "ingest").Msg("draining")
// INF ℹ️ draining (emea) queue=ingest

OmitKey drops the key and its separator; Prefix and Suffix wrap the value. Keys absent from the map render normally. Like SetParts, shapes replace any previously configured ones - pass nil to clear them.

Shapes compose with the styling tiers rather than competing with them: shape decides the tokens, KeyValues (or Keys, or Values) decides the colour, so a key can render as a badge and still colour each value differently.

clog.SetStyles(&style.Config{
  KeyValues: style.KeyValueMap{
    "region": {Values: style.ValueMap{
      "emea": new(lipgloss.NewStyle().Foreground(lipgloss.Color("2"))),
      "apac": new(lipgloss.NewStyle().Foreground(lipgloss.Color("4"))),
    }},
  },
})
// "(emea)" renders green, brackets included; "(apac)" blue.

The affixes take the value’s resolved style so the whole token reads as one unit. Values styled per segment or by gradient (durations, percentages, quantities, slices, highlighted JSON) have no single colour, so their affixes render plain unless a KeyValues, Keys or Values entry governs the key.

A few details worth knowing:

• Affixes wrap outside quoting and slice brackets: a quoted value renders ("emea north"), a slice renders ⟨[a, b]⟩.
• Shapes are structural, so they apply with colour off too - piped output shows the same tokens as a terminal.
• Sorting still uses the real key, even when it is hidden.
• Shapes apply to the built-in formatter, including animation task rows. A custom Handler receives the raw fields.

Slice Formatting

Slice fields render as [a, b, c] by default. The brackets and separator are configurable:

clog.SetSliceSeparator(" ")        // [a b c]
clog.SetSliceBrackets('(', ')')    // (a, b, c)
clog.SetSliceBrackets('«', '»')    // «a, b, c»
clog.SetSliceBrackets('|', '|')    // |a, b, c| - same char for open and close

Duration Formatting

By default, Duration fields use the shared TimeScale: values below one second render in milliseconds (450ms), values below ten seconds render with up to one decimal place (1.5s, but 1s rather than 1.0s), and larger values round to whole seconds (12s). DurationMinimum defaults to 0, so sub-second values remain visible. Durations >= 1m use composite format (e.g. 1m30s, 2h15m). See FieldFormats for custom scales, scalar round/precision mode, and inheritance. Set DurationFormat to apply a custom formatter per logger instead:

f := clog.DefaultFieldFormats()
f.DurationFormat = commonutil.FormatDuration
clog.SetFieldFormats(f)

clog.Info().Duration("took", time.Since(start)).Msg("done")
// INF ℹ️ done took=2.3s

DurationFormat also applies as a fallback for Elapsed fields. Duration slices continue to use time.Duration.String() per element and do not apply TimeScale. See Elapsed Configuration for details.

Duration Gradient

Duration fields support the same green → yellow → red gradient as Elapsed fields. Enable it by setting a max duration:

f := clog.DefaultFieldFormats()
f.DurationGradientMax = 20 * time.Second
clog.SetFieldFormats(f)

clog.Info().Duration("duration", 2*time.Second).Msg("fast")    // green
clog.Info().Duration("duration", 10*time.Second).Msg("medium") // yellow
clog.Info().Duration("duration", 25*time.Second).Msg("slow")   // red (clamped)

When active, the gradient overrides the FieldDuration segment styles. See Duration Gradient in the styles reference for gradient mode and custom stop configuration.

Nested Fields (Dict)

Group related fields under a common key prefix using dot notation:

clog.Info().Dict("request", clog.Dict().
  Str("method", "GET").
  Int("status", 200),
).Msg("Handled")
// INF ℹ️ Handled request.method=GET request.status=200

Works with sub-loggers too:

logger := clog.With().Dict("db", clog.Dict().
  Str("host", "localhost").
  Int("port", 5432),
).Logger()

Finalising Events

clog.Info().Str("k", "v").Msg("message")  // Log with message
clog.Info().Str("k", "v").Msgf("n=%d", 5) // Log with formatted message
clog.Info().Str("k", "v").Send()           // Log with empty message
clog.Error().Err(err).Send()               // Log with error as message (no error= field)
clog.Error().Err(err).Msg("failed")        // Log with message + error= field

// Lazy message - fn only called when event is enabled:
clog.Debug().MsgFunc(func() string { return expensiveString() })