opentelemetry-api 0.16.0 → 0.17.0

data/lib/opentelemetry/context/propagation.rb

@@ -4,18 +4,48 @@
 #
 # SPDX-License-Identifier: Apache-2.0
 
-require 'opentelemetry/context/propagation/composite_propagator'
-require 'opentelemetry/context/propagation/noop_extractor'
-require 'opentelemetry/context/propagation/noop_injector'
-require 'opentelemetry/context/propagation/propagator'
+require 'opentelemetry/context/propagation/composite_text_map_propagator'
+require 'opentelemetry/context/propagation/noop_text_map_propagator'
+require 'opentelemetry/context/propagation/rack_env_getter'
 require 'opentelemetry/context/propagation/text_map_getter'
+require 'opentelemetry/context/propagation/text_map_propagator'
 require 'opentelemetry/context/propagation/text_map_setter'
-require 'opentelemetry/context/propagation/rack_env_getter'
 
 module OpenTelemetry
   class Context
     # The propagation module contains APIs and utilities to interact with context
     # and propagate across process boundaries.
+    #
+    # The API implicitly defines 3 interfaces: TextMapPropagator, TextMapInjector
+    # and TextMapExtractor. Concrete implementations of TextMapPropagator are
+    # provided. Custom text map propagators can leverage these implementations
+    # or simply implement the expected interface. The interfaces are described
+    # below.
+    #
+    # The TextMapPropagator interface:
+    #
+    #    inject(carrier, context:, setter:)
+    #    extract(carrier, context:, getter:) -> Context
+    #    fields -> Array<String>
+    #
+    # The TextMapInjector interface:
+    #
+    #    inject(carrier, context:, setter:)
+    #    fields -> Array<String>
+    #
+    # The TextMapExtractor interface:
+    #
+    #    extract(carrier, context:, getter:) -> Context
+    #
+    # The API provides 3 TextMapPropagator implementations:
+    # - A default NoopTextMapPropagator that implements +inject+ and +extract+
+    #   methods as no-ops. Its +fields+ method returns an empty list.
+    # - A TextMapPropagator that composes an Injector and an Extractor. Its
+    #   +fields+ method delegates to the provided Injector.
+    # - A CompositeTextMapPropagator that wraps either a list of text map
+    #   propagators or a list of Injectors and a list of Extractors. Its
+    #   +fields+ method returns the union of fields returned by the Injectors
+    #   it wraps.
     module Propagation
       extend self
 

data/lib/opentelemetry/context/propagation/composite_text_map_propagator.rb

@@ -0,0 +1,105 @@
+# frozen_string_literal: true
+
+# Copyright The OpenTelemetry Authors
+#
+# SPDX-License-Identifier: Apache-2.0
+
+module OpenTelemetry
+  class Context
+    module Propagation
+      # A composite text map propagator either composes a list of injectors and a
+      # list of extractors, or wraps a list of propagators, into a single interface
+      # exposing inject and extract methods. Injection and extraction will preserve
+      # the order of the injectors and extractors (or propagators) passed in during
+      # initialization.
+      class CompositeTextMapPropagator
+        class << self
+          private :new # rubocop:disable Style/AccessModifierDeclarations
+
+          # Returns a Propagator that extracts using the provided extractors
+          # and injectors.
+          #
+          # @param [Array<#inject, #fields>] injectors An array of text map injectors
+          # @param [Array<#extract>] extractors An array of text map extractors
+          def compose(injectors:, extractors:)
+            raise ArgumentError, 'injectors and extractors must both be non-nil arrays' unless injectors.is_a?(Array) && extractors.is_a?(Array)
+
+            new(injectors: injectors, extractors: extractors)
+          end
+
+          # Returns a Propagator that extracts using the provided propagators.
+          #
+          # @param [Array<#inject, #extract, #fields>] propagators An array of
+          #   text map propagators
+          def compose_propagators(propagators)
+            raise ArgumentError, 'propagators must be a non-nil array' unless propagators.is_a?(Array)
+            return NoopTextMapPropagator.new if propagators.empty?
+            return propagators.first if propagators.size == 1
+
+            new(propagators: propagators)
+          end
+        end
+
+        # @api private
+        def initialize(injectors: nil, extractors: nil, propagators: nil)
+          @injectors = injectors
+          @extractors = extractors
+          @propagators = propagators
+        end
+
+        # Runs injectors or propagators in order. If an injection fails
+        # a warning will be logged and remaining injectors will be executed.
+        #
+        # @param [Object] carrier A mutable carrier to inject context into.
+        # @param [optional Context] context Context to be injected into carrier. Defaults
+        #   to +Context.current+.
+        # @param [optional Setter] setter If the optional setter is provided, it
+        #   will be used to write context into the carrier, otherwise the default
+        #   setter will be used.
+        def inject(carrier, context: Context.current, setter: Context::Propagation.text_map_setter)
+          injectors = @injectors || @propagators
+          injectors.each do |injector|
+            injector.inject(carrier, context: context, setter: setter)
+          rescue StandardError => e
+            OpenTelemetry.logger.warn "Error in CompositePropagator#inject #{e.message}"
+          end
+          nil
+        end
+
+        # Runs extractors or propagators in order and returns a Context updated
+        # with the results of each extraction. If an extraction fails, a warning
+        # will be logged and remaining extractors will continue to be executed. Always
+        # returns a valid context.
+        #
+        # @param [Object] carrier The carrier to extract context from.
+        # @param [optional Context] context Context to be updated with the state
+        #   extracted from the carrier. Defaults to +Context.current+.
+        # @param [optional Getter] getter If the optional getter is provided, it
+        #   will be used to read the header from the carrier, otherwise the default
+        #   getter will be used.
+        #
+        # @return [Context] a new context updated with state extracted from the
+        #   carrier
+        def extract(carrier, context: Context.current, getter: Context::Propagation.text_map_getter)
+          extractors = @extractors || @propagators
+          extractors.inject(context) do |ctx, extractor|
+            extractor.extract(carrier, context: ctx, getter: getter)
+          rescue StandardError => e
+            OpenTelemetry.logger.warn "Error in CompositePropagator#extract #{e.message}"
+            ctx
+          end
+        end
+
+        # Returns the union of the propagation fields returned by the composed injectors
+        # or propagators. If your carrier is reused, you should delete the fields returned
+        # by this method before calling +inject+.
+        #
+        # @return [Array<String>] a list of fields that will be used by this propagator.
+        def fields
+          injectors = @injectors || @propagators
+          injectors.flat_map(&fields).uniq
+        end
+      end
+    end
+  end
+end

data/lib/opentelemetry/context/propagation/noop_text_map_propagator.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+# Copyright The OpenTelemetry Authors
+#
+# SPDX-License-Identifier: Apache-2.0
+
+module OpenTelemetry
+  class Context
+    module Propagation
+      # A no-op text map propagator implementation
+      class NoopTextMapPropagator
+        EMPTY_LIST = [].freeze
+        private_constant(:EMPTY_LIST)
+
+        # Injects the provided context into a carrier.
+        #
+        # @param [Object] carrier A mutable carrier to inject context into.
+        # @param [optional Context] context Context to be injected into carrier. Defaults
+        #   to +Context.current+.
+        # @param [optional Setter] setter If the optional setter is provided, it
+        #   will be used to write context into the carrier, otherwise the default
+        #   setter will be used.
+        def inject(carrier, context: Context.current, setter: Context::Propagation.text_map_setter); end
+
+        # Extracts and returns context from a carrier. Returns the provided
+        # context and logs a warning if an error if extraction fails.
+        #
+        # @param [Object] carrier The carrier to extract context from.
+        # @param [optional Context] context Context to be updated with the state
+        #   extracted from the carrier. Defaults to +Context.current+.
+        # @param [optional Getter] getter If the optional getter is provided, it
+        #   will be used to read the header from the carrier, otherwise the default
+        #   getter will be used.
+        #
+        # @return [Context] a new context updated with state extracted from the
+        #   carrier
+        def extract(carrier, context: Context.current, getter: Context::Propagation.text_map_getter)
+          context
+        end
+
+        # Returns the predefined propagation fields. If your carrier is reused, you
+        # should delete the fields returned by this method before calling +inject+.
+        #
+        # @return [Array<String>] a list of fields that will be used by this propagator.
+        def fields
+          EMPTY_LIST
+        end
+      end
+    end
+  end
+end

data/lib/opentelemetry/context/propagation/{propagator.rb → text_map_propagator.rb}

@@ -7,45 +7,44 @@
 module OpenTelemetry
   class Context
     module Propagation
-      # A propagator composes an extractor and injector into a single interface
-      # exposing inject and extract methods
-      class Propagator
+      # A text map propagator that composes an extractor and injector into a
+      # single interface exposing inject and extract methods.
+      class TextMapPropagator
         # Returns a Propagator that delegates inject and extract to the provided
         # injector and extractor
         #
         # @param [#inject] injector
         # @param [#extract] extractor
         def initialize(injector, extractor)
+          raise ArgumentError, 'injector and extractor must both be non-nil' if injector.nil? || extractor.nil?
+
           @injector = injector
           @extractor = extractor
         end
 
-        # Returns a carrier with the provided context injected according the
-        # underlying injector. Returns the carrier and logs a warning if
-        # injection fails.
+        # Injects the provided context into a carrier using the underlying
+        # injector. Logs a warning if injection fails.
         #
-        # @param [Object] carrier A carrier to inject context into
-        #   context into
+        # @param [Object] carrier A mutable carrier to inject context into.
         # @param [optional Context] context Context to be injected into carrier. Defaults
-        #   to +Context.current+
+        #   to +Context.current+.
         # @param [optional Setter] setter If the optional setter is provided, it
         #   will be used to write context into the carrier, otherwise the default
         #   setter will be used.
-        #
-        # @return [Object] carrier
         def inject(carrier, context: Context.current, setter: Context::Propagation.text_map_setter)
           @injector.inject(carrier, context, setter)
-        rescue => e # rubocop:disable Style/RescueStandardError
+          nil
+        rescue StandardError => e
           OpenTelemetry.logger.warn "Error in Propagator#inject #{e.message}"
-          carrier
+          nil
         end
 
         # Extracts and returns context from a carrier. Returns the provided
         # context and logs a warning if an error if extraction fails.
         #
-        # @param [Object] carrier The carrier to extract context from
+        # @param [Object] carrier The carrier to extract context from.
         # @param [optional Context] context Context to be updated with the state
-        #   extracted from the carrier. Defaults to +Context.current+
+        #   extracted from the carrier. Defaults to +Context.current+.
         # @param [optional Getter] getter If the optional getter is provided, it
         #   will be used to read the header from the carrier, otherwise the default
         #   getter will be used.
@@ -54,10 +53,18 @@ module OpenTelemetry
         #   carrier
         def extract(carrier, context: Context.current, getter: Context::Propagation.text_map_getter)
           @extractor.extract(carrier, context, getter)
-        rescue => e # rubocop:disable Style/RescueStandardError
+        rescue StandardError => e
           OpenTelemetry.logger.warn "Error in Propagator#extract #{e.message}"
           context
         end
+
+        # Returns the predefined propagation fields. If your carrier is reused, you
+        # should delete the fields returned by this method before calling +inject+.
+        #
+        # @return [Array<String>] a list of fields that will be used by this propagator.
+        def fields
+          @injector.fields
+        end
       end
     end
   end

data/lib/opentelemetry/internal.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+# Copyright The OpenTelemetry Authors
+#
+# SPDX-License-Identifier: Apache-2.0
+
+require 'opentelemetry/internal/proxy_tracer'
+require 'opentelemetry/internal/proxy_tracer_provider'
+
+module OpenTelemetry
+  # @api private
+  #
+  # The Internal module provides API internal functionality that is not a part of the
+  # public API.
+  module Internal
+  end
+end

data/lib/opentelemetry/internal/proxy_tracer.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+# Copyright The OpenTelemetry Authors
+#
+# SPDX-License-Identifier: Apache-2.0
+
+module OpenTelemetry
+  module Internal
+    # @api private
+    #
+    # {ProxyTracer} is an implementation of {OpenTelemetry::Trace::Tracer}. It is returned from
+    # the ProxyTracerProvider until a delegate tracer provider is installed. After the delegate
+    # tracer provider is installed, the ProxyTracer will delegate to the corresponding "real"
+    # tracer.
+    class ProxyTracer < Trace::Tracer
+      attr_writer :delegate
+
+      # Returns a new {ProxyTracer} instance.
+      #
+      # @return [ProxyTracer]
+      def initialize
+        @delegate = nil
+      end
+
+      def start_root_span(name, attributes: nil, links: nil, start_timestamp: nil, kind: nil)
+        return @delegate.start_root_span(name, attributes: attributes, links: links, start_timestamp: start_timestamp, kind: kind) unless @delegate.nil?
+
+        super
+      end
+
+      def start_span(name, with_parent: nil, attributes: nil, links: nil, start_timestamp: nil, kind: nil)
+        return @delegate.start_span(name, with_parent: with_parent, attributes: attributes, links: links, start_timestamp: start_timestamp, kind: kind) unless @delegate.nil?
+
+        super
+      end
+    end
+  end
+end

data/lib/opentelemetry/internal/proxy_tracer_provider.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+# Copyright The OpenTelemetry Authors
+#
+# SPDX-License-Identifier: Apache-2.0
+
+module OpenTelemetry
+  module Internal
+    # @api private
+    #
+    # {ProxyTracerProvider} is an implementation of {OpenTelemetry::Trace::TracerProvider}.
+    # It is the default global tracer provider returned by OpenTelemetry.tracer_provider.
+    # It delegates to a "real" TracerProvider after the global tracer provider is registered.
+    # It returns {ProxyTracer} instances until the delegate is installed.
+    class ProxyTracerProvider < Trace::TracerProvider
+      Key = Struct.new(:name, :version)
+      private_constant(:Key)
+
+      # Returns a new {ProxyTracerProvider} instance.
+      #
+      # @return [ProxyTracerProvider]
+      def initialize
+        @mutex = Mutex.new
+        @registry = {}
+        @delegate = nil
+      end
+
+      # Set the delegate tracer provider. If this is called more than once, a warning will
+      # be logged and superfluous calls will be ignored.
+      #
+      # @param [TracerProvider] provider The tracer provider to delegate to
+      def delegate=(provider)
+        unless @delegate.nil?
+          OpenTelemetry.logger.warn 'Attempt to reset delegate in ProxyTracerProvider ignored.'
+          return
+        end
+
+        @mutex.synchronize do
+          @delegate = provider
+          @registry.each { |key, tracer| tracer.delegate = provider.tracer(key.name, key.version) }
+        end
+      end
+
+      # Returns a {Tracer} instance.
+      #
+      # @param [optional String] name Instrumentation package name
+      # @param [optional String] version Instrumentation package version
+      #
+      # @return [Tracer]
+      def tracer(name = nil, version = nil)
+        @mutex.synchronize do
+          return @delegate.tracer(name, version) unless @delegate.nil?
+
+          @registry[Key.new(name, version)] ||= ProxyTracer.new
+        end
+      end
+    end
+  end
+end

data/lib/opentelemetry/trace/propagation/trace_context.rb

@@ -5,8 +5,7 @@
 # SPDX-License-Identifier: Apache-2.0
 
 require 'opentelemetry/trace/propagation/trace_context/trace_parent'
-require 'opentelemetry/trace/propagation/trace_context/text_map_extractor'
-require 'opentelemetry/trace/propagation/trace_context/text_map_injector'
+require 'opentelemetry/trace/propagation/trace_context/text_map_propagator'
 
 module OpenTelemetry
   module Trace
@@ -15,24 +14,14 @@ module OpenTelemetry
       # for context propagation in the W3C Trace Context format.
       module TraceContext
         extend self
-        TRACEPARENT_KEY = 'traceparent'
-        TRACESTATE_KEY = 'tracestate'
-        TEXT_MAP_EXTRACTOR = TextMapExtractor.new
-        TEXT_MAP_INJECTOR = TextMapInjector.new
+        TEXT_MAP_PROPAGATOR = TextMapPropagator.new
 
-        private_constant :TRACEPARENT_KEY, :TRACESTATE_KEY,
-                         :TEXT_MAP_INJECTOR, :TEXT_MAP_EXTRACTOR
+        private_constant :TEXT_MAP_PROPAGATOR
 
-        # Returns an extractor that extracts context using the W3C Trace Context
-        # format
-        def text_map_extractor
-          TEXT_MAP_EXTRACTOR
-        end
-
-        # Returns an injector that injects context using the W3C Trace Context
-        # format
-        def text_map_injector
-          TEXT_MAP_INJECTOR
+        # Returns a text map propagator that propagates context using the
+        # W3C Trace Context format.
+        def text_map_propagator
+          TEXT_MAP_PROPAGATOR
         end
       end
     end