chore: add documentation for logging

[ohmayr]

Fixes b/384047953

[parthea]

Added minor observations, otherwise LGTM.

[parthea]

Suggested change

	Users must **explicitly opt-in** to enable logging by configuring the `GOOGLE_SDK_PYTHON_LOGGING_SCOPE` environment variable with a valid logging scope.
	By default this feature is not enabled. Users may opt-in to enable logging by configuring the `GOOGLE_SDK_PYTHON_LOGGING_SCOPE` environment variable with a valid logging scope.

[parthea]

Suggested change

	**NOTE**: If an invalid logging scope is configured, we do not act on the corresponding logger.
	**NOTE**: If an invalid logging scope is configured, debug logging will remain disabled.

[vchudnov-g]

• we shouldn't call this "debug logging" externally (see internal doc comment, for example)
• "will remain disabled" is misleading, because the user could set up handlers a different way

I tried to clear this up in the suggested text.

[parthea]

Suggested change

	To enable a handler for a specific GAPIC:
	To enable a handler for a specific module:

[parthea]

Suggested change

	export GOOGLE_SDK_PYTHON_LOGGING_SCOPE=google.cloud.abc.v1
	export GOOGLE_SDK_PYTHON_LOGGING_SCOPE=google.cloud.abc_v1

[parthea]

Suggested change

	: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.
	:code:`GOOGLE_SDK_PYTHON_LOGGING_SCOPE` allows users to enable or disable logs by configuring a log system; however it is not currently possible to customize log levels, handlers, formatters, etc.

[parthea]

Suggested change

	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.
	Configured loggers 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.

[parthea]

Would it be helpful to provide a one line sample of the log output so that users can see what debug logs will look like when logging is configured?

[vchudnov-g]

I'm not sure how much value that adds. Plus, since we're giving ourselves the leeway to change the log messages, this could easily become stale, depending on how much information we provide here.

[vchudnov-g]

I found it easier to make changes separately, and this is the text I suggest. WDYT?

Some notes:

1. If you prefer to discuss the text in a Google Doc first, I can easily export it to one and we can discuss the content there.
2. It would be great to not use a generic example library in this file (in the content below, google.cloud.library_v1) but rather the actual name of the library we're generating. This should be simple because we're in a template, but if it's not, let's file a follow-up issue to get back to this.

(sorry I couldn't do this directly in RST. Once we agree on the content, I should be able to export to RST with minimal set-up on my part, if that's helpful.)

SUGGESTED CONTENT FOLLOWS

---

Logging

This library uses the standard Python logging functionality to log some RPC events that could be of interest for debugging and monitoring purposes. Note the following:

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.
2. 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.
3. By default, the logging events from this library are not handled. You must explicitly configure log handling using one of the mechanisms below.

Simple, environment-based configuration

To enable logging for this library without any changes in your code, set the GOOGLE_SDK_PYTHON_LOGGING_SCOPE environment variable to a valid Google logging scope. This configures handling of logging events (at level 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 google, identifying the Python module or package to log.

• Valid logging scopes: google, google.cloud.asset.v1, google.api, google.auth, etc.
• Invalid logging scopes: foo, 123, etc.

NOTE: If the logging scope is invalid, the library does not set up any logging handlers.

Examples

• Enabling the default handler for all Google-based loggers

  export GOOGLE_SDK_PYTHON_LOGGING_SCOPE=google
  

• Enabling the default handler for a specific Google module

  In the case of a client library called Library:

  export GOOGLE_SDK_PYTHON_LOGGING_SCOPE=google.cloud.library_v1
  

Advanced, code-based configuration

You can also configure a valid logging scope using Python's standard logging mechanism.

Examples

• Configuring a handler for all Google-based loggers

  import logging
  
  from google.cloud.translate_v3 import translate
  
  base_logger = logging.getLogger("google")
  base_logger.addHandler(logging.StreamHandler())
  base_logger.setLevel(logging.DEBUG)
  

• Configuring a handler for a specific Google module

  In the case of a client library called Library:

  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.
3. 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.)

[vchudnov-g]

I'm not sure it's clear or accurate to say we support "enabling" logging. We log, in the sense we emit logging events. Users can set up handlers for those events, either explicitly via code or with the help of our environment-based config, which we describe below. I tried to clear this up in the suggested text.

[vchudnov-g]

If it's not trivial to use the info for the library being generated rather than the generic "library" API, could you file an issue to follow up on that? Thanks! (This was suggestion 2 in my previous comment)

[vchudnov-g]

This nested 1 does not render correctly (at least according to the GitHub preview if you click on the page icon, the second from the left, in the set of icons for this file shown right above this diff, on the right).

We need to specify it's a sub-bullet.

[ohmayr]

If it's not trivial to use the info for the library being generated rather than the generic "library" API, could you file an issue to follow up on that? Thanks! (This was suggestion 2 in my previous comment)

Filed #2314

[vchudnov-g]

Just one minor change for consistency.

Thanks so much for doing this, Omair! It looks great!