opentelemetry-api 0.2.0

data/lib/opentelemetry/metrics/meter.rb

@@ -0,0 +1,109 @@
+# 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
+      NOOP_LABEL_SET = Object.new
+      private_constant(:NOOP_LABEL_SET)
+
+      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
+
+      # 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_factory.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 factory.
+    class MeterFactory
+      # 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,53 @@
+# 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 array with all zero bytes, encoded
+    # as a hexadecimal string.
+    INVALID_TRACE_ID = ('0' * 32).freeze
+
+    # An invalid span identifier, an 8-byte array with all zero bytes, encoded
+    # as a hexadecimal string.
+    INVALID_SPAN_ID = ('0' * 16).freeze
+
+    # Generates a valid trace identifier, a 16-byte array with at least one
+    # non-zero byte, encoded as a hexadecimal string.
+    #
+    # @return [String] a hexadecimal string encoding of a valid trace ID.
+    def self.generate_trace_id
+      loop do
+        id = Random::DEFAULT.bytes(16).unpack1('H*')
+        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.
+    #
+    # @return [String] a hexadecimal string encoding of a valid span ID.
+    def self.generate_span_id
+      loop do
+        id = Random::DEFAULT.bytes(8).unpack1('H*')
+        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/tracer'
+require 'opentelemetry/trace/tracer_factory'

data/lib/opentelemetry/trace/event.rb

@@ -0,0 +1,45 @@
+# 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, Object>]
+      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, Object>] 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,45 @@
+# 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, Object>]
+      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.
+      # @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/sampling_hint.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+# Copyright 2019 OpenTelemetry Authors
+#
+# SPDX-License-Identifier: Apache-2.0
+
+module OpenTelemetry
+  module Trace
+    # Hints to influence sampling decisions. The default option for span
+    # creation is to not provide any suggestion.
+    module SamplingHint
+      # Suggest to not record events and not sample.
+      NOT_RECORD = :__not_record__
+
+      # Suggest to record events and not sample.
+      RECORD = :__record__
+
+      # Suggest to record events and sample.
+      RECORD_AND_SAMPLED = :__record_and_sampled__
+    end
+  end
+end

data/lib/opentelemetry/trace/span.rb

@@ -0,0 +1,137 @@
+# frozen_string_literal: true
+
+# Copyright 2019 OpenTelemetry Authors
+#
+# SPDX-License-Identifier: Apache-2.0
+
+module OpenTelemetry
+  module Trace
+    # Span represents a single operation within a trace. Spans can be nested to
+    # form a trace tree. Often, a trace contains a root span that describes the
+    # end-to-end latency and, optionally, one or more sub-spans for its
+    # sub-operations.
+    #
+    # Once Span {Tracer#start_span is created} - Span operations can be used to
+    # add additional properties to it like attributes, links, events, name and
+    # resulting status. Span cannot be used to retrieve these properties. This
+    # prevents the mis-use of spans as an in-process information propagation
+    # mechanism.
+    #
+    # {Span} must be ended by calling {#finish}.
+    class Span
+      # Retrieve the spans SpanContext
+      #
+      # The returned value may be used even after the Span is finished.
+      #
+      # @return [SpanContext]
+      attr_reader :context
+
+      # Spans must be created using {Tracer}. This is for internal use only.
+      #
+      # @api private
+      def initialize(span_context: nil)
+        @context = span_context || SpanContext.new
+      end
+
+      # Return whether this span is recording.
+      #
+      # @return [Boolean] true if this Span is active and recording information
+      #   like events with the #add_event operation and attributes using
+      #   #set_attribute.
+      def recording?
+        false
+      end
+
+      # Set attribute
+      #
+      # Note that the OpenTelemetry project
+      # {https://github.com/open-telemetry/opentelemetry-specification/blob/master/semantic-conventions.md
+      # documents} certain "standard attributes" that have prescribed semantic
+      # meanings.
+      #
+      # @param [String] key
+      # @param [String, Boolean, Numeric] value
+      #
+      # @return [self] returns itself
+      def set_attribute(key, value)
+        self
+      end
+      alias []= set_attribute
+
+      # Add an Event to a {Span}. This can be accomplished eagerly or lazily.
+      # Lazy evaluation is useful when the event attributes are expensive to
+      # build and where the cost can be avoided for an unsampled {Span}.
+      #
+      # Eager example:
+      #
+      #   span.add_event(name: 'event', attributes: {'eager' => true})
+      #
+      # Lazy example:
+      #
+      #   span.add_event { tracer.create_event(name: 'event', attributes: {'eager' => false}) }
+      #
+      # Note that the OpenTelemetry project
+      # {https://github.com/open-telemetry/opentelemetry-specification/blob/master/semantic-conventions.md
+      # documents} certain "standard event names and keys" which have
+      # prescribed semantic meanings.
+      #
+      # @param [optional String] name Optional name of the event. This is
+      #   required if a block is not given.
+      # @param [optional Hash<String, Object>] attributes One or more key:value
+      #   pairs, where the keys must be strings and the values may be string,
+      #   boolean or numeric type. This argument should only be used when
+      #   passing in a name.
+      # @param [optional Time] timestamp Optional timestamp for the event.
+      #   This argument should only be used when passing in a name.
+      #
+      # @return [self] returns itself
+      def add_event(name: nil, attributes: nil, timestamp: nil)
+        self
+      end
+
+      # Sets the Status to the Span
+      #
+      # If used, this will override the default Span status. Default is OK.
+      #
+      # Only the value of the last call will be recorded, and implementations
+      # are free to ignore previous calls.
+      #
+      # @param [Status] status The new status, which overrides the default Span
+      #   status, which is OK.
+      #
+      # @return [void]
+      def status=(status); end
+
+      # Updates the Span name
+      #
+      # Upon this update, any sampling behavior based on Span name will depend
+      # on the implementation.
+      #
+      # @param [String] new_name The new operation name, which supersedes
+      #   whatever was passed in when the Span was started
+      #
+      # @return [void]
+      def name=(new_name); end
+
+      # Finishes the Span
+      #
+      # Implementations MUST ignore all subsequent calls to {#finish} (there
+      # might be exceptions when Tracer is streaming event and has no mutable
+      # state associated with the Span).
+      #
+      # Call to {#finish} MUST not have any effects on child spans. Those may
+      # still be running and can be ended later.
+      #
+      # This API MUST be non-blocking.
+      #
+      # @param [Time] end_timestamp optional end timestamp for the span.
+      #
+      # @return [self] returns itself
+      def finish(end_timestamp: nil)
+        self
+      end
+
+      INVALID = new(span_context: SpanContext::INVALID)
+    end
+  end
+end

data/lib/opentelemetry/trace/span_context.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+# Copyright 2019 OpenTelemetry Authors
+#
+# SPDX-License-Identifier: Apache-2.0
+
+module OpenTelemetry
+  module Trace
+    # A SpanContext contains the state that must propagate to child {Span}s and across process boundaries.
+    # It contains the identifiers (a trace ID and span ID) associated with the {Span}, a set of
+    # {TraceFlags}, a system-specific tracestate, and a boolean indicating that the SpanContext was
+    # extracted from the wire.
+    class SpanContext
+      attr_reader :trace_id, :span_id, :trace_flags, :tracestate
+
+      # Returns a new {SpanContext}.
+      #
+      # @param [optional String] trace_id The trace ID associated with a {Span}.
+      # @param [optional String] span_id The span ID associated with a {Span}.
+      # @param [optional TraceFlags] trace_flags The trace flags associated with a {Span}.
+      # @param [optional String] tracestate The tracestate associated with a {Span}. May be nil.
+      # @param [optional Boolean] remote Whether the {SpanContext} was extracted from the wire.
+      # @return [SpanContext]
+      def initialize(
+        trace_id: Trace.generate_trace_id,
+        span_id: Trace.generate_span_id,
+        trace_flags: TraceFlags::DEFAULT,
+        tracestate: nil,
+        remote: false
+      )
+        @trace_id = trace_id
+        @span_id = span_id
+        @trace_flags = trace_flags
+        @tracestate = tracestate
+        @remote = remote
+      end
+
+      # Returns true if the {SpanContext} has a non-zero trace ID and non-zero span ID.
+      #
+      # @return [Boolean]
+      def valid?
+        @trace_id != INVALID_TRACE_ID && @span_id != INVALID_SPAN_ID
+      end
+
+      # Returns true if the {SpanContext} was propagated from a remote parent.
+      #
+      # @return [Boolean]
+      def remote?
+        @remote
+      end
+
+      # Represents an invalid {SpanContext}, with an invalid trace ID and an invalid span ID.
+      INVALID = new(trace_id: INVALID_TRACE_ID, span_id: INVALID_SPAN_ID)
+    end
+  end
+end