Skip to content

Commit b66a8d9

Browse files
ohmayrohmayr
committed
chore: add documentation for logging
1 parent 558e2e2 commit b66a8d9

File tree

5 files changed

+234
-0
lines changed

5 files changed

+234
-0
lines changed

‎gapic/templates/README.rst.j2‎

Lines changed: 46 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -48,3 +48,49 @@ Windows
4848
<your-env>\Scripts\activate
4949
<your-env>\Scripts\pip.exe install \path\to\library
5050

51+
52+
LOGGING
53+
-------
54+
55+
This library has support to enable logging for debugging and monitoring purposes. Note that logs may contain sensitive information and care should be
56+
taken to restrict access to the logs if they are saved, whether it be on local storage or Google Cloud Logging.
57+
58+
Users must **explicitly opt-in** to enable logging by configuring the `GOOGLE_SDK_PYTHON_LOGGING_SCOPE` environment variable with a valid logging scope.
59+
60+
A logging scope is a namespace that begins with :code:`google`.
61+
62+
- Valid logging scopes: :code:`google`, :code:`google.cloud.asset.v1`, :code:`google.api`, :code:`google.auth`, etc.
63+
- Invalid logging scopes: :code:`foo`, :code:`123`, etc.
64+
65+
**NOTE**: If an invalid logging scope is configured, we do not act on the corresponding logger.
66+
67+
To set a handler that applies to all Google-based loggers:
68+
69+
.. code-block:: console
70+
71+
export GOOGLE_SDK_PYTHON_LOGGING_SCOPE=google
72+
73+
To enable a handler for a specific GAPIC:
74+
75+
.. code-block:: console
76+
77+
export GOOGLE_SDK_PYTHON_LOGGING_SCOPE=google.cloud.abc.v1
78+
79+
: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.
80+
81+
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.
82+
83+
Alternatively, users can define and configure a valid logging scope using the standard logging library.
84+
85+
A typical use case is the following, which defines a handler that applies to all Google-based loggers:
86+
87+
.. code-block:: python3
88+
89+
import logging
90+
91+
from google.cloud.translate_v3 import translate
92+
93+
base_logger = logging.getLogger("google")
94+
base_logger.addHandler(logging.StreamHandler())
95+
base_logger.setLevel(logging.DEBUG)
96+
Client = translate.TranslationServiceClient()

‎tests/integration/goldens/asset/README.rst‎

Lines changed: 47 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -47,3 +47,50 @@ Windows
4747
python3 -m venv <your-env>
4848
<your-env>\Scripts\activate
4949
<your-env>\Scripts\pip.exe install \path\to\library
50+
51+
52+
LOGGING
53+
-------
54+
55+
This library has support to enable logging for debugging and monitoring purposes. Note that logs may contain sensitive information and care should be
56+
taken to restrict access to the logs if they are saved, whether it be on local storage or Google Cloud Logging.
57+
58+
Users must **explicitly opt-in** to enable logging by configuring the `GOOGLE_SDK_PYTHON_LOGGING_SCOPE` environment variable with a valid logging scope.
59+
60+
A logging scope is a namespace that begins with :code:`google`.
61+
62+
- Valid logging scopes: :code:`google`, :code:`google.cloud.asset.v1`, :code:`google.api`, :code:`google.auth`, etc.
63+
- Invalid logging scopes: :code:`foo`, :code:`123`, etc.
64+
65+
**NOTE**: If an invalid logging scope is configured, we do not act on the corresponding logger.
66+
67+
To set a handler that applies to all Google-based loggers:
68+
69+
.. code-block:: console
70+
71+
export GOOGLE_SDK_PYTHON_LOGGING_SCOPE=google
72+
73+
To enable a handler for a specific GAPIC:
74+
75+
.. code-block:: console
76+
77+
export GOOGLE_SDK_PYTHON_LOGGING_SCOPE=google.cloud.abc.v1
78+
79+
: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.
80+
81+
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.
82+
83+
Alternatively, users can define and configure a valid logging scope using the standard logging library.
84+
85+
A typical use case is the following, which defines a handler that applies to all Google-based loggers:
86+
87+
.. code-block:: python3
88+
89+
import logging
90+
91+
from google.cloud.translate_v3 import translate
92+
93+
base_logger = logging.getLogger("google")
94+
base_logger.addHandler(logging.StreamHandler())
95+
base_logger.setLevel(logging.DEBUG)
96+
Client = translate.TranslationServiceClient()

‎tests/integration/goldens/credentials/README.rst‎

Lines changed: 47 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -47,3 +47,50 @@ Windows
4747
python3 -m venv <your-env>
4848
<your-env>\Scripts\activate
4949
<your-env>\Scripts\pip.exe install \path\to\library
50+
51+
52+
LOGGING
53+
-------
54+
55+
This library has support to enable logging for debugging and monitoring purposes. Note that logs may contain sensitive information and care should be
56+
taken to restrict access to the logs if they are saved, whether it be on local storage or Google Cloud Logging.
57+
58+
Users must **explicitly opt-in** to enable logging by configuring the `GOOGLE_SDK_PYTHON_LOGGING_SCOPE` environment variable with a valid logging scope.
59+
60+
A logging scope is a namespace that begins with :code:`google`.
61+
62+
- Valid logging scopes: :code:`google`, :code:`google.cloud.asset.v1`, :code:`google.api`, :code:`google.auth`, etc.
63+
- Invalid logging scopes: :code:`foo`, :code:`123`, etc.
64+
65+
**NOTE**: If an invalid logging scope is configured, we do not act on the corresponding logger.
66+
67+
To set a handler that applies to all Google-based loggers:
68+
69+
.. code-block:: console
70+
71+
export GOOGLE_SDK_PYTHON_LOGGING_SCOPE=google
72+
73+
To enable a handler for a specific GAPIC:
74+
75+
.. code-block:: console
76+
77+
export GOOGLE_SDK_PYTHON_LOGGING_SCOPE=google.cloud.abc.v1
78+
79+
: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.
80+
81+
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.
82+
83+
Alternatively, users can define and configure a valid logging scope using the standard logging library.
84+
85+
A typical use case is the following, which defines a handler that applies to all Google-based loggers:
86+
87+
.. code-block:: python3
88+
89+
import logging
90+
91+
from google.cloud.translate_v3 import translate
92+
93+
base_logger = logging.getLogger("google")
94+
base_logger.addHandler(logging.StreamHandler())
95+
base_logger.setLevel(logging.DEBUG)
96+
Client = translate.TranslationServiceClient()

‎tests/integration/goldens/eventarc/README.rst‎

Lines changed: 47 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -47,3 +47,50 @@ Windows
4747
python3 -m venv <your-env>
4848
<your-env>\Scripts\activate
4949
<your-env>\Scripts\pip.exe install \path\to\library
50+
51+
52+
LOGGING
53+
-------
54+
55+
This library has support to enable logging for debugging and monitoring purposes. Note that logs may contain sensitive information and care should be
56+
taken to restrict access to the logs if they are saved, whether it be on local storage or Google Cloud Logging.
57+
58+
Users must **explicitly opt-in** to enable logging by configuring the `GOOGLE_SDK_PYTHON_LOGGING_SCOPE` environment variable with a valid logging scope.
59+
60+
A logging scope is a namespace that begins with :code:`google`.
61+
62+
- Valid logging scopes: :code:`google`, :code:`google.cloud.asset.v1`, :code:`google.api`, :code:`google.auth`, etc.
63+
- Invalid logging scopes: :code:`foo`, :code:`123`, etc.
64+
65+
**NOTE**: If an invalid logging scope is configured, we do not act on the corresponding logger.
66+
67+
To set a handler that applies to all Google-based loggers:
68+
69+
.. code-block:: console
70+
71+
export GOOGLE_SDK_PYTHON_LOGGING_SCOPE=google
72+
73+
To enable a handler for a specific GAPIC:
74+
75+
.. code-block:: console
76+
77+
export GOOGLE_SDK_PYTHON_LOGGING_SCOPE=google.cloud.abc.v1
78+
79+
: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.
80+
81+
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.
82+
83+
Alternatively, users can define and configure a valid logging scope using the standard logging library.
84+
85+
A typical use case is the following, which defines a handler that applies to all Google-based loggers:
86+
87+
.. code-block:: python3
88+
89+
import logging
90+
91+
from google.cloud.translate_v3 import translate
92+
93+
base_logger = logging.getLogger("google")
94+
base_logger.addHandler(logging.StreamHandler())
95+
base_logger.setLevel(logging.DEBUG)
96+
Client = translate.TranslationServiceClient()

‎tests/integration/goldens/redis/README.rst‎

Lines changed: 47 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -47,3 +47,50 @@ Windows
4747
python3 -m venv <your-env>
4848
<your-env>\Scripts\activate
4949
<your-env>\Scripts\pip.exe install \path\to\library
50+
51+
52+
LOGGING
53+
-------
54+
55+
This library has support to enable logging for debugging and monitoring purposes. Note that logs may contain sensitive information and care should be
56+
taken to restrict access to the logs if they are saved, whether it be on local storage or Google Cloud Logging.
57+
58+
Users must **explicitly opt-in** to enable logging by configuring the `GOOGLE_SDK_PYTHON_LOGGING_SCOPE` environment variable with a valid logging scope.
59+
60+
A logging scope is a namespace that begins with :code:`google`.
61+
62+
- Valid logging scopes: :code:`google`, :code:`google.cloud.asset.v1`, :code:`google.api`, :code:`google.auth`, etc.
63+
- Invalid logging scopes: :code:`foo`, :code:`123`, etc.
64+
65+
**NOTE**: If an invalid logging scope is configured, we do not act on the corresponding logger.
66+
67+
To set a handler that applies to all Google-based loggers:
68+
69+
.. code-block:: console
70+
71+
export GOOGLE_SDK_PYTHON_LOGGING_SCOPE=google
72+
73+
To enable a handler for a specific GAPIC:
74+
75+
.. code-block:: console
76+
77+
export GOOGLE_SDK_PYTHON_LOGGING_SCOPE=google.cloud.abc.v1
78+
79+
: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.
80+
81+
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.
82+
83+
Alternatively, users can define and configure a valid logging scope using the standard logging library.
84+
85+
A typical use case is the following, which defines a handler that applies to all Google-based loggers:
86+
87+
.. code-block:: python3
88+
89+
import logging
90+
91+
from google.cloud.translate_v3 import translate
92+
93+
base_logger = logging.getLogger("google")
94+
base_logger.addHandler(logging.StreamHandler())
95+
base_logger.setLevel(logging.DEBUG)
96+
Client = translate.TranslationServiceClient()

0 commit comments

Comments
 (0)