opentelemetry-api 0.16.0 → 0.17.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2044ecfc3776d70aa668bcbd537f9df904f3a48a19b3b1daa67d0632686b3358
-  data.tar.gz: 996749298853bb15d62cadff700e06a1f3bcb505f5b49786b713c1daa1796165
+  metadata.gz: 9d983ae124f8d6da3e8fa92560912718bdbbc9a3ea89f2012cb2d51e6d80873d
+  data.tar.gz: 75bc11d4296b0a21a136b3ada57d6a5cf59c736d61d6d113ab4bbd6195dacb8c
 SHA512:
-  metadata.gz: 12c9863e4b90e34f5b4d6e2e3e5b97244d609e5381d554b39d461e77cfff5e7f8130b1389c68743d6fb7ea3080321aa4b12dc56e3ca78cac20fda1cc0100e7b7
-  data.tar.gz: 990f49fa7ef5e2990283cf4b42af9a6ecaa4989078a7b084568806675a9a2d3ae635bb830bccc9626b51869e3f0bfc9df5406f2cdbfda6c33576e4fd92c26716
+  metadata.gz: 2c051831f433ca25fbbdf4662d7ac8e156804bdb98e6dd5d2476597baac55561edc46d32bb3a02d23f7a316e20aee88b6ea5dfae608813933d8d08d5fdbb7afb
+  data.tar.gz: 9bd812321d5d84960a4e866a50b1a6b483a6742a4a909118792a72859e7123df0f945fea4476eeb9e5eca6e2b120cfd09eee55475a7ef36f11bafb4e124f1258

data/CHANGELOG.md

@@ -1,5 +1,22 @@
 # Release History: opentelemetry-api
 
+### v0.17.0 / 2021-04-22
+
+* BREAKING CHANGE: Replace TextMapInjector/TextMapExtractor pairs with a TextMapPropagator.
+
+  [Check the propagator documentation](https://open-telemetry.github.io/opentelemetry-ruby/) for the new usage.
+* BREAKING CHANGE: Remove metrics API.
+
+  `OpenTelemetry::Metrics` and all of its behavior removed until spec stabilizes.
+* BREAKING CHANGE: Extract instrumentation base from api (#698).
+
+  To take advantage of a base instrumentation class to create your own auto-instrumentation, require and use the `opentelemetry-instrumentation-base` gem.
+
+* ADDED: Default noop tracer for instrumentation 
+* FIXED: Refactor propagators to add #fields 
+* FIXED: Remove metrics API 
+* FIXED: Dynamically upgrade global tracer provider 
+
 ### v0.16.0 / 2021-03-17
 
 * ADDED: Span#add_attributes 

data/lib/opentelemetry.rb

@@ -9,9 +9,8 @@ require 'logger'
 require 'opentelemetry/error'
 require 'opentelemetry/context'
 require 'opentelemetry/baggage'
-require_relative './opentelemetry/instrumentation'
-require 'opentelemetry/metrics'
 require 'opentelemetry/trace'
+require 'opentelemetry/internal'
 require 'opentelemetry/version'
 
 # OpenTelemetry is an open source observability framework, providing a
@@ -22,8 +21,10 @@ require 'opentelemetry/version'
 module OpenTelemetry
   extend self
 
-  attr_writer :tracer_provider, :meter_provider, :propagation, :baggage,
-              :logger, :error_handler
+  @mutex = Mutex.new
+  @tracer_provider = Internal::ProxyTracerProvider.new
+
+  attr_writer :propagation, :baggage, :logger, :error_handler
 
   # @return [Object, Logger] configured Logger or a default STDOUT Logger.
   def logger
@@ -44,36 +45,35 @@ module OpenTelemetry
     error_handler.call(exception: exception, message: message)
   end
 
+  # Register the global tracer provider.
+  #
+  # @param [TracerProvider] provider A tracer provider to register as the
+  #   global instance.
+  def tracer_provider=(provider)
+    @mutex.synchronize do
+      if @tracer_provider.instance_of? Internal::ProxyTracerProvider
+        logger.debug("Upgrading default proxy tracer provider to #{provider.class}")
+        @tracer_provider.delegate = provider
+      end
+      @tracer_provider = provider
+    end
+  end
+
   # @return [Object, Trace::TracerProvider] registered tracer provider or a
   #   default no-op implementation of the tracer provider.
   def tracer_provider
-    @tracer_provider ||= Trace::TracerProvider.new
-  end
-
-  # @return [Object, Metrics::MeterProvider] registered meter provider or a
-  #   default no-op implementation of the meter provider.
-  def meter_provider
-    @meter_provider ||= Metrics::MeterProvider.new
-  end
-
-  # @return [Instrumentation::Registry] registry containing all known
-  #  instrumentation
-  def instrumentation_registry
-    @instrumentation_registry ||= Instrumentation::Registry.new
+    @mutex.synchronize { @tracer_provider }
   end
 
-  # @return [Object, Baggage::Manager] registered
+  # @return [Object, Baggage::NoopManager] registered
   #   baggage manager or a default no-op implementation of the
   #   manager.
   def baggage
-    @baggage ||= Baggage::Manager.new
+    @baggage ||= Baggage::NoopManager.new
   end
 
   # @return [Context::Propagation::Propagator] a propagator instance
   def propagation
-    @propagation ||= Context::Propagation::Propagator.new(
-      Context::Propagation::NoopInjector.new,
-      Context::Propagation::NoopExtractor.new
-    )
+    @propagation ||= Context::Propagation::NoopTextMapPropagator.new
   end
 end

data/lib/opentelemetry/baggage.rb

@@ -4,9 +4,12 @@
 #
 # SPDX-License-Identifier: Apache-2.0
 
+require 'opentelemetry/baggage/propagation'
 require 'opentelemetry/baggage/builder'
+require 'opentelemetry/baggage/entry'
 require 'opentelemetry/baggage/manager'
-require 'opentelemetry/baggage/propagation'
+require 'opentelemetry/baggage/noop_builder'
+require 'opentelemetry/baggage/noop_manager'
 
 module OpenTelemetry
   # The Baggage module provides functionality to record and propagate

data/lib/opentelemetry/baggage/builder.rb

@@ -6,13 +6,39 @@
 
 module OpenTelemetry
   module Baggage
-    # No op implementation of Baggage::Builder
+    # Operational implementation of Baggage::Builder
     class Builder
-      def set_value(key, value); end
+      # @api private
+      attr_reader :entries
 
-      def remove_value(key); end
+      # @api private
+      def initialize(entries)
+        @entries = entries
+      end
 
-      def clear; end
+      # Set key-value in the to-be-created baggage
+      #
+      # @param [String] key The key to store this value under
+      # @param [String] value String value to be stored under key
+      # @param [optional String] metadata This is here to store properties
+      #   received from other W3C Baggage impelmentations but is not exposed in
+      #   OpenTelemetry. This is condsidered private API and not for use by
+      #   end-users.
+      def set_value(key, value, metadata: nil)
+        @entries[key] = OpenTelemetry::Baggage::Entry.new(value, metadata)
+      end
+
+      # Removes key from the to-be-created baggage
+      #
+      # @param [String] key The key to remove
+      def remove_value(key)
+        @entries.delete(key)
+      end
+
+      # Clears all baggage from the to-be-created baggage
+      def clear
+        @entries.clear
+      end
     end
   end
 end

data/lib/opentelemetry/baggage/entry.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+# Copyright The OpenTelemetry Authors
+#
+# SPDX-License-Identifier: Apache-2.0
+
+module OpenTelemetry
+  # OpenTelemetry Baggage Implementation
+  module Baggage
+    # Read-only representation of a baggage entry
+    class Entry
+      attr_reader :value, :metadata
+
+      def initialize(value, metadata = nil)
+        @value = value
+        @metadata = metadata
+      end
+    end
+  end
+end

data/lib/opentelemetry/baggage/manager.rb

@@ -6,35 +6,98 @@
 
 module OpenTelemetry
   module Baggage
-    # No op implementation of Baggage::Manager
+    # Operational Baggage Manager implementation
     class Manager
-      NOOP_BUILDER = Builder.new
-      EMPTY_VALUES = {}.freeze
-      private_constant(:NOOP_BUILDER, :EMPTY_VALUES)
+      BAGGAGE_KEY = OpenTelemetry::Baggage::Propagation::ContextKeys.baggage_key
+      EMPTY_BAGGAGE = {}.freeze
+      private_constant(:BAGGAGE_KEY, :EMPTY_BAGGAGE)
 
+      # Used to chain modifications to baggage. The result is a
+      # context with an updated baggage. If only a single
+      # modification is being made to baggage, use the other
+      # methods on +Manager+, if multiple modifications are being made, use
+      # this one.
+      #
+      # @param [optional Context] context The context to update with with new
+      #   modified baggage. Defaults to +Context.current+
+      # @return [Context]
       def build(context: Context.current)
-        yield NOOP_BUILDER
-        context
+        builder = Builder.new(baggage_for(context).dup)
+        yield builder
+        context.set_value(BAGGAGE_KEY, builder.entries)
       end
 
-      def set_value(key, value, context: Context.current)
-        context
+      # Returns a new context with empty baggage
+      #
+      # @param [optional Context] context Context to clear baggage from. Defaults
+      #   to +Context.current+
+      # @return [Context]
+      def clear(context: Context.current)
+        context.set_value(BAGGAGE_KEY, EMPTY_BAGGAGE)
       end
 
+      # Returns the corresponding baggage.entry (or nil) for key
+      #
+      # @param [String] key The lookup key
+      # @param [optional Context] context The context from which to retrieve
+      #   the key.
+      #   Defaults to +Context.current+
+      # @return [String]
       def value(key, context: Context.current)
-        nil
+        baggage_for(context)[key]&.value
       end
 
+      # Returns the baggage
+      #
+      # @param [optional Context] context The context from which to retrieve
+      #   the baggage.
+      #   Defaults to +Context.current+
+      # @return [Hash]
       def values(context: Context.current)
-        EMPTY_VALUES
+        baggage_for(context).transform_values(&:value)
+      end
+
+      # @api private
+      def raw_entries(context: Context.current)
+        baggage_for(context).dup.freeze
+      end
+
+      # Returns a new context with new key-value pair
+      #
+      # @param [String] key The key to store this value under
+      # @param [String] value String value to be stored under key
+      # @param [optional String] metadata This is here to store properties
+      #   received from other W3C Baggage impelmentations but is not exposed in
+      #   OpenTelemetry. This is condsidered private API and not for use by
+      #   end-users.
+      # @param [optional Context] context The context to update with new
+      #   value. Defaults to +Context.current+
+      # @return [Context]
+      def set_value(key, value, metadata: nil, context: Context.current)
+        new_baggage = baggage_for(context).dup
+        new_baggage[key] = Entry.new(value, metadata)
+        context.set_value(BAGGAGE_KEY, new_baggage)
       end
 
+      # Returns a new context with value at key removed
+      #
+      # @param [String] key The key to remove
+      # @param [optional Context] context The context to remove baggage
+      #   from. Defaults to +Context.current+
+      # @return [Context]
       def remove_value(key, context: Context.current)
-        context
+        baggage = baggage_for(context)
+        return context unless baggage.key?(key)
+
+        new_baggage = baggage.dup
+        new_baggage.delete(key)
+        context.set_value(BAGGAGE_KEY, new_baggage)
       end
 
-      def clear(context: Context.current)
-        context
+      private
+
+      def baggage_for(context)
+        context.value(BAGGAGE_KEY) || EMPTY_BAGGAGE
       end
     end
   end

data/lib/opentelemetry/baggage/noop_builder.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+# Copyright The OpenTelemetry Authors
+#
+# SPDX-License-Identifier: Apache-2.0
+
+module OpenTelemetry
+  module Baggage
+    # No op implementation of Baggage::Builder
+    class NoopBuilder
+      def set_value(key, value, metadata: nil); end
+
+      def remove_value(key); end
+
+      def clear; end
+    end
+  end
+end

data/lib/opentelemetry/baggage/noop_manager.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+# Copyright The OpenTelemetry Authors
+#
+# SPDX-License-Identifier: Apache-2.0
+
+module OpenTelemetry
+  module Baggage
+    # No op implementation of Baggage::Manager
+    class NoopManager
+      NOOP_BUILDER = NoopBuilder.new
+      EMPTY_HASH = {}.freeze
+      private_constant(:NOOP_BUILDER, :EMPTY_HASH)
+
+      def build(context: Context.current)
+        yield NOOP_BUILDER
+        context
+      end
+
+      def set_value(key, value, metadata: nil, context: Context.current)
+        context
+      end
+
+      def value(key, context: Context.current)
+        nil
+      end
+
+      def values(context: Context.current)
+        EMPTY_HASH
+      end
+
+      def raw_entries(context: Context.current)
+        EMPTY_HASH
+      end
+
+      def remove_value(key, context: Context.current)
+        context
+      end
+
+      def clear(context: Context.current)
+        context
+      end
+    end
+  end
+end

data/lib/opentelemetry/baggage/propagation.rb

@@ -5,32 +5,23 @@
 # SPDX-License-Identifier: Apache-2.0
 
 require 'opentelemetry/baggage/propagation/context_keys'
-require 'opentelemetry/baggage/propagation/text_map_injector'
-require 'opentelemetry/baggage/propagation/text_map_extractor'
+require 'opentelemetry/baggage/propagation/text_map_propagator'
 
 module OpenTelemetry
   module Baggage
-    # The Baggage::Propagation module contains injectors and
-    # extractors for sending and receiving baggage over the wire
+    # The Baggage::Propagation module contains a text map propagator for
+    # sending and receiving baggage over the wire.
     module Propagation
       extend self
 
-      BAGGAGE_KEY = 'baggage'
-      TEXT_MAP_EXTRACTOR = TextMapExtractor.new
-      TEXT_MAP_INJECTOR = TextMapInjector.new
+      TEXT_MAP_PROPAGATOR = TextMapPropagator.new
 
-      private_constant :BAGGAGE_KEY, :TEXT_MAP_INJECTOR, :TEXT_MAP_EXTRACTOR
+      private_constant :TEXT_MAP_PROPAGATOR
 
-      # Returns an extractor that extracts context using the W3C Baggage
-      # format
-      def text_map_injector
-        TEXT_MAP_INJECTOR
-      end
-
-      # Returns an injector that injects context using the W3C Baggage
-      # format
-      def text_map_extractor
-        TEXT_MAP_EXTRACTOR
+      # Returns a text map propagator that propagates context using the
+      # W3C Baggage format.
+      def text_map_propagator
+        TEXT_MAP_PROPAGATOR
       end
     end
   end

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