Updated for v2.8.0 (#389)

Co-authored-by: Mohammed Al Sahaf <msaa1990@gmail.com>
Co-authored-by: Francis Lavoie <lavofr@gmail.com>
Co-authored-by: Nebez Briefkani <me@nebezb.com>
Co-authored-by: Mohammed Al Sahaf <mohammed@caffeinatedwonders.com>

src/docs/markdown/caddyfile/directives/log.md

@@ -32,7 +32,9 @@ To configure Caddy's runtime logs, see the [`log` global option](/docs/caddyfile
 
 The `log` directive applies to the hostnames of the site block it appears in, unless overridden with the `hostnames` subdirective.
 
-When configured, by default all requests to the site will be logged. To conditionally skip some requests from logging, use the [`skip_log` directive](skip_log).
+When configured, by default all requests to the site will be logged. To conditionally skip some requests from logging, use the [`log_skip` directive](log_skip).
+
+To add custom fields to the log entries, use the [`log_append` directive](log_append).
 
 
 - [Syntax](#syntax)
@@ -54,6 +56,7 @@ When configured, by default all requests to the site will be logged. To conditio
 	- [cookie](#cookie)
 	- [regexp](#regexp)
 	- [hash](#hash)
+  - [append](#append)
 - [Examples](#examples)
 
 Since Caddy v2.5, by default, headers with potentially sensitive information (`Cookie`, `Set-Cookie`, `Authorization` and `Proxy-Authorization`) will be logged with empty values. This behaviour can be disabled with the [`log_credentials`](/docs/caddyfile/options#log-credentials) global server option.
@@ -281,14 +284,15 @@ format json
 
 #### filter
 
-Wraps another encoder module, allowing per-field filtering.
+Allows per-field filtering.
 
 ```caddy-d
 format filter {
-	wrap <encode_module> ...
 	fields {
 		<field> <filter> ...
 	}
+	<field> <filter> ...
+	wrap <encode_module> ...
 }
 ```
 
@@ -296,6 +300,11 @@ Nested fields can be referenced by representing a layer of nesting with `>`. In
 
 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`.
 
+Specifying `wrap` is optional; if omitted, a default is chosen depending on whether the current output module is [`stderr`](#stderr) or [`stdout`](#stdout), and is an interactive terminal, in which case [`console`](#console) is chosen, otherwise [`json`](#json) is chosen.
+
+As a shortcut, the `fields` block can be omitted and the filters can be specified directly within the `filter` block.
+
+
 These are the available filters:
 
 ##### delete
@@ -337,7 +346,7 @@ Most commonly, the fields to filter would be:
 - `request>headers>X-Forwarded-For` if behind a reverse proxy
 
 ```caddy-d
-<field> ip_mask {
+<field> ip_mask [<ipv4> [<ipv6>]] {
 	ipv4 <cidr>
 	ipv6 <cidr>
 }
@@ -411,6 +420,26 @@ Useful to obscure the value if it's sensitive, while being able to notice whethe
 <field> hash
 ```
 
+#### append
+
+Appends field(s) to all log entries.
+
+```caddy-d
+format append {
+	fields {
+		<field> <value>
+	}
+	<field> <value>
+	wrap <encode_module> ...
+}
+```
+
+It is most useful for adding information about the Caddy instance that is producing the log entries, possibly via an environment variable. The field values may be global placeholders (e.g. `{env.*}`), but _not_ per-request placeholders due to logs being written outside of the HTTP request context.
+
+Specifying `wrap` is optional; if omitted, a default is chosen depending on whether the current output module is [`stderr`](#stderr) or [`stdout`](#stdout), and is an interactive terminal, in which case [`console`](#console) is chosen, otherwise [`json`](#json) is chosen.
+
+The `fields` block can be omitted and the fields can be specified directly within the `append` block.
+
 
 
 ## Examples
@@ -458,10 +487,7 @@ Delete the `User-Agent` request header from the logs:
 example.com {
 	log {
 		format filter {
-			wrap console
-			fields {
-				request>headers>User-Agent delete
-			}
+			request>headers>User-Agent delete
 		}
 	}
 }
@@ -474,12 +500,9 @@ Redact multiple sensitive cookies. (Note that some sensitive headers are logged
 example.com {
 	log {
 		format filter {
-			wrap console
-			fields {
-				request>headers>Cookie cookie {
-					replace session REDACTED
-					delete secret
-				}
+			request>headers>Cookie cookie {
+				replace session REDACTED
+				delete secret
 			}
 		}
 	}
@@ -495,12 +518,23 @@ Note that as of Caddy v2.7, both `remote_ip` and `client_ip` are logged, where `
 example.com {
 	log {
 		format filter {
-			wrap console
-			fields {
-				request>remote_ip ip_mask {
-					ipv4 16
-					ipv6 32
-				}
+			request>remote_ip ip_mask 16 32
+			request>client_ip ip_mask 16 32
+		}
+	}
+}
+```
+
+
+To append a server ID from an environment variable to all log entries, and chain it with a `filter` to delete a header:
+
+```caddy
+example.com {
+	log {
+		format append {
+			server_id {env.SERVER_ID}
+			wrap filter {
+				request>headers>Cookie delete
 			}
 		}
 	}