opentelemetry-sdk 0.8.0 → 0.12.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 735ead8ec769c6a55c3e3393341366ebd4a7e83bd4bdd8a71ca474b470ab0566
-  data.tar.gz: 862d5aa24d401a6c215d852a4c601a58d858d452c9f3679cd33d71094de2eeb4
+  metadata.gz: 718ea2029bb234ea6ed56da8b65923595e275bb4730c3f3ea50bc20c4a01597d
+  data.tar.gz: 39e4031d0ef4ff426fe9bd776b4e85a2dd351a77c9dc8e19b80330dc5bf9d544
 SHA512:
-  metadata.gz: 8cb9becaedfbf07126a03c68f1968c988d499042c587a4d4e1100048660d2fa699b809c7d687eb90700d63ecceda4b31172e2efd25ea147abb0ccd7afbe9b476
-  data.tar.gz: 718f2a0a972e3a3f60beea5f4d3d8bff47f943fc24ecc2726182449f1cb3e958122e40971f5db7b96771b9380cd79b93f0ef7e3480d4319b5466d1c7ce3e0287
+  metadata.gz: caa3842133c57ab739e0c21d8e1cd5f9cd58293e1e34055eef6b18fd4ff0869a39edbe87bcbb0fef7e76ea733f9ea0f9ff84663cf70a3a88820b7074c78c156d
+  data.tar.gz: f3e8176d0b495ea3784b6f8e2b2676000e35b3db7a1fab7b0890014ff69accd9caa69a00af02b4668964d3837aabd470bdaec78bda0d06ada1a9cfe6f1b000a7

data/CHANGELOG.md

@@ -1,5 +1,40 @@
 # Release History: opentelemetry-sdk
 
+### v0.12.0 / 2020-12-24
+
+* ADDED: Structured error handling 
+* ADDED: Pluggable ID generation 
+* FIXED: BSP dropped span buffer full reporting 
+* FIXED: Implement SDK environment variables 
+* FIXED: Remove incorrect TODO 
+
+### v0.11.1 / 2020-12-16
+
+* FIXED: BSP dropped span buffer full reporting 
+
+### v0.11.0 / 2020-12-11
+
+* ADDED: Metrics reporting from trace export 
+* FIXED: Copyright comments to not reference year 
+
+### v0.10.0 / 2020-12-03
+
+* BREAKING CHANGE: Allow samplers to modify tracestate 
+
+* FIXED: Allow samplers to modify tracestate 
+
+### v0.9.0 / 2020-11-27
+
+* BREAKING CHANGE: Pass full Context to samplers 
+* BREAKING CHANGE: Add timeout for force_flush and shutdown 
+
+* ADDED: Add OTEL_RUBY_BSP_START_THREAD_ON_BOOT env var 
+* ADDED: Add timeout for force_flush and shutdown 
+* FIXED: Signal at batch_size 
+* FIXED: SDK Span.recording? after finish 
+* FIXED: Pass full Context to samplers 
+* DOCS: Add documentation on usage scenarios for span processors 
+
 ### v0.8.0 / 2020-10-27
 
 * BREAKING CHANGE: Move context/span methods to Trace module 

data/LICENSE

@@ -186,7 +186,7 @@
       same "printed page" as the copyright notice for easier
       identification within third-party archives.
 
-   Copyright 2020 OpenTelemetry Authors
+   Copyright The OpenTelemetry Authors
 
    Licensed under the Apache License, Version 2.0 (the "License");
    you may not use this file except in compliance with the License.

data/lib/opentelemetry-sdk.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-# Copyright 2019 OpenTelemetry Authors
+# Copyright The OpenTelemetry Authors
 #
 # SPDX-License-Identifier: Apache-2.0
 

data/lib/opentelemetry/sdk.rb

@@ -1,10 +1,11 @@
 # frozen_string_literal: true
 
-# Copyright 2019 OpenTelemetry Authors
+# Copyright The OpenTelemetry Authors
 #
 # SPDX-License-Identifier: Apache-2.0
 
 require 'opentelemetry'
+require 'opentelemetry/common'
 
 # OpenTelemetry is an open source observability framework, providing a
 # general-purpose API, SDK, and related tools required for the instrumentation
@@ -17,6 +18,11 @@ module OpenTelemetry
   module SDK
     extend self
 
+    # ConfigurationError is an exception type used to wrap configuration errors
+    # passed to OpenTelemetry.error_handler. This can be used to distinguish
+    # errors reported during SDK configuration.
+    ConfigurationError = Class.new(OpenTelemetry::Error)
+
     # Configures SDK and instrumentation
     #
     # @yieldparam [Configurator] configurator Yields a configurator to the
@@ -56,6 +62,12 @@ module OpenTelemetry
       configurator = Configurator.new
       yield configurator if block_given?
       configurator.configure
+    rescue StandardError
+      begin
+        raise ConfigurationError
+      rescue ConfigurationError => e
+        OpenTelemetry.handle_error(exception: e, message: 'unexpected configuration error')
+      end
     end
   end
 end

data/lib/opentelemetry/sdk/baggage.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-# Copyright 2019 OpenTelemetry Authors
+# Copyright The OpenTelemetry Authors
 #
 # SPDX-License-Identifier: Apache-2.0
 

data/lib/opentelemetry/sdk/baggage/builder.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-# Copyright 2019 OpenTelemetry Authors
+# Copyright The OpenTelemetry Authors
 #
 # SPDX-License-Identifier: Apache-2.0
 

data/lib/opentelemetry/sdk/baggage/manager.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-# Copyright 2019 OpenTelemetry Authors
+# Copyright The OpenTelemetry Authors
 #
 # SPDX-License-Identifier: Apache-2.0
 

data/lib/opentelemetry/sdk/configurator.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-# Copyright 2019 OpenTelemetry Authors
+# Copyright The OpenTelemetry Authors
 #
 # SPDX-License-Identifier: Apache-2.0
 
@@ -16,7 +16,7 @@ module OpenTelemetry
       private_constant :USE_MODE_UNSPECIFIED, :USE_MODE_ONE, :USE_MODE_ALL
 
       attr_writer :logger, :http_extractors, :http_injectors, :text_map_extractors,
-                  :text_map_injectors
+                  :text_map_injectors, :error_handler, :id_generator
 
       def initialize
         @instrumentation_names = []
@@ -28,12 +28,17 @@ module OpenTelemetry
         @span_processors = []
         @use_mode = USE_MODE_UNSPECIFIED
         @resource = Resources::Resource.telemetry_sdk
+        @id_generator = OpenTelemetry::Trace
       end
 
       def logger
         @logger ||= OpenTelemetry.logger
       end
 
+      def error_handler
+        @error_handler ||= OpenTelemetry.error_handler
+      end
+
       # Accepts a resource object that is merged with the default telemetry sdk
       # resource. The use of this method is optional, and is provided as means
       # to include additional resource information.
@@ -110,9 +115,11 @@ module OpenTelemetry
       #   - install instrumentation
       def configure
         OpenTelemetry.logger = logger
+        OpenTelemetry.error_handler = error_handler
         OpenTelemetry.baggage = Baggage::Manager.new
         configure_propagation
         configure_span_processors
+        tracer_provider.id_generator = @id_generator
         OpenTelemetry.tracer_provider = tracer_provider
         install_instrumentation
       end

data/lib/opentelemetry/sdk/instrumentation_library.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-# Copyright 2019 OpenTelemetry Authors
+# Copyright The OpenTelemetry Authors
 #
 # SPDX-License-Identifier: Apache-2.0
 

data/lib/opentelemetry/sdk/internal.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-# Copyright 2019 OpenTelemetry Authors
+# Copyright The OpenTelemetry Authors
 #
 # SPDX-License-Identifier: Apache-2.0
 
@@ -45,7 +45,17 @@ module OpenTelemetry
       end
 
       def valid_attributes?(attrs)
-        attrs.nil? || attrs.all? { |k, v| valid_key?(k) && valid_value?(v) }
+        attrs.nil? || attrs.all? do |k, v|
+          if !valid_key?(k)
+            OpenTelemetry.handle_error(message: "invalid attribute key type #{v.class}")
+            false
+          elsif !valid_value?(v)
+            OpenTelemetry.handle_error(message: "invalid attribute value type #{v.class}")
+            false
+          else
+            true
+          end
+        end
       end
     end
   end

data/lib/opentelemetry/sdk/resources.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-# Copyright 2019 OpenTelemetry Authors
+# Copyright The OpenTelemetry Authors
 #
 # SPDX-License-Identifier: Apache-2.0
 

data/lib/opentelemetry/sdk/resources/constants.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-# Copyright 2020 OpenTelemetry Authors
+# Copyright The OpenTelemetry Authors
 #
 # SPDX-License-Identifier: Apache-2.0
 

data/lib/opentelemetry/sdk/resources/resource.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-# Copyright 2019 OpenTelemetry Authors
+# Copyright The OpenTelemetry Authors
 #
 # SPDX-License-Identifier: Apache-2.0
 
@@ -22,7 +22,7 @@ module OpenTelemetry
           def create(attributes = {})
             frozen_attributes = attributes.each_with_object({}) do |(k, v), memo|
               raise ArgumentError, 'attribute keys must be strings' unless k.is_a?(String)
-              raise ArgumentError, 'attribute values must be strings, integers, floats, or booleans' unless Internal.valid_value?(v)
+              raise ArgumentError, 'attribute values must be (array of) strings, integers, floats, or booleans' unless Internal.valid_value?(v)
 
               memo[-k] = v.freeze
             end.freeze

data/lib/opentelemetry/sdk/trace.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-# Copyright 2019 OpenTelemetry Authors
+# Copyright The OpenTelemetry Authors
 #
 # SPDX-License-Identifier: Apache-2.0
 

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

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-# Copyright 2019 OpenTelemetry Authors
+# Copyright The OpenTelemetry Authors
 #
 # SPDX-License-Identifier: Apache-2.0
 

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

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-# Copyright 2019 OpenTelemetry Authors
+# Copyright The OpenTelemetry Authors
 #
 # SPDX-License-Identifier: Apache-2.0
 
@@ -10,20 +10,6 @@ module OpenTelemetry
       module Config
         # Class that holds global trace parameters.
         class TraceConfig
-          DEFAULT_SAMPLER = Samplers.parent_based(root: Samplers::ALWAYS_ON)
-          DEFAULT_MAX_ATTRIBUTES_COUNT = 32
-          DEFAULT_MAX_EVENTS_COUNT = 128
-          DEFAULT_MAX_LINKS_COUNT = 32
-          DEFAULT_MAX_ATTRIBUTES_PER_EVENT = 32
-          DEFAULT_MAX_ATTRIBUTES_PER_LINK = 32
-
-          private_constant(:DEFAULT_SAMPLER,
-                           :DEFAULT_MAX_ATTRIBUTES_COUNT,
-                           :DEFAULT_MAX_EVENTS_COUNT,
-                           :DEFAULT_MAX_LINKS_COUNT,
-                           :DEFAULT_MAX_ATTRIBUTES_PER_EVENT,
-                           :DEFAULT_MAX_ATTRIBUTES_PER_LINK)
-
           # The global default sampler (see {Samplers}).
           attr_reader :sampler
 
@@ -46,12 +32,12 @@ module OpenTelemetry
           #
           # @return [TraceConfig] with the desired values.
           # @raise [ArgumentError] if any of the max numbers are not positive.
-          def initialize(sampler: DEFAULT_SAMPLER,
-                         max_attributes_count: DEFAULT_MAX_ATTRIBUTES_COUNT,
-                         max_events_count: DEFAULT_MAX_EVENTS_COUNT,
-                         max_links_count: DEFAULT_MAX_LINKS_COUNT,
-                         max_attributes_per_event: DEFAULT_MAX_ATTRIBUTES_PER_EVENT,
-                         max_attributes_per_link: DEFAULT_MAX_ATTRIBUTES_PER_LINK)
+          def initialize(sampler: sampler_from_environment(Samplers.parent_based(root: Samplers::ALWAYS_ON)),
+                         max_attributes_count: Integer(ENV.fetch('OTEL_SPAN_ATTRIBUTE_COUNT_LIMIT', 1000)),
+                         max_events_count: Integer(ENV.fetch('OTEL_SPAN_EVENT_COUNT_LIMIT', 1000)),
+                         max_links_count: Integer(ENV.fetch('OTEL_SPAN_LINK_COUNT_LIMIT', 1000)),
+                         max_attributes_per_event: max_attributes_count,
+                         max_attributes_per_link: max_attributes_count)
             raise ArgumentError, 'max_attributes_count must be positive' unless max_attributes_count.positive?
             raise ArgumentError, 'max_events_count must be positive' unless max_events_count.positive?
             raise ArgumentError, 'max_links_count must be positive' unless max_links_count.positive?
@@ -67,6 +53,22 @@ module OpenTelemetry
           end
 
           # TODO: from_proto
+          private
+
+          def sampler_from_environment(default_sampler) # rubocop:disable Metrics/CyclomaticComplexity
+            case ENV['OTEL_TRACE_SAMPLER']
+            when 'always_on' then Samplers::ALWAYS_ON
+            when 'always_off' then Samplers::ALWAYS_OFF
+            when 'traceidratio' then Samplers.trace_id_ratio_based(Float(ENV['OTEL_TRACE_SAMPLER_ARG']))
+            when 'parentbased_always_on' then Samplers.parent_based(root: Samplers::ALWAYS_ON)
+            when 'parentbased_always_off' then Samplers.parent_based(root: Samplers::ALWAYS_OFF)
+            when 'parentbased_traceidratio' then Samplers.parent_based(root: Samplers.trace_id_ratio_based(Float(ENV['OTEL_TRACE_SAMPLER_ARG'])))
+            else default_sampler
+            end
+          rescue StandardError => e
+            OpenTelemetry.handle_error(exception: e, message: "installing default sampler #{default_sampler.description}")
+            default_sampler
+          end
 
           # The default {TraceConfig}.
           DEFAULT = new

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

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-# Copyright 2019 OpenTelemetry Authors
+# Copyright The OpenTelemetry Authors
 #
 # SPDX-License-Identifier: Apache-2.0
 

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

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-# Copyright 2019 OpenTelemetry Authors
+# Copyright The OpenTelemetry Authors
 #
 # SPDX-License-Identifier: Apache-2.0
 
@@ -30,6 +30,7 @@ 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/metrics_reporter'
 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

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-# Copyright 2019 OpenTelemetry Authors
+# Copyright The OpenTelemetry Authors
 #
 # SPDX-License-Identifier: Apache-2.0
 
@@ -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,7 +25,7 @@ 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
+        class BatchSpanProcessor # rubocop:disable Metrics/ClassLength
           # Returns a new instance of the {BatchSpanProcessor}.
           #
           # @param [SpanExporter] exporter
@@ -44,42 +47,46 @@ module OpenTelemetry
                          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)))
+                         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,
+                         metrics_reporter: nil)
             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
+            @metrics_reporter = metrics_reporter || OpenTelemetry::SDK::Trace::Export::MetricsReporter
             @spans = []
             @pid = nil
             @thread = nil
-            reset_on_fork
+            reset_on_fork(restart_thread: start_thread_on_boot)
           end
 
-          # does nothing for this processor
-          def on_start(span, parent_context)
-            # 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?
+              if n.positive?
+                spans.shift(n)
+                report_dropped_spans(n, reason: 'buffer-full')
+              end
               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.
           #
@@ -88,42 +95,64 @@ module OpenTelemetry
           # the process after an invocation, but before the `Processor` exports
           # the completed spans.
           #
+          # @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
+          def force_flush(timeout: nil) # rubocop:disable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity, Metrics/MethodLength
+            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
+              if n.positive?
+                snapshot.shift(n)
+                report_dropped_spans(n, reason: 'buffer-full')
+              end
+              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
+          # 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
+          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))
+            dropped_spans = lock { spans.size }
+            report_dropped_spans(dropped_spans, reason: 'terminating') if dropped_spans.positive?
           end
 
           private
 
           attr_reader :spans, :max_queue_size, :batch_size
 
-          def work
+          def work # rubocop:disable Metrics/AbcSize
             loop do
               batch = lock do
                 reset_on_fork(restart_thread: false)
@@ -134,6 +163,8 @@ module OpenTelemetry
                 fetch_batch
               end
 
+              @metrics_reporter.observe_value('otel.bsp.buffer_utilization', value: spans.size / max_queue_size.to_f)
+
               export_batch(batch)
             end
           end
@@ -147,19 +178,25 @@ module OpenTelemetry
             @thread = Thread.new { work } if restart_thread
           end
 
-          def export_batch(batch)
-            result_code = export_with_timeout(batch)
+          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 export_with_timeout(batch)
-            Timeout.timeout(@exporter_timeout_seconds) { @exporter.export(batch) }
-          rescue Timeout::Error
-            FAILURE
+          def report_result(result_code, batch)
+            if result_code == SUCCESS
+              @metrics_reporter.add_to_counter('otel.bsp.export.success')
+              @metrics_reporter.add_to_counter('otel.bsp.exported_spans', increment: batch.size)
+            else
+              OpenTelemetry.handle_error(message: "Unable to export #{batch.size} spans")
+              @metrics_reporter.add_to_counter('otel.bsp.export.failure')
+              report_dropped_spans(batch.size, reason: 'export-failure')
+            end
           end
 
-          def report_result(result_code, batch)
-            OpenTelemetry.logger.error("Unable to export #{batch.size} spans") unless result_code == SUCCESS
+          def report_dropped_spans(count, reason:)
+            @metrics_reporter.add_to_counter('otel.bsp.dropped_spans', increment: count, labels: { 'reason' => reason })
           end
 
           def fetch_batch