opentelemetry-api 0.5.1

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_provider'
+
+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,44 @@
+# 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 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 labels more than
+    # once, obtaining an instrument handle corresponding to the labels
+    # ensures the highest performance available.
+    #
+    # To obtain a handle given an instrument and labels, use the  #handle
+    # method to return an interface that supports the #add or #record
+    # method of the instrument in question.
+    #
+    # Instrument handles may consume SDK resources indefinitely.
+    module Handles
+      # 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,105 @@
+# 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, Observers, and Measures.
+    module Instruments
+      # TODO: Observers.
+
+      # A float counter instrument.
+      class FloatCounter
+        def add(value, labels = {}); end
+
+        # Obtain a handle from the instrument and labels.
+        #
+        # @param [optional Hash<String, String>] labels A Hash of Strings.
+        # @return [Handles::FloatCounter]
+        def handle(labels = {})
+          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 = {}); end
+
+        # Obtain a handle from the instrument and labels.
+        #
+        # @param [optional Hash<String, String>] labels A Hash of Strings.
+        # @return [Handles::IntegerCounter]
+        def handle(labels = {})
+          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 = {}); end
+
+        # Obtain a handle from the instrument and labels.
+        #
+        # @param [optional Hash<String, String>] labels A Hash of Strings.
+        # @return [Handles::FloatMeasure]
+        def handle(labels = {})
+          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 = {}); end
+
+        # Obtain a handle from the instrument and labels.
+        #
+        # @param [optional Hash<String, String>] labels A Hash of Strings.
+        # @return [Handles::IntegerMeasure]
+        def handle(labels = {})
+          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

data/lib/opentelemetry/metrics/meter.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+# Copyright 2019 OpenTelemetry Authors
+#
+# SPDX-License-Identifier: Apache-2.0
+
+module OpenTelemetry
+  module Metrics
+    # No-op implementation of Meter.
+    class Meter
+      def record_batch(*measurements, labels: nil); end
+
+      # TODO: Observers.
+
+      # Create and return a floating point counter.
+      #
+      # @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 counter accepts only monotonic updates. Defaults to true.
+      # @return [FloatCounter]
+      def create_float_counter(name, description: nil, unit: nil, recommended_label_keys: nil, monotonic: true)
+        raise ArgumentError if name.nil?
+
+        Instruments::FloatCounter.new
+      end
+
+      # Create and return an integer counter.
+      #
+      # @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 counter accepts only monotonic updates. Defaults to true.
+      # @return [IntegerCounter]
+      def create_integer_counter(name, description: nil, unit: nil, recommended_label_keys: nil, monotonic: true)
+        raise ArgumentError if name.nil?
+
+        Instruments::IntegerCounter.new
+      end
+
+      # Create and return a floating point measure.
+      #
+      # @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] absolute Whether the measure accepts only non-negative updates. Defaults to true.
+      # @return [FloatMeasure]
+      def create_float_measure(name, description: nil, unit: nil, recommended_label_keys: nil, absolute: true)
+        raise ArgumentError if name.nil?
+
+        Instruments::FloatMeasure.new
+      end
+
+      # Create and return an integer measure.
+      #
+      # @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] absolute Whether the measure accepts only non-negative updates. Defaults to true.
+      # @return [IntegerMeasure]
+      def create_integer_measure(name, description: nil, unit: nil, recommended_label_keys: nil, absolute: true)
+        raise ArgumentError if name.nil?
+
+        Instruments::IntegerMeasure.new
+      end
+    end
+  end
+end

data/lib/opentelemetry/metrics/meter_provider.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+# Copyright 2019 OpenTelemetry Authors
+#
+# SPDX-License-Identifier: Apache-2.0
+
+module OpenTelemetry
+  module Metrics
+    # No-op implementation of a meter provider.
+    class MeterProvider
+      # Returns a {Meter} instance.
+      #
+      # @param [optional String] name Instrumentation package name
+      # @param [optional String] version Instrumentation package version
+      #
+      # @return [Meter]
+      def meter(name = nil, version = nil)
+        @meter ||= Meter.new
+      end
+    end
+  end
+end

data/lib/opentelemetry/trace.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+# Copyright 2019 OpenTelemetry Authors
+#
+# SPDX-License-Identifier: Apache-2.0
+
+module OpenTelemetry
+  # The Trace API allows recording a set of events, triggered as a result of a
+  # single logical operation, consolidated across various components of an
+  # application.
+  module Trace
+    # 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 string with all zero bytes.
+    INVALID_SPAN_ID = ("\0" * 8).b
+
+    # Generates a valid trace identifier, a 16-byte string with at least one
+    # non-zero byte.
+    #
+    # @return [String] a valid trace ID.
+    def self.generate_trace_id
+      loop do
+        id = Random::DEFAULT.bytes(16)
+        return id unless id == INVALID_TRACE_ID
+      end
+    end
+
+    # Generates a valid span identifier, an 8-byte string with at least one
+    # non-zero byte.
+    #
+    # @return [String] a valid span ID.
+    def self.generate_span_id
+      loop do
+        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/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/tracer'
+require 'opentelemetry/trace/tracer_provider'

data/lib/opentelemetry/trace/event.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+# Copyright 2019 OpenTelemetry Authors
+#
+# SPDX-License-Identifier: Apache-2.0
+
+module OpenTelemetry
+  module Trace
+    # A text annotation with a set of attributes and a timestamp.
+    class Event
+      EMPTY_ATTRIBUTES = {}.freeze
+
+      private_constant :EMPTY_ATTRIBUTES
+
+      # Returns the name of this event
+      #
+      # @return [String]
+      attr_reader :name
+
+      # Returns the frozen attributes for this event
+      #
+      # @return [Hash{String => String, Numeric, Boolean, Array<String, Numeric, Boolean>}]
+      attr_reader :attributes
+
+      # Returns the timestamp for this event
+      #
+      # @return [Time]
+      attr_reader :timestamp
+
+      # Returns a new immutable {Event}.
+      #
+      # @param [String] name The name of this event
+      # @param [optional Hash{String => String, Numeric, Boolean, Array<String, Numeric, Boolean>}]
+      #   attributes A hash of attributes for this event. Attributes will be
+      #   frozen during Event initialization.
+      # @param [optional Time] timestamp The timestamp for this event.
+      #   Defaults to Time.now.
+      # @return [Event]
+      def initialize(name:, attributes: nil, timestamp: nil)
+        @name = name
+        @attributes = attributes.freeze || EMPTY_ATTRIBUTES
+        @timestamp = timestamp || Time.now
+      end
+    end
+  end
+end

data/lib/opentelemetry/trace/link.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+# Copyright 2019 OpenTelemetry Authors
+#
+# SPDX-License-Identifier: Apache-2.0
+
+module OpenTelemetry
+  module Trace
+    # A link to a {Span}. Used (for example) in batching operations, where a
+    # single batch handler processes multiple requests from different traces.
+    # A Link can be also used to reference spans from the same trace. A Link
+    # and its attributes are immutable.
+    class Link
+      EMPTY_ATTRIBUTES = {}.freeze
+
+      private_constant :EMPTY_ATTRIBUTES
+
+      # Returns the {SpanContext} for this link
+      #
+      # @return [SpanContext]
+      attr_reader :context
+
+      # Returns the frozen attributes for this link.
+      #
+      # @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 => 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
+        @attributes = attributes.freeze || EMPTY_ATTRIBUTES
+      end
+
+      # Returns true if two {Link}s are equal.
+      def ==(other)
+        other.context == @context && other.attributes == @attributes
+      end
+    end
+  end
+end

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