feat: Add Cloud Trace v2 retry defaults for BatchWriteSpans (#294)

* feat: Add Cloud Trace v2 retry defaults for BatchWriteSpans

PiperOrigin-RevId: 504068544

Source-Link: googleapis/googleapis@685d359

Source-Link: https://github.com/googleapis/googleapis-gen/commit/43aa9dacfc417b625ad8be1bed2a9fc36c277db6
Copy-Tag: eyJwIjoiLmdpdGh1Yi8uT3dsQm90LnlhbWwiLCJoIjoiNDNhYTlkYWNmYzQxN2I2MjVhZDhiZTFiZWQyYTlmYzM2YzI3N2RiNiJ9

* 🦉 Updates from OwlBot post-processor

See https://github.com/googleapis/repo-automation-bots/blob/main/packages/owl-bot/README.md

Co-authored-by: Owl Bot <gcf-owl-bot[bot]@users.noreply.github.com>

Author: gcf-owl-bot[bot]

google/cloud/trace_v2/services/trace_service/async_client.py

@@ -54,12 +54,13 @@
 
 
 class TraceServiceAsyncClient:
-    """This file describes an API for collecting and viewing traces
-    and spans within a trace.  A Trace is a collection of spans
-    corresponding to a single operation or set of operations for an
-    application. A span is an individual timed event which forms a
-    node of the trace tree. A single trace may contain span(s) from
-    multiple services.
+    """Service for collecting and viewing traces and spans within a
+    trace.
+    A trace is a collection of spans corresponding to a single
+    operation or a set of operations in an application.
+    A span is an individual timed event which forms a node of the
+    trace tree. A single trace can contain spans from multiple
+    services.
     """
 
     _client: TraceServiceClient
@@ -229,8 +230,8 @@ async def batch_write_spans(
         timeout: Union[float, object] = gapic_v1.method.DEFAULT,
         metadata: Sequence[Tuple[str, str]] = (),
     ) -> None:
-        r"""Sends new spans to new or existing traces. You cannot
-        update existing spans.
+        r"""Batch writes new spans to new or existing traces. You
+        cannot update existing spans.
 
         .. code-block:: python
 
@@ -274,7 +275,8 @@ async def sample_batch_write_spans():
             spans (:class:`MutableSequence[google.cloud.trace_v2.types.Span]`):
                 Required. A list of new spans. The
                 span names must not match existing
-                spans, or the results are undefined.
+                spans, otherwise the results are
+                undefined.
 
                 This corresponds to the ``spans`` field
                 on the ``request`` instance; if ``request`` is provided, this
@@ -308,6 +310,16 @@ async def sample_batch_write_spans():
         # and friendly error handling.
         rpc = gapic_v1.method_async.wrap_method(
             self._client._transport.batch_write_spans,
+            default_retry=retries.Retry(
+                initial=0.1,
+                maximum=30.0,
+                multiplier=2,
+                predicate=retries.if_exception_type(
+                    core_exceptions.DeadlineExceeded,
+                    core_exceptions.ServiceUnavailable,
+                ),
+                deadline=120.0,
+            ),
             default_timeout=120.0,
             client_info=DEFAULT_CLIENT_INFO,
         )
@@ -369,10 +381,11 @@ async def sample_create_span():
                 within a trace. Spans can be nested to form a trace
                 tree. Often, a trace contains a root span that describes
                 the end-to-end latency, and one or more subspans for its
-                sub-operations. A trace can also contain multiple root
-                spans, or none at all. Spans do not need to be
-                contiguous—there may be gaps or overlaps between
-                spans in a trace.
+                sub-operations.
+
+                A trace can also contain multiple root spans, or none at
+                all. Spans do not need to be contiguous—there
+                might be gaps or overlaps between spans in a trace.
             retry (google.api_core.retry.Retry): Designation of what errors, if any,
                 should be retried.
             timeout (float): The timeout for this request.
@@ -386,11 +399,13 @@ async def sample_create_span():
                 form a trace tree. Often, a trace
                 contains a root span that describes the
                 end-to-end latency, and one or more
-                subspans for its sub-operations. A trace
-                can also contain multiple root spans, or
-                none at all. Spans do not need to be
-                contiguous—there may be gaps or
-                overlaps between spans in a trace.
+                subspans for its sub-operations.
+
+                A trace can also contain multiple root
+                spans, or none at all. Spans do not need
+                to be contiguous—there might be
+                gaps or overlaps between spans in a
+                trace.
 
         """
         # Create or coerce a protobuf request object.

google/cloud/trace_v2/services/trace_service/client.py

@@ -92,12 +92,13 @@ def get_transport_class(
 
 
 class TraceServiceClient(metaclass=TraceServiceClientMeta):
-    """This file describes an API for collecting and viewing traces
-    and spans within a trace.  A Trace is a collection of spans
-    corresponding to a single operation or set of operations for an
-    application. A span is an individual timed event which forms a
-    node of the trace tree. A single trace may contain span(s) from
-    multiple services.
+    """Service for collecting and viewing traces and spans within a
+    trace.
+    A trace is a collection of spans corresponding to a single
+    operation or a set of operations in an application.
+    A span is an individual timed event which forms a node of the
+    trace tree. A single trace can contain spans from multiple
+    services.
     """
 
     @staticmethod
@@ -458,8 +459,8 @@ def batch_write_spans(
         timeout: Union[float, object] = gapic_v1.method.DEFAULT,
         metadata: Sequence[Tuple[str, str]] = (),
     ) -> None:
-        r"""Sends new spans to new or existing traces. You cannot
-        update existing spans.
+        r"""Batch writes new spans to new or existing traces. You
+        cannot update existing spans.
 
         .. code-block:: python
 
@@ -503,7 +504,8 @@ def sample_batch_write_spans():
             spans (MutableSequence[google.cloud.trace_v2.types.Span]):
                 Required. A list of new spans. The
                 span names must not match existing
-                spans, or the results are undefined.
+                spans, otherwise the results are
+                undefined.
 
                 This corresponds to the ``spans`` field
                 on the ``request`` instance; if ``request`` is provided, this
@@ -598,10 +600,11 @@ def sample_create_span():
                 within a trace. Spans can be nested to form a trace
                 tree. Often, a trace contains a root span that describes
                 the end-to-end latency, and one or more subspans for its
-                sub-operations. A trace can also contain multiple root
-                spans, or none at all. Spans do not need to be
-                contiguous—there may be gaps or overlaps between
-                spans in a trace.
+                sub-operations.
+
+                A trace can also contain multiple root spans, or none at
+                all. Spans do not need to be contiguous—there
+                might be gaps or overlaps between spans in a trace.
             retry (google.api_core.retry.Retry): Designation of what errors, if any,
                 should be retried.
             timeout (float): The timeout for this request.
@@ -615,11 +618,13 @@ def sample_create_span():
                 form a trace tree. Often, a trace
                 contains a root span that describes the
                 end-to-end latency, and one or more
-                subspans for its sub-operations. A trace
-                can also contain multiple root spans, or
-                none at all. Spans do not need to be
-                contiguous—there may be gaps or
-                overlaps between spans in a trace.
+                subspans for its sub-operations.
+
+                A trace can also contain multiple root
+                spans, or none at all. Spans do not need
+                to be contiguous—there might be
+                gaps or overlaps between spans in a
+                trace.
 
         """
         # Create or coerce a protobuf request object.

google/cloud/trace_v2/services/trace_service/transports/base.py

@@ -128,6 +128,16 @@ def _prep_wrapped_messages(self, client_info):
         self._wrapped_methods = {
             self.batch_write_spans: gapic_v1.method.wrap_method(
                 self.batch_write_spans,
+                default_retry=retries.Retry(
+                    initial=0.1,
+                    maximum=30.0,
+                    multiplier=2,
+                    predicate=retries.if_exception_type(
+                        core_exceptions.DeadlineExceeded,
+                        core_exceptions.ServiceUnavailable,
+                    ),
+                    deadline=120.0,
+                ),
                 default_timeout=120.0,
                 client_info=client_info,
             ),

google/cloud/trace_v2/services/trace_service/transports/grpc.py

@@ -31,12 +31,13 @@
 class TraceServiceGrpcTransport(TraceServiceTransport):
     """gRPC backend transport for TraceService.
 
-    This file describes an API for collecting and viewing traces
-    and spans within a trace.  A Trace is a collection of spans
-    corresponding to a single operation or set of operations for an
-    application. A span is an individual timed event which forms a
-    node of the trace tree. A single trace may contain span(s) from
-    multiple services.
+    Service for collecting and viewing traces and spans within a
+    trace.
+    A trace is a collection of spans corresponding to a single
+    operation or a set of operations in an application.
+    A span is an individual timed event which forms a node of the
+    trace tree. A single trace can contain spans from multiple
+    services.
 
     This class defines the same methods as the primary client, so the
     primary client can load the underlying transport implementation
@@ -240,8 +241,8 @@ def batch_write_spans(
     ) -> Callable[[tracing.BatchWriteSpansRequest], empty_pb2.Empty]:
         r"""Return a callable for the batch write spans method over gRPC.
 
-        Sends new spans to new or existing traces. You cannot
-        update existing spans.
+        Batch writes new spans to new or existing traces. You
+        cannot update existing spans.
 
         Returns:
             Callable[[~.BatchWriteSpansRequest],

google/cloud/trace_v2/services/trace_service/transports/grpc_asyncio.py

@@ -32,12 +32,13 @@
 class TraceServiceGrpcAsyncIOTransport(TraceServiceTransport):
     """gRPC AsyncIO backend transport for TraceService.
 
-    This file describes an API for collecting and viewing traces
-    and spans within a trace.  A Trace is a collection of spans
-    corresponding to a single operation or set of operations for an
-    application. A span is an individual timed event which forms a
-    node of the trace tree. A single trace may contain span(s) from
-    multiple services.
+    Service for collecting and viewing traces and spans within a
+    trace.
+    A trace is a collection of spans corresponding to a single
+    operation or a set of operations in an application.
+    A span is an individual timed event which forms a node of the
+    trace tree. A single trace can contain spans from multiple
+    services.
 
     This class defines the same methods as the primary client, so the
     primary client can load the underlying transport implementation
@@ -243,8 +244,8 @@ def batch_write_spans(
     ) -> Callable[[tracing.BatchWriteSpansRequest], Awaitable[empty_pb2.Empty]]:
         r"""Return a callable for the batch write spans method over gRPC.
 
-        Sends new spans to new or existing traces. You cannot
-        update existing spans.
+        Batch writes new spans to new or existing traces. You
+        cannot update existing spans.
 
         Returns:
             Callable[[~.BatchWriteSpansRequest],

google/cloud/trace_v2/types/trace.py

@@ -36,37 +36,36 @@ class Span(proto.Message):
     r"""A span represents a single operation within a trace. Spans
     can be nested to form a trace tree. Often, a trace contains a
     root span that describes the end-to-end latency, and one or more
-    subspans for its sub-operations. A trace can also contain
-    multiple root spans, or none at all. Spans do not need to be
-    contiguous—there may be gaps or overlaps between spans in
-    a trace.
+    subspans for its sub-operations.
+
+    A trace can also contain multiple root spans, or none at all.
+    Spans do not need to be contiguous—there might be gaps or
+    overlaps between spans in a trace.
 
     Attributes:
         name (str):
             Required. The resource name of the span in the following
             format:
 
-            ::
-
-                projects/[PROJECT_ID]/traces/[TRACE_ID]/spans/[SPAN_ID]
+            -  ``projects/[PROJECT_ID]/traces/[TRACE_ID]/spans/[SPAN_ID]``
 
-            [TRACE_ID] is a unique identifier for a trace within a
+            ``[TRACE_ID]`` is a unique identifier for a trace within a
             project; it is a 32-character hexadecimal encoding of a
-            16-byte array.
+            16-byte array. It should not be zero.
 
-            [SPAN_ID] is a unique identifier for a span within a trace;
-            it is a 16-character hexadecimal encoding of an 8-byte
-            array.
+            ``[SPAN_ID]`` is a unique identifier for a span within a
+            trace; it is a 16-character hexadecimal encoding of an
+            8-byte array. It should not be zero. .
         span_id (str):
-            Required. The [SPAN_ID] portion of the span's resource name.
+            Required. The ``[SPAN_ID]`` portion of the span's resource
+            name.
         parent_span_id (str):
-            The [SPAN_ID] of this span's parent span. If this is a root
-            span, then this field must be empty.
+            The ``[SPAN_ID]`` of this span's parent span. If this is a
+            root span, then this field must be empty.
         display_name (google.cloud.trace_v2.types.TruncatableString):
             Required. A description of the span's
-            operation (up to 128 bytes). Stackdriver Trace
-            displays the description in the Google Cloud
-            Platform Console.
+            operation (up to 128 bytes). Cloud Trace
+            displays the description in the Cloud console.
             For example, the display name can be a qualified
             method name or a file name and a line number
             where the operation is called. A best practice
@@ -103,9 +102,9 @@ class Span(proto.Message):
         same_process_as_parent_span (google.protobuf.wrappers_pb2.BoolValue):
             Optional. Set this parameter to indicate
             whether this span is in the same process as its
-            parent. If you do not set this parameter,
-            Stackdriver Trace is unable to take advantage of
-            this helpful information.
+            parent. If you do not set this parameter, Trace
+            is unable to take advantage of this helpful
+            information.
         child_span_count (google.protobuf.wrappers_pb2.Int32Value):
             Optional. The number of child spans that were
             generated while this span was active. If set,
@@ -160,13 +159,13 @@ class SpanKind(proto.Enum):
         CONSUMER = 5
 
     class Attributes(proto.Message):
-        r"""A set of attributes, each in the format ``[KEY]:[VALUE]``.
+        r"""A set of attributes as key-value pairs.
 
         Attributes:
             attribute_map (MutableMapping[str, google.cloud.trace_v2.types.AttributeValue]):
-                The set of attributes. Each attribute's key can be up to 128
+                A set of attributes. Each attribute's key can be up to 128
                 bytes long. The value can be a string up to 256 bytes, a
-                signed 64-bit integer, or the Boolean values ``true`` and
+                signed 64-bit integer, or the boolean values ``true`` or
                 ``false``. For example:
 
                 ::
@@ -250,17 +249,16 @@ class MessageEvent(proto.Message):
                     Type of MessageEvent. Indicates whether the
                     message was sent or received.
                 id (int):
-                    An identifier for the MessageEvent's message
-                    that can be used to match SENT and RECEIVED
-                    MessageEvents. It is recommended to be unique
-                    within a Span.
+                    An identifier for the MessageEvent's message that can be
+                    used to match ``SENT`` and ``RECEIVED`` MessageEvents.
                 uncompressed_size_bytes (int):
                     The number of uncompressed bytes sent or
                     received.
                 compressed_size_bytes (int):
                     The number of compressed bytes sent or
-                    received. If missing assumed to be the same size
-                    as uncompressed.
+                    received. If missing, the compressed size is
+                    assumed to be the same size as the uncompressed
+                    size.
             """
 
             class Type(proto.Enum):
@@ -355,15 +353,15 @@ class Link(proto.Message):
 
         Attributes:
             trace_id (str):
-                The [TRACE_ID] for a trace within a project.
+                The ``[TRACE_ID]`` for a trace within a project.
             span_id (str):
-                The [SPAN_ID] for a span within a trace.
+                The ``[SPAN_ID]`` for a span within a trace.
             type (google.cloud.trace_v2.types.Span.Link.Type):
                 The relationship of the current span relative
                 to the linked span.
             attributes (google.cloud.trace_v2.types.Span.Attributes):
-                A set of attributes on the link. You have
-                have up to  32 attributes per link.
+                A set of attributes on the link. Up to 32
+                attributes can be specified per link.
         """
 
         class Type(proto.Enum):
@@ -496,7 +494,7 @@ class Links(proto.Message):
 
 
 class AttributeValue(proto.Message):
-    r"""The allowed types for [VALUE] in a ``[KEY]:[VALUE]`` attribute.
+    r"""The allowed types for ``[VALUE]`` in a ``[KEY]:[VALUE]`` attribute.
 
     This message has `oneof`_ fields (mutually exclusive fields).
     For each oneof, at most one member field can be set at the same time.
@@ -567,7 +565,8 @@ class StackFrame(proto.Message):
                 in this frame (up to 1024 bytes).
             original_function_name (google.cloud.trace_v2.types.TruncatableString):
                 An un-mangled function name, if ``function_name`` is
-                `mangled <http://www.avabodh.com/cxxin/namemangling.html>`__.
+                mangled. To get information about name mangling, run `this
+                search <https://www.google.com/search?q=cxx+name+mangling>`__.
                 The name can be fully-qualified (up to 1024 bytes).
             file_name (google.cloud.trace_v2.types.TruncatableString):
                 The name of the source file where the