10000 chore: add logging section to readme (#313) · googleapis/python-runtimeconfig@18d0cd2 · GitHub
[go: up one dir, main page]
Skip to content

Commit 18d0cd2

Browse files
gcf-owl-bot[bot]vchudnov-g
gcf-owl-bot[bot]
and
vchudnov-g
authored
chore: add logging section to readme (#313)
Source-Link: googleapis/synthtool@d1011bc Post-Processor: gcr.io/cloud-devrel-public-resources/owlbot-python:latest@sha256:fdc038572b896f739f95cc90e62f16c06e4f2ef0ef3bea343a358331862ad0f0 Co-authored-by: Owl Bot <gcf-owl-bot[bot]@users.noreply.github.com> Co-authored-by: Victor Chudnovsky <vchudnov@google.com>
1 parent 5849cea commit 18d0cd2

File tree

2 files changed

+91
-2
lines changed

2 files changed

+91
-2
lines changed

‎.github/.OwlBot.lock.yaml

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -13,5 +13,5 @@
1313
# limitations under the License.
1414
docker:
1515
image: gcr.io/cloud-devrel-public-resources/owlbot-python:latest
16-
digest: sha256:631b4a35a4f9dd5e97740a97c4c117646eb85b35e103844dc49d152bd18694cd
17-
# created: 2025-02-05T14:40:56.685429494Z
16+
digest: sha256:fdc038572b896f739f95cc90e62f16c06e4f2ef0ef3bea343a358331862ad0f0
17+
# created: 2025-02-13T21:06:55.521673457Z

‎README.rst

Lines changed: 89 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -106,3 +106,92 @@ Next Steps
106106

107107
.. _Google Cloud Runtime Configurator API Product documentation: https://cloud.google.com/deployment-manager/runtime-configurator/
108108
.. _README: https://github.com/googleapis/google-cloud-python/blob/main/README.rst
109+
110+
Logging
111+
-------
112+
113+
This library uses the standard Python :code:`logging` functionality to log some RPC events that could be of interest for debugging and monitoring purposes.
114+
Note the following:
115+
116+
#. Logs may contain sensitive information. Take care to **restrict access to the logs** if they are saved, whether it be on local storage or on Google Cloud Logging.
117+
#. 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**.
118+
#. By default, the logging events from this library are not handled. You must **explicitly configure log handling** using one of the mechanisms below.
119+
120+
Simple, environment-based configuration
121+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
122+
123+
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
124+
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
125+
messages in a structured format. It does not currently allow customizing the logging levels captured nor the handlers, formatters, etc. used for any logging
126+
event.
127+
128+
A logging scope is a period-separated namespace that begins with :code:`google`, identifying the Python module or package to log.
129+
130+
- Valid logging scopes: :code:`google`, :code:`google.cloud.asset.v1`, :code:`google.api`, :code:`google.auth`, etc.
131+
- Invalid logging scopes: :code:`foo`, :code:`123`, etc.
132+
133+
**NOTE**: If the logging scope is invalid, the library does not set up any logging handlers.
134+
135+
Environment-Based Examples
136+
^^^^^^^^^^^^^^^^^^^^^^^^^^
137+
138+
- Enabling the default handler for all Google-based loggers
139+
140+
.. code-block:: console
141+
142+
export GOOGLE_SDK_PYTHON_LOGGING_SCOPE=google
143+
144+
- Enabling the default handler for a specific Google module (for a client library called :code:`library_v1`):
145+
146+
.. code-block:: console
147+
148+
export GOOGLE_SDK_PYTHON_LOGGING_SCOPE=google.cloud.library_v1
149+
150+
151+
Advanced, code-based configuration
152+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
153+
154+
You can also configure a valid logging scope using Python's standard `logging` mechanism.
155+
156+
Code-Based Examples
157+
^^^^^^^^^^^^^^^^^^^
158+
159+
- Configuring a handler for all Google-based loggers
160+
161+
.. code-block:: python
162+
163+
import logging
164+
165+
from google.cloud.translate_v3 import translate
166+
167+
base_logger = logging.getLogger("google")
168+
base_logger.addHandler(logging.StreamHandler())
169+
base_logger.setLevel(logging.DEBUG)
170+
171+
- Configuring a handler for a specific Google module (for a client library called :code:`library_v1`):
172+
173+
.. code-block:: python
174+
175+
import logging
176+
177+
from google.cloud.translate_v3 import translate
178+
179+
base_logger = logging.getLogger("google.cloud.library_v1")
180+
base_logger.addHandler(logging.StreamHandler())
181+
base_logger.setLevel(logging.DEBUG)
182+
183+
Logging details
184+
~~~~~~~~~~~~~~~
185+
186+
#. 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
187+
logger from the `google`-level logger. If you need the events to be propagated to the root logger, you must explicitly set
188+
:code:`logging.getLogger("google").propagate = True` in your code.
189+
#. You can mix the different logging configurations above for different Google modules. For example, you may want use a code-based logging configuration for
190+
one library, but decide you need to also set up environment-based logging configuration for another library.
191+
192+
#. If you attempt to use both code-based and environment-based configuration for the same module, the environment-based configuration will be ineffectual
193+
if the code -based configuration gets applied first.
194+
195+
#. The Google-specific logging configurations (default handlers for environment-based configuration; not propagating logging events to the root logger) get
196+
executed the first time *any* client library is instantiated in your application, and only if the affected loggers have not been previously configured.
197+
(This is the reason for 2.i. above.)

0 commit comments

Comments
 (0)
0