opentelemetry-api 0.16.0 → 1.0.0.rc3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2044ecfc3776d70aa668bcbd537f9df904f3a48a19b3b1daa67d0632686b3358
-  data.tar.gz: 996749298853bb15d62cadff700e06a1f3bcb505f5b49786b713c1daa1796165
+  metadata.gz: b873eaad4492b7cefaebdf1a9e5e9998f8af3192340d0d4eae0d2e7c32964e16
+  data.tar.gz: a7a4c5c20d299ac33d0cae853104ee8f33a2f8e4436888e5259a706b0061d6cb
 SHA512:
-  metadata.gz: 12c9863e4b90e34f5b4d6e2e3e5b97244d609e5381d554b39d461e77cfff5e7f8130b1389c68743d6fb7ea3080321aa4b12dc56e3ca78cac20fda1cc0100e7b7
-  data.tar.gz: 990f49fa7ef5e2990283cf4b42af9a6ecaa4989078a7b084568806675a9a2d3ae635bb830bccc9626b51869e3f0bfc9df5406f2cdbfda6c33576e4fd92c26716
+  metadata.gz: a9689040364ba9f92dbd9b4af6a95c5d9e0adbffb805ed79f3d0e4a7e2061fd6ac0d5dec6ec50ef5e4fe290dfd74c3779a0331145b9ebee5fe83dc9551bdf58a
+  data.tar.gz: 0127d9a7168c4f275a132b63f038d0e4f58105d72475e70ab2db03f3a868dc85d2252e5c50bf5b52af713b0018c33a4d8366a872ba4d1522304e2d8f5e8d5360

data/CHANGELOG.md

@@ -1,5 +1,62 @@
 # Release History: opentelemetry-api
 
+### v1.0.0.rc3 / 2021-08-12
+
+* BREAKING CHANGE: Remove optional parent_context from in_span
+* BREAKING CHANGE: Refactor Baggage to remove Noop*
+* BREAKING CHANGE: Total order constraint on span.status=
+
+* ADDED: Add Tracer.non_recording_span to API
+* ADDED: Make API's NoopTextMapPropagator private
+* FIXED: Remove optional parent_context from in_span
+* FIXED: Reduce span allocation in API
+* FIXED: Refactor Baggage to remove Noop*
+* FIXED: Total order constraint on span.status=
+* FIXED: Return early if carrier is nil
+* FIXED: Update context to match spec
+* FIXED: Return the original context if the baggage header value is empty
+* DOCS: Update docs to rely more on environment variable configuration
+
+### v1.0.0.rc2 / 2021-06-23
+
+* BREAKING CHANGE: Remove optional parent_context from in_span [729](https://github.com/open-telemetry/opentelemetry-ruby/pull/729)
+* BREAKING CHANGE: Refactor Baggage to remove Noop* [800](https://github.com/open-telemetry/opentelemetry-ruby/pull/800)
+  - The noop baggage manger has been removed.
+  - The baggage management methods are now available through OpenTelemetry::Baggage#method, previously OpenTelemetry.baggage#method
+* BREAKING CHANGE: Total order constraint on span.status= [805](https://github.com/open-telemetry/opentelemetry-ruby/pull/805)
+  - The OpenTelemetry::Trace::Util::HttpToStatus module has been removed as it was incorrectly setting the span status to OK for codes codes in the range 100..399
+  - The HttpToStatus module can be replaced inline as follows `span.status = OpenTelemetry::Trace::Status.error unless (100..399).include?(response_code.to_i)`
+  - The `Status.new(code, description:)` initializer has been hidden in favour of simpler constructors for each status code: `Status.ok`, `Status.error` and `Status.unset`. Each constructor takes an optional description.
+
+* ADDED: Add Tracer.non_recording_span to API [799](https://github.com/open-telemetry/opentelemetry-ruby/pull/799)
+* FIXED: Reduce span allocation in API [795](https://github.com/open-telemetry/opentelemetry-ruby/pull/795)
+* FIXED: Return early if carrier is nil [835](https://github.com/open-telemetry/opentelemetry-ruby/pull/835)
+* FIXED: Update context to match spec [807](https://github.com/open-telemetry/opentelemetry-ruby/pull/807)
+  - The `Context.current` setter has been removed and the previously private attach/detach methods are now available as class methods on the context module.
+
+### v1.0.0.rc1 / 2021-05-21
+
+* BREAKING CHANGE: Remove optional parent_context from in_span 
+
+* FIXED: Remove optional parent_context from in_span
+
+### 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/README.md

@@ -29,11 +29,11 @@ Then, use the OpenTelemetry interfaces to produces traces and other telemetry da
 ```ruby
 require 'opentelemetry'
 
-# Obtain the current default tracer factory
-factory = OpenTelemetry.tracer_factory
+# Obtain the current default tracer provider
+provider = OpenTelemetry.tracer_provider
 
 # Create a trace
-tracer = factory.tracer('my_app', '1.0')
+tracer = provider.tracer('my_app', '1.0')
 
 # Record spans
 tracer.in_span('my_task') do |task_span|

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, :logger, :error_handler
 
   # @return [Object, Logger] configured Logger or a default STDOUT Logger.
   def logger
@@ -44,36 +45,28 @@ 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
-  end
-
-  # @return [Object, Baggage::Manager] registered
-  #   baggage manager or a default no-op implementation of the
-  #   manager.
-  def baggage
-    @baggage ||= Baggage::Manager.new
+    @mutex.synchronize { @tracer_provider }
   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,13 +4,106 @@
 #
 # SPDX-License-Identifier: Apache-2.0
 
-require 'opentelemetry/baggage/builder'
-require 'opentelemetry/baggage/manager'
 require 'opentelemetry/baggage/propagation'
+require 'opentelemetry/baggage/builder'
+require 'opentelemetry/baggage/entry'
 
 module OpenTelemetry
   # The Baggage module provides functionality to record and propagate
   # baggage in a distributed trace
   module Baggage
+    extend self
+
+    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 +Baggage+, 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)
+      builder = Builder.new(baggage_for(context).dup)
+      yield builder
+      context.set_value(BAGGAGE_KEY, builder.entries)
+    end
+
+    # 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)
+      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)
+      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)
+      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
+
+    private
+
+    def baggage_for(context)
+      context.value(BAGGAGE_KEY) || EMPTY_BAGGAGE
+    end
   end
 end

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/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,111 @@
+# 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 or there is no baggage to extract,
+        # then 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)
+          return context if header.nil? || header.empty?
+
+          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