flare 0.4.0 → 1.0.0

data/lib/flare/storage.rb

@@ -1,54 +0,0 @@
-# frozen_string_literal: true
-
-module Flare
-  module Storage
-    class Base
-      def save_case(attributes)
-        raise NotImplementedError
-      end
-
-      def save_clues(clues)
-        raise NotImplementedError
-      end
-
-      def find_case(uuid)
-        raise NotImplementedError
-      end
-
-      def list_cases(type: nil, status: nil, method: nil, name: nil, origin: nil, limit: 50, offset: 0)
-        raise NotImplementedError
-      end
-
-      def clues_for_case(case_uuid)
-        raise NotImplementedError
-      end
-
-      def list_clues(type: nil, search: nil, limit: 50, offset: 0)
-        raise NotImplementedError
-      end
-
-      def find_clue(id)
-        raise NotImplementedError
-      end
-
-      def prune(retention_hours:, max_cases:)
-        raise NotImplementedError
-      end
-
-      def clear_all
-        raise NotImplementedError
-      end
-
-      def count_cases(type: nil, status: nil, method: nil, name: nil, origin: nil)
-        raise NotImplementedError
-      end
-
-      def count_clues(type: nil, search: nil)
-        raise NotImplementedError
-      end
-    end
-  end
-end
-
-  # storage/sqlite is loaded on demand when spans are enabled
-  # to avoid requiring sqlite3 in production environments

data/lib/flare/trace_blob.rb

@@ -1,116 +0,0 @@
-# frozen_string_literal: true
-
-require "time"
-
-module Flare
-  # Value object that turns a group of OTel span_data for a single trace
-  # into the Flare-JSON wire format the server expects:
-  #
-  #   {
-  #     "trace_id":       "<hex>",
-  #     "trace_rule_id":  <int|nil>,
-  #     "root_name":      "<string>",
-  #     "started_at":     "<iso8601>",
-  #     "duration_ms":    <int>,
-  #     "spans": [
-  #       { "id", "parent_id", "name", "started_at",
-  #         "duration_ms", "attributes" }
-  #     ]
-  #   }
-  #
-  # The trace_rule_id is read from any span carrying the
-  # `flare.rule_id` attribute (Path 1 sets it on the sampled root, Path 2
-  # sets it on the rack owner span via WebMarkerSubscriber).
-  class TraceBlob
-    ZERO_SPAN_ID = ("\x00".b * 8).freeze
-    ROOT_NAME_LIMIT = 255
-
-    def self.build(trace_id:, spans:)
-      return nil if spans.nil? || spans.empty?
-      new(trace_id: trace_id, spans: spans)
-    end
-
-    def initialize(trace_id:, spans:)
-      @trace_id = trace_id
-      @spans    = spans
-    end
-
-    def to_h
-      root = find_root
-      {
-        "trace_id"      => hexify(@trace_id),
-        "trace_rule_id" => rule_id_from_spans,
-        "root_name"     => root_name(root),
-        "started_at"    => iso(root&.start_timestamp),
-        "duration_ms"   => duration_ms(root),
-        "spans"         => @spans.map { |s| span_to_h(s) }
-      }
-    end
-
-    private
-
-    def find_root
-      @spans.find { |s| entry_span?(s) && rule_id_attribute(s) } ||
-        @spans.find { |s| root?(s) } ||
-        @spans.find { |s| entry_span?(s) } ||
-        @spans.find { |s| rule_id_attribute(s) } ||
-        @spans.first
-    end
-
-    def root?(span)
-      pid = span.parent_span_id
-      pid.nil? || pid.empty? || pid == ZERO_SPAN_ID
-    end
-
-    def entry_span?(span)
-      return false unless span.respond_to?(:kind)
-
-      span.kind == :server || span.kind == :consumer
-    end
-
-    def rule_id_from_spans
-      @spans.each do |s|
-        value = rule_id_attribute(s)
-        return value if value
-      end
-      nil
-    end
-
-    def rule_id_attribute(span)
-      attrs = span.attributes
-      return nil unless attrs
-
-      attrs[Sampler::RULE_ID_ATTRIBUTE] || attrs[Sampler::RULE_ID_ATTRIBUTE.to_sym]
-    end
-
-    def root_name(root)
-      root&.name&.to_s&.slice(0, ROOT_NAME_LIMIT)
-    end
-
-    def span_to_h(span)
-      {
-        "id"          => hexify(span.span_id),
-        "parent_id"   => root?(span) ? nil : hexify(span.parent_span_id),
-        "name"        => span.name,
-        "started_at"  => iso(span.start_timestamp),
-        "duration_ms" => duration_ms(span),
-        "attributes"  => span.attributes || {}
-      }
-    end
-
-    def hexify(bytes)
-      return nil if bytes.nil?
-      bytes.unpack1("H*")
-    end
-
-    def iso(nanos)
-      return nil if nanos.nil?
-      Time.at(nanos / 1_000_000_000.0).utc.iso8601(6)
-    end
-
-    def duration_ms(span)
-      return nil unless span && span.start_timestamp && span.end_timestamp
-      ((span.end_timestamp - span.start_timestamp) / 1_000_000).to_i
-    end
-  end
-end

data/lib/flare/trace_exporter.rb

@@ -1,182 +0,0 @@
-# frozen_string_literal: true
-
-require "json"
-require "zlib"
-require "stringio"
-require "logger"
-require "uri"
-require "concurrent/atomic/atomic_fixnum"
-require "opentelemetry/sdk"
-
-require_relative "client_headers"
-require_relative "sampler"
-require_relative "trace_blob"
-require_relative "http_transport"
-require_relative "deadline"
-
-module Flare
-  # Custom OTel exporter. For each batch FilteringSpanProcessor hands over:
-  #
-  #   1. Group spans by trace_id.
-  #   2. For each trace, build a Flare::TraceBlob and gzip-JSON-encode it.
-  #   3. Check out a presigned R2 PUT URL from UploadUrlPool.
-  #   4. PUT the gzipped body straight to R2 -- Flare's server is NOT in
-  #      the trace-bytes path.
-  #   5. After R2 returns 200, POST /api/traces { key } using the
-  #      customer's push token + Flare-Project / Flare-Environment headers.
-  #      That's the self-notify hop the design swapped in for the CF Worker.
-  #
-  # 403 from R2 means the presigned URL expired between issue and use;
-  # discard, check out the next URL, retry once. Pool empty -> FAILURE.
-  # Notify-POST failure is logged + counted but doesn't fail the export
-  # (the blob is in R2, just won't be processed; incoming/* lifecycle
-  # cleans it up in 1hr).
-  class TraceExporter
-    SUCCESS = OpenTelemetry::SDK::Trace::Export::SUCCESS
-    FAILURE = OpenTelemetry::SDK::Trace::Export::FAILURE
-    TIMEOUT = OpenTelemetry::SDK::Trace::Export::TIMEOUT
-
-    PUT_HEADERS = {
-      "Content-Type"     => "application/json",
-      "Content-Encoding" => "gzip"
-    }.freeze
-
-    attr_reader :put_failure_count, :notify_failure_count, :pool_empty_count, :exception_count
-
-    def initialize(pool:, notify_url:, api_key:, project:, environment:,
-                   transport: nil, logger: nil)
-      @pool         = pool
-      @notify_url   = notify_url.to_s
-      @api_key      = api_key
-      @project      = project
-      @environment  = environment
-      @transport    = transport || HttpTransport.new
-      @logger       = logger || Logger.new($stderr, level: Logger::WARN)
-
-      @put_failure_count    = Concurrent::AtomicFixnum.new(0)
-      @notify_failure_count = Concurrent::AtomicFixnum.new(0)
-      @pool_empty_count     = Concurrent::AtomicFixnum.new(0)
-      @exception_count      = Concurrent::AtomicFixnum.new(0)
-    end
-
-    def export(spans, timeout: nil)
-      deadline = Deadline.new(timeout)
-      grouped = spans.group_by(&:trace_id)
-      return SUCCESS if grouped.empty?
-
-      overall = SUCCESS
-      grouped.each do |trace_id, group|
-        return TIMEOUT if deadline.expired?
-
-        result = ship(TraceBlob.build(trace_id: trace_id, spans: group), deadline: deadline)
-        return TIMEOUT if result == TIMEOUT || deadline.expired?
-        overall = FAILURE if result == FAILURE
-      end
-      overall
-    rescue StandardError => e
-      return TIMEOUT if deadline&.expired? || e.is_a?(HttpTransport::DeadlineExceeded)
-
-      @exception_count.increment
-      @logger.warn("[Flare::TraceExporter] export raised: #{e.class}: #{e.message}")
-      FAILURE
-    end
-
-    def force_flush(timeout: nil)
-      SUCCESS
-    end
-
-    def shutdown(timeout: nil)
-      SUCCESS
-    end
-
-    private
-
-    def ship(blob, deadline:, retried: false)
-      return FAILURE if blob.nil?
-      return TIMEOUT if deadline.expired?
-
-      entry = @pool.checkout
-      if entry.nil?
-        @pool_empty_count.increment
-        return FAILURE
-      end
-
-      body = gzip(JSON.generate(blob.to_h))
-      response = transport_request(:put, entry[:put_url], body, PUT_HEADERS, timeout: deadline.remaining)
-      return TIMEOUT if deadline.expired?
-
-      case response.code
-      when "200", "204"
-        notify(entry[:key], deadline: deadline)
-      when "403"
-        # Presigned URL probably expired; try once more with the next one.
-        retried ? record_put_failure(response) : ship(blob, deadline: deadline, retried: true)
-      else
-        record_put_failure(response)
-      end
-    end
-
-    def notify(key, deadline:)
-      return TIMEOUT if deadline.expired?
-
-      response = transport_request(
-        :post,
-        @notify_url,
-        JSON.generate(key: key),
-        notify_headers,
-        timeout: deadline.remaining
-      )
-      return TIMEOUT if deadline.expired?
-      return SUCCESS if response.code == "202"
-
-      @notify_failure_count.increment
-      @logger.warn("[Flare::TraceExporter] notify failed: HTTP #{response.code}")
-      SUCCESS
-    rescue StandardError => e
-      return TIMEOUT if deadline.expired? || e.is_a?(HttpTransport::DeadlineExceeded)
-
-      @notify_failure_count.increment
-      @logger.warn("[Flare::TraceExporter] notify exception: #{e.class}: #{e.message}")
-      SUCCESS
-    end
-
-    def transport_request(method, *args, timeout:)
-      parameters = @transport.method(method).parameters
-      accepts_timeout = parameters.any? do |type, name|
-        type == :keyrest || ([:key, :keyreq].include?(type) && name == :timeout)
-      end
-
-      if accepts_timeout
-        @transport.public_send(method, *args, timeout: timeout)
-      else
-        @transport.public_send(method, *args)
-      end
-    end
-
-    # Identifies the client on the Flare-API notify POST. The presigned R2
-    # PUT in #ship deliberately uses PUT_HEADERS only -- adding these there
-    # could invalidate the signed-header set.
-    def notify_headers
-      ClientHeaders.to_h.merge(
-        "Content-Type"      => "application/json",
-        "Authorization"     => "Bearer #{@api_key}",
-        "Flare-Project"     => @project,
-        "Flare-Environment" => @environment
-      )
-    end
-
-    def record_put_failure(response)
-      @put_failure_count.increment
-      @logger.warn("[Flare::TraceExporter] PUT failed: HTTP #{response.code}")
-      FAILURE
-    end
-
-    def gzip(body)
-      io = StringIO.new
-      gz = Zlib::GzipWriter.new(io)
-      gz.write(body)
-      gz.close
-      io.string
-    end
-  end
-end

data/lib/flare/trace_health_reporter.rb

@@ -1,74 +0,0 @@
-# frozen_string_literal: true
-
-require_relative "metric_key"
-
-module Flare
-  # Records client-side tracing health into MetricStorage so flare-web can
-  # warn when local buffering, URL exhaustion, or export errors reduce trace
-  # fidelity.
-  class TraceHealthReporter
-    NAMESPACE = "sdk"
-    SERVICE = "flare-ruby"
-    TARGET = "tracing"
-
-    def initialize(processor:, pool:, exporter:)
-      @processor = processor
-      @pool = pool
-      @exporter = exporter
-      @last = {}
-      @mutex = Mutex.new
-    end
-
-    def record(storage, bucket: Time.now.utc)
-      @mutex.synchronize do
-        record_counter(storage, bucket, "dropped_spans", @processor.dropped_count.value)
-        record_counter(storage, bucket, "export_failures", @processor.failed_export_count.value)
-        record_counter(storage, bucket, "processor_exceptions", @processor.exception_count.value)
-
-        record_counter(storage, bucket, "upload_url_pool_empty", @pool.empty_count.value)
-        record_counter(storage, bucket, "upload_url_expired", @pool.expired_count.value)
-
-        record_counter(storage, bucket, "r2_put_failures", @exporter.put_failure_count.value)
-        record_counter(storage, bucket, "notify_failures", @exporter.notify_failure_count.value)
-        record_counter(storage, bucket, "trace_pool_empty", @exporter.pool_empty_count.value)
-        record_counter(storage, bucket, "trace_export_exceptions", @exporter.exception_count.value)
-
-        buffer_size = @processor.buffer_size
-        buffer_high_watermark = @processor.buffer_high_watermark.value
-        record_gauge(storage, bucket, "buffer_size", buffer_size)
-        record_gauge(storage, bucket, "buffer_high_watermark", buffer_high_watermark)
-        record_gauge(storage, bucket, "buffer_limit", @processor.max_queue) if buffer_size.positive? || buffer_high_watermark.positive?
-        @processor.reset_buffer_high_watermark
-      end
-    end
-
-    private
-
-    def record_counter(storage, bucket, operation, current)
-      previous = @last.fetch(operation, 0)
-      @last[operation] = current
-      delta = current - previous
-      return unless delta.positive?
-
-      storage.add(key(bucket, operation), count: delta, sum_ms: 0, error_count: 0)
-    end
-
-    def record_gauge(storage, bucket, operation, value)
-      storage.add(key(bucket, operation), count: 1, sum_ms: value, error_count: 0)
-    end
-
-    def key(bucket, operation)
-      MetricKey.new(
-        bucket: bucket_time(bucket),
-        namespace: NAMESPACE,
-        service: SERVICE,
-        target: TARGET,
-        operation: operation
-      )
-    end
-
-    def bucket_time(time)
-      Time.utc(time.year, time.month, time.day, time.hour, time.min, 0)
-    end
-  end
-end

data/lib/flare/upload_url_pool.rb

@@ -1,108 +0,0 @@
-# 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 +0,0 @@
-# frozen_string_literal: true
-
-module Flare
-  VERSION = "0.4.0"
-end

data/lib/flare/web_marker_subscriber.rb

@@ -1,76 +0,0 @@
-# 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