opentelemetry-sdk 0.5.0 → 0.9.0

data/lib/opentelemetry/sdk/trace.rb

@@ -15,6 +15,7 @@ end
 
 require 'opentelemetry/sdk/trace/samplers'
 require 'opentelemetry/sdk/trace/config'
+require 'opentelemetry/sdk/trace/event'
 require 'opentelemetry/sdk/trace/export'
 require 'opentelemetry/sdk/trace/multi_span_processor'
 require 'opentelemetry/sdk/trace/noop_span_processor'

data/lib/opentelemetry/sdk/trace/config/trace_config.rb

@@ -10,7 +10,7 @@ module OpenTelemetry
       module Config
         # Class that holds global trace parameters.
         class TraceConfig
-          DEFAULT_SAMPLER = Samplers::ALWAYS_ON
+          DEFAULT_SAMPLER = Samplers.parent_based(root: Samplers::ALWAYS_ON)
           DEFAULT_MAX_ATTRIBUTES_COUNT = 32
           DEFAULT_MAX_EVENTS_COUNT = 128
           DEFAULT_MAX_LINKS_COUNT = 32
@@ -30,13 +30,13 @@ module OpenTelemetry
           # The global default max number of attributes per {Span}.
           attr_reader :max_attributes_count
 
-          # The global default max number of {OpenTelemetry::Trace::Event}s per {Span}.
+          # The global default max number of {OpenTelemetry::SDK::Trace::Event}s per {Span}.
           attr_reader :max_events_count
 
           # The global default max number of {OpenTelemetry::Trace::Link} entries per {Span}.
           attr_reader :max_links_count
 
-          # The global default max number of attributes per {OpenTelemetry::Trace::Event}.
+          # The global default max number of attributes per {OpenTelemetry::SDK::Trace::Event}.
           attr_reader :max_attributes_per_event
 
           # The global default max number of attributes per {OpenTelemetry::Trace::Link}.

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

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+# Copyright 2019 OpenTelemetry Authors
+#
+# SPDX-License-Identifier: Apache-2.0
+
+module OpenTelemetry
+  module SDK
+    module Trace
+      # A text annotation with a set of attributes and a timestamp.
+      class Event
+        EMPTY_ATTRIBUTES = {}.freeze
+
+        private_constant :EMPTY_ATTRIBUTES
+
+        # Returns the name of this event
+        #
+        # @return [String]
+        attr_reader :name
+
+        # Returns the frozen attributes for this event
+        #
+        # @return [Hash{String => String, Numeric, Boolean, Array<String, Numeric, Boolean>}]
+        attr_reader :attributes
+
+        # Returns the timestamp for this event
+        #
+        # @return [Time]
+        attr_reader :timestamp
+
+        # Returns a new immutable {Event}.
+        #
+        # @param [String] name The name of this event
+        # @param [optional Hash{String => String, Numeric, Boolean, Array<String, Numeric, Boolean>}]
+        #   attributes A hash of attributes for this event. Attributes will be
+        #   frozen during Event initialization.
+        # @param [optional Time] timestamp The timestamp for this event.
+        #   Defaults to Time.now.
+        # @return [Event]
+        def initialize(name:, attributes: nil, timestamp: nil)
+          @name = name
+          @attributes = attributes.freeze || EMPTY_ATTRIBUTES
+          @timestamp = timestamp || Time.now
+        end
+      end
+    end
+  end
+end

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

@@ -7,16 +7,21 @@
 module OpenTelemetry
   module SDK
     module Trace
-      # The Export module contains the built-in exporters for the OpenTelemetry
+      # The Export module contains the built-in exporters and span processors for the OpenTelemetry
       # reference implementation.
       module Export
-        # Result codes for the SpanExporter#export method.
+        # Result codes for the SpanExporter#export method and the SpanProcessor#force_flush and SpanProcessor#shutdown methods.
 
-        # The export operation finished successfully.
+        # The operation finished successfully.
         SUCCESS = 0
 
-        # The export operation finished with an error.
+        # The operation finished with an error.
         FAILURE = 1
+
+        # Additional result code for the SpanProcessor#force_flush and SpanProcessor#shutdown methods.
+
+        # The operation timed out.
+        TIMEOUT = 2
       end
     end
   end

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

@@ -13,6 +13,9 @@ module OpenTelemetry
         # Implementation of the duck type SpanProcessor that batches spans
         # exported by the SDK then pushes them to the exporter pipeline.
         #
+        # Typically, the BatchSpanProcessor will be more suitable for
+        # production environments than the SimpleSpanProcessor.
+        #
         # 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
@@ -22,50 +25,63 @@ module OpenTelemetry
         # 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.
-        class BatchSpanProcessor
-          EXPORTER_TIMEOUT_MILLIS = 30_000
-          SCHEDULE_DELAY_MILLIS = 5_000
-          MAX_QUEUE_SIZE = 2048
-          MAX_EXPORT_BATCH_SIZE = 512
-          private_constant(:SCHEDULE_DELAY_MILLIS, :MAX_QUEUE_SIZE, :MAX_EXPORT_BATCH_SIZE)
-
+        class BatchSpanProcessor # rubocop:disable Metrics/ClassLength
+          # Returns a new instance of the {BatchSpanProcessor}.
+          #
+          # @param [SpanExporter] exporter
+          # @param [Numeric] exporter_timeout_millis the delay interval between two
+          #   consecutive exports. Defaults to the value of the OTEL_BSP_EXPORT_TIMEOUT_MILLIS
+          #   environment variable, if set, or 30,000 (30 seconds).
+          # @param [Numeric] schedule_delay_millis the maximum allowed time to export data.
+          #   Defaults to the value of the OTEL_BSP_SCHEDULE_DELAY_MILLIS environment
+          #   variable, if set, or 5,000 (5 seconds).
+          # @param [Integer] max_queue_size the maximum queue size in spans.
+          #   Defaults to the value of the OTEL_BSP_MAX_QUEUE_SIZE environment
+          #   variable, if set, or 2048.
+          # @param [Integer] max_export_batch_size the maximum batch size in spans.
+          #   Defaults to the value of the OTEL_BSP_MAX_EXPORT_BATCH_SIZE environment
+          #   variable, if set, or 512.
+          #
+          # @return a new instance of the {BatchSpanProcessor}.
           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)
+                         exporter_timeout_millis: Float(ENV.fetch('OTEL_BSP_EXPORT_TIMEOUT_MILLIS', 30_000)),
+                         schedule_delay_millis: Float(ENV.fetch('OTEL_BSP_SCHEDULE_DELAY_MILLIS', 5_000)),
+                         max_queue_size: Integer(ENV.fetch('OTEL_BSP_MAX_QUEUE_SIZE', 2048)),
+                         max_export_batch_size: Integer(ENV.fetch('OTEL_BSP_MAX_EXPORT_BATCH_SIZE', 512)),
+                         start_thread_on_boot: String(ENV['OTEL_RUBY_BSP_START_THREAD_ON_BOOT']) !~ /false/i)
             raise ArgumentError if max_export_batch_size > max_queue_size
 
             @exporter = exporter
             @exporter_timeout_seconds = exporter_timeout_millis / 1000.0
             @mutex = Mutex.new
+            @export_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
             @spans = []
-            @thread = Thread.new { work }
+            @pid = nil
+            @thread = nil
+            reset_on_fork(restart_thread: start_thread_on_boot)
           end
 
-          # does nothing for this processor
-          def on_start(span)
-            # noop
-          end
+          # Does nothing for this processor
+          def on_start(_span, _parent_context); end
 
-          # adds a span to the batcher, threadsafe may block on lock
+          # Adds a span to the batch. Thread-safe; may block on lock.
           def on_finish(span) # rubocop:disable Metrics/AbcSize
             return unless span.context.trace_flags.sampled?
 
             lock do
+              reset_on_fork
               n = spans.size + 1 - max_queue_size
               spans.shift(n) if n.positive?
               spans << span
-              @condition.signal if spans.size > max_queue_size / 2
+              @condition.signal if spans.size > batch_size
             end
           end
 
-          # TODO: test this explicitly.
           # Export all ended spans to the configured `Exporter` that have not yet
           # been exported.
           #
@@ -73,26 +89,53 @@ module OpenTelemetry
           # necessary, such as when using some FaaS providers that may suspend
           # the process after an invocation, but before the `Processor` exports
           # the completed spans.
-          def force_flush
-            snapshot = lock { spans.shift(spans.size) }
+          #
+          # @param [optional Numeric] timeout An optional timeout in seconds.
+          # @return [Integer] SUCCESS if no error occurred, FAILURE if a
+          #   non-specific failure occurred, TIMEOUT if a timeout occurred.
+          def force_flush(timeout: nil) # rubocop:disable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
+            start_time = Time.now
+            snapshot = lock do
+              reset_on_fork(restart_thread: false) if @keep_running
+              spans.shift(spans.size)
+            end
             until snapshot.empty?
+              remaining_timeout = OpenTelemetry::Common::Utilities.maybe_timeout(timeout, start_time)
+              return TIMEOUT if remaining_timeout&.zero?
+
               batch = snapshot.shift(@batch_size).map!(&:to_span_data)
-              result_code = @exporter.export(batch)
-              report_result(result_code, batch)
+              result_code = export_batch(batch, timeout: remaining_timeout)
+              return result_code unless result_code == SUCCESS
+            end
+
+            SUCCESS
+          ensure
+            # Unshift the remaining spans if we timed out. We drop excess spans from
+            # the snapshot because they're older than any spans in the spans buffer.
+            lock do
+              n = spans.size + snapshot.size - max_queue_size
+              snapshot.shift(n) if n.positive?
+              spans.unshift(snapshot) unless snapshot.empty?
+              @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
+          # Shuts the consumer thread down and flushes the current accumulated buffer
+          # will block until the thread is finished.
+          #
+          # @param [optional Numeric] timeout An optional timeout in seconds.
+          # @return [Integer] SUCCESS if no error occurred, FAILURE if a
+          #   non-specific failure occurred, TIMEOUT if a timeout occurred.
+          def shutdown(timeout: nil)
+            start_time = Time.now
             lock do
               @keep_running = false
               @condition.signal
             end
 
-            @thread.join
-            force_flush
-            @exporter.shutdown
+            @thread.join(timeout)
+            force_flush(timeout: OpenTelemetry::Common::Utilities.maybe_timeout(timeout, start_time))
+            @exporter.shutdown(timeout: OpenTelemetry::Common::Utilities.maybe_timeout(timeout, start_time))
           end
 
           private
@@ -102,6 +145,7 @@ module OpenTelemetry
           def work
             loop do
               batch = lock do
+                reset_on_fork(restart_thread: false)
                 @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
@@ -113,15 +157,19 @@ module OpenTelemetry
             end
           end
 
-          def export_batch(batch)
-            result_code = export_with_timeout(batch)
-            report_result(result_code, batch)
+          def reset_on_fork(restart_thread: true)
+            pid = Process.pid
+            return if @pid == pid
+
+            @pid = pid
+            spans.clear
+            @thread = Thread.new { work } if restart_thread
           end
 
-          def export_with_timeout(batch)
-            Timeout.timeout(@exporter_timeout_seconds) { @exporter.export(batch) }
-          rescue Timeout::Error
-            FAILURE
+          def export_batch(batch, timeout: @exporter_timeout_seconds)
+            result_code = @export_mutex.synchronize { @exporter.export(batch, timeout: timeout) }
+            report_result(result_code, batch)
+            result_code
           end
 
           def report_result(result_code, batch)

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

@@ -14,24 +14,21 @@ module OpenTelemetry
         #
         # 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::FAILURE if @stopped
+          def export(spans, timeout: nil)
+            return FAILURE if @stopped
 
             Array(spans).each { |s| pp s }
 
-            ResultCodes::SUCCESS
+            SUCCESS
           end
 
-          def shutdown
+          def shutdown(timeout: nil)
             @stopped = true
+            SUCCESS
           end
         end
       end

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

@@ -60,9 +60,10 @@ module OpenTelemetry
           #
           # @param [Enumerable<SpanData>] span_datas the list of sampled {SpanData}s to be
           #   exported.
+          # @param [optional Numeric] timeout An optional timeout in seconds.
           # @return [Integer] the result of the export, SUCCESS or
           #   FAILURE
-          def export(span_datas)
+          def export(span_datas, timeout: nil)
             @mutex.synchronize do
               return FAILURE if @stopped
 
@@ -73,11 +74,16 @@ module OpenTelemetry
 
           # Called when {TracerProvider#shutdown} is called, if this exporter is
           # registered to a {TracerProvider} object.
-          def shutdown
+          #
+          # @param [optional Numeric] timeout An optional timeout in seconds.
+          # @return [Integer] SUCCESS if no error occurred, FAILURE if a
+          #   non-specific failure occurred, TIMEOUT if a timeout occurred.
+          def shutdown(timeout: nil)
             @mutex.synchronize do
               @finished_spans.clear
               @stopped = true
             end
+            SUCCESS
           end
         end
       end

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

@@ -23,33 +23,34 @@ module OpenTelemetry
           #
           # @param [Enumerable<Span>] spans the list of sampled {Span}s to be
           #   exported.
+          # @param [optional Numeric] timeout An optional timeout in seconds.
           # @return [Integer] the result of the export.
-          def export(spans)
-            @span_exporters.inject(SUCCESS) do |result_code, span_exporter|
-              merge_result_code(result_code, span_exporter.export(spans))
+          def export(spans, timeout: nil)
+            start_time = Time.now
+            results = @span_exporters.map do |span_exporter|
+              span_exporter.export(spans, timeout: OpenTelemetry::Common::Utilities.maybe_timeout(timeout, start_time))
             rescue => e # rubocop:disable Style/RescueStandardError
               OpenTelemetry.logger.warn("exception raised by export - #{e}")
               FAILURE
             end
+            results.uniq.max || SUCCESS
           end
 
           # Called when {TracerProvider#shutdown} is called, if this exporter is
           # registered to a {TracerProvider} object.
-          def shutdown
-            @span_exporters.each(&:shutdown)
-          end
-
-          private
+          #
+          # @param [optional Numeric] timeout An optional timeout in seconds.
+          # @return [Integer] SUCCESS if no error occurred, FAILURE if a
+          #   non-specific failure occurred, TIMEOUT if a timeout occurred.
+          def shutdown(timeout: nil)
+            start_time = Time.now
+            results = @span_exporters.map do |processor|
+              remaining_timeout = OpenTelemetry::Common::Utilities.maybe_timeout(timeout, start_time)
+              return TIMEOUT if remaining_timeout&.zero?
 
-          # 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
-            else
-              # At this point at least one of the code is FAILURE, so return FAILURE.
-              FAILURE
+              processor.shutdown(timeout: remaining_timeout)
             end
+            results.uniq.max || SUCCESS
           end
         end
       end

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

@@ -23,8 +23,9 @@ module OpenTelemetry
           #
           # @param [Enumerable<Span>] spans the list of sampled {Span}s to be
           #   exported.
+          # @param [optional Numeric] timeout An optional timeout in seconds.
           # @return [Integer] the result of the export.
-          def export(spans)
+          def export(spans, timeout: nil)
             return SUCCESS unless @stopped
 
             FAILURE
@@ -32,8 +33,11 @@ module OpenTelemetry
 
           # Called when {TracerProvider#shutdown} is called, if this exporter is
           # registered to a {TracerProvider} object.
-          def shutdown
+          #
+          # @param [optional Numeric] timeout An optional timeout in seconds.
+          def shutdown(timeout: nil)
             @stopped = true
+            SUCCESS
           end
         end
       end

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

@@ -12,6 +12,12 @@ module OpenTelemetry
         # {Span} to {io.opentelemetry.proto.trace.v1.Span} and passes it to the
         # configured exporter.
         #
+        # Typically, the SimpleSpanProcessor will be most suitable for use in testing;
+        # it should be used with caution in production. It may be appropriate for
+        # production use in scenarios where creating multiple threads is not desirable
+        # as well as scenarios where different custom attributes should be added to
+        # individual spans based on code scopes.
+        #
         # Only spans that are recorded are converted, {OpenTelemetry::Trace::Span#is_recording?} must
         # return true.
         class SimpleSpanProcessor
@@ -33,7 +39,9 @@ module OpenTelemetry
           # not throw or block the execution thread.
           #
           # @param [Span] span the {Span} that just started.
-          def on_start(span)
+          # @param [Context] parent_context the parent {Context} of the newly
+          #  started span.
+          def on_start(span, parent_context)
             # Do nothing.
           end
 
@@ -59,11 +67,21 @@ module OpenTelemetry
           # necessary, such as when using some FaaS providers that may suspend
           # the process after an invocation, but before the `Processor` exports
           # the completed spans.
-          def force_flush; end
+          #
+          # @param [optional Numeric] timeout An optional timeout in seconds.
+          # @return [Integer] SUCCESS if no error occurred, FAILURE if a
+          #   non-specific failure occurred, TIMEOUT if a timeout occurred.
+          def force_flush(timeout: nil)
+            SUCCESS
+          end
 
           # Called when {TracerProvider#shutdown} is called.
-          def shutdown
-            @span_exporter&.shutdown
+          #
+          # @param [optional Numeric] timeout An optional timeout in seconds.
+          # @return [Integer] SUCCESS if no error occurred, FAILURE if a
+          #   non-specific failure occurred, TIMEOUT if a timeout occurred.
+          def shutdown(timeout: nil)
+            @span_exporter&.shutdown(timeout: timeout) || SUCCESS
           end
         end
       end