flare 0.2.0 → 0.3.0

data/lib/flare/upload_url_pool.rb

@@ -0,0 +1,108 @@
+# frozen_string_literal: true
+
+require "concurrent/atomic/atomic_reference"
+
+module Flare
+  # Thread-safe pool of presigned R2 PUT URLs the RuleManager fills from
+  # the /api/rules response. TraceExporter checks one out before each
+  # upload; if the pool is empty (no active rules, no fresh URLs) it
+  # returns nil and the exporter gives up on that batch -- caller decides
+  # what to do.
+  #
+  # Each entry is a Hash: { upload_id:, key:, put_url:, expires_at: }.
+  # expires_at is a Time; entries past their expiry are skipped on checkout.
+  #
+  # Fork-safe: after_fork clears the pool so child processes don't reuse
+  # parent URLs (each child polls its own copy from /api/rules anyway).
+  class UploadUrlPool
+    attr_reader :checkouts, :empty_count, :expired_count
+
+    def initialize
+      @entries_ref   = Concurrent::AtomicReference.new([].freeze)
+      @checkouts     = Concurrent::AtomicFixnum.new(0)
+      @empty_count   = Concurrent::AtomicFixnum.new(0)
+      @expired_count = Concurrent::AtomicFixnum.new(0)
+    end
+
+    def replace(entries)
+      normalized = (entries || []).filter_map { |raw| normalize(raw) }
+      @entries_ref.set(normalized.freeze)
+    end
+
+    def checkout
+      now = Time.now
+      loop do
+        current = @entries_ref.get
+        if current.empty?
+          @empty_count.increment
+          return nil
+        end
+
+        candidate, *rest = current
+        next_state = rest.freeze
+        next unless @entries_ref.compare_and_set(current, next_state)
+
+        if expired?(candidate, now)
+          @expired_count.increment
+          next # try the next one
+        end
+
+        @checkouts.increment
+        return candidate
+      end
+    end
+
+    def size
+      @entries_ref.get.length
+    end
+
+    def empty?
+      size.zero?
+    end
+
+    def clear
+      @entries_ref.set([].freeze)
+    end
+
+    # Drop URLs that have already passed their expires_at. Cheap; safe to
+    # call from RuleManager's scheduler in between polls.
+    def sweep
+      now = Time.now
+      current = @entries_ref.get
+      live    = current.reject { |e| expired?(e, now) }
+      return 0 if live.length == current.length
+
+      @entries_ref.set(live.freeze)
+      current.length - live.length
+    end
+
+    # Call from Flare.after_fork. Parent's URLs aren't usable from the
+    # child's point of view (each child should get its own from a fresh
+    # /api/rules poll), so just drop them.
+    def after_fork
+      clear
+    end
+
+    private
+
+    def normalize(raw)
+      h = raw.is_a?(Hash) ? raw : nil
+      return nil unless h
+
+      upload_id  = h[:upload_id] || h["upload_id"]
+      key        = h[:key]       || h["key"]
+      put_url    = h[:put_url]   || h["put_url"]
+      expires_at = h[:expires_at] || h["expires_at"]
+      return nil if upload_id.nil? || key.nil? || put_url.nil?
+
+      expires_at = Time.iso8601(expires_at) if expires_at.is_a?(String)
+      { upload_id: upload_id, key: key, put_url: put_url, expires_at: expires_at }
+    rescue StandardError
+      nil
+    end
+
+    def expired?(entry, now)
+      entry[:expires_at] && entry[:expires_at] <= now
+    end
+  end
+end

data/lib/flare/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Flare
-  VERSION = "0.2.0"
+  VERSION = "0.3.0"
 end

data/lib/flare/web_marker_subscriber.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+require "opentelemetry/sdk"
+
+module Flare
+  # Path 2: ActiveSupport::Notifications subscriber that fires on
+  # `start_processing.action_controller`, after Rails has routed to a
+  # controller#action. At that point the rack server span's start
+  # attributes don't yet carry code.namespace/code.function -- only the
+  # ActionPack instrumentation adds them, and Flare::Sampler's start-time
+  # decision (RECORD_ONLY) was already locked in.
+  #
+  # The subscriber consults the same sampler's rule set, finds any whose
+  # match_attributes match the now-known controller/action, applies the
+  # deterministic trace_id_ratio gate (CAF-1: no rate bypass on Path 2),
+  # and on pass calls marker.mark(trace_id, owner_span_id:, rule_id:).
+  # FilteringSpanProcessor then forwards every span in the trace to the
+  # exporter and unmarks when the owner (this rack span) finishes.
+  class WebMarkerSubscriber
+    NOTIFICATION = "start_processing.action_controller"
+
+    def initialize(sampler:, marker:)
+      @sampler = sampler
+      @marker = marker
+    end
+
+    def start
+      @subscriber = ActiveSupport::Notifications.subscribe(NOTIFICATION) do |*, payload|
+        handle(payload)
+      end
+      self
+    end
+
+    def stop
+      ActiveSupport::Notifications.unsubscribe(@subscriber) if @subscriber
+      @subscriber = nil
+      self
+    end
+
+    # Public for tests so they don't have to drive ActiveSupport::Notifications.
+    # current_span lets tests inject a context; in production it's the
+    # rack server span on the current thread.
+    def handle(payload, current_span: OpenTelemetry::Trace.current_span)
+      return unless current_span
+      ctx = current_span.context
+      return unless ctx && ctx.valid?
+
+      attrs = candidate_attributes(payload)
+      return if attrs.empty?
+
+      @sampler.rules.each do |rule|
+        next unless matches?(rule, attrs)
+        next unless @sampler.trace_id_ratio(ctx.trace_id) < rule.rate
+
+        current_span.set_attribute(Flare::Sampler::RULE_ID_ATTRIBUTE, rule.id) if current_span.respond_to?(:set_attribute)
+        @marker.mark(ctx.trace_id, owner_span_id: ctx.span_id, rule_id: rule.id)
+        break
+      end
+    end
+
+    private
+
+    def candidate_attributes(payload)
+      controller = payload[:controller] || payload["controller"]
+      action     = payload[:action]     || payload["action"]
+      {
+        "code.namespace" => controller,
+        "code.function"  => action
+      }.compact
+    end
+
+    def matches?(rule, attrs)
+      rule.match_attributes.all? { |k, v| attrs[k] == v }
+    end
+  end
+end

data/lib/flare.rb

@@ -13,6 +13,15 @@ require_relative "flare/metric_flusher"
 require_relative "flare/backoff_policy"
 require_relative "flare/metric_submitter"
 
+require_relative "flare/sampler"
+require_relative "flare/marker"
+require_relative "flare/web_marker_subscriber"
+require_relative "flare/filtering_span_processor"
+require_relative "flare/upload_url_pool"
+require_relative "flare/trace_exporter"
+require_relative "flare/rule_manager"
+require_relative "flare/trace_health_reporter"
+
 module Flare
   class Error < StandardError; end
 
@@ -114,15 +123,43 @@ module Flare
     @metric_flusher = flusher
   end
 
+  # Trace-sampling components, exposed for tests + manual after_fork wiring.
+  def sampler         = @sampler
+  def marker          = @marker
+  def upload_url_pool = @upload_url_pool
+  def rule_manager    = @rule_manager
+  def trace_span_processor = @trace_span_processor
+  def trace_health_reporter = @trace_health_reporter
+
   # Manually flush metrics (useful for testing or forced flushes).
   def flush_metrics
     @metric_flusher&.flush_now || 0
   end
 
-  # Re-initialize metric flusher after fork.
+  # Default project key, derived from the host Rails app's module name.
+  # Customers can override by configuring something else once we expose
+  # configuration.project; for v0.3 this matches MetricSubmitter's behavior.
+  def service_name_for_app
+    if defined?(Rails) && Rails.respond_to?(:application) && Rails.application
+      Rails.application.class.module_parent_name.underscore rescue "rails_app"
+    else
+      "app"
+    end
+  end
+
+  def rails_env_name
+    if defined?(Rails) && Rails.respond_to?(:env)
+      Rails.env.to_s
+    else
+      ENV.fetch("RACK_ENV", "development")
+    end
+  end
+
+  # Re-initialize background threads after fork.
   # Call this from Puma/Unicorn after_fork hooks.
   def after_fork
     @metric_flusher&.after_fork
+    @rule_manager&.after_fork
   end
 
   # Configure OpenTelemetry SDK and instrumentations. Must run before the
@@ -135,11 +172,7 @@ module Flare
     # Suppress noisy OTel INFO logs
     OpenTelemetry.logger = Logger.new(STDOUT, level: Logger::WARN)
 
-    service_name = if defined?(Rails) && Rails.application
-      Rails.application.class.module_parent_name.underscore rescue "rails_app"
-    else
-      "app"
-    end
+    service_name = service_name_for_app
 
     # Require flare's bundled instrumentations
     require "opentelemetry-instrumentation-rack"
@@ -201,12 +234,98 @@ module Flare
         span_processor.shutdown
         log "Span processor flushed and stopped"
       end
+      if @trace_span_processor
+        @trace_span_processor.force_flush
+        @trace_span_processor.shutdown
+        log "Trace span processor flushed and stopped"
+      end
       log "Shutdown complete"
     end
 
     @otel_configured = true
   end
 
+  # Start the trace-rules poller. Polls GET /api/rules every
+  # tracing_poll_interval (default 30s) so the in-process sampler + URL
+  # pool stay current. Called from config.after_initialize -- after the
+  # user's configure block has run -- so configuration.url / .key /
+  # .tracing_enabled are settled.
+  def start_rule_manager
+    return unless configuration.tracing_submission_configured?
+
+    setup_tracing_components
+    return unless @sampler && @marker && @upload_url_pool
+
+    @rule_manager = RuleManager.new(
+      sampler:     @sampler,
+      marker:      @marker,
+      pool:        @upload_url_pool,
+      base_url:    configuration.url,
+      api_key:     configuration.key,
+      project:     service_name_for_app,
+      environment: rails_env_name,
+      interval:    configuration.tracing_poll_interval
+    )
+    @rule_manager.start
+    log "Rule manager started (poll=#{configuration.tracing_poll_interval}s)"
+
+    at_exit { @rule_manager&.stop }
+  end
+
+  def setup_tracing_components
+    return if @trace_span_processor
+
+    @sampler         = Sampler.new
+    @marker          = Marker.new
+    @upload_url_pool = UploadUrlPool.new
+
+    # Trace sampling: server-controlled per-route capture. The sampler runs
+    # at span start; for routes it can't decide there (Rails web spans get
+    # their controller#action attributes set post-routing) the marker +
+    # WebMarkerSubscriber handle it. The RECORD_ONLY delegates keep children
+    # of unsampled local and remote parents recording so processors still see
+    # web requests that arrive with an unsampled traceparent header.
+    #
+    # Sampler is set on the tracer_provider AFTER SDK.configure -- the SDK's
+    # Configurator block doesn't expose a `sampler=`; the provider does.
+    OpenTelemetry.tracer_provider.sampler =
+      OpenTelemetry::SDK::Trace::Samplers.parent_based(
+        root: @sampler,
+        remote_parent_sampled: ALWAYS_RECORD_ONLY,
+        remote_parent_not_sampled: ALWAYS_RECORD_ONLY,
+        local_parent_not_sampled: ALWAYS_RECORD_ONLY
+      )
+
+    @trace_exporter = TraceExporter.new(
+      pool:        @upload_url_pool,
+      notify_url:  "#{configuration.url.to_s.chomp('/')}/api/traces",
+      api_key:     configuration.key,
+      project:     service_name_for_app,
+      environment: rails_env_name
+    )
+
+    @trace_span_processor = FilteringSpanProcessor.new(
+      exporter: @trace_exporter,
+      marker: @marker,
+      max_queue: configuration.tracing_max_queue
+    )
+    OpenTelemetry.tracer_provider.add_span_processor(@trace_span_processor)
+
+    @trace_health_reporter = TraceHealthReporter.new(
+      processor: @trace_span_processor,
+      pool: @upload_url_pool,
+      exporter: @trace_exporter
+    )
+
+    # Path 2 trace marking. Rails-only -- in non-Rails contexts the
+    # subscriber would never fire but creating it is harmless.
+    if defined?(ActiveSupport::Notifications)
+      @web_marker_subscriber = WebMarkerSubscriber.new(sampler: @sampler, marker: @marker).start
+    end
+
+    log "Tracing enabled (poll=#{configuration.tracing_poll_interval}s)"
+  end
+
   # Start the metrics flusher. Called from config.after_initialize so
   # user configuration (metrics_enabled, flush_interval, etc.) is applied.
   def start_metrics_flusher
@@ -229,7 +348,8 @@ module Flare
       @metric_flusher = MetricFlusher.new(
         storage: @metric_storage,
         submitter: submitter,
-        interval: configuration.metrics_flush_interval
+        interval: configuration.metrics_flush_interval,
+        health_reporters: @trace_health_reporter ? [@trace_health_reporter] : []
       )
       @metric_flusher.start
       log "Metrics flusher started (interval=#{configuration.metrics_flush_interval}s)"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: flare
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.0
 platform: ruby
 authors:
 - John Nunemaker
@@ -198,18 +198,28 @@ files:
 - lib/flare/cli/status_command.rb
 - lib/flare/configuration.rb
 - lib/flare/engine.rb
+- lib/flare/filtering_span_processor.rb
 - lib/flare/http_metrics_config.rb
+- lib/flare/http_transport.rb
+- lib/flare/marker.rb
 - lib/flare/metric_counter.rb
 - lib/flare/metric_flusher.rb
 - lib/flare/metric_key.rb
 - lib/flare/metric_span_processor.rb
 - lib/flare/metric_storage.rb
 - lib/flare/metric_submitter.rb
+- lib/flare/rule_manager.rb
+- lib/flare/sampler.rb
 - lib/flare/source_location.rb
 - lib/flare/sqlite_exporter.rb
 - lib/flare/storage.rb
 - lib/flare/storage/sqlite.rb
+- lib/flare/trace_blob.rb
+- lib/flare/trace_exporter.rb
+- lib/flare/trace_health_reporter.rb
+- lib/flare/upload_url_pool.rb
 - lib/flare/version.rb
+- lib/flare/web_marker_subscriber.rb
 - public/flare-assets/flare.css
 - public/flare-assets/images/flipper.png
 homepage: https://github.com/jnunemaker/flare