diff --git a/README.rst b/README.rst index 2618dc37a..84dd1e77f 100644 --- 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 index a485fce6d..be43231fd 100644 --- 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 `_: + +.. 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` .. note:: - Fields marked with "*" require a supported Python web framework. The Google Cloud Logging - library currently supports `flask `_ and `django `_ + Fields marked with "*" require a :doc:`supported Python web framework `. Manual Metadata Using the `extra` Argument -------------------------------------------- diff --git a/docs/usage.rst b/docs/usage.rst index 929ee9cef..7541f355b 100644 --- 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 new file mode 100644 index 000000000..d91d714b3 --- /dev/null +++ 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 `_ and `django `_ to +automatically populate `LogEntry fields `_ +`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 `_. +To enable Django integration, add `google.cloud.logging_v2.handlers.middleware.RequestMiddleware` to the list of `MIDDLEWARE` +in your `settings `_ file. Also be sure to :doc:`set up logging ` 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 ` before declaring the Flask app. diff --git a/google/cloud/logging_v2/handlers/_helpers.py b/google/cloud/logging_v2/handlers/_helpers.py index 43678ed0d..f0c301ceb 100644 --- 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 index 5c9e86990..f4292a9de 100644 --- 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