google-cloud-trace 0.21.0

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

@@ -0,0 +1,199 @@
+# Copyright 2014 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
+    module Trace
+      ##
+      # ResultSet represents the results of a `list_traces` request. It is
+      # an enumerable of the traces found, plus information about the request
+      # and a token to get the next page of results.
+      #
+      class ResultSet
+        include Enumerable
+
+        ##
+        # Create a new ResultSet given an enumerable of result Trace objects,
+        # a next page token (or nil if this is the last page), and all the
+        # query parameters.
+        #
+        # @private
+        #
+        def initialize service, project,
+                       results, next_page_token,
+                       start_time, end_time,
+                       filter: nil,
+                       order_by: nil,
+                       view: nil,
+                       page_size: nil,
+                       page_token: nil
+          @service = service
+          @project = project
+          @results = results
+          @next_page_token = next_page_token
+          @view = view
+          @page_size = page_size
+          @start_time = start_time
+          @end_time = end_time
+          @filter = filter
+          @order_by = order_by
+          @page_token = page_token
+        end
+
+        ##
+        # An `each` method that supports the Enumerable module. Iterates over
+        # the results and yields each, as a {Google::Cloud::Trace::TraceRecord}
+        # object, to the given block. If no block is provided, returns an
+        # Enumerator.
+        #
+        def each &block
+          @results.each(&block)
+        end
+
+        ##
+        # Returns the number of traces in this page of results.
+        #
+        # @return [Integer]
+        #
+        def size
+          @results.size
+        end
+
+        ##
+        # The trace service client that obtained this result set
+        # @private
+        attr_reader :service
+
+        ##
+        # The project ID string.
+        #
+        # @return [String]
+        #
+        attr_reader :project
+
+        ##
+        # The token to pass to `list_traces` to get the next page, or nil if
+        # this is the last page.
+        #
+        # @return [String, nil]
+        #
+        attr_reader :next_page_token
+
+        ##
+        # The `view` query parameter.
+        #
+        # @return [Symbol, nil]
+        #
+        attr_reader :view
+
+        ##
+        # The `page_size` query parameter.
+        #
+        # @return [Integer, nil]
+        #
+        attr_reader :page_size
+
+        ##
+        # The `start_time` query parameter.
+        #
+        # @return [Time, nil]
+        #
+        attr_reader :start_time
+
+        ##
+        # The `end_time` query parameter.
+        #
+        # @return [Time, nil]
+        #
+        attr_reader :end_time
+
+        ##
+        # The `filter` query parameter.
+        #
+        # @return [String, nil]
+        #
+        attr_reader :filter
+
+        ##
+        # The `order_by` query parameter.
+        #
+        # @return [String, nil]
+        #
+        attr_reader :order_by
+
+        ##
+        # The page token used to obtain this page of results.
+        #
+        # @return [String, nil]
+        #
+        attr_reader :page_token
+
+        ##
+        # Returns true if at least one more page of results can be retrieved.
+        #
+        # @return [Boolean]
+        #
+        def results_pending?
+          !next_page_token.nil?
+        end
+
+        ##
+        # Queries the service for the next page of results and returns a new
+        # ResultSet for that page. Returns `nil` if there are no more results.
+        #
+        # @return [Google::Cloud::Trace::ResultSet]
+        #
+        def next_page
+          return nil unless results_pending?
+          service.list_traces \
+            project, start_time, end_time,
+            filter: filter,
+            order_by: order_by,
+            view: view,
+            page_size: page_size,
+            page_token: next_page_token
+        end
+
+        ##
+        # Create a new ResultSet given a Google::Gax::PagedEnumerable::Page,
+        # and all the query parameters.
+        #
+        # @private
+        #
+        def self.from_gax_page service, project_id,
+                               page, start_time, end_time,
+                               filter: nil,
+                               order_by: nil,
+                               view: nil,
+                               page_size: nil,
+                               page_token: nil
+          next_page_token = page.next_page_token
+          next_page_token = nil unless page.next_page_token?
+          results = page.map do |proto|
+            Google::Cloud::Trace::TraceRecord.from_grpc proto
+          end
+          new service, project_id,
+              results, next_page_token,
+              start_time, end_time,
+              filter: filter,
+              order_by: order_by,
+              view: view,
+              page_size: page_size,
+              page_token: page_token
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,166 @@
+# Copyright 2014 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.
+
+
+require "google/cloud/errors"
+require "google/cloud/trace/version"
+require "google/cloud/trace/v1"
+require "google/gax/errors"
+
+module Google
+  module Cloud
+    module Trace
+      ##
+      # Represents the connection to Trace, and exposes the API calls.
+      #
+      # @private
+      #
+      class Service
+        ##
+        # @private
+        attr_accessor :project
+
+        ##
+        # @private
+        attr_accessor :credentials
+
+        ##
+        # @private
+        attr_accessor :host
+
+        ##
+        # @private
+        attr_accessor :timeout
+
+        ##
+        # @private
+        attr_accessor :client_config
+
+        ##
+        # Creates a new Service instance.
+        def initialize project, credentials, host: nil, timeout: nil,
+                       client_config: nil
+          @project = project
+          @credentials = credentials
+          @host = host || V1::TraceServiceApi::SERVICE_ADDRESS
+          @timeout = timeout
+          @client_config = client_config || {}
+        end
+
+        def channel
+          require "grpc"
+          GRPC::Core::Channel.new host, nil, chan_creds
+        end
+
+        def chan_creds
+          return credentials if insecure?
+          require "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::TraceServiceApi.new(
+              service_path: host,
+              channel: channel,
+              timeout: timeout,
+              client_config: client_config,
+              app_name: "gcloud-ruby",
+              app_version: Google::Cloud::Trace::VERSION)
+        end
+        attr_accessor :mocked_lowlevel_client
+
+        ##
+        # Sends new traces to Stackdriver Trace or updates existing traces.
+        def patch_traces traces
+          traces = Array(traces)
+          traces_proto = Google::Devtools::Cloudtrace::V1::Traces.new
+          traces.each do |trace|
+            traces_proto.traces.push trace.to_grpc
+          end
+          execute do
+            lowlevel_client.patch_traces @project, traces_proto
+          end
+          traces
+        end
+
+        ##
+        # Returns a trace given its ID
+        def get_trace trace_id
+          trace_proto = execute do
+            lowlevel_client.get_trace @project, trace_id
+          end
+          Google::Cloud::Trace::TraceRecord.from_grpc trace_proto
+        end
+
+        ##
+        # Searches for traces matching the given criteria.
+        #
+        # rubocop:disable Metrics/MethodLength
+        def list_traces project_id, start_time, end_time,
+                        filter: nil,
+                        order_by: nil,
+                        view: nil,
+                        page_size: nil,
+                        page_token: nil
+          if page_token
+            call_opts = Google::Gax::CallOptions.new page_token: page_token
+          else
+            call_opts = Google::Gax::CallOptions.new
+          end
+          start_proto = Google::Cloud::Trace::Utils.time_to_grpc start_time
+          end_proto = Google::Cloud::Trace::Utils.time_to_grpc end_time
+          paged_enum = execute do
+            lowlevel_client.list_traces project_id,
+                                        view: view,
+                                        page_size: page_size,
+                                        start_time: start_proto,
+                                        end_time: end_proto,
+                                        filter: filter,
+                                        order_by: order_by,
+                                        options: call_opts
+          end
+          Google::Cloud::Trace::ResultSet.from_gax_page \
+            self, project_id,
+            paged_enum.page, start_time, end_time,
+            filter: filter,
+            order_by: order_by,
+            view: view,
+            page_size: page_size,
+            page_token: page_token
+        end
+
+        # @private
+        def inspect
+          "#{self.class}(#{@project})"
+        end
+
+        protected
+
+        def execute
+          yield
+        rescue Google::Gax::GaxError => e
+          # GaxError wraps BadStatus, but exposes it as #cause
+          raise Google::Cloud::Error.from_error(e.cause)
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,450 @@
+# Copyright 2014 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.
+
+
+require "set"
+require "google/devtools/cloudtrace/v1/trace_pb"
+
+module Google
+  module Cloud
+    module Trace
+      ##
+      # Span represents a span in a trace record. Spans are contained in
+      # a trace and arranged in a forest. That is, each span may be a root span
+      # or have a parent span, and may have zero or more children.
+      #
+      class Span
+        ##
+        # The Trace object containing this span.
+        #
+        # @return [Google::Cloud::Trace::TraceRecord]
+        #
+        attr_reader :trace
+
+        ##
+        # The TraceSpan object representing this span's parent, or `nil` if
+        # this span is a root span.
+        #
+        # @return [Google::Cloud::Trace::Span, nil]
+        #
+        attr_reader :parent
+
+        ##
+        # The numeric ID of this span.
+        #
+        # @return [Integer]
+        #
+        attr_reader :span_id
+
+        ##
+        # The ID of the parent span, as an integer that may be zero if this
+        # is a true root span.
+        #
+        # Note that it is possible for a span to be "orphaned", that is, to be
+        # a root span with a nonzero parent ID, indicating that parent has not
+        # (yet) been written. In that case, `parent` will return nil, but
+        # `parent_span_id` will have a value.
+        #
+        # @return [Integer]
+        #
+        attr_reader :parent_span_id
+
+        ##
+        # The kind of this span.
+        #
+        # @return [Google::Cloud::Trace::SpanKind]
+        #
+        attr_accessor :kind
+
+        ##
+        # The name of this span.
+        #
+        # @return [String]
+        #
+        attr_accessor :name
+
+        ##
+        # The starting timestamp of this span in UTC, or `nil` if the
+        # starting timestamp has not yet been populated.
+        #
+        # @return [Time, nil]
+        #
+        attr_accessor :start_time
+
+        ##
+        # The ending timestamp of this span in UTC, or `nil` if the
+        # ending timestamp has not yet been populated.
+        #
+        # @return [Time, nil]
+        #
+        attr_accessor :end_time
+
+        ##
+        # The properties of this span.
+        #
+        # @return [Hash{String => String}]
+        #
+        attr_reader :labels
+
+        ##
+        # Create an empty Span object.
+        #
+        # @private
+        #
+        def initialize trace, id, parent_span_id, parent, name, kind,
+                       start_time, end_time, labels
+          @trace = trace
+          @span_id = id
+          @parent_span_id = parent_span_id
+          @parent = parent
+          @children = []
+          @name = name
+          @kind = kind
+          @start_time = start_time
+          @end_time = end_time
+          @labels = labels
+        end
+
+        ##
+        # Standard value equality check for this object.
+        #
+        # @param [Object] other
+        # @return [Boolean]
+        #
+        # rubocop:disable Metrics/AbcSize
+        def eql? other
+          other.is_a?(Google::Cloud::Trace::Span) &&
+            trace.trace_context == other.trace.trace_context &&
+            span_id == other.span_id &&
+            parent_span_id == other.parent_span_id &&
+            same_children?(other) &&
+            kind == other.kind &&
+            name == other.name &&
+            start_time == other.start_time &&
+            end_time == other.end_time &&
+            labels == other.labels
+        end
+        alias_method :==, :eql?
+
+        ##
+        # Create a new Span object from a TraceSpan protobuf and insert it
+        # into the given trace.
+        #
+        # @param [Google::Devtools::Cloudtrace::V1::TraceSpan] span_proto The
+        #     span protobuf from the V1 gRPC Trace API.
+        # @param [Google::Cloud::Trace::TraceRecord] trace The trace object
+        #     to contain the span.
+        # @return [Google::Cloud::Trace::Span] A corresponding Span object.
+        #
+        def self.from_grpc span_proto, trace
+          labels = {}
+          span_proto.labels.each { |k, v| labels[k] = v }
+          span_kind = SpanKind.get span_proto.kind
+          start_time =
+            Google::Cloud::Trace::Utils.grpc_to_time span_proto.start_time
+          end_time =
+            Google::Cloud::Trace::Utils.grpc_to_time span_proto.end_time
+          trace.create_span span_proto.name,
+                            parent_span_id: span_proto.parent_span_id.to_i,
+                            span_id: span_proto.span_id.to_i,
+                            kind: span_kind,
+                            start_time: start_time,
+                            end_time: end_time,
+                            labels: labels
+        end
+
+        ##
+        # Convert this Span object to an equivalent TraceSpan protobuf suitable
+        # for the V1 gRPC Trace API.
+        #
+        # @param [Integer] default_parent_id The parent span ID to use if the
+        #     span has no parent in the trace tree. Optional; defaults to 0.
+        # @return [Google::Devtools::Cloudtrace::V1::TraceSpan] The generated
+        #     protobuf.
+        #
+        def to_grpc default_parent_id = 0
+          start_proto = Google::Cloud::Trace::Utils.time_to_grpc start_time
+          end_proto = Google::Cloud::Trace::Utils.time_to_grpc end_time
+          Google::Devtools::Cloudtrace::V1::TraceSpan.new \
+            span_id: span_id.to_i,
+            kind: kind.to_sym,
+            name: name,
+            start_time: start_proto,
+            end_time: end_proto,
+            parent_span_id: parent_span_id || default_parent_id,
+            labels: labels
+        end
+
+        ##
+        # Returns true if this span exists. A span exists until it has been
+        # removed from its trace.
+        #
+        # @return [Boolean]
+        #
+        def exists?
+          !@trace.nil?
+        end
+
+        ##
+        # Returns the trace context in effect within this span.
+        #
+        # @return [Stackdriver::Core::TraceContext]
+        #
+        def trace_context
+          ensure_exists!
+          trace.trace_context.with span_id: span_id
+        end
+
+        ##
+        # Returns the trace ID for this span.
+        #
+        # @return [String] The trace ID string.
+        #
+        def trace_id
+          ensure_exists!
+          trace.trace_id
+        end
+
+        ##
+        # Returns a list of children of this span.
+        #
+        # @return [Array{TraceSpan}] The children.
+        #
+        def children
+          ensure_exists!
+          @children.dup
+        end
+
+        ##
+        # Creates a new child span under this span.
+        #
+        # @param [String] name The name of the span.
+        # @param [Integer] span_id The numeric ID of the span, or nil to
+        #     generate a new random unique ID. Optional (defaults to nil).
+        # @param [SpanKind] kind The kind of span. Optional.
+        # @param [Time] start_time The starting timestamp, or nil if not yet
+        #     specified. Optional (defaults to nil).
+        # @param [Time] end_time The ending timestamp, or nil if not yet
+        #     specified. Optional (defaults to nil).
+        # @param [Hash{String=>String}] labels The span properties. Optional
+        #     (defaults to empty).
+        # @return [TraceSpan] The created span.
+        #
+        # @example
+        #   require "google/cloud/trace"
+        #
+        #   trace = Google::Cloud::Trace.new trace_context
+        #   span = trace.create_span "root_span"
+        #   subspan = span.create_span "subspan"
+        #
+        def create_span name, span_id: nil, kind: SpanKind::UNSPECIFIED,
+                        start_time: nil, end_time: nil,
+                        labels: {}
+          ensure_exists!
+          span = trace.internal_create_span self, span_id, self.span_id, name,
+                                            kind, start_time, end_time, labels
+          @children << span
+          span
+        end
+
+        ##
+        # Creates a root span around the given block. Automatically populates
+        # the start and end timestamps. The span (with start time but not end
+        # time populated) is yielded to the block.
+        #
+        # @param [String] name The name of the span.
+        # @param [SpanKind] kind The kind of span. Optional.
+        # @param [Hash{String=>String}] labels The span properties. Optional
+        #     (defaults to empty).
+        # @return [TraceSpan] The created span.
+        #
+        # @example
+        #   require "google/cloud/trace"
+        #
+        #   trace = Google::Cloud::Trace.new trace_context
+        #   trace.in_span "root_span" do |span|
+        #     # Do stuff...
+        #     span.in_span "subspan" do |subspan|
+        #       # Do subspan stuff...
+        #     end
+        #     # Do stuff...
+        #   end
+        #
+        def in_span name, kind: SpanKind::UNSPECIFIED, labels: {}
+          span = create_span name, kind: kind, labels: labels
+          span.start!
+          yield span
+        ensure
+          span.finish!
+        end
+
+        ##
+        # Sets the starting timestamp for this span to the current time.
+        # Asserts that the timestamp has not yet been set, and throws a
+        # RuntimeError if that is not the case.
+        # Also ensures that all ancestor spans have already started, and
+        # starts them if not.
+        #
+        def start!
+          fail "Span already started" if start_time
+          ensure_started
+        end
+
+        ##
+        # Sets the ending timestamp for this span to the current time.
+        # Asserts that the timestamp has not yet been set, and throws a
+        # RuntimeError if that is not the case.
+        # Also ensures that all descendant spans have also finished, and
+        # finishes them if not.
+        #
+        def finish!
+          fail "Span not yet started" unless start_time
+          fail "Span already finished" if end_time
+          ensure_finished
+        end
+
+        ##
+        # Sets the starting timestamp for this span to the current time, if
+        # it has not yet been set. Also ensures that all ancestor spans have
+        # also been started.
+        # Does nothing if the starting timestamp for this span is already set.
+        #
+        def ensure_started
+          ensure_exists!
+          unless start_time
+            self.start_time = ::Time.now.utc
+            parent.ensure_started if parent
+          end
+          self
+        end
+
+        ##
+        # Sets the ending timestamp for this span to the current time, if
+        # it has not yet been set. Also ensures that all descendant spans have
+        # also been finished.
+        # Does nothing if the ending timestamp for this span is already set.
+        #
+        def ensure_finished
+          ensure_exists!
+          unless end_time
+            self.end_time = ::Time.now.utc
+            @children.each(&:ensure_finished)
+          end
+          self
+        end
+
+        ##
+        # Deletes this span, and all descendant spans. After this completes,
+        # {Span#exists?} will return `false`.
+        #
+        def delete
+          ensure_exists!
+          @children.each(&:delete)
+          parent.remove_child(self) if parent
+          trace.remove_span(self)
+          @trace = nil
+          @parent = nil
+          self
+        end
+
+        ##
+        # Moves this span under a new parent, which must be part of the same
+        # trace. The entire tree under this span moves with it.
+        #
+        # @param [Google::Cloud::Trace::Span] new_parent The new parent.
+        #
+        # @example
+        #   require "google/cloud/trace"
+        #
+        #   trace = Google::Cloud::Trace.new
+        #   root1 = trace.create_span "root_span_1"
+        #   root2 = trace.create_span "root_span_2"
+        #   subspan = root1.create_span "subspan"
+        #   subspan.move_under root2
+        #
+        def move_under new_parent
+          ensure_exists!
+          ensure_no_cycle! new_parent
+          if parent
+            parent.remove_child self
+          else
+            trace.remove_root self
+          end
+          if new_parent
+            new_parent.add_child self
+            @parent_span_id = new_parent.span_id
+          else
+            trace.add_root self
+            @parent_span_id = 0
+          end
+          @parent = new_parent
+          self
+        end
+
+        ##
+        # Add the given span to this span's child list.
+        #
+        # @private
+        #
+        def add_child child
+          @children << child
+        end
+
+        ##
+        # Remove the given span from this span's child list.
+        #
+        # @private
+        #
+        def remove_child child
+          @children.delete child
+        end
+
+        ##
+        # Ensure this span exists (i.e. has not been deleted) and throw a
+        # RuntimeError if not.
+        #
+        # @private
+        #
+        def ensure_exists!
+          fail "Span has been deleted" unless trace
+        end
+
+        ##
+        # Ensure moving this span under the given parent would not result
+        # in a cycle, and throw a RuntimeError if it would.
+        #
+        # @private
+        #
+        def ensure_no_cycle! new_parent
+          ptr = new_parent
+          until ptr.nil?
+            fail "Move would result in a cycle" if ptr.equal?(self)
+            ptr = ptr.parent
+          end
+        end
+
+        ##
+        # Returns true if this span has the same children as the given other.
+        #
+        # @private
+        #
+        def same_children? other
+          child_ids = @children.map(&:span_id)
+          other_child_ids = other.children.map(&:span_id)
+          ::Set.new(child_ids) == ::Set.new(other_child_ids)
+        end
+      end
+    end
+  end
+end