fix(trace)!: remove span_path resource helper method from v2; modif…

…y retry configs; standardize usage of 'optional' and 'required' for args in docstrings; add 2.7 deprecation warning (via synth) (#10075)

trace/docs/conf.py

@@ -164,7 +164,7 @@
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,
 # so a file named "default.css" will overwrite the builtin "default.css".
-# html_static_path = []
+html_static_path = ["_static"]
 
 # Add any extra paths that contain custom files (such as robots.txt or
 # .htaccess) here, relative to this directory. These files are copied

trace/google/cloud/trace_v1/__init__.py

@@ -16,12 +16,23 @@
 
 
 from __future__ import absolute_import
+import sys
+import warnings
 
 from google.cloud.trace_v1 import types
 from google.cloud.trace_v1.gapic import enums
 from google.cloud.trace_v1.gapic import trace_service_client
 
 
+if sys.version_info[:2] == (2, 7):
+    message = (
+        "A future version of this library will drop support for Python 2.7."
+        "More details about Python 2 support for Google Cloud Client Libraries"
+        "can be found at https://cloud.google.com/python/docs/python2-sunset/"
+    )
+    warnings.warn(message, DeprecationWarning)
+
+
 class TraceServiceClient(trace_service_client.TraceServiceClient):
     __doc__ = trace_service_client.TraceServiceClient.__doc__
     enums = enums

trace/google/cloud/trace_v1/gapic/trace_service_client_config.py

@@ -8,16 +8,16 @@
             "retry_params": {
                 "default": {
                     "initial_retry_delay_millis": 100,
-                    "retry_delay_multiplier": 1.2,
-                    "max_retry_delay_millis": 1000,
+                    "retry_delay_multiplier": 1.3,
+                    "max_retry_delay_millis": 60000,
                     "initial_rpc_timeout_millis": 20000,
-                    "rpc_timeout_multiplier": 1.5,
-                    "max_rpc_timeout_millis": 30000,
-                    "total_timeout_millis": 45000,
+                    "rpc_timeout_multiplier": 1.0,
+                    "max_rpc_timeout_millis": 20000,
+                    "total_timeout_millis": 600000,
                 }
             },
             "methods": {
-                "PatchTraces": {
+                "ListTraces": {
                     "timeout_millis": 60000,
                     "retry_codes_name": "idempotent",
                     "retry_params_name": "default",
@@ -27,9 +27,9 @@
                     "retry_codes_name": "idempotent",
                     "retry_params_name": "default",
                 },
-                "ListTraces": {
+                "PatchTraces": {
                     "timeout_millis": 60000,
-                    "retry_codes_name": "idempotent",
+                    "retry_codes_name": "non_idempotent",
                     "retry_params_name": "default",
                 },
             },

trace/google/cloud/trace_v1/gapic/transports/trace_service_grpc_transport.py

@@ -112,21 +112,17 @@ def channel(self):
         return self._channel
 
     @property
-    def patch_traces(self):
-        """Return the gRPC stub for :meth:`TraceServiceClient.patch_traces`.
+    def list_traces(self):
+        """Return the gRPC stub for :meth:`TraceServiceClient.list_traces`.
 
-        Sends new traces to Stackdriver Trace or updates existing traces. If the ID
-        of a trace that you send matches that of an existing trace, any fields
-        in the existing trace and its spans are overwritten by the provided values,
-        and any new fields provided are merged with the existing trace data. If the
-        ID does not match, a new trace is created.
+        Returns of a list of traces that match the specified filter conditions.
 
         Returns:
             Callable: A callable which accepts the appropriate
                 deserialized request object and returns a
                 deserialized response object.
         """
-        return self._stubs["trace_service_stub"].PatchTraces
+        return self._stubs["trace_service_stub"].ListTraces
 
     @property
     def get_trace(self):
@@ -142,14 +138,18 @@ def get_trace(self):
         return self._stubs["trace_service_stub"].GetTrace
 
     @property
-    def list_traces(self):
-        """Return the gRPC stub for :meth:`TraceServiceClient.list_traces`.
+    def patch_traces(self):
+        """Return the gRPC stub for :meth:`TraceServiceClient.patch_traces`.
 
-        Returns of a list of traces that match the specified filter conditions.
+        Sends new traces to Stackdriver Trace or updates existing traces. If the ID
+        of a trace that you send matches that of an existing trace, any fields
+        in the existing trace and its spans are overwritten by the provided values,
+        and any new fields provided are merged with the existing trace data. If the
+        ID does not match, a new trace is created.
 
         Returns:
             Callable: A callable which accepts the appropriate
                 deserialized request object and returns a
                 deserialized response object.
         """
-        return self._stubs["trace_service_stub"].ListTraces
+        return self._stubs["trace_service_stub"].PatchTraces

trace/google/cloud/trace_v1/proto/trace.proto

@@ -1,4 +1,4 @@
-// Copyright 2017 Google Inc.
+// Copyright 2019 Google LLC.
 //
 // Licensed under the Apache License, Version 2.0 (the "License");
 // you may not use this file except in compliance with the License.
@@ -17,6 +17,9 @@ syntax = "proto3";
 package google.devtools.cloudtrace.v1;
 
 import "google/api/annotations.proto";
+import "google/api/client.proto";
+import "google/api/field_behavior.proto";
+import "google/api/resource.proto";
 import "google/protobuf/empty.proto";
 import "google/protobuf/timestamp.proto";
 
@@ -33,18 +36,26 @@ option php_namespace = "Google\\Cloud\\Trace\\V1";
 // timed event which forms a node of the trace tree. Spans for a single trace
 // may span multiple services.
 service TraceService {
+  option (google.api.default_host) = "cloudtrace.googleapis.com";
+  option (google.api.oauth_scopes) =
+      "https://www.googleapis.com/auth/cloud-platform,"
+      "https://www.googleapis.com/auth/trace.append,"
+      "https://www.googleapis.com/auth/trace.readonly";
+
   // Returns of a list of traces that match the specified filter conditions.
   rpc ListTraces(ListTracesRequest) returns (ListTracesResponse) {
     option (google.api.http) = {
       get: "/v1/projects/{project_id}/traces"
     };
+    option (google.api.method_signature) = "project_id";
   }
 
   // Gets a single trace by its ID.
   rpc GetTrace(GetTraceRequest) returns (Trace) {
     option (google.api.http) = {
       get: "/v1/projects/{project_id}/traces/{trace_id}"
     };
+    option (google.api.method_signature) = "project_id,trace_id";
   }
 
   // Sends new traces to Stackdriver Trace or updates existing traces. If the ID
@@ -57,6 +68,7 @@ service TraceService {
       patch: "/v1/projects/{project_id}/traces"
       body: "traces"
     };
+    option (google.api.method_signature) = "project_id,traces";
   }
 }
 
@@ -68,7 +80,8 @@ message Trace {
   string project_id = 1;
 
   // Globally unique identifier for the trace. This identifier is a 128-bit
-  // numeric value formatted as a 32-byte hex string.
+  // numeric value formatted as a 32-byte hex string. For example,
+  // `382d4f4c6b7bb2f4a972559d9085001d`.
   string trace_id = 2;
 
   // Collection of spans in the trace.
@@ -103,7 +116,7 @@ message TraceSpan {
   }
 
   // Identifier for the span. Must be a 64-bit integer other than 0 and
-  // unique within a trace.
+  // unique within a trace. For example, `2205310701640571284`.
   fixed64 span_id = 1;
 
   // Distinguishes between spans generated in a particular context. For example,
@@ -113,7 +126,7 @@ message TraceSpan {
 
   // Name of the span. Must be less than 128 bytes. The span name is sanitized
   // and displayed in the Stackdriver Trace tool in the
-  // {% dynamic print site_values.console_name %}.
+  // Google Cloud Platform Console.
   // The name may be a method name or some other per-call site name.
   // For the same executable and the same call point, a best practice is
   // to use a consistent name, which makes it easier to correlate
@@ -126,8 +139,8 @@ message TraceSpan {
   // End time of the span in nanoseconds from the UNIX epoch.
   google.protobuf.Timestamp end_time = 5;
 
-  // ID of the parent span, if any. Optional.
-  fixed64 parent_span_id = 6;
+  // Optional. ID of the parent span, if any.
+  fixed64 parent_span_id = 6 [(google.api.field_behavior) = OPTIONAL];
 
   // Collection of labels associated with the span. Label keys must be less than
   // 128 bytes. Label values must be less than 16 kilobytes (10MB for
@@ -189,20 +202,20 @@ message ListTracesRequest {
     COMPLETE = 3;
   }
 
-  // ID of the Cloud project where the trace data is stored.
-  string project_id = 1;
+  // Required. ID of the Cloud project where the trace data is stored.
+  string project_id = 1 [(google.api.field_behavior) = REQUIRED];
 
-  // Type of data returned for traces in the list. Optional. Default is
+  // Optional. Type of data returned for traces in the list. Default is
   // `MINIMAL`.
-  ViewType view = 2;
+  ViewType view = 2 [(google.api.field_behavior) = OPTIONAL];
 
-  // Maximum number of traces to return. If not specified or <= 0, the
+  // Optional. Maximum number of traces to return. If not specified or <= 0, the
   // implementation selects a reasonable value.  The implementation may
-  // return fewer traces than the requested page size. Optional.
-  int32 page_size = 3;
+  // return fewer traces than the requested page size.
+  int32 page_size = 3 [(google.api.field_behavior) = OPTIONAL];
 
   // Token identifying the page of results to return. If provided, use the
-  // value of the `next_page_token` field from a previous request. Optional.
+  // value of the `next_page_token` field from a previous request.
   string page_token = 4;
 
   // Start of the time interval (inclusive) during which the trace data was
@@ -213,7 +226,7 @@ message ListTracesRequest {
   // collected from the application.
   google.protobuf.Timestamp end_time = 6;
 
-  // An optional filter against labels for the request.
+  // Optional. A filter against labels for the request.
   //
   // By default, searches use prefix matching. To specify exact match, prepend
   // a plus symbol (`+`) to the search term.
@@ -243,9 +256,9 @@ message ListTracesRequest {
   //     specified.
   // *   `method:VALUE`: Equivalent to `/http/method:VALUE`.
   // *   `url:VALUE`: Equivalent to `/http/url:VALUE`.
-  string filter = 7;
+  string filter = 7 [(google.api.field_behavior) = OPTIONAL];
 
-  // Field used to sort the returned traces. Optional.
+  // Optional. Field used to sort the returned traces.
   // Can be one of the following:
   //
   // *   `trace_id`
@@ -258,12 +271,12 @@ message ListTracesRequest {
   // (for example, `name desc`).
   //
   // Only one sort field is permitted.
-  string order_by = 8;
+  string order_by = 8 [(google.api.field_behavior) = OPTIONAL];
 }
 
 // The response message for the `ListTraces` method.
 message ListTracesResponse {
-  // List of trace records returned.
+  // List of trace records as specified by the view parameter.
   repeated Trace traces = 1;
 
   // If defined, indicates that there are more traces that match the request
@@ -274,18 +287,18 @@ message ListTracesResponse {
 
 // The request message for the `GetTrace` method.
 message GetTraceRequest {
-  // ID of the Cloud project where the trace data is stored.
-  string project_id = 1;
+  // Required. ID of the Cloud project where the trace data is stored.
+  string project_id = 1 [(google.api.field_behavior) = REQUIRED];
 
-  // ID of the trace to return.
-  string trace_id = 2;
+  // Required. ID of the trace to return.
+  string trace_id = 2 [(google.api.field_behavior) = REQUIRED];
 }
 
 // The request message for the `PatchTraces` method.
 message PatchTracesRequest {
-  // ID of the Cloud project where the trace data is stored.
-  string project_id = 1;
+  // Required. ID of the Cloud project where the trace data is stored.
+  string project_id = 1 [(google.api.field_behavior) = REQUIRED];
 
-  // The body of the message.
-  Traces traces = 2;
+  // Required. The body of the message.
+  Traces traces = 2 [(google.api.field_behavior) = REQUIRED];
 }