dox-jaeger-client 2.0.0

data/lib/jaeger/injectors.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+module Jaeger
+  module Injectors
+    def self.context_as_jaeger_string(span_context)
+      [
+        span_context.trace_id.to_s(16),
+        span_context.span_id.to_s(16),
+        span_context.parent_id.to_s(16),
+        span_context.flags.to_s(16)
+      ].join(':')
+    end
+
+    class JaegerTextMapCodec
+      def self.inject(span_context, carrier)
+        carrier['uber-trace-id'] = Injectors.context_as_jaeger_string(span_context)
+        span_context.baggage.each do |key, value|
+          carrier["uberctx-#{key}"] = value
+        end
+      end
+    end
+
+    class JaegerRackCodec
+      def self.inject(span_context, carrier)
+        carrier['uber-trace-id'] =
+          CGI.escape(Injectors.context_as_jaeger_string(span_context))
+        span_context.baggage.each do |key, value|
+          carrier["uberctx-#{key}"] = CGI.escape(value)
+        end
+      end
+    end
+
+    class JaegerBinaryCodec
+      def self.inject(_span_context, _carrier)
+        warn 'Jaeger::Client with binary format is not supported yet'
+      end
+    end
+
+    class B3RackCodec
+      def self.inject(span_context, carrier)
+        carrier['x-b3-traceid'] = TraceId.to_hex(span_context.trace_id)
+        carrier['x-b3-spanid'] = TraceId.to_hex(span_context.span_id)
+        carrier['x-b3-parentspanid'] = TraceId.to_hex(span_context.parent_id)
+
+        # flags (for debug) and sampled headers are mutually exclusive
+        if span_context.flags == Jaeger::SpanContext::Flags::DEBUG
+          carrier['x-b3-flags'] = '1'
+        else
+          carrier['x-b3-sampled'] = span_context.flags.to_s(16)
+        end
+      end
+    end
+
+    class TraceContextRackCodec
+      def self.inject(span_context, carrier)
+        flags = span_context.sampled? || span_context.debug? ? 1 : 0
+
+        carrier['traceparent'] = format(
+          '%<version>s-%<trace_id>s-%<span_id>s-%<flags>s',
+          version: '00',
+          trace_id: span_context.trace_id.to_s(16).rjust(32, '0'),
+          span_id: span_context.span_id.to_s(16).rjust(16, '0'),
+          flags: flags.to_s(16).rjust(2, '0')
+        )
+      end
+    end
+
+    DEFAULT_INJECTORS = {
+      OpenTracing::FORMAT_TEXT_MAP => JaegerTextMapCodec,
+      OpenTracing::FORMAT_BINARY => JaegerBinaryCodec,
+      OpenTracing::FORMAT_RACK => JaegerRackCodec
+    }.freeze
+
+    def self.prepare(injectors)
+      DEFAULT_INJECTORS.reduce(injectors) do |acc, (format, default)|
+        provided_injectors = Array(injectors[format])
+        provided_injectors += [default] if provided_injectors.empty?
+
+        acc.merge(format => provided_injectors)
+      end
+    end
+  end
+end

data/lib/jaeger/rate_limiter.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+module Jaeger
+  # RateLimiter is based on leaky bucket algorithm, formulated in terms of a
+  # credits balance that is replenished every time check_credit() method is
+  # called (tick) by the amount proportional to the time elapsed since the
+  # last tick, up to the max_balance. A call to check_credit() takes a cost
+  # of an item we want to pay with the balance. If the balance exceeds the
+  # cost of the item, the item is "purchased" and the balance reduced,
+  # indicated by returned value of true. Otherwise the balance is unchanged
+  # and return false.
+  #
+  # This can be used to limit a rate of messages emitted by a service by
+  # instantiating the Rate Limiter with the max number of messages a service
+  # is allowed to emit per second, and calling check_credit(1.0) for each
+  # message to determine if the message is within the rate limit.
+  #
+  # It can also be used to limit the rate of traffic in bytes, by setting
+  # credits_per_second to desired throughput as bytes/second, and calling
+  # check_credit() with the actual message size.
+  class RateLimiter
+    def initialize(credits_per_second:, max_balance:)
+      @credits_per_second = credits_per_second
+      @max_balance = max_balance
+      @balance = max_balance
+      @last_tick = Time.now
+    end
+
+    def check_credit(item_cost)
+      update_balance
+
+      return false if @balance < item_cost
+
+      @balance -= item_cost
+      true
+    end
+
+    def update(credits_per_second:, max_balance:)
+      update_balance
+
+      @credits_per_second = credits_per_second
+
+      # The new balance should be proportional to the old balance
+      @balance = max_balance * @balance / @max_balance
+      @max_balance = max_balance
+    end
+
+    private
+
+    def update_balance
+      current_time = Time.now
+      elapsed_time = current_time - @last_tick
+      @last_tick = current_time
+
+      @balance += elapsed_time * @credits_per_second
+      return if @balance <= @max_balance
+
+      @balance = @max_balance
+    end
+  end
+end

data/lib/jaeger/recurring_executor.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module Jaeger
+  # Executes a given block periodically. The block will be executed only once
+  # when interval is set to 0.
+  class RecurringExecutor
+    def initialize(interval:)
+      @interval = interval
+    end
+
+    def start(&block)
+      raise 'Already running' if @thread
+
+      @thread = Thread.new do
+        if @interval <= 0
+          yield
+        else
+          loop do
+            yield
+            sleep @interval
+          end
+        end
+      end
+    end
+
+    def running?
+      @thread&.alive?
+    end
+
+    def stop
+      @thread.kill
+      @thread = nil
+    end
+  end
+end

data/lib/jaeger/reporters/composite_reporter.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module Jaeger
+  module Reporters
+    class CompositeReporter
+      def initialize(reporters:)
+        @reporters = reporters
+      end
+
+      def report(span)
+        @reporters.each do |reporter|
+          reporter.report(span)
+        end
+      end
+    end
+  end
+end

data/lib/jaeger/reporters/in_memory_reporter.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module Jaeger
+  module Reporters
+    class InMemoryReporter
+      def initialize
+        @spans = []
+        @mutex = Mutex.new
+      end
+
+      def report(span)
+        @mutex.synchronize do
+          @spans << span
+        end
+      end
+
+      def spans
+        @mutex.synchronize do
+          @spans
+        end
+      end
+
+      def clear
+        @mutex.synchronize do
+          @spans.clear
+        end
+      end
+    end
+  end
+end

data/lib/jaeger/reporters/logging_reporter.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module Jaeger
+  module Reporters
+    class LoggingReporter
+      def initialize(logger: Logger.new($stdout))
+        @logger = logger
+      end
+
+      def report(span)
+        span_info = {
+          operation_name: span.operation_name,
+          start_time: span.start_time.iso8601,
+          end_time: span.end_time.iso8601,
+          trace_id: span.context.to_trace_id,
+          span_id: span.context.to_span_id
+        }
+        @logger.info "Span reported: #{span_info}"
+      end
+    end
+  end
+end

data/lib/jaeger/reporters/null_reporter.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module Jaeger
+  module Reporters
+    class NullReporter
+      def report(_span)
+        # no-op
+      end
+    end
+  end
+end

data/lib/jaeger/reporters/remote_reporter/buffer.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module Jaeger
+  module Reporters
+    class RemoteReporter
+      class Buffer
+        def initialize
+          @buffer = []
+          @mutex = Mutex.new
+        end
+
+        def <<(element)
+          @mutex.synchronize do
+            @buffer << element
+            true
+          end
+        end
+
+        def retrieve
+          @mutex.synchronize do
+            elements = @buffer.dup
+            @buffer.clear
+            elements
+          end
+        end
+      end
+    end
+  end
+end

data/lib/jaeger/reporters/remote_reporter.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+require_relative './remote_reporter/buffer'
+
+module Jaeger
+  module Reporters
+    class RemoteReporter
+      def initialize(sender:, flush_interval:)
+        @sender = sender
+        @flush_interval = flush_interval
+        @buffer = Buffer.new
+      end
+
+      def flush
+        spans = @buffer.retrieve
+        @sender.send_spans(spans) if spans.any?
+        spans
+      end
+
+      def report(span)
+        return if !span.context.sampled? && !span.context.debug?
+
+        init_reporter_thread
+        @buffer << span
+      end
+
+      private
+
+      def init_reporter_thread
+        return if @initializer_pid == Process.pid
+
+        @initializer_pid = Process.pid
+        Thread.new do
+          loop do
+            flush
+            sleep(@flush_interval)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/jaeger/reporters.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+require_relative 'reporters/composite_reporter'
+require_relative 'reporters/in_memory_reporter'
+require_relative 'reporters/logging_reporter'
+require_relative 'reporters/null_reporter'
+require_relative 'reporters/remote_reporter'

data/lib/jaeger/samplers/const.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module Jaeger
+  module Samplers
+    # Const sampler
+    #
+    # A sampler that always makes the same decision for new traces depending
+    # on the initialization value. Use `Jaeger::Samplers::Const.new(true)`
+    # to mark all new traces as sampled.
+    class Const
+      def initialize(decision)
+        @decision = decision
+        @tags = {
+          'sampler.type' => 'const',
+          'sampler.param' => @decision ? 1 : 0
+        }
+      end
+
+      def sample(*)
+        [@decision, @tags]
+      end
+    end
+  end
+end

data/lib/jaeger/samplers/guaranteed_throughput_probabilistic.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module Jaeger
+  module Samplers
+    # A sampler that leverages both Probabilistic sampler and RateLimiting
+    # sampler. The RateLimiting is used as a guaranteed lower bound sampler
+    # such that every operation is sampled at least once in a time interval
+    # defined by the lower_bound. ie a lower_bound of 1.0 / (60 * 10) will
+    # sample an operation at least once every 10 minutes.
+    #
+    # The Probabilistic sampler is given higher priority when tags are
+    # emitted, ie. if is_sampled() for both samplers return true, the tags
+    # for Probabilistic sampler will be used.
+    class GuaranteedThroughputProbabilistic
+      attr_reader :tags, :probabilistic_sampler, :lower_bound_sampler
+
+      def initialize(lower_bound:, rate:, lower_bound_sampler: nil)
+        @probabilistic_sampler = Probabilistic.new(rate: rate)
+        @lower_bound_sampler = lower_bound_sampler || RateLimiting.new(max_traces_per_second: lower_bound)
+        @lower_bound_tags = {
+          'sampler.type' => 'lowerbound',
+          'sampler.param' => rate
+        }
+      end
+
+      def update(lower_bound:, rate:)
+        is_updated = @probabilistic_sampler.update(rate: rate)
+        is_updated = @lower_bound_sampler.update(max_traces_per_second: lower_bound) || is_updated
+        @lower_bound_tags['sampler.param'] = rate
+        is_updated
+      end
+
+      def sample(...)
+        is_sampled, probabilistic_tags = @probabilistic_sampler.sample(...)
+        if is_sampled
+          # We still call lower_bound_sampler to update the rate limiter budget
+          @lower_bound_sampler.sample(...)
+
+          return [is_sampled, probabilistic_tags]
+        end
+
+        is_sampled, _tags = @lower_bound_sampler.sample(...)
+        [is_sampled, @lower_bound_tags]
+      end
+    end
+  end
+end

data/lib/jaeger/samplers/per_operation.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+module Jaeger
+  module Samplers
+    # A sampler that leverages both Probabilistic sampler and RateLimiting
+    # sampler via the GuaranteedThroughputProbabilistic sampler. This sampler
+    # keeps track of all operations and delegates calls the the respective
+    # GuaranteedThroughputProbabilistic sampler.
+    class PerOperation
+      DEFAULT_SAMPLING_PROBABILITY = 0.001
+      DEFAULT_LOWER_BOUND = 1.0 / (10.0 * 60.0) # sample once every 10 minutes'
+
+      attr_reader :default_sampling_probability, :lower_bound, :samplers
+
+      def initialize(strategies:, max_operations:)
+        @max_operations = max_operations
+        @samplers = {}
+        update(strategies: strategies)
+      end
+
+      def update(strategies:)
+        is_updated = false
+
+        @default_sampling_probability =
+          strategies[:default_sampling_probability] || DEFAULT_SAMPLING_PROBABILITY
+        @lower_bound =
+          strategies[:default_lower_bound_traces_per_second] || DEFAULT_LOWER_BOUND
+
+        if @default_sampler
+          is_updated = @default_sampler.update(rate: @default_sampling_probability)
+        else
+          @default_sampler = Probabilistic.new(rate: @default_sampling_probability)
+        end
+
+        update_operation_strategies(strategies) || is_updated
+      end
+
+      def sample(opts)
+        operation_name = opts.fetch(:operation_name)
+        sampler = @samplers[operation_name]
+        return sampler.sample(opts) if sampler
+
+        return @default_sampler.sample(opts) if @samplers.length >= @max_operations
+
+        sampler = GuaranteedThroughputProbabilistic.new(
+          lower_bound: @lower_bound,
+          rate: @default_sampling_probability
+        )
+        @samplers[operation_name] = sampler
+        sampler.sample(opts)
+      end
+
+      private
+
+      def update_operation_strategies(strategies)
+        is_updated = false
+
+        (strategies[:per_operation_strategies] || []).each do |strategy|
+          operation = strategy.fetch(:operation)
+          rate = strategy.fetch(:probabilistic_sampling).fetch(:sampling_rate)
+
+          if (sampler = @samplers[operation])
+            is_updated = sampler.update(lower_bound: @lower_bound, rate: rate) || is_updated
+          else
+            @samplers[operation] = GuaranteedThroughputProbabilistic.new(
+              lower_bound: @lower_bound,
+              rate: rate
+            )
+            is_updated = true
+          end
+        end
+
+        is_updated
+      end
+    end
+  end
+end

data/lib/jaeger/samplers/probabilistic.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module Jaeger
+  module Samplers
+    # Probabilistic sampler
+    #
+    # Sample a portion of traces using trace_id as the random decision
+    class Probabilistic
+      attr_reader :rate
+
+      def initialize(rate: 0.001)
+        update(rate: rate)
+      end
+
+      def update(rate:)
+        if rate < 0.0 || rate > 1.0
+          raise "Sampling rate must be between 0.0 and 1.0, got #{rate.inspect}"
+        end
+
+        new_boundary = TraceId::TRACE_ID_UPPER_BOUND * rate
+        return false if @boundary == new_boundary
+
+        @rate = rate
+        @boundary = TraceId::TRACE_ID_UPPER_BOUND * rate
+        @tags = {
+          'sampler.type' => 'probabilistic',
+          'sampler.param' => rate
+        }
+
+        true
+      end
+
+      def sample(opts)
+        trace_id = opts.fetch(:trace_id)
+
+        [@boundary >= trace_id, @tags]
+      end
+    end
+  end
+end

data/lib/jaeger/samplers/rate_limiting.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module Jaeger
+  module Samplers
+    # Samples at most max_traces_per_second. The distribution of sampled
+    # traces follows burstiness of the service, i.e. a service with uniformly
+    # distributed requests will have those requests sampled uniformly as
+    # well, but if requests are bursty, especially sub-second, then a number
+    # of sequential requests can be sampled each second.
+    class RateLimiting
+      attr_reader :tags, :max_traces_per_second
+
+      def initialize(max_traces_per_second: 10)
+        update(max_traces_per_second: max_traces_per_second)
+      end
+
+      def update(max_traces_per_second:)
+        if max_traces_per_second < 0.0
+          raise "max_traces_per_second must not be negative, got #{max_traces_per_second}"
+        end
+
+        return false if max_traces_per_second == @max_traces_per_second
+
+        @tags = {
+          'sampler.type' => 'ratelimiting',
+          'sampler.param' => max_traces_per_second
+        }
+        @max_traces_per_second = max_traces_per_second
+        max_balance = [max_traces_per_second, 1.0].max
+
+        if @rate_limiter
+          @rate_limiter.update(
+            credits_per_second: max_traces_per_second,
+            max_balance: max_balance
+          )
+        else
+          @rate_limiter = RateLimiter.new(
+            credits_per_second: max_traces_per_second,
+            max_balance: [max_traces_per_second, 1.0].max
+          )
+        end
+
+        true
+      end
+
+      def sample(*)
+        [@rate_limiter.check_credit(1.0), @tags]
+      end
+    end
+  end
+end

data/lib/jaeger/samplers/remote_controlled/instructions_fetcher.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module Jaeger
+  module Samplers
+    class RemoteControlled
+      class InstructionsFetcher
+        FetchFailed = Class.new(StandardError)
+
+        def initialize(host:, port:, service_name:)
+          @host = host
+          @port = port
+          @service_name = service_name
+        end
+
+        def fetch
+          http = Net::HTTP.new(@host, @port)
+          path = "/sampling?service=#{CGI.escape(@service_name)}"
+          response =
+            begin
+              http.request(Net::HTTP::Get.new(path))
+            rescue StandardError => e
+              raise FetchFailed, e.inspect
+            end
+
+          unless response.is_a?(Net::HTTPSuccess)
+            raise FetchFailed, "Unsuccessful response (code=#{response.code})"
+          end
+
+          JSON.parse(response.body)
+        end
+      end
+    end
+  end
+end