opentelemetry-sdk 0.5.1

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

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+# Copyright 2019 OpenTelemetry Authors
+#
+# SPDX-License-Identifier: Apache-2.0
+
+module OpenTelemetry
+  module SDK
+    module Trace
+      module Export
+        # A noop exporter that demonstrates and documents the SpanExporter
+        # 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 {TracerProvider} using
+        # a {SimpleSpanProcessor} or a {BatchSpanProcessor}.
+        class NoopSpanExporter
+          def initialize
+            @stopped = false
+          end
+
+          # Called to export sampled {Span}s.
+          #
+          # @param [Enumerable<Span>] spans the list of sampled {Span}s to be
+          #   exported.
+          # @return [Integer] the result of the export.
+          def export(spans)
+            return SUCCESS unless @stopped
+
+            FAILURE
+          end
+
+          # Called when {TracerProvider#shutdown} is called, if this exporter is
+          # registered to a {TracerProvider} object.
+          def shutdown
+            @stopped = true
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+# Copyright 2019 OpenTelemetry Authors
+#
+# SPDX-License-Identifier: Apache-2.0
+
+module OpenTelemetry
+  module SDK
+    module Trace
+      module Export
+        # An implementation of the duck type SpanProcessor that converts the
+        # {Span} to {io.opentelemetry.proto.trace.v1.Span} and passes it to the
+        # configured exporter.
+        #
+        # Only spans that are recorded are converted, {OpenTelemetry::Trace::Span#is_recording?} must
+        # return true.
+        class SimpleSpanProcessor
+          # Returns a new {SimpleSpanProcessor} that converts spans to
+          # proto and forwards them to the given span_exporter.
+          #
+          # @param span_exporter the (duck type) SpanExporter to where the
+          #   recorded Spans are pushed.
+          # @return [SimpleSpanProcessor]
+          # @raise ArgumentError if the span_exporter is nil.
+          def initialize(span_exporter)
+            @span_exporter = span_exporter
+          end
+
+          # Called when a {Span} is started, if the {Span#recording?}
+          # returns true.
+          #
+          # This method is called synchronously on the execution thread, should
+          # not throw or block the execution thread.
+          #
+          # @param [Span] span the {Span} that just started.
+          def on_start(span)
+            # Do nothing.
+          end
+
+          # Called when a {Span} is ended, if the {Span#recording?}
+          # returns true.
+          #
+          # This method is called synchronously on the execution thread, should
+          # not throw or block the execution thread.
+          #
+          # @param [Span] span the {Span} that just ended.
+          def on_finish(span)
+            return unless span.context.trace_flags.sampled?
+
+            @span_exporter&.export([span.to_span_data])
+          rescue => e # rubocop:disable Style/RescueStandardError
+            OpenTelemetry.logger.error("unexpected error in span.on_finish - #{e}")
+          end
+
+          # 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
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+# Copyright 2019 OpenTelemetry Authors
+#
+# SPDX-License-Identifier: Apache-2.0
+
+module OpenTelemetry
+  module SDK
+    module Trace
+      # Implementation of the SpanProcessor duck type that simply forwards all
+      # received events to a list of SpanProcessors.
+      class MultiSpanProcessor
+        # Creates a new {MultiSpanProcessor}.
+        #
+        # @param [Enumerable<SpanProcessor>] span_processors a collection of
+        #   SpanProcessors.
+        # @return [MultiSpanProcessor]
+        def initialize(span_processors)
+          @span_processors = span_processors.to_a.freeze
+        end
+
+        # Called when a {Span} is started, if the {Span#recording?}
+        # returns true.
+        #
+        # This method is called synchronously on the execution thread, should
+        # 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) }
+        end
+
+        # Called when a {Span} is ended, if the {Span#recording?}
+        # returns true.
+        #
+        # This method is called synchronously on the execution thread, should
+        # not throw or block the execution thread.
+        #
+        # @param [Span] span the {Span} that just ended.
+        def on_finish(span)
+          @span_processors.each { |processor| processor.on_finish(span) }
+        end
+
+        # 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
+      end
+    end
+  end
+end

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

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+# Copyright 2019 OpenTelemetry Authors
+#
+# SPDX-License-Identifier: Apache-2.0
+
+require 'singleton'
+
+module OpenTelemetry
+  module SDK
+    module Trace
+      # NoopSpanProcessor is a singleton implementation of the duck type
+      # SpanProcessor that provides synchronous no-op hooks for when a
+      # {Span} is started or when a {Span} is ended.
+      class NoopSpanProcessor
+        include Singleton
+
+        # Called when a {Span} is started, if the {Span#recording?}
+        # returns true.
+        #
+        # This method is called synchronously on the execution thread, should
+        # not throw or block the execution thread.
+        #
+        # @param [Span] span the {Span} that just started.
+        def on_start(span); end
+
+        # Called when a {Span} is ended, if the {Span#recording?}
+        # returns true.
+        #
+        # This method is called synchronously on the execution thread, should
+        # not throw or block the execution thread.
+        #
+        # @param [Span] span the {Span} that just ended.
+        def on_finish(span); end
+
+        # 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
+  end
+end

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

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+# Copyright 2019 OpenTelemetry Authors
+#
+# SPDX-License-Identifier: Apache-2.0
+
+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'
+
+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}.
+      #
+      # Custom samplers can be provided by SDK users. The required interface is:
+      #
+      #   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 [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 [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.
+      # @param [Symbol] kind The {OpenTelemetry::Trace::SpanKind} of the {Span}
+      #   to be created. Can be nil.
+      # @param [Hash<String, Object>] attributes Attributes to be attached
+      #   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
+
+        private_constant(:RECORD_AND_SAMPLED, :NOT_RECORD, :RECORD, :SAMPLING_HINTS, :APPLY_PROBABILITY_TO_SYMBOLS)
+
+        # Returns a {Result} with {Decision::RECORD_AND_SAMPLED}.
+        ALWAYS_ON = ConstantSampler.new(result: RECORD_AND_SAMPLED, description: 'AlwaysOnSampler')
+
+        # Returns a {Result} with {Decision::NOT_RECORD}.
+        ALWAYS_OFF = ConstantSampler.new(result: NOT_RECORD, description: 'AlwaysOffSampler')
+
+        # Returns a new sampler. It either respects the parent span's sampling
+        # decision or delegates to delegate_sampler for root spans.
+        #
+        # @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)
+        end
+
+        # Returns a new sampler. The probability of sampling a trace is equal
+        # to that of the specified probability.
+        #
+        # @param [Numeric] probability The desired probability of sampling.
+        #   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)
+
+          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)
+        end
+      end
+    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

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+# Copyright 2019 OpenTelemetry Authors
+#
+# SPDX-License-Identifier: Apache-2.0
+
+module OpenTelemetry
+  module SDK
+    module Trace
+      module Samplers
+        # The Decision module contains a set of constants to be used in the
+        # decision part of a sampling {Result}.
+        module Decision
+          # Decision to not record events and not sample.
+          NOT_RECORD = :__not_record__
+
+          # Decision to record events and not sample.
+          RECORD = :__record__
+
+          # Decision to record events and sample.
+          RECORD_AND_SAMPLED = :__record_and_sampled__
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,43 @@
+# 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. It either respects the parent span's sampling
+        # decision or delegates to delegate_sampler for root spans.
+        class ParentOrElse
+          def initialize(delegate_sampler)
+            @delegate_sampler = delegate_sampler
+          end
+
+          # @api private
+          #
+          # See {Samplers}.
+          def description
+            "ParentOrElse{#{@delegate_sampler.description}}"
+          end
+
+          # @api private
+          #
+          # See {Samplers}.
+          def should_sample?(trace_id:, parent_context:, links:, name:, kind:, attributes:)
+            if parent_context.nil?
+              @delegate_sampler.should_sample?(trace_id: trace_id, parent_context: parent_context, links: links, name: name, kind: kind, attributes: attributes)
+            elsif parent_context.trace_flags.sampled?
+              RECORD_AND_SAMPLED
+            else
+              NOT_RECORD
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,64 @@
+# 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 ProbabilitySampler
+          attr_reader :description
+
+          def initialize(probability, ignore_parent:, apply_to_remote_parent:, apply_to_all_spans:)
+            @probability = probability
+            @id_upper_bound = (probability * (2**64 - 1)).ceil
+            @use_parent_sampled_flag = !ignore_parent
+            @apply_to_remote_parent = apply_to_remote_parent
+            @apply_to_all_spans = apply_to_all_spans
+            @description = format('ProbabilitySampler{%.6f}', probability)
+          end
+
+          # @api private
+          #
+          # See {Samplers}.
+          def should_sample?(trace_id:, parent_context:, links:, name:, kind:, attributes:)
+            # Ignored for sampling decision: links, name, kind, attributes.
+
+            if sample?(trace_id, parent_context)
+              RECORD_AND_SAMPLED
+            else
+              NOT_RECORD
+            end
+          end
+
+          private
+
+          def sample?(trace_id, parent_context)
+            if parent_context.nil?
+              sample_trace_id?(trace_id)
+            else
+              parent_sampled?(parent_context) || sample_trace_id_for_child?(parent_context, trace_id)
+            end
+          end
+
+          def parent_sampled?(parent_context)
+            @use_parent_sampled_flag && parent_context.trace_flags.sampled?
+          end
+
+          def sample_trace_id_for_child?(parent_context, trace_id)
+            (@apply_to_all_spans || (@apply_to_remote_parent && parent_context.remote?)) && sample_trace_id?(trace_id)
+          end
+
+          def sample_trace_id?(trace_id)
+            @probability == 1.0 || trace_id[8, 8].unpack1('Q>') < @id_upper_bound
+          end
+        end
+      end
+    end
+  end
+end