opentelemetry-sdk 0.2.0

data/lib/opentelemetry/sdk/trace/export.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+# Copyright 2019 OpenTelemetry Authors
+#
+# SPDX-License-Identifier: Apache-2.0
+
+module OpenTelemetry
+  module SDK
+    module Trace
+      # The Export module contains the built-in exporters for the OpenTelemetry
+      # reference implementation.
+      module Export
+        # Result codes for the SpanExporter#export method.
+
+        # The export operation finished successfully.
+        SUCCESS = 0
+
+        # The export operation finished with an error, but retrying may
+        # succeed.
+        FAILED_RETRYABLE = 1
+
+        # The export operation finished with an error, the caller should not
+        # try to export the same data again.
+        FAILED_NOT_RETRYABLE = 2
+      end
+    end
+  end
+end
+
+require 'opentelemetry/sdk/trace/export/batch_span_processor'
+require 'opentelemetry/sdk/trace/export/console_span_exporter'
+require 'opentelemetry/sdk/trace/export/in_memory_span_exporter'
+require 'opentelemetry/sdk/trace/export/multi_span_exporter'
+require 'opentelemetry/sdk/trace/export/noop_span_exporter'
+require 'opentelemetry/sdk/trace/export/simple_span_processor'

data/lib/opentelemetry/sdk/trace/export/batch_span_processor.rb

@@ -0,0 +1,149 @@
+# frozen_string_literal: true
+
+# Copyright 2019 OpenTelemetry Authors
+#
+# SPDX-License-Identifier: Apache-2.0
+
+require 'timeout'
+
+module OpenTelemetry
+  module SDK
+    module Trace
+      module Export
+        # Implementation of the duck type SpanProcessor that batches spans
+        # exported by the SDK then pushes them to the exporter pipeline.
+        #
+        # All spans reported by the SDK implementation are first added to a
+        # synchronized queue (with a {max_queue_size} maximum size, after the
+        # size is reached spans are dropped) and exported every
+        # schedule_delay_millis to the exporter pipeline in batches of
+        # max_export_batch_size.
+        #
+        # If the queue gets half full a preemptive notification is sent to the
+        # worker thread that exports the spans to wake up and start a new
+        # export cycle.
+        #
+        # max_export_attempts attempts are made to export each batch, while
+        # export fails with {FAILED_RETRYABLE}, backing off linearly in 100ms
+        # increments.
+        class BatchSpanProcessor
+          EXPORTER_TIMEOUT_MILLIS = 30_000
+          SCHEDULE_DELAY_MILLIS = 5_000
+          MAX_QUEUE_SIZE = 2048
+          MAX_EXPORT_BATCH_SIZE = 512
+          MAX_EXPORT_ATTEMPTS = 5
+          private_constant(:SCHEDULE_DELAY_MILLIS, :MAX_QUEUE_SIZE, :MAX_EXPORT_BATCH_SIZE, :MAX_EXPORT_ATTEMPTS)
+
+          def initialize(exporter:,
+                         exporter_timeout_millis: EXPORTER_TIMEOUT_MILLIS,
+                         schedule_delay_millis: SCHEDULE_DELAY_MILLIS,
+                         max_queue_size: MAX_QUEUE_SIZE,
+                         max_export_batch_size: MAX_EXPORT_BATCH_SIZE,
+                         max_export_attempts: MAX_EXPORT_ATTEMPTS)
+            raise ArgumentError if max_export_batch_size > max_queue_size
+
+            @exporter = exporter
+            @exporter_timeout_seconds = exporter_timeout_millis / 1000.0
+            @mutex = Mutex.new
+            @condition = ConditionVariable.new
+            @keep_running = true
+            @delay_seconds = schedule_delay_millis / 1000.0
+            @max_queue_size = max_queue_size
+            @batch_size = max_export_batch_size
+            @export_attempts = max_export_attempts
+            @spans = []
+            @thread = Thread.new { work }
+          end
+
+          # does nothing for this processor
+          def on_start(span)
+            # noop
+          end
+
+          # adds a span to the batcher, threadsafe may block on lock
+          def on_finish(span) # rubocop:disable Metrics/AbcSize
+            return unless span.context.trace_flags.sampled?
+
+            lock do
+              n = spans.size + 1 - max_queue_size
+              spans.shift(n) if n.positive?
+              spans << span
+              @condition.signal if spans.size > max_queue_size / 2
+            end
+          end
+
+          # shuts the consumer thread down and flushes the current accumulated buffer
+          # will block until the thread is finished
+          def shutdown
+            lock do
+              @keep_running = false
+              @condition.signal
+            end
+
+            @thread.join
+            flush
+            @exporter.shutdown
+          end
+
+          private
+
+          attr_reader :spans, :max_queue_size, :batch_size
+
+          def work
+            loop do
+              batch = lock do
+                @condition.wait(@mutex, @delay_seconds) if spans.size < batch_size && @keep_running
+                @condition.wait(@mutex, @delay_seconds) while spans.empty? && @keep_running
+                return unless @keep_running
+
+                fetch_batch
+              end
+
+              export_batch(batch)
+            end
+          end
+
+          def export_batch(batch)
+            result_code = nil
+            @export_attempts.times do |attempts|
+              result_code = export_with_timeout(batch)
+              break unless result_code == FAILED_RETRYABLE
+
+              sleep(0.1 * attempts)
+            end
+            report_result(result_code, batch)
+          end
+
+          def export_with_timeout(batch)
+            Timeout.timeout(@exporter_timeout_seconds) { @exporter.export(batch) }
+          rescue Timeout::Error
+            FAILED_NOT_RETRYABLE
+          end
+
+          def report_result(result_code, batch)
+            OpenTelemetry.logger.error("Unable to export #{batch.size} spans") unless result_code == SUCCESS
+          end
+
+          def flush
+            snapshot = lock { spans.shift(spans.size) }
+            until snapshot.empty?
+              batch = snapshot.shift(@batch_size).map!(&:to_span_data)
+              result_code = @exporter.export(batch)
+              report_result(result_code, batch)
+            end
+          end
+
+          def fetch_batch
+            spans.shift(@batch_size).map!(&:to_span_data)
+          end
+
+          def lock
+            @mutex.synchronize do
+              yield
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/opentelemetry/sdk/trace/export/console_span_exporter.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+# Copyright 2019 OpenTelemetry Authors
+#
+# SPDX-License-Identifier: Apache-2.0
+
+require 'pp'
+
+module OpenTelemetry
+  module SDK
+    module Trace
+      module Export
+        # Outputs {SpanData} to the console.
+        #
+        # Potentially useful for exploratory purposes.
+        class ConsoleSpanExporter
+          ResultCodes = OpenTelemetry::SDK::Trace::Export
+
+          private_constant(:ResultCodes)
+
+          def initialize
+            @stopped = false
+          end
+
+          def export(spans)
+            return ResultCodes::FAILED_NOT_RETRYABLE if @stopped
+
+            Array(spans).each { |s| pp s }
+
+            ResultCodes::SUCCESS
+          end
+
+          def shutdown
+            @stopped = true
+          end
+        end
+      end
+    end
+  end
+end

data/lib/opentelemetry/sdk/trace/export/in_memory_span_exporter.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+# Copyright 2019 OpenTelemetry Authors
+#
+# SPDX-License-Identifier: Apache-2.0
+
+module OpenTelemetry
+  module SDK
+    module Trace
+      module Export
+        # A SpanExporter implementation that can be used to test OpenTelemetry integration.
+        #
+        # Example usage:
+        #
+        # class MyClassTest
+        #   def setup
+        #     @tracer_factory = TracerFactory.new
+        #     @exporter = InMemorySpanExporter.new
+        #     @tracer_factory.add_span_processor(SimpleSampledSpansProcessor.new(@exporter))
+        #   end
+        #
+        #   def test_finished_spans
+        #     @tracer_factory.tracer.in_span("span") {}
+        #
+        #     spans = @exporter.finished_spans
+        #     spans.wont_be_nil
+        #     spans.size.must_equal(1)
+        #     spans[0].name.must_equal("span")
+        #   end
+        class InMemorySpanExporter
+          # Returns a new instance of the {InMemorySpanExporter}.
+          #
+          # @return a new instance of the {InMemorySpanExporter}.
+          def initialize
+            @finished_spans = []
+            @stopped = false
+            @mutex = Mutex.new
+          end
+
+          # Returns a frozen array of the finished {SpanData}s, represented by
+          # {io.opentelemetry.proto.trace.v1.Span}.
+          #
+          # @return [Array<SpanData>] a frozen array of the finished {SpanData}s.
+          def finished_spans
+            @mutex.synchronize do
+              @finished_spans.clone.freeze
+            end
+          end
+
+          # Clears the internal collection of finished {Span}s.
+          #
+          # Does not reset the state of this exporter if already shutdown.
+          def reset
+            @mutex.synchronize do
+              @finished_spans.clear
+            end
+          end
+
+          # Called to export sampled {SpanData}s.
+          #
+          # @param [Enumerable<SpanData>] span_datas the list of sampled {SpanData}s to be
+          #   exported.
+          # @return [Integer] the result of the export, SUCCESS or
+          #   FAILED_NOT_RETRYABLE
+          def export(span_datas)
+            @mutex.synchronize do
+              return FAILED_NOT_RETRYABLE if @stopped
+
+              @finished_spans.concat(span_datas.to_a)
+            end
+            SUCCESS
+          end
+
+          # Called when {TracerFactory#shutdown} is called, if this exporter is
+          # registered to a {TracerFactory} object.
+          def shutdown
+            @mutex.synchronize do
+              @finished_spans.clear
+              @stopped = true
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/opentelemetry/sdk/trace/export/multi_span_exporter.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+# Copyright 2019 OpenTelemetry Authors
+#
+# SPDX-License-Identifier: Apache-2.0
+
+module OpenTelemetry
+  module SDK
+    module Trace
+      module Export
+        # Implementation of the SpanExporter duck type that simply forwards all
+        # received spans to a collection of SpanExporters.
+        #
+        # Can be used to export to multiple backends using the same
+        # SpanProcessor like a {SimpleSpanProcessor} or a
+        # {BatchSpanProcessor}.
+        class MultiSpanExporter
+          def initialize(span_exporters)
+            @span_exporters = span_exporters.clone.freeze
+          end
+
+          # Called to export sampled {Span}s.
+          #
+          # @param [Enumerable<Span>] spans the list of sampled {Span}s to be
+          #   exported.
+          # @return [Integer] the result of the export.
+          def export(spans)
+            @span_exporters.inject(SUCCESS) do |result_code, span_exporter|
+              begin
+                merge_result_code(result_code, span_exporter.export(spans))
+              rescue => e # rubocop:disable Style/RescueStandardError
+                OpenTelemetry.logger.warn("exception raised by export - #{e}")
+                FAILED_NOT_RETRYABLE
+              end
+            end
+          end
+
+          # Called when {TracerFactory#shutdown} is called, if this exporter is
+          # registered to a {TracerFactory} object.
+          def shutdown
+            @span_exporters.each(&:shutdown)
+          end
+
+          private
+
+          # Returns a merged error code, see the rules in the code.
+          def merge_result_code(result_code, new_result_code)
+            if result_code == SUCCESS && new_result_code == SUCCESS
+              # If both errors are success then return success.
+              SUCCESS
+            elsif result_code == FAILED_NOT_RETRYABLE || new_result_code == FAILED_NOT_RETRYABLE
+              # If any of the codes is not retryable then return not_retryable.
+              FAILED_NOT_RETRYABLE
+            else
+              # At this point at least one of the code is FAILED_RETRYABLE and
+              # none are FAILED_NOT_RETRYABLE, so return FAILED_RETRYABLE.
+              FAILED_RETRYABLE
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/opentelemetry/sdk/trace/export/noop_span_exporter.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+# Copyright 2019 OpenTelemetry Authors
+#
+# SPDX-License-Identifier: Apache-2.0
+
+module OpenTelemetry
+  module SDK
+    module Trace
+      module Export
+        # A noop exporter that demonstrates and documents the SpanExporter
+        # duck type. SpanExporter allows different tracing services to export
+        # recorded data for sampled spans in their own format.
+        #
+        # To export data an exporter MUST be registered to the {TracerFactory} using
+        # a {SimpleSpanProcessor} or a {BatchSpanProcessor}.
+        class NoopSpanExporter
+          def initialize
+            @stopped = false
+          end
+
+          # Called to export sampled {Span}s.
+          #
+          # @param [Enumerable<Span>] spans the list of sampled {Span}s to be
+          #   exported.
+          # @return [Integer] the result of the export.
+          def export(spans)
+            return SUCCESS unless @stopped
+
+            FAILED_NOT_RETRYABLE
+          end
+
+          # Called when {TracerFactory#shutdown} is called, if this exporter is
+          # registered to a {TracerFactory} object.
+          def shutdown
+            @stopped = true
+          end
+        end
+      end
+    end
+  end
+end

data/lib/opentelemetry/sdk/trace/export/simple_span_processor.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+# Copyright 2019 OpenTelemetry Authors
+#
+# SPDX-License-Identifier: Apache-2.0
+
+module OpenTelemetry
+  module SDK
+    module Trace
+      module Export
+        # An implementation of the duck type SpanProcessor that converts the
+        # {Span} to {io.opentelemetry.proto.trace.v1.Span} and passes it to the
+        # configured exporter.
+        #
+        # Only spans that are recorded are converted, {OpenTelemetry::Trace::Span#is_recording?} must
+        # return true.
+        class SimpleSpanProcessor
+          # Returns a new {SimpleSpanProcessor} that converts spans to
+          # proto and forwards them to the given span_exporter.
+          #
+          # @param span_exporter the (duck type) SpanExporter to where the
+          #   recorded Spans are pushed.
+          # @return [SimpleSpanProcessor]
+          # @raise ArgumentError if the span_exporter is nil.
+          def initialize(span_exporter)
+            @span_exporter = span_exporter
+          end
+
+          # Called when a {Span} is started, if the {Span#recording?}
+          # returns true.
+          #
+          # This method is called synchronously on the execution thread, should
+          # not throw or block the execution thread.
+          #
+          # @param [Span] span the {Span} that just started.
+          def on_start(span)
+            # Do nothing.
+          end
+
+          # Called when a {Span} is ended, if the {Span#recording?}
+          # returns true.
+          #
+          # This method is called synchronously on the execution thread, should
+          # not throw or block the execution thread.
+          #
+          # @param [Span] span the {Span} that just ended.
+          def on_finish(span)
+            return unless span.context.trace_flags.sampled?
+
+            @span_exporter&.export([span.to_span_data])
+          rescue => e # rubocop:disable Style/RescueStandardError
+            OpenTelemetry.logger.error("unexpected error in span.on_finish - #{e}")
+          end
+
+          # Called when {TracerFactory#shutdown} is called.
+          def shutdown
+            @span_exporter&.shutdown
+          end
+        end
+      end
+    end
+  end
+end