google-cloud-trace 0.27.2 → 0.28.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: 738619f7020791ff599a950fc987c8e725712e4c
-  data.tar.gz: 22a78c9abed2cfc846a41ce294e9227f36c27af7
+SHA256:
+  metadata.gz: 155666f9d25b1a89fc1961ff6f951a85d70ee76d0b873c0ae8d0968d2fe7bdc5
+  data.tar.gz: bb205f6876342cc8475afa4846199bf7776c9a424e22ae3bf76db4c4081dfcab
 SHA512:
-  metadata.gz: 85b5c5f7960a4af52650d0376480d6e6f7e82bf901e986e19c743e13f25cab8095a5e5d57c06b50fbf8a9c5334aa7cffbe445b09e1e0dde99a134d79f2d63770
-  data.tar.gz: 0eed3070b782306da41e78bf9b336023671ff151f77aee648a27c00916f711f760642428a578df61c9d8f6ebb949e4d3fdccb56b610c2e07721ecd9f96aa2ca5
+  metadata.gz: 3f8611b26a07d784c37d71c57d067b7aa811176301cd146c47fc355c2b53e4da7987d19ea83a423fa1bdfda7a3780c465c4f4cf1f5413f922069b00259c07485
+  data.tar.gz: 3cbfea10ed4fd5452a6b543177f713a8cdfe89944285ace795a6d83d33f69870aa5341b741adb6449371b743000a38ea7158206ccf9405c21c3e7c0ec00ca1c8

data/lib/google-cloud-trace.rb

@@ -13,9 +13,9 @@
 # limitations under the License.
 
 ##
-# This file is here to be autorequired by bundler, so that the .trace and
-# #trace methods can be available, but the library and all dependencies won't
-# be loaded until required and used.
+# This file is here to be autorequired by bundler, so that the
+# Google::Cloud.trace and Google::Cloud#trace methods can be available, but the
+# library and all dependencies won't be loaded until required and used.
 
 
 gem "google-cloud-core"
@@ -63,10 +63,12 @@ module Google
     # For more information on connecting to Google Cloud see the [Authentication
     # Guide](https://googlecloudplatform.github.io/google-cloud-ruby/#/docs/guides/authentication).
     #
-    # @param [String] project Project identifier for the Stackdriver Trace
-    #   service.
-    # @param [String, Hash] keyfile Keyfile downloaded from Google Cloud:
-    #   either the JSON data or the path to a readable file.
+    # @param [String] project_id Project identifier for the Stackdriver Trace
+    #   service you are connecting to. If not present, the default project for
+    #   the credentials is used.
+    # @param [String, Hash, Google::Auth::Credentials] credentials The path to
+    #   the keyfile as a String, the contents of the keyfile as a Hash, or a
+    #   Google::Auth::Credentials object. (See {Trace::Credentials})
     # @param [String, Array<String>] scope The OAuth 2.0 scopes controlling the
     #   set of resources and operations that the connection can access. See
     #   [Using OAuth 2.0 to Access Google
@@ -86,10 +88,10 @@ module Google
     #     puts "Retrieved trace ID: #{trace.trace_id}"
     #   end
     #
-    def self.trace project = nil, keyfile = nil, scope: nil, timeout: nil,
-                   client_config: nil
+    def self.trace project_id = nil, credentials = nil, scope: nil,
+                   timeout: nil, client_config: nil
       require "google/cloud/trace"
-      Google::Cloud::Trace.new project: project, keyfile: keyfile,
+      Google::Cloud::Trace.new project_id: project_id, credentials: credentials,
                                scope: scope, timeout: timeout,
                                client_config: client_config
     end

data/lib/google/cloud/trace.rb

@@ -205,16 +205,21 @@ module Google
       # [Authentication
       # Guide](https://googlecloudplatform.github.io/google-cloud-ruby/#/docs/guides/authentication).
       #
-      # @param [String] project Project identifier for the Stackdriver Trace
-      #   service.
-      # @param [String, Hash] keyfile Keyfile downloaded from Google Cloud:
-      #   either the JSON data or the path to a readable file.
+      # @param [String] project_id Project identifier for the Stackdriver Trace
+      #   service you are connecting to. If not present, the default project for
+      #   the credentials is used.
+      # @param [String, Hash, Google::Auth::Credentials] credentials The path to
+      #   the keyfile as a String, the contents of the keyfile as a Hash, or a
+      #   Google::Auth::Credentials object. (See {Trace::Credentials})
       # @param [String, Array<String>] scope The OAuth 2.0 scopes controlling
       #   the set of resources and operations that the connection can access.
       #   See [Using OAuth 2.0 to Access Google
       #   APIs](https://developers.google.com/identity/protocols/OAuth2).
       #   The default scope is `https://www.googleapis.com/auth/cloud-platform`
       # @param [Integer] timeout Default timeout to use in requests. Optional.
+      # @param [String] project Alias for the `project_id` argument. Deprecated.
+      # @param [String] keyfile Alias for the `credentials` argument.
+      #   Deprecated.
       #
       # @return [Google::Cloud::Trace::Project]
       #
@@ -228,20 +233,21 @@ module Google
       #     puts "Retrieved trace ID: #{trace.trace_id}"
       #   end
       #
-      def self.new project: nil, keyfile: nil, scope: nil, timeout: nil,
-                   client_config: nil
-        project ||= Google::Cloud::Trace::Project.default_project
-        project = project.to_s # Always cast to a string
-        fail ArgumentError, "project is missing" if project.empty?
+      def self.new project_id: nil, credentials: nil, scope: nil, timeout: nil,
+                   client_config: nil, project: nil, keyfile: nil
+        project_id ||= (project || Trace::Project.default_project_id)
+        project_id = project_id.to_s # Always cast to a string
+        fail ArgumentError, "project_id is missing" if project_id.empty?
 
-        credentials =
-          Google::Cloud::Trace::Credentials.credentials_with_scope keyfile,
-                                                                   scope
+        credentials ||= (keyfile || Trace::Credentials.default(scope: scope))
+        unless credentials.is_a? Google::Auth::Credentials
+          credentials = Trace::Credentials.new credentials, scope: scope
+        end
 
-        Google::Cloud::Trace::Project.new(
-          Google::Cloud::Trace::Service.new(
-            project, credentials, timeout: timeout,
-                                  client_config: client_config))
+        Trace::Project.new(
+          Trace::Service.new(
+            project_id, credentials, timeout: timeout,
+                                     client_config: client_config))
       end
 
       ##

data/lib/google/cloud/trace/credentials.rb

@@ -13,28 +13,44 @@
 # limitations under the License.
 
 
-require "google/cloud/credentials"
+require "googleauth"
 
 module Google
   module Cloud
     module Trace
       ##
-      # @private Represents the OAuth 2.0 signing logic for Trace.
-      class Credentials < Google::Cloud::Credentials
+      # # Credentials
+      #
+      # Represents the authentication and authorization used to connect to the
+      # Stackdriver Trace API.
+      #
+      # @example
+      #   require "google/cloud/trace"
+      #
+      #   keyfile = "/path/to/keyfile.json"
+      #   creds = Google::Cloud::Trace::Credentials.new keyfile
+      #
+      #   trace = Google::Cloud::Trace.new(
+      #     project_id: "my-project",
+      #     credentials: creds
+      #   )
+      #
+      #   trace.project_id #=> "my-project"
+      #
+      class Credentials < Google::Auth::Credentials
         SCOPE = ["https://www.googleapis.com/auth/cloud-platform"]
-        PATH_ENV_VARS = %w(TRACE_KEYFILE GOOGLE_CLOUD_KEYFILE GCLOUD_KEYFILE)
-        JSON_ENV_VARS = %w(TRACE_KEYFILE_JSON GOOGLE_CLOUD_KEYFILE_JSON
+        PATH_ENV_VARS = %w(TRACE_CREDENTIALS
+                           TRACE_KEYFILE
+                           GOOGLE_CLOUD_CREDENTIALS
+                           GOOGLE_CLOUD_KEYFILE
+                           GCLOUD_KEYFILE)
+        JSON_ENV_VARS = %w(TRACE_CREDENTIALS_JSON
+                           TRACE_KEYFILE_JSON
+                           GOOGLE_CLOUD_CREDENTIALS_JSON
+                           GOOGLE_CLOUD_KEYFILE_JSON
                            GCLOUD_KEYFILE_JSON)
-
-        ##
-        # @private Create credentials with given scope and/or keyfile
-        def self.credentials_with_scope keyfile, scope = nil
-          if keyfile.nil?
-            default(scope: scope)
-          else
-            new(keyfile, scope: scope)
-          end
-        end
+        DEFAULT_PATHS = \
+          ["~/.config/gcloud/application_default_credentials.json"]
       end
     end
   end

data/lib/google/cloud/trace/label_key.rb

@@ -106,7 +106,7 @@ module Google
         # @example
         #   require "google/cloud/trace"
         #
-        #   trace_record = Google::Cloud::Trace::TraceRecord.new "my-project-id"
+        #   trace_record = Google::Cloud::Trace::TraceRecord.new "my-project"
         #   span = trace_record.create_span "root_span"
         #   Google::Cloud::Trace::LabelKey.set_stack_trace span.labels
         #

data/lib/google/cloud/trace/middleware.rb

@@ -378,7 +378,7 @@ module Google
         # Fallback to default configuration values if not defined already
         def init_default_config
           configuration.project_id ||= Cloud.configure.project_id ||
-                                       Trace::Project.default_project
+                                       Trace::Project.default_project_id
           configuration.keyfile ||= Cloud.configure.keyfile
           configuration.capture_stack ||= false
         end

data/lib/google/cloud/trace/notifications.rb

@@ -61,7 +61,7 @@ module Google
         #
         #   Google::Cloud::Trace::Notifications.instrument "sql.activerecord"
         #
-        #   trace_record = Google::Cloud::Trace::TraceRecord.new "my-project-id"
+        #   trace_record = Google::Cloud::Trace::TraceRecord.new "my-project"
         #   Google::Cloud::Trace.set trace_record
         #
         #   ActiveRecord::Base.connection.execute "SHOW TABLES"

data/lib/google/cloud/trace/project.rb

@@ -61,15 +61,16 @@ module Google
         #   require "google/cloud/trace"
         #
         #   trace_client = Google::Cloud::Trace.new(
-        #     project: "my-project",
-        #     keyfile: "/path/to/keyfile.json"
+        #     project_id: "my-project",
+        #     credentials: "/path/to/keyfile.json"
         #   )
         #
-        #   trace_client.project #=> "my-project"
+        #   trace_client.project_id #=> "my-project"
         #
-        def project
+        def project_id
           service.project
         end
+        alias_method :project, :project_id
 
         ##
         # Create a new empty trace record for this project. Uses the current
@@ -87,8 +88,8 @@ module Google
         #   require "google/cloud/trace"
         #
         #   trace_client = Google::Cloud::Trace.new(
-        #     project: "my-project",
-        #     keyfile: "/path/to/keyfile.json"
+        #     project_id: "my-project",
+        #     credentials: "/path/to/keyfile.json"
         #   )
         #
         #   trace = trace_client.new_trace
@@ -198,7 +199,7 @@ module Google
 
         ##
         # @private Default project.
-        def self.default_project
+        def self.default_project_id
           ENV["TRACE_PROJECT"] ||
             ENV["GOOGLE_CLOUD_PROJECT"] ||
             ENV["GCLOUD_PROJECT"] ||

data/lib/google/cloud/trace/rails.rb

@@ -163,7 +163,7 @@ module Google
         ##
         # Fallback to default config values if config parameters not provided.
         def self.init_default_config
-          Trace.configure.project_id ||= Trace::Project.default_project
+          Trace.configure.project_id ||= Trace::Project.default_project_id
         end
 
         ##

data/lib/google/cloud/trace/service.rb

@@ -35,10 +35,6 @@ module Google
         # @private
         attr_accessor :credentials
 
-        ##
-        # @private
-        attr_accessor :host
-
         ##
         # @private
         attr_accessor :timeout
@@ -49,41 +45,29 @@ module Google
 
         ##
         # Creates a new Service instance.
-        def initialize project, credentials, host: nil, timeout: nil,
-                       client_config: nil
+        def initialize project, credentials, timeout: nil, client_config: nil
           @project = project
           @credentials = credentials
-          @host = host || V1::TraceServiceClient::SERVICE_ADDRESS
           @timeout = timeout
           @client_config = client_config || {}
         end
 
-        def channel
-          load_grpc
-          GRPC::Core::Channel.new host, nil, chan_creds
-        end
-
-        def chan_creds
-          return credentials if insecure?
-          load_grpc
-          GRPC::Core::ChannelCredentials.new.compose \
-            GRPC::Core::CallCredentials.new credentials.client.updater_proc
-        end
-
-        def insecure?
-          credentials == :this_channel_is_insecure
-        end
-
         def lowlevel_client
           return mocked_lowlevel_client if mocked_lowlevel_client
+
           @lowlevel_client ||= \
-            V1::TraceServiceClient.new(
-              service_path: host,
-              channel: channel,
-              timeout: timeout,
-              client_config: client_config,
-              lib_name: "gccl",
-              lib_version: Google::Cloud::Trace::VERSION)
+            begin
+              require "grpc"
+              require "google/cloud/trace/patches/active_call_with_trace"
+              require "google/cloud/trace/patches/call_with_trace"
+
+              V1::TraceServiceClient.new(
+                credentials: credentials,
+                timeout: timeout,
+                client_config: client_config,
+                lib_name: "gccl",
+                lib_version: Google::Cloud::Trace::VERSION)
+            end
         end
         attr_accessor :mocked_lowlevel_client
 
@@ -160,12 +144,6 @@ module Google
           # GaxError wraps BadStatus, but exposes it as #cause
           raise Google::Cloud::Error.from_error(e.cause)
         end
-
-        def load_grpc
-          require "grpc"
-          require "google/cloud/trace/patches/active_call_with_trace"
-          require "google/cloud/trace/patches/call_with_trace"
-        end
       end
     end
   end

data/lib/google/cloud/trace/span.rb

@@ -244,7 +244,7 @@ module Google
         # @example
         #   require "google/cloud/trace"
         #
-        #   trace_record = Google::Cloud::Trace::TraceRecord.new "my-project-id"
+        #   trace_record = Google::Cloud::Trace::TraceRecord.new "my-project"
         #   span = trace_record.create_span "root_span"
         #   subspan = span.create_span "subspan"
         #
@@ -272,7 +272,7 @@ module Google
         # @example
         #   require "google/cloud/trace"
         #
-        #   trace_record = Google::Cloud::Trace::TraceRecord.new "my-project-id"
+        #   trace_record = Google::Cloud::Trace::TraceRecord.new "my-project"
         #   trace_record.in_span "root_span" do |span|
         #     # Do stuff...
         #     span.in_span "subspan" do |subspan|
@@ -367,7 +367,7 @@ module Google
         # @example
         #   require "google/cloud/trace"
         #
-        #   trace_record = Google::Cloud::Trace::TraceRecord.new "my-project-id"
+        #   trace_record = Google::Cloud::Trace::TraceRecord.new "my-project"
         #   root1 = trace_record.create_span "root_span_1"
         #   root2 = trace_record.create_span "root_span_2"
         #   subspan = root1.create_span "subspan"

data/lib/google/cloud/trace/trace_record.rb

@@ -122,6 +122,7 @@ module Google
         # @return [String]
         #
         attr_reader :project
+        alias_method :project_id, :project
 
         ##
         # The context for this trace.
@@ -182,7 +183,7 @@ module Google
         # @example
         #   require "google/cloud/trace"
         #
-        #   trace_record = Google::Cloud::Trace::TraceRecord.new "my-project-id"
+        #   trace_record = Google::Cloud::Trace::TraceRecord.new "my-project"
         #   span = trace_record.create_span "root_span"
         #
         def create_span name, span_id: nil, parent_span_id: 0,
@@ -219,7 +220,7 @@ module Google
         # @example
         #   require "google/cloud/trace"
         #
-        #   trace_record = Google::Cloud::Trace::TraceRecord.new "my-project-id"
+        #   trace_record = Google::Cloud::Trace::TraceRecord.new "my-project"
         #   trace_record.in_span "root_span" do |span|
         #     # Do stuff...
         #   end

data/lib/google/cloud/trace/v1/doc/google/devtools/cloudtrace/v1/trace.rb

@@ -15,6 +15,17 @@
 module Google
   module Devtools
     module Cloudtrace
+      ##
+      # # Stackdriver Trace API Contents
+      #
+      # | Class | Description |
+      # | ----- | ----------- |
+      # | [TraceServiceClient][] | Send and retrieve trace data from Stackdriver Trace. Data is generated and available by default for all App Engine applications. Data from other applications can be written to Stackdriver Trace for display, reporting, and analysis. |
+      # | [Data Types][] | Data types for Google::Cloud::Trace::V1 |
+      #
+      # [TraceServiceClient]: https://googlecloudplatform.github.io/google-cloud-ruby/#/docs/google-cloud-trace/latest/google/devtools/cloudtrace/v1/traceserviceclient
+      # [Data Types]: https://googlecloudplatform.github.io/google-cloud-ruby/#/docs/google-cloud-trace/latest/google/devtools/cloudtrace/v1/datatypes
+      #
       module V1
         # A trace describes how long it takes for an application to perform an
         # operation. It consists of a set of spans, each of which represent a single
@@ -53,8 +64,9 @@ module Google
         #     and +RPC_SERVER+ to identify queueing latency associated with the span.
         # @!attribute [rw] name
         #   @return [String]
-        #     Name of the trace. The trace name is sanitized and displayed in the
-        #     Stackdriver Trace tool in the Google Developers Console.
+        #     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 %}.
         #     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
@@ -70,7 +82,39 @@ module Google
         #     ID of the parent span, if any. Optional.
         # @!attribute [rw] labels
         #   @return [Hash{String => String}]
-        #     Collection of labels associated with the span.
+        #     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
+        #     +/stacktrace+ values).
+        #
+        #     Some predefined label keys exist, or you may create your own. When creating
+        #     your own, we recommend the following formats:
+        #
+        #     * +/category/product/key+ for agents of well-known products (e.g.
+        #       +/db/mongodb/read_size+).
+        #     * +short_host/path/key+ for domain-specific keys (e.g.
+        #       +foo.com/myproduct/bar+)
+        #
+        #     Predefined labels include:
+        #
+        #     * +/agent+
+        #     * +/component+
+        #     * +/error/message+
+        #     * +/error/name+
+        #     * +/http/client_city+
+        #     * +/http/client_country+
+        #     * +/http/client_protocol+
+        #     * +/http/client_region+
+        #     * +/http/host+
+        #     * +/http/method+
+        #     * +/http/redirected_url+
+        #     * +/http/request/size+
+        #     * +/http/response/size+
+        #     * +/http/status_code+
+        #     * +/http/url+
+        #     * +/http/user_agent+
+        #     * +/pid+
+        #     * +/stacktrace+
+        #     * +/tid+
         class TraceSpan
           # Type of span. Can be used to specify additional relationships between spans
           # in addition to a parent/child relationship.
@@ -108,25 +152,54 @@ module Google
         #     value of the +next_page_token+ field from a previous request. Optional.
         # @!attribute [rw] start_time
         #   @return [Google::Protobuf::Timestamp]
-        #     End of the time interval (inclusive) during which the trace data was
+        #     Start of the time interval (inclusive) during which the trace data was
         #     collected from the application.
         # @!attribute [rw] end_time
         #   @return [Google::Protobuf::Timestamp]
-        #     Start of the time interval (inclusive) during which the trace data was
+        #     End of the time interval (inclusive) during which the trace data was
         #     collected from the application.
         # @!attribute [rw] filter
         #   @return [String]
-        #     An optional filter for the request.
+        #     An optional filter against labels for the request.
+        #
+        #     By default, searches use prefix matching. To specify exact match, prepend
+        #     a plus symbol (+++) to the search term.
+        #     Multiple terms are ANDed. Syntax:
+        #
+        #     * +root:NAME_PREFIX+ or +NAME_PREFIX+: Return traces where any root
+        #       span starts with +NAME_PREFIX+.
+        #     * ++root:NAME+ or ++NAME+: Return traces where any root span's name is
+        #       exactly +NAME+.
+        #     * +span:NAME_PREFIX+: Return traces where any span starts with
+        #       +NAME_PREFIX+.
+        #     * ++span:NAME+: Return traces where any span's name is exactly
+        #       +NAME+.
+        #     * +latency:DURATION+: Return traces whose overall latency is
+        #       greater or equal to than +DURATION+. Accepted units are nanoseconds
+        #       (+ns+), milliseconds (+ms+), and seconds (+s+). Default is +ms+. For
+        #       example, +latency:24ms+ returns traces whose overall latency
+        #       is greater than or equal to 24 milliseconds.
+        #     * +label:LABEL_KEY+: Return all traces containing the specified
+        #       label key (exact match, case-sensitive) regardless of the key:value
+        #       pair's value (including empty values).
+        #     * +LABEL_KEY:VALUE_PREFIX+: Return all traces containing the specified
+        #       label key (exact match, case-sensitive) whose value starts with
+        #       +VALUE_PREFIX+. Both a key and a value must be specified.
+        #     * ++LABEL_KEY:VALUE+: Return all traces containing a key:value pair
+        #       exactly matching the specified text. Both a key and a value must be
+        #       specified.
+        #     * +method:VALUE+: Equivalent to +/http/method:VALUE+.
+        #     * +url:VALUE+: Equivalent to +/http/url:VALUE+.
         # @!attribute [rw] order_by
         #   @return [String]
         #     Field used to sort the returned traces. Optional.
         #     Can be one of the following:
         #
-        #     *   +trace_id+
-        #     *   +name+ (+name+ field of root span in the trace)
-        #     *   +duration+ (difference between +end_time+ and +start_time+ fields of
-        #          the root span)
-        #     *   +start+ (+start_time+ field of the root span)
+        #     * +trace_id+
+        #     * +name+ (+name+ field of root span in the trace)
+        #     * +duration+ (difference between +end_time+ and +start_time+ fields of
+        #       the root span)
+        #     * +start+ (+start_time+ field of the root span)
         #
         #     Descending order can be specified by appending +desc+ to the sort field
         #     (for example, +name desc+).

data/lib/google/cloud/trace/v1/doc/google/protobuf/timestamp.rb

@@ -24,7 +24,9 @@ module Google
     # 0001-01-01T00:00:00Z to 9999-12-31T23:59:59.999999999Z.
     # By restricting to that range, we ensure that we can convert to
     # and from  RFC 3339 date strings.
-    # See {https://www.ietf.org/rfc/rfc3339.txt}[https://www.ietf.org/rfc/rfc3339.txt].
+    # See [https://www.ietf.org/rfc/rfc3339.txt](https://www.ietf.org/rfc/rfc3339.txt).
+    #
+    # = Examples
     #
     # Example 1: Compute Timestamp from POSIX +time()+.
     #
@@ -65,6 +67,29 @@ module Google
     #
     #     timestamp = Timestamp()
     #     timestamp.GetCurrentTime()
+    #
+    # = JSON Mapping
+    #
+    # In JSON format, the Timestamp type is encoded as a string in the
+    # [RFC 3339](https://www.ietf.org/rfc/rfc3339.txt) format. That is, the
+    # format is "{year}-{month}-{day}T{hour}:{min}:{sec}[.{frac_sec}]Z"
+    # where {year} is always expressed using four digits while {month}, {day},
+    # {hour}, {min}, and {sec} are zero-padded to two digits each. The fractional
+    # seconds, which can go up to 9 digits (i.e. up to 1 nanosecond resolution),
+    # are optional. The "Z" suffix indicates the timezone ("UTC"); the timezone
+    # is required, though only UTC (as indicated by "Z") is presently supported.
+    #
+    # For example, "2017-01-15T01:30:15.01Z" encodes 15.01 seconds past
+    # 01:30 UTC on January 15, 2017.
+    #
+    # In JavaScript, one can convert a Date object to this format using the
+    # standard [toISOString()](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/toISOString]
+    # method. In Python, a standard +datetime.datetime+ object can be converted
+    # to this format using [+strftime+](https://docs.python.org/2/library/time.html#time.strftime)
+    # with the time format spec '%Y-%m-%dT%H:%M:%S.%fZ'. Likewise, in Java, one
+    # can use the Joda Time's [+ISODateTimeFormat.dateTime()+](
+    # http://joda-time.sourceforge.net/apidocs/org/joda/time/format/ISODateTimeFormat.html#dateTime())
+    # to obtain a formatter capable of generating timestamps in this format.
     # @!attribute [rw] seconds
     #   @return [Integer]
     #     Represents seconds of UTC time since Unix epoch

data/lib/google/cloud/trace/v1/doc/overview.rb

@@ -0,0 +1,56 @@
+# Copyright 2017, Google Inc. All rights reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+module Google
+  module Cloud
+    # rubocop:disable LineLength
+
+    ##
+    # # Ruby Client for Stackdriver Trace API ([Alpha](https://github.com/GoogleCloudPlatform/google-cloud-ruby#versioning))
+    #
+    # [Stackdriver Trace API][Product Documentation]:
+    # Send and retrieve trace data from Stackdriver Trace. Data is generated and
+    # available by default for all App Engine applications. Data from other
+    # applications can be written to Stackdriver Trace for display, reporting, and
+    # analysis.
+    # - [Product Documentation][]
+    #
+    # ## Quick Start
+    # In order to use this library, you first need to go through the following
+    # steps:
+    #
+    # 1. [Select or create a Cloud Platform project.](https://console.cloud.google.com/project)
+    # 2. [Enable the Stackdriver Trace API.](https://console.cloud.google.com/apis/api/cloudtrace)
+    # 3. [Setup Authentication.](https://googlecloudplatform.github.io/google-cloud-ruby/#/docs/google-cloud/master/guides/authentication)
+    #
+    # ### Installation
+    # ```
+    # $ gem install google-cloud-trace
+    # ```
+    #
+    # ### Next Steps
+    # - Read the [Stackdriver Trace API Product documentation][Product Documentation]
+    #   to learn more about the product and see How-to Guides.
+    # - View this [repository's main README](https://github.com/GoogleCloudPlatform/google-cloud-ruby/blob/master/README.md)
+    #   to see the full list of Cloud APIs that we cover.
+    #
+    # [Product Documentation]: https://cloud.google.com/cloudtrace
+    #
+    #
+    module Trace
+      module V1
+      end
+    end
+  end
+end

data/lib/google/cloud/trace/v1/trace_service_client.rb

@@ -28,6 +28,7 @@ require "pathname"
 require "google/gax"
 
 require "google/devtools/cloudtrace/v1/trace_pb"
+require "google/cloud/trace/credentials"
 
 module Google
   module Cloud
@@ -69,15 +70,24 @@ module Google
             "https://www.googleapis.com/auth/trace.readonly"
           ].freeze
 
-          # @param service_path [String]
-          #   The domain name of the API remote host.
-          # @param port [Integer]
-          #   The port on which to connect to the remote host.
-          # @param channel [Channel]
-          #   A Channel object through which to make calls.
-          # @param chan_creds [Grpc::ChannelCredentials]
-          #   A ChannelCredentials for the setting up the RPC client.
-          # @param client_config[Hash]
+          # @param credentials [Google::Auth::Credentials, String, Hash, GRPC::Core::Channel, GRPC::Core::ChannelCredentials, Proc]
+          #   Provides the means for authenticating requests made by the client. This parameter can
+          #   be many types.
+          #   A `Google::Auth::Credentials` uses a the properties of its represented keyfile for
+          #   authenticating requests made by this client.
+          #   A `String` will be treated as the path to the keyfile to be used for the construction of
+          #   credentials for this client.
+          #   A `Hash` will be treated as the contents of a keyfile to be used for the construction of
+          #   credentials for this client.
+          #   A `GRPC::Core::Channel` will be used to make calls through.
+          #   A `GRPC::Core::ChannelCredentials` for the setting up the RPC client. The channel credentials
+          #   should already be composed with a `GRPC::Core::CallCredentials` object.
+          #   A `Proc` will be used as an updater_proc for the Grpc channel. The proc transforms the
+          #   metadata for requests, generally, to give OAuth credentials.
+          # @param scopes [Array<String>]
+          #   The OAuth scopes for this service. This parameter is ignored if
+          #   an updater_proc is supplied.
+          # @param client_config [Hash]
           #   A Hash for call options for each method. See
           #   Google::Gax#construct_settings for the structure of
           #   this data. Falls back to the default config if not specified
@@ -89,11 +99,11 @@ module Google
               port: DEFAULT_SERVICE_PORT,
               channel: nil,
               chan_creds: nil,
+              updater_proc: nil,
+              credentials: nil,
               scopes: ALL_SCOPES,
               client_config: {},
               timeout: DEFAULT_TIMEOUT,
-              app_name: nil,
-              app_version: nil,
               lib_name: nil,
               lib_version: ""
             # These require statements are intentionally placed here to initialize
@@ -102,14 +112,38 @@ module Google
             require "google/gax/grpc"
             require "google/devtools/cloudtrace/v1/trace_services_pb"
 
+            if channel || chan_creds || updater_proc
+              warn "The `channel`, `chan_creds`, and `updater_proc` parameters will be removed " \
+                "on 2017/09/08"
+              credentials ||= channel
+              credentials ||= chan_creds
+              credentials ||= updater_proc
+            end
+            if service_path != SERVICE_ADDRESS || port != DEFAULT_SERVICE_PORT
+              warn "`service_path` and `port` parameters are deprecated and will be removed"
+            end
+
+            credentials ||= Google::Cloud::Trace::Credentials.default
 
-            if app_name || app_version
-              warn "`app_name` and `app_version` are no longer being used in the request headers."
+            if credentials.is_a?(String) || credentials.is_a?(Hash)
+              updater_proc = Google::Cloud::Trace::Credentials.new(credentials).updater_proc
+            end
+            if credentials.is_a?(GRPC::Core::Channel)
+              channel = credentials
+            end
+            if credentials.is_a?(GRPC::Core::ChannelCredentials)
+              chan_creds = credentials
+            end
+            if credentials.is_a?(Proc)
+              updater_proc = credentials
+            end
+            if credentials.is_a?(Google::Auth::Credentials)
+              updater_proc = credentials.updater_proc
             end
 
             google_api_client = "gl-ruby/#{RUBY_VERSION}"
             google_api_client << " #{lib_name}/#{lib_version}" if lib_name
-            google_api_client << " gapic/0.6.8 gax/#{Google::Gax::VERSION}"
+            google_api_client << " gapic/0.1.0 gax/#{Google::Gax::VERSION}"
             google_api_client << " grpc/#{GRPC::VERSION}"
             google_api_client.freeze
 
@@ -134,95 +168,27 @@ module Google
               port,
               chan_creds: chan_creds,
               channel: channel,
+              updater_proc: updater_proc,
               scopes: scopes,
               &Google::Devtools::Cloudtrace::V1::TraceService::Stub.method(:new)
             )
 
-            @patch_traces = Google::Gax.create_api_call(
-              @trace_service_stub.method(:patch_traces),
-              defaults["patch_traces"]
+            @list_traces = Google::Gax.create_api_call(
+              @trace_service_stub.method(:list_traces),
+              defaults["list_traces"]
             )
             @get_trace = Google::Gax.create_api_call(
               @trace_service_stub.method(:get_trace),
               defaults["get_trace"]
             )
-            @list_traces = Google::Gax.create_api_call(
-              @trace_service_stub.method(:list_traces),
-              defaults["list_traces"]
+            @patch_traces = Google::Gax.create_api_call(
+              @trace_service_stub.method(:patch_traces),
+              defaults["patch_traces"]
             )
           end
 
           # Service calls
 
-          # 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.
-          #
-          # @param project_id [String]
-          #   ID of the Cloud project where the trace data is stored.
-          # @param traces [Google::Devtools::Cloudtrace::V1::Traces]
-          #   The body of the message.
-          # @param options [Google::Gax::CallOptions]
-          #   Overrides the default settings for this call, e.g, timeout,
-          #   retries, etc.
-          # @raise [Google::Gax::GaxError] if the RPC is aborted.
-          # @example
-          #   require "google/cloud/trace/v1/trace_service_client"
-          #
-          #   TraceServiceClient = Google::Cloud::Trace::V1::TraceServiceClient
-          #   Traces = Google::Devtools::Cloudtrace::V1::Traces
-          #
-          #   trace_service_client = TraceServiceClient.new
-          #   project_id = ''
-          #   traces = Traces.new
-          #   trace_service_client.patch_traces(project_id, traces)
-
-          def patch_traces \
-              project_id,
-              traces,
-              options: nil
-            req = Google::Devtools::Cloudtrace::V1::PatchTracesRequest.new({
-              project_id: project_id,
-              traces: traces
-            }.delete_if { |_, v| v.nil? })
-            @patch_traces.call(req, options)
-            nil
-          end
-
-          # Gets a single trace by its ID.
-          #
-          # @param project_id [String]
-          #   ID of the Cloud project where the trace data is stored.
-          # @param trace_id [String]
-          #   ID of the trace to return.
-          # @param options [Google::Gax::CallOptions]
-          #   Overrides the default settings for this call, e.g, timeout,
-          #   retries, etc.
-          # @return [Google::Devtools::Cloudtrace::V1::Trace]
-          # @raise [Google::Gax::GaxError] if the RPC is aborted.
-          # @example
-          #   require "google/cloud/trace/v1/trace_service_client"
-          #
-          #   TraceServiceClient = Google::Cloud::Trace::V1::TraceServiceClient
-          #
-          #   trace_service_client = TraceServiceClient.new
-          #   project_id = ''
-          #   trace_id = ''
-          #   response = trace_service_client.get_trace(project_id, trace_id)
-
-          def get_trace \
-              project_id,
-              trace_id,
-              options: nil
-            req = Google::Devtools::Cloudtrace::V1::GetTraceRequest.new({
-              project_id: project_id,
-              trace_id: trace_id
-            }.delete_if { |_, v| v.nil? })
-            @get_trace.call(req, options)
-          end
-
           # Returns of a list of traces that match the specified filter conditions.
           #
           # @param project_id [String]
@@ -231,26 +197,61 @@ module Google
           #   Type of data returned for traces in the list. Optional. Default is
           #   +MINIMAL+.
           # @param page_size [Integer]
-          #   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.
-          # @param start_time [Google::Protobuf::Timestamp]
-          #   End of the time interval (inclusive) during which the trace data was
-          #   collected from the application.
-          # @param end_time [Google::Protobuf::Timestamp]
+          #   The maximum number of resources contained in the underlying API
+          #   response. If page streaming is performed per-resource, this
+          #   parameter does not affect the return value. If page streaming is
+          #   performed per-page, this determines the maximum number of
+          #   resources in a page.
+          # @param start_time [Google::Protobuf::Timestamp | Hash]
           #   Start of the time interval (inclusive) during which the trace data was
           #   collected from the application.
+          #   A hash of the same form as `Google::Protobuf::Timestamp`
+          #   can also be provided.
+          # @param end_time [Google::Protobuf::Timestamp | Hash]
+          #   End of the time interval (inclusive) during which the trace data was
+          #   collected from the application.
+          #   A hash of the same form as `Google::Protobuf::Timestamp`
+          #   can also be provided.
           # @param filter [String]
-          #   An optional filter for the request.
+          #   An optional filter against labels for the request.
+          #
+          #   By default, searches use prefix matching. To specify exact match, prepend
+          #   a plus symbol (+++) to the search term.
+          #   Multiple terms are ANDed. Syntax:
+          #
+          #   * +root:NAME_PREFIX+ or +NAME_PREFIX+: Return traces where any root
+          #     span starts with +NAME_PREFIX+.
+          #   * ++root:NAME+ or ++NAME+: Return traces where any root span's name is
+          #     exactly +NAME+.
+          #   * +span:NAME_PREFIX+: Return traces where any span starts with
+          #     +NAME_PREFIX+.
+          #   * ++span:NAME+: Return traces where any span's name is exactly
+          #     +NAME+.
+          #   * +latency:DURATION+: Return traces whose overall latency is
+          #     greater or equal to than +DURATION+. Accepted units are nanoseconds
+          #     (+ns+), milliseconds (+ms+), and seconds (+s+). Default is +ms+. For
+          #     example, +latency:24ms+ returns traces whose overall latency
+          #     is greater than or equal to 24 milliseconds.
+          #   * +label:LABEL_KEY+: Return all traces containing the specified
+          #     label key (exact match, case-sensitive) regardless of the key:value
+          #     pair's value (including empty values).
+          #   * +LABEL_KEY:VALUE_PREFIX+: Return all traces containing the specified
+          #     label key (exact match, case-sensitive) whose value starts with
+          #     +VALUE_PREFIX+. Both a key and a value must be specified.
+          #   * ++LABEL_KEY:VALUE+: Return all traces containing a key:value pair
+          #     exactly matching the specified text. Both a key and a value must be
+          #     specified.
+          #   * +method:VALUE+: Equivalent to +/http/method:VALUE+.
+          #   * +url:VALUE+: Equivalent to +/http/url:VALUE+.
           # @param order_by [String]
           #   Field used to sort the returned traces. Optional.
           #   Can be one of the following:
           #
-          #   *   +trace_id+
-          #   *   +name+ (+name+ field of root span in the trace)
-          #   *   +duration+ (difference between +end_time+ and +start_time+ fields of
-          #        the root span)
-          #   *   +start+ (+start_time+ field of the root span)
+          #   * +trace_id+
+          #   * +name+ (+name+ field of root span in the trace)
+          #   * +duration+ (difference between +end_time+ and +start_time+ fields of
+          #     the root span)
+          #   * +start+ (+start_time+ field of the root span)
           #
           #   Descending order can be specified by appending +desc+ to the sort field
           #   (for example, +name desc+).
@@ -266,11 +267,9 @@ module Google
           #   object.
           # @raise [Google::Gax::GaxError] if the RPC is aborted.
           # @example
-          #   require "google/cloud/trace/v1/trace_service_client"
+          #   require "google/cloud/trace/v1"
           #
-          #   TraceServiceClient = Google::Cloud::Trace::V1::TraceServiceClient
-          #
-          #   trace_service_client = TraceServiceClient.new
+          #   trace_service_client = Google::Cloud::Trace::V1.new
           #   project_id = ''
           #
           #   # Iterate over all results.
@@ -295,7 +294,7 @@ module Google
               filter: nil,
               order_by: nil,
               options: nil
-            req = Google::Devtools::Cloudtrace::V1::ListTracesRequest.new({
+            req = {
               project_id: project_id,
               view: view,
               page_size: page_size,
@@ -303,9 +302,78 @@ module Google
               end_time: end_time,
               filter: filter,
               order_by: order_by
-            }.delete_if { |_, v| v.nil? })
+            }.delete_if { |_, v| v.nil? }
+            req = Google::Gax::to_proto(req, Google::Devtools::Cloudtrace::V1::ListTracesRequest)
             @list_traces.call(req, options)
           end
+
+          # Gets a single trace by its ID.
+          #
+          # @param project_id [String]
+          #   ID of the Cloud project where the trace data is stored.
+          # @param trace_id [String]
+          #   ID of the trace to return.
+          # @param options [Google::Gax::CallOptions]
+          #   Overrides the default settings for this call, e.g, timeout,
+          #   retries, etc.
+          # @return [Google::Devtools::Cloudtrace::V1::Trace]
+          # @raise [Google::Gax::GaxError] if the RPC is aborted.
+          # @example
+          #   require "google/cloud/trace/v1"
+          #
+          #   trace_service_client = Google::Cloud::Trace::V1.new
+          #   project_id = ''
+          #   trace_id = ''
+          #   response = trace_service_client.get_trace(project_id, trace_id)
+
+          def get_trace \
+              project_id,
+              trace_id,
+              options: nil
+            req = {
+              project_id: project_id,
+              trace_id: trace_id
+            }.delete_if { |_, v| v.nil? }
+            req = Google::Gax::to_proto(req, Google::Devtools::Cloudtrace::V1::GetTraceRequest)
+            @get_trace.call(req, options)
+          end
+
+          # 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.
+          #
+          # @param project_id [String]
+          #   ID of the Cloud project where the trace data is stored.
+          # @param traces [Google::Devtools::Cloudtrace::V1::Traces | Hash]
+          #   The body of the message.
+          #   A hash of the same form as `Google::Devtools::Cloudtrace::V1::Traces`
+          #   can also be provided.
+          # @param options [Google::Gax::CallOptions]
+          #   Overrides the default settings for this call, e.g, timeout,
+          #   retries, etc.
+          # @raise [Google::Gax::GaxError] if the RPC is aborted.
+          # @example
+          #   require "google/cloud/trace/v1"
+          #
+          #   trace_service_client = Google::Cloud::Trace::V1.new
+          #   project_id = ''
+          #   traces = {}
+          #   trace_service_client.patch_traces(project_id, traces)
+
+          def patch_traces \
+              project_id,
+              traces,
+              options: nil
+            req = {
+              project_id: project_id,
+              traces: traces
+            }.delete_if { |_, v| v.nil? }
+            req = Google::Gax::to_proto(req, Google::Devtools::Cloudtrace::V1::PatchTracesRequest)
+            @patch_traces.call(req, options)
+            nil
+          end
         end
       end
     end

data/lib/google/cloud/trace/v1/trace_service_client_config.json

@@ -17,23 +17,32 @@
           "rpc_timeout_multiplier": 1.5,
           "max_rpc_timeout_millis": 30000,
           "total_timeout_millis": 45000
+        },
+        "write_sink": {
+          "initial_retry_delay_millis": 100,
+          "retry_delay_multiplier": 1.2,
+          "max_retry_delay_millis": 1000,
+          "initial_rpc_timeout_millis": 30000,
+          "rpc_timeout_multiplier": 1.5,
+          "max_rpc_timeout_millis": 60000,
+          "total_timeout_millis": 120000
         }
       },
       "methods": {
-        "PatchTraces": {
-          "timeout_millis": 30000,
+        "ListTraces": {
+          "timeout_millis": 60000,
           "retry_codes_name": "idempotent",
           "retry_params_name": "default"
         },
         "GetTrace": {
-          "timeout_millis": 30000,
+          "timeout_millis": 60000,
           "retry_codes_name": "idempotent",
           "retry_params_name": "default"
         },
-        "ListTraces": {
+        "PatchTraces": {
           "timeout_millis": 30000,
-          "retry_codes_name": "idempotent",
-          "retry_params_name": "default"
+          "retry_codes_name": "non_idempotent",
+          "retry_params_name": "write_sink"
         }
       }
     }

data/lib/google/cloud/trace/version.rb

@@ -16,7 +16,7 @@
 module Google
   module Cloud
     module Trace
-      VERSION = "0.27.2".freeze
+      VERSION = "0.28.0".freeze
     end
   end
 end

data/lib/google/devtools/cloudtrace/v1/trace_services_pb.rb

@@ -1,7 +1,7 @@
 # Generated by the protocol buffer compiler.  DO NOT EDIT!
 # Source: google/devtools/cloudtrace/v1/trace.proto for package 'google.devtools.cloudtrace.v1'
 # Original file comments:
-# Copyright 2016 Google Inc.
+# Copyright 2017 Google Inc.
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: google-cloud-trace
 version: !ruby/object:Gem::Version
-  version: 0.27.2
+  version: 0.28.0
 platform: ruby
 authors:
 - Daniel Azuma
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2017-09-20 00:00:00.000000000 Z
+date: 2017-11-15 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: google-cloud-core
@@ -16,14 +16,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.0'
+        version: '1.1'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.0'
+        version: '1.1'
 - !ruby/object:Gem::Dependency
   name: stackdriver-core
   requirement: !ruby/object:Gem::Requirement
@@ -44,14 +44,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.8.0
+        version: 0.10.1
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.8.0
+        version: 0.10.1
 - !ruby/object:Gem::Dependency
   name: minitest
   requirement: !ruby/object:Gem::Requirement
@@ -252,6 +252,7 @@ files:
 - lib/google/cloud/trace/v1.rb
 - lib/google/cloud/trace/v1/doc/google/devtools/cloudtrace/v1/trace.rb
 - lib/google/cloud/trace/v1/doc/google/protobuf/timestamp.rb
+- lib/google/cloud/trace/v1/doc/overview.rb
 - lib/google/cloud/trace/v1/trace_service_client.rb
 - lib/google/cloud/trace/v1/trace_service_client_config.json
 - lib/google/cloud/trace/version.rb
@@ -277,7 +278,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 2.6.13
+rubygems_version: 2.7.2
 signing_key: 
 specification_version: 4
 summary: Application Instrumentation and API Client library for Stackdriver Trace