opentelemetry-api 0.5.1

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_extractor'
+require 'opentelemetry/trace/propagation/trace_context/text_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_EXTRACTOR = TextExtractor.new
+        TEXT_INJECTOR = TextInjector.new
+        RACK_EXTRACTOR = TextExtractor.new(
+          traceparent_key: 'HTTP_TRACEPARENT',
+          tracestate_key: 'HTTP_TRACESTATE'
+        )
+        RACK_INJECTOR = TextInjector.new(
+          traceparent_key: 'HTTP_TRACEPARENT',
+          tracestate_key: 'HTTP_TRACESTATE'
+        )
+
+        private_constant :TEXT_INJECTOR, :TEXT_EXTRACTOR,
+                         :RACK_INJECTOR, :RACK_EXTRACTOR
+
+        # Returns an extractor that extracts context using the W3C Trace Context
+        # format
+        def text_extractor
+          TEXT_EXTRACTOR
+        end
+
+        # Returns an injector that injects context using the W3C Trace Context
+        # format
+        def text_injector
+          TEXT_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_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 TextExtractor
+          include Context::Propagation::DefaultGetter
+
+          # Returns a new TextExtractor 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 [TextExtractor]
+          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_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 TextInjector
+          include Context::Propagation::DefaultSetter
+
+          # Returns a new TextInjector 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 [TextInjector]
+          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::INVALID_TRACE_ID.unpack1('H*')
+          INVALID_SPAN_ID = OpenTelemetry::Trace::INVALID_SPAN_ID.unpack1('H*')
+          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

data/lib/opentelemetry/trace/span.rb

@@ -0,0 +1,145 @@
+# 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/specification/data-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/specification/data-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 => String, Numeric, Boolean, Array<String, Numeric, Boolean>}]
+      #   attributes One or more key:value pairs, where the keys must be
+      #   strings and the values may be (array of) 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
+
+      # Record an error during the execution of this span. Multiple errors
+      # can be recorded on a span.
+      #
+      # @param [Exception] error The error to recorded
+      #
+      # @return [void]
+      def record_error(error); 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