opencensus-stackdriver 0.1.0.pre1

data/Rakefile

@@ -0,0 +1,21 @@
+require "bundler/gem_tasks"
+require "rake/testtask"
+require "yard"
+
+require "rubocop/rake_task"
+RuboCop::RakeTask.new
+
+Rake::TestTask.new :test do |t|
+  t.libs << "test"
+  t.libs << "lib"
+  t.test_files = FileList["test/**/*_test.rb"]
+  t.warning = false
+end
+
+YARD::Rake::YardocTask.new do |t|
+ t.files   = ['lib/**/*.rb']   # optional
+ t.options = ['--output-dir', 'docs/api'] # optional
+ t.stats_options = ['--list-undoc']         # optional
+end
+
+task :default => [:test, :rubocop, :yard]

data/lib/opencensus-stackdriver.rb

@@ -0,0 +1,15 @@
+# Copyright 2018 OpenCensus Authors
+#
+# 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 "opencensus/stackdriver"

data/lib/opencensus/stackdriver.rb

@@ -0,0 +1,25 @@
+# Copyright 2018 OpenCensus Authors
+#
+# 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 "opencensus"
+
+module OpenCensus
+  ## Information about the Stackdriver exporter plugin
+  module Stackdriver
+  end
+end
+
+require "opencensus/stackdriver/version"
+require "opencensus/trace/exporters/stackdriver"
+require "opencensus/trace/exporters/stackdriver/converter"

data/lib/opencensus/stackdriver/version.rb

@@ -0,0 +1,20 @@
+# Copyright 2018 OpenCensus Authors
+#
+# 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 OpenCensus
+  module Stackdriver
+    ## Current OpenCensus Stackdriver plugin version
+    VERSION = "0.1.0.pre1".freeze
+  end
+end

data/lib/opencensus/trace/exporters/stackdriver.rb

@@ -0,0 +1,259 @@
+# Copyright 2018 OpenCensus Authors
+#
+# 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.
+
+gem "google-cloud-trace"
+gem "concurrent-ruby"
+
+require "concurrent"
+require "google/cloud/trace"
+require "google/cloud/trace/v2"
+
+module OpenCensus
+  module Trace
+    module Exporters
+      ##
+      # The Stackdriver exporter for OpenCensus Trace exports captured spans
+      # to a Google Stackdriver project. It calls the Stackdriver Trace API in
+      # a background thread pool.
+      #
+      class Stackdriver
+        ##
+        # Create a Stackdriver exporter.
+        #
+        # @param [String] project_id The project identifier for the Stackdriver
+        #     Trace service you are connecting to. If you are running on Google
+        #     Cloud hosting (e.g. Compute Engine, Kubernetes Engine, or App
+        #     Engine), this parameter is optional and will default to the
+        #     hosting project. Otherwise, it is required.
+        # @param [String, Hash, Google::Auth::Credentials] credentials The
+        #     Stackdriver API credentials, which can be a path to a keyfile as
+        #     a String, the contents of a keyfile as a Hash, or a
+        #     Google::Auth::Credentials object. If you are running on Google
+        #     Cloud hosting (e.g. Compute Engine, Kubernetes Engine, or App
+        #     Engine), this parameter is optional and will default to the
+        #     credentials provided by the hosting project. Otherwise, it is
+        #     required.
+        # @param [String, Array<String>] scope The OAuth 2.0 scopes controlling
+        #     the set of resources and operations the API client can access.
+        #     Optional. Most applications can leave this set to the default.
+        # @param [Integer] timeout The default timeout for API requests, in
+        #     seconds. Optional.
+        # @param [Hash] client_config An optional set of additional
+        #     configuration values for the API connection.
+        # @param [Integer] max_queue The maximum number of API requests that
+        #     can be queued for background operation. If the queue exceeds this
+        #     value, additional requests will be run in the calling thread
+        #     rather than in the background. Set to 0 to allow the queue to
+        #     grow indefinitely. Default is 1000.
+        # @param [Integer] max_threads The maximum number of threads that can
+        #     be spun up to handle API requests. Default is 1. If set to 0,
+        #     backgrounding will be disabled and all requests will run in the
+        #     calling thread.
+        # @param [Integer] auto_terminate_time The time in seconds allotted to
+        #     complete any pending background requests when Ruby is exiting.
+        #
+        def initialize \
+            project_id: nil,
+            credentials: nil,
+            scope: nil,
+            timeout: nil,
+            client_config: nil,
+            max_queue: 1000,
+            max_threads: 1,
+            auto_terminate_time: 10,
+            mock_client: nil
+          @project_id = final_project_id project_id
+
+          @executor = create_executor max_threads, max_queue
+          if auto_terminate_time
+            terminate_at_exit! @executor, auto_terminate_time
+          end
+
+          if mock_client
+            @client_promise =
+              Concurrent::Promise.fulfill mock_client, executor: @executor
+          else
+            credentials = final_credentials credentials, scope
+            scope ||= Google::Cloud.configure.trace.scope
+            timeout ||= Google::Cloud.configure.trace.timeout
+            client_config ||= Google::Cloud.configure.trace.client_config
+            @client_promise = create_client_promise \
+              @executor, credentials, scope, client_config, timeout
+          end
+        end
+
+        ##
+        # The project ID
+        # @return [String]
+        #
+        attr_reader :project_id
+
+        ##
+        # Export spans to Stackdriver asynchronously.
+        #
+        # @param [Array<OpenCensus::Trace::Span>] spans The captured spans to
+        #     export to Stackdriver
+        #
+        def export spans
+          raise "Exporter is no longer running" unless @executor.running?
+
+          @client_promise.execute
+          export_promise = @client_promise.then do |client|
+            export_as_batch(client, spans)
+          end
+          export_promise.on_error do |reason|
+            warn "Unable to export to Stackdriver because: #{reason}"
+          end
+
+          true
+        end
+
+        ##
+        # Returns true if this exporter is running and will accept further
+        # export requests. Returns false once the exporter begins shutting down.
+        #
+        # @return [boolean]
+        #
+        def running?
+          @executor.running?
+        end
+
+        ##
+        # Returns true if this exporter has finished shutting down and all
+        # pending spans have been sent.
+        #
+        # @return [boolean]
+        #
+        def shutdown?
+          @executor.shutdown?
+        end
+
+        ##
+        # Returns true if this exporter has begun shutting down and is no
+        # longer accepting export requests, but is still running queued
+        # requests in the background.
+        #
+        # @return [boolean]
+        #
+        def shuttingdown?
+          @executor.shuttingdown?
+        end
+
+        ##
+        # Begin shutting down the exporter gracefully. After this operation is
+        # performed, the exporter will no longer accept export requests, but
+        # will finish any pending requests in the background.
+        #
+        def shutdown
+          @executor.shutdown
+          self
+        end
+
+        ##
+        # Begin shutting down the exporter forcefully. After this operation is
+        # performed, the exporter will no longer accept export requests, and
+        # will finish any currently running export requests, but will cancel
+        # all requests that are still pending in the queue.
+        #
+        def kill
+          @executor.kill
+          self
+        end
+
+        ##
+        # Wait for the exporter to finish shutting down.
+        #
+        # @param [Integer, nil] timeout A timeout in seconds, or nil for no
+        #     timeout.
+        # @return [boolean] true if the exporter is shut down, or false if the
+        #     wait timed out.
+        #
+        def wait_for_termination timeout = nil
+          @executor.wait_for_termination timeout
+        end
+
+        private
+
+        # Create the executor
+        def create_executor max_threads, max_queue
+          if max_threads >= 1
+            Concurrent::ThreadPoolExecutor.new \
+              min_length: 1, max_length: max_threads,
+              max_queue: max_queue, fallback_policy: :caller_runs,
+              auto_terminate: false
+          else
+            Concurrent::ImmediateExecutor.new
+          end
+        end
+
+        # Create the client promise.
+        # We create the client lazily so grpc doesn't get initialized until
+        # we actually need it. This is important because if it is intialized
+        # too early, before a fork, it can go into a bad state.
+        def create_client_promise executor, credentials, scopes, client_config,
+                                  timeout
+          Concurrent::Promise.new executor: executor do
+            Google::Cloud::Trace::V2.new(
+              credentials: credentials,
+              scopes: scopes,
+              client_config: client_config,
+              timeout: timeout,
+              lib_name: "opencensus",
+              lib_version: OpenCensus::Stackdriver::VERSION
+            )
+          end
+        end
+
+        # Set up an at_exit hook that shuts the exporter down.
+        def terminate_at_exit! executor, timeout
+          at_exit do
+            executor.shutdown
+            unless executor.wait_for_termination timeout
+              executor.kill
+              executor.wait_for_termination timeout
+            end
+          end
+        end
+
+        # Fall back to default project ID
+        def final_project_id project_id
+          project_id ||
+            Google::Cloud.configure.trace.project_id ||
+            Google::Cloud.configure.project_id ||
+            Google::Cloud.env.project_id
+        end
+
+        # Fall back to default credentials, and wrap in a creds object
+        def final_credentials credentials, scope
+          credentials ||=
+            Google::Cloud.configure.trace.credentials ||
+            Google::Cloud.configure.credentials ||
+            Google::Cloud::Trace::Credentials.default(scope: scope)
+          unless credentials.is_a? Google::Auth::Credentials
+            credentials =
+              Google::Cloud::Trace::Credentials.new credentials, scope: scope
+          end
+          credentials
+        end
+
+        # Export a list of spans in a single batch write, in the current thread
+        def export_as_batch client, spans
+          converter = Converter.new project_id
+          span_protos = Array(spans).map { |span| converter.convert_span span }
+          client.batch_write_spans "projects/#{project_id}", span_protos
+        end
+      end
+    end
+  end
+end

data/lib/opencensus/trace/exporters/stackdriver/converter.rb

@@ -0,0 +1,356 @@
+# Copyright 2018 OpenCensus Authors
+#
+# 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/devtools/cloudtrace/v2/trace_pb"
+require "google/protobuf/well_known_types"
+
+module OpenCensus
+  module Trace
+    module Exporters
+      class Stackdriver
+        ##
+        # An object that converts OpenCensus span data objects to Stackdriver
+        # Trace V2 protos.
+        #
+        # You should use one converter instance to convert the spans for a
+        # single export request, because the converter will keep track of and
+        # omit duplicate stack traces. Use a new converter instance for the
+        # next request.
+        #
+        # @private
+        #
+        class Converter
+          ##
+          # @private
+          # Alias for the V2 Cloudtrace protos namespace
+          #
+          TraceProtos = Google::Devtools::Cloudtrace::V2
+
+          ##
+          # Create a converter
+          #
+          # @param [String] project_id Google project ID
+          #
+          def initialize project_id
+            @project_id = project_id
+            @stack_trace_hash_ids = {}
+          end
+
+          # rubocop:disable Metrics/AbcSize
+
+          ##
+          # Convert a span object.
+          #
+          # @param [OpenCensus::Trace::Span] obj OpenCensus span object
+          # @return [Google::Devtools::Cloudtrace::V2::Span] The generated
+          #     proto
+          #
+          def convert_span obj
+            TraceProtos::Span.new \
+              name: make_resource_name(@project_id, obj.trace_id, obj.span_id),
+              span_id: obj.span_id,
+              parent_span_id: obj.parent_span_id || "",
+              display_name: convert_truncatable_string(obj.name),
+              start_time: convert_time(obj.start_time),
+              end_time: convert_time(obj.end_time),
+              attributes:
+                convert_attributes(obj.attributes,
+                                   obj.dropped_attributes_count),
+              stack_trace:
+                convert_stack_trace(obj.stack_trace, obj.dropped_frames_count,
+                                    obj.stack_trace_hash_id),
+              time_events:
+                convert_time_events(obj.time_events,
+                                    obj.dropped_annotations_count,
+                                    obj.dropped_message_events_count),
+              links: convert_links(obj.links, obj.dropped_links_count),
+              status: convert_optional_status(obj.status),
+              same_process_as_parent_span:
+                convert_optional_bool(obj.same_process_as_parent_span),
+              child_span_count: convert_optional_int32(obj.child_span_count)
+          end
+
+          # rubocop:enable Metrics/AbcSize
+
+          ##
+          # Make a span resource name.
+          #
+          # @param [String] project_id The project ID
+          # @param [String] trace_id The project ID
+          # @param [String] span_id The project ID
+          # @return [String] The resource na,e
+          #
+          def make_resource_name project_id, trace_id, span_id
+            "projects/#{project_id}/traces/#{trace_id}/spans/#{span_id}"
+          end
+
+          ##
+          # Create a truncatable string proto.
+          #
+          # @param [String] str The string
+          # @param [Integer] truncated_byte_count The number of bytes omitted.
+          #     Defaults to 0.
+          # @return [Google::Devtools::Cloudtrace::V2::TruncatableString] The
+          #     generated proto
+          #
+          def make_truncatable_string str, truncated_byte_count = 0
+            TraceProtos::TruncatableString.new \
+              value: str,
+              truncated_byte_count: truncated_byte_count
+          end
+
+          ##
+          # Convert a truncatable string object.
+          #
+          # @param [OpenCensus::Trace::TruncatableString] obj OpenCensus
+          #     truncatable string object
+          # @return [Google::Devtools::Cloudtrace::V2::TruncatableString] The
+          #     generated proto
+          #
+          def convert_truncatable_string obj
+            make_truncatable_string obj.value, obj.truncated_byte_count
+          end
+
+          ##
+          # Convert a time object.
+          #
+          # @param [Time] time Ruby Time object
+          # @return [Google::Protobuf::Timestamp] The generated proto
+          #
+          def convert_time time
+            proto = Google::Protobuf::Timestamp.new
+            proto.from_time(time)
+            proto
+          end
+
+          ##
+          # Convert a value that can be used for an attribute.
+          #
+          # @param [OpenCensus::Trace::TruncatableString, Integer, boolean]
+          #     obj Object to convert
+          # @return [Google::Devtools::Cloudtrace::V2::AttributeValue] The
+          #     generated proto
+          #
+          def convert_attribute_value obj
+            case obj
+            when OpenCensus::Trace::TruncatableString
+              TraceProtos::AttributeValue.new \
+                string_value: convert_truncatable_string(obj)
+            when Integer
+              TraceProtos::AttributeValue.new int_value: obj
+            when true, false
+              TraceProtos::AttributeValue.new bool_value: obj
+            end
+          end
+
+          ##
+          # Convert an attributes hash
+          #
+          # @param [Hash] attributes The map of attribute values to convert
+          # @param [Integer] dropped_attributes_count Number of dropped
+          # @return [Google::Devtools::Cloudtrace::V2::Attributes] The
+          #     generated proto
+          #
+          def convert_attributes attributes, dropped_attributes_count
+            attribute_map = {}
+            attributes.each do |k, v|
+              attribute_map[k] = convert_attribute_value v
+            end
+            TraceProtos::Span::Attributes.new \
+              attribute_map: attribute_map,
+              dropped_attributes_count: dropped_attributes_count
+          end
+
+          ##
+          # Convert a single stack frame as a Thread::Backtrace::Location
+          #
+          # @param [Thread::Backtrace::Location] frame The backtrace element to
+          #     convert
+          # @return [Google::Devtools::Cloudtrace::V2::StackTrace::StackFrame]
+          #     The generated proto
+          #
+          def convert_stack_frame frame
+            TraceProtos::StackTrace::StackFrame.new \
+              function_name: make_truncatable_string(frame.label),
+              file_name: make_truncatable_string(frame.path),
+              line_number: frame.lineno
+          end
+
+          ##
+          # Convert a full backtrace.
+          #
+          # @param [Array<Thread::Backtrace::Location>] backtrace The backtrace
+          #     element array to convert
+          # @param [Integer] dropped_frames_count Frames that were dropped
+          # @param [Integer] stack_trace_hash_id Hash of the data
+          # @return [Google::Devtools::Cloudtrace::V2::StackTrace] The
+          #     generated proto
+          #
+          def convert_stack_trace backtrace, dropped_frames_count,
+                                  stack_trace_hash_id
+            if @stack_trace_hash_ids[stack_trace_hash_id]
+              return TraceProtos::StackTrace.new \
+                stack_trace_hash_id: stack_trace_hash_id
+            end
+            @stack_trace_hash_ids[stack_trace_hash_id] = true
+            frame_protos = backtrace.map { |frame| convert_stack_frame(frame) }
+            frames_proto = TraceProtos::StackTrace::StackFrames.new \
+              frame: frame_protos,
+              dropped_frames_count: dropped_frames_count
+            TraceProtos::StackTrace.new \
+              stack_frames: frames_proto,
+              stack_trace_hash_id: stack_trace_hash_id
+          end
+
+          ##
+          # Convert an annotation object
+          #
+          # @param [OpenCensus::Trace::Annotation] annotation The annotation
+          #     object to convert
+          # @return
+          #     [Google::Devtools::Cloudtrace::V2::Span::TimeEvent::Annotation]
+          #     The generated proto
+          #
+          def convert_annotation annotation
+            annotation_proto = TraceProtos::Span::TimeEvent::Annotation.new \
+              description: convert_truncatable_string(annotation.description),
+              attributes:
+                convert_attributes(annotation.attributes,
+                                   annotation.dropped_attributes_count)
+            TraceProtos::Span::TimeEvent.new \
+              time: convert_time(annotation.time),
+              annotation: annotation_proto
+          end
+
+          ##
+          # Convert a message event object
+          #
+          # @param [OpenCensus::Trace::MessageEvent] message_event The message
+          #     event object to convert
+          # @return
+          #    [Google::Devtools::Cloudtrace::V2::Span::TimeEvent::MessageEvent]
+          #    The generated proto
+          #
+          def convert_message_event message_event
+            message_event_proto =
+              TraceProtos::Span::TimeEvent::MessageEvent.new \
+                type: message_event.type,
+                id: message_event.id,
+                uncompressed_size_bytes: message_event.uncompressed_size,
+                compressed_size_bytes: message_event.compressed_size
+            Google::Devtools::Cloudtrace::V2::Span::TimeEvent.new \
+              time: convert_time(message_event.time),
+              message_event: message_event_proto
+          end
+
+          ##
+          # Convert a list of time event objects
+          #
+          # @param [Array<OpenCensus::Trace::TimeEvent>] time_events The time
+          #     event objects to convert
+          # @param [Integer] dropped_annotations_count Number of dropped
+          #     annotations
+          # @param [Integer] dropped_message_events_count Number of dropped
+          #     message events
+          # @return [Google::Devtools::Cloudtrace::V2::Span::TimeEvents] The
+          #     generated proto
+          #
+          def convert_time_events time_events, dropped_annotations_count,
+                                  dropped_message_events_count
+            time_event_protos = time_events.map do |time_event|
+              case time_event
+              when OpenCensus::Trace::Annotation
+                convert_annotation time_event
+              when OpenCensus::Trace::MessageEvent
+                convert_message_event time_event
+              else
+                nil
+              end
+            end.compact
+            TraceProtos::Span::TimeEvents.new \
+              time_event: time_event_protos,
+              dropped_annotations_count: dropped_annotations_count,
+              dropped_message_events_count: dropped_message_events_count
+          end
+
+          ##
+          # Convert a link object
+          #
+          # @param [OpenCensus::Trace::Link] link The link object to convert
+          # @return [Google::Devtools::Cloudtrace::V2::Span::Link] The
+          #     generated proto
+          #
+          def convert_link link
+            TraceProtos::Span::Link.new \
+              trace_id: link.trace_id,
+              span_id: link.span_id,
+              type: link.type,
+              attributes:
+                convert_attributes(link.attributes,
+                                   link.dropped_attributes_count)
+          end
+
+          ##
+          # Convert a list of link objects
+          #
+          # @param [Array<OpenCensus::Trace::Link>] links The link objects to
+          #     convert
+          # @param [Integer] dropped_links_count Number of dropped links
+          # @return [Google::Devtools::Cloudtrace::V2::Span::Links] The
+          #     generated proto
+          #
+          def convert_links links, dropped_links_count
+            TraceProtos::Span::Links.new \
+              link: links.map { |link| convert_link link },
+              dropped_links_count: dropped_links_count
+          end
+
+          ##
+          # Convert a nullable status object
+          #
+          # @param [OpenCensus::Trace::Status, nil] status The status object to
+          #     convert, or nil if absent
+          # @return [Google::Rpc::Status, nil] The generated proto, or nil
+          #
+          def convert_optional_status status
+            return nil if status.nil?
+            Google::Rpc::Status.new code: status.code, message: status.message
+          end
+
+          ##
+          # Convert a nullable boolean object
+          #
+          # @param [boolean, nil] value The value to convert, or nil if absent
+          # @return [Google::Protobuf::BoolValue, nil] Generated proto, or nil
+          #
+          def convert_optional_bool value
+            return nil if value.nil?
+            Google::Protobuf::BoolValue.new value: value
+          end
+
+          ##
+          # Convert a nullable int32 object
+          #
+          # @param [Integer, nil] value The value to convert, or nil if absent
+          # @return [Google::Protobuf::Int32Value, nil] Generated proto, or nil
+          #
+          def convert_optional_int32 value
+            return nil if value.nil?
+            Google::Protobuf::Int32Value.new value: value
+          end
+        end
+      end
+    end
+  end
+end