flare 0.1.1 → 0.3.0

data/lib/flare/metric_flusher.rb

@@ -15,11 +15,12 @@ module Flare
 
     attr_reader :interval, :shutdown_timeout
 
-    def initialize(storage:, submitter:, interval: DEFAULT_INTERVAL, shutdown_timeout: DEFAULT_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
     end
@@ -44,7 +45,7 @@ module Flare
 
       @stopped = true
 
-      Flare.log "Shutting down metrics flusher, draining remaining metrics..."
+      log "Shutting down metrics flusher, draining remaining metrics..."
 
       if @timer
         @timer.shutdown
@@ -59,7 +60,7 @@ module Flare
         @pool.kill unless pool_terminated
       end
 
-      Flare.log "Metrics flusher stopped"
+      log "Metrics flusher stopped"
     end
 
     def restart
@@ -72,6 +73,7 @@ module Flare
     def flush_now
       return 0 unless @storage && @submitter
 
+      record_health_metrics
       drained = @storage.drain
       return 0 if drained.empty?
 
@@ -100,13 +102,14 @@ module Flare
     private
 
     def post_to_pool
+      record_health_metrics
       drained = @storage.drain
       if drained.empty?
-        Flare.log "No metrics to flush"
+        log "No metrics to flush"
         return
       end
 
-      Flare.log "Drained #{drained.size} metric keys for submission"
+      log "Drained #{drained.size} metric keys for submission"
       @pool.post { submit_to_cloud(drained) }
     rescue => e
       warn "[Flare] Metric drain error: #{e.message}"
@@ -120,5 +123,15 @@ module Flare
     rescue => e
       warn "[Flare] Metric submission error: #{e.message}"
     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_span_processor.rb

@@ -156,7 +156,7 @@ module Flare
         bucket: bucket_time(span),
         namespace: "job",
         service: extract_job_system(span),
-        target: transaction_name || span.attributes["code.namespace"] || span.attributes["messaging.destination"] || "unknown",
+        target: transaction_name || span.attributes["code.namespace"] || span.attributes["messaging.sidekiq.job_class"] || span.attributes["messaging.destination"] || "unknown",
         operation: transaction_name ? "perform" : (span.attributes["code.function"] || span.name)
       )
 

data/lib/flare/metric_storage.rb

@@ -16,6 +16,11 @@ module Flare
       counter.increment(duration_ms: duration_ms, error: error)
     end
 
+    def add(key, count:, sum_ms:, error_count: 0)
+      counter = @storage.compute_if_absent(key) { MetricCounter.new }
+      counter.add(count: count, sum_ms: sum_ms, error_count: error_count)
+    end
+
     # Atomically retrieves and clears all metrics.
     # Returns a frozen hash of MetricKey => counter data.
     def drain

data/lib/flare/rule_manager.rb

@@ -0,0 +1,140 @@
+# frozen_string_literal: true
+
+require "json"
+require "logger"
+require "concurrent/timer_task"
+require "concurrent/atomic/atomic_fixnum"
+
+require_relative "http_transport"
+
+module Flare
+  # The SDK's only poll. Every interval seconds (default 30) it does a
+  # GET /api/rules; the 200 response carries the active TraceRules (with
+  # server-computed sample_rate) plus a bag of presigned R2 PUT URLs.
+  # We hand the rules to Sampler#update_rules and the URLs to
+  # UploadUrlPool#replace, and sweep the Marker so stuck rack-span
+  # entries don't linger.
+  #
+  # ETag-guarded: subsequent polls send If-None-Match. A 304 still gets
+  # us a Marker.sweep but doesn't touch sampler or pool. 401/403 stops
+  # the poller (misconfigured token shouldn't beat down the server).
+  # 5xx and exceptions are logged + counted; the timer just tries again
+  # on the next tick.
+  #
+  # Fork-safe: after_fork clears the pool and restarts the timer in the
+  # child process so each child polls independently.
+  class RuleManager
+    DEFAULT_INTERVAL = 30
+
+    attr_reader :poll_count, :etag, :stopped_due_to_auth, :last_error_count
+
+    def initialize(sampler:, marker:, pool:, base_url:, api_key:, project:, environment:,
+                   interval: DEFAULT_INTERVAL, transport: nil, logger: nil)
+      @sampler     = sampler
+      @marker      = marker
+      @pool        = pool
+      @rules_url   = "#{base_url.to_s.chomp('/')}/api/rules"
+      @api_key     = api_key
+      @project     = project
+      @environment = environment
+      @interval    = interval
+      @transport   = transport || HttpTransport.new
+      @logger      = logger || Logger.new($stderr, level: Logger::WARN)
+
+      @etag = nil
+      @poll_count          = Concurrent::AtomicFixnum.new(0)
+      @last_error_count    = Concurrent::AtomicFixnum.new(0)
+      @stopped_due_to_auth = false
+      @pid                 = $$
+    end
+
+    def start
+      return self if @timer || @stopped_due_to_auth
+
+      @timer = Concurrent::TimerTask.execute(
+        execution_interval: @interval,
+        run_now:            true,
+        name:               "flare-rule-manager-timer"
+      ) { poll_safely }
+      self
+    end
+
+    def stop
+      if @timer
+        @timer.shutdown
+        @timer.wait_for_termination(1)
+        @timer.kill unless @timer.shutdown?
+        @timer = nil
+      end
+      self
+    end
+
+    def running?
+      @timer ? @timer.running? : false
+    end
+
+    def after_fork
+      @pid = $$
+      @pool.after_fork
+      stop
+      start
+    end
+
+    # Public so callers can force a poll (tests + integration tests).
+    def poll_now
+      poll_safely
+    end
+
+    private
+
+    def poll_safely
+      poll
+    rescue StandardError => e
+      @last_error_count.increment
+      @logger.warn("[Flare::RuleManager] poll exception: #{e.class}: #{e.message}")
+    end
+
+    def poll
+      return if @stopped_due_to_auth
+
+      response = @transport.get(@rules_url, request_headers)
+      @poll_count.increment
+
+      case response.code
+      when "304"
+        @marker.sweep
+      when "200"
+        @etag = response.header("ETag")
+        apply(JSON.parse(response.body))
+        @marker.sweep
+      when "401", "403"
+        @stopped_due_to_auth = true
+        @logger.warn("[Flare::RuleManager] auth failed (#{response.code}); stopping poll")
+        stop
+      else
+        @last_error_count.increment
+        @logger.warn("[Flare::RuleManager] unexpected #{response.code}")
+      end
+    end
+
+    def request_headers
+      headers = {
+        "Authorization"     => "Bearer #{@api_key}",
+        "Flare-Project"     => @project,
+        "Flare-Environment" => @environment
+      }
+      headers["If-None-Match"] = @etag if @etag
+      headers
+    end
+
+    # Server payload shape (see tirana-v2 Api::RulesController):
+    #   { "trace_rules": [{ "id", "match_attributes", "rate", ..., "urls": [...] }] }
+    def apply(payload)
+      rules = payload["trace_rules"] || []
+      @sampler.update_rules(rules)
+
+      url_entries = rules.flat_map { |r| Array(r["urls"]) }
+      @pool.replace(url_entries)
+    end
+  end
+end

data/lib/flare/sampler.rb

@@ -0,0 +1,130 @@
+# frozen_string_literal: true
+
+require "concurrent/atomic/atomic_reference"
+require "opentelemetry/sdk"
+
+module Flare
+  # Path 1 trace sampler. At span start, iterates active rules; returns
+  # RECORD_AND_SAMPLE when one matches and the deterministic trace_id_ratio
+  # falls under the rule's rate. Otherwise RECORD_ONLY -- the span still
+  # records so MetricSpanProcessor sees it; the trace export decision for
+  # web spans is deferred to Path 2 via Flare::Marker.
+  #
+  # Used as the `root` sampler inside an OTel ParentBased sampler so root
+  # spans go through this logic but child spans inherit upstream decisions.
+  # The `local_parent_not_sampled` slot of the ParentBased should point at
+  # Flare::ALWAYS_RECORD_ONLY -- the default ALWAYS_OFF would drop children
+  # of an unsampled local parent, making them NoOp spans the processors
+  # never see.
+  #
+  # Rules are pushed in via update_rules from Flare::RuleManager; the swap
+  # is atomic, and malformed rule entries are dropped with a counter so a
+  # bad server payload can't crash the tracing path.
+  class Sampler
+    Decision = OpenTelemetry::SDK::Trace::Samplers::Decision
+    Result   = OpenTelemetry::SDK::Trace::Samplers::Result
+
+    RULE_ID_ATTRIBUTE = "flare.rule_id"
+
+    Rule = Struct.new(:id, :match_attributes, :rate, keyword_init: true)
+
+    attr_reader :dropped_rule_count
+
+    def initialize
+      @rules_ref = Concurrent::AtomicReference.new([].freeze)
+      @dropped_rule_count = Concurrent::AtomicFixnum.new(0)
+    end
+
+    # new_rules: an array of rule hashes from GET /api/rules, e.g.
+    #   [{ "id" => 1, "match_attributes" => {...}, "rate" => 0.5 }, ...]
+    # Entries that don't validate are skipped (counted in dropped_rule_count).
+    def update_rules(new_rules)
+      validated = (new_rules || []).filter_map { |r| validate(r) }
+      @dropped_rule_count.increment((new_rules || []).length - validated.length)
+      @rules_ref.set(validated.freeze)
+    end
+
+    def rules
+      @rules_ref.get
+    end
+
+    def should_sample?(trace_id:, parent_context:, links:, name:, kind:, attributes:)
+      tracestate = tracestate_from(parent_context)
+
+      rules.each do |rule|
+        next unless matches?(rule, attributes)
+        next unless trace_id_ratio(trace_id) < rule.rate
+
+        merged = (attributes || {}).merge(RULE_ID_ATTRIBUTE => rule.id)
+        return Result.new(decision: Decision::RECORD_AND_SAMPLE, attributes: merged, tracestate: tracestate)
+      end
+
+      Result.new(decision: Decision::RECORD_ONLY, tracestate: tracestate)
+    end
+
+    def description
+      "Flare::Sampler"
+    end
+
+    # Cross-language formula: last 8 bytes of the 16-byte raw trace_id as
+    # uint64-big-endian, divided by 2^64. Same in every Flare SDK so the
+    # server can reproduce the decision if it ever needs to.
+    def trace_id_ratio(trace_id)
+      bytes = trace_id.is_a?(String) ? trace_id.bytes : Array(trace_id)
+      tail = bytes.last(8)
+      n = 0
+      tail.each { |b| n = (n << 8) | b }
+      n.to_f / (1 << 64)
+    end
+
+    private
+
+    def tracestate_from(parent_context)
+      OpenTelemetry::Trace.current_span(parent_context).context.tracestate ||
+        OpenTelemetry::Trace::Tracestate::DEFAULT
+    end
+
+    def matches?(rule, attributes)
+      return false if attributes.nil?
+      rule.match_attributes.all? { |k, v| attributes[k] == v }
+    end
+
+    def validate(raw)
+      return nil unless raw.is_a?(Hash)
+
+      id    = raw["id"] || raw[:id]
+      match = raw["match_attributes"] || raw[:match_attributes]
+      rate  = raw["rate"] || raw[:rate]
+
+      return nil if id.nil?
+      return nil unless match.is_a?(Hash) && match.any?
+      return nil unless match.all? { |k, v| k.is_a?(String) && v.is_a?(String) && !v.empty? }
+      return nil unless rate.is_a?(Numeric) && rate > 0.0 && rate <= 1.0
+
+      Rule.new(id: id, match_attributes: match, rate: rate.to_f)
+    rescue StandardError
+      nil
+    end
+  end
+
+  # Tiny sampler whose should_sample? returns RECORD_ONLY for every span.
+  # Slot this into the ParentBased local_parent_not_sampled position so
+  # children of an unsampled local parent stay recording (the default
+  # ALWAYS_OFF turns them into NoOp spans no processor ever sees).
+  class AlwaysRecordOnly
+    Decision = OpenTelemetry::SDK::Trace::Samplers::Decision
+    Result   = OpenTelemetry::SDK::Trace::Samplers::Result
+
+    def should_sample?(parent_context: nil, **)
+      tracestate = OpenTelemetry::Trace.current_span(parent_context).context.tracestate ||
+        OpenTelemetry::Trace::Tracestate::DEFAULT
+      Result.new(decision: Decision::RECORD_ONLY, tracestate: tracestate)
+    end
+
+    def description
+      "Flare::AlwaysRecordOnly"
+    end
+  end
+
+  ALWAYS_RECORD_ONLY = AlwaysRecordOnly.new
+end

data/lib/flare/storage/sqlite.rb

@@ -34,25 +34,25 @@ module Flare
         if status
           case status
           when "2xx"
-            conditions << "status_prop.value LIKE ?"
+            conditions << "COALESCE(status_prop.value, status_prop_old.value) LIKE ?"
             values << "2%"
           when "3xx"
-            conditions << "status_prop.value LIKE ?"
+            conditions << "COALESCE(status_prop.value, status_prop_old.value) LIKE ?"
             values << "3%"
           when "4xx"
-            conditions << "status_prop.value LIKE ?"
+            conditions << "COALESCE(status_prop.value, status_prop_old.value) LIKE ?"
             values << "4%"
           when "5xx"
-            conditions << "status_prop.value LIKE ?"
+            conditions << "COALESCE(status_prop.value, status_prop_old.value) LIKE ?"
             values << "5%"
           else
-            conditions << "status_prop.value = ?"
+            conditions << "COALESCE(status_prop.value, status_prop_old.value) = ?"
             values << status.to_s
           end
         end
 
         if method
-          conditions << "method_prop.value = ?"
+          conditions << "COALESCE(method_prop.value, method_prop_old.value) = ?"
           values << "\"#{method}\""
         end
 
@@ -79,19 +79,22 @@ module Flare
 
         rows = query_all(<<~SQL, values)
           SELECT s.*,
-                 method_prop.value as http_method,
-                 status_prop.value as http_status,
-                 target_prop.value as http_target,
+                 COALESCE(method_prop.value, method_prop_old.value) as http_method,
+                 COALESCE(status_prop.value, status_prop_old.value) as http_status,
+                 COALESCE(target_prop.value, target_prop_old.value) as http_target,
                  controller_prop.value as controller,
                  action_prop.value as action
           FROM flare_spans s
-          LEFT JOIN flare_properties method_prop ON method_prop.owner_type = 'Flare::Span' AND method_prop.owner_id = s.id AND method_prop.key = 'http.method'
-          LEFT JOIN flare_properties status_prop ON status_prop.owner_type = 'Flare::Span' AND status_prop.owner_id = s.id AND status_prop.key = 'http.status_code'
-          LEFT JOIN flare_properties target_prop ON target_prop.owner_type = 'Flare::Span' AND target_prop.owner_id = s.id AND target_prop.key = 'http.target'
+          LEFT JOIN flare_properties method_prop ON method_prop.owner_type = 'Flare::Span' AND method_prop.owner_id = s.id AND method_prop.key = 'http.request.method'
+          LEFT JOIN flare_properties method_prop_old ON method_prop_old.owner_type = 'Flare::Span' AND method_prop_old.owner_id = s.id AND method_prop_old.key = 'http.method'
+          LEFT JOIN flare_properties status_prop ON status_prop.owner_type = 'Flare::Span' AND status_prop.owner_id = s.id AND status_prop.key = 'http.response.status_code'
+          LEFT JOIN flare_properties status_prop_old ON status_prop_old.owner_type = 'Flare::Span' AND status_prop_old.owner_id = s.id AND status_prop_old.key = 'http.status_code'
+          LEFT JOIN flare_properties target_prop ON target_prop.owner_type = 'Flare::Span' AND target_prop.owner_id = s.id AND target_prop.key = 'url.path'
+          LEFT JOIN flare_properties target_prop_old ON target_prop_old.owner_type = 'Flare::Span' AND target_prop_old.owner_id = s.id AND target_prop_old.key = 'http.target'
           LEFT JOIN flare_properties controller_prop ON controller_prop.owner_type = 'Flare::Span' AND controller_prop.owner_id = s.id AND controller_prop.key = 'code.namespace'
           LEFT JOIN flare_properties action_prop ON action_prop.owner_type = 'Flare::Span' AND action_prop.owner_id = s.id AND action_prop.key = 'code.function'
           #{where_clause}
-          AND method_prop.value IS NOT NULL
+          AND COALESCE(method_prop.value, method_prop_old.value) IS NOT NULL
           ORDER BY s.created_at DESC
           LIMIT ? OFFSET ?
         SQL
@@ -352,25 +355,25 @@ module Flare
         if status
           case status
           when "2xx"
-            conditions << "status_prop.value LIKE ?"
+            conditions << "COALESCE(status_prop.value, status_prop_old.value) LIKE ?"
             values << "2%"
           when "3xx"
-            conditions << "status_prop.value LIKE ?"
+            conditions << "COALESCE(status_prop.value, status_prop_old.value) LIKE ?"
             values << "3%"
           when "4xx"
-            conditions << "status_prop.value LIKE ?"
+            conditions << "COALESCE(status_prop.value, status_prop_old.value) LIKE ?"
             values << "4%"
           when "5xx"
-            conditions << "status_prop.value LIKE ?"
+            conditions << "COALESCE(status_prop.value, status_prop_old.value) LIKE ?"
             values << "5%"
           else
-            conditions << "status_prop.value = ?"
+            conditions << "COALESCE(status_prop.value, status_prop_old.value) = ?"
             values << status.to_s
           end
         end
 
         if method
-          conditions << "method_prop.value = ?"
+          conditions << "COALESCE(method_prop.value, method_prop_old.value) = ?"
           values << "\"#{method}\""
         end
 
@@ -396,11 +399,13 @@ module Flare
         row = query_one(<<~SQL, values)
           SELECT COUNT(*) as count
           FROM flare_spans s
-          LEFT JOIN flare_properties method_prop ON method_prop.owner_type = 'Flare::Span' AND method_prop.owner_id = s.id AND method_prop.key = 'http.method'
-          LEFT JOIN flare_properties status_prop ON status_prop.owner_type = 'Flare::Span' AND status_prop.owner_id = s.id AND status_prop.key = 'http.status_code'
+          LEFT JOIN flare_properties method_prop ON method_prop.owner_type = 'Flare::Span' AND method_prop.owner_id = s.id AND method_prop.key = 'http.request.method'
+          LEFT JOIN flare_properties method_prop_old ON method_prop_old.owner_type = 'Flare::Span' AND method_prop_old.owner_id = s.id AND method_prop_old.key = 'http.method'
+          LEFT JOIN flare_properties status_prop ON status_prop.owner_type = 'Flare::Span' AND status_prop.owner_id = s.id AND status_prop.key = 'http.response.status_code'
+          LEFT JOIN flare_properties status_prop_old ON status_prop_old.owner_type = 'Flare::Span' AND status_prop_old.owner_id = s.id AND status_prop_old.key = 'http.status_code'
           LEFT JOIN flare_properties controller_prop ON controller_prop.owner_type = 'Flare::Span' AND controller_prop.owner_id = s.id AND controller_prop.key = 'code.namespace'
           #{where_clause}
-          AND method_prop.value IS NOT NULL
+          AND COALESCE(method_prop.value, method_prop_old.value) IS NOT NULL
         SQL
 
         row ? row["count"] : 0

data/lib/flare/trace_blob.rb

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