opentelemetry-sdk 0.6.0 → 0.11.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3a01fcf121db23108ffb47d196f9594993018bb1b945242710620bb87daa8320
-  data.tar.gz: ef3b3e9cd4e2853a22ffb149e7a18cbd021988412d24c40350192e222b3be58b
+  metadata.gz: cb411f30633b54940beb1f9098606f19330f8ebab59e3b98cec8e56ec2e3bbdf
+  data.tar.gz: 6f9a05cd0341cf0411c501abbb40648c11dc97d920b65728386dca2c404b8f60
 SHA512:
-  metadata.gz: 5da08d0e902ece66efc7afa892f99f2b9fe3bcd5b89b51cd3da1a565a23ab0917eb1c39d6fb44ed6b82a71048624cb357539d9b6305b1a0c8debc594ef2467d3
-  data.tar.gz: 5fe47387c0d91e8d5436be4d4464839f08a9ae46964e8fe1679ab6ef7e7bf8b7a59ae086472d465e6f12c57b70c712a982064351f287a8ebbb6bbe173c37b45d
+  metadata.gz: 44ed1519e66997080314953a11e483e6f00d4bb774b9eecc6effe6623f2e48c68485594717db25ba39bd92c453cd25c926c0ca2dabc19588878067eefba48ece
+  data.tar.gz: 3f1dcd7506145ed4c008403926827205ed8661a3ee6c35f524ead8d6fd16984ce556722c4b0917229e2e641c37ffe3c83088beadd990d6dfb6015a1fa083cf6a

data/.yardopts

@@ -1,9 +1,9 @@
 --no-private
 --title=OpenTelemetry SDK
 --markup=markdown
---main=OVERVIEW.md
+--main=README.md
 ./lib/opentelemetry/sdk/**/*.rb
 ./lib/opentelemetry/sdk.rb
 -
-OVERVIEW.md
+README.md
 CHANGELOG.md

data/CHANGELOG.md

@@ -1,5 +1,47 @@
 # Release History: opentelemetry-sdk
 
+### 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 
+* BREAKING CHANGE: Remove 'canonical' from status codes 
+* BREAKING CHANGE: Assorted SpanContext fixes 
+
+* FIXED: Move context/span methods to Trace module 
+* FIXED: Remove 'canonical' from status codes 
+* FIXED: Assorted SpanContext fixes 
+
+### v0.7.0 / 2020-10-07
+
+* ADDED: Add service_name setter to configurator 
+* ADDED: Add service_version setter to configurator 
+* FIXED: Fork safety for batch processor 
+* FIXED: Don't generate a span ID unnecessarily 
+* DOCS: Fix Configurator#add_span_processor 
+* DOCS: Standardize toplevel docs structure and readme 
+
 ### v0.6.0 / 2020-09-10
 
 * BREAKING CHANGE: Rename Resource labels to attributes 

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

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
 
@@ -44,6 +44,26 @@ module OpenTelemetry
         @resource = new_resource.merge(@resource)
       end
 
+      # Accepts a string that is merged in as the service.name resource attribute.
+      # The most recent assigned value will be used in the event of repeated
+      # calls to this setter.
+      # @param [String] service_name The value to be used as the service name
+      def service_name=(service_name)
+        @resource = OpenTelemetry::SDK::Resources::Resource.create(
+          OpenTelemetry::SDK::Resources::Constants::SERVICE_RESOURCE[:name] => service_name
+        ).merge(@resource)
+      end
+
+      # Accepts a string that is merged in as the service.version resource attribute.
+      # The most recent assigned value will be used in the event of repeated
+      # calls to this setter.
+      # @param [String] service_version The value to be used as the service version
+      def service_version=(service_version)
+        @resource = OpenTelemetry::SDK::Resources::Resource.create(
+          OpenTelemetry::SDK::Resources::Constants::SERVICE_RESOURCE[:version] => service_version
+        ).merge(@resource)
+      end
+
       # Install an instrumentation with specificied optional +config+.
       # Use can be called multiple times to install multiple instrumentation.
       # Only +use+ or +use_all+, but not both when installing
@@ -73,8 +93,8 @@ module OpenTelemetry
 
       # Add a span processor to the export pipeline
       #
-      # @param [#on_start, #on_finish, #shutdown] span_processor A span_processor
-      #   that satisfies the duck type #on_start, #on_finish, #shutdown. See
+      # @param [#on_start, #on_finish, #shutdown, #force_flush] span_processor A span_processor
+      #   that satisfies the duck type #on_start, #on_finish, #shutdown, #force_flush. See
       #   {SimpleSpanProcessor} for an example.
       def add_span_processor(span_processor)
         @span_processors << span_processor

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
 

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
 
@@ -79,10 +79,6 @@ module OpenTelemetry
 
         # Attributes defining a computing instance (e.g. host).
         HOST_RESOURCE = {
-          # Hostname of the host. It contains what the hostname command returns on the
-          # host machine.
-          hostname: 'host.hostname',
-
           # Unique host id. For Cloud this must be the instance_id assigned by the
           # cloud provider
           id: 'host.id',

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
 

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
 

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,22 +1,27 @@
 # frozen_string_literal: true
 
-# Copyright 2019 OpenTelemetry Authors
+# Copyright The 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
+      # 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
@@ -25,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,39 +47,44 @@ 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 = []
-            @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?
+              report_dropped_spans(n, reason: 'buffer-full')
               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.
           #
@@ -84,35 +92,66 @@ 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?
+              report_dropped_spans(n, reason: 'buffer-full')
+              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))
+            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)
                 @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
@@ -120,23 +159,40 @@ 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
 
-          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)
-            OpenTelemetry.logger.error("Unable to export #{batch.size} spans") unless result_code == SUCCESS
+            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.logger.error("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_dropped_spans(count, reason:)
+            @metrics_reporter.add_to_counter('otel.bsp.dropped_spans', increment: count, labels: { 'reason' => reason })
           end
 
           def fetch_batch