opentelemetry-api 0.13.0 → 1.0.0.rc1

data/lib/opentelemetry/baggage/propagation/text_map_propagator.rb

@@ -0,0 +1,109 @@
+# frozen_string_literal: true
+
+# Copyright The OpenTelemetry Authors
+#
+# SPDX-License-Identifier: Apache-2.0
+
+require 'cgi'
+
+module OpenTelemetry
+  module Baggage
+    module Propagation
+      # Propagates baggage using the W3C Baggage format
+      class TextMapPropagator
+        # Maximums according to W3C Baggage spec
+        MAX_ENTRIES = 180
+        MAX_ENTRY_LENGTH = 4096
+        MAX_TOTAL_LENGTH = 8192
+
+        BAGGAGE_KEY = 'baggage'
+        FIELDS = [BAGGAGE_KEY].freeze
+
+        private_constant :BAGGAGE_KEY, :FIELDS, :MAX_ENTRIES, :MAX_ENTRY_LENGTH, :MAX_TOTAL_LENGTH
+
+        # Inject in-process baggage into the supplied carrier.
+        #
+        # @param [Carrier] carrier The mutable carrier to inject baggage into
+        # @param [Context] context The context to read baggage from
+        # @param [optional Setter] setter If the optional setter is provided, it
+        #   will be used to write context into the carrier, otherwise the default
+        #   text map setter will be used.
+        def inject(carrier, context: Context.current, setter: Context::Propagation.text_map_setter)
+          baggage = OpenTelemetry.baggage.raw_entries(context: context)
+
+          return if baggage.nil? || baggage.empty?
+
+          encoded_baggage = encode(baggage)
+          setter.set(carrier, BAGGAGE_KEY, encoded_baggage) unless encoded_baggage&.empty?
+          nil
+        end
+
+        # Extract remote baggage from the supplied carrier.
+        # If extraction fails, the original context will be returned
+        #
+        # @param [Carrier] carrier The carrier to get the header from
+        # @param [optional Context] context Context to be updated with the baggage
+        #   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
+        #   text map getter will be used.
+        #
+        # @return [Context] context updated with extracted baggage, or the original context
+        #   if extraction fails
+        def extract(carrier, context: Context.current, getter: Context::Propagation.text_map_getter)
+          header = getter.get(carrier, BAGGAGE_KEY)
+
+          entries = header.gsub(/\s/, '').split(',')
+
+          OpenTelemetry.baggage.build(context: context) do |builder|
+            entries.each do |entry|
+              # Note metadata is currently unused in OpenTelemetry, but is part
+              # the W3C spec where it's referred to as properties. We preserve
+              # the properties (as-is) so that they can be propagated elsewhere.
+              kv, meta = entry.split(';', 2)
+              k, v = kv.split('=').map!(&CGI.method(:unescape))
+              builder.set_value(k, v, metadata: meta)
+            end
+          end
+        rescue StandardError => e
+          OpenTelemetry.logger.debug "Error extracting W3C baggage: #{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
+          FIELDS
+        end
+
+        private
+
+        def encode(baggage)
+          result = +''
+          encoded_count = 0
+          baggage.each_pair do |key, entry|
+            break unless encoded_count < MAX_ENTRIES
+
+            encoded_entry = encode_value(key, entry)
+            next unless encoded_entry.size <= MAX_ENTRY_LENGTH &&
+                        encoded_entry.size + result.size <= MAX_TOTAL_LENGTH
+
+            result << encoded_entry << ','
+            encoded_count += 1
+          end
+          result.chop!
+        end
+
+        def encode_value(key, entry)
+          result = +"#{CGI.escape(key.to_s)}=#{CGI.escape(entry.value.to_s)}"
+          # We preserve metadata recieved on extract and assume it's already formatted
+          # for transport. It's sent as-is without further processing.
+          result << ";#{entry.metadata}" if entry.metadata
+          result
+        end
+      end
+    end
+  end
+end

data/lib/opentelemetry/context/propagation.rb

@@ -4,19 +4,74 @@
 #
 # SPDX-License-Identifier: Apache-2.0
 
-require 'opentelemetry/context/propagation/composite_propagator'
-require 'opentelemetry/context/propagation/default_getter'
-require 'opentelemetry/context/propagation/default_setter'
-require 'opentelemetry/context/propagation/noop_extractor'
-require 'opentelemetry/context/propagation/noop_injector'
-require 'opentelemetry/context/propagation/propagation'
-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'
 
 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
+
+      TEXT_MAP_GETTER = TextMapGetter.new
+      TEXT_MAP_SETTER = TextMapSetter.new
+      RACK_ENV_GETTER = RackEnvGetter.new
+
+      private_constant :TEXT_MAP_GETTER, :TEXT_MAP_SETTER, :RACK_ENV_GETTER
+
+      # Returns a {TextMapGetter} instance suitable for reading values from a
+      # hash-like carrier
+      def text_map_getter
+        TEXT_MAP_GETTER
+      end
+
+      # Returns a {TextMapSetter} instance suitable for writing values into a
+      # hash-like carrier
+      def text_map_setter
+        TEXT_MAP_SETTER
+      end
+
+      # Returns a {RackEnvGetter} instance suitable for reading values from a
+      # Rack environment.
+      def rack_env_getter
+        RACK_ENV_GETTER
+      end
     end
   end
 end

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

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+# Copyright The OpenTelemetry Authors
+#
+# SPDX-License-Identifier: Apache-2.0
+
+module OpenTelemetry
+  class Context
+    module Propagation
+      # The RackEnvGetter class provides a common methods for reading
+      # keys from a rack environment. It abstracts away the rack-normalization
+      # process so that keys can be looked up without having to transform them
+      # first. With this class you can get +traceparent+ instead of
+      # +HTTP_TRACEPARENT+
+      class RackEnvGetter
+        # 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[key]
+        end
+
+        # Reads all keys from a carrier and converts them from the rack-normalized
+        # form to the original. The resulting keys will be lowercase and
+        # underscores will be replaced with dashes.
+        def keys(carrier)
+          carrier.keys.map(&method(:from_rack_key))
+        end
+
+        private
+
+        def to_rack_key(key)
+          ret = 'HTTP_' + key
+          ret.tr!('-', '_')
+          ret.upcase!
+          ret
+        end
+
+        def from_rack_key(key)
+          start = key.start_with?('HTTP_') ? 5 : 0
+          ret = key[start..-1]
+          ret.tr!('_', '-')
+          ret.downcase!
+          ret
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+# Copyright The OpenTelemetry Authors
+#
+# SPDX-License-Identifier: Apache-2.0
+
+module OpenTelemetry
+  class Context
+    module Propagation
+      # The default getter module provides a common methods for reading
+      # key from a carrier that implements +[]+ and a +keys+ method
+      class TextMapGetter
+        # Reads a key from a carrier that implements +[]+. Useful for extract
+        # operations.
+        def get(carrier, key)
+          carrier[key]
+        end
+
+        # Reads all keys from a carrier. Useful for iterating over a carrier's
+        # keys.
+        def keys(carrier)
+          carrier.keys
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+# Copyright The OpenTelemetry Authors
+#
+# SPDX-License-Identifier: Apache-2.0
+
+module OpenTelemetry
+  class Context
+    module Propagation
+      # 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
+
+        # Injects the provided context into a carrier using the underlying
+        # injector. Logs a warning if injection fails.
+        #
+        # @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)
+          @injector.inject(carrier, context, setter)
+          nil
+        rescue StandardError => e
+          OpenTelemetry.logger.warn "Error in Propagator#inject #{e.message}"
+          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 [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)
+          @extractor.extract(carrier, context, getter)
+        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
+end