AppendEncoder can be used to add fields to all log entries that pass through it. It is a wrapper around another encoder, which it uses to actually encode the log entries. It is most useful for adding information about the Caddy instance that is producing the log entries, possibly via an environment variable.

Field name	Field type	Comment
WrappedRaw	json.RawMessage	The underlying encoder that actually encodes the log entries. If not specified, defaults to "json", unless the output is a terminal, in which case it defaults to "console".
Fields	map[string]any	A map of field names to their values. The values can be global placeholders (e.g. env vars), or constants. Note that the encoder does not run as part of an HTTP request context, so request placeholders are not available.
wrapped	zapcore.Encoder	No comment on field.
repl	*caddy.Replacer	No comment on field.
wrappedIsDefault	bool	No comment on field.
ctx	caddy.Context	No comment on field.

ConsoleEncoder encodes log entries that are mostly human-readable.

Field name	Field type	Comment
	zapcore.Encoder	No comment on field.
	LogEncoderConfig	No comment on field.

CookieFilter is a Caddy log field filter that filters cookies.

This filter updates the logged HTTP header string to remove, replace or hash cookies containing sensitive data. For instance, it can be used to redact any kind of secrets, such as session IDs.

If several actions are configured for the same cookie name, only the first will be applied.

Field name	Field type	Comment
Actions	[]cookieFilterAction	A list of actions to apply to the cookies.

DeleteFilter is a Caddy log field filter that deletes the field.

FileWriter can write logs to files. By default, log files are rotated ("rolled") when they get large, and old log files get deleted, to ensure that the process does not exhaust disk space.

Field name	Field type	Comment
Filename	string	Filename is the name of the file to write.
Mode	fileMode	The file permissions mode. 0600 by default.
Roll	*bool	Roll toggles log rolling or rotation, which is enabled by default.
RollSizeMB	int	When a log file reaches approximately this size, it will be rotated.
RollCompress	*bool	Whether to compress rolled files. Default: true
RollLocalTime	bool	Whether to use local timestamps in rolled filenames. Default: false
RollKeep	int	The maximum number of rolled log files to keep. Default: 10
RollKeepDays	int	How many days to keep rolled log files. Default: 90

FilterEncoder can filter (manipulate) fields on log entries before they are actually encoded by an underlying encoder.

Field name	Field type	Comment
WrappedRaw	json.RawMessage	The underlying encoder that actually encodes the log entries. If not specified, defaults to "json", unless the output is a terminal, in which case it defaults to "console".
FieldsRaw	map[string]json.RawMessage	A map of field names to their filters. Note that this is not a module map; the keys are field names. Nested fields can be referenced by representing a layer of nesting with >. In other words, for an object like {"a":{"b":0}}, the inner field can be referenced as a>b. The following fields are fundamental to the log and cannot be filtered because they are added by the underlying logging library as special cases: ts, level, logger, and msg.
wrapped	zapcore.Encoder	No comment on field.
Fields	map[string]LogFieldFilter	No comment on field.
keyPrefix	string	used to keep keys unique across nested objects
wrappedIsDefault	bool	No comment on field.
ctx	caddy.Context	No comment on field.

HashFilter is a Caddy log field filter that replaces the field with the initial 4 bytes of the SHA-256 hash of the content. Operates on string fields, or on arrays of strings where each string is hashed.

IPMaskFilter is a Caddy log field filter that masks IP addresses in a string, or in an array of strings. The string may be a comma separated list of IP addresses, where all of the values will be masked.

Field name	Field type	Comment
IPv4MaskRaw	int	The IPv4 mask, as an subnet size CIDR.
IPv6MaskRaw	int	The IPv6 mask, as an subnet size CIDR.
v4Mask	net.IPMask	No comment on field.
v6Mask	net.IPMask	No comment on field.

JSONEncoder encodes entries as JSON.

Field name	Field type	Comment
	zapcore.Encoder	No comment on field.
	LogEncoderConfig	No comment on field.

LogEncoderConfig holds configuration common to most encoders.

Field name	Field type	Comment
MessageKey	*string	No comment on field.
LevelKey	*string	No comment on field.
TimeKey	*string	No comment on field.
NameKey	*string	No comment on field.
CallerKey	*string	No comment on field.
StacktraceKey	*string	No comment on field.
LineEnding	*string	No comment on field.
TimeFormat	string	Recognized values are: unix_seconds_float, unix_milli_float, unix_nano, iso8601, rfc3339, rfc3339_nano, wall, wall_milli, wall_nano, common_log. The value may also be custom format per the Go time package layout specification, as described here.
TimeLocal	bool	No comment on field.
DurationFormat	string	Recognized values are: s/second/seconds, ns/nano/nanos, ms/milli/millis, string. Empty and unrecognized value default to seconds.
LevelFormat	string	Recognized values are: lower, upper, color. Empty and unrecognized value default to lower.

LogFieldFilter can filter (or manipulate) a field in a log entry.

Field name	Field type	Comment
type	any	No comment on field.

MockCore is a no-op module, purely for testing

Field name	Field type	Comment
	zapcore.Core	No comment on field.

NetWriter implements a log writer that outputs to a network socket. If the socket goes down, it will dump logs to stderr while it attempts to reconnect.

Field name	Field type	Comment
Address	string	The address of the network socket to which to connect.
DialTimeout	caddy.Duration	The timeout to wait while connecting to the socket.
SoftStart	bool	If enabled, allow connections errors when first opening the writer. The error and subsequent log entries will be reported to stderr instead until a connection can be re-established.
addr	caddy.NetworkAddress	No comment on field.

QueryFilter is a Caddy log field filter that filters query parameters from a URL.

This filter updates the logged URL string to remove, replace or hash query parameters containing sensitive data. For instance, it can be used to redact any kind of secrets which were passed as query parameters, such as OAuth access tokens, session IDs, magic link tokens, etc.

Field name	Field type	Comment
Actions	[]queryFilterAction	A list of actions to apply to the query parameters of the URL.

RegexpFilter is a Caddy log field filter that replaces the field matching the provided regexp with the indicated string. If the field is an array of strings, each of them will have the regexp replacement applied.

Field name	Field type	Comment
RawRegexp	string	The regular expression pattern defining what to replace.
Value	string	The value to use as replacement
regexp	*regexp.Regexp	No comment on field.

RenameFilter is a Caddy log field filter that renames the field's key with the indicated name.

Field name	Field type	Comment
Name	string	No comment on field.

ReplaceFilter is a Caddy log field filter that replaces the field with the indicated string.

Field name	Field type	Comment
Value	string	No comment on field.

This type doesn't have documentation.

Field name	Field type	Comment
Type	filterAction	replace to replace the value of the cookie, hash to replace it with the 4 initial bytes of the SHA-256 of its content or delete to remove it entirely.
Name	string	The name of the cookie.
Value	string	The value to use as replacement if the action is replace.

fileMode is a string made of 1 to 4 octal digits representing a numeric mode as specified with the chmod unix command. "0777" and "777" are thus equivalent values.

Field name	Field type	Comment
type	os.FileMode	No comment on field.

This type doesn't have documentation.

Field name	Field type	Comment
type	string	No comment on field.

logObjectMarshalerWrapper allows us to recursively filter fields of objects as they get encoded.

Field name	Field type	Comment
enc	FilterEncoder	No comment on field.
marsh	zapcore.ObjectMarshaler	No comment on field.

nopEncoder is a zapcore.Encoder that does nothing.

This type doesn't have documentation.

Field name	Field type	Comment
Type	filterAction	replace to replace the value(s) associated with the parameter(s), hash to replace them with the 4 initial bytes of the SHA-256 of their content or delete to remove them entirely.
Parameter	string	The name of the query parameter.
Value	string	The value to use as replacement if the action is replace.

redialerConn wraps an underlying Conn so that if any writes fail, the connection is redialed and the write is retried.

Field name	Field type	Comment
	net.Conn	No comment on field.
connMu	sync.RWMutex	No comment on field.
nw	NetWriter	No comment on field.
timeout	time.Duration	No comment on field.
lastRedial	time.Time	No comment on field.

ConfigureDefaultFormat will set the default format to "console" if the writer is a terminal. If already configured, it passes through the writer so a deeply nested encoder can configure its own default format.

Uses: fmt.Errorf, os.Stderr, term.IsTerminal.

Provision sets up the encoder.

Uses: fmt.Errorf, zapcore.Encoder.

UnmarshalCaddyfile sets up the module from Caddyfile tokens. Syntax:

append {
    wrap <another encoder>
    fields {
        <field> <value>
    }
    <field> <value>
}

Uses: caddyconfig.JSONModuleObject, caddyfile.UnmarshalModule, zapcore.Encoder.

Provision sets up the encoder.

Uses: zapcore.NewConsoleEncoder.

UnmarshalCaddyfile sets up the module from Caddyfile tokens. Syntax:

console {
    <common encoder config subdirectives...>
}

See the godoc on the LogEncoderConfig type for the syntax of subdirectives that are common to most/all encoders.

UnmarshalCaddyfile sets up the module from Caddyfile tokens.

Validate checks that action types are correct.

Provision sets up the module

Uses: fmt.Errorf.

UnmarshalCaddyfile sets up the module from Caddyfile tokens. Syntax:

file <filename> {
    mode          <mode>
    roll_disabled
    roll_size     <size>
    roll_uncompressed
    roll_local_time
    roll_keep     <num>
    roll_keep_for <days>
}

The roll_size value has megabyte resolution. Fractional values are rounded up to the next whole megabyte (MiB).

By default, compression is enabled, but can be turned off by setting the roll_uncompressed option.

The roll_keep_for duration has day resolution. Fractional values are rounded up to the next whole number of days.

If any of the mode, roll_size, roll_keep, or roll_keep_for subdirectives are omitted or set to a zero value, then Caddy's default value for that subdirective is used.

Uses: humanize.MiByte, humanize.ParseBytes, math.Ceil, strconv.Atoi.

ConfigureDefaultFormat will set the default format to "console" if the writer is a terminal. If already configured as a filter encoder, it passes through the writer so a deeply nested filter encoder can configure its own default format.

Uses: fmt.Errorf, os.Stderr, term.IsTerminal.

Provision sets up the encoder.

Uses: fmt.Errorf, zapcore.Encoder.

UnmarshalCaddyfile sets up the module from Caddyfile tokens. Syntax:

filter {
    wrap <another encoder>
    fields {
        <field> <filter> {
            <filter options>
        }
    }
    <field> <filter> {
        <filter options>
    }
}

Uses: caddyconfig.JSONModuleObject, caddyfile.UnmarshalModule, json.RawMessage, zapcore.Encoder.

Filter filters the input field with the replacement value.

Uses: caddyhttp.LoggableStringArray.

UnmarshalCaddyfile sets up the module from Caddyfile tokens.

Provision parses m's IP masks, from integers.

Uses: net.CIDRMask, net.IPMask.

UnmarshalCaddyfile sets up the module from Caddyfile tokens.

Uses: strconv.Atoi.

Provision sets up the encoder.

Uses: zapcore.NewJSONEncoder.

UnmarshalCaddyfile sets up the module from Caddyfile tokens. Syntax:

json {
    <common encoder config subdirectives...>
}

See the godoc on the LogEncoderConfig type for the syntax of subdirectives that are common to most/all encoders.

UnmarshalCaddyfile populates the struct from Caddyfile tokens. Syntax:

{
    message_key     <key>
    level_key       <key>
    time_key        <key>
    name_key        <key>
    caller_key      <key>
    stacktrace_key  <key>
    line_ending     <char>
    time_format     <format>
    time_local
    duration_format <format>
    level_format    <format>
}

ZapcoreEncoderConfig returns the equivalent zapcore.EncoderConfig. If lec is nil, zap.NewProductionEncoderConfig() is returned.

Uses: time.RFC3339, time.RFC3339Nano, time.Time, zap.NewProductionEncoderConfig, zapcore.CapitalColorLevelEncoder, zapcore.CapitalLevelEncoder, zapcore.DurationEncoder, zapcore.EpochMillisTimeEncoder, zapcore.EpochNanosTimeEncoder, zapcore.EpochTimeEncoder, zapcore.ISO8601TimeEncoder, zapcore.LevelEncoder, zapcore.LowercaseLevelEncoder, zapcore.MillisDurationEncoder, zapcore.NanosDurationEncoder, zapcore.PrimitiveArrayEncoder, zapcore.SecondsDurationEncoder, zapcore.StringDurationEncoder, zapcore.TimeEncoder.

Provision sets up the module.

Uses: fmt.Errorf.

UnmarshalCaddyfile sets up the handler from Caddyfile tokens. Syntax:

net <address> {
    dial_timeout <duration>
    soft_start
}

UnmarshalCaddyfile sets up the module from Caddyfile tokens.

Validate checks that action types are correct.

Filter filters the input field with the replacement value if it matches the regexp.

Uses: caddyhttp.LoggableStringArray.

Provision compiles m's regexp.

Uses: regexp.Compile.

UnmarshalCaddyfile sets up the module from Caddyfile tokens.

Filter renames the input field with the replacement name.

UnmarshalCaddyfile sets up the module from Caddyfile tokens.

Filter filters the input field with the replacement value.

Uses: zapcore.StringType.

UnmarshalCaddyfile sets up the module from Caddyfile tokens.

MarshalJSON satisfies json.Marshaler.

Uses: fmt.Sprintf.

UnmarshalJSON satisfies json.Unmarshaler.

Uses: io.EOF, json.Unmarshal.

Write wraps the underlying Conn.Write method, but if that fails, it will re-dial the connection anew and try writing again.

Uses: os.Stderr, time.Now, time.Second, time.Since.

AddArray is part of the zapcore.ObjectEncoder interface.

AddBinary is part of the zapcore.ObjectEncoder interface.

AddBool is part of the zapcore.ObjectEncoder interface.

AddByteString is part of the zapcore.ObjectEncoder interface.

AddComplex128 is part of the zapcore.ObjectEncoder interface.

AddComplex64 is part of the zapcore.ObjectEncoder interface.

AddDuration is part of the zapcore.ObjectEncoder interface.

AddFloat32 is part of the zapcore.ObjectEncoder interface.

AddFloat64 is part of the zapcore.ObjectEncoder interface.

AddInt is part of the zapcore.ObjectEncoder interface.

AddInt16 is part of the zapcore.ObjectEncoder interface.

AddInt32 is part of the zapcore.ObjectEncoder interface.

AddInt64 is part of the zapcore.ObjectEncoder interface.

AddInt8 is part of the zapcore.ObjectEncoder interface.

AddObject is part of the zapcore.ObjectEncoder interface.

AddReflected is part of the zapcore.ObjectEncoder interface.

AddString is part of the zapcore.ObjectEncoder interface.

AddTime is part of the zapcore.ObjectEncoder interface.

AddUint is part of the zapcore.ObjectEncoder interface.

AddUint16 is part of the zapcore.ObjectEncoder interface.

AddUint32 is part of the zapcore.ObjectEncoder interface.

AddUint64 is part of the zapcore.ObjectEncoder interface.

AddUint8 is part of the zapcore.ObjectEncoder interface.

AddUintptr is part of the zapcore.ObjectEncoder interface.

CaddyModule returns the Caddy module information.

Clone is part of the zapcore.ObjectEncoder interface.

EncodeEntry partially implements the zapcore.Encoder interface.

Uses: strings.Count, strings.HasPrefix, strings.HasSuffix, strings.Trim, zap.Any, zap.String.

OpenNamespace is part of the zapcore.ObjectEncoder interface.

CaddyModule returns the Caddy module information.

CaddyModule returns the Caddy module information.

Filter filters the input field.

Uses: caddyhttp.LoggableStringArray, http.Header, http.Request.

CaddyModule returns the Caddy module information.

Filter filters the input field.

Uses: zapcore.SkipType.

UnmarshalCaddyfile sets up the module from Caddyfile tokens.

CaddyModule returns the Caddy module information.

OpenWriter opens a new file writer.

Uses: filepath.Dir, fmt.Errorf, os.Chmod, os.FileMode, os.MkdirAll, os.ModePerm, os.O_APPEND, os.O_CREATE, os.O_WRONLY, os.OpenFile.

WriterKey returns a unique key representing this fw.

AddArray is part of the zapcore.ObjectEncoder interface. Array elements do not get filtered.

Uses: zap.Array.

AddBinary is part of the zapcore.ObjectEncoder interface.

AddBool is part of the zapcore.ObjectEncoder interface.

AddByteString is part of the zapcore.ObjectEncoder interface.

AddComplex128 is part of the zapcore.ObjectEncoder interface.

AddComplex64 is part of the zapcore.ObjectEncoder interface.

AddDuration is part of the zapcore.ObjectEncoder interface.

AddFloat32 is part of the zapcore.ObjectEncoder interface.

AddFloat64 is part of the zapcore.ObjectEncoder interface.

AddInt is part of the zapcore.ObjectEncoder interface.

AddInt16 is part of the zapcore.ObjectEncoder interface.

AddInt32 is part of the zapcore.ObjectEncoder interface.

AddInt64 is part of the zapcore.ObjectEncoder interface.

AddInt8 is part of the zapcore.ObjectEncoder interface.

AddObject is part of the zapcore.ObjectEncoder interface.

AddReflected is part of the zapcore.ObjectEncoder interface.

AddString is part of the zapcore.ObjectEncoder interface.

AddTime is part of the zapcore.ObjectEncoder interface.

AddUint is part of the zapcore.ObjectEncoder interface.

AddUint16 is part of the zapcore.ObjectEncoder interface.

AddUint32 is part of the zapcore.ObjectEncoder interface.

AddUint64 is part of the zapcore.ObjectEncoder interface.

AddUint8 is part of the zapcore.ObjectEncoder interface.

AddUintptr is part of the zapcore.ObjectEncoder interface.

CaddyModule returns the Caddy module information.

Clone is part of the zapcore.ObjectEncoder interface. We don't use it as of Oct 2019 (v2 beta 7), I'm not really sure what it'd be useful for in our case.

EncodeEntry partially implements the zapcore.Encoder interface.

OpenNamespace is part of the zapcore.ObjectEncoder interface.

CaddyModule returns the Caddy module information.

CaddyModule returns the Caddy module information.

Filter filters the input field.

Uses: caddyhttp.LoggableStringArray.

CaddyModule returns the Caddy module information.

CaddyModule returns the Caddy module information.

CaddyModule returns the Caddy module information.

OpenWriter opens a new network connection.

Uses: fmt.Fprintf, os.Stderr, time.Duration.

WriterKey returns a unique key representing this nw.

CaddyModule returns the Caddy module information.

Filter filters the input field.

Uses: caddyhttp.LoggableStringArray.

CaddyModule returns the Caddy module information.

CaddyModule returns the Caddy module information.

CaddyModule returns the Caddy module information.

Uses: errors.New.

MarshalLogObject implements the zapcore.ObjectMarshaler interface.

AddArray is part of the zapcore.ObjectEncoder interface. Array elements do not get filtered.

AddBinary is part of the zapcore.ObjectEncoder interface.

AddBool is part of the zapcore.ObjectEncoder interface.

AddByteString is part of the zapcore.ObjectEncoder interface.

AddComplex128 is part of the zapcore.ObjectEncoder interface.

AddComplex64 is part of the zapcore.ObjectEncoder interface.

AddDuration is part of the zapcore.ObjectEncoder interface.

AddFloat32 is part of the zapcore.ObjectEncoder interface.

AddFloat64 is part of the zapcore.ObjectEncoder interface.

AddInt is part of the zapcore.ObjectEncoder interface.

AddInt16 is part of the zapcore.ObjectEncoder interface.

AddInt32 is part of the zapcore.ObjectEncoder interface.

AddInt64 is part of the zapcore.ObjectEncoder interface.

AddInt8 is part of the zapcore.ObjectEncoder interface.

AddObject is part of the zapcore.ObjectEncoder interface.

AddReflected is part of the zapcore.ObjectEncoder interface.

AddString is part of the zapcore.ObjectEncoder interface.

AddTime is part of the zapcore.ObjectEncoder interface.

AddUint is part of the zapcore.ObjectEncoder interface.

AddUint16 is part of the zapcore.ObjectEncoder interface.

AddUint32 is part of the zapcore.ObjectEncoder interface.

AddUint64 is part of the zapcore.ObjectEncoder interface.

AddUint8 is part of the zapcore.ObjectEncoder interface.

AddUintptr is part of the zapcore.ObjectEncoder interface.

Clone is part of the zapcore.ObjectEncoder interface. We don't use it as of Oct 2019 (v2 beta 7), I'm not really sure what it'd be useful for in our case.

EncodeEntry partially implements the zapcore.Encoder interface.

OpenNamespace is part of the zapcore.ObjectEncoder interface.