opentelemetry-sdk 0.6.0 → 0.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3a01fcf121db23108ffb47d196f9594993018bb1b945242710620bb87daa8320
-  data.tar.gz: ef3b3e9cd4e2853a22ffb149e7a18cbd021988412d24c40350192e222b3be58b
+  metadata.gz: b5510dccb3f3f94057ab6f17a625b8c71fbeeb958d2ec2de2eb732bfc59a4225
+  data.tar.gz: 768a8e36a2a5a34458d6872584339a93d14d83b0302ed998626d21d97d4592b7
 SHA512:
-  metadata.gz: 5da08d0e902ece66efc7afa892f99f2b9fe3bcd5b89b51cd3da1a565a23ab0917eb1c39d6fb44ed6b82a71048624cb357539d9b6305b1a0c8debc594ef2467d3
-  data.tar.gz: 5fe47387c0d91e8d5436be4d4464839f08a9ae46964e8fe1679ab6ef7e7bf8b7a59ae086472d465e6f12c57b70c712a982064351f287a8ebbb6bbe173c37b45d
+  metadata.gz: ab2eb7f6eec8f1c62812e8a6f53502a2f29d017489078ede3c5fc4b4b9928435e71658c2cb506b73a16098ef681fffd9d088a028fd6938fec3da0d6a30cc3ec8
+  data.tar.gz: a1ee4191297bdb3491988e0bca431274f29685057578781e3911bd9f34e66042826aa1528c5eda9172d65beeaf6aeed269185665eb0f6a2361500de09a311c10

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,14 @@
 # Release History: opentelemetry-sdk
 
+### 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/lib/opentelemetry/sdk/configurator.rb

@@ -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/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

@@ -56,11 +56,13 @@ module OpenTelemetry
             @max_queue_size = max_queue_size
             @batch_size = max_export_batch_size
             @spans = []
-            @thread = Thread.new { work }
+            @pid = nil
+            @thread = nil
+            reset_on_fork
           end
 
           # does nothing for this processor
-          def on_start(span)
+          def on_start(span, parent_context)
             # noop
           end
 
@@ -69,6 +71,7 @@ module OpenTelemetry
             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
@@ -84,17 +87,27 @@ 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.
+          #
+          # @return [Integer] SUCCESS if no error occurred, FAILURE if a
+          #   non-specific failure occurred, TIMEOUT if a timeout occurred.
           def force_flush
-            snapshot = lock { spans.shift(spans.size) }
+            snapshot = lock do
+              reset_on_fork(restart_thread: false) if @keep_running
+              spans.shift(spans.size)
+            end
             until snapshot.empty?
               batch = snapshot.shift(@batch_size).map!(&:to_span_data)
               result_code = @exporter.export(batch)
               report_result(result_code, batch)
             end
+            SUCCESS
           end
 
           # shuts the consumer thread down and flushes the current accumulated buffer
           # will block until the thread is finished
+          #
+          # @return [Integer] SUCCESS if no error occurred, FAILURE if a
+          #   non-specific failure occurred, TIMEOUT if a timeout occurred.
           def shutdown
             lock do
               @keep_running = false
@@ -113,6 +126,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
@@ -124,6 +138,15 @@ module OpenTelemetry
             end
           end
 
+          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_batch(batch)
             result_code = export_with_timeout(batch)
             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
+            return FAILURE if @stopped
 
             Array(spans).each { |s| pp s }
 
-            ResultCodes::SUCCESS
+            SUCCESS
           end
 
           def shutdown
             @stopped = true
+            SUCCESS
           end
         end
       end

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

@@ -73,11 +73,15 @@ module OpenTelemetry
 
           # Called when {TracerProvider#shutdown} is called, if this exporter is
           # registered to a {TracerProvider} object.
+          #
+          # @return [Integer] SUCCESS if no error occurred, FAILURE if a
+          #   non-specific failure occurred, TIMEOUT if a timeout occurred.
           def shutdown
             @mutex.synchronize do
               @finished_spans.clear
               @stopped = true
             end
+            SUCCESS
           end
         end
       end

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

@@ -35,8 +35,11 @@ module OpenTelemetry
 
           # Called when {TracerProvider#shutdown} is called, if this exporter is
           # registered to a {TracerProvider} object.
+          #
+          # @return [Integer] SUCCESS if no error occurred, FAILURE if a
+          #   non-specific failure occurred, TIMEOUT if a timeout occurred.
           def shutdown
-            @span_exporters.each(&:shutdown)
+            @span_exporters.map(&:shutdown).uniq.max
           end
 
           private

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

@@ -34,6 +34,7 @@ module OpenTelemetry
           # registered to a {TracerProvider} object.
           def shutdown
             @stopped = true
+            SUCCESS
           end
         end
       end

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

@@ -33,7 +33,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 +61,19 @@ 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
+          #
+          # @return [Integer] SUCCESS if no error occurred, FAILURE if a
+          #   non-specific failure occurred, TIMEOUT if a timeout occurred.
+          def force_flush
+            SUCCESS
+          end
 
           # Called when {TracerProvider#shutdown} is called.
+          #
+          # @return [Integer] SUCCESS if no error occurred, FAILURE if a
+          #   non-specific failure occurred, TIMEOUT if a timeout occurred.
           def shutdown
-            @span_exporter&.shutdown
+            @span_exporter&.shutdown || SUCCESS
           end
         end
       end

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

@@ -26,8 +26,10 @@ module OpenTelemetry
         # not throw or block the execution thread.
         #
         # @param [Span] span the {Span} that just started.
-        def on_start(span)
-          @span_processors.each { |processor| processor.on_start(span) }
+        # @param [Context] parent_context the parent {Context} of the newly
+        #  started span.
+        def on_start(span, parent_context)
+          @span_processors.each { |processor| processor.on_start(span, parent_context) }
         end
 
         # Called when a {Span} is ended, if the {Span#recording?}
@@ -48,13 +50,19 @@ 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.
+        #
+        # @return [Integer] Export::SUCCESS if no error occurred, Export::FAILURE if
+        #   a non-specific failure occurred, Export::TIMEOUT if a timeout occurred.
         def force_flush
-          @span_processors.each(&:force_flush)
+          @span_processors.map(&:force_flush).uniq.max
         end
 
         # Called when {TracerProvider#shutdown} is called.
+        #
+        # @return [Integer] Export::SUCCESS if no error occurred, Export::FAILURE if
+        #   a non-specific failure occurred, Export::TIMEOUT if a timeout occurred.
         def shutdown
-          @span_processors.each(&:shutdown)
+          @span_processors.map(&:shutdown).uniq.max
         end
       end
     end

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

@@ -22,7 +22,9 @@ module OpenTelemetry
         # not throw or block the execution thread.
         #
         # @param [Span] span the {Span} that just started.
-        def on_start(span); end
+        # @param [Context] parent_context the parent {Context} of the newly
+        #  started span.
+        def on_start(span, parent_context); end
 
         # Called when a {Span} is ended, if the {Span#recording?}
         # returns true.
@@ -40,10 +42,20 @@ 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
+        #
+        # @return [Integer] Export::SUCCESS if no error occurred, Export::FAILURE if
+        #   a non-specific failure occurred, Export::TIMEOUT if a timeout occurred.
+        def force_flush
+          Export::SUCCESS
+        end
 
         # Called when {TracerProvider#shutdown} is called.
-        def shutdown; end
+        #
+        # @return [Integer] Export::SUCCESS if no error occurred, Export::FAILURE if
+        #   a non-specific failure occurred, Export::TIMEOUT if a timeout occurred.
+        def shutdown
+          Export::SUCCESS
+        end
       end
     end
   end

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

@@ -37,18 +37,18 @@ module OpenTelemetry
       #   to the {Span} to be created. Can be nil.
       # @return [Result] The sampling result.
       module Samplers
-        RECORD_AND_SAMPLED = Result.new(decision: Decision::RECORD_AND_SAMPLED)
-        NOT_RECORD = Result.new(decision: Decision::NOT_RECORD)
-        RECORD = Result.new(decision: Decision::RECORD)
-        SAMPLING_HINTS = [Decision::NOT_RECORD, Decision::RECORD, Decision::RECORD_AND_SAMPLED].freeze
+        RECORD_AND_SAMPLE = Result.new(decision: Decision::RECORD_AND_SAMPLE)
+        DROP = Result.new(decision: Decision::DROP)
+        RECORD_ONLY = Result.new(decision: Decision::RECORD_ONLY)
+        SAMPLING_HINTS = [Decision::DROP, Decision::RECORD_ONLY, Decision::RECORD_AND_SAMPLE].freeze
 
-        private_constant(:RECORD_AND_SAMPLED, :NOT_RECORD, :RECORD, :SAMPLING_HINTS)
+        private_constant(:RECORD_AND_SAMPLE, :DROP, :RECORD_ONLY, :SAMPLING_HINTS)
 
-        # Returns a {Result} with {Decision::RECORD_AND_SAMPLED}.
-        ALWAYS_ON = ConstantSampler.new(result: RECORD_AND_SAMPLED, description: 'AlwaysOnSampler')
+        # Returns a {Result} with {Decision::RECORD_AND_SAMPLE}.
+        ALWAYS_ON = ConstantSampler.new(result: RECORD_AND_SAMPLE, description: 'AlwaysOnSampler')
 
-        # Returns a {Result} with {Decision::NOT_RECORD}.
-        ALWAYS_OFF = ConstantSampler.new(result: NOT_RECORD, description: 'AlwaysOffSampler')
+        # Returns a {Result} with {Decision::DROP}.
+        ALWAYS_OFF = ConstantSampler.new(result: DROP, description: 'AlwaysOffSampler')
 
         # Returns a new sampler. It delegates to samplers according to the following rules:
         #

data/lib/opentelemetry/sdk/trace/samplers/decision.rb

@@ -12,13 +12,13 @@ module OpenTelemetry
         # decision part of a sampling {Result}.
         module Decision
           # Decision to not record events and not sample.
-          NOT_RECORD = :__not_record__
+          DROP = :__drop__
 
           # Decision to record events and not sample.
-          RECORD = :__record__
+          RECORD_ONLY = :__record_only__
 
           # Decision to record events and sample.
-          RECORD_AND_SAMPLED = :__record_and_sampled__
+          RECORD_AND_SAMPLE = :__record_and_sample__
         end
       end
     end

data/lib/opentelemetry/sdk/trace/samplers/result.rb

@@ -14,7 +14,7 @@ module OpenTelemetry
         # root span.
         class Result
           EMPTY_HASH = {}.freeze
-          DECISIONS = [Decision::RECORD, Decision::NOT_RECORD, Decision::RECORD_AND_SAMPLED].freeze
+          DECISIONS = [Decision::RECORD_ONLY, Decision::DROP, Decision::RECORD_AND_SAMPLE].freeze
           private_constant(:EMPTY_HASH, :DECISIONS)
 
           # Returns a frozen hash of attributes to be attached span.
@@ -39,14 +39,14 @@ module OpenTelemetry
           #
           # @return [Boolean] sampling decision
           def sampled?
-            @decision == Decision::RECORD_AND_SAMPLED
+            @decision == Decision::RECORD_AND_SAMPLE
           end
 
           # Returns true if this span should record events, attributes, status, etc.
           #
           # @return [Boolean] recording decision
           def recording?
-            @decision != Decision::NOT_RECORD
+            @decision != Decision::DROP
           end
         end
       end

data/lib/opentelemetry/sdk/trace/samplers/trace_id_ratio_based.rb

@@ -27,9 +27,9 @@ module OpenTelemetry
             # Ignored for sampling decision: parent_context:, links, name, kind, attributes.
 
             if sample?(trace_id)
-              RECORD_AND_SAMPLED
+              RECORD_AND_SAMPLE
             else
-              NOT_RECORD
+              DROP
             end
           end
 

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

@@ -16,6 +16,10 @@ module OpenTelemetry
       #
       # rubocop:disable Metrics/ClassLength
       class Span < OpenTelemetry::Trace::Span
+        DEFAULT_STATUS = OpenTelemetry::Trace::Status.new(OpenTelemetry::Trace::Status::UNSET)
+
+        private_constant(:DEFAULT_STATUS)
+
         # The following readers are intended for the use of SpanProcessors and
         # should not be considered part of the public interface for instrumentation.
         attr_reader :name, :status, :kind, :parent_span_id, :start_timestamp, :end_timestamp, :links, :resource, :instrumentation_library
@@ -219,7 +223,6 @@ module OpenTelemetry
             @kind,
             @status,
             @parent_span_id,
-            @child_count,
             @total_recorded_attributes,
             @total_recorded_events,
             @total_recorded_links,
@@ -238,7 +241,7 @@ module OpenTelemetry
         end
 
         # @api private
-        def initialize(context, name, kind, parent_span_id, trace_config, span_processor, attributes, links, start_timestamp, resource, instrumentation_library) # rubocop:disable Metrics/AbcSize, Metrics/MethodLength
+        def initialize(context, parent_context, name, kind, parent_span_id, trace_config, span_processor, attributes, links, start_timestamp, resource, instrumentation_library) # rubocop:disable Metrics/AbcSize
           super(span_context: context)
           @mutex = Mutex.new
           @name = name
@@ -249,8 +252,7 @@ module OpenTelemetry
           @resource = resource
           @instrumentation_library = instrumentation_library
           @ended = false
-          @status = nil
-          @child_count = 0
+          @status = DEFAULT_STATUS
           @total_recorded_events = 0
           @total_recorded_links = links&.size || 0
           @total_recorded_attributes = attributes&.size || 0
@@ -260,7 +262,7 @@ module OpenTelemetry
           trim_span_attributes(@attributes)
           @events = nil
           @links = trim_links(links, trace_config.max_links_count, trace_config.max_attributes_per_link)
-          @span_processor.on_start(self)
+          @span_processor.on_start(self, parent_context)
         end
 
         # TODO: Java implementation overrides finalize to log if a span isn't finished.

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

@@ -14,7 +14,6 @@ module OpenTelemetry
                             :kind,
                             :status,
                             :parent_span_id,
-                            :child_count,
                             :total_recorded_attributes,
                             :total_recorded_events,
                             :total_recorded_links,

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

@@ -30,33 +30,34 @@ module OpenTelemetry
         end
 
         def start_root_span(name, attributes: nil, links: nil, start_timestamp: nil, kind: nil)
-          start_span(name, with_parent_context: Context.empty, attributes: attributes, links: links, start_timestamp: start_timestamp, kind: kind)
+          start_span(name, with_parent: Context.empty, attributes: attributes, links: links, start_timestamp: start_timestamp, kind: kind)
         end
 
-        def start_span(name, with_parent: nil, with_parent_context: nil, attributes: nil, links: nil, start_timestamp: nil, kind: nil)
+        def start_span(name, with_parent: nil, attributes: nil, links: nil, start_timestamp: nil, kind: nil) # rubocop:disable Metrics/AbcSize
           name ||= 'empty'
 
-          parent_span_context = with_parent&.context || active_span_context(with_parent_context)
+          with_parent ||= Context.current
+          parent_span_context = current_span(with_parent).context
           parent_span_context = nil unless parent_span_context.valid?
           parent_span_id = parent_span_context&.span_id
           tracestate = parent_span_context&.tracestate
           trace_id = parent_span_context&.trace_id
           trace_id ||= OpenTelemetry::Trace.generate_trace_id
-          span_id = OpenTelemetry::Trace.generate_span_id
           sampler = tracer_provider.active_trace_config.sampler
           result = sampler.should_sample?(trace_id: trace_id, parent_context: parent_span_context, links: links, name: name, kind: kind, attributes: attributes)
-          internal_create_span(result, name, kind, trace_id, span_id, parent_span_id, attributes, links, start_timestamp, tracestate)
+          internal_create_span(result, name, kind, trace_id, parent_span_id, attributes, links, start_timestamp, tracestate, with_parent)
         end
 
         private
 
-        def internal_create_span(result, name, kind, trace_id, span_id, parent_span_id, attributes, links, start_timestamp, tracestate) # rubocop:disable Metrics/AbcSize
+        def internal_create_span(result, name, kind, trace_id, parent_span_id, attributes, links, start_timestamp, tracestate, parent_context) # rubocop:disable Metrics/AbcSize
           if result.recording? && !tracer_provider.stopped?
             trace_flags = result.sampled? ? OpenTelemetry::Trace::TraceFlags::SAMPLED : OpenTelemetry::Trace::TraceFlags::DEFAULT
             context = OpenTelemetry::Trace::SpanContext.new(trace_id: trace_id, trace_flags: trace_flags, tracestate: tracestate)
             attributes = attributes&.merge(result.attributes) || result.attributes
             Span.new(
               context,
+              parent_context,
               name,
               kind,
               parent_span_id,

data/lib/opentelemetry/sdk/version.rb

@@ -7,6 +7,6 @@
 module OpenTelemetry
   module SDK
     ## Current OpenTelemetry version
-    VERSION = '0.6.0'
+    VERSION = '0.7.0'
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: opentelemetry-sdk
 version: !ruby/object:Gem::Version
-  version: 0.6.0
+  version: 0.7.0
 platform: ruby
 authors:
 - OpenTelemetry Authors
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2020-09-11 00:00:00.000000000 Z
+date: 2020-10-08 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: opentelemetry-api
@@ -16,14 +16,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.6.0
+        version: 0.7.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.6.0
+        version: 0.7.0
 - !ruby/object:Gem::Dependency
   name: bundler
   requirement: !ruby/object:Gem::Requirement
@@ -201,7 +201,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.1.2
+rubygems_version: 3.1.4
 signing_key: 
 specification_version: 4
 summary: A stats collection and distributed tracing framework