From b66a8d92402117c3abaa9ab8e2a2fcba5b3bfbb7 Mon Sep 17 00:00:00 2001 From: ohmayr Date: Mon, 6 Jan 2025 14:17:22 +0000 Subject: [PATCH] chore: add documentation for logging --- gapic/templates/README.rst.j2 | 46 ++++++++++++++++++ tests/integration/goldens/asset/README.rst | 47 +++++++++++++++++++ .../goldens/credentials/README.rst | 47 +++++++++++++++++++ tests/integration/goldens/eventarc/README.rst | 47 +++++++++++++++++++ tests/integration/goldens/redis/README.rst | 47 +++++++++++++++++++ 5 files changed, 234 insertions(+) diff --git a/gapic/templates/README.rst.j2 b/gapic/templates/README.rst.j2 index c443a63406..4c076a4ebb 100644 --- a/gapic/templates/README.rst.j2 +++ b/gapic/templates/README.rst.j2 @@ -48,3 +48,49 @@ Windows \Scripts\activate \Scripts\pip.exe install \path\to\library + +LOGGING +------- + +This library has support to enable logging for debugging and monitoring purposes. Note that logs may contain sensitive information and care should be +taken to restrict access to the logs if they are saved, whether it be on local storage or Google Cloud Logging. + +Users must **explicitly opt-in** to enable logging by configuring the `GOOGLE_SDK_PYTHON_LOGGING_SCOPE` environment variable with a valid logging scope. + +A logging scope is a namespace that begins with :code:`google`. + +- Valid logging scopes: :code:`google`, :code:`google.cloud.asset.v1`, :code:`google.api`, :code:`google.auth`, etc. +- Invalid logging scopes: :code:`foo`, :code:`123`, etc. + +**NOTE**: If an invalid logging scope is configured, we do not act on the corresponding logger. + +To set a handler that applies to all Google-based loggers: + +.. code-block:: console + + export GOOGLE_SDK_PYTHON_LOGGING_SCOPE=google + +To enable a handler for a specific GAPIC: + +.. code-block:: console + + export GOOGLE_SDK_PYTHON_LOGGING_SCOPE=google.cloud.abc.v1 + +:code:`GOOGLE_SDK_PYTHON_LOGGING_SCOPE` allows users to enable or disable logs by configuring a log system; it does not let them configure log levels, handlers, formatters, etc. + +Loggers so configured will handle log messages at level DEBUG or higher, outputting them to stderr. The default log format for these log messages is structured log format. + +Alternatively, users can define and configure a valid logging scope using the standard logging library. + +A typical use case is the following, which defines a handler that applies to all Google-based loggers: + +.. code-block:: python3 + + import logging + + from google.cloud.translate_v3 import translate + + base_logger = logging.getLogger("google") + base_logger.addHandler(logging.StreamHandler()) + base_logger.setLevel(logging.DEBUG) + Client = translate.TranslationServiceClient() diff --git a/tests/integration/goldens/asset/README.rst b/tests/integration/goldens/asset/README.rst index 110d4086ab..424defdbbd 100755 --- a/tests/integration/goldens/asset/README.rst +++ b/tests/integration/goldens/asset/README.rst @@ -47,3 +47,50 @@ Windows python3 -m venv \Scripts\activate \Scripts\pip.exe install \path\to\library + + +LOGGING +------- + +This library has support to enable logging for debugging and monitoring purposes. Note that logs may contain sensitive information and care should be +taken to restrict access to the logs if they are saved, whether it be on local storage or Google Cloud Logging. + +Users must **explicitly opt-in** to enable logging by configuring the `GOOGLE_SDK_PYTHON_LOGGING_SCOPE` environment variable with a valid logging scope. + +A logging scope is a namespace that begins with :code:`google`. + +- Valid logging scopes: :code:`google`, :code:`google.cloud.asset.v1`, :code:`google.api`, :code:`google.auth`, etc. +- Invalid logging scopes: :code:`foo`, :code:`123`, etc. + +**NOTE**: If an invalid logging scope is configured, we do not act on the corresponding logger. + +To set a handler that applies to all Google-based loggers: + +.. code-block:: console + + export GOOGLE_SDK_PYTHON_LOGGING_SCOPE=google + +To enable a handler for a specific GAPIC: + +.. code-block:: console + + export GOOGLE_SDK_PYTHON_LOGGING_SCOPE=google.cloud.abc.v1 + +:code:`GOOGLE_SDK_PYTHON_LOGGING_SCOPE` allows users to enable or disable logs by configuring a log system; it does not let them configure log levels, handlers, formatters, etc. + +Loggers so configured will handle log messages at level DEBUG or higher, outputting them to stderr. The default log format for these log messages is structured log format. + +Alternatively, users can define and configure a valid logging scope using the standard logging library. + +A typical use case is the following, which defines a handler that applies to all Google-based loggers: + +.. code-block:: python3 + + import logging + + from google.cloud.translate_v3 import translate + + base_logger = logging.getLogger("google") + base_logger.addHandler(logging.StreamHandler()) + base_logger.setLevel(logging.DEBUG) + Client = translate.TranslationServiceClient() diff --git a/tests/integration/goldens/credentials/README.rst b/tests/integration/goldens/credentials/README.rst index b4de941450..2cf8f55afb 100755 --- a/tests/integration/goldens/credentials/README.rst +++ b/tests/integration/goldens/credentials/README.rst @@ -47,3 +47,50 @@ Windows python3 -m venv \Scripts\activate \Scripts\pip.exe install \path\to\library + + +LOGGING +------- + +This library has support to enable logging for debugging and monitoring purposes. Note that logs may contain sensitive information and care should be +taken to restrict access to the logs if they are saved, whether it be on local storage or Google Cloud Logging. + +Users must **explicitly opt-in** to enable logging by configuring the `GOOGLE_SDK_PYTHON_LOGGING_SCOPE` environment variable with a valid logging scope. + +A logging scope is a namespace that begins with :code:`google`. + +- Valid logging scopes: :code:`google`, :code:`google.cloud.asset.v1`, :code:`google.api`, :code:`google.auth`, etc. +- Invalid logging scopes: :code:`foo`, :code:`123`, etc. + +**NOTE**: If an invalid logging scope is configured, we do not act on the corresponding logger. + +To set a handler that applies to all Google-based loggers: + +.. code-block:: console + + export GOOGLE_SDK_PYTHON_LOGGING_SCOPE=google + +To enable a handler for a specific GAPIC: + +.. code-block:: console + + export GOOGLE_SDK_PYTHON_LOGGING_SCOPE=google.cloud.abc.v1 + +:code:`GOOGLE_SDK_PYTHON_LOGGING_SCOPE` allows users to enable or disable logs by configuring a log system; it does not let them configure log levels, handlers, formatters, etc. + +Loggers so configured will handle log messages at level DEBUG or higher, outputting them to stderr. The default log format for these log messages is structured log format. + +Alternatively, users can define and configure a valid logging scope using the standard logging library. + +A typical use case is the following, which defines a handler that applies to all Google-based loggers: + +.. code-block:: python3 + + import logging + + from google.cloud.translate_v3 import translate + + base_logger = logging.getLogger("google") + base_logger.addHandler(logging.StreamHandler()) + base_logger.setLevel(logging.DEBUG) + Client = translate.TranslationServiceClient() diff --git a/tests/integration/goldens/eventarc/README.rst b/tests/integration/goldens/eventarc/README.rst index 4c79a1d0f7..83db914880 100755 --- a/tests/integration/goldens/eventarc/README.rst +++ b/tests/integration/goldens/eventarc/README.rst @@ -47,3 +47,50 @@ Windows python3 -m venv \Scripts\activate \Scripts\pip.exe install \path\to\library + + +LOGGING +------- + +This library has support to enable logging for debugging and monitoring purposes. Note that logs may contain sensitive information and care should be +taken to restrict access to the logs if they are saved, whether it be on local storage or Google Cloud Logging. + +Users must **explicitly opt-in** to enable logging by configuring the `GOOGLE_SDK_PYTHON_LOGGING_SCOPE` environment variable with a valid logging scope. + +A logging scope is a namespace that begins with :code:`google`. + +- Valid logging scopes: :code:`google`, :code:`google.cloud.asset.v1`, :code:`google.api`, :code:`google.auth`, etc. +- Invalid logging scopes: :code:`foo`, :code:`123`, etc. + +**NOTE**: If an invalid logging scope is configured, we do not act on the corresponding logger. + +To set a handler that applies to all Google-based loggers: + +.. code-block:: console + + export GOOGLE_SDK_PYTHON_LOGGING_SCOPE=google + +To enable a handler for a specific GAPIC: + +.. code-block:: console + + export GOOGLE_SDK_PYTHON_LOGGING_SCOPE=google.cloud.abc.v1 + +:code:`GOOGLE_SDK_PYTHON_LOGGING_SCOPE` allows users to enable or disable logs by configuring a log system; it does not let them configure log levels, handlers, formatters, etc. + +Loggers so configured will handle log messages at level DEBUG or higher, outputting them to stderr. The default log format for these log messages is structured log format. + +Alternatively, users can define and configure a valid logging scope using the standard logging library. + +A typical use case is the following, which defines a handler that applies to all Google-based loggers: + +.. code-block:: python3 + + import logging + + from google.cloud.translate_v3 import translate + + base_logger = logging.getLogger("google") + base_logger.addHandler(logging.StreamHandler()) + base_logger.setLevel(logging.DEBUG) + Client = translate.TranslationServiceClient() diff --git a/tests/integration/goldens/redis/README.rst b/tests/integration/goldens/redis/README.rst index 45c06d80c6..fbd4f04c3c 100755 --- a/tests/integration/goldens/redis/README.rst +++ b/tests/integration/goldens/redis/README.rst @@ -47,3 +47,50 @@ Windows python3 -m venv \Scripts\activate \Scripts\pip.exe install \path\to\library + + +LOGGING +------- + +This library has support to enable logging for debugging and monitoring purposes. Note that logs may contain sensitive information and care should be +taken to restrict access to the logs if they are saved, whether it be on local storage or Google Cloud Logging. + +Users must **explicitly opt-in** to enable logging by configuring the `GOOGLE_SDK_PYTHON_LOGGING_SCOPE` environment variable with a valid logging scope. + +A logging scope is a namespace that begins with :code:`google`. + +- Valid logging scopes: :code:`google`, :code:`google.cloud.asset.v1`, :code:`google.api`, :code:`google.auth`, etc. +- Invalid logging scopes: :code:`foo`, :code:`123`, etc. + +**NOTE**: If an invalid logging scope is configured, we do not act on the corresponding logger. + +To set a handler that applies to all Google-based loggers: + +.. code-block:: console + + export GOOGLE_SDK_PYTHON_LOGGING_SCOPE=google + +To enable a handler for a specific GAPIC: + +.. code-block:: console + + export GOOGLE_SDK_PYTHON_LOGGING_SCOPE=google.cloud.abc.v1 + +:code:`GOOGLE_SDK_PYTHON_LOGGING_SCOPE` allows users to enable or disable logs by configuring a log system; it does not let them configure log levels, handlers, formatters, etc. + +Loggers so configured will handle log messages at level DEBUG or higher, outputting them to stderr. The default log format for these log messages is structured log format. + +Alternatively, users can define and configure a valid logging scope using the standard logging library. + +A typical use case is the following, which defines a handler that applies to all Google-based loggers: + +.. code-block:: python3 + + import logging + + from google.cloud.translate_v3 import translate + + base_logger = logging.getLogger("google") + base_logger.addHandler(logging.StreamHandler()) + base_logger.setLevel(logging.DEBUG) + Client = translate.TranslationServiceClient()