opentelemetry-api 0.2.0 → 0.6.0

data/lib/opentelemetry/metrics/meter.rb

@@ -8,46 +8,9 @@ module OpenTelemetry
   module Metrics
     # No-op implementation of Meter.
     class Meter
-      NOOP_LABEL_SET = Object.new
-      private_constant(:NOOP_LABEL_SET)
+      def record_batch(*measurements, labels: nil); end
 
-      def record_batch(*measurements, label_set: nil); end
-
-      # Canonicalizes labels, returning an opaque {LabelSet} object.
-      #
-      # @param [Hash<String, String>] labels
-      # @return [LabelSet]
-      def labels(labels)
-        NOOP_LABEL_SET
-      end
-
-      # Create and return a floating point gauge.
-      #
-      # @param [String] name Name of the metric. See {Meter} for required metric name syntax.
-      # @param [optional String] description Descriptive text documenting the instrument.
-      # @param [optional String] unit Unit specified according to http://unitsofmeasure.org/ucum.html.
-      # @param [optional Enumerable<String>] recommended_label_keys Recommended grouping keys for this instrument.
-      # @param [optional Boolean] monotonic Whether the gauge accepts only monotonic updates. Defaults to false.
-      # @return [FloatGauge]
-      def create_float_gauge(name, description: nil, unit: nil, recommended_label_keys: nil, monotonic: false)
-        raise ArgumentError if name.nil?
-
-        Instruments::FloatGauge.new
-      end
-
-      # Create and return an integer gauge.
-      #
-      # @param [String] name Name of the metric. See {Meter} for required metric name syntax.
-      # @param [optional String] description Descriptive text documenting the instrument.
-      # @param [optional String] unit Unit specified according to http://unitsofmeasure.org/ucum.html.
-      # @param [optional Enumerable<String>] recommended_label_keys Recommended grouping keys for this instrument.
-      # @param [optional Boolean] monotonic Whether the gauge accepts only monotonic updates. Defaults to false.
-      # @return [IntegerGauge]
-      def create_integer_gauge(name, description: nil, unit: nil, recommended_label_keys: nil, monotonic: false)
-        raise ArgumentError if name.nil?
-
-        Instruments::IntegerGauge.new
-      end
+      # TODO: Observers.
 
       # Create and return a floating point counter.
       #

data/lib/opentelemetry/metrics/{meter_factory.rb → meter_provider.rb}

@@ -6,8 +6,8 @@
 
 module OpenTelemetry
   module Metrics
-    # No-op implementation of a meter factory.
-    class MeterFactory
+    # No-op implementation of a meter provider.
+    class MeterProvider
       # Returns a {Meter} instance.
       #
       # @param [optional String] name Instrumentation package name

data/lib/opentelemetry/trace.rb

@@ -9,45 +9,42 @@ module OpenTelemetry
   # single logical operation, consolidated across various components of an
   # application.
   module Trace
-    # An invalid trace identifier, a 16-byte array with all zero bytes, encoded
-    # as a hexadecimal string.
-    INVALID_TRACE_ID = ('0' * 32).freeze
+    # An invalid trace identifier, a 16-byte string with all zero bytes.
+    INVALID_TRACE_ID = ("\0" * 16).b
 
-    # An invalid span identifier, an 8-byte array with all zero bytes, encoded
-    # as a hexadecimal string.
-    INVALID_SPAN_ID = ('0' * 16).freeze
+    # An invalid span identifier, an 8-byte string with all zero bytes.
+    INVALID_SPAN_ID = ("\0" * 8).b
 
-    # Generates a valid trace identifier, a 16-byte array with at least one
-    # non-zero byte, encoded as a hexadecimal string.
+    # Generates a valid trace identifier, a 16-byte string with at least one
+    # non-zero byte.
     #
-    # @return [String] a hexadecimal string encoding of a valid trace ID.
+    # @return [String] a valid trace ID.
     def self.generate_trace_id
       loop do
-        id = Random::DEFAULT.bytes(16).unpack1('H*')
+        id = Random::DEFAULT.bytes(16)
         return id unless id == INVALID_TRACE_ID
       end
     end
 
-    # Generates a valid span identifier, an 8-byte array with at least one
-    # non-zero byte, encoded as a hexadecimal string.
+    # Generates a valid span identifier, an 8-byte string with at least one
+    # non-zero byte.
     #
-    # @return [String] a hexadecimal string encoding of a valid span ID.
+    # @return [String] a valid span ID.
     def self.generate_span_id
       loop do
-        id = Random::DEFAULT.bytes(8).unpack1('H*')
+        id = Random::DEFAULT.bytes(8)
         return id unless id == INVALID_SPAN_ID
       end
     end
   end
 end
 
-require 'opentelemetry/trace/event'
 require 'opentelemetry/trace/link'
 require 'opentelemetry/trace/trace_flags'
 require 'opentelemetry/trace/span_context'
 require 'opentelemetry/trace/span_kind'
 require 'opentelemetry/trace/span'
-require 'opentelemetry/trace/sampling_hint'
 require 'opentelemetry/trace/status'
+require 'opentelemetry/trace/propagation'
 require 'opentelemetry/trace/tracer'
-require 'opentelemetry/trace/tracer_factory'
+require 'opentelemetry/trace/tracer_provider'

data/lib/opentelemetry/trace/link.rb

@@ -22,14 +22,15 @@ module OpenTelemetry
 
       # Returns the frozen attributes for this link.
       #
-      # @return [Hash<String, Object>]
+      # @return [Hash{String => String, Numeric, Boolean, Array<String, Numeric, Boolean>}]
       attr_reader :attributes
 
       # Returns a new immutable {Link}.
       #
       # @param [SpanContext] span_context The context of the linked {Span}.
-      # @param [optional Hash<String, Object>] attributes A hash of attributes for
-      #   this link. Attributes will be frozen during Link initialization.
+      # @param [optional Hash{String => String, Numeric, Boolean, Array<String, Numeric, Boolean>}]
+      #   attributes A hash of attributes for this link. Attributes will be
+      #   frozen during Link initialization.
       # @return [Link]
       def initialize(span_context, attributes = nil)
         @context = span_context

data/lib/opentelemetry/trace/propagation.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+# Copyright 2019 OpenTelemetry Authors
+#
+# SPDX-License-Identifier: Apache-2.0
+
+require 'opentelemetry/trace/propagation/context_keys'
+require 'opentelemetry/trace/propagation/trace_context'
+
+module OpenTelemetry
+  module Trace
+    # The Trace::Propagation module contains injectors and extractors for
+    # sending and receiving span context over the wire
+    module Propagation
+    end
+  end
+end

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

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+# Copyright 2019 OpenTelemetry Authors
+#
+# SPDX-License-Identifier: Apache-2.0
+
+module OpenTelemetry
+  module Trace
+    module Propagation
+      # Contains the keys used to index the current span, or extracted span
+      # context in a {Context} instance
+      module ContextKeys
+        extend self
+
+        EXTRACTED_SPAN_CONTEXT_KEY = Context.create_key('extracted-span-context')
+        CURRENT_SPAN_KEY = Context.create_key('current-span')
+        private_constant :EXTRACTED_SPAN_CONTEXT_KEY, :CURRENT_SPAN_KEY
+
+        # Returns the context key that an extracted span context is indexed by
+        #
+        # @return [Context::Key]
+        def extracted_span_context_key
+          EXTRACTED_SPAN_CONTEXT_KEY
+        end
+
+        # Returns the context key that the current span is indexed by
+        #
+        # @return [Context::Key]
+        def current_span_key
+          CURRENT_SPAN_KEY
+        end
+      end
+    end
+  end
+end

data/lib/opentelemetry/trace/propagation/trace_context.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+# Copyright 2020 OpenTelemetry Authors
+#
+# SPDX-License-Identifier: Apache-2.0
+
+require 'opentelemetry/trace/propagation/trace_context/trace_parent'
+require 'opentelemetry/trace/propagation/trace_context/text_map_extractor'
+require 'opentelemetry/trace/propagation/trace_context/text_map_injector'
+
+module OpenTelemetry
+  module Trace
+    module Propagation
+      # The TraceContext module contains injectors, extractors, and utilties
+      # for context propagation in the W3C Trace Context format.
+      module TraceContext
+        extend self
+
+        TEXT_MAP_EXTRACTOR = TextMapExtractor.new
+        TEXT_MAP_INJECTOR = TextMapInjector.new
+        RACK_EXTRACTOR = TextMapExtractor.new(
+          traceparent_key: 'HTTP_TRACEPARENT',
+          tracestate_key: 'HTTP_TRACESTATE'
+        )
+        RACK_INJECTOR = TextMapInjector.new(
+          traceparent_key: 'HTTP_TRACEPARENT',
+          tracestate_key: 'HTTP_TRACESTATE'
+        )
+
+        private_constant :TEXT_MAP_INJECTOR, :TEXT_MAP_EXTRACTOR,
+                         :RACK_INJECTOR, :RACK_EXTRACTOR
+
+        # Returns an extractor that extracts context using the W3C Trace Context
+        # format
+        def text_map_extractor
+          TEXT_MAP_EXTRACTOR
+        end
+
+        # Returns an injector that injects context using the W3C Trace Context
+        # format
+        def text_map_injector
+          TEXT_MAP_INJECTOR
+        end
+
+        # Returns an extractor that extracts context using the W3C Trace Context
+        # with Rack normalized keys (upcased and prefixed with HTTP_)
+        def rack_extractor
+          RACK_EXTRACTOR
+        end
+
+        # Returns an injector that injects context using the W3C Trace Context
+        # format with Rack normalized keys (upcased and prefixed with HTTP_)
+        def rack_injector
+          RACK_INJECTOR
+        end
+      end
+    end
+  end
+end

data/lib/opentelemetry/trace/propagation/trace_context/text_map_extractor.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+# Copyright 2020 OpenTelemetry Authors
+#
+# SPDX-License-Identifier: Apache-2.0
+module OpenTelemetry
+  module Trace
+    module Propagation
+      module TraceContext
+        # Extracts context from carriers in the W3C Trace Context format
+        class TextMapExtractor
+          include Context::Propagation::DefaultGetter
+
+          # Returns a new TextMapExtractor that extracts context using the
+          # specified header keys
+          #
+          # @param [String] traceparent_key The traceparent header key used in the carrier
+          # @param [String] tracestate_key The tracestate header key used in the carrier
+          # @return [TextMapExtractor]
+          def initialize(traceparent_key: 'traceparent',
+                         tracestate_key: 'tracestate')
+            @traceparent_key = traceparent_key
+            @tracestate_key = tracestate_key
+          end
+
+          # Extract a remote {Trace::SpanContext} from the supplied carrier.
+          # Invalid headers will result in a new, valid, non-remote {Trace::SpanContext}.
+          #
+          # @param [Carrier] carrier The carrier to get the header from.
+          # @param [Context] context The context to be updated with extracted context
+          # @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] Updated context with span context from the header, or the original
+          #   context if parsing fails.
+          def extract(carrier, context, &getter)
+            getter ||= default_getter
+            header = getter.call(carrier, @traceparent_key)
+            tp = TraceParent.from_string(header)
+
+            tracestate = getter.call(carrier, @tracestate_key)
+
+            span_context = Trace::SpanContext.new(trace_id: tp.trace_id,
+                                                  span_id: tp.span_id,
+                                                  trace_flags: tp.flags,
+                                                  tracestate: tracestate,
+                                                  remote: true)
+            context.set_value(ContextKeys.extracted_span_context_key, span_context)
+          rescue OpenTelemetry::Error
+            context
+          end
+        end
+      end
+    end
+  end
+end

data/lib/opentelemetry/trace/propagation/trace_context/text_map_injector.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+# Copyright 2020 OpenTelemetry Authors
+#
+# SPDX-License-Identifier: Apache-2.0
+module OpenTelemetry
+  module Trace
+    module Propagation
+      module TraceContext
+        # Injects context into carriers using the W3C Trace Context format
+        class TextMapInjector
+          include Context::Propagation::DefaultSetter
+
+          # Returns a new TextMapInjector that injects context using the
+          # specified header keys
+          #
+          # @param [String] traceparent_key The traceparent header key used in the carrier
+          # @param [String] tracestate_key The tracestate header key used in the carrier
+          # @return [TextMapInjector]
+          def initialize(traceparent_key: 'traceparent',
+                         tracestate_key: 'tracestate')
+            @traceparent_key = traceparent_key
+            @tracestate_key = tracestate_key
+          end
+
+          # Set the span context on the supplied carrier.
+          #
+          # @param [Context] context The active {Context}.
+          # @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. If omitted the default setter
+          #   will be used which expects the carrier to respond to [] and []=.
+          # @yield [Carrier, String, String] if an optional setter is provided, inject will yield
+          #   carrier, header key, header value to the setter.
+          # @return [Object] the carrier with context injected
+          def inject(carrier, context, &setter)
+            return carrier unless (span_context = span_context_from(context))
+
+            setter ||= DEFAULT_SETTER
+            setter.call(carrier, @traceparent_key, TraceParent.from_context(span_context).to_s)
+            setter.call(carrier, @tracestate_key, span_context.tracestate) unless span_context.tracestate.nil?
+
+            carrier
+          end
+
+          private
+
+          def span_context_from(context)
+            context[ContextKeys.current_span_key]&.context ||
+              context[ContextKeys.extracted_span_context_key]
+          end
+        end
+      end
+    end
+  end
+end

data/lib/opentelemetry/trace/propagation/trace_context/trace_parent.rb

@@ -0,0 +1,130 @@
+# frozen_string_literal: true
+
+# Copyright 2020 OpenTelemetry Authors
+#
+# SPDX-License-Identifier: Apache-2.0
+module OpenTelemetry
+  module Trace
+    module Propagation
+      module TraceContext
+        # A TraceParent is an implementation of the W3C trace context specification
+        # https://www.w3.org/TR/trace-context/
+        # {Trace::SpanContext}
+        class TraceParent
+          InvalidFormatError = Class.new(Error)
+          InvalidVersionError = Class.new(Error)
+          InvalidTraceIDError = Class.new(Error)
+          InvalidSpanIDError = Class.new(Error)
+
+          TRACE_PARENT_HEADER = 'traceparent'
+          SUPPORTED_VERSION = 0
+          private_constant :SUPPORTED_VERSION
+          MAX_VERSION = 254
+          private_constant :MAX_VERSION
+
+          REGEXP = /^(?<version>[A-Fa-f0-9]{2})-(?<trace_id>[A-Fa-f0-9]{32})-(?<span_id>[A-Fa-f0-9]{16})-(?<flags>[A-Fa-f0-9]{2})(?<ignored>-.*)?$/.freeze
+          private_constant :REGEXP
+
+          INVALID_TRACE_ID = OpenTelemetry::Trace::SpanContext::INVALID.hex_trace_id
+          INVALID_SPAN_ID = OpenTelemetry::Trace::SpanContext::INVALID.hex_span_id
+          private_constant :INVALID_TRACE_ID, :INVALID_SPAN_ID
+
+          class << self
+            # Creates a new {TraceParent} from a supplied {Trace::SpanContext}
+            # @param [SpanContext] ctx The context
+            # @return [TraceParent] a trace parent
+            def from_context(ctx)
+              new(trace_id: ctx.trace_id, span_id: ctx.span_id, flags: ctx.trace_flags)
+            end
+
+            # Deserializes the {TraceParent} from the string representation
+            # @param [String] string The serialized trace parent
+            # @return [TraceParent] a trace_parent
+            # @raise [InvalidFormatError] on an invalid format
+            # @raise [InvalidVerionError] on an invalid version
+            # @raise [InvalidTraceIDError] on an invalid trace_id
+            # @raise [InvalidSpanIDError] on an invalid span_id
+            def from_string(string)
+              matches = match_input(string)
+
+              version = parse_version(matches[:version])
+              raise InvalidFormatError if version > SUPPORTED_VERSION && string.length < 55
+
+              trace_id = parse_trace_id(matches[:trace_id])
+              span_id = parse_span_id(matches[:span_id])
+              flags = parse_flags(matches[:flags])
+
+              new(trace_id: trace_id, span_id: span_id, flags: flags)
+            end
+
+            private
+
+            def match_input(string)
+              matches = REGEXP.match(string)
+              raise InvalidFormatError, 'regexp match failed' if !matches || matches.length < 6
+
+              matches
+            end
+
+            def parse_version(string)
+              v = string.to_i(16)
+              raise InvalidFormatError, string unless v
+              raise InvalidVersionError, v if v > MAX_VERSION
+
+              v
+            end
+
+            def parse_trace_id(string)
+              raise InvalidTraceIDError, string if string == INVALID_TRACE_ID
+
+              string.downcase!
+              Array(string).pack('H*')
+            end
+
+            def parse_span_id(string)
+              raise InvalidSpanIDError, string if string == INVALID_SPAN_ID
+
+              string.downcase!
+              Array(string).pack('H*')
+            end
+
+            def parse_flags(string)
+              OpenTelemetry::Trace::TraceFlags.from_byte(string.to_i(16))
+            end
+          end
+
+          attr_reader :version, :trace_id, :span_id, :flags
+
+          private_class_method :new
+
+          # Returns the sampling choice from the trace_flags
+          # @return [Boolean] the sampling choice
+          def sampled?
+            flags.sampled?
+          end
+
+          # converts this object into a string according to the w3c spec
+          # @return [String] the serialized trace_parent
+          def to_s
+            "00-#{trace_id.unpack1('H*')}-#{span_id.unpack1('H*')}-#{flag_string}"
+          end
+
+          private
+
+          def flag_string
+            # the w3c standard only dictates the one flag for this version
+            # therefore we can only output the one flag.
+            flags.sampled? ? '01' : '00'
+          end
+
+          def initialize(trace_id: nil, span_id: nil, version: SUPPORTED_VERSION, flags: Trace::TraceFlags::DEFAULT)
+            @trace_id = trace_id
+            @span_id = span_id
+            @version = version
+            @flags = flags
+          end
+        end
+      end
+    end
+  end
+end