opentelemetry-api 0.2.0 → 0.3.0

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

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+# Copyright 2019 OpenTelemetry Authors
+#
+# SPDX-License-Identifier: Apache-2.0
+
+module OpenTelemetry
+  class Context
+    module Propagation
+      # The default getter module provides a common method for reading
+      # a key from a carrier that implements +[]+
+      module DefaultGetter
+        DEFAULT_GETTER = ->(carrier, key) { carrier[key] }
+        private_constant :DEFAULT_GETTER
+
+        # Returns a callable that can read a key from a carrier that implements
+        # +[]+. Useful for extract operations.
+        #
+        # @return [Callable]
+        def default_getter
+          DEFAULT_GETTER
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+# Copyright 2019 OpenTelemetry Authors
+#
+# SPDX-License-Identifier: Apache-2.0
+
+module OpenTelemetry
+  class Context
+    module Propagation
+      # The default setter module provides a common method for writing
+      # a key into a carrier that implements +[]=+
+      module DefaultSetter
+        DEFAULT_SETTER = ->(carrier, key, value) { carrier[key] = value }
+        private_constant :DEFAULT_SETTER
+
+        # Returns a callable that can write a key into a carrier that implements
+        # +[]=+. Useful for inject operations.
+        #
+        # @return [Callable]
+        def default_setter
+          DEFAULT_SETTER
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+# Copyright 2020 OpenTelemetry Authors
+#
+# SPDX-License-Identifier: Apache-2.0
+
+module OpenTelemetry
+  class Context
+    module Propagation
+      # A no-op extractor implementation
+      class NoopExtractor
+        # Extract a context from the given carrier
+        #
+        # @param [Object] carrier The carrier to extract the context from
+        # @param [Context] context The context to be upated with the extracted
+        #   context
+        # @param [optional Callable] getter An optional callable that takes a carrier and a key and
+        #   and returns the value associated with the key
+        # @return [Context]
+        def extract(carrier, context, &getter)
+          context
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+# Copyright 2020 OpenTelemetry Authors
+#
+# SPDX-License-Identifier: Apache-2.0
+
+module OpenTelemetry
+  class Context
+    module Propagation
+      # A no-op injector implementation
+      class NoopInjector
+        # Inject the given context into the specified carrier
+        #
+        # @param [Object] carrier The carrier to inject the provided context
+        #   into
+        # @param [Context] context The context to be injected
+        # @param [optional Callable] setter An optional callable that takes a carrier and a key and
+        #   a value and assigns the key-value pair in the carrier
+        # @return [Object] carrier
+        def inject(carrier, context, &setter)
+          carrier
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+# Copyright 2019 OpenTelemetry Authors
+#
+# SPDX-License-Identifier: Apache-2.0
+
+module OpenTelemetry
+  class Context
+    module Propagation
+      # The Propagation class provides methods to inject and extract context
+      # to pass across process boundaries
+      class Propagation
+        # Get or set the global http propagator. Use a CompositePropagator
+        # to propagate multiple formats.
+        attr_accessor :http
+
+        # Get or set the global text propagator. Use a CompositePropagator
+        # to propagate multiple formats.
+        attr_accessor :text
+
+        def initialize
+          @http = @text = Propagator.new(NoopInjector.new, NoopExtractor.new)
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+# Copyright 2020 OpenTelemetry Authors
+#
+# SPDX-License-Identifier: Apache-2.0
+
+module OpenTelemetry
+  class Context
+    module Propagation
+      # A propagator composes an extractor and injector into a single interface
+      # exposing inject and extract methods
+      class Propagator
+        # Returns a Propagator that delegates inject and extract to the provided
+        # injector and extractor
+        #
+        # @param [#inject] injector
+        # @param [#extract] extractor
+        def initialize(injector, extractor)
+          @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.
+        #
+        # @param [Object] carrier A carrier to inject context into
+        #   context into
+        # @param [optional Context] context Context to be injected into carrier. Defaults
+        #   to +Context.current+
+        # @param [optional Callable] setter An optional callable that takes a carrier, a key and
+        #   a value and assigns the key-value pair in the carrier. If omitted the default setter
+        #   will be used which expects the carrier to respond to [] and []=.
+        #
+        # @return [Object] carrier
+        def inject(carrier, context = Context.current, &setter)
+          @injector.inject(carrier, context, &setter)
+        rescue => e # rubocop:disable Style/RescueStandardError
+          OpenTelemetry.logger.warn "Error in Propagator#inject #{e.message}"
+          carrier
+        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 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 []=.
+        #
+        # @return [Context] a new context updated with state extracted from the
+        #   carrier
+        def extract(carrier, context = Context.current, &getter)
+          @extractor.extract(carrier, context, &getter)
+        rescue => e # rubocop:disable Style/RescueStandardError
+          OpenTelemetry.logger.warn "Error in Propagator#extract #{e.message}"
+          context
+        end
+      end
+    end
+  end
+end

data/lib/opentelemetry/correlation_context.rb

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

data/lib/opentelemetry/correlation_context/builder.rb

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

data/lib/opentelemetry/correlation_context/manager.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+# Copyright 2019 OpenTelemetry Authors
+#
+# SPDX-License-Identifier: Apache-2.0
+
+module OpenTelemetry
+  module CorrelationContext
+    # No op implementation of CorrelationContext::Manager
+    class Manager
+      NOOP_BUILDER = Builder.new
+      private_constant :NOOP_BUILDER
+
+      def build(context: Context.current)
+        yield NOOP_BUILDER
+        context
+      end
+
+      def set_value(key, value, context: Context.current)
+        context
+      end
+
+      def value(key, context: Context.current)
+        nil
+      end
+
+      def remove_value(key, context: Context.current)
+        context
+      end
+
+      def clear(context: Context.current)
+        context
+      end
+    end
+  end
+end

data/lib/opentelemetry/correlation_context/propagation.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+# Copyright 2019 OpenTelemetry Authors
+#
+# SPDX-License-Identifier: Apache-2.0
+
+require 'opentelemetry/correlation_context/propagation/context_keys'
+require 'opentelemetry/correlation_context/propagation/text_injector'
+require 'opentelemetry/correlation_context/propagation/text_extractor'
+
+module OpenTelemetry
+  module CorrelationContext
+    # The Correlation::Propagation module contains injectors and
+    # extractors for sending and receiving correlation context over the wire
+    module Propagation
+      extend self
+
+      TEXT_EXTRACTOR = TextExtractor.new
+      TEXT_INJECTOR = TextInjector.new
+      RACK_EXTRACTOR = TextExtractor.new(
+        correlation_context_key: 'HTTP_CORRELATION_CONTEXT'
+      )
+      RACK_INJECTOR = TextInjector.new(
+        correlation_context_key: 'HTTP_CORRELATION_CONTEXT'
+      )
+
+      private_constant :TEXT_INJECTOR, :TEXT_EXTRACTOR, :RACK_INJECTOR,
+                       :RACK_EXTRACTOR
+
+      # Returns an extractor that extracts context using the W3C Correlation
+      # Context format
+      def text_injector
+        TEXT_INJECTOR
+      end
+
+      # Returns an injector that injects context using the W3C Correlation
+      # Context format
+      def text_extractor
+        TEXT_EXTRACTOR
+      end
+
+      # Returns an extractor that extracts context using the W3C Correlation
+      # Context 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 Correlation
+      # Context format with Rack normalized keys (upcased and prefixed with
+      # HTTP_)
+      def rack_extractor
+        RACK_EXTRACTOR
+      end
+    end
+  end
+end

data/lib/opentelemetry/correlation_context/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 CorrelationContext
+    module Propagation
+      # The ContextKeys module contains the keys used to index correlations
+      # in a {Context} instance
+      module ContextKeys
+        extend self
+
+        CORRELATION_CONTEXT_KEY = Context.create_key('correlation-context')
+        private_constant :CORRELATION_CONTEXT_KEY
+
+        # Returns the context key that correlations are indexed by
+        #
+        # @return [Context::Key]
+        def correlation_context_key
+          CORRELATION_CONTEXT_KEY
+        end
+      end
+    end
+  end
+end

data/lib/opentelemetry/correlation_context/propagation/text_extractor.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+# Copyright 2019 OpenTelemetry Authors
+#
+# SPDX-License-Identifier: Apache-2.0
+
+require 'cgi'
+
+module OpenTelemetry
+  module CorrelationContext
+    module Propagation
+      # Extracts correlations from carriers in the W3C Correlation Context format
+      class TextExtractor
+        include Context::Propagation::DefaultGetter
+
+        # Returns a new TextExtractor that extracts context using the specified
+        # header key
+        #
+        # @param [String] correlation_context_key The correlation context header
+        #   key used in the carrier
+        # @return [TextExtractor]
+        def initialize(correlation_context_key: 'Correlation-Context')
+          @correlation_context_key = correlation_context_key
+        end
+
+        # Extract remote correlations 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 [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
+        #   if extraction fails
+        def extract(carrier, context, &getter)
+          getter ||= default_getter
+          header = getter.call(carrier, @correlation_context_key)
+
+          entries = header.gsub(/\s/, '').split(',')
+
+          correlations = 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
+            kv, = entry.split(';', 2)
+            k, v = kv.split('=').map!(&CGI.method(:unescape))
+            memo[k] = v
+          end
+
+          context.set_value(ContextKeys.correlation_context_key, correlations)
+        rescue StandardError
+          context
+        end
+      end
+    end
+  end
+end

data/lib/opentelemetry/correlation_context/propagation/text_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 CorrelationContext
+    module Propagation
+      # Injects correlation context using the W3C Correlation Context format
+      class TextInjector
+        include Context::Propagation::DefaultSetter
+
+        # Returns a new TextInjector that injects context using the specified
+        # header key
+        #
+        # @param [String] correlation_context_header_key The correlation context header
+        #   key used in the carrier
+        # @return [TextInjector]
+        def initialize(correlation_context_key: 'Correlation-Context')
+          @correlation_context_key = correlation_context_key
+        end
+
+        # Inject in-process correlations into the supplied carrier.
+        #
+        # @param [Carrier] carrier The carrier to inject correlations into
+        # @param [Context] context The context to read correlations 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 correlations
+        def inject(carrier, context, &setter)
+          return carrier unless (correlations = context[ContextKeys.correlation_context_key]) && !correlations.empty?
+
+          setter ||= default_setter
+          setter.call(carrier, @correlation_context_key, encode(correlations))
+
+          carrier
+        end
+
+        private
+
+        def encode(correlations)
+          correlations.inject(+'') do |memo, (k, v)|
+            memo << CGI.escape(k.to_s) << '=' << CGI.escape(v.to_s) << ','
+          end.chop!
+        end
+      end
+    end
+  end
+end