From a32c7f537d1fad8374f26ee84c6eed1ac57f5b55 Mon Sep 17 00:00:00 2001
From: Guy Lichtman <1395797+glicht@users.noreply.github.com>
Date: Tue, 10 Apr 2018 01:49:33 +0300
Subject: [PATCH] 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 | 22 ++++++++++++++++++++++
 docs/root/intro/version_history.rst    |  1 +
 2 files changed, 23 insertions(+)

diff --git a/docs/root/configuration/access_log.rst b/docs/root/configuration/access_log.rst
index 96f4d401..a7098011 100644
--- a/docs/root/configuration/access_log.rst
+++ b/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
diff --git a/docs/root/intro/version_history.rst b/docs/root/intro/version_history.rst
index 720d55aa..03c96094 100644
--- a/docs/root/intro/version_history.rst
+++ b/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