access_log: support for dynamic metadata set as part of the request info (#590)

documentation for PR: envoyproxy/envoy#2895

Signed-off-by: Guy Lichtman <guy@lichtman.io>

docs/root/configuration/access_log.rst

@@ -164,6 +164,28 @@ The following command operators are supported:
   TCP
     Not implemented ("-").
 
+%DYNAMIC_METADATA(NAMESPACE:KEY*):Z%
+  HTTP
+    :ref:`Dynamic Metadata <envoy_api_msg_core.Metadata>` info,
+    where NAMESPACE is the the filter namespace used when setting the metadata, KEY is an optional
+    lookup up key in the namespace with the option of specifying nested keys separated by ':',
+    and Z is an optional parameter denoting string truncation up to Z characters long. Dynamic Metadata
+    can be set by filters using the :repo:`RequestInfo <include/envoy/request_info/request_info.h>` API:
+    *setDynamicMetadata*. The data will be logged as a JSON string. For example, for the following dynamic metadata:
+
+    ``com.test.my_filter: {"test_key": "foo", "test_object": {"inner_key": "bar"}}``
+
+    * %DYNAMIC_METADATA(com.test.my_filter)% will log: ``{"test_key": "foo", "test_object": {"inner_key": "bar"}}``
+    * %DYNAMIC_METADATA(com.test.my_filter:test_key)% will log: ``"foo"``
+    * %DYNAMIC_METADATA(com.test.my_filter:test_object)% will log: ``{"inner_key": "bar"}``
+    * %DYNAMIC_METADATA(com.test.my_filter:test_object:inner_key)% will log: ``"bar"``
+    * %DYNAMIC_METADATA(com.unknown_filter)% will log: ``-``
+    * %DYNAMIC_METADATA(com.test.my_filter:unknown_key)% will log: ``-``
+    * %DYNAMIC_METADATA(com.test.my_filter):25% will log (truncation at 25 characters): ``{"test_key": "foo", "test``
+
+  TCP
+    Not implemented ("-").
+
 .. _config_access_log_default_format:
 
 Default format

docs/root/intro/version_history.rst

@@ -5,6 +5,7 @@ Version history
 ===============
 
 * access log: ability to format START_TIME
+* access log: added DYNAMIC_METADATA :ref:`access log formatter <config_access_log_format>`.
 * admin: added :http:get:`/config_dump` for dumping current configs
 * admin: added :http:get:`/stats/prometheus` as an alternative endpoint for getting stats in prometheus format.
 * admin: added :ref:`/runtime_modify endpoint <operations_admin_interface_runtime_modify>` to add or change runtime values