opentelemetry-sdk 0.5.0 → 0.9.0

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,35 @@ 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
-          @span_processors.each(&:force_flush)
+        #
+        # @param [optional Numeric] timeout An optional timeout in seconds.
+        # @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(timeout: nil)
+          start_time = Time.now
+          results = @span_processors.map do |processor|
+            remaining_timeout = OpenTelemetry::Common::Utilities.maybe_timeout(timeout, start_time)
+            return Export::TIMEOUT if remaining_timeout&.zero?
+
+            processor.force_flush(timeout: remaining_timeout)
+          end
+          results.uniq.max
         end
 
         # Called when {TracerProvider#shutdown} is called.
-        def shutdown
-          @span_processors.each(&:shutdown)
+        #
+        # @param [optional Numeric] timeout An optional timeout in seconds.
+        # @return [Integer] Export::SUCCESS if no error occurred, Export::FAILURE if
+        #   a non-specific failure occurred, Export::TIMEOUT if a timeout occurred.
+        def shutdown(timeout: nil)
+          start_time = Time.now
+          results = @span_processors.map do |processor|
+            remaining_timeout = OpenTelemetry::Common::Utilities.maybe_timeout(timeout, start_time)
+            return Export::TIMEOUT if remaining_timeout&.zero?
+
+            processor.shutdown(timeout: remaining_timeout)
+          end
+          results.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,22 @@ 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] Export::SUCCESS if no error occurred, Export::FAILURE if
+        #   a non-specific failure occurred, Export::TIMEOUT if a timeout occurred.
+        def force_flush(timeout: nil)
+          Export::SUCCESS
+        end
 
         # Called when {TracerProvider#shutdown} is called.
-        def shutdown; end
+        #
+        # @param [optional Numeric] timeout An optional timeout in seconds.
+        # @return [Integer] Export::SUCCESS if no error occurred, Export::FAILURE if
+        #   a non-specific failure occurred, Export::TIMEOUT if a timeout occurred.
+        def shutdown(timeout: nil)
+          Export::SUCCESS
+        end
       end
     end
   end

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

@@ -7,15 +7,15 @@
 require 'opentelemetry/sdk/trace/samplers/decision'
 require 'opentelemetry/sdk/trace/samplers/result'
 require 'opentelemetry/sdk/trace/samplers/constant_sampler'
-require 'opentelemetry/sdk/trace/samplers/parent_or_else'
-require 'opentelemetry/sdk/trace/samplers/probability_sampler'
+require 'opentelemetry/sdk/trace/samplers/parent_based'
+require 'opentelemetry/sdk/trace/samplers/trace_id_ratio_based'
 
 module OpenTelemetry
   module SDK
     module Trace
       # The Samplers module contains the sampling logic for OpenTelemetry. The
-      # reference implementation provides a {ProbabilitySampler}, {ALWAYS_ON},
-      # {ALWAYS_OFF}, and {ParentOrElse}.
+      # reference implementation provides a {TraceIdRatioBased}, {ALWAYS_ON},
+      # {ALWAYS_OFF}, and {ParentBased}.
       #
       # Custom samplers can be provided by SDK users. The required interface is:
       #
@@ -25,9 +25,10 @@ module OpenTelemetry
       # Where:
       #
       # @param [String] trace_id The trace_id of the {Span} to be created.
-      # @param [OpenTelemetry::Trace::SpanContext] parent_context The
-      #   {OpenTelemetry::Trace::SpanContext} of a parent span, typically
-      #   extracted from the wire. Can be nil for a root span.
+      # @param [OpenTelemetry::Context] parent_context The
+      #   {OpenTelemetry::Context} with a parent {Span}. The {Span}'s
+      #   {OpenTelemetry::Trace::SpanContext} may be invalid to indicate a
+      #   root span.
       # @param [Enumerable<Link>] links A collection of links to be associated
       #   with the {Span} to be created. Can be nil.
       # @param [String] name Name of the {Span} to be created.
@@ -37,52 +38,59 @@ 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
-        APPLY_PROBABILITY_TO_SYMBOLS = %i[root_spans root_spans_and_remote_parent all_spans].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, :APPLY_PROBABILITY_TO_SYMBOLS)
+        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 either respects the parent span's sampling
-        # decision or delegates to delegate_sampler for root spans.
+        # Returns a new sampler. It delegates to samplers according to the following rules:
         #
-        # @param [Sampler] delegate_sampler The sampler to which the sampling
-        #   decision is delegated for root spans.
-        def self.parent_or_else(delegate_sampler)
-          ParentOrElse.new(delegate_sampler)
+        # | Parent | parent.remote? | parent.trace_flags.sampled? | Invoke sampler |
+        # |--|--|--|--|
+        # | absent | n/a | n/a | root |
+        # | present | true | true | remote_parent_sampled |
+        # | present | true | false | remote_parent_not_sampled |
+        # | present | false | true | local_parent_sampled |
+        # | present | false | false | local_parent_not_sampled |
+        #
+        # @param [Sampler] root The sampler to which the sampling
+        #   decision is delegated for spans with no parent (root spans).
+        # @param [optional Sampler] remote_parent_sampled The sampler to which the sampling
+        #   decision is delegated for remote parent sampled spans. Defaults to ALWAYS_ON.
+        # @param [optional Sampler] remote_parent_not_sampled The sampler to which the sampling
+        #   decision is delegated for remote parent not sampled spans. Defaults to ALWAYS_OFF.
+        # @param [optional Sampler] local_parent_sampled The sampler to which the sampling
+        #   decision is delegated for local parent sampled spans. Defaults to ALWAYS_ON.
+        # @param [optional Sampler] local_parent_not_sampled The sampler to which the sampling
+        #   decision is delegated for local parent not sampld spans. Defaults to ALWAYS_OFF.
+        def self.parent_based(
+          root:,
+          remote_parent_sampled: ALWAYS_ON,
+          remote_parent_not_sampled: ALWAYS_OFF,
+          local_parent_sampled: ALWAYS_ON,
+          local_parent_not_sampled: ALWAYS_OFF
+        )
+          ParentBased.new(root, remote_parent_sampled, remote_parent_not_sampled, local_parent_sampled, local_parent_not_sampled)
         end
 
-        # Returns a new sampler. The probability of sampling a trace is equal
-        # to that of the specified probability.
+        # Returns a new sampler. The ratio describes the proportion of the trace ID
+        # space that is sampled.
         #
-        # @param [Numeric] probability The desired probability of sampling.
+        # @param [Numeric] ratio The desired sampling ratio.
         #   Must be within [0.0, 1.0].
-        # @param [optional Boolean] ignore_parent Whether to ignore parent
-        #   sampling. Defaults to not ignore parent sampling.
-        # @param [optional Symbol] apply_probability_to Whether to apply
-        #   probability sampling to root spans, root spans and remote parents,
-        #   or all spans. Allowed values include :root_spans, :root_spans_and_remote_parent,
-        #   and :all_spans. Defaults to :root_spans_and_remote_parent.
-        # @raise [ArgumentError] if probability is out of range
-        # @raise [ArgumentError] if apply_probability_to is not one of the allowed symbols
-        def self.probability(probability,
-                             ignore_parent: false,
-                             apply_probability_to: :root_spans_and_remote_parent)
-          raise ArgumentError, 'probability must be in range [0.0, 1.0]' unless (0.0..1.0).include?(probability)
-          raise ArgumentError, 'apply_probability_to' unless APPLY_PROBABILITY_TO_SYMBOLS.include?(apply_probability_to)
+        # @raise [ArgumentError] if ratio is out of range
+        def self.trace_id_ratio_based(ratio)
+          raise ArgumentError, 'ratio must be in range [0.0, 1.0]' unless (0.0..1.0).include?(ratio)
 
-          ProbabilitySampler.new(probability,
-                                 ignore_parent: ignore_parent,
-                                 apply_to_remote_parent: apply_probability_to != :root_spans,
-                                 apply_to_all_spans: apply_probability_to == :all_spans)
+          TraceIdRatioBased.new(ratio)
         end
       end
     end

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/parent_based.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+# Copyright The OpenTelemetry Authors
+#
+# SPDX-License-Identifier: Apache-2.0
+
+module OpenTelemetry
+  module SDK
+    module Trace
+      module Samplers
+        # @api private
+        #
+        # This is a composite sampler. ParentBased helps distinguished between the
+        # following cases:
+        #   * No parent (root span).
+        #   * Remote parent (SpanContext.remote? with trace_flags.sampled?)
+        #   * Remote parent (SpanContext.remote? with !trace_flags.sampled?)
+        #   * Local parent (!SpanContext.remote? with trace_flags.sampled?)
+        #   * Local parent (!SpanContext.remote? with !trace_flags.sampled?)
+        class ParentBased
+          def initialize(root, remote_parent_sampled, remote_parent_not_sampled, local_parent_sampled, local_parent_not_sampled)
+            @root = root
+            @remote_parent_sampled = remote_parent_sampled
+            @remote_parent_not_sampled = remote_parent_not_sampled
+            @local_parent_sampled = local_parent_sampled
+            @local_parent_not_sampled = local_parent_not_sampled
+          end
+
+          # @api private
+          #
+          # See {Samplers}.
+          def description
+            "ParentBased{root=#{@root.description}, remote_parent_sampled=#{@remote_parent_sampled.description}, remote_parent_not_sampled=#{@remote_parent_not_sampled.description}, local_parent_sampled=#{@local_parent_sampled.description}, local_parent_not_sampled=#{@local_parent_not_sampled.description}}"
+          end
+
+          # @api private
+          #
+          # See {Samplers}.
+          def should_sample?(trace_id:, parent_context:, links:, name:, kind:, attributes:)
+            parent_span_context = OpenTelemetry::Trace.current_span(parent_context).context
+            delegate = if !parent_span_context.valid?
+                         @root
+                       elsif parent_span_context.remote?
+                         parent_span_context.trace_flags.sampled? ? @remote_parent_sampled : @remote_parent_not_sampled
+                       else
+                         parent_span_context.trace_flags.sampled? ? @local_parent_sampled : @local_parent_not_sampled
+                       end
+            delegate.should_sample?(trace_id: trace_id, parent_context: parent_context, links: links, name: name, kind: kind, attributes: attributes)
+          end
+        end
+      end
+    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

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+# Copyright 2019 OpenTelemetry Authors
+#
+# SPDX-License-Identifier: Apache-2.0
+
+module OpenTelemetry
+  module SDK
+    module Trace
+      module Samplers
+        # @api private
+        #
+        # Implements sampling based on a probability.
+        class TraceIdRatioBased
+          attr_reader :description
+
+          def initialize(probability)
+            @probability = probability
+            @id_upper_bound = (probability * (2**64 - 1)).ceil
+            @description = format('TraceIdRatioBased{%.6f}', probability)
+          end
+
+          # @api private
+          #
+          # See {Samplers}.
+          def should_sample?(trace_id:, parent_context:, links:, name:, kind:, attributes:)
+            # Ignored for sampling decision: parent_context:, links, name, kind, attributes.
+
+            if sample?(trace_id)
+              RECORD_AND_SAMPLE
+            else
+              DROP
+            end
+          end
+
+          private
+
+          def sample?(trace_id)
+            @probability == 1.0 || trace_id[8, 8].unpack1('Q>') < @id_upper_bound
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -16,12 +16,16 @@ 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, :library_resource, :instrumentation_library
+        attr_reader :name, :status, :kind, :parent_span_id, :start_timestamp, :end_timestamp, :links, :resource, :instrumentation_library
 
         # Return a frozen copy of the current attributes. This is intended for
-        # use of SpanProcesses and should not be considered part of the public
+        # use of SpanProcessors and should not be considered part of the public
         # interface for instrumentation.
         #
         # @return [Hash{String => String, Numeric, Boolean, Array<String, Numeric, Boolean>}] may be nil.
@@ -48,7 +52,7 @@ module OpenTelemetry
         #   like events with the #add_event operation and attributes using
         #   #set_attribute.
         def recording?
-          true
+          !@ended
         end
 
         # Set attribute
@@ -59,7 +63,7 @@ module OpenTelemetry
         # meanings.
         #
         # @param [String] key
-        # @param [String, Boolean, Numeric] value
+        # @param [String, Boolean, Numeric, Array<String, Numeric, Boolean>] value
         #
         # @return [self] returns itself
         def set_attribute(key, value)
@@ -76,37 +80,29 @@ module OpenTelemetry
           end
           self
         end
+        alias []= set_attribute
 
-        # Add an Event to a {Span}. This can be accomplished eagerly or lazily.
-        # Lazy evaluation is useful when the event attributes are expensive to
-        # build and where the cost can be avoided for an unsampled {Span}.
-        #
-        # Eager example:
-        #
-        #   span.add_event(name: 'event', attributes: {'eager' => true})
+        # Add an Event to a {Span}.
         #
-        # Lazy example:
+        # Example:
         #
-        #   span.add_event { OpenTelemetry::Trace::Event.new(name: 'event', attributes: {'eager' => false}) }
+        #   span.add_event('event', attributes: {'eager' => true})
         #
         # Note that the OpenTelemetry project
         # {https://github.com/open-telemetry/opentelemetry-specification/blob/master/specification/data-semantic-conventions.md
         # documents} certain "standard event names and keys" which have
         # prescribed semantic meanings.
         #
-        # @param [optional String] name Optional name of the event. This is
-        #   required if a block is not given.
+        # @param [String] name Name of the event.
         # @param [optional Hash{String => String, Numeric, Boolean, Array<String, Numeric, Boolean>}] attributes
         #   One or more key:value pairs, where the keys must be strings and the
-        #   values may be string, boolean or numeric type. This argument should
-        #   only be used when passing in a name.
+        #   values may be string, boolean or numeric type.
         # @param [optional Time] timestamp Optional timestamp for the event.
-        #   This argument should only be used when passing in a name.
         #
         # @return [self] returns itself
-        def add_event(name: nil, attributes: nil, timestamp: nil)
+        def add_event(name, attributes: nil, timestamp: nil)
           super
-          event = block_given? ? yield : OpenTelemetry::Trace::Event.new(name: name, attributes: attributes, timestamp: timestamp || Time.now)
+          event = Event.new(name: name, attributes: attributes, timestamp: timestamp || Time.now)
 
           @mutex.synchronize do
             if @ended
@@ -120,18 +116,18 @@ module OpenTelemetry
           self
         end
 
-        # Record an error during the execution of this span. Multiple errors
+        # Record an exception during the execution of this span. Multiple exceptions
         # can be recorded on a span.
         #
-        # @param [Exception] error The error to be recorded
+        # @param [Exception] exception The exception to be recorded
         #
         # @return [void]
-        def record_error(error)
-          add_event(name: 'error',
+        def record_exception(exception)
+          add_event('exception',
                     attributes: {
-                      'error.type' => error.class.to_s,
-                      'error.message' => error.message,
-                      'error.stack' => error.backtrace.join("\n")
+                      'exception.type' => exception.class.to_s,
+                      'exception.message' => exception.message,
+                      'exception.stacktrace' => exception.full_message(highlight: false, order: :top)
                     })
         end
 
@@ -227,7 +223,6 @@ module OpenTelemetry
             @kind,
             @status,
             @parent_span_id,
-            @child_count,
             @total_recorded_attributes,
             @total_recorded_events,
             @total_recorded_links,
@@ -236,7 +231,7 @@ module OpenTelemetry
             @attributes,
             @links,
             @events,
-            @library_resource,
+            @resource,
             @instrumentation_library,
             context.span_id,
             context.trace_id,
@@ -246,7 +241,7 @@ module OpenTelemetry
         end
 
         # @api private
-        def initialize(context, name, kind, parent_span_id, trace_config, span_processor, attributes, links, start_timestamp, library_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
@@ -254,11 +249,10 @@ module OpenTelemetry
           @parent_span_id = parent_span_id.freeze || OpenTelemetry::Trace::INVALID_SPAN_ID
           @trace_config = trace_config
           @span_processor = span_processor
-          @library_resource = library_resource
+          @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
@@ -268,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.
@@ -300,7 +294,7 @@ module OpenTelemetry
             attrs.keep_if { |key, value| Internal.valid_key?(key) && Internal.valid_value?(value) }
             excess = attrs.size - max_attributes_per_link
             excess.times { attrs.shift } if excess.positive?
-            OpenTelemetry::Trace::Link.new(link.context, attrs)
+            OpenTelemetry::Trace::Link.new(link.span_context, attrs)
           end.freeze
         end
 
@@ -325,7 +319,7 @@ module OpenTelemetry
             attrs.keep_if { |key, value| Internal.valid_key?(key) && Internal.valid_value?(value) }
             excess = attrs.size - max_attributes_per_event
             excess.times { attrs.shift } if excess.positive?
-            event = OpenTelemetry::Trace::Event.new(name: event.name, attributes: attrs, timestamp: event.timestamp)
+            event = Event.new(name: event.name, attributes: attrs, timestamp: event.timestamp)
           end
           events << event
         end