jaeger-client 0.7.1 → 1.1.0

data/lib/jaeger/span.rb

@@ -0,0 +1,97 @@
+# frozen_string_literal: true
+
+require_relative 'span/thrift_log_builder'
+
+module Jaeger
+  class Span
+    attr_accessor :operation_name
+
+    attr_reader :context, :start_time, :end_time, :references, :tags, :logs
+
+    # Creates a new {Span}
+    #
+    # @param context [SpanContext] the context of the span
+    # @param operation_name [String] the operation name
+    # @param reporter [#report] span reporter
+    #
+    # @return [Span] a new Span
+    def initialize(context, operation_name, reporter, start_time: Time.now, references: [], tags: {})
+      @context = context
+      @operation_name = operation_name
+      @reporter = reporter
+      @start_time = start_time
+      @references = references
+      @tags = []
+      @logs = []
+
+      tags.each { |key, value| set_tag(key, value) }
+    end
+
+    # Set a tag value on this span
+    #
+    # @param key [String] the key of the tag
+    # @param value [String, Numeric, Boolean] the value of the tag. If it's not
+    # a String, Numeric, or Boolean it will be encoded with to_s
+    def set_tag(key, value)
+      if key == 'sampling.priority'
+        if value.to_i > 0
+          return self if @context.debug?
+
+          @context.flags = @context.flags | SpanContext::Flags::SAMPLED | SpanContext::Flags::DEBUG
+        else
+          @context.flags = @context.flags & ~SpanContext::Flags::SAMPLED
+        end
+        return self
+      end
+
+      # Using Thrift::Tag to avoid unnecessary memory allocations
+      @tags << ThriftTagBuilder.build(key, value)
+
+      self
+    end
+
+    # Set a baggage item on the span
+    #
+    # @param key [String] the key of the baggage item
+    # @param value [String] the value of the baggage item
+    def set_baggage_item(key, value)
+      @context.set_baggage_item(key, value)
+      self
+    end
+
+    # Get a baggage item
+    #
+    # @param key [String] the key of the baggage item
+    #
+    # @return Value of the baggage item
+    def get_baggage_item(key)
+      @context.get_baggage_item(key)
+    end
+
+    # Add a log entry to this span
+    #
+    # @deprecated Use {#log_kv} instead.
+    def log(*args)
+      warn 'Span#log is deprecated. Please use Span#log_kv instead.'
+      log_kv(*args)
+    end
+
+    # Add a log entry to this span
+    #
+    # @param timestamp [Time] time of the log
+    # @param fields [Hash] Additional information to log
+    def log_kv(timestamp: Time.now, **fields)
+      # Using Thrift::Log to avoid unnecessary memory allocations
+      @logs << ThriftLogBuilder.build(timestamp, fields)
+      nil
+    end
+
+    # Finish the {Span}
+    #
+    # @param end_time [Time] custom end time, if not now
+    def finish(end_time: Time.now)
+      @end_time = end_time
+      @reporter.report(self)
+    end
+  end
+end

data/lib/jaeger/span/thrift_log_builder.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module Jaeger
+  class Span
+    class ThriftLogBuilder
+      FIELDS = Jaeger::Thrift::Log::FIELDS
+      TIMESTAMP = FIELDS[Jaeger::Thrift::Log::TIMESTAMP].fetch(:name)
+      LOG_FIELDS = FIELDS[Jaeger::Thrift::Log::LOG_FIELDS].fetch(:name)
+
+      def self.build(timestamp, fields)
+        Jaeger::Thrift::Log.new(
+          TIMESTAMP => (timestamp.to_f * 1_000_000).to_i,
+          LOG_FIELDS => fields.map { |key, value| ThriftTagBuilder.build(key, value) }
+        )
+      end
+    end
+  end
+end

data/lib/jaeger/span_context.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+module Jaeger
+  # SpanContext holds the data for a span that gets inherited to child spans
+  class SpanContext
+    module Flags
+      NONE = 0x00
+      SAMPLED = 0x01
+      DEBUG = 0x02
+    end
+
+    def self.create_from_parent_context(span_context)
+      new(
+        trace_id: span_context.trace_id,
+        parent_id: span_context.span_id,
+        span_id: TraceId.generate,
+        flags: span_context.flags,
+        baggage: span_context.baggage.dup
+      )
+    end
+
+    attr_reader :span_id, :parent_id, :trace_id, :baggage, :flags
+    attr_writer :flags
+
+    def initialize(span_id:, parent_id: 0, trace_id:, flags:, baggage: {})
+      @span_id = span_id
+      @parent_id = parent_id
+      @trace_id = trace_id
+      @baggage = baggage
+      @flags = flags
+    end
+
+    def sampled?
+      @flags & Flags::SAMPLED == Flags::SAMPLED
+    end
+
+    def debug?
+      @flags & Flags::DEBUG == Flags::DEBUG
+    end
+
+    def to_trace_id
+      @to_trace_id ||= @trace_id.to_s(16)
+    end
+
+    def to_span_id
+      @to_span_id ||= @span_id.to_s(16)
+    end
+
+    def set_baggage_item(key, value)
+      @baggage[key.to_s] = value.to_s
+    end
+
+    def get_baggage_item(key)
+      @baggage[key.to_s]
+    end
+  end
+end

data/lib/jaeger/thrift_tag_builder.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module Jaeger
+  class ThriftTagBuilder
+    FIELDS = Jaeger::Thrift::Tag::FIELDS
+    KEY = FIELDS[Jaeger::Thrift::Tag::KEY].fetch(:name)
+    VTYPE = FIELDS[Jaeger::Thrift::Tag::VTYPE].fetch(:name)
+    VLONG = FIELDS[Jaeger::Thrift::Tag::VLONG].fetch(:name)
+    VDOUBLE = FIELDS[Jaeger::Thrift::Tag::VDOUBLE].fetch(:name)
+    VBOOL = FIELDS[Jaeger::Thrift::Tag::VBOOL].fetch(:name)
+    VSTR = FIELDS[Jaeger::Thrift::Tag::VSTR].fetch(:name)
+
+    def self.build(key, value)
+      if value.is_a?(Integer)
+        Jaeger::Thrift::Tag.new(
+          KEY => key.to_s,
+          VTYPE => Jaeger::Thrift::TagType::LONG,
+          VLONG => value
+        )
+      elsif value.is_a?(Float)
+        Jaeger::Thrift::Tag.new(
+          KEY => key.to_s,
+          VTYPE => Jaeger::Thrift::TagType::DOUBLE,
+          VDOUBLE => value
+        )
+      elsif value.is_a?(TrueClass) || value.is_a?(FalseClass)
+        Jaeger::Thrift::Tag.new(
+          KEY => key.to_s,
+          VTYPE => Jaeger::Thrift::TagType::BOOL,
+          VBOOL => value
+        )
+      else
+        Jaeger::Thrift::Tag.new(
+          KEY => key.to_s,
+          VTYPE => Jaeger::Thrift::TagType::STRING,
+          VSTR => value.to_s
+        )
+      end
+    end
+  end
+end

data/lib/jaeger/trace_id.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module Jaeger
+  module TraceId
+    MAX_64BIT_SIGNED_INT = (1 << 63) - 1
+    MAX_64BIT_UNSIGNED_INT = (1 << 64) - 1
+    MAX_128BIT_UNSIGNED_INT = (1 << 128) - 1
+    TRACE_ID_UPPER_BOUND = MAX_64BIT_UNSIGNED_INT + 1
+
+    def self.generate
+      rand(TRACE_ID_UPPER_BOUND)
+    end
+
+    def self.base16_hex_id_to_uint64(id)
+      return nil unless id
+
+      value = id.to_i(16)
+      value > MAX_64BIT_UNSIGNED_INT || value < 0 ? 0 : value
+    end
+
+    def self.base16_hex_id_to_uint128(id)
+      return nil unless id
+
+      value = id.to_i(16)
+      value > MAX_128BIT_UNSIGNED_INT || value < 0 ? 0 : value
+    end
+
+    # Thrift defines ID fields as i64, which is signed, therefore we convert
+    # large IDs (> 2^63) to negative longs
+    def self.uint64_id_to_int64(id)
+      id > MAX_64BIT_SIGNED_INT ? id - MAX_64BIT_UNSIGNED_INT - 1 : id
+    end
+
+    # Convert an integer id into a 0 padded hex string.
+    # If the string is shorter than 16 characters, it will be padded to 16.
+    # If it is longer than 16 characters, it is padded to 32.
+    def self.to_hex(id)
+      hex_str = id.to_s(16)
+
+      # pad the string with '0's to 16 or 32 characters
+      if hex_str.length > 16
+        hex_str.rjust(32, '0')
+      else
+        hex_str.rjust(16, '0')
+      end
+    end
+  end
+end

data/lib/jaeger/tracer.rb

@@ -0,0 +1,213 @@
+# frozen_string_literal: true
+
+module Jaeger
+  class Tracer
+    def initialize(reporter:, sampler:, injectors:, extractors:)
+      @reporter = reporter
+      @sampler = sampler
+      @injectors = injectors
+      @extractors = extractors
+      @scope_manager = ScopeManager.new
+    end
+
+    # @return [ScopeManager] the current ScopeManager, which may be a no-op
+    #   but may not be nil.
+    attr_reader :scope_manager
+
+    # @return [Span, nil] the active span. This is a shorthand for
+    #   `scope_manager.active.span`, and nil will be returned if
+    #   Scope#active is nil.
+    def active_span
+      scope = scope_manager.active
+      scope.span if scope
+    end
+
+    # Starts a new span.
+    #
+    # This is similar to #start_active_span, but the returned Span will not
+    # be registered via the ScopeManager.
+    #
+    # @param operation_name [String] The operation name for the Span
+    # @param child_of [SpanContext, Span] SpanContext that acts as a parent to
+    #   the newly-started Span. If a Span instance is provided, its
+    #   context is automatically substituted. See [Reference] for more
+    #   information.
+    #
+    #   If specified, the `references` parameter must be omitted.
+    # @param references [Array<Reference>] An array of reference
+    #   objects that identify one or more parent SpanContexts.
+    # @param start_time [Time] When the Span started, if not now
+    # @param tags [Hash] Tags to assign to the Span at start time
+    # @param ignore_active_scope [Boolean] whether to create an implicit
+    #   References#CHILD_OF reference to the ScopeManager#active.
+    #
+    # @yield [Span] If passed an optional block, start_span will yield the
+    #   newly-created span to the block. The span will be finished automatically
+    #   after the block is executed.
+    # @return [Span, Object] If passed an optional block, start_span will return
+    #  the block's return value, otherwise it returns the newly-started Span
+    #  instance, which has not been automatically registered via the
+    #  ScopeManager
+    def start_span(operation_name,
+                   child_of: nil,
+                   references: nil,
+                   start_time: Time.now,
+                   tags: {},
+                   ignore_active_scope: false,
+                   **)
+      context, sampler_tags = prepare_span_context(
+        operation_name: operation_name,
+        child_of: child_of,
+        references: references,
+        ignore_active_scope: ignore_active_scope
+      )
+      span = Span.new(
+        context,
+        operation_name,
+        @reporter,
+        start_time: start_time,
+        references: references,
+        tags: tags.merge(sampler_tags)
+      )
+
+      if block_given?
+        begin
+          yield(span)
+        ensure
+          span.finish
+        end
+      else
+        span
+      end
+    end
+
+    # Creates a newly started and activated Scope
+    #
+    # If the Tracer's ScopeManager#active is not nil, no explicit references
+    # are provided, and `ignore_active_scope` is false, then an inferred
+    # References#CHILD_OF reference is created to the ScopeManager#active's
+    # SpanContext when start_active is invoked.
+    #
+    # @param operation_name [String] The operation name for the Span
+    # @param child_of [SpanContext, Span] SpanContext that acts as a parent to
+    #   the newly-started Span. If a Span instance is provided, its
+    #   context is automatically substituted. See [Reference] for more
+    #   information.
+    #
+    #   If specified, the `references` parameter must be omitted.
+    # @param references [Array<Reference>] An array of reference
+    #   objects that identify one or more parent SpanContexts.
+    # @param start_time [Time] When the Span started, if not now
+    # @param tags [Hash] Tags to assign to the Span at start time
+    # @param ignore_active_scope [Boolean] whether to create an implicit
+    #   References#CHILD_OF reference to the ScopeManager#active.
+    # @param finish_on_close [Boolean] whether span should automatically be
+    #   finished when Scope#close is called
+    # @yield [Scope] If an optional block is passed to start_active_span it
+    #   will yield the newly-started Scope. If `finish_on_close` is true then the
+    #   Span will be finished automatically after the block is executed.
+    # @return [Scope, Object] If passed an optional block, start_active_span
+    #   returns the block's return value, otherwise it returns the newly-started
+    #   and activated Scope
+    def start_active_span(operation_name,
+                          child_of: nil,
+                          references: nil,
+                          start_time: Time.now,
+                          tags: {},
+                          ignore_active_scope: false,
+                          finish_on_close: true,
+                          **)
+      span = start_span(
+        operation_name,
+        child_of: child_of,
+        references: references,
+        start_time: start_time,
+        tags: tags,
+        ignore_active_scope: ignore_active_scope
+      )
+      scope = @scope_manager.activate(span, finish_on_close: finish_on_close)
+
+      if block_given?
+        begin
+          yield scope
+        ensure
+          scope.close
+        end
+      else
+        scope
+      end
+    end
+
+    # Inject a SpanContext into the given carrier
+    #
+    # @param span_context [SpanContext]
+    # @param format [OpenTracing::FORMAT_TEXT_MAP, OpenTracing::FORMAT_BINARY, OpenTracing::FORMAT_RACK]
+    # @param carrier [Carrier] A carrier object of the type dictated by the specified `format`
+    def inject(span_context, format, carrier)
+      @injectors.fetch(format).each do |injector|
+        injector.inject(span_context, carrier)
+      end
+    end
+
+    # Extract a SpanContext in the given format from the given carrier.
+    #
+    # @param format [OpenTracing::FORMAT_TEXT_MAP, OpenTracing::FORMAT_BINARY, OpenTracing::FORMAT_RACK]
+    # @param carrier [Carrier] A carrier object of the type dictated by the specified `format`
+    # @return [SpanContext] the extracted SpanContext or nil if none could be found
+    def extract(format, carrier)
+      @extractors
+        .fetch(format)
+        .lazy
+        .map { |extractor| extractor.extract(carrier) }
+        .reject(&:nil?)
+        .first
+    end
+
+    private
+
+    def prepare_span_context(operation_name:, child_of:, references:, ignore_active_scope:)
+      context =
+        context_from_child_of(child_of) ||
+        context_from_references(references) ||
+        context_from_active_scope(ignore_active_scope)
+
+      if context
+        [SpanContext.create_from_parent_context(context), {}]
+      else
+        trace_id = TraceId.generate
+        is_sampled, tags = @sampler.sample(
+          trace_id: trace_id,
+          operation_name: operation_name
+        )
+        span_context = SpanContext.new(
+          trace_id: trace_id,
+          span_id: trace_id,
+          flags: is_sampled ? SpanContext::Flags::SAMPLED : SpanContext::Flags::NONE
+        )
+        [span_context, tags]
+      end
+    end
+
+    def context_from_child_of(child_of)
+      return nil unless child_of
+      child_of.respond_to?(:context) ? child_of.context : child_of
+    end
+
+    def context_from_references(references)
+      return nil if !references || references.none?
+
+      # Prefer CHILD_OF reference if present
+      ref = references.detect do |reference|
+        reference.type == OpenTracing::Reference::CHILD_OF
+      end
+      (ref || references[0]).context
+    end
+
+    def context_from_active_scope(ignore_active_scope)
+      return if ignore_active_scope
+
+      active_scope = @scope_manager.active
+      active_scope.span.context if active_scope
+    end
+  end
+end