site: document support for custom Envoy JSON Fields (#3077)

follow-up for #3059

Co-authored-by: Leah Hanson <lhanson@pivotal.io>
Co-authored-by: Alex Standke <astandke@vmware.com>

site/_guides/structured-logs.md

@@ -9,26 +9,45 @@ This document describes how to configure structured logging for Envoy via Contou
 
 Contour allows you to choose from a set of JSON fields that will be expanded into Envoy templates and sent to Envoy.
 There is a default set of fields if you enable JSON logging, and you may customize which fields you log.
-Custom fields are not currently possible, however, we welcome PRs on the field list.
 
-The canonical location for the current field list is at [JSONFields][1].
-The default list of fields is available at [DefaultFields][2]
+The list of available fields are discoverable in the following objects:
+- [JSONFields][1] are fields that have built in mappings to commonly used envoy
+  operators.
+- [envoySimpleOperators][2] are the names of simple envoy operators that don't
+  require arguments, they are case-insensitive when configured.
+- [envoyComplexOperators][3] are the names of complex envoy operators that require
+  arguments.
+
+The default list of fields is available at [DefaultFields][4].
 
 ## Enabling the feature
 
 To enable the feature you have two options:
 
-- just add `--accesslog-format=json` to your Contour startup line
+- Add `--accesslog-format=json` to your Contour startup line.
 - Add `accesslog-format: json` to your configuration file.
 
+Without any further customization, the [default fields][4] will be used.
+
 ## Customizing logged fields
 
-To customize the logged fields, add a `json-fields` list of strings to your config file.
-These strings must be options from the [list of valid fields][1].
-If the `json-fields` key is not specified, the [default fields][2] will be configured.
-Field names not in that list will be silently dropped. (This is not ideal, watch [#1507][3] for updates.)
+To customize the logged fields, add a `json-fields` list of strings to your
+config file.  If the `json-fields` key is not specified, the [default fields][4]
+will be configured.
+
+To use a value from [JSONFields][1] or [envoySimpleOperators][2], simply include
+the name of the value in the list of strings. The JSONFields are case-sensitive,
+but envoySimpleOperators are not.
+
+To use [envoyComplexOperators][3] or to use alternative field names, specify strings as
+key/value pairs like `"fieldName=%OPERATOR(...)%"`.
+
+Unknown field names in non key/value fields will result in validation errors, as
+will unknown Envoy operators in key/value fields. Note that the
+`DYNAMIC_METADATA` and `FILTER_STATE` Envoy logging operators are not supported
+at this time due to the complexity of their validation.
 
-The [example config file][4] contains the full list of fields as well.
+See the [example config file][5] to see this used in context.
 
 ## Sample configuration file
 
@@ -41,6 +60,7 @@ json-fields:
   - "authority"
   - "bytes_received"
   - "bytes_sent"
+  - "customer_id=%REQ(X-CUSTOMER-ID)%"
   - "downstream_local_address"
   - "downstream_remote_address"
   - "duration"
@@ -60,7 +80,8 @@ json-fields:
   - "x_forwarded_for"
 ```
 
-[1]: https://godoc.org/github.com/projectcontour/contour/internal/envoy#JSONFields
-[2]: https://godoc.org/github.com/projectcontour/contour/internal/envoy#DefaultFields
-[3]: {{site.github.repository_url}}/issues/1507
-[4]: {{site.github.repository_url}}/blob/{{site.github.latest_release.tag_name}}/examples/contour/01-contour-config.yaml
+[1]: https://github.com/projectcontour/contour/blob/main/pkg/config/accesslog.go#L33-L45
+[2]: https://github.com/projectcontour/contour/blob/main/pkg/config/accesslog.go#L49-L93
+[3]: https://github.com/projectcontour/contour/blob/main/pkg/config/accesslog.go#L97-L102
+[4]: https://github.com/projectcontour/contour/blob/main/pkg/config/accesslog.go#L4
+[5]: {{site.github.repository_url}}/blob/{{site.github.latest_release.tag_name}}/examples/contour/01-contour-config.yaml