flare 0.4.0 → 1.0.0

data/lib/flare/marker.rb

@@ -1,106 +0,0 @@
-# frozen_string_literal: true
-
-require "concurrent/map"
-require "concurrent/atomic/atomic_fixnum"
-
-module Flare
-  # Thread-safe registry of trace_ids that Path 2 (the WebMarkerSubscriber)
-  # has marked for export. FilteringSpanProcessor checks marked? on every
-  # on_finish; matching spans get forwarded to the trace exporter, the rest
-  # are dropped.
-  #
-  # Each entry records the OWNER span_id (the local rack server span the
-  # subscriber was inside when it marked the trace). Cleanup is keyed on
-  # the owner finishing, not the trace root finishing -- remote-parented
-  # rack spans aren't trace roots, and child spans can outlive their parent
-  # in OTel, so root-driven cleanup would leak on the dominant production
-  # case (web app behind a load balancer or service mesh).
-  #
-  # Bounded by:
-  #   - sweep(): drops entries older than max_age (default 5 min) so a rack
-  #     span that never finishes (process killed mid-request, exception path
-  #     that skips ensure) doesn't leak forever.
-  #   - hard ceiling at max_entries (default 10k): on overflow, drop oldest
-  #     10% by marked_at.
-  class Marker
-    Entry = Struct.new(:owner_span_id, :rule_id, :marked_at, keyword_init: true)
-
-    DEFAULT_MAX_ENTRIES = 10_000
-    DEFAULT_MAX_AGE = 5 * 60 # seconds
-
-    attr_reader :evicted_count
-
-    def initialize(max_entries: DEFAULT_MAX_ENTRIES, max_age: DEFAULT_MAX_AGE)
-      @entries = Concurrent::Map.new
-      @max_entries = max_entries
-      @max_age = max_age
-      @evicted_count = Concurrent::AtomicFixnum.new(0)
-    end
-
-    def mark(trace_id, owner_span_id:, rule_id:)
-      @entries[trace_id] = Entry.new(
-        owner_span_id: owner_span_id,
-        rule_id: rule_id,
-        marked_at: monotonic_now
-      )
-      maybe_evict_oldest
-    end
-
-    def marked?(trace_id)
-      @entries.key?(trace_id)
-    end
-
-    # True only when span_id matches the marker's owner -- the rack span
-    # that originally marked this trace. Used by FilteringSpanProcessor to
-    # decide when to unmark (only when that exact span finishes, not on
-    # every span that happens to have this trace_id).
-    def owner?(trace_id, span_id)
-      entry = @entries[trace_id]
-      !entry.nil? && entry.owner_span_id == span_id
-    end
-
-    def rule_id(trace_id)
-      entry = @entries[trace_id]
-      entry&.rule_id
-    end
-
-    def unmark(trace_id)
-      @entries.delete(trace_id)
-    end
-
-    def size
-      @entries.size
-    end
-
-    # Drop entries older than max_age. Call periodically (the RuleManager's
-    # scheduler is the natural place) to handle the rack-span-never-finishes
-    # leak case (CAF-7).
-    def sweep
-      threshold = monotonic_now - @max_age
-      evicted = 0
-      @entries.each_pair do |trace_id, entry|
-        if entry.marked_at < threshold
-          @entries.delete(trace_id)
-          evicted += 1
-        end
-      end
-      @evicted_count.increment(evicted) if evicted.positive?
-      evicted
-    end
-
-    private
-
-    def maybe_evict_oldest
-      return if @entries.size <= @max_entries
-
-      to_drop = (@max_entries * 0.1).ceil
-      sorted = @entries.each_pair.to_a.sort_by { |_, entry| entry.marked_at }
-      sorted.first(to_drop).each { |trace_id, _| @entries.delete(trace_id) }
-      @evicted_count.increment(to_drop)
-    end
-
-    def monotonic_now
-      Process.clock_gettime(Process::CLOCK_MONOTONIC)
-    end
-  end
-end

data/lib/flare/metric_counter.rb

@@ -1,51 +0,0 @@
-# frozen_string_literal: true
-
-require "concurrent/atomic/atomic_fixnum"
-
-module Flare
-  # Thread-safe counter for metric aggregation.
-  # Uses atomic operations for lock-free increments.
-  #
-  # Note: Durations are stored as integer milliseconds. Sub-millisecond
-  # durations are truncated to 0. For very fast operations (e.g., cache hits),
-  # the sum_ms may undercount actual time spent.
-  class MetricCounter
-    def initialize
-      @count = Concurrent::AtomicFixnum.new(0)
-      @sum_ms = Concurrent::AtomicFixnum.new(0)
-      @error_count = Concurrent::AtomicFixnum.new(0)
-    end
-
-    def increment(duration_ms:, error: false)
-      @count.increment
-      @sum_ms.increment(duration_ms.to_i)
-      @error_count.increment if error
-    end
-
-    def add(count:, sum_ms:, error_count: 0)
-      @count.increment(count.to_i)
-      @sum_ms.increment(sum_ms.to_i)
-      @error_count.increment(error_count.to_i)
-    end
-
-    def count
-      @count.value
-    end
-
-    def sum_ms
-      @sum_ms.value
-    end
-
-    def error_count
-      @error_count.value
-    end
-
-    def to_h
-      {
-        count: @count.value,
-        sum_ms: @sum_ms.value,
-        error_count: @error_count.value
-      }
-    end
-  end
-end

data/lib/flare/metric_flusher.rb

@@ -1,279 +0,0 @@
-# frozen_string_literal: true
-
-require "concurrent/timer_task"
-require "concurrent/executor/fixed_thread_pool"
-require "opentelemetry/sdk"
-
-require_relative "deadline"
-
-module Flare
-  # Background threads that periodically drain in-memory metrics and submit
-  # them via HTTP. Uses concurrent-ruby TimerTask + FixedThreadPool, matching
-  # the pattern in Flipper's telemetry.
-  #
-  # Fork-safe: detects forked processes and restarts automatically.
-  class MetricFlusher
-    SUCCESS = OpenTelemetry::SDK::Trace::Export::SUCCESS
-    FAILURE = OpenTelemetry::SDK::Trace::Export::FAILURE
-    TIMEOUT = OpenTelemetry::SDK::Trace::Export::TIMEOUT
-    DEFAULT_INTERVAL = 60 # seconds
-    DEFAULT_SHUTDOWN_TIMEOUT = 5 # seconds
-
-    attr_reader :interval, :shutdown_timeout
-
-    def initialize(storage:, submitter:, interval: DEFAULT_INTERVAL, shutdown_timeout: DEFAULT_SHUTDOWN_TIMEOUT, health_reporters: [])
-      @storage = storage
-      @submitter = submitter
-      @interval = interval
-      @shutdown_timeout = shutdown_timeout
-      @health_reporters = Array(health_reporters)
-      @pid = $$
-      @stopped = false
-      initialize_synchronization
-    end
-
-    def start
-      @stopped = false
-
-      @pool = Concurrent::FixedThreadPool.new(1, {
-        max_queue: 20,
-        fallback_policy: :discard,
-        name: "flare-metrics-submit-pool".freeze,
-      })
-
-      @timer = Concurrent::TimerTask.execute({
-        execution_interval: @interval,
-        name: "flare-metrics-drain-timer".freeze,
-      }) { post_to_pool }
-    end
-
-    def stop(timeout: @shutdown_timeout)
-      return if @stopped
-
-      deadline = Deadline.new(timeout)
-      @stopped = true
-
-      log "Shutting down metrics flusher, draining remaining metrics..."
-
-      if @timer
-        @timer.shutdown
-        @timer.wait_for_termination([deadline.remaining || 1, 1].min)
-        @timer.kill unless @timer.shutdown?
-      end
-
-      force_flush(timeout: deadline.remaining)
-
-      if @pool
-        @pool.shutdown
-        pool_terminated = @pool.wait_for_termination(deadline.remaining || @shutdown_timeout)
-        @pool.kill unless pool_terminated
-      end
-
-      log "Metrics flusher stopped"
-    end
-
-    def restart
-      @stopped = false
-      stop
-      start
-    end
-
-    # Manually trigger a flush (useful for testing or forced flushes).
-    def flush_now(timeout: nil)
-      return 0 unless @storage && @submitter
-
-      detect_forking
-      count, error, = flush_synchronously(Deadline.new(timeout))
-      if error
-        warn "[Flare] Metric submission error: #{error.message}"
-      end
-      count
-    rescue => e
-      warn "[Flare] Metric flush error: #{e.message}"
-      0
-    end
-
-    def force_flush(timeout: nil)
-      return SUCCESS unless @storage && @submitter
-
-      detect_forking
-      deadline = Deadline.new(timeout)
-      _count, error, timed_out = flush_synchronously(deadline)
-      return TIMEOUT if timed_out || deadline.expired?
-      return FAILURE if error
-
-      SUCCESS
-    rescue => e
-      warn "[Flare] Metric flush error: #{e.message}"
-      FAILURE
-    end
-
-    def running?
-      @timer&.running? || false
-    end
-
-    # Re-initialize after fork. Called automatically by MetricSpanProcessor
-    # on first span in the new process, or manually from Puma/Unicorn
-    # after_fork hooks.
-    def after_fork
-      @pid = $$
-      @storage.after_fork if @storage.respond_to?(:after_fork)
-      initialize_synchronization
-      @timer = nil
-      @pool = nil
-      start
-    end
-
-    private
-
-    def detect_forking
-      after_fork if @pid != $$
-    end
-
-    def initialize_synchronization
-      @submission_mutex = Mutex.new
-      @submission_condition = ConditionVariable.new
-      @pending_submissions = 0
-      @flush_owner = nil
-    end
-
-    def post_to_pool
-      return unless reserve_background_submission
-
-      record_health_metrics
-      drained = @storage.drain
-      if drained.empty?
-        log "No metrics to flush"
-        background_submission_finished
-        return
-      end
-
-      log "Drained #{drained.size} metric keys for submission"
-      posted = @pool.post do
-        submit_to_cloud(drained)
-      ensure
-        background_submission_finished
-      end
-      background_submission_finished unless posted
-    rescue => e
-      background_submission_finished
-      warn "[Flare] Metric drain error: #{e.message}"
-    end
-
-    def submit_to_cloud(drained)
-      _response, error = @submitter.submit(drained)
-      if error
-        warn "[Flare] Metric submission error: #{error.message}"
-      end
-    rescue => e
-      warn "[Flare] Metric submission error: #{e.message}"
-    end
-
-    def reserve_background_submission
-      @submission_mutex.synchronize do
-        return false if @flush_owner || @pending_submissions.positive?
-
-        @pending_submissions += 1
-        true
-      end
-    end
-
-    def background_submission_finished
-      @submission_mutex.synchronize do
-        @pending_submissions -= 1 if @pending_submissions.positive?
-        @submission_condition.broadcast
-      end
-    end
-
-    def flush_synchronously(deadline)
-      return [0, nil, true] unless begin_synchronous_flush(deadline)
-
-      record_health_metrics
-      drained = @storage.drain
-      return [0, nil, false] if drained.empty?
-
-      submit_with_deadline(drained, deadline)
-    ensure
-      finish_synchronous_flush if @flush_owner == Thread.current
-    end
-
-    def begin_synchronous_flush(deadline)
-      @submission_mutex.synchronize do
-        while @flush_owner && @flush_owner != Thread.current
-          return false if deadline.expired?
-
-          @submission_condition.wait(@submission_mutex, deadline.remaining)
-        end
-        @flush_owner = Thread.current
-
-        while @pending_submissions.positive?
-          return false if deadline.expired?
-
-          @submission_condition.wait(@submission_mutex, deadline.remaining)
-        end
-      end
-      true
-    end
-
-    def finish_synchronous_flush
-      @submission_mutex.synchronize do
-        @flush_owner = nil
-        @submission_condition.broadcast
-      end
-    end
-
-    def submit_metrics(drained, timeout:)
-      parameters = @submitter.method(:submit).parameters
-      accepts_timeout = parameters.any? do |type, name|
-        type == :keyrest || ([:key, :keyreq].include?(type) && name == :timeout)
-      end
-
-      if accepts_timeout
-        @submitter.submit(drained, timeout: timeout)
-      else
-        @submitter.submit(drained)
-      end
-    end
-
-    def submit_with_deadline(drained, deadline)
-      operation = { done: false, count: 0, error: nil }
-      @submission_mutex.synchronize { @pending_submissions += 1 }
-      Thread.new do
-        operation[:count], operation[:error] = submit_metrics(drained, timeout: deadline.remaining)
-      rescue => e
-        operation[:error] = e
-      ensure
-        @submission_mutex.synchronize do
-          operation[:done] = true
-          @pending_submissions -= 1
-          @submission_condition.broadcast
-        end
-      end
-
-      @submission_mutex.synchronize do
-        until operation[:done]
-          return [0, nil, true] if deadline.expired?
-
-          @submission_condition.wait(@submission_mutex, deadline.remaining)
-        end
-      end
-
-      timed_out = deadline.expired? || deadline_error?(operation[:error])
-      [operation[:count], operation[:error], timed_out]
-    end
-
-    def deadline_error?(error)
-      defined?(MetricSubmitter::DeadlineExceeded) && error.is_a?(MetricSubmitter::DeadlineExceeded)
-    end
-
-    def record_health_metrics
-      @health_reporters.each { |reporter| reporter.record(@storage) }
-    rescue => e
-      warn "[Flare] Health metric recording error: #{e.message}"
-    end
-
-    def log(message)
-      Flare.log(message) if Flare.respond_to?(:log)
-    end
-  end
-end

data/lib/flare/metric_key.rb

@@ -1,42 +0,0 @@
-# frozen_string_literal: true
-
-module Flare
-  # Identifies a unique metric for aggregation.
-  # Immutable and hashable for use as Concurrent::Map keys.
-  class MetricKey
-    attr_reader :bucket, :namespace, :service, :target, :operation
-
-    def initialize(bucket:, namespace:, service:, target:, operation:)
-      @bucket = bucket
-      @namespace = namespace.to_s.freeze
-      @service = service.to_s.freeze
-      @target = target&.to_s&.freeze
-      @operation = operation.to_s.freeze
-      freeze
-    end
-
-    def eql?(other)
-      self.class.eql?(other.class) &&
-        bucket == other.bucket &&
-        namespace == other.namespace &&
-        service == other.service &&
-        target == other.target &&
-        operation == other.operation
-    end
-    alias == eql?
-
-    def hash
-      [self.class, bucket, namespace, service, target, operation].hash
-    end
-
-    def to_h
-      {
-        bucket: bucket,
-        namespace: namespace,
-        service: service,
-        target: target,
-        operation: operation
-      }
-    end
-  end
-end