google-cloud-logging 3.11.3__tar.gz → 3.12.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (111) hide show
  1. {google_cloud_logging-3.11.3/google_cloud_logging.egg-info → google_cloud_logging-3.12.0}/PKG-INFO +12 -11
  2. {google_cloud_logging-3.11.3 → google_cloud_logging-3.12.0}/README.rst +1 -1
  3. {google_cloud_logging-3.11.3 → google_cloud_logging-3.12.0}/google/cloud/logging/gapic_version.py +1 -1
  4. {google_cloud_logging-3.11.3 → google_cloud_logging-3.12.0}/google/cloud/logging_v2/_gapic.py +5 -1
  5. {google_cloud_logging-3.11.3 → google_cloud_logging-3.12.0}/google/cloud/logging_v2/client.py +17 -1
  6. {google_cloud_logging-3.11.3 → google_cloud_logging-3.12.0}/google/cloud/logging_v2/gapic_version.py +1 -1
  7. {google_cloud_logging-3.11.3 → google_cloud_logging-3.12.0}/google/cloud/logging_v2/handlers/handlers.py +26 -1
  8. {google_cloud_logging-3.11.3 → google_cloud_logging-3.12.0}/google/cloud/logging_v2/handlers/transports/background_thread.py +46 -12
  9. {google_cloud_logging-3.11.3 → google_cloud_logging-3.12.0}/google/cloud/logging_v2/handlers/transports/base.py +8 -0
  10. {google_cloud_logging-3.11.3 → google_cloud_logging-3.12.0}/google/cloud/logging_v2/handlers/transports/sync.py +7 -0
  11. {google_cloud_logging-3.11.3 → google_cloud_logging-3.12.0}/google/cloud/logging_v2/logger.py +42 -3
  12. {google_cloud_logging-3.11.3 → google_cloud_logging-3.12.0}/google/cloud/logging_v2/services/__init__.py +1 -1
  13. {google_cloud_logging-3.11.3 → google_cloud_logging-3.12.0}/google/cloud/logging_v2/services/config_service_v2/__init__.py +1 -1
  14. {google_cloud_logging-3.11.3 → google_cloud_logging-3.12.0}/google/cloud/logging_v2/services/config_service_v2/async_client.py +284 -143
  15. {google_cloud_logging-3.11.3 → google_cloud_logging-3.12.0}/google/cloud/logging_v2/services/config_service_v2/client.py +346 -194
  16. {google_cloud_logging-3.11.3 → google_cloud_logging-3.12.0}/google/cloud/logging_v2/services/config_service_v2/pagers.py +51 -31
  17. {google_cloud_logging-3.11.3 → google_cloud_logging-3.12.0}/google/cloud/logging_v2/services/config_service_v2/transports/__init__.py +1 -1
  18. {google_cloud_logging-3.11.3 → google_cloud_logging-3.12.0}/google/cloud/logging_v2/services/config_service_v2/transports/base.py +16 -1
  19. {google_cloud_logging-3.11.3 → google_cloud_logging-3.12.0}/google/cloud/logging_v2/services/config_service_v2/transports/grpc.py +127 -39
  20. {google_cloud_logging-3.11.3 → google_cloud_logging-3.12.0}/google/cloud/logging_v2/services/config_service_v2/transports/grpc_asyncio.py +184 -71
  21. {google_cloud_logging-3.11.3 → google_cloud_logging-3.12.0}/google/cloud/logging_v2/services/logging_service_v2/__init__.py +1 -1
  22. {google_cloud_logging-3.11.3 → google_cloud_logging-3.12.0}/google/cloud/logging_v2/services/logging_service_v2/async_client.py +98 -51
  23. {google_cloud_logging-3.11.3 → google_cloud_logging-3.12.0}/google/cloud/logging_v2/services/logging_service_v2/client.py +160 -102
  24. {google_cloud_logging-3.11.3 → google_cloud_logging-3.12.0}/google/cloud/logging_v2/services/logging_service_v2/pagers.py +31 -19
  25. {google_cloud_logging-3.11.3 → google_cloud_logging-3.12.0}/google/cloud/logging_v2/services/logging_service_v2/transports/__init__.py +1 -1
  26. {google_cloud_logging-3.11.3 → google_cloud_logging-3.12.0}/google/cloud/logging_v2/services/logging_service_v2/transports/base.py +16 -1
  27. {google_cloud_logging-3.11.3 → google_cloud_logging-3.12.0}/google/cloud/logging_v2/services/logging_service_v2/transports/grpc.py +98 -12
  28. {google_cloud_logging-3.11.3 → google_cloud_logging-3.12.0}/google/cloud/logging_v2/services/logging_service_v2/transports/grpc_asyncio.py +131 -18
  29. {google_cloud_logging-3.11.3 → google_cloud_logging-3.12.0}/google/cloud/logging_v2/services/metrics_service_v2/__init__.py +1 -1
  30. {google_cloud_logging-3.11.3 → google_cloud_logging-3.12.0}/google/cloud/logging_v2/services/metrics_service_v2/async_client.py +97 -49
  31. {google_cloud_logging-3.11.3 → google_cloud_logging-3.12.0}/google/cloud/logging_v2/services/metrics_service_v2/client.py +159 -100
  32. {google_cloud_logging-3.11.3 → google_cloud_logging-3.12.0}/google/cloud/logging_v2/services/metrics_service_v2/pagers.py +11 -7
  33. {google_cloud_logging-3.11.3 → google_cloud_logging-3.12.0}/google/cloud/logging_v2/services/metrics_service_v2/transports/__init__.py +1 -1
  34. {google_cloud_logging-3.11.3 → google_cloud_logging-3.12.0}/google/cloud/logging_v2/services/metrics_service_v2/transports/base.py +16 -1
  35. {google_cloud_logging-3.11.3 → google_cloud_logging-3.12.0}/google/cloud/logging_v2/services/metrics_service_v2/transports/grpc.py +97 -11
  36. {google_cloud_logging-3.11.3 → google_cloud_logging-3.12.0}/google/cloud/logging_v2/services/metrics_service_v2/transports/grpc_asyncio.py +129 -16
  37. {google_cloud_logging-3.11.3 → google_cloud_logging-3.12.0}/google/cloud/logging_v2/types/__init__.py +1 -1
  38. {google_cloud_logging-3.11.3 → google_cloud_logging-3.12.0}/google/cloud/logging_v2/types/log_entry.py +1 -1
  39. {google_cloud_logging-3.11.3 → google_cloud_logging-3.12.0}/google/cloud/logging_v2/types/logging.py +1 -1
  40. {google_cloud_logging-3.11.3 → google_cloud_logging-3.12.0}/google/cloud/logging_v2/types/logging_config.py +1 -1
  41. {google_cloud_logging-3.11.3 → google_cloud_logging-3.12.0}/google/cloud/logging_v2/types/logging_metrics.py +1 -1
  42. {google_cloud_logging-3.11.3 → google_cloud_logging-3.12.0/google_cloud_logging.egg-info}/PKG-INFO +12 -11
  43. google_cloud_logging-3.12.0/google_cloud_logging.egg-info/requires.txt +15 -0
  44. {google_cloud_logging-3.11.3 → google_cloud_logging-3.12.0}/setup.py +10 -9
  45. {google_cloud_logging-3.11.3 → google_cloud_logging-3.12.0}/tests/__init__.py +1 -1
  46. {google_cloud_logging-3.11.3 → google_cloud_logging-3.12.0}/tests/system/test_system.py +67 -0
  47. {google_cloud_logging-3.11.3 → google_cloud_logging-3.12.0}/tests/unit/__init__.py +1 -1
  48. {google_cloud_logging-3.11.3 → google_cloud_logging-3.12.0}/tests/unit/gapic/__init__.py +1 -1
  49. google_cloud_logging-3.12.0/tests/unit/gapic/logging_v2/__init__.py +15 -0
  50. {google_cloud_logging-3.11.3 → google_cloud_logging-3.12.0}/tests/unit/gapic/logging_v2/test_config_service_v2.py +2189 -1952
  51. {google_cloud_logging-3.11.3 → google_cloud_logging-3.12.0}/tests/unit/gapic/logging_v2/test_logging_service_v2.py +420 -381
  52. {google_cloud_logging-3.11.3 → google_cloud_logging-3.12.0}/tests/unit/gapic/logging_v2/test_metrics_service_v2.py +437 -399
  53. {google_cloud_logging-3.11.3 → google_cloud_logging-3.12.0}/tests/unit/handlers/test_handlers.py +81 -0
  54. {google_cloud_logging-3.11.3 → google_cloud_logging-3.12.0}/tests/unit/handlers/transports/test_background_thread.py +131 -12
  55. {google_cloud_logging-3.11.3 → google_cloud_logging-3.12.0}/tests/unit/handlers/transports/test_base.py +4 -0
  56. {google_cloud_logging-3.11.3 → google_cloud_logging-3.12.0}/tests/unit/test__gapic.py +17 -0
  57. {google_cloud_logging-3.11.3 → google_cloud_logging-3.12.0}/tests/unit/test_client.py +164 -0
  58. google_cloud_logging-3.11.3/google_cloud_logging.egg-info/requires.txt +0 -12
  59. google_cloud_logging-3.11.3/tests/unit/gapic/logging_v2/__init__.py +0 -15
  60. {google_cloud_logging-3.11.3 → google_cloud_logging-3.12.0}/LICENSE +0 -0
  61. {google_cloud_logging-3.11.3 → google_cloud_logging-3.12.0}/MANIFEST.in +0 -0
  62. {google_cloud_logging-3.11.3 → google_cloud_logging-3.12.0}/google/cloud/logging/__init__.py +0 -0
  63. {google_cloud_logging-3.11.3 → google_cloud_logging-3.12.0}/google/cloud/logging/handlers/__init__.py +0 -0
  64. {google_cloud_logging-3.11.3 → google_cloud_logging-3.12.0}/google/cloud/logging/handlers/middleware/__init__.py +0 -0
  65. {google_cloud_logging-3.11.3 → google_cloud_logging-3.12.0}/google/cloud/logging/handlers/transports/__init__.py +0 -0
  66. {google_cloud_logging-3.11.3 → google_cloud_logging-3.12.0}/google/cloud/logging/py.typed +0 -0
  67. {google_cloud_logging-3.11.3 → google_cloud_logging-3.12.0}/google/cloud/logging_v2/__init__.py +0 -0
  68. {google_cloud_logging-3.11.3 → google_cloud_logging-3.12.0}/google/cloud/logging_v2/_helpers.py +0 -0
  69. {google_cloud_logging-3.11.3 → google_cloud_logging-3.12.0}/google/cloud/logging_v2/_http.py +0 -0
  70. {google_cloud_logging-3.11.3 → google_cloud_logging-3.12.0}/google/cloud/logging_v2/_instrumentation.py +0 -0
  71. {google_cloud_logging-3.11.3 → google_cloud_logging-3.12.0}/google/cloud/logging_v2/entries.py +0 -0
  72. {google_cloud_logging-3.11.3 → google_cloud_logging-3.12.0}/google/cloud/logging_v2/gapic_metadata.json +0 -0
  73. {google_cloud_logging-3.11.3 → google_cloud_logging-3.12.0}/google/cloud/logging_v2/handlers/__init__.py +0 -0
  74. {google_cloud_logging-3.11.3 → google_cloud_logging-3.12.0}/google/cloud/logging_v2/handlers/_helpers.py +0 -0
  75. {google_cloud_logging-3.11.3 → google_cloud_logging-3.12.0}/google/cloud/logging_v2/handlers/_monitored_resources.py +0 -0
  76. {google_cloud_logging-3.11.3 → google_cloud_logging-3.12.0}/google/cloud/logging_v2/handlers/app_engine.py +0 -0
  77. {google_cloud_logging-3.11.3 → google_cloud_logging-3.12.0}/google/cloud/logging_v2/handlers/container_engine.py +0 -0
  78. {google_cloud_logging-3.11.3 → google_cloud_logging-3.12.0}/google/cloud/logging_v2/handlers/middleware/__init__.py +0 -0
  79. {google_cloud_logging-3.11.3 → google_cloud_logging-3.12.0}/google/cloud/logging_v2/handlers/middleware/request.py +0 -0
  80. {google_cloud_logging-3.11.3 → google_cloud_logging-3.12.0}/google/cloud/logging_v2/handlers/structured_log.py +0 -0
  81. {google_cloud_logging-3.11.3 → google_cloud_logging-3.12.0}/google/cloud/logging_v2/handlers/transports/__init__.py +0 -0
  82. {google_cloud_logging-3.11.3 → google_cloud_logging-3.12.0}/google/cloud/logging_v2/metric.py +0 -0
  83. {google_cloud_logging-3.11.3 → google_cloud_logging-3.12.0}/google/cloud/logging_v2/py.typed +0 -0
  84. {google_cloud_logging-3.11.3 → google_cloud_logging-3.12.0}/google/cloud/logging_v2/resource.py +0 -0
  85. {google_cloud_logging-3.11.3 → google_cloud_logging-3.12.0}/google/cloud/logging_v2/sink.py +0 -0
  86. {google_cloud_logging-3.11.3 → google_cloud_logging-3.12.0}/google_cloud_logging.egg-info/SOURCES.txt +0 -0
  87. {google_cloud_logging-3.11.3 → google_cloud_logging-3.12.0}/google_cloud_logging.egg-info/dependency_links.txt +0 -0
  88. {google_cloud_logging-3.11.3 → google_cloud_logging-3.12.0}/google_cloud_logging.egg-info/not-zip-safe +0 -0
  89. {google_cloud_logging-3.11.3 → google_cloud_logging-3.12.0}/google_cloud_logging.egg-info/top_level.txt +0 -0
  90. {google_cloud_logging-3.11.3 → google_cloud_logging-3.12.0}/setup.cfg +0 -0
  91. {google_cloud_logging-3.11.3 → google_cloud_logging-3.12.0}/tests/performance/noxfile.py +0 -0
  92. {google_cloud_logging-3.11.3 → google_cloud_logging-3.12.0}/tests/performance/test_performance.py +0 -0
  93. {google_cloud_logging-3.11.3 → google_cloud_logging-3.12.0}/tests/system/gapic/v2/test_system_logging_service_v2_v2.py +0 -0
  94. {google_cloud_logging-3.11.3 → google_cloud_logging-3.12.0}/tests/unit/handlers/__init__.py +0 -0
  95. {google_cloud_logging-3.11.3 → google_cloud_logging-3.12.0}/tests/unit/handlers/middleware/test_request.py +0 -0
  96. {google_cloud_logging-3.11.3 → google_cloud_logging-3.12.0}/tests/unit/handlers/test__helpers.py +0 -0
  97. {google_cloud_logging-3.11.3 → google_cloud_logging-3.12.0}/tests/unit/handlers/test__monitored_resources.py +0 -0
  98. {google_cloud_logging-3.11.3 → google_cloud_logging-3.12.0}/tests/unit/handlers/test_app_engine.py +0 -0
  99. {google_cloud_logging-3.11.3 → google_cloud_logging-3.12.0}/tests/unit/handlers/test_container_engine.py +0 -0
  100. {google_cloud_logging-3.11.3 → google_cloud_logging-3.12.0}/tests/unit/handlers/test_structured_log.py +0 -0
  101. {google_cloud_logging-3.11.3 → google_cloud_logging-3.12.0}/tests/unit/handlers/transports/__init__.py +0 -0
  102. {google_cloud_logging-3.11.3 → google_cloud_logging-3.12.0}/tests/unit/handlers/transports/test_sync.py +0 -0
  103. {google_cloud_logging-3.11.3 → google_cloud_logging-3.12.0}/tests/unit/test__helpers.py +0 -0
  104. {google_cloud_logging-3.11.3 → google_cloud_logging-3.12.0}/tests/unit/test__http.py +0 -0
  105. {google_cloud_logging-3.11.3 → google_cloud_logging-3.12.0}/tests/unit/test__instrumentation.py +0 -0
  106. {google_cloud_logging-3.11.3 → google_cloud_logging-3.12.0}/tests/unit/test_entries.py +0 -0
  107. {google_cloud_logging-3.11.3 → google_cloud_logging-3.12.0}/tests/unit/test_logger.py +0 -0
  108. {google_cloud_logging-3.11.3 → google_cloud_logging-3.12.0}/tests/unit/test_logging_shim.py +0 -0
  109. {google_cloud_logging-3.11.3 → google_cloud_logging-3.12.0}/tests/unit/test_metric.py +0 -0
  110. {google_cloud_logging-3.11.3 → google_cloud_logging-3.12.0}/tests/unit/test_packaging.py +0 -0
  111. {google_cloud_logging-3.11.3 → google_cloud_logging-3.12.0}/tests/unit/test_sink.py +0 -0
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.1
2
2
  Name: google-cloud-logging
3
- Version: 3.11.3
3
+ Version: 3.12.0
4
4
  Summary: Stackdriver Logging API client library
5
5
  Home-page: https://github.com/googleapis/python-logging
6
6
  Author: Google LLC
@@ -22,16 +22,17 @@ Classifier: Operating System :: OS Independent
22
22
  Classifier: Topic :: Internet
23
23
  Requires-Python: >=3.7
24
24
  License-File: LICENSE
25
- Requires-Dist: google-api-core[grpc]!=2.0.*,!=2.1.*,!=2.10.*,!=2.2.*,!=2.3.*,!=2.4.*,!=2.5.*,!=2.6.*,!=2.7.*,!=2.8.*,!=2.9.*,<3.0.0dev,>=1.34.1
26
- Requires-Dist: google-auth!=2.24.0,!=2.25.0,<3.0.0dev,>=2.14.1
27
- Requires-Dist: google-cloud-appengine-logging<2.0.0dev,>=0.1.3
28
- Requires-Dist: google-cloud-audit-log<1.0.0dev,>=0.2.4
29
- Requires-Dist: google-cloud-core<3.0.0dev,>=2.0.0
30
- Requires-Dist: grpc-google-iam-v1<1.0.0dev,>=0.12.4
25
+ Requires-Dist: google-api-core[grpc]!=2.0.*,!=2.1.*,!=2.10.*,!=2.2.*,!=2.3.*,!=2.4.*,!=2.5.*,!=2.6.*,!=2.7.*,!=2.8.*,!=2.9.*,<3.0.0,>=1.34.1
26
+ Requires-Dist: google-auth!=2.24.0,!=2.25.0,<3.0.0,>=2.14.1
27
+ Requires-Dist: google-cloud-appengine-logging<2.0.0,>=0.1.3
28
+ Requires-Dist: google-cloud-audit-log<1.0.0,>=0.3.1
29
+ Requires-Dist: google-cloud-core<3.0.0,>=2.0.0
30
+ Requires-Dist: grpc-google-iam-v1<1.0.0,>=0.12.4
31
31
  Requires-Dist: opentelemetry-api>=1.9.0
32
- Requires-Dist: proto-plus<2.0.0dev,>=1.22.0
33
- Requires-Dist: proto-plus<2.0.0dev,>=1.22.2; python_version >= "3.11"
34
- Requires-Dist: protobuf!=4.21.0,!=4.21.1,!=4.21.2,!=4.21.3,!=4.21.4,!=4.21.5,<6.0.0dev,>=3.20.2
32
+ Requires-Dist: proto-plus<2.0.0,>=1.22.0
33
+ Requires-Dist: proto-plus<2.0.0,>=1.22.2; python_version >= "3.11"
34
+ Requires-Dist: proto-plus<2.0.0,>=1.25.0; python_version >= "3.13"
35
+ Requires-Dist: protobuf!=4.21.0,!=4.21.1,!=4.21.2,!=4.21.3,!=4.21.4,!=4.21.5,<7.0.0,>=3.20.2
35
36
 
36
37
  Python Client for Cloud Logging
37
38
  =====================================
@@ -49,7 +50,7 @@ Logging configuration.
49
50
  .. |versions| image:: https://img.shields.io/pypi/pyversions/google-cloud-logging.svg
50
51
  :target: https://pypi.org/project/google-cloud-logging/
51
52
  .. _Cloud Logging API: https://cloud.google.com/logging
52
- .. _Client Library Documentation: https://googleapis.dev/python/logging/latest
53
+ .. _Client Library Documentation: https://cloud.google.com/python/docs/reference/logging/latest/summary_overview
53
54
  .. _Product Documentation: https://cloud.google.com/logging/docs
54
55
  .. _Setting Up Cloud Logging for Python: https://cloud.google.com/logging/docs/setup/python
55
56
  .. _Python's standard logging library: https://docs.python.org/2/library/logging.html
@@ -14,7 +14,7 @@ Logging configuration.
14
14
  .. |versions| image:: https://img.shields.io/pypi/pyversions/google-cloud-logging.svg
15
15
  :target: https://pypi.org/project/google-cloud-logging/
16
16
  .. _Cloud Logging API: https://cloud.google.com/logging
17
- .. _Client Library Documentation: https://googleapis.dev/python/logging/latest
17
+ .. _Client Library Documentation: https://cloud.google.com/python/docs/reference/logging/latest/summary_overview
18
18
  .. _Product Documentation: https://cloud.google.com/logging/docs
19
19
  .. _Setting Up Cloud Logging for Python: https://cloud.google.com/logging/docs/setup/python
20
20
  .. _Python's standard logging library: https://docs.python.org/2/library/logging.html
@@ -13,4 +13,4 @@
13
13
  # See the License for the specific language governing permissions and
14
14
  # limitations under the License.
15
15
  #
16
- __version__ = "3.11.3" # {x-release-please-version}
16
+ __version__ = "3.12.0" # {x-release-please-version}
@@ -30,6 +30,7 @@ from google.cloud.logging_v2.types import LogEntry as LogEntryPB
30
30
 
31
31
  from google.protobuf.json_format import MessageToDict
32
32
  from google.protobuf.json_format import ParseDict
33
+ from google.protobuf.json_format import ParseError
33
34
 
34
35
  from google.cloud.logging_v2._helpers import entry_from_resource
35
36
  from google.cloud.logging_v2.sink import Sink
@@ -151,7 +152,10 @@ class _LoggingAPI(object):
151
152
  Useful for checking whether the logging API endpoints are working
152
153
  properly before sending valuable data.
153
154
  """
154
- log_entry_pbs = [_log_entry_mapping_to_pb(entry) for entry in entries]
155
+ try:
156
+ log_entry_pbs = [_log_entry_mapping_to_pb(entry) for entry in entries]
157
+ except ParseError as e:
158
+ raise ValueError(f"Invalid log entry: {str(e)}") from e
155
159
 
156
160
  request = WriteLogEntriesRequest(
157
161
  log_name=logger_name,
@@ -149,6 +149,8 @@ class Client(ClientWithProject):
149
149
  else:
150
150
  self._use_grpc = _use_grpc
151
151
 
152
+ self._handlers = set()
153
+
152
154
  @property
153
155
  def logging_api(self):
154
156
  """Helper for logging-related API calls.
@@ -400,7 +402,8 @@ class Client(ClientWithProject):
400
402
  loggers, will report to Cloud Logging.
401
403
 
402
404
  Args:
403
- log_level (Optional[int]): Python logging log level. Defaults to
405
+ log_level (Optional[int]): The logging level threshold of the attached logger,
406
+ as set by the :meth:`logging.Logger.setLevel` method. Defaults to
404
407
  :const:`logging.INFO`.
405
408
  excluded_loggers (Optional[Tuple[str]]): The loggers to not attach the
406
409
  handler to. This will always include the
@@ -410,4 +413,17 @@ class Client(ClientWithProject):
410
413
  dict: keyword args passed to handler constructor
411
414
  """
412
415
  handler = self.get_default_handler(**kw)
416
+ self._handlers.add(handler)
413
417
  setup_logging(handler, log_level=log_level, excluded_loggers=excluded_loggers)
418
+
419
+ def flush_handlers(self):
420
+ """Flushes all Python log handlers associated with this Client."""
421
+
422
+ for handler in self._handlers:
423
+ handler.flush()
424
+
425
+ def close(self):
426
+ """Closes the Client and all handlers associated with this Client."""
427
+ super(Client, self).close()
428
+ for handler in self._handlers:
429
+ handler.close()
@@ -13,4 +13,4 @@
13
13
  # See the License for the specific language governing permissions and
14
14
  # limitations under the License.
15
15
  #
16
- __version__ = "3.11.3" # {x-release-please-version}
16
+ __version__ = "3.12.0" # {x-release-please-version}
@@ -188,7 +188,10 @@ class CloudLoggingHandler(logging.StreamHandler):
188
188
  resource = detect_resource(client.project)
189
189
  self.name = name
190
190
  self.client = client
191
+ client._handlers.add(self)
191
192
  self.transport = transport(client, name, resource=resource)
193
+ self._transport_open = True
194
+ self._transport_cls = transport
192
195
  self.project_id = client.project
193
196
  self.resource = resource
194
197
  self.labels = labels
@@ -213,6 +216,12 @@ class CloudLoggingHandler(logging.StreamHandler):
213
216
  labels = {**add_resource_labels(resource, record), **(labels or {})} or None
214
217
 
215
218
  # send off request
219
+ if not self._transport_open:
220
+ self.transport = self._transport_cls(
221
+ self.client, self.name, resource=self.resource
222
+ )
223
+ self._transport_open = True
224
+
216
225
  self.transport.send(
217
226
  record,
218
227
  message,
@@ -225,6 +234,21 @@ class CloudLoggingHandler(logging.StreamHandler):
225
234
  source_location=record._source_location,
226
235
  )
227
236
 
237
+ def flush(self):
238
+ """Forces the Transport object to submit any pending log records.
239
+
240
+ For SyncTransport, this is a no-op.
241
+ """
242
+ super(CloudLoggingHandler, self).flush()
243
+ if self._transport_open:
244
+ self.transport.flush()
245
+
246
+ def close(self):
247
+ """Closes the log handler and cleans up all Transport objects used."""
248
+ self.transport.close()
249
+ self.transport = None
250
+ self._transport_open = False
251
+
228
252
 
229
253
  def _format_and_parse_message(record, formatter_handler):
230
254
  """
@@ -296,7 +320,8 @@ def setup_logging(
296
320
  excluded_loggers (Optional[Tuple[str]]): The loggers to not attach the handler
297
321
  to. This will always include the loggers in the
298
322
  path of the logging client itself.
299
- log_level (Optional[int]): Python logging log level. Defaults to
323
+ log_level (Optional[int]): The logging level threshold of the attached logger,
324
+ as set by the :meth:`logging.Logger.setLevel` method. Defaults to
300
325
  :const:`logging.INFO`.
301
326
  """
302
327
  all_excluded_loggers = set(excluded_loggers + _INTERNAL_LOGGERS)
@@ -38,6 +38,13 @@ _WORKER_THREAD_NAME = "google.cloud.logging.Worker"
38
38
  _WORKER_TERMINATOR = object()
39
39
  _LOGGER = logging.getLogger(__name__)
40
40
 
41
+ _CLOSE_THREAD_SHUTDOWN_ERROR_MSG = (
42
+ "CloudLoggingHandler shutting down, cannot send logs entries to Cloud Logging due to "
43
+ "inconsistent threading behavior at shutdown. To avoid this issue, flush the logging handler "
44
+ "manually or switch to StructuredLogHandler. You can also close the CloudLoggingHandler manually "
45
+ "via handler.close or client.close."
46
+ )
47
+
41
48
 
42
49
  def _get_many(queue_, *, max_items=None, max_latency=0):
43
50
  """Get multiple items from a Queue.
@@ -140,9 +147,11 @@ class _Worker(object):
140
147
  else:
141
148
  batch.log(**item)
142
149
 
143
- self._safely_commit_batch(batch)
150
+ # We cannot commit logs upstream if the main thread is shutting down
151
+ if threading.main_thread().is_alive():
152
+ self._safely_commit_batch(batch)
144
153
 
145
- for _ in items:
154
+ for it in items:
146
155
  self._queue.task_done()
147
156
 
148
157
  _LOGGER.debug("Background thread exited gracefully.")
@@ -162,7 +171,7 @@ class _Worker(object):
162
171
  )
163
172
  self._thread.daemon = True
164
173
  self._thread.start()
165
- atexit.register(self._main_thread_terminated)
174
+ atexit.register(self._handle_exit)
166
175
 
167
176
  def stop(self, *, grace_period=None):
168
177
  """Signals the background thread to stop.
@@ -202,26 +211,26 @@ class _Worker(object):
202
211
 
203
212
  return success
204
213
 
205
- def _main_thread_terminated(self):
206
- """Callback that attempts to send pending logs before termination."""
214
+ def _close(self, close_msg):
215
+ """Callback that attempts to send pending logs before termination if the main thread is alive."""
207
216
  if not self.is_alive:
208
217
  return
209
218
 
210
219
  if not self._queue.empty():
211
- print(
212
- "Program shutting down, attempting to send %d queued log "
213
- "entries to Cloud Logging..." % (self._queue.qsize(),),
214
- file=sys.stderr,
215
- )
220
+ print(close_msg, file=sys.stderr)
216
221
 
217
- if self.stop(grace_period=self._grace_period):
222
+ if threading.main_thread().is_alive() and self.stop(
223
+ grace_period=self._grace_period
224
+ ):
218
225
  print("Sent all pending logs.", file=sys.stderr)
219
- else:
226
+ elif not self._queue.empty():
220
227
  print(
221
228
  "Failed to send %d pending logs." % (self._queue.qsize(),),
222
229
  file=sys.stderr,
223
230
  )
224
231
 
232
+ self._thread = None
233
+
225
234
  def enqueue(self, record, message, **kwargs):
226
235
  """Queues a log entry to be written by the background thread.
227
236
 
@@ -251,6 +260,26 @@ class _Worker(object):
251
260
  """Submit any pending log records."""
252
261
  self._queue.join()
253
262
 
263
+ def close(self):
264
+ """Signals the worker thread to stop, then closes the transport thread.
265
+
266
+ This call will attempt to send pending logs before termination, and
267
+ should be followed up by disowning the transport object.
268
+ """
269
+ atexit.unregister(self._handle_exit)
270
+ self._close(
271
+ "Background thread shutting down, attempting to send %d queued log "
272
+ "entries to Cloud Logging..." % (self._queue.qsize(),)
273
+ )
274
+
275
+ def _handle_exit(self):
276
+ """Handle system exit.
277
+
278
+ Since we cannot send pending logs during system shutdown due to thread errors,
279
+ log an error message to stderr to notify the user.
280
+ """
281
+ self._close(_CLOSE_THREAD_SHUTDOWN_ERROR_MSG)
282
+
254
283
 
255
284
  class BackgroundThreadTransport(Transport):
256
285
  """Asynchronous transport that uses a background thread."""
@@ -285,6 +314,7 @@ class BackgroundThreadTransport(Transport):
285
314
  """
286
315
  self.client = client
287
316
  logger = self.client.logger(name, resource=resource)
317
+ self.grace_period = grace_period
288
318
  self.worker = _Worker(
289
319
  logger,
290
320
  grace_period=grace_period,
@@ -307,3 +337,7 @@ class BackgroundThreadTransport(Transport):
307
337
  def flush(self):
308
338
  """Submit any pending log records."""
309
339
  self.worker.flush()
340
+
341
+ def close(self):
342
+ """Closes the worker thread."""
343
+ self.worker.close()
@@ -51,3 +51,11 @@ class Transport(object):
51
51
 
52
52
  For blocking/sync transports, this is a no-op.
53
53
  """
54
+ pass
55
+
56
+ def close(self):
57
+ """Closes the transport and cleans up resources used by it.
58
+
59
+ This call should be followed up by disowning the transport.
60
+ """
61
+ pass
@@ -59,3 +59,10 @@ class SyncTransport(Transport):
59
59
  labels=labels,
60
60
  **kwargs,
61
61
  )
62
+
63
+ def close(self):
64
+ """Closes the transport and cleans up resources used by it.
65
+
66
+ This call is usually followed up by cleaning up the reference to the transport.
67
+ """
68
+ self.logger = None
@@ -162,6 +162,7 @@ class Logger(object):
162
162
 
163
163
  api_repr = entry.to_api_repr()
164
164
  entries = [api_repr]
165
+
165
166
  if google.cloud.logging_v2._instrumentation_emitted is False:
166
167
  entries = _add_instrumentation(entries, **kw)
167
168
  google.cloud.logging_v2._instrumentation_emitted = True
@@ -200,18 +201,38 @@ class Logger(object):
200
201
  self._do_log(client, TextEntry, text, **kw)
201
202
 
202
203
  def log_struct(self, info, *, client=None, **kw):
203
- """Log a dictionary message
204
+ """Logs a dictionary message.
204
205
 
205
206
  See
206
207
  https://cloud.google.com/logging/docs/reference/v2/rest/v2/entries/write
207
208
 
209
+ The message must be able to be serializable to a Protobuf Struct.
210
+ It must be a dictionary of strings to one of the following:
211
+
212
+ - :class:`str`
213
+ - :class:`int`
214
+ - :class:`float`
215
+ - :class:`bool`
216
+ - :class:`list[str|float|int|bool|list|dict|None]`
217
+ - :class:`dict[str, str|float|int|bool|list|dict|None]`
218
+
219
+ For more details on Protobuf structs, see https://protobuf.dev/reference/protobuf/google.protobuf/#value.
220
+ If the provided dictionary cannot be serialized into a Protobuf struct,
221
+ it will not be logged, and a :class:`ValueError` will be raised.
222
+
208
223
  Args:
209
- info (dict): the log entry information
224
+ info (dict[str, str|float|int|bool|list|dict|None]):
225
+ the log entry information.
210
226
  client (Optional[~logging_v2.client.Client]):
211
227
  The client to use. If not passed, falls back to the
212
228
  ``client`` stored on the current sink.
213
229
  kw (Optional[dict]): additional keyword arguments for the entry.
214
230
  See :class:`~logging_v2.entries.LogEntry`.
231
+
232
+ Raises:
233
+ ValueError:
234
+ if the dictionary message provided cannot be serialized into a Protobuf
235
+ struct.
215
236
  """
216
237
  for field in _STRUCT_EXTRACTABLE_FIELDS:
217
238
  # attempt to copy relevant fields from the payload into the LogEntry body
@@ -405,8 +426,22 @@ class Batch(object):
405
426
  def log_struct(self, info, **kw):
406
427
  """Add a struct entry to be logged during :meth:`commit`.
407
428
 
429
+ The message must be able to be serializable to a Protobuf Struct.
430
+ It must be a dictionary of strings to one of the following:
431
+
432
+ - :class:`str`
433
+ - :class:`int`
434
+ - :class:`float`
435
+ - :class:`bool`
436
+ - :class:`list[str|float|int|bool|list|dict|None]`
437
+ - :class:`dict[str, str|float|int|bool|list|dict|None]`
438
+
439
+ For more details on Protobuf structs, see https://protobuf.dev/reference/protobuf/google.protobuf/#value.
440
+ If the provided dictionary cannot be serialized into a Protobuf struct,
441
+ it will not be logged, and a :class:`ValueError` will be raised during :meth:`commit`.
442
+
408
443
  Args:
409
- info (dict): The struct entry,
444
+ info (dict[str, str|float|int|bool|list|dict|None]): The struct entry,
410
445
  kw (Optional[dict]): Additional keyword arguments for the entry.
411
446
  See :class:`~logging_v2.entries.LogEntry`.
412
447
  """
@@ -451,6 +486,10 @@ class Batch(object):
451
486
  Whether a batch's valid entries should be written even
452
487
  if some other entry failed due to a permanent error such
453
488
  as INVALID_ARGUMENT or PERMISSION_DENIED.
489
+
490
+ Raises:
491
+ ValueError:
492
+ if one of the messages in the batch cannot be successfully parsed.
454
493
  """
455
494
  if client is None:
456
495
  client = self.client
@@ -1,5 +1,5 @@
1
1
  # -*- coding: utf-8 -*-
2
- # Copyright 2024 Google LLC
2
+ # Copyright 2025 Google LLC
3
3
  #
4
4
  # Licensed under the Apache License, Version 2.0 (the "License");
5
5
  # you may not use this file except in compliance with the License.
@@ -1,5 +1,5 @@
1
1
  # -*- coding: utf-8 -*-
2
- # Copyright 2024 Google LLC
2
+ # Copyright 2025 Google LLC
3
3
  #
4
4
  # Licensed under the Apache License, Version 2.0 (the "License");
5
5
  # you may not use this file except in compliance with the License.