opentelemetry-api 0.14.0 → 1.0.0.rc2

data/lib/opentelemetry/context.rb

@@ -10,8 +10,11 @@ require 'opentelemetry/context/propagation'
 module OpenTelemetry
   # Manages context on a per-fiber basis
   class Context
-    KEY = :__opentelemetry_context__
     EMPTY_ENTRIES = {}.freeze
+    STACK_KEY = :__opentelemetry_context_storage__
+    private_constant :EMPTY_ENTRIES, :STACK_KEY
+
+    DetachError = Class.new(OpenTelemetry::Error)
 
     class << self
       # Returns a key used to index a value in a Context
@@ -26,14 +29,36 @@ module OpenTelemetry
       #
       # @return [Context]
       def current
-        Thread.current[KEY] ||= ROOT
+        stack.last || ROOT
       end
 
-      # Sets the current context
+      # Associates a Context with the caller's current Fiber. Every call to
+      # this operation should be paired with a corresponding call to detach.
       #
-      # @param [Context] ctx The context to be made active
-      def current=(ctx)
-        Thread.current[KEY] = ctx
+      # Returns a token to be used with the matching call to detach
+      #
+      # @param [Context] context The new context
+      # @return [Object] A token to be used when detaching
+      def attach(context)
+        s = stack
+        s.push(context)
+        s.size
+      end
+
+      # Restores the previous Context associated with the current Fiber.
+      # The supplied token is used to check if the call to detach is balanced
+      # with a corresponding attach call. A warning is logged if the
+      # calls are unbalanced.
+      #
+      # @param [Object] token The token provided by the matching call to attach
+      # @return [Boolean] True if the calls matched, false otherwise
+      def detach(token)
+        s = stack
+        calls_matched = (token == s.size)
+        OpenTelemetry.handle_error(exception: DetachError.new('calls to detach should match corresponding calls to attach.')) unless calls_matched
+
+        s.pop
+        calls_matched
       end
 
       # Executes a block with ctx as the current context. It restores
@@ -42,10 +67,10 @@ module OpenTelemetry
       # @param [Context] ctx The context to be made active
       # @yield [context] Yields context to the block
       def with_current(ctx)
-        prev = ctx.attach
+        token = attach(ctx)
         yield ctx
       ensure
-        ctx.detach(prev)
+        detach(token)
       end
 
       # Execute a block in a new context with key set to value. Restores the
@@ -58,10 +83,10 @@ module OpenTelemetry
       #   the block
       def with_value(key, value)
         ctx = current.set_value(key, value)
-        prev = ctx.attach
+        token = attach(ctx)
         yield ctx, value
       ensure
-        ctx.detach(prev)
+        detach(token)
       end
 
       # Execute a block in a new context where its values are merged with the
@@ -75,10 +100,10 @@ module OpenTelemetry
       #   to the block
       def with_values(values)
         ctx = current.set_values(values)
-        prev = ctx.attach
+        token = attach(ctx)
         yield ctx, values
       ensure
-        ctx.detach(prev)
+        detach(token)
       end
 
       # Returns the value associated with key in the current context
@@ -89,16 +114,21 @@ module OpenTelemetry
       end
 
       def clear
-        self.current = ROOT
+        stack.clear
       end
 
       def empty
-        new(nil, EMPTY_ENTRIES)
+        new(EMPTY_ENTRIES)
+      end
+
+      private
+
+      def stack
+        Thread.current[STACK_KEY] ||= []
       end
     end
 
-    def initialize(parent, entries)
-      @parent = parent
+    def initialize(entries)
       @entries = entries.freeze
     end
 
@@ -120,7 +150,7 @@ module OpenTelemetry
     def set_value(key, value)
       new_entries = @entries.dup
       new_entries[key] = value
-      Context.new(self, new_entries)
+      Context.new(new_entries)
     end
 
     # Returns a new Context with the current context's entries merged with the
@@ -131,22 +161,7 @@ module OpenTelemetry
     # @param [Object] value Object to be stored under key
     # @return [Context]
     def set_values(values) # rubocop:disable Naming/AccessorMethodName:
-      Context.new(self, @entries.merge(values))
-    end
-
-    # @api private
-    def attach
-      prev = self.class.current
-      self.class.current = self
-      prev
-    end
-
-    # @api private
-    def detach(ctx_to_attach = nil)
-      OpenTelemetry.logger.warn 'Calls to detach should match corresponding calls to attach' if self.class.current != self
-
-      ctx_to_attach ||= @parent || ROOT
-      ctx_to_attach.attach
+      Context.new(@entries.merge(values))
     end
 
     ROOT = empty.freeze

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

@@ -16,7 +16,7 @@ module OpenTelemetry
         # Converts key into a rack-normalized key and reads it from the carrier.
         # Useful for extract operations.
         def get(carrier, key)
-          carrier[to_rack_key(key)]
+          carrier[to_rack_key(key)] || carrier[key]
         end
 
         # Reads all keys from a carrier and converts them from the rack-normalized
@@ -32,6 +32,7 @@ module OpenTelemetry
           ret = 'HTTP_' + key
           ret.tr!('-', '_')
           ret.upcase!
+          ret
         end
 
         def from_rack_key(key)
@@ -39,6 +40,7 @@ module OpenTelemetry
           ret = key[start..-1]
           ret.tr!('_', '-')
           ret.downcase!
+          ret
         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