opentelemetry-api 0.5.1 → 0.10.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6851022b08b4488e128a4bc73ef53b1463c8bd04763aba1ecd7279aaf32e65ae
-  data.tar.gz: fa593580948f328f9445849846e0856ff496f63513c6352e5000cc27f6695faa
+  metadata.gz: 2cee7fab7654059566d26d776b3813fbf526152804e861788d4c432c1167eb51
+  data.tar.gz: e1fb0ea50cf900e5caa840ddbc7031e083d4ac91250befab42036e7be93ab83d
 SHA512:
-  metadata.gz: 280ab63486d494ab2e338cba6d9d8c60ff8dd9c7bf79f70ab83606caa7dd16eb9e10708d6205e6725fed1e519b07e26faf1e267d59d0579cd4b673e97fdfc7cb
-  data.tar.gz: 756dc2722afe75c45c3aef8c06a1885e77a6f132d7cf4772488df40a5205b6ee182d9cd9e683951c49e9f18b81d12176adc1286e12fbe8dd1c732335df6e2d20
+  metadata.gz: b0bdfb487a5d1031c9f5981ace74e9535e4bd871059ab7f43070e451c4ef598361dde7c15644a31ba9b4f829f578fdb520568f484250f57ce31e686f0005834d
+  data.tar.gz: 3c247ff76a50b9ba58ac6ce3b2f534a86c2792181323c43c5407bc4f13afa17273651eee5eebe808d419b266f7fc94d3cf29a39e05d3b387dd7fbed96819126e

data/.yardopts

@@ -1,9 +1,9 @@
 --no-private
 --title=OpenTelemetry API
 --markup=markdown
---main=OVERVIEW.md
+--main=README.md
 ./lib/opentelemetry/**/*.rb
 ./lib/opentelemetry.rb
 -
-OVERVIEW.md
+README.md
 CHANGELOG.md

data/CHANGELOG.md

@@ -1 +1,39 @@
 # Release History: opentelemetry-api
+
+### v0.10.0 / 2020-12-03
+
+* (No significant changes)
+
+### v0.9.0 / 2020-11-27
+
+* (No significant changes)
+
+### v0.8.0 / 2020-10-27
+
+* BREAKING CHANGE: Move context/span methods to Trace module 
+* BREAKING CHANGE: Remove 'canonical' from status codes 
+* BREAKING CHANGE: Assorted SpanContext fixes 
+
+* ADDED: B3 support 
+* FIXED: Move context/span methods to Trace module 
+* FIXED: Remove 'canonical' from status codes 
+* FIXED: Assorted SpanContext fixes 
+
+### v0.7.0 / 2020-10-07
+
+* FIXED: Safely navigate span variable during error cases 
+* DOCS: Standardize toplevel docs structure and readme 
+* DOCS: Fix param description in TextMapInjector for Baggage 
+
+### v0.6.0 / 2020-09-10
+
+* ADDED: Add support for OTEL_LOG_LEVEL env var
+* Documented array valued attributes [#343](https://github.com/open-telemetry/opentelemetry-ruby/pull/343)
+* Renamed CorrelationContext to Baggage [#338](https://github.com/open-telemetry/opentelemetry-ruby/pull/338)
+* Renamed Text* to TextMap* (propagators) [#335](https://github.com/open-telemetry/opentelemetry-ruby/pull/335)
+* Fixed exception semantic conventions (`span.record_error` -> `span.record_exception`) [#333](https://github.com/open-telemetry/opentelemetry-ruby/pull/333)
+* Removed support for lazy event creation [#329](https://github.com/open-telemetry/opentelemetry-ruby/pull/329)
+  * `name:` named parameter to `span.add_event` becomes first positional argument
+  * `Event` class removed from API
+* Added `hex_trace_id` and `hex_span_id` helpers to `SpanContext` [#332](https://github.com/open-telemetry/opentelemetry-ruby/pull/332)
+* Added `CorrelationContext::Manager.values` method to return correlations as a `Hash` [#323](https://github.com/open-telemetry/opentelemetry-ruby/pull/323)

data/lib/opentelemetry.rb

@@ -8,8 +8,7 @@ require 'logger'
 
 require 'opentelemetry/error'
 require 'opentelemetry/context'
-require 'opentelemetry/correlation_context'
-require 'opentelemetry/internal'
+require 'opentelemetry/baggage'
 require_relative './opentelemetry/instrumentation'
 require 'opentelemetry/metrics'
 require 'opentelemetry/trace'
@@ -23,9 +22,12 @@ require 'opentelemetry/version'
 module OpenTelemetry
   extend self
 
-  attr_writer :tracer_provider, :meter_provider, :correlations
+  attr_writer :tracer_provider, :meter_provider, :baggage, :logger
 
-  attr_accessor :logger
+  # @return [Object, Logger] configured Logger or a default STDOUT Logger.
+  def logger
+    @logger ||= Logger.new(STDOUT, level: ENV['OTEL_LOG_LEVEL'] || Logger::INFO)
+  end
 
   # @return [Object, Trace::TracerProvider] registered tracer provider or a
   #   default no-op implementation of the tracer provider.
@@ -45,17 +47,15 @@ module OpenTelemetry
     @instrumentation_registry ||= Instrumentation::Registry.new
   end
 
-  # @return [Object, CorrelationContext::Manager] registered
-  #   correlation context manager or a default no-op implementation of the
+  # @return [Object, Baggage::Manager] registered
+  #   baggage manager or a default no-op implementation of the
   #   manager.
-  def correlations
-    @correlations ||= CorrelationContext::Manager.new
+  def baggage
+    @baggage ||= Baggage::Manager.new
   end
 
   # @return [Context::Propagation::Propagation] an instance of the propagation API
   def propagation
     @propagation ||= Context::Propagation::Propagation.new
   end
-
-  self.logger = Logger.new(STDOUT)
 end

data/lib/opentelemetry/baggage.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+# Copyright 2019 OpenTelemetry Authors
+#
+# SPDX-License-Identifier: Apache-2.0
+
+require 'opentelemetry/baggage/builder'
+require 'opentelemetry/baggage/manager'
+require 'opentelemetry/baggage/propagation'
+
+module OpenTelemetry
+  # The Baggage module provides functionality to record and propagate
+  # baggage in a distributed trace
+  module Baggage
+  end
+end

data/lib/opentelemetry/{correlation_context → baggage}/builder.rb

@@ -5,8 +5,8 @@
 # SPDX-License-Identifier: Apache-2.0
 
 module OpenTelemetry
-  module CorrelationContext
-    # No op implementation of CorrelationContext::Builder
+  module Baggage
+    # No op implementation of Baggage::Builder
     class Builder
       def set_value(key, value); end
 

data/lib/opentelemetry/{correlation_context → baggage}/manager.rb

@@ -5,11 +5,12 @@
 # SPDX-License-Identifier: Apache-2.0
 
 module OpenTelemetry
-  module CorrelationContext
-    # No op implementation of CorrelationContext::Manager
+  module Baggage
+    # No op implementation of Baggage::Manager
     class Manager
       NOOP_BUILDER = Builder.new
-      private_constant :NOOP_BUILDER
+      EMPTY_VALUES = {}.freeze
+      private_constant(:NOOP_BUILDER, :EMPTY_VALUES)
 
       def build(context: Context.current)
         yield NOOP_BUILDER
@@ -24,6 +25,10 @@ module OpenTelemetry
         nil
       end
 
+      def values(context: Context.current)
+        EMPTY_VALUES
+      end
+
       def remove_value(key, context: Context.current)
         context
       end

data/lib/opentelemetry/baggage/propagation.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+# Copyright 2019 OpenTelemetry Authors
+#
+# 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'
+
+module OpenTelemetry
+  module Baggage
+    # The Baggage::Propagation module contains injectors and
+    # extractors for sending and receiving baggage over the wire
+    module Propagation
+      extend self
+
+      TEXT_MAP_EXTRACTOR = TextMapExtractor.new
+      TEXT_MAP_INJECTOR = TextMapInjector.new
+      RACK_EXTRACTOR = TextMapExtractor.new(
+        baggage_key: 'HTTP_BAGGAGE'
+      )
+      RACK_INJECTOR = TextMapInjector.new(
+        baggage_key: 'HTTP_BAGGAGE'
+      )
+
+      private_constant :TEXT_MAP_INJECTOR, :TEXT_MAP_EXTRACTOR, :RACK_INJECTOR,
+                       :RACK_EXTRACTOR
+
+      # 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
+      end
+
+      # Returns an extractor that extracts context using the W3C Baggage
+      # format with Rack normalized keys (upcased and prefixed with
+      # HTTP_)
+      def rack_injector
+        RACK_INJECTOR
+      end
+
+      # Returns an injector that injects context using the W3C Baggage
+      # format with Rack normalized keys (upcased and prefixed with
+      # HTTP_)
+      def rack_extractor
+        RACK_EXTRACTOR
+      end
+    end
+  end
+end

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

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+# Copyright 2019 OpenTelemetry Authors
+#
+# SPDX-License-Identifier: Apache-2.0
+
+module OpenTelemetry
+  module Baggage
+    module Propagation
+      # The ContextKeys module contains the keys used to index baggage
+      # in a {Context} instance
+      module ContextKeys
+        extend self
+
+        BAGGAGE_KEY = Context.create_key('baggage')
+        private_constant :BAGGAGE_KEY
+
+        # Returns the context key that baggage are indexed by
+        #
+        # @return [Context::Key]
+        def baggage_key
+          BAGGAGE_KEY
+        end
+      end
+    end
+  end
+end

data/lib/opentelemetry/{correlation_context/propagation/text_extractor.rb → baggage/propagation/text_map_extractor.rb}

@@ -7,41 +7,41 @@
 require 'cgi'
 
 module OpenTelemetry
-  module CorrelationContext
+  module Baggage
     module Propagation
-      # Extracts correlations from carriers in the W3C Correlation Context format
-      class TextExtractor
+      # Extracts baggage from carriers in the W3C Baggage format
+      class TextMapExtractor
         include Context::Propagation::DefaultGetter
 
-        # Returns a new TextExtractor that extracts context using the specified
+        # Returns a new TextMapExtractor that extracts context using the specified
         # header key
         #
-        # @param [String] correlation_context_key The correlation context header
+        # @param [String] baggage_key The baggage header
         #   key used in the carrier
-        # @return [TextExtractor]
-        def initialize(correlation_context_key: 'otcorrelations')
-          @correlation_context_key = correlation_context_key
+        # @return [TextMapExtractor]
+        def initialize(baggage_key: 'baggage')
+          @baggage_key = baggage_key
         end
 
-        # Extract remote correlations from the supplied carrier.
+        # 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 [Context] context The context to be updated with extracted correlations
+        # @param [Context] context The context to be updated with extracted baggage
         # @param [optional Callable] getter An optional callable that takes a carrier and a key and
         #   returns the value associated with the key. If omitted the default getter will be used
         #   which expects the carrier to respond to [] and []=.
         # @yield [Carrier, String] if an optional getter is provided, extract will yield the carrier
         #   and the header key to the getter.
-        # @return [Context] context updated with extracted correlations, or the original context
+        # @return [Context] context updated with extracted baggage, or the original context
         #   if extraction fails
         def extract(carrier, context, &getter)
           getter ||= default_getter
-          header = getter.call(carrier, @correlation_context_key)
+          header = getter.call(carrier, @baggage_key)
 
           entries = header.gsub(/\s/, '').split(',')
 
-          correlations = entries.each_with_object({}) do |entry, memo|
+          baggage = entries.each_with_object({}) do |entry, memo|
             # The ignored variable below holds properties as per the W3C spec.
             # OTel is not using them currently, but they might be used for
             # metadata in the future
@@ -50,7 +50,7 @@ module OpenTelemetry
             memo[k] = v
           end
 
-          context.set_value(ContextKeys.correlation_context_key, correlations)
+          context.set_value(ContextKeys.baggage_key, baggage)
         rescue StandardError
           context
         end

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

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+# Copyright 2019 OpenTelemetry Authors
+#
+# SPDX-License-Identifier: Apache-2.0
+
+require 'cgi'
+
+module OpenTelemetry
+  module Baggage
+    module Propagation
+      # Injects baggage using the W3C Baggage format
+      class TextMapInjector
+        include Context::Propagation::DefaultSetter
+
+        # Returns a new TextMapInjector that injects context using the specified
+        # header key
+        #
+        # @param [String] baggage_key The baggage header
+        #   key used in the carrier
+        # @return [TextMapInjector]
+        def initialize(baggage_key: 'baggage')
+          @baggage_key = baggage_key
+        end
+
+        # Inject in-process baggage into the supplied carrier.
+        #
+        # @param [Carrier] carrier The carrier to inject baggage into
+        # @param [Context] context The context to read baggage from
+        # @param [optional Callable] getter An optional callable that takes a carrier and a key and
+        #   returns the value associated with the key. If omitted the default getter will be used
+        #   which expects the carrier to respond to [] and []=.
+        # @yield [Carrier, String] if an optional getter is provided, inject will yield the carrier
+        #   and the header key to the getter.
+        # @return [Object] carrier with injected baggage
+        def inject(carrier, context, &setter)
+          return carrier unless (baggage = context[ContextKeys.baggage_key]) && !baggage.empty?
+
+          setter ||= default_setter
+          setter.call(carrier, @baggage_key, encode(baggage))
+
+          carrier
+        end
+
+        private
+
+        def encode(baggage)
+          baggage.inject(+'') do |memo, (k, v)|
+            memo << CGI.escape(k.to_s) << '=' << CGI.escape(v.to_s) << ','
+          end.chop!
+        end
+      end
+    end
+  end
+end

data/lib/opentelemetry/trace.rb

@@ -9,6 +9,12 @@ module OpenTelemetry
   # single logical operation, consolidated across various components of an
   # application.
   module Trace
+    extend self
+
+    CURRENT_SPAN_KEY = Context.create_key('current-span')
+
+    private_constant :CURRENT_SPAN_KEY
+
     # An invalid trace identifier, a 16-byte string with all zero bytes.
     INVALID_TRACE_ID = ("\0" * 16).b
 
@@ -19,7 +25,7 @@ module OpenTelemetry
     # non-zero byte.
     #
     # @return [String] a valid trace ID.
-    def self.generate_trace_id
+    def generate_trace_id
       loop do
         id = Random::DEFAULT.bytes(16)
         return id unless id == INVALID_TRACE_ID
@@ -30,22 +36,50 @@ module OpenTelemetry
     # non-zero byte.
     #
     # @return [String] a valid span ID.
-    def self.generate_span_id
+    def generate_span_id
       loop do
         id = Random::DEFAULT.bytes(8)
         return id unless id == INVALID_SPAN_ID
       end
     end
+
+    # Returns the current span from the current or provided context
+    #
+    # @param [optional Context] context The context to lookup the current
+    #   {Span} from. Defaults to Context.current
+    def current_span(context = nil)
+      context ||= Context.current
+      context.value(CURRENT_SPAN_KEY) || Span::INVALID
+    end
+
+    # Returns a context containing the span, derived from the optional parent
+    # context, or the current context if one was not provided.
+    #
+    # @param [optional Context] context The context to use as the parent for
+    #   the returned context
+    def context_with_span(span, parent_context: Context.current)
+      parent_context.set_value(CURRENT_SPAN_KEY, span)
+    end
+
+    # Activates/deactivates the Span within the current Context, which makes the "current span"
+    # available implicitly.
+    #
+    # On exit, the Span that was active before calling this method will be reactivated.
+    #
+    # @param [Span] span the span to activate
+    # @yield [span, context] yields span and a context containing the span to the block.
+    def with_span(span)
+      Context.with_value(CURRENT_SPAN_KEY, span) { |c, s| yield s, c }
+    end
   end
 end
 
-require 'opentelemetry/trace/event'
 require 'opentelemetry/trace/link'
-require 'opentelemetry/trace/propagation'
 require 'opentelemetry/trace/trace_flags'
 require 'opentelemetry/trace/span_context'
 require 'opentelemetry/trace/span_kind'
 require 'opentelemetry/trace/span'
 require 'opentelemetry/trace/status'
+require 'opentelemetry/trace/propagation'
 require 'opentelemetry/trace/tracer'
 require 'opentelemetry/trace/tracer_provider'