Fix #45: Document extra log fields (#105)

mozilla-services · Mar 28, 2024 · 540563a · 540563a
1 parent 4c5ae34
commit 540563a
Show file tree

Hide file tree

Showing 4 changed files with 79 additions and 8 deletions.
diff --git a/docs/django.rst b/docs/django.rst
@@ -414,9 +414,26 @@ In order to include querystrings in the request summary log, set this flag in se
     DOCKERFLOW_SUMMARY_LOG_QUERYSTRING = True
 
 
-A unique request ID is read from the `X-Request-ID` request header, and a UUID4 value is generated if unset.
+MozLog App-Specific Fields
+~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-Leveraging the `RequestIdFilter` in logging configuration as shown above will add a ``rid`` attribute to all log messages.
+The *MozLog* formatter will output ``Fields`` application-specific fields. It can be populated through the ``extra`` parameter:
+
+.. code-block:: python
+
+    logger.info(
+        "Subsystem %s running at %s:%s",
+        name, host, port,
+        extra={"phase": "started", "host": host, "port": port}
+    )
+
+
+Requests Correlation ID
+~~~~~~~~~~~~~~~~~~~~~~~
+
+A unique request ID is read from the ``X-Request-ID`` request header, and a UUID4 value is generated if unset.
+
+Leveraging the ``RequestIdFilter`` in logging configuration as shown above will add a ``rid`` field into the ``Fields`` entry of all log messages.
 
 The header name to obtain the request ID can be customized in settings:
 

diff --git a/docs/fastapi.rst b/docs/fastapi.rst
@@ -326,9 +326,27 @@ In order to include querystrings in the request summary log, set this flag in th
 
     app.state.DOCKERFLOW_SUMMARY_LOG_QUERYSTRING = True
 
-A unique request ID is read from the `X-Request-ID` request header using the `RequestIdMiddleware` middleware (see :ref:`fastapi-setup`), and a UUID4 value is generated if unset.
 
-Leveraging the `RequestIdFilter` in logging configuration as shown above will add a ``rid`` attribute to all log messages.
+MozLog App-Specific Fields
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The *MozLog* formatter will output ``Fields`` application-specific fields. It can be populated through the ``extra`` parameter:
+
+.. code-block:: python
+
+    logger.info(
+        "Subsystem %s running at %s:%s",
+        name, host, port,
+        extra={"phase": "started", "host": host, "port": port}
+    )
+
+
+Requests Correlation ID
+~~~~~~~~~~~~~~~~~~~~~~~
+
+A unique request ID is read from the ``X-Request-ID`` request header, and a UUID4 value is generated if unset.
+
+Leveraging the ``RequestIdFilter`` in logging configuration as shown above will add a ``rid`` field into the ``Fields`` entry of all log messages.
 
 The header name to obtain the request ID can be customized in settings:
 

diff --git a/docs/flask.rst b/docs/flask.rst
@@ -466,9 +466,27 @@ In order to include querystrings in the request summary log, set this flag in :r
 
     DOCKERFLOW_SUMMARY_LOG_QUERYSTRING = True
 
-A unique request ID is read from the `X-Request-ID` request header, and a UUID4 value is generated if unset.
 
-Leveraging the `RequestIdFilter` in logging configuration as shown above will add a ``rid`` attribute to all log messages.
+MozLog App-Specific Fields
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The *MozLog* formatter will output ``Fields`` application-specific fields. It can be populated through the ``extra`` parameter:
+
+.. code-block:: python
+
+    logger.info(
+        "Subsystem %s running at %s:%s",
+        name, host, port,
+        extra={"phase": "started", "host": host, "port": port}
+    )
+
+
+Requests Correlation ID
+~~~~~~~~~~~~~~~~~~~~~~~
+
+A unique request ID is read from the ``X-Request-ID`` request header, and a UUID4 value is generated if unset.
+
+Leveraging the ``RequestIdFilter`` in logging configuration as shown above will add a ``rid`` field into the ``Fields`` entry of all log messages.
 
 The header name to obtain the request ID can be customized in settings:
 

diff --git a/docs/sanic.rst b/docs/sanic.rst
@@ -465,9 +465,27 @@ In order to include querystrings in the request summary log, set this flag in :r
 
     DOCKERFLOW_SUMMARY_LOG_QUERYSTRING = True
 
-A unique request ID is read from the `X-Request-ID` request header, and a UUID4 value is generated if unset.
 
-Leveraging the `RequestIdFilter` in logging configuration as shown above will add a ``rid`` attribute to all log messages.
+MozLog App-Specific Fields
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The *MozLog* formatter will output ``Fields`` application-specific fields. It can be populated through the ``extra`` parameter:
+
+.. code-block:: python
+
+    logger.info(
+        "Subsystem %s running at %s:%s",
+        name, host, port,
+        extra={"phase": "started", "host": host, "port": port}
+    )
+
+
+Requests Correlation ID
+~~~~~~~~~~~~~~~~~~~~~~~
+
+A unique request ID is read from the ``X-Request-ID`` request header, and a UUID4 value is generated if unset.
+
+Leveraging the ``RequestIdFilter`` in logging configuration as shown above will add a ``rid`` field into the ``Fields`` entry of all log messages.
 
 The header name to obtain the request ID can be customized in settings: