flare 0.4.0 → 1.0.0

data/lib/flare/sampler.rb

@@ -1,130 +0,0 @@
-# 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/source_location.rb

@@ -1,113 +0,0 @@
-# frozen_string_literal: true
-
-module Flare
-  # Utility for finding the source location (file, line, method) of app code
-  # that triggered a database query or other instrumented operation.
-  module SourceLocation
-    # How many app code lines to capture for the backtrace
-    MAX_TRACE_LINES = 8
-
-    # Patterns to filter out from backtraces (gems, framework code)
-    IGNORE_PATTERNS = [
-      /\/gems\//,
-      /\/ruby\//,
-      /\/rubygems\//,
-      /lib\/active_record/,
-      /lib\/active_support/,
-      /lib\/action_/,
-      /opentelemetry/,
-      /flare/,
-      /<internal:/,
-      /\/bin\//,
-    ].freeze
-
-    module_function
-
-    # Find the first app source location from the current backtrace
-    # Returns a hash with :filepath, :lineno, :function or nil
-    def find
-      backtrace = caller(2, 50)
-      return nil unless backtrace
-
-      # Find the first line that's app code (not gems/framework)
-      app_line = backtrace.find { |line| app_code?(line) }
-      return nil unless app_line
-
-      parse_backtrace_line(app_line)
-    end
-
-    # Find multiple app source locations from the current backtrace
-    # Returns an array of cleaned backtrace lines (up to MAX_TRACE_LINES)
-    def find_trace
-      backtrace = caller(2, 100)
-      return [] unless backtrace
-
-      # Filter to only app code lines
-      app_lines = backtrace.select { |line| app_code?(line) }
-      return [] if app_lines.empty?
-
-      # Clean and format each line, limit to MAX_TRACE_LINES
-      app_lines.first(MAX_TRACE_LINES).map { |line| clean_backtrace_line(line) }
-    end
-
-    # Add source location attributes to a hash (for span attributes)
-    def add_to_attributes(attrs)
-      location = find
-      return attrs unless location
-
-      attrs["code.filepath"] = location[:filepath]
-      attrs["code.lineno"] = location[:lineno]
-      attrs["code.function"] = location[:function] if location[:function]
-
-      # Add full trace as a single string attribute
-      trace = find_trace
-      attrs["code.stacktrace"] = trace.join("\n") if trace.any?
-
-      attrs
-    end
-
-    def app_code?(line)
-      # Must contain /app/ (Rails convention) and not match ignore patterns
-      return false unless line.include?("/app/")
-
-      IGNORE_PATTERNS.none? { |pattern| line.match?(pattern) }
-    end
-
-    def parse_backtrace_line(line)
-      # Parse: /path/to/file.rb:123:in `method_name'
-      if line =~ /\A(.+):(\d+):in [`'](.+)'\z/
-        {
-          filepath: clean_path($1),
-          lineno: $2.to_i,
-          function: $3
-        }
-      elsif line =~ /\A(.+):(\d+)\z/
-        {
-          filepath: clean_path($1),
-          lineno: $2.to_i,
-          function: nil
-        }
-      end
-    end
-
-    def clean_backtrace_line(line)
-      # Parse and reformat: "app/models/user.rb:42:in `find_by_email'"
-      if line =~ /\A(.+):(\d+):in [`'](.+)'\z/
-        "#{clean_path($1)}:#{$2} in `#{$3}'"
-      elsif line =~ /\A(.+):(\d+)\z/
-        "#{clean_path($1)}:#{$2}"
-      else
-        clean_path(line)
-      end
-    end
-
-    def clean_path(path)
-      # Remove Rails.root prefix if present
-      if defined?(Rails) && Rails.respond_to?(:root) && Rails.root
-        path.sub(/\A#{Regexp.escape(Rails.root.to_s)}\//, "")
-      else
-        path
-      end
-    end
-  end
-end

data/lib/flare/sqlite_exporter.rb

@@ -1,334 +0,0 @@
-# frozen_string_literal: true
-
-require "sqlite3"
-require "json"
-
-require_relative "deadline"
-
-module Flare
-  class SQLiteExporter
-    SUCCESS = OpenTelemetry::SDK::Trace::Export::SUCCESS
-    FAILURE = OpenTelemetry::SDK::Trace::Export::FAILURE
-    TIMEOUT = OpenTelemetry::SDK::Trace::Export::TIMEOUT
-
-    # Prune roughly every 100 exports (1% chance per export)
-    PRUNE_PROBABILITY = 0.01
-
-    def initialize(database_path)
-      @database_path = database_path
-      @mutex = Mutex.new
-      @setup = false
-      @pid = $$
-    end
-
-    # Maximum number of retry attempts when the database is busy.
-    # Mirrors ActiveRecord's retry strategy for SQLite.
-    MAX_RETRIES = 3
-    ExportDeadlineExceeded = Class.new(StandardError)
-
-    def export(span_datas, timeout: nil)
-      detect_forking
-      deadline = Deadline.new(timeout)
-
-      retries = 0
-      exported = 0
-
-      begin
-        setup_database(deadline) unless @setup
-        raise ExportDeadlineExceeded if deadline.expired?
-        raise ExportDeadlineExceeded unless lock_before_deadline(deadline)
-
-        begin
-          apply_busy_timeout(deadline)
-          connection.transaction do
-            span_datas.each do |span_data|
-              raise ExportDeadlineExceeded if deadline.expired?
-              next if should_ignore_span?(span_data)
-
-              create_span(span_data)
-              exported += 1
-            end
-          end
-        ensure
-          @mutex.unlock
-        end
-      rescue ExportDeadlineExceeded
-        return TIMEOUT
-      rescue ::SQLite3::BusyException
-        retries += 1
-        if retries <= MAX_RETRIES
-          sleep_time = 0.1 * retries
-          return TIMEOUT if deadline.remaining && sleep_time >= deadline.remaining
-
-          sleep(sleep_time)
-          retry
-        end
-        warn "[Flare] SQLite export error: database is busy after #{MAX_RETRIES} retries"
-        return FAILURE
-      end
-
-      Flare.log "Exported #{exported} spans to SQLite" if exported > 0 && Flare.respond_to?(:log)
-
-      # Periodically prune old data
-      maybe_prune unless deadline.expired?
-
-      deadline.expired? ? TIMEOUT : SUCCESS
-    rescue => e
-      warn "[Flare] SQLite export error: #{e.message}"
-      FAILURE
-    end
-
-    def force_flush(timeout: nil)
-      SUCCESS
-    end
-
-    def shutdown(timeout: nil)
-      SUCCESS
-    end
-
-    private
-
-    def detect_forking
-      return if @pid == $$
-
-      @pid = $$
-      @mutex = Mutex.new
-      close_connection
-    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 apply_busy_timeout(deadline)
-      remaining = deadline.remaining
-      timeout_ms = remaining ? [(remaining * 1_000).floor, 1].max : 5_000
-      connection.busy_timeout = [timeout_ms, 5_000].min
-    end
-
-    def maybe_prune
-      return unless rand < PRUNE_PROBABILITY
-
-      Flare.storage.prune(
-        retention_hours: Flare.configuration.retention_hours,
-        max_spans: Flare.configuration.max_spans
-      )
-    rescue => e
-      warn "[Flare] Prune error: #{e.message}"
-    end
-
-    def should_ignore_span?(span_data)
-      span_data.name&.start_with?("Flare::")
-    end
-
-    def create_span(span_data)
-      now = Time.now.iso8601(6)
-
-      sql = <<~SQL
-        INSERT INTO flare_spans (name, kind, span_id, trace_id, parent_span_id, start_timestamp, end_timestamp, total_recorded_links, total_recorded_events, total_recorded_properties, created_at, updated_at)
-        VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
-      SQL
-
-      values = [
-        span_data.name,
-        span_data.kind.to_s,
-        span_data.hex_span_id,
-        span_data.hex_trace_id,
-        span_data.hex_parent_span_id,
-        span_data.start_timestamp,
-        span_data.end_timestamp,
-        span_data.total_recorded_links,
-        span_data.total_recorded_events,
-        span_data.total_recorded_attributes,
-        now,
-        now
-      ]
-
-      connection.execute(sql, values)
-      span_record_id = connection.last_insert_row_id
-
-      span_data.events&.each do |span_event|
-        create_event(span_record_id, span_event)
-      end
-
-      create_properties("Flare::Span", span_record_id, span_data.attributes)
-    end
-
-    def create_event(span_record_id, span_event)
-      now = Time.now.iso8601(6)
-      timestamp = span_event.timestamp ? Time.at(span_event.timestamp / 1_000_000_000.0).iso8601(6) : now
-
-      sql = <<~SQL
-        INSERT INTO flare_events (span_id, name, created_at, updated_at)
-        VALUES (?, ?, ?, ?)
-      SQL
-
-      connection.execute(sql, [span_record_id, span_event.name, timestamp, now])
-      event_record_id = connection.last_insert_row_id
-      create_properties("Flare::Event", event_record_id, span_event.attributes)
-    end
-
-    def create_properties(owner_type, owner_id, attributes)
-      return unless attributes
-
-      now = Time.now.iso8601(6)
-
-      sql = <<~SQL
-        INSERT INTO flare_properties (key, value, value_type, owner_type, owner_id, created_at, updated_at)
-        VALUES (?, ?, ?, ?, ?, ?, ?)
-      SQL
-
-      attributes.each do |key, value|
-        next if value.nil?
-
-        value_type = determine_value_type(value)
-        serialized_value = JSON.generate(value)
-        connection.execute(sql, [key, serialized_value, value_type, owner_type, owner_id, now, now])
-      end
-    end
-
-    def determine_value_type(value)
-      case value
-      when String then 0  # string
-      when Integer then 1 # integer
-      when Float then 2   # float
-      when TrueClass, FalseClass then 3 # boolean
-      when Array then 4   # array
-      else 0              # default to string
-      end
-    end
-
-    def setup_database(deadline)
-      raise ExportDeadlineExceeded unless lock_before_deadline(deadline)
-
-      begin
-        return if @setup
-
-        db = connection
-        configure_pragmas(db, deadline)
-
-        execute_setup(db, deadline, <<~SQL)
-          CREATE TABLE IF NOT EXISTS flare_spans (
-            id INTEGER PRIMARY KEY AUTOINCREMENT,
-            name TEXT NOT NULL,
-            kind TEXT NOT NULL,
-            span_id TEXT NOT NULL,
-            trace_id TEXT NOT NULL,
-            parent_span_id TEXT,
-            start_timestamp INTEGER NOT NULL,
-            end_timestamp INTEGER NOT NULL,
-            total_recorded_properties INTEGER NOT NULL DEFAULT 0,
-            total_recorded_events INTEGER NOT NULL DEFAULT 0,
-            total_recorded_links INTEGER NOT NULL DEFAULT 0,
-            created_at TEXT NOT NULL,
-            updated_at TEXT NOT NULL
-          )
-        SQL
-
-        execute_setup(db, deadline, <<~SQL)
-          CREATE INDEX IF NOT EXISTS idx_spans_span_id ON flare_spans(span_id)
-        SQL
-
-        execute_setup(db, deadline, <<~SQL)
-          CREATE INDEX IF NOT EXISTS idx_spans_trace_id ON flare_spans(trace_id)
-        SQL
-
-        execute_setup(db, deadline, <<~SQL)
-          CREATE INDEX IF NOT EXISTS idx_spans_parent_span_id ON flare_spans(parent_span_id)
-        SQL
-
-        execute_setup(db, deadline, <<~SQL)
-          CREATE INDEX IF NOT EXISTS idx_spans_created_at ON flare_spans(created_at)
-        SQL
-
-        execute_setup(db, deadline, <<~SQL)
-          CREATE TABLE IF NOT EXISTS flare_events (
-            id INTEGER PRIMARY KEY AUTOINCREMENT,
-            span_id INTEGER NOT NULL,
-            name TEXT NOT NULL,
-            created_at TEXT NOT NULL,
-            updated_at TEXT NOT NULL,
-            FOREIGN KEY (span_id) REFERENCES flare_spans(id)
-          )
-        SQL
-
-        execute_setup(db, deadline, <<~SQL)
-          CREATE INDEX IF NOT EXISTS idx_events_span_id ON flare_events(span_id)
-        SQL
-
-        execute_setup(db, deadline, <<~SQL)
-          CREATE TABLE IF NOT EXISTS flare_properties (
-            id INTEGER PRIMARY KEY AUTOINCREMENT,
-            key TEXT NOT NULL,
-            value TEXT,
-            value_type INTEGER NOT NULL DEFAULT 0,
-            owner_type TEXT NOT NULL,
-            owner_id INTEGER NOT NULL,
-            created_at TEXT NOT NULL,
-            updated_at TEXT NOT NULL
-          )
-        SQL
-
-        execute_setup(db, deadline, <<~SQL)
-          CREATE INDEX IF NOT EXISTS idx_properties_owner ON flare_properties(owner_type, owner_id)
-        SQL
-
-        execute_setup(db, deadline, <<~SQL)
-          CREATE INDEX IF NOT EXISTS idx_properties_key ON flare_properties(key)
-        SQL
-
-        close_connection # avoid inheriting connection across fork
-        @setup = true
-      ensure
-        @mutex.unlock
-      end
-    end
-
-    # Applies the same SQLite pragmas that ActiveRecord uses for good
-    # concurrency and performance with threaded/multi-process access.
-    def configure_pragmas(db, deadline)
-      execute_setup(db, deadline, "PRAGMA journal_mode=WAL")
-      execute_setup(db, deadline, "PRAGMA synchronous=NORMAL")
-      execute_setup(db, deadline, "PRAGMA mmap_size=134217728")         # 128MB
-      execute_setup(db, deadline, "PRAGMA journal_size_limit=67108864") # 64MB
-      execute_setup(db, deadline, "PRAGMA cache_size=2000")
-    end
-
-    def execute_setup(db, deadline, statement)
-      raise ExportDeadlineExceeded if deadline.expired?
-
-      apply_busy_timeout(deadline)
-      db.execute(statement)
-      raise ExportDeadlineExceeded if deadline.expired?
-    end
-
-    def connection_key
-      :"flare_sqlite_db_#{@database_path.hash}"
-    end
-
-    def connection
-      Thread.current[connection_key] ||= begin
-        dir = File.dirname(@database_path)
-        FileUtils.mkdir_p(dir) unless File.directory?(dir)
-        db = ::SQLite3::Database.new(@database_path, results_as_hash: true)
-        db.busy_timeout = 5000
-        db
-      end
-    end
-
-    def close_connection
-      key = connection_key
-      if db = Thread.current[key]
-        db.close rescue nil
-        Thread.current[key] = nil
-      end
-    end
-  end
-end