flare 0.4.0 → 1.0.0

data/lib/flare/filtering_span_processor.rb

@@ -1,429 +0,0 @@
-# frozen_string_literal: true
-
-require "concurrent/atomic/atomic_fixnum"
-require "logger"
-require "opentelemetry/sdk"
-
-require_relative "deadline"
-
-module Flare
-  # BSP-shaped span processor whose filter is `sampled OR marked` instead
-  # of BSP's `sampled` (BSP early-returns on RECORD_ONLY spans -- our
-  # Path 2 spans have sampled=false so they'd be dropped). Forwards
-  # matching spans to a trace exporter on a background worker thread so
-  # the exporter never runs on the request/job thread (CAF-3).
-  #
-  # On every on_finish we also check marker.owner?(trace_id, span_id) and
-  # unmark when the owning rack span finishes (CAF-2). Cleanup runs even
-  # for spans we don't export.
-  class FilteringSpanProcessor
-    SUCCESS = OpenTelemetry::SDK::Trace::Export::SUCCESS
-    FAILURE = OpenTelemetry::SDK::Trace::Export::FAILURE
-    TIMEOUT = OpenTelemetry::SDK::Trace::Export::TIMEOUT
-
-    DEFAULT_MAX_QUEUE = 5_000
-    DEFAULT_FLUSH_INTERVAL = 5      # seconds
-    DEFAULT_EXPORT_TIMEOUT = 30     # seconds
-    DEFAULT_MARKED_TRACE_GRACE_PERIOD = 1.0 # seconds
-
-    attr_reader :dropped_count, :failed_export_count, :exception_count, :buffer_high_watermark, :max_queue
-
-    def initialize(exporter:, marker:,
-                   max_queue: DEFAULT_MAX_QUEUE,
-                   flush_interval: DEFAULT_FLUSH_INTERVAL,
-                   export_timeout: DEFAULT_EXPORT_TIMEOUT,
-                   marked_trace_grace_period: DEFAULT_MARKED_TRACE_GRACE_PERIOD,
-                   logger: nil)
-      @exporter       = exporter
-      @marker         = marker
-      @max_queue      = max_queue
-      @flush_interval = flush_interval
-      @export_timeout = export_timeout
-      @marked_trace_grace_period = marked_trace_grace_period.to_f
-      @logger         = logger || Logger.new($stderr, level: Logger::WARN)
-
-      @pending_by_trace = {}
-      @trace_order      = []
-      @pending_count    = 0
-      @ready_queue      = []
-      @delayed_ready_by_trace = {}
-      @mutex            = Mutex.new
-      @cond             = ConditionVariable.new
-      @stopped          = false
-      @active_exports   = 0
-      @export_completion_sequence = 0
-      @last_export_result = SUCCESS
-      @flush_owner      = nil
-      @pid              = $$
-
-      @dropped_count       = Concurrent::AtomicFixnum.new(0)
-      @failed_export_count = Concurrent::AtomicFixnum.new(0)
-      @exception_count     = Concurrent::AtomicFixnum.new(0)
-      @buffer_high_watermark = Concurrent::AtomicFixnum.new(0)
-
-      start_worker
-    end
-
-    def on_start(_span, _parent_context); end
-
-    def on_finish(span)
-      detect_forking
-
-      ctx = span.context
-      sampled = ctx&.trace_flags&.sampled?
-      marked  = ctx && @marker.marked?(ctx.trace_id)
-      owner_finished = marked && @marker.owner?(ctx.trace_id, ctx.span_id)
-
-      return unless sampled || marked
-
-      span_data = span.respond_to?(:to_span_data) ? span.to_span_data : span
-      enqueue(
-        span_data,
-        complete: owner_finished || sampled_completion_span?(span_data),
-        delay: owner_finished ? @marked_trace_grace_period : 0
-      )
-    end
-
-    def force_flush(timeout: nil)
-      detect_forking
-      deadline = Deadline.new(timeout)
-      return TIMEOUT unless begin_flush(deadline)
-      prior_result = @flush_prior_result
-
-      batch = snapshot_for_flush(deadline)
-      return TIMEOUT unless batch
-
-      operation = start_flush_export(batch, deadline)
-      result = wait_for_flush_export(operation, deadline)
-      [prior_result, result].max
-    ensure
-      finish_flush if @flush_owner == Thread.current
-    end
-
-    def shutdown(timeout: nil)
-      detect_forking
-      deadline = Deadline.new(timeout)
-      return TIMEOUT unless lock_before_deadline(deadline)
-
-      begin
-        @stopped = true
-        @cond.broadcast
-      ensure
-        @mutex.unlock
-      end
-      @worker.join(deadline.remaining || 5)
-      return TIMEOUT if @worker.alive? || deadline.expired?
-
-      result = force_flush(timeout: deadline.remaining)
-      return result unless result == SUCCESS
-      return TIMEOUT if deadline.expired?
-
-      exporter_result = @exporter.shutdown(timeout: deadline.remaining) if @exporter.respond_to?(:shutdown)
-      return TIMEOUT if deadline.expired?
-
-      exporter_result || SUCCESS
-    end
-
-    def buffer_size
-      @mutex.synchronize { queued_span_count }
-    end
-
-    def reset_buffer_high_watermark
-      @buffer_high_watermark.value = buffer_size
-    end
-
-    private
-
-    def enqueue(span_data, complete:, delay: 0)
-      @mutex.synchronize do
-        trace_id = span_data.trace_id
-        @trace_order << trace_id unless @pending_by_trace.key?(trace_id)
-        @pending_by_trace[trace_id] ||= []
-        @pending_by_trace[trace_id] << span_data
-        @pending_count += 1
-        evict_oldest_spans
-
-        if complete
-          delay.positive? ? delay_trace_ready(trace_id, delay) : mark_trace_ready(trace_id)
-        end
-        evict_oldest_spans
-        update_buffer_high_watermark
-      end
-    end
-
-    def worker_loop
-      until stopped?
-        @mutex.synchronize do
-          timeout = next_wait_timeout
-          waiting_for_export = @flush_owner || @active_exports.positive?
-          @cond.wait(@mutex, timeout) if (@ready_queue.empty? || waiting_for_export) && !@stopped
-        end
-        drain_and_export
-      end
-    end
-
-    def stopped?
-      @mutex.synchronize { @stopped }
-    end
-
-    def drain_and_export
-      batch = nil
-      @mutex.synchronize do
-        promote_due_delayed_traces
-        return if @ready_queue.empty? || @flush_owner || @active_exports.positive?
-
-        batch = @ready_queue
-        @ready_queue = []
-        @active_exports += 1
-      end
-
-      result = export_batch(batch, timeout: @export_timeout)
-    ensure
-      export_finished(result || FAILURE) if batch
-    end
-
-    def begin_flush(deadline)
-      return false unless lock_before_deadline(deadline)
-
-      begin
-        initial_sequence = @export_completion_sequence
-        while @flush_owner && @flush_owner != Thread.current
-          return false if deadline.expired?
-
-          @cond.wait(@mutex, deadline.remaining)
-        end
-        @flush_owner = Thread.current
-
-        while @active_exports.positive?
-          return false if deadline.expired?
-
-          @cond.wait(@mutex, deadline.remaining)
-        end
-        @flush_prior_result = if @export_completion_sequence > initial_sequence
-          @last_export_result
-        else
-          SUCCESS
-        end
-      ensure
-        @mutex.unlock
-      end
-      true
-    end
-
-    def finish_flush
-      @mutex.synchronize do
-        @flush_owner = nil
-        @cond.broadcast
-      end
-    end
-
-    def snapshot_for_flush(deadline)
-      return unless lock_before_deadline(deadline)
-
-      begin
-        @ready_queue.concat(@pending_by_trace.values.flatten)
-        @pending_by_trace.clear
-        @trace_order.clear
-        @pending_count = 0
-        unmark_delayed_traces
-        @delayed_ready_by_trace.clear
-        batch = @ready_queue
-        @ready_queue = []
-        batch
-      ensure
-        @mutex.unlock
-      end
-    end
-
-    def start_flush_export(batch, deadline)
-      operation = { done: false, result: nil }
-      @mutex.synchronize { @active_exports += 1 }
-      Thread.new do
-        result = batch.empty? ? SUCCESS : export_batch(batch, timeout: deadline.remaining)
-        if result == SUCCESS && !deadline.expired? && @exporter.respond_to?(:force_flush)
-          result = @exporter.force_flush(timeout: deadline.remaining)
-        end
-        result = TIMEOUT if deadline.expired?
-        operation[:result] = result
-      rescue StandardError => e
-        @exception_count.increment
-        @logger.warn("[Flare::FilteringSpanProcessor] force flush failed: #{e.class}: #{e.message}")
-        operation[:result] = FAILURE
-      ensure
-        @mutex.synchronize do
-          operation[:done] = true
-          complete_export(operation[:result])
-        end
-      end
-      operation
-    end
-
-    def wait_for_flush_export(operation, deadline)
-      @mutex.synchronize do
-        until operation[:done]
-          return TIMEOUT if deadline.expired?
-
-          @cond.wait(@mutex, deadline.remaining)
-        end
-      end
-      operation[:result]
-    end
-
-    def export_batch(batch, timeout:)
-      result = @exporter.export(batch, timeout: timeout)
-      @failed_export_count.increment if result != SUCCESS
-      result
-    rescue StandardError => e
-      @exception_count.increment
-      @logger.warn("[Flare::FilteringSpanProcessor] export failed: #{e.class}: #{e.message}")
-      FAILURE
-    end
-
-    def export_finished(result)
-      @mutex.synchronize do
-        complete_export(result)
-      end
-    end
-
-    def complete_export(result)
-      @active_exports -= 1
-      @export_completion_sequence += 1
-      @last_export_result = result || FAILURE
-      @cond.broadcast
-    end
-
-    def lock_before_deadline(deadline)
-      return @mutex.lock unless deadline.remaining
-
-      until @mutex.try_lock
-        return false if deadline.expired?
-
-        sleep([deadline.remaining, 0.001].min)
-      end
-      true
-    end
-
-    def mark_trace_ready(trace_id)
-      batch = @pending_by_trace.delete(trace_id)
-      return unless batch
-
-      @trace_order.delete(trace_id)
-      @delayed_ready_by_trace.delete(trace_id)
-      @pending_count -= batch.length
-      @ready_queue.concat(batch)
-      @cond.signal
-    end
-
-    def delay_trace_ready(trace_id, delay)
-      @delayed_ready_by_trace[trace_id] = monotonic_now + delay
-      @cond.signal
-    end
-
-    def promote_due_delayed_traces
-      now = monotonic_now
-      ready_trace_ids = @delayed_ready_by_trace.select { |_, ready_at| ready_at <= now }.keys
-      ready_trace_ids.each do |trace_id|
-        mark_trace_ready(trace_id)
-        @marker.unmark(trace_id)
-      end
-    end
-
-    def unmark_delayed_traces
-      @delayed_ready_by_trace.each_key { |trace_id| @marker.unmark(trace_id) }
-    end
-
-    def next_wait_timeout
-      next_ready_at = @delayed_ready_by_trace.values.min
-      return @flush_interval unless next_ready_at
-
-      [next_ready_at - monotonic_now, 0].max
-    end
-
-    def evict_oldest_spans
-      while queued_span_count > @max_queue
-        trace_id = @trace_order.first
-        unless trace_id
-          @ready_queue.shift
-          @dropped_count.increment
-          next
-        end
-
-        spans = @pending_by_trace[trace_id]
-        if spans.nil? || spans.empty?
-          @trace_order.shift
-          next
-        end
-
-        spans.shift
-        @pending_count -= 1
-        @dropped_count.increment
-
-        if spans.empty?
-          @pending_by_trace.delete(trace_id)
-          @trace_order.shift
-        end
-      end
-    end
-
-    def queued_span_count
-      @pending_count + @ready_queue.length
-    end
-
-    def update_buffer_high_watermark
-      current = queued_span_count
-      @buffer_high_watermark.update { |previous| current > previous ? current : previous }
-    end
-
-    def monotonic_now
-      Process.clock_gettime(Process::CLOCK_MONOTONIC)
-    end
-
-    def sampled_completion_span?(span_data)
-      root_span?(span_data) || entry_span?(span_data)
-    end
-
-    def root_span?(span_data)
-      parent_id = span_data.parent_span_id if span_data.respond_to?(:parent_span_id)
-      parent_id.nil? ||
-        (parent_id.respond_to?(:empty?) && parent_id.empty?) ||
-        parent_id == OpenTelemetry::Trace::INVALID_SPAN_ID
-    end
-
-    def entry_span?(span_data)
-      return false unless span_data.respond_to?(:kind)
-
-      span_data.kind == :server || span_data.kind == :consumer
-    end
-
-    def detect_forking
-      return if @pid == $$
-
-      # The child only retains the forking thread. Replace synchronization
-      # objects so it cannot inherit locks or active-export bookkeeping owned
-      # by vanished threads.
-      @pid = $$
-      @mutex = Mutex.new
-      @cond = ConditionVariable.new
-      @pending_by_trace = {}
-      @trace_order = []
-      @ready_queue = []
-      @delayed_ready_by_trace = {}
-      @pending_count = 0
-      @active_exports = 0
-      @export_completion_sequence = 0
-      @last_export_result = SUCCESS
-      @flush_prior_result = SUCCESS
-      @flush_owner = nil
-      @stopped = false
-      @worker = nil
-      start_worker
-    end
-
-    def start_worker
-      return if @worker&.alive?
-
-      @worker = Thread.new { worker_loop }
-      @worker.name = "flare-filtering-span-processor"
-    end
-  end
-end

data/lib/flare/http_metrics_config.rb

@@ -1,101 +0,0 @@
-# frozen_string_literal: true
-
-module Flare
-  class HttpMetricsConfig
-    class HostConfig
-      attr_reader :rules
-
-      def initialize
-        @rules = []
-        @all = false
-      end
-
-      def initialize_copy(source)
-        @rules = source.rules.dup
-      end
-
-      def all?
-        @all
-      end
-
-      # Track all paths for this host (normalized via normalize_path)
-      def all
-        @all = true
-      end
-
-      # Track paths matching this regex (normalized via normalize_path)
-      def allow(pattern)
-        @rules << {pattern: pattern, replacement: nil}
-      end
-
-      # Track paths matching this regex with a custom replacement string
-      def map(pattern, replacement)
-        @rules << {pattern: pattern, replacement: replacement}
-      end
-
-      # Returns the resolved path for a given raw path, or "*" if no match.
-      # If :all, returns nil to signal "use normalize_path".
-      # If a rule matches with a replacement, returns the replacement.
-      # If a rule matches without a replacement, returns nil to signal "use normalize_path".
-      # If no rules match, returns "*".
-      def resolve(path)
-        return nil if @all
-
-        @rules.each do |rule|
-          if rule[:pattern].match?(path)
-            return rule[:replacement] # nil means use normalize_path
-          end
-        end
-
-        "*"
-      end
-    end
-
-    def initialize
-      @hosts = {}
-    end
-
-    def initialize_copy(source)
-      @hosts = source.instance_variable_get(:@hosts).transform_values(&:dup)
-    end
-
-    def host(hostname, mode = nil, &block)
-      config = @hosts[hostname] ||= HostConfig.new
-
-      if mode == :all
-        config.all
-      elsif block
-        yield config
-      end
-    end
-
-    # Resolve a host+path to the target path for metrics.
-    # Returns "*" for unknown hosts or unmatched paths.
-    # Returns nil to signal "use normalize_path".
-    # Returns a string for custom replacements.
-    def resolve(hostname, path)
-      host_config = @hosts[hostname]
-      return "*" unless host_config
-
-      host_config.resolve(path)
-    end
-
-    DEFAULT = new.tap do |config|
-      config.host "flare.am" do |h|
-        h.allow %r{/api/metrics}
-      end
-
-      config.host "www.flippercloud.io" do |h|
-        h.map %r{/adapter/features/[^/]+/(boolean|actors|groups|percentage_of_actors|percentage_of_time|expression|clear)}, "/adapter/features/:name/:gate"
-        h.map %r{/adapter/features/[^/]+}, "/adapter/features/:name"
-        h.map %r{/adapter/actors/[^/]+}, "/adapter/actors/:id"
-        h.allow %r{/adapter/features}
-        h.allow %r{/adapter/import}
-        h.allow %r{/adapter/telemetry/summary}
-        h.allow %r{/adapter/telemetry}
-        h.allow %r{/adapter/events}
-        h.allow %r{/adapter/audits}
-      end
-    end.freeze
-  end
-end

data/lib/flare/http_transport.rb

@@ -1,76 +0,0 @@
-# frozen_string_literal: true
-
-require "net/http"
-require "uri"
-
-require_relative "deadline"
-
-module Flare
-  # Tiny HTTP wrapper used by TraceExporter (and anything else that wants
-  # to PUT/POST without pulling in a heavy client). Designed for injection
-  # at the boundary so tests can swap in a recording fake; no other moving
-  # parts.
-  class HttpTransport
-    DeadlineExceeded = Class.new(StandardError)
-    DEFAULT_OPEN_TIMEOUT  = 2
-    DEFAULT_READ_TIMEOUT  = 5
-    DEFAULT_WRITE_TIMEOUT = 5
-
-    Response = Struct.new(:code, :body, :headers, keyword_init: true) do
-      def header(name)
-        return nil unless headers
-        headers[name] || headers[name.downcase] || headers[name.upcase]
-      end
-    end
-
-    def initialize(open_timeout: DEFAULT_OPEN_TIMEOUT,
-                   read_timeout: DEFAULT_READ_TIMEOUT,
-                   write_timeout: DEFAULT_WRITE_TIMEOUT)
-      @open_timeout  = open_timeout
-      @read_timeout  = read_timeout
-      @write_timeout = write_timeout
-    end
-
-    def get(url, headers = {}, timeout: nil)
-      request(url, nil, headers, Net::HTTP::Get, timeout: timeout)
-    end
-
-    def put(url, body, headers = {}, timeout: nil)
-      request(url, body, headers, Net::HTTP::Put, timeout: timeout)
-    end
-
-    def post(url, body, headers = {}, timeout: nil)
-      request(url, body, headers, Net::HTTP::Post, timeout: timeout)
-    end
-
-    private
-
-    def request(url, body, headers, klass, timeout: nil)
-      deadline = Deadline.new(timeout)
-      raise DeadlineExceeded if deadline.expired?
-
-      uri = URI(url)
-      http = Net::HTTP.new(uri.host, uri.port)
-      http.use_ssl     = uri.scheme == "https"
-      http.open_timeout = effective_timeout(@open_timeout, deadline.remaining)
-      http.read_timeout = effective_timeout(@read_timeout, deadline.remaining)
-      http.write_timeout = effective_timeout(@write_timeout, deadline.remaining) if http.respond_to?(:write_timeout=)
-
-      req = klass.new(uri.request_uri == "" ? "/" : uri.request_uri)
-      headers.each { |k, v| req[k] = v }
-      req.body = body if body
-
-      response = http.request(req)
-      raise DeadlineExceeded if deadline.expired?
-
-      hash = response.each_header.to_h
-      Response.new(code: response.code.to_s, body: response.body, headers: hash)
-    end
-
-    def effective_timeout(configured_timeout, remaining)
-      return configured_timeout unless remaining
-
-      [configured_timeout, remaining].min
-    end
-  end
-end

data/lib/flare/lifecycle.rb

@@ -1,39 +0,0 @@
-# frozen_string_literal: true
-
-require "opentelemetry/sdk"
-
-require_relative "deadline"
-
-module Flare
-  module Lifecycle
-    # Flush all trace processors and the separate aggregated metric pipeline
-    # using one monotonic timeout budget. This is safe to call from lifecycle
-    # hooks for short-lived and fork-per-job workers.
-    def force_flush(timeout: nil)
-      deadline = Deadline.new(timeout)
-      results = []
-
-      results << tracer_provider_for_flush.force_flush(timeout: deadline.remaining)
-      return OpenTelemetry::SDK::Trace::Export::TIMEOUT if deadline.expired?
-
-      flusher = metric_flusher_for_flush
-      results << flusher.force_flush(timeout: deadline.remaining) if flusher
-      return OpenTelemetry::SDK::Trace::Export::TIMEOUT if deadline.expired?
-
-      results.max || OpenTelemetry::SDK::Trace::Export::SUCCESS
-    rescue => e
-      warn "[Flare] Telemetry flush error: #{e.message}"
-      OpenTelemetry::SDK::Trace::Export::FAILURE
-    end
-
-    def tracer_provider_for_flush
-      OpenTelemetry.tracer_provider
-    end
-
-    def metric_flusher_for_flush
-      @metric_flusher
-    end
-  end
-
-  extend Lifecycle
-end