address PR feedback

gapic/templates/README.rst.j2

@@ -52,45 +52,91 @@ Windows
 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.
+This library uses the standard Python :code:`logging` functionality to log some RPC events that could be of interest for debugging and monitoring purposes.
+Note the following:
 
-Users must **explicitly opt-in** to enable logging by configuring the `GOOGLE_SDK_PYTHON_LOGGING_SCOPE` environment variable with a valid logging scope.
+1.  Logs may contain sensitive information. Take care to **restrict access to the logs** if they are saved, whether it be on local storage or Google Cloud Logging.
+4.  Google may refine the occurrence, level, and content of various log messages in this library without flagging such changes as breaking. **Do not depend on immutability
+    of the logging events**.
+5.  By default, the logging events from this library are not handled. You must **explicitly configure log handling** using one of the mechanisms below.
 
-A logging scope is a namespace that begins with :code:`google`.
+
+Simple, environment-based configuration
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+To enable logging for this library without any changes in your code, set the :code:`GOOGLE_SDK_PYTHON_LOGGING_SCOPE` environment variable to a valid Google
+logging scope. This configures handling of logging events (at level :code:`logging.DEBUG` or higher) from this library in a default manner, emitting the logged
+messages in a structured format. It does not currently allow customizing the logging levels captured nor the handlers, formatters, etc. used for any logging
+event.
+
+A logging scope is a period-separated namespace that begins with :code:`google`, identifying the Python module or package to log.
 
 - 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.
+**NOTE**: If the logging scope is invalid, the library does not set up any logging handlers.
 
-To set a handler that applies to all Google-based loggers:
+
+Examples
+^^^^^^^^
+
+- Enabling the default handler for all Google-based loggers
 
 .. code-block:: console
 
     export GOOGLE_SDK_PYTHON_LOGGING_SCOPE=google
 
-To enable a handler for a specific GAPIC:
+- Enabling the default handler for a specific Google module (In the case of a client library called :code:`Library`):
 
 .. code-block:: console
 
-    export GOOGLE_SDK_PYTHON_LOGGING_SCOPE=google.cloud.abc.v1
+    export GOOGLE_SDK_PYTHON_LOGGING_SCOPE=google.cloud.library_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.
+Advanced, code-based configuration
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-Alternatively, users can define and configure a valid logging scope using the standard logging library.
+You can also configure a valid logging scope using Python's standard `logging` mechanism.
 
-A typical use case is the following, which defines a handler that applies to all Google-based loggers:
 
-.. code-block:: python3
+Examples
+^^^^^^^^
 
-    import logging
+- Configuring a handler for all Google-based loggers
 
-    from google.cloud.translate_v3 import translate
+.. code-block:: console
 
+    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()
+
+- Configuring a handler for a specific Google module (In the case of a client library called :code:`Library`):
+
+.. code-block:: console
+
+    import logging
+
+    from google.cloud.translate_v3 import translate
+
+    base_logger = logging.getLogger("google.cloud.library_v1")
+    base_logger.addHandler(logging.StreamHandler())
+    base_logger.setLevel(logging.DEBUG)
+
+
+Logging details
+~~~~~~~~~~~~~~~
+
+1.  Regardless of which of the mechanisms above you use to configure logging for this library, by default logging events are not propagated up to the root
+    logger from the `google`-level logger. If you need the events to be propagated to the root logger, you must explicitly set
+    `logging.getLogger("google").propagate = True` in your code.
+2.  You can mix the different logging configurations above for different Google modules. For example, you may want use a code-based logging configuration for
+    one library, but decide you need to also set up environment-based logging configuration for another library.
+    1.  If you attempt to use both code-based and environment-based configuration for the same module, the environment-based configuration will be ineffectual
+    if the code -based configuration gets applied first.
+4.  The Google-specific logging configurations (default handlers for environment-based configuration; not propagating logging events to the root logger) get
+    executed the first time *any* client library is instantiated in your application, and only if the affected loggers have not been previously configured.
+    (This is the reason for 2.1 above.)

tests/integration/goldens/asset/README.rst

@@ -52,39 +52,59 @@ Windows
 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.
+This library uses the standard Python :code:`logging` functionality to log some RPC events that could be of interest for debugging and monitoring purposes.
+Note the following:
 
-Users must **explicitly opt-in** to enable logging by configuring the `GOOGLE_SDK_PYTHON_LOGGING_SCOPE` environment variable with a valid logging scope.
+1.  Logs may contain sensitive information. Take care to **restrict access to the logs** if they are saved, whether it be on local storage or Google Cloud Logging.
+4.  Google may refine the occurrence, level, and content of various log messages in this library without flagging such changes as breaking. **Do not depend on immutability
+    of the logging events**.
+5.  By default, the logging events from this library are not handled. You must **explicitly configure log handling** using one of the mechanisms below.
 
-A logging scope is a namespace that begins with :code:`google`.
+
+Simple, environment-based configuration
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+To enable logging for this library without any changes in your code, set the :code:`GOOGLE_SDK_PYTHON_LOGGING_SCOPE` environment variable to a valid Google
+logging scope. This configures handling of logging events (at level :code:`logging.DEBUG` or higher) from this library in a default manner, emitting the logged
+messages in a structured format. It does not currently allow customizing the logging levels captured nor the handlers, formatters, etc. used for any logging
+event.
+
+A logging scope is a period-separated namespace that begins with :code:`google`, identifying the Python module or package to log.
 
 - 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.
+**NOTE**: If the logging scope is invalid, the library does not set up any logging handlers.
 
-To set a handler that applies to all Google-based loggers:
+
+Examples
+^^^^^^^^
+
+- Enabling the default handler for all Google-based loggers
 
 .. code-block:: console
 
     export GOOGLE_SDK_PYTHON_LOGGING_SCOPE=google
 
-To enable a handler for a specific GAPIC:
+- Enabling the default handler for a specific Google module (In the case of a client library called :code:`Library`):
 
 .. code-block:: console
 
-    export GOOGLE_SDK_PYTHON_LOGGING_SCOPE=google.cloud.abc.v1
+    export GOOGLE_SDK_PYTHON_LOGGING_SCOPE=google.cloud.library_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.
+Advanced, code-based configuration
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-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.
+You can also configure a valid logging scope using Python's standard `logging` mechanism.
 
-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:
+Examples
+^^^^^^^^
 
-.. code-block:: python3
+- Configuring a handler for all Google-based loggers
+
+.. code-block:: console
 
     import logging
 
@@ -93,4 +113,30 @@ A typical use case is the following, which defines a handler that applies to all
     base_logger = logging.getLogger("google")
     base_logger.addHandler(logging.StreamHandler())
     base_logger.setLevel(logging.DEBUG)
-    Client = translate.TranslationServiceClient()
+
+- Configuring a handler for a specific Google module (In the case of a client library called :code:`Library`):
+
+.. code-block:: console
+
+    import logging
+
+    from google.cloud.translate_v3 import translate
+
+    base_logger = logging.getLogger("google.cloud.library_v1")
+    base_logger.addHandler(logging.StreamHandler())
+    base_logger.setLevel(logging.DEBUG)
+
+
+Logging details
+~~~~~~~~~~~~~~~
+
+1.  Regardless of which of the mechanisms above you use to configure logging for this library, by default logging events are not propagated up to the root
+    logger from the `google`-level logger. If you need the events to be propagated to the root logger, you must explicitly set
+    `logging.getLogger("google").propagate = True` in your code.
+2.  You can mix the different logging configurations above for different Google modules. For example, you may want use a code-based logging configuration for
+    one library, but decide you need to also set up environment-based logging configuration for another library.
+    1.  If you attempt to use both code-based and environment-based configuration for the same module, the environment-based configuration will be ineffectual
+    if the code -based configuration gets applied first.
+4.  The Google-specific logging configurations (default handlers for environment-based configuration; not propagating logging events to the root logger) get
+    executed the first time *any* client library is instantiated in your application, and only if the affected loggers have not been previously configured.
+    (This is the reason for 2.1 above.)

tests/integration/goldens/credentials/README.rst

@@ -52,39 +52,59 @@ Windows
 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.
+This library uses the standard Python :code:`logging` functionality to log some RPC events that could be of interest for debugging and monitoring purposes.
+Note the following:
 
-Users must **explicitly opt-in** to enable logging by configuring the `GOOGLE_SDK_PYTHON_LOGGING_SCOPE` environment variable with a valid logging scope.
+1.  Logs may contain sensitive information. Take care to **restrict access to the logs** if they are saved, whether it be on local storage or Google Cloud Logging.
+4.  Google may refine the occurrence, level, and content of various log messages in this library without flagging such changes as breaking. **Do not depend on immutability
+    of the logging events**.
+5.  By default, the logging events from this library are not handled. You must **explicitly configure log handling** using one of the mechanisms below.
 
-A logging scope is a namespace that begins with :code:`google`.
+
+Simple, environment-based configuration
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+To enable logging for this library without any changes in your code, set the :code:`GOOGLE_SDK_PYTHON_LOGGING_SCOPE` environment variable to a valid Google
+logging scope. This configures handling of logging events (at level :code:`logging.DEBUG` or higher) from this library in a default manner, emitting the logged
+messages in a structured format. It does not currently allow customizing the logging levels captured nor the handlers, formatters, etc. used for any logging
+event.
+
+A logging scope is a period-separated namespace that begins with :code:`google`, identifying the Python module or package to log.
 
 - 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.
+**NOTE**: If the logging scope is invalid, the library does not set up any logging handlers.
 
-To set a handler that applies to all Google-based loggers:
+
+Examples
+^^^^^^^^
+
+- Enabling the default handler for all Google-based loggers
 
 .. code-block:: console
 
     export GOOGLE_SDK_PYTHON_LOGGING_SCOPE=google
 
-To enable a handler for a specific GAPIC:
+- Enabling the default handler for a specific Google module (In the case of a client library called :code:`Library`):
 
 .. code-block:: console
 
-    export GOOGLE_SDK_PYTHON_LOGGING_SCOPE=google.cloud.abc.v1
+    export GOOGLE_SDK_PYTHON_LOGGING_SCOPE=google.cloud.library_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.
+Advanced, code-based configuration
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-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.
+You can also configure a valid logging scope using Python's standard `logging` mechanism.
 
-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:
+Examples
+^^^^^^^^
 
-.. code-block:: python3
+- Configuring a handler for all Google-based loggers
+
+.. code-block:: console
 
     import logging
 
@@ -93,4 +113,30 @@ A typical use case is the following, which defines a handler that applies to all
     base_logger = logging.getLogger("google")
     base_logger.addHandler(logging.StreamHandler())
     base_logger.setLevel(logging.DEBUG)
-    Client = translate.TranslationServiceClient()
+
+- Configuring a handler for a specific Google module (In the case of a client library called :code:`Library`):
+
+.. code-block:: console
+
+    import logging
+
+    from google.cloud.translate_v3 import translate
+
+    base_logger = logging.getLogger("google.cloud.library_v1")
+    base_logger.addHandler(logging.StreamHandler())
+    base_logger.setLevel(logging.DEBUG)
+
+
+Logging details
+~~~~~~~~~~~~~~~
+
+1.  Regardless of which of the mechanisms above you use to configure logging for this library, by default logging events are not propagated up to the root
+    logger from the `google`-level logger. If you need the events to be propagated to the root logger, you must explicitly set
+    `logging.getLogger("google").propagate = True` in your code.
+2.  You can mix the different logging configurations above for different Google modules. For example, you may want use a code-based logging configuration for
+    one library, but decide you need to also set up environment-based logging configuration for another library.
+    1.  If you attempt to use both code-based and environment-based configuration for the same module, the environment-based configuration will be ineffectual
+    if the code -based configuration gets applied first.
+4.  The Google-specific logging configurations (default handlers for environment-based configuration; not propagating logging events to the root logger) get
+    executed the first time *any* client library is instantiated in your application, and only if the affected loggers have not been previously configured.
+    (This is the reason for 2.1 above.)