opentelemetry-api 0.2.0

data/lib/opentelemetry/distributed_context/propagation/text_format.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+# Copyright 2019 OpenTelemetry Authors
+#
+# SPDX-License-Identifier: Apache-2.0
+module OpenTelemetry
+  module DistributedContext
+    module Propagation
+      # TextFormat is a formatter that injects and extracts a value as text into carriers that travel in-band across
+      # process boundaries.
+      # Encoding is expected to conform to the HTTP Header Field semantics. Values are often encoded as RPC/HTTP request
+      # headers.
+      #
+      # The carrier of propagated data on both the client (injector) and server (extractor) side is usually an http request.
+      # Propagation is usually implemented via library-specific request interceptors, where the client-side injects values
+      # and the server-side extracts them.
+      class TextFormat
+        DEFAULT_GETTER = ->(carrier, key) { carrier[key] }
+        DEFAULT_SETTER = ->(carrier, key, value) { carrier[key] = value }
+        private_constant(:DEFAULT_GETTER, :DEFAULT_SETTER)
+
+        # Returns an array with the trace context header keys used by this formatter
+        attr_reader :fields
+
+        # Returns a new TextFormat that injects and extracts using the specified trace context
+        # header keys
+        #
+        # @param [String] traceparent_header_key The traceparent header key used in the carrier
+        # @param [String] tracestate_header_key The tracestate header key used in the carrier
+        # @return [TextFormatter]
+        def initialize(traceparent_header_key:, tracestate_header_key:)
+          @traceparent_header_key = traceparent_header_key
+          @tracestate_header_key = tracestate_header_key
+          @fields = [traceparent_header_key, tracestate_header_key].freeze
+        end
+
+        # Return a remote {Trace::SpanContext} extracted from the supplied carrier. Expects the
+        # the supplied carrier to have keys in rack normalized format (HTTP_#{UPPERCASE_KEY}).
+        # Invalid headers will result in a new, valid, non-remote {Trace::SpanContext}.
+        #
+        # @param [Carrier] carrier The carrier to get the header 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, extract will yield the carrier
+        #   and the header key to the getter.
+        # @return [SpanContext] the span context from the header, or a new one if parsing fails.
+        def extract(carrier, &getter)
+          getter ||= DEFAULT_GETTER
+          header = getter.call(carrier, @traceparent_header_key)
+          tp = TraceParent.from_string(header)
+
+          tracestate = getter.call(carrier, @tracestate_header_key)
+
+          Trace::SpanContext.new(trace_id: tp.trace_id, span_id: tp.span_id, trace_flags: tp.flags, tracestate: tracestate, remote: true)
+        rescue OpenTelemetry::Error
+          Trace::SpanContext.new
+        end
+
+        # Set the span context on the supplied carrier.
+        #
+        # @param [SpanContext] context The active {Trace::SpanContext}.
+        # @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.
+        def inject(context, carrier, &setter)
+          setter ||= DEFAULT_SETTER
+          setter.call(carrier, @traceparent_header_key, TraceParent.from_context(context).to_s)
+          setter.call(carrier, @tracestate_header_key, context.tracestate) unless context.tracestate.nil?
+        end
+      end
+    end
+  end
+end

data/lib/opentelemetry/distributed_context/propagation/trace_parent.rb

@@ -0,0 +1,124 @@
+# frozen_string_literal: true
+
+# Copyright 2019 OpenTelemetry Authors
+#
+# SPDX-License-Identifier: Apache-2.0
+module OpenTelemetry
+  module DistributedContext
+    module Propagation
+      # 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
+
+        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 == OpenTelemetry::Trace::INVALID_TRACE_ID
+
+            string.downcase!
+            string
+          end
+
+          def parse_span_id(string)
+            raise InvalidSpanIDError, string if string == OpenTelemetry::Trace::INVALID_SPAN_ID
+
+            string.downcase!
+            string
+          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}-#{span_id}-#{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

data/lib/opentelemetry/error.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+# Copyright 2019 OpenTelemetry Authors
+#
+# SPDX-License-Identifier: Apache-2.0
+module OpenTelemetry
+  class Error < StandardError
+  end
+end

data/lib/opentelemetry/internal.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+# Copyright 2019 OpenTelemetry Authors
+#
+# SPDX-License-Identifier: Apache-2.0
+
+module OpenTelemetry
+  # @api private
+  #
+  # Internal contains helpers used by the no-op API implementation.
+  module Internal
+    extend self
+
+    def printable_ascii?(string)
+      return false unless string.is_a?(String)
+
+      r = 32..126
+      string.each_codepoint { |c| return false unless r.include?(c) }
+      true
+    end
+  end
+end

data/lib/opentelemetry/metrics.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+# Copyright 2019 OpenTelemetry Authors
+#
+# SPDX-License-Identifier: Apache-2.0
+
+require 'opentelemetry/metrics/handles'
+require 'opentelemetry/metrics/instruments'
+require 'opentelemetry/metrics/meter'
+require 'opentelemetry/metrics/meter_factory'
+
+module OpenTelemetry
+  # The Metrics API allows reporting raw measurements as well as metrics with known aggregation and labels.
+  module Metrics
+  end
+end

data/lib/opentelemetry/metrics/handles.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+# Copyright 2019 OpenTelemetry Authors
+#
+# SPDX-License-Identifier: Apache-2.0
+
+module OpenTelemetry
+  module Metrics
+    # In situations where performance is a requirement and a metric is
+    # repeatedly used with the same set of labels, the developer may elect to
+    # use instrument {Handles} as an optimization. For handles to be a benefit,
+    # it requires that a specific instrument will be re-used with specific
+    # labels. If an instrument will be used with the same label set more than
+    # once, obtaining an instrument handle corresponding to the label set
+    # ensures the highest performance available.
+    #
+    # To obtain a handle given an instrument and label set, use the  #handle
+    # method to return an interface that supports the #add, #set, or #record
+    # method of the instrument in question.
+    #
+    # Instrument handles may consume SDK resources indefinitely.
+    module Handles
+      # A float gauge handle.
+      class FloatGauge
+        def set(value); end
+      end
+
+      # An integer gauge handle.
+      class IntegerGauge
+        def set(value); end
+      end
+
+      # A float counter handle.
+      class FloatCounter
+        def add(value); end
+      end
+
+      # An integer counter handle.
+      class IntegerCounter
+        def add(value); end
+      end
+
+      # A float measure handle.
+      class FloatMeasure
+        def record(value); end
+      end
+
+      # An integer measure handle.
+      class IntegerMeasure
+        def record(value); end
+      end
+    end
+  end
+end

data/lib/opentelemetry/metrics/instruments.rb

@@ -0,0 +1,156 @@
+# frozen_string_literal: true
+
+# Copyright 2019 OpenTelemetry Authors
+#
+# SPDX-License-Identifier: Apache-2.0
+
+module OpenTelemetry
+  module Metrics
+    # The user-facing metrics API supports producing diagnostic measurements
+    # using three basic kinds of instrument. "Metrics" are the thing being
+    # produced -- mathematical, statistical summaries of certain observable
+    # behavior in the program. "Instruments" are the devices used by the
+    # program to record observations about their behavior. Therefore, we use
+    # "metric instrument" to refer to a program object, allocated through the
+    # API, used for recording metrics. There are three distinct instruments in
+    # the Metrics API, commonly known as Counters, Gauges, and Measures.
+    module Instruments
+      # A float gauge instrument.
+      class FloatGauge
+        # Set the value of the gauge.
+        #
+        # @param [Float] value The value to set.
+        # @param [optional LabelSet, Hash<String, String>] labels_or_label_set
+        #   A {LabelSet} returned from {Meter#labels} or a Hash of Strings.
+        def set(value, labels_or_label_set = {}); end
+
+        # Obtain a handle from the instrument and label set.
+        #
+        # @param [optional LabelSet, Hash<String, String>] labels_or_label_set
+        #   A {LabelSet} returned from {Meter#labels} or a Hash of Strings.
+        # @return [Handles::FloatGauge]
+        def handle(labels_or_label_set = {})
+          Handles::FloatGauge.new
+        end
+
+        # Return a measurement to be recorded via {Meter#record_batch}.
+        #
+        # @param [Float] value
+        # @return [Object, Measurement]
+        def measurement(value)
+          NOOP_MEASUREMENT
+        end
+      end
+
+      # An integer gauge instrument.
+      class IntegerGauge
+        def set(value, labels_or_label_set = {}); end
+
+        # Obtain a handle from the instrument and label set.
+        #
+        # @param [optional LabelSet, Hash<String, String>] labels_or_label_set
+        #   A {LabelSet} returned from {Meter#labels} or a Hash of Strings.
+        # @return [Handles::IntegerGauge]
+        def handle(labels_or_label_set = {})
+          Handles::IntegerGauge.new
+        end
+
+        # Return a measurement to be recorded via {Meter#record_batch}.
+        #
+        # @param [Integer] value
+        # @return [Object, Measurement]
+        def measurement(value)
+          NOOP_MEASUREMENT
+        end
+      end
+
+      # A float counter instrument.
+      class FloatCounter
+        def add(value, labels_or_label_set = {}); end
+
+        # Obtain a handle from the instrument and label set.
+        #
+        # @param [optional LabelSet, Hash<String, String>] labels_or_label_set
+        #   A {LabelSet} returned from {Meter#labels} or a Hash of Strings.
+        # @return [Handles::FloatCounter]
+        def handle(labels_or_label_set = {})
+          Handles::FloatCounter.new
+        end
+
+        # Return a measurement to be recorded via {Meter#record_batch}.
+        #
+        # @param [Float] value
+        # @return [Object, Measurement]
+        def measurement(value)
+          NOOP_MEASUREMENT
+        end
+      end
+
+      # An integer counter instrument.
+      class IntegerCounter
+        def add(value, labels_or_label_set = {}); end
+
+        # Obtain a handle from the instrument and label set.
+        #
+        # @param [optional LabelSet, Hash<String, String>] labels_or_label_set
+        #   A {LabelSet} returned from {Meter#labels} or a Hash of Strings.
+        # @return [Handles::IntegerCounter]
+        def handle(labels_or_label_set = {})
+          Handles::IntegerCounter.new
+        end
+
+        # Return a measurement to be recorded via {Meter#record_batch}.
+        #
+        # @param [Integer] value
+        # @return [Object, Measurement]
+        def measurement(value)
+          NOOP_MEASUREMENT
+        end
+      end
+
+      # A float measure instrument.
+      class FloatMeasure
+        def record(value, labels_or_label_set = {}); end
+
+        # Obtain a handle from the instrument and label set.
+        #
+        # @param [optional LabelSet, Hash<String, String>] labels_or_label_set
+        #   A {LabelSet} returned from {Meter#labels} or a Hash of Strings.
+        # @return [Handles::FloatMeasure]
+        def handle(labels_or_label_set = {})
+          Handles::FloatMeasure.new
+        end
+
+        # Return a measurement to be recorded via {Meter#record_batch}.
+        #
+        # @param [Float] value
+        # @return [Object, Measurement]
+        def measurement(value)
+          NOOP_MEASUREMENT
+        end
+      end
+
+      # An integer measure instrument.
+      class IntegerMeasure
+        def record(value, labels_or_label_set = {}); end
+
+        # Obtain a handle from the instrument and label set.
+        #
+        # @param [optional LabelSet, Hash<String, String>] labels_or_label_set
+        #   A {LabelSet} returned from {Meter#labels} or a Hash of Strings.
+        # @return [Handles::IntegerMeasure]
+        def handle(labels_or_label_set = {})
+          Handles::IntegerMeasure.new
+        end
+
+        # Return a measurement to be recorded via {Meter#record_batch}.
+        #
+        # @param [Integer] value
+        # @return [Object, Measurement]
+        def measurement(value)
+          NOOP_MEASUREMENT
+        end
+      end
+    end
+  end
+end