opentelemetry-sdk 0.2.0 → 0.6.0

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

@@ -23,7 +23,7 @@ module OpenTelemetry
           end
 
           def export(spans)
-            return ResultCodes::FAILED_NOT_RETRYABLE if @stopped
+            return ResultCodes::FAILURE if @stopped
 
             Array(spans).each { |s| pp s }
 

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

@@ -14,13 +14,13 @@ module OpenTelemetry
         #
         # class MyClassTest
         #   def setup
-        #     @tracer_factory = TracerFactory.new
+        #     @tracer_provider = TracerProvider.new
         #     @exporter = InMemorySpanExporter.new
-        #     @tracer_factory.add_span_processor(SimpleSampledSpansProcessor.new(@exporter))
+        #     @tracer_provider.add_span_processor(SimpleSampledSpansProcessor.new(@exporter))
         #   end
         #
         #   def test_finished_spans
-        #     @tracer_factory.tracer.in_span("span") {}
+        #     @tracer_provider.tracer.in_span("span") {}
         #
         #     spans = @exporter.finished_spans
         #     spans.wont_be_nil
@@ -61,18 +61,18 @@ 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
             SUCCESS
           end
 
-          # Called when {TracerFactory#shutdown} is called, if this exporter is
-          # registered to a {TracerFactory} object.
+          # Called when {TracerProvider#shutdown} is called, if this exporter is
+          # registered to a {TracerProvider} object.
           def shutdown
             @mutex.synchronize do
               @finished_spans.clear

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

@@ -26,17 +26,15 @@ module OpenTelemetry
           # @return [Integer] the result of the export.
           def export(spans)
             @span_exporters.inject(SUCCESS) do |result_code, span_exporter|
-              begin
-                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
-              end
+              merge_result_code(result_code, span_exporter.export(spans))
+            rescue => e # rubocop:disable Style/RescueStandardError
+              OpenTelemetry.logger.warn("exception raised by export - #{e}")
+              FAILURE
             end
           end
 
-          # Called when {TracerFactory#shutdown} is called, if this exporter is
-          # registered to a {TracerFactory} object.
+          # Called when {TracerProvider#shutdown} is called, if this exporter is
+          # registered to a {TracerProvider} object.
           def shutdown
             @span_exporters.each(&:shutdown)
           end
@@ -48,13 +46,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

@@ -12,7 +12,7 @@ module OpenTelemetry
         # duck type. SpanExporter allows different tracing services to export
         # recorded data for sampled spans in their own format.
         #
-        # To export data an exporter MUST be registered to the {TracerFactory} using
+        # To export data an exporter MUST be registered to the {TracerProvider} using
         # a {SimpleSpanProcessor} or a {BatchSpanProcessor}.
         class NoopSpanExporter
           def initialize
@@ -27,11 +27,11 @@ module OpenTelemetry
           def export(spans)
             return SUCCESS unless @stopped
 
-            FAILED_NOT_RETRYABLE
+            FAILURE
           end
 
-          # Called when {TracerFactory#shutdown} is called, if this exporter is
-          # registered to a {TracerFactory} object.
+          # Called when {TracerProvider#shutdown} is called, if this exporter is
+          # registered to a {TracerProvider} object.
           def shutdown
             @stopped = true
           end

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

@@ -52,7 +52,16 @@ module OpenTelemetry
             OpenTelemetry.logger.error("unexpected error in span.on_finish - #{e}")
           end
 
-          # Called when {TracerFactory#shutdown} is called.
+          # Export all ended spans to the configured `Exporter` that have not yet
+          # been exported.
+          #
+          # This method should only be called in cases where it is absolutely
+          # 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
+
+          # Called when {TracerProvider#shutdown} is called.
           def shutdown
             @span_exporter&.shutdown
           end

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

@@ -41,7 +41,18 @@ module OpenTelemetry
           @span_processors.each { |processor| processor.on_finish(span) }
         end
 
-        # Called when {TracerFactory#shutdown} is called.
+        # Export all ended spans to the configured `Exporter` that have not yet
+        # been exported.
+        #
+        # This method should only be called in cases where it is absolutely
+        # 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)
+        end
+
+        # Called when {TracerProvider#shutdown} is called.
         def shutdown
           @span_processors.each(&:shutdown)
         end

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

@@ -33,7 +33,16 @@ module OpenTelemetry
         # @param [Span] span the {Span} that just ended.
         def on_finish(span); end
 
-        # Called when {TracerFactory#shutdown} is called.
+        # Export all ended spans to the configured `Exporter` that have not yet
+        # been exported.
+        #
+        # This method should only be called in cases where it is absolutely
+        # 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
+
+        # Called when {TracerProvider#shutdown} is called.
         def shutdown; end
       end
     end

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

@@ -6,29 +6,28 @@
 
 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:, hint:, 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.
-      # @param [Symbol] hint A {OpenTelemetry::Trace::SamplingHint} about
-      #   whether the {Span} should be sampled and/or record events.
       # @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.
@@ -42,63 +41,55 @@ module OpenTelemetry
         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
 
-        private_constant(:RECORD_AND_SAMPLED, :NOT_RECORD, :RECORD, :SAMPLING_HINTS, :APPLY_PROBABILITY_TO_SYMBOLS)
+        private_constant(:RECORD_AND_SAMPLED, :NOT_RECORD, :RECORD, :SAMPLING_HINTS)
 
-        # rubocop:disable Lint/UnusedBlockArgument
+        # Returns a {Result} with {Decision::RECORD_AND_SAMPLED}.
+        ALWAYS_ON = ConstantSampler.new(result: RECORD_AND_SAMPLED, description: 'AlwaysOnSampler')
 
-        # Ignores all values in hint and returns a {Result} with
-        # {Decision::RECORD_AND_SAMPLED}.
-        ALWAYS_ON = ->(trace_id:, span_id:, parent_context:, hint:, links:, name:, kind:, attributes:) { RECORD_AND_SAMPLED }
+        # Returns a {Result} with {Decision::NOT_RECORD}.
+        ALWAYS_OFF = ConstantSampler.new(result: NOT_RECORD, description: 'AlwaysOffSampler')
 
-        # Ignores all values in hint and returns a {Result} with
-        # {Decision::NOT_RECORD}.
-        ALWAYS_OFF = ->(trace_id:, span_id:, parent_context:, hint:, links:, name:, kind:, attributes:) { NOT_RECORD }
-
-        # Ignores all values in hint and 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:, hint:, 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 Enumerable<Symbol>] ignore_hints Sampling hints to
-        #   ignore. Defaults to ignore {OpenTelemetry::Trace::SamplingHint::RECORD}.
-        # @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 ignore_hints contains invalid hints
-        # @raise [ArgumentError] if apply_probability_to is not one of the allowed symbols
-        def self.probability(probability,
-                             ignore_hints: [OpenTelemetry::Trace::SamplingHint::RECORD],
-                             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, 'ignore_hints' unless (ignore_hints.to_a - SAMPLING_HINTS).empty?
-          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_hints: ignore_hints.to_a,
-                                 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 = OpenTelemetry::Trace::SamplingHint::NOT_RECORD
+          NOT_RECORD = :__not_record__
 
           # Decision to record events and not sample.
-          RECORD = OpenTelemetry::Trace::SamplingHint::RECORD
+          RECORD = :__record__
 
           # Decision to record events and sample.
-          RECORD_AND_SAMPLED = OpenTelemetry::Trace::SamplingHint::RECORD_AND_SAMPLED
+          RECORD_AND_SAMPLED = :__record_and_sampled__
         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

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

@@ -19,7 +19,7 @@ module OpenTelemetry
 
           # Returns a frozen hash of attributes to be attached span.
           #
-          # @return [Hash<String, Object>]
+          # @return [Hash{String => String, Numeric, Boolean, Array<String, Numeric, Boolean>}]
           attr_reader :attributes
 
           # Returns a new sampling result with the specified decision and
@@ -27,8 +27,9 @@ module OpenTelemetry
           #
           # @param [Symbol] decision Whether or not a span should be sampled
           #   and/or record events.
-          # @param [optional Hash<String, Object>] attributes A frozen or freezable hash
-          #   containing attributes to be attached to the span.
+          # @param [optional Hash{String => String, Numeric, Boolean, Array<String, Numeric, Boolean>}]
+          #   attributes A frozen or freezable hash containing attributes to be
+          #   attached to the span.
           def initialize(decision:, attributes: nil)
             @decision = decision
             @attributes = attributes.freeze || EMPTY_HASH

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_SAMPLED
+            else
+              NOT_RECORD
+            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