docs: Added documentation for Django/Flask integrations and dictConfig (#848)

gkevinzheng · gcf-owl-bot[bot] · web-flow · commit c65ec92bf348 · 2024-02-14T15:27:24.000-05:00
* docs: Added documentation for Django/Flask integrations and dictConfig * 🦉 Updates from OwlBot post-processor See https://github.com/googleapis/repo-automation-bots/blob/main/packages/owl-bot/README.md * Added product prefix to new snippet * Added client setup in sample + link to settings in documentation * Changed django links to point to `/stable/` links --------- Co-authored-by: Owl Bot <gcf-owl-bot[bot]@users.noreply.github.com>
diff --git a/README.rst b/README.rst
@@ -61,8 +61,8 @@ Python >= 3.7
 
 Unsupported Python Versions
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^
-Python == 2.7. The last version of the library compatible with Python 2.7 is `google-cloud-logging==1.15.1`.
-Python == 3.6. The last version of the library compatible with Python 3.6 is `google-cloud-logging==3.1.2`.
+| Python == 2.7. The last version of the library compatible with Python 2.7 is ``google-cloud-logging==1.15.1``.
+| Python == 3.6. The last version of the library compatible with Python 3.6 is ``google-cloud-logging==3.1.2``.
 
 
 Mac/Linux
diff --git a/docs/std-lib-integration.rst b/docs/std-lib-integration.rst
@@ -44,6 +44,16 @@ There are two supported handler classes to choose from:
       to standard out, to be read and parsed by a GCP logging agent
     - This is the default handler on Kubernetes Engine, Cloud Functions and Cloud Run
 
+Handler classes can also be specified via `dictConfig <https://docs.python.org/3/library/logging.config.html#logging-config-dictschema>`_:
+
+.. literalinclude:: ../samples/snippets/usage_guide.py
+    :start-after: [START logging_dict_config]
+    :end-before: [END logging_dict_config]
+    :dedent: 4
+
+Note that since :class:`~google.cloud.logging_v2.handlers.handlers.CloudLoggingHandler` requires an already initialized :class:`~google.cloud.logging_v2.client.Client`,
+you must initialize a client and include it in the dictConfig entry for a `CloudLoggingHandler`.
+
 Standard Library
 ---------------------------
 
@@ -101,8 +111,7 @@ The following fields are currently supported:
 - :ref:`json_fields<JSON>`
 
 .. note::
-    Fields marked with "*" require a supported Python web framework. The Google Cloud Logging
-    library currently supports `flask <https://flask.palletsprojects.com/>`_ and `django <https://www.djangoproject.com/>`_
+    Fields marked with "*" require a :doc:`supported Python web framework </web-framework-integration>`.
 
 Manual Metadata Using the `extra` Argument
 --------------------------------------------
diff --git a/docs/usage.rst b/docs/usage.rst
@@ -4,6 +4,7 @@ Usage Guide
    :maxdepth: 2
 
    std-lib-integration
+   web-framework-integration
    direct-lib-usage
    grpc-vs-http
 
diff --git a/docs/web-framework-integration.rst b/docs/web-framework-integration.rst
@@ -0,0 +1,32 @@
+Integration with Python Web Frameworks
+======================================
+
+The Google Cloud Logging library can integrate with Python web frameworks
+`flask <https://flask.palletsprojects.com/>`_ and `django <https://www.djangoproject.com/>`_ to
+automatically populate `LogEntry fields <https://cloud.google.com/logging/docs/reference/v2/rest/v2/LogEntry>`_ 
+`trace`, `span_id`, `trace_sampled`, and `http_request`.
+
+Django
+------
+
+Django integration has been tested to work with each of the Django/Python versions listed `here <https://docs.djangoproject.com/en/stable/faq/install/#what-python-version-can-i-use-with-django>`_. 
+To enable Django integration, add `google.cloud.logging_v2.handlers.middleware.RequestMiddleware` to the list of `MIDDLEWARE`
+in your `settings <https://docs.djangoproject.com/en/stable/topics/settings/>`_ file. Also be sure to :doc:`set up logging </std-lib-integration>` in your settings file.
+
+Flask
+-----
+
+Flask integration has been tested to work with the following versions of Flask:
+
+===============  ==============
+Python version   Flask versions
+===============  ==============
+3.7              >=1.0.0
+3.8              >=1.0.0
+3.9              >=1.0.0
+3.10             >=1.0.3
+3.11             >=1.0.3
+3.12             >=1.0.3
+===============  ==============
+
+Be sure to :doc:`set up logging </std-lib-integration>` before declaring the Flask app.
diff --git a/google/cloud/logging_v2/handlers/_helpers.py b/google/cloud/logging_v2/handlers/_helpers.py
@@ -66,7 +66,7 @@ def get_request_data_from_flask():
     Returns:
         Tuple[Optional[dict], Optional[str], Optional[str], bool]:
             Data related to the current http request, trace_id, span_id and trace_sampled
-            for the request. All fields will be None if a django request isn't found.
+            for the request. All fields will be None if a Flask request isn't found.
     """
     if flask is None or not flask.request:
         return None, None, None, False
diff --git a/samples/snippets/usage_guide.py b/samples/snippets/usage_guide.py
@@ -484,6 +484,37 @@ def setup_logging(client):
     # [END setup_logging_excludes]
 
 
+@snippet
+def logging_dict_config(client):
+    import logging.config
+
+    # [START logging_dict_config]
+    import google.cloud.logging
+
+    client = google.cloud.logging.Client()
+
+    LOGGING = {
+        "version": 1,
+        "handlers": {
+            "cloud_logging": {
+                "class": "google.cloud.logging.handlers.CloudLoggingHandler",
+                "client": client,
+            },
+            "structured_log": {
+                "class": "google.cloud.logging.handlers.StructuredLogHandler"
+            },
+        },
+        "root": {"handlers": ["console"], "level": "WARNING"},
+        "loggers": {
+            "my_logger": {"handlers": ["cloud_logging"], "level": "INFO"},
+            "my_other_logger": {"handlers": ["structured_log"], "level": "INFO"},
+        },
+    }
+    # [END logging_dict_config]
+
+    logging.config.dictConfig(LOGGING)
+
+
 def _line_no(func):
     return func.__code__.co_firstlineno
 
