You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
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`):
#. 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.
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`):
#. 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.
![gcf-owl-bot[bot]](https://avatars.githubusercontent.com/in/99011?v=4&size=40){kind=avatar}
0 commit comments