Shortcuts on this page
r m x toggle line displays
j k next/prev highlighted chunk
0 (zero) top of page
1 (one) first highlighted chunk
1# -*- coding: utf-8 -*-
2# Copyright 2025 Google LLC
3#
4# Licensed under the Apache License, Version 2.0 (the "License");
5# you may not use this file except in compliance with the License.
6# You may obtain a copy of the License at
7#
8# http://www.apache.org/licenses/LICENSE-2.0
9#
10# Unless required by applicable law or agreed to in writing, software
11# distributed under the License is distributed on an "AS IS" BASIS,
12# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13# See the License for the specific language governing permissions and
14# limitations under the License.
15#
16import json
17import logging as std_logging
18import pickle
19import warnings
20from typing import Callable, Dict, Optional, Sequence, Tuple, Union
22from google.api_core import grpc_helpers
23from google.api_core import gapic_v1
24import google.auth # type: ignore
25from google.auth import credentials as ga_credentials # type: ignore
26from google.auth.transport.grpc import SslCredentials # type: ignore
27from google.protobuf.json_format import MessageToJson
28import google.protobuf.message
30import grpc # type: ignore
31import proto # type: ignore
33from google.cloud.logging_v2.types import logging
34from google.longrunning import operations_pb2 # type: ignore
35from google.protobuf import empty_pb2 # type: ignore
36from .base import LoggingServiceV2Transport, DEFAULT_CLIENT_INFO
38try:
39 from google.api_core import client_logging # type: ignore
41 CLIENT_LOGGING_SUPPORTED = True # pragma: NO COVER
42except ImportError: # pragma: NO COVER
43 CLIENT_LOGGING_SUPPORTED = False
45_LOGGER = std_logging.getLogger(__name__)
48class _LoggingClientInterceptor(grpc.UnaryUnaryClientInterceptor): # pragma: NO COVER
49 def intercept_unary_unary(self, continuation, client_call_details, request):
50 logging_enabled = CLIENT_LOGGING_SUPPORTED and _LOGGER.isEnabledFor(
51 std_logging.DEBUG
52 )
53 if logging_enabled: # pragma: NO COVER
54 request_metadata = client_call_details.metadata
55 if isinstance(request, proto.Message):
56 request_payload = type(request).to_json(request)
57 elif isinstance(request, google.protobuf.message.Message):
58 request_payload = MessageToJson(request)
59 else:
60 request_payload = f"{type(request).__name__}: {pickle.dumps(request)}"
62 request_metadata = {
63 key: value.decode("utf-8") if isinstance(value, bytes) else value
64 for key, value in request_metadata
65 }
66 grpc_request = {
67 "payload": request_payload,
68 "requestMethod": "grpc",
69 "metadata": dict(request_metadata),
70 }
71 _LOGGER.debug(
72 f"Sending request for {client_call_details.method}",
73 extra={
74 "serviceName": "google.logging.v2.LoggingServiceV2",
75 "rpcName": str(client_call_details.method),
76 "request": grpc_request,
77 "metadata": grpc_request["metadata"],
78 },
79 )
80 response = continuation(client_call_details, request)
81 if logging_enabled: # pragma: NO COVER
82 response_metadata = response.trailing_metadata()
83 # Convert gRPC metadata `<class 'grpc.aio._metadata.Metadata'>` to list of tuples
84 metadata = (
85 dict([(k, str(v)) for k, v in response_metadata])
86 if response_metadata
87 else None
88 )
89 result = response.result()
90 if isinstance(result, proto.Message):
91 response_payload = type(result).to_json(result)
92 elif isinstance(result, google.protobuf.message.Message):
93 response_payload = MessageToJson(result)
94 else:
95 response_payload = f"{type(result).__name__}: {pickle.dumps(result)}"
96 grpc_response = {
97 "payload": response_payload,
98 "metadata": metadata,
99 "status": "OK",
100 }
101 _LOGGER.debug(
102 f"Received response for {client_call_details.method}.",
103 extra={
104 "serviceName": "google.logging.v2.LoggingServiceV2",
105 "rpcName": client_call_details.method,
106 "response": grpc_response,
107 "metadata": grpc_response["metadata"],
108 },
109 )
110 return response
113class LoggingServiceV2GrpcTransport(LoggingServiceV2Transport):
114 """gRPC backend transport for LoggingServiceV2.
116 Service for ingesting and querying logs.
118 This class defines the same methods as the primary client, so the
119 primary client can load the underlying transport implementation
120 and call it.
122 It sends protocol buffers over the wire using gRPC (which is built on
123 top of HTTP/2); the ``grpcio`` package must be installed.
124 """
126 _stubs: Dict[str, Callable]
128 def __init__(
129 self,
130 *,
131 host: str = "logging.googleapis.com",
132 credentials: Optional[ga_credentials.Credentials] = None,
133 credentials_file: Optional[str] = None,
134 scopes: Optional[Sequence[str]] = None,
135 channel: Optional[Union[grpc.Channel, Callable[..., grpc.Channel]]] = None,
136 api_mtls_endpoint: Optional[str] = None,
137 client_cert_source: Optional[Callable[[], Tuple[bytes, bytes]]] = None,
138 ssl_channel_credentials: Optional[grpc.ChannelCredentials] = None,
139 client_cert_source_for_mtls: Optional[Callable[[], Tuple[bytes, bytes]]] = None,
140 quota_project_id: Optional[str] = None,
141 client_info: gapic_v1.client_info.ClientInfo = DEFAULT_CLIENT_INFO,
142 always_use_jwt_access: Optional[bool] = False,
143 api_audience: Optional[str] = None,
144 ) -> None:
145 """Instantiate the transport.
147 Args:
148 host (Optional[str]):
149 The hostname to connect to (default: 'logging.googleapis.com').
150 credentials (Optional[google.auth.credentials.Credentials]): The
151 authorization credentials to attach to requests. These
152 credentials identify the application to the service; if none
153 are specified, the client will attempt to ascertain the
154 credentials from the environment.
155 This argument is ignored if a ``channel`` instance is provided.
156 credentials_file (Optional[str]): A file with credentials that can
157 be loaded with :func:`google.auth.load_credentials_from_file`.
158 This argument is ignored if a ``channel`` instance is provided.
159 scopes (Optional(Sequence[str])): A list of scopes. This argument is
160 ignored if a ``channel`` instance is provided.
161 channel (Optional[Union[grpc.Channel, Callable[..., grpc.Channel]]]):
162 A ``Channel`` instance through which to make calls, or a Callable
163 that constructs and returns one. If set to None, ``self.create_channel``
164 is used to create the channel. If a Callable is given, it will be called
165 with the same arguments as used in ``self.create_channel``.
166 api_mtls_endpoint (Optional[str]): Deprecated. The mutual TLS endpoint.
167 If provided, it overrides the ``host`` argument and tries to create
168 a mutual TLS channel with client SSL credentials from
169 ``client_cert_source`` or application default SSL credentials.
170 client_cert_source (Optional[Callable[[], Tuple[bytes, bytes]]]):
171 Deprecated. A callback to provide client SSL certificate bytes and
172 private key bytes, both in PEM format. It is ignored if
173 ``api_mtls_endpoint`` is None.
174 ssl_channel_credentials (grpc.ChannelCredentials): SSL credentials
175 for the grpc channel. It is ignored if a ``channel`` instance is provided.
176 client_cert_source_for_mtls (Optional[Callable[[], Tuple[bytes, bytes]]]):
177 A callback to provide client certificate bytes and private key bytes,
178 both in PEM format. It is used to configure a mutual TLS channel. It is
179 ignored if a ``channel`` instance or ``ssl_channel_credentials`` is provided.
180 quota_project_id (Optional[str]): An optional project to use for billing
181 and quota.
182 client_info (google.api_core.gapic_v1.client_info.ClientInfo):
183 The client info used to send a user-agent string along with
184 API requests. If ``None``, then default info will be used.
185 Generally, you only need to set this if you're developing
186 your own client library.
187 always_use_jwt_access (Optional[bool]): Whether self signed JWT should
188 be used for service account credentials.
190 Raises:
191 google.auth.exceptions.MutualTLSChannelError: If mutual TLS transport
192 creation failed for any reason.
193 google.api_core.exceptions.DuplicateCredentialArgs: If both ``credentials``
194 and ``credentials_file`` are passed.
195 """
196 self._grpc_channel = None
197 self._ssl_channel_credentials = ssl_channel_credentials
198 self._stubs: Dict[str, Callable] = {}
200 if api_mtls_endpoint:
201 warnings.warn("api_mtls_endpoint is deprecated", DeprecationWarning)
202 if client_cert_source:
203 warnings.warn("client_cert_source is deprecated", DeprecationWarning)
205 if isinstance(channel, grpc.Channel):
206 # Ignore credentials if a channel was passed.
207 credentials = None
208 self._ignore_credentials = True
209 # If a channel was explicitly provided, set it.
210 self._grpc_channel = channel
211 self._ssl_channel_credentials = None
213 else:
214 if api_mtls_endpoint:
215 host = api_mtls_endpoint
217 # Create SSL credentials with client_cert_source or application
218 # default SSL credentials.
219 if client_cert_source:
220 cert, key = client_cert_source()
221 self._ssl_channel_credentials = grpc.ssl_channel_credentials(
222 certificate_chain=cert, private_key=key
223 )
224 else:
225 self._ssl_channel_credentials = SslCredentials().ssl_credentials
227 else:
228 if client_cert_source_for_mtls and not ssl_channel_credentials:
229 cert, key = client_cert_source_for_mtls()
230 self._ssl_channel_credentials = grpc.ssl_channel_credentials(
231 certificate_chain=cert, private_key=key
232 )
234 # The base transport sets the host, credentials and scopes
235 super().__init__(
236 host=host,
237 credentials=credentials,
238 credentials_file=credentials_file,
239 scopes=scopes,
240 quota_project_id=quota_project_id,
241 client_info=client_info,
242 always_use_jwt_access=always_use_jwt_access,
243 api_audience=api_audience,
244 )
246 if not self._grpc_channel:
247 # initialize with the provided callable or the default channel
248 channel_init = channel or type(self).create_channel
249 self._grpc_channel = channel_init(
250 self._host,
251 # use the credentials which are saved
252 credentials=self._credentials,
253 # Set ``credentials_file`` to ``None`` here as
254 # the credentials that we saved earlier should be used.
255 credentials_file=None,
256 scopes=self._scopes,
257 ssl_credentials=self._ssl_channel_credentials,
258 quota_project_id=quota_project_id,
259 options=[
260 ("grpc.max_send_message_length", -1),
261 ("grpc.max_receive_message_length", -1),
262 ],
263 )
265 self._interceptor = _LoggingClientInterceptor()
266 self._logged_channel = grpc.intercept_channel(
267 self._grpc_channel, self._interceptor
268 )
270 # Wrap messages. This must be done after self._logged_channel exists
271 self._prep_wrapped_messages(client_info)
273 @classmethod
274 def create_channel(
275 cls,
276 host: str = "logging.googleapis.com",
277 credentials: Optional[ga_credentials.Credentials] = None,
278 credentials_file: Optional[str] = None,
279 scopes: Optional[Sequence[str]] = None,
280 quota_project_id: Optional[str] = None,
281 **kwargs,
282 ) -> grpc.Channel:
283 """Create and return a gRPC channel object.
284 Args:
285 host (Optional[str]): The host for the channel to use.
286 credentials (Optional[~.Credentials]): The
287 authorization credentials to attach to requests. These
288 credentials identify this application to the service. If
289 none are specified, the client will attempt to ascertain
290 the credentials from the environment.
291 credentials_file (Optional[str]): A file with credentials that can
292 be loaded with :func:`google.auth.load_credentials_from_file`.
293 This argument is mutually exclusive with credentials.
294 scopes (Optional[Sequence[str]]): A optional list of scopes needed for this
295 service. These are only used when credentials are not specified and
296 are passed to :func:`google.auth.default`.
297 quota_project_id (Optional[str]): An optional project to use for billing
298 and quota.
299 kwargs (Optional[dict]): Keyword arguments, which are passed to the
300 channel creation.
301 Returns:
302 grpc.Channel: A gRPC channel object.
304 Raises:
305 google.api_core.exceptions.DuplicateCredentialArgs: If both ``credentials``
306 and ``credentials_file`` are passed.
307 """
309 return grpc_helpers.create_channel(
310 host,
311 credentials=credentials,
312 credentials_file=credentials_file,
313 quota_project_id=quota_project_id,
314 default_scopes=cls.AUTH_SCOPES,
315 scopes=scopes,
316 default_host=cls.DEFAULT_HOST,
317 **kwargs,
318 )
320 @property
321 def grpc_channel(self) -> grpc.Channel:
322 """Return the channel designed to connect to this service."""
323 return self._grpc_channel
325 @property
326 def delete_log(self) -> Callable[[logging.DeleteLogRequest], empty_pb2.Empty]:
327 r"""Return a callable for the delete log method over gRPC.
329 Deletes all the log entries in a log for the \_Default Log
330 Bucket. The log reappears if it receives new entries. Log
331 entries written shortly before the delete operation might not be
332 deleted. Entries received after the delete operation with a
333 timestamp before the operation will be deleted.
335 Returns:
336 Callable[[~.DeleteLogRequest],
337 ~.Empty]:
338 A function that, when called, will call the underlying RPC
339 on the server.
340 """
341 # Generate a "stub function" on-the-fly which will actually make
342 # the request.
343 # gRPC handles serialization and deserialization, so we just need
344 # to pass in the functions for each.
345 if "delete_log" not in self._stubs:
346 self._stubs["delete_log"] = self._logged_channel.unary_unary(
347 "/google.logging.v2.LoggingServiceV2/DeleteLog",
348 request_serializer=logging.DeleteLogRequest.serialize,
349 response_deserializer=empty_pb2.Empty.FromString,
350 )
351 return self._stubs["delete_log"]
353 @property
354 def write_log_entries(
355 self,
356 ) -> Callable[[logging.WriteLogEntriesRequest], logging.WriteLogEntriesResponse]:
357 r"""Return a callable for the write log entries method over gRPC.
359 Writes log entries to Logging. This API method is the
360 only way to send log entries to Logging. This method is
361 used, directly or indirectly, by the Logging agent
362 (fluentd) and all logging libraries configured to use
363 Logging. A single request may contain log entries for a
364 maximum of 1000 different resources (projects,
365 organizations, billing accounts or folders)
367 Returns:
368 Callable[[~.WriteLogEntriesRequest],
369 ~.WriteLogEntriesResponse]:
370 A function that, when called, will call the underlying RPC
371 on the server.
372 """
373 # Generate a "stub function" on-the-fly which will actually make
374 # the request.
375 # gRPC handles serialization and deserialization, so we just need
376 # to pass in the functions for each.
377 if "write_log_entries" not in self._stubs:
378 self._stubs["write_log_entries"] = self._logged_channel.unary_unary(
379 "/google.logging.v2.LoggingServiceV2/WriteLogEntries",
380 request_serializer=logging.WriteLogEntriesRequest.serialize,
381 response_deserializer=logging.WriteLogEntriesResponse.deserialize,
382 )
383 return self._stubs["write_log_entries"]
385 @property
386 def list_log_entries(
387 self,
388 ) -> Callable[[logging.ListLogEntriesRequest], logging.ListLogEntriesResponse]:
389 r"""Return a callable for the list log entries method over gRPC.
391 Lists log entries. Use this method to retrieve log entries that
392 originated from a project/folder/organization/billing account.
393 For ways to export log entries, see `Exporting
394 Logs <https://cloud.google.com/logging/docs/export>`__.
396 Returns:
397 Callable[[~.ListLogEntriesRequest],
398 ~.ListLogEntriesResponse]:
399 A function that, when called, will call the underlying RPC
400 on the server.
401 """
402 # Generate a "stub function" on-the-fly which will actually make
403 # the request.
404 # gRPC handles serialization and deserialization, so we just need
405 # to pass in the functions for each.
406 if "list_log_entries" not in self._stubs:
407 self._stubs["list_log_entries"] = self._logged_channel.unary_unary(
408 "/google.logging.v2.LoggingServiceV2/ListLogEntries",
409 request_serializer=logging.ListLogEntriesRequest.serialize,
410 response_deserializer=logging.ListLogEntriesResponse.deserialize,
411 )
412 return self._stubs["list_log_entries"]
414 @property
415 def list_monitored_resource_descriptors(
416 self,
417 ) -> Callable[
418 [logging.ListMonitoredResourceDescriptorsRequest],
419 logging.ListMonitoredResourceDescriptorsResponse,
420 ]:
421 r"""Return a callable for the list monitored resource
422 descriptors method over gRPC.
424 Lists the descriptors for monitored resource types
425 used by Logging.
427 Returns:
428 Callable[[~.ListMonitoredResourceDescriptorsRequest],
429 ~.ListMonitoredResourceDescriptorsResponse]:
430 A function that, when called, will call the underlying RPC
431 on the server.
432 """
433 # Generate a "stub function" on-the-fly which will actually make
434 # the request.
435 # gRPC handles serialization and deserialization, so we just need
436 # to pass in the functions for each.
437 if "list_monitored_resource_descriptors" not in self._stubs:
438 self._stubs[
439 "list_monitored_resource_descriptors"
440 ] = self._logged_channel.unary_unary(
441 "/google.logging.v2.LoggingServiceV2/ListMonitoredResourceDescriptors",
442 request_serializer=logging.ListMonitoredResourceDescriptorsRequest.serialize,
443 response_deserializer=logging.ListMonitoredResourceDescriptorsResponse.deserialize,
444 )
445 return self._stubs["list_monitored_resource_descriptors"]
447 @property
448 def list_logs(
449 self,
450 ) -> Callable[[logging.ListLogsRequest], logging.ListLogsResponse]:
451 r"""Return a callable for the list logs method over gRPC.
453 Lists the logs in projects, organizations, folders,
454 or billing accounts. Only logs that have entries are
455 listed.
457 Returns:
458 Callable[[~.ListLogsRequest],
459 ~.ListLogsResponse]:
460 A function that, when called, will call the underlying RPC
461 on the server.
462 """
463 # Generate a "stub function" on-the-fly which will actually make
464 # the request.
465 # gRPC handles serialization and deserialization, so we just need
466 # to pass in the functions for each.
467 if "list_logs" not in self._stubs:
468 self._stubs["list_logs"] = self._logged_channel.unary_unary(
469 "/google.logging.v2.LoggingServiceV2/ListLogs",
470 request_serializer=logging.ListLogsRequest.serialize,
471 response_deserializer=logging.ListLogsResponse.deserialize,
472 )
473 return self._stubs["list_logs"]
475 @property
476 def tail_log_entries(
477 self,
478 ) -> Callable[[logging.TailLogEntriesRequest], logging.TailLogEntriesResponse]:
479 r"""Return a callable for the tail log entries method over gRPC.
481 Streaming read of log entries as they are ingested.
482 Until the stream is terminated, it will continue reading
483 logs.
485 Returns:
486 Callable[[~.TailLogEntriesRequest],
487 ~.TailLogEntriesResponse]:
488 A function that, when called, will call the underlying RPC
489 on the server.
490 """
491 # Generate a "stub function" on-the-fly which will actually make
492 # the request.
493 # gRPC handles serialization and deserialization, so we just need
494 # to pass in the functions for each.
495 if "tail_log_entries" not in self._stubs:
496 self._stubs["tail_log_entries"] = self._logged_channel.stream_stream(
497 "/google.logging.v2.LoggingServiceV2/TailLogEntries",
498 request_serializer=logging.TailLogEntriesRequest.serialize,
499 response_deserializer=logging.TailLogEntriesResponse.deserialize,
500 )
501 return self._stubs["tail_log_entries"]
503 def close(self):
504 self._logged_channel.close()
506 @property
507 def cancel_operation(
508 self,
509 ) -> Callable[[operations_pb2.CancelOperationRequest], None]:
510 r"""Return a callable for the cancel_operation method over gRPC."""
511 # Generate a "stub function" on-the-fly which will actually make
512 # the request.
513 # gRPC handles serialization and deserialization, so we just need
514 # to pass in the functions for each.
515 if "cancel_operation" not in self._stubs:
516 self._stubs["cancel_operation"] = self._logged_channel.unary_unary(
517 "/google.longrunning.Operations/CancelOperation",
518 request_serializer=operations_pb2.CancelOperationRequest.SerializeToString,
519 response_deserializer=None,
520 )
521 return self._stubs["cancel_operation"]
523 @property
524 def get_operation(
525 self,
526 ) -> Callable[[operations_pb2.GetOperationRequest], operations_pb2.Operation]:
527 r"""Return a callable for the get_operation method over gRPC."""
528 # Generate a "stub function" on-the-fly which will actually make
529 # the request.
530 # gRPC handles serialization and deserialization, so we just need
531 # to pass in the functions for each.
532 if "get_operation" not in self._stubs:
533 self._stubs["get_operation"] = self._logged_channel.unary_unary(
534 "/google.longrunning.Operations/GetOperation",
535 request_serializer=operations_pb2.GetOperationRequest.SerializeToString,
536 response_deserializer=operations_pb2.Operation.FromString,
537 )
538 return self._stubs["get_operation"]
540 @property
541 def list_operations(
542 self,
543 ) -> Callable[
544 [operations_pb2.ListOperationsRequest], operations_pb2.ListOperationsResponse
545 ]:
546 r"""Return a callable for the list_operations method over gRPC."""
547 # Generate a "stub function" on-the-fly which will actually make
548 # the request.
549 # gRPC handles serialization and deserialization, so we just need
550 # to pass in the functions for each.
551 if "list_operations" not in self._stubs:
552 self._stubs["list_operations"] = self._logged_channel.unary_unary(
553 "/google.longrunning.Operations/ListOperations",
554 request_serializer=operations_pb2.ListOperationsRequest.SerializeToString,
555 response_deserializer=operations_pb2.ListOperationsResponse.FromString,
556 )
557 return self._stubs["list_operations"]
559 @property
560 def kind(self) -> str:
561 return "grpc"
564__all__ = ("LoggingServiceV2GrpcTransport",)