opentelemetry-sdk 0.4.0 → 0.8.0

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::FAILED_NOT_RETRYABLE 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

@@ -61,10 +61,10 @@ module OpenTelemetry
           # @param [Enumerable<SpanData>] span_datas the list of sampled {SpanData}s to be
           #   exported.
           # @return [Integer] the result of the export, SUCCESS or
-          #   FAILED_NOT_RETRYABLE
+          #   FAILURE
           def export(span_datas)
             @mutex.synchronize do
-              return FAILED_NOT_RETRYABLE if @stopped
+              return FAILURE if @stopped
 
               @finished_spans.concat(span_datas.to_a)
             end
@@ -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

@@ -29,14 +29,17 @@ module OpenTelemetry
               merge_result_code(result_code, span_exporter.export(spans))
             rescue => e # rubocop:disable Style/RescueStandardError
               OpenTelemetry.logger.warn("exception raised by export - #{e}")
-              FAILED_NOT_RETRYABLE
+              FAILURE
             end
           end
 
           # 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
@@ -46,13 +49,9 @@ module OpenTelemetry
             if result_code == SUCCESS && new_result_code == SUCCESS
               # If both errors are success then return success.
               SUCCESS
-            elsif result_code == FAILED_NOT_RETRYABLE || new_result_code == FAILED_NOT_RETRYABLE
-              # If any of the codes is not retryable then return not_retryable.
-              FAILED_NOT_RETRYABLE
             else
-              # At this point at least one of the code is FAILED_RETRYABLE and
-              # none are FAILED_NOT_RETRYABLE, so return FAILED_RETRYABLE.
-              FAILED_RETRYABLE
+              # At this point at least one of the code is FAILURE, so return FAILURE.
+              FAILURE
             end
           end
         end

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

@@ -27,13 +27,14 @@ module OpenTelemetry
           def export(spans)
             return SUCCESS unless @stopped
 
-            FAILED_NOT_RETRYABLE
+            FAILURE
           end
 
           # Called when {TracerProvider#shutdown} is called, if this exporter is
           # 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

@@ -6,24 +6,25 @@
 
 require 'opentelemetry/sdk/trace/samplers/decision'
 require 'opentelemetry/sdk/trace/samplers/result'
-require 'opentelemetry/sdk/trace/samplers/probability_sampler'
+require 'opentelemetry/sdk/trace/samplers/constant_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 {ALWAYS_PARENT}.
+      # reference implementation provides a {TraceIdRatioBased}, {ALWAYS_ON},
+      # {ALWAYS_OFF}, and {ParentBased}.
       #
-      # Custom samplers can be provided by SDK users. The required interface is
-      # a callable with the signature:
+      # Custom samplers can be provided by SDK users. The required interface is:
       #
-      #   (trace_id:, span_id:, parent_context:, links:, name:, kind:, attributes:) -> Result
+      #   should_sample?(trace_id:, parent_context:, links:, name:, kind:, attributes:) -> Result
+      #   description -> String
       #
       # Where:
       #
       # @param [String] trace_id The trace_id of the {Span} to be created.
-      # @param [String] span_id The span_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.
@@ -36,59 +37,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)
 
-        # rubocop:disable Lint/UnusedBlockArgument
+        # Returns a {Result} with {Decision::RECORD_AND_SAMPLE}.
+        ALWAYS_ON = ConstantSampler.new(result: RECORD_AND_SAMPLE, description: 'AlwaysOnSampler')
 
-        # Returns a {Result} with {Decision::RECORD_AND_SAMPLED}.
-        ALWAYS_ON = ->(trace_id:, span_id:, parent_context:, links:, name:, kind:, attributes:) { RECORD_AND_SAMPLED }
+        # Returns a {Result} with {Decision::DROP}.
+        ALWAYS_OFF = ConstantSampler.new(result: DROP, description: 'AlwaysOffSampler')
 
-        # Returns a {Result} with {Decision::NOT_RECORD}.
-        ALWAYS_OFF = ->(trace_id:, span_id:, parent_context:, links:, name:, kind:, attributes:) { NOT_RECORD }
-
-        # Returns a {Result} with {Decision::RECORD_AND_SAMPLED} if the parent
-        # context is sampled or {Decision::NOT_RECORD} otherwise, or if there
-        # is no parent context.
-        # rubocop:disable Style/Lambda
-        ALWAYS_PARENT = ->(trace_id:, span_id:, parent_context:, links:, name:, kind:, attributes:) do
-          if parent_context&.trace_flags&.sampled?
-            RECORD_AND_SAMPLED
-          else
-            NOT_RECORD
-          end
+        # Returns a new sampler. It delegates to samplers according to the following rules:
+        #
+        # | 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
-        # rubocop:enable Style/Lambda
-        # rubocop:enable Lint/UnusedBlockArgument
 
-        # 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/constant_sampler.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+# Copyright The OpenTelemetry Authors
+#
+# SPDX-License-Identifier: Apache-2.0
+
+module OpenTelemetry
+  module SDK
+    module Trace
+      module Samplers
+        # @api private
+        #
+        # Implements a sampler returning a constant result.
+        class ConstantSampler
+          attr_reader :description
+
+          def initialize(result:, description:)
+            @result = result
+            @description = description
+          end
+
+          # @api private
+          #
+          # See {Samplers}.
+          def should_sample?(trace_id:, parent_context:, links:, name:, kind:, attributes:)
+            # All arguments ignored for sampling decision.
+            @result
+          end
+        end
+      end
+    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,53 @@
+# 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:)
+            delegate = if parent_context.nil?
+                         @root
+                       elsif parent_context.remote?
+                         parent_context.trace_flags.sampled? ? @remote_parent_sampled : @remote_parent_not_sampled
+                       else
+                         parent_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