catpm 0.1.0

data/lib/catpm/adapter/postgresql.rb

@@ -0,0 +1,186 @@
+# frozen_string_literal: true
+
+require 'zlib'
+
+module Catpm
+  module Adapter
+    module PostgreSQL
+      extend Base
+
+      class << self
+        def persist_buckets(aggregated_buckets)
+          return if aggregated_buckets.empty?
+
+          ActiveRecord::Base.connection_pool.with_connection do |conn|
+            aggregated_buckets.each_slice(Catpm.config.persistence_batch_size) do |batch|
+              batch.each do |bucket_data|
+                lock_id = advisory_lock_key(
+                  "bucket:#{bucket_data[:kind]}:#{bucket_data[:target]}:" \
+                  "#{bucket_data[:operation]}:#{bucket_data[:bucket_start]}"
+                )
+
+                ActiveRecord::Base.transaction do
+                  conn.execute("SELECT pg_advisory_xact_lock(#{lock_id})")
+
+                  existing = Catpm::Bucket.find_by(
+                    kind: bucket_data[:kind],
+                    target: bucket_data[:target],
+                    operation: bucket_data[:operation],
+                    bucket_start: bucket_data[:bucket_start]
+                  )
+
+                  if existing
+                    merged_metadata = merge_metadata_sum(
+                      existing.metadata_sum, bucket_data[:metadata_sum]
+                    )
+                    merged_digest = merge_digest(
+                      existing.p95_digest, bucket_data[:p95_digest]
+                    )
+
+                    existing.update!(
+                      count: existing.count + bucket_data[:count],
+                      success_count: existing.success_count + bucket_data[:success_count],
+                      failure_count: existing.failure_count + bucket_data[:failure_count],
+                      duration_sum: existing.duration_sum + bucket_data[:duration_sum],
+                      duration_max: [existing.duration_max, bucket_data[:duration_max]].max,
+                      duration_min: [existing.duration_min, bucket_data[:duration_min]].min,
+                      metadata_sum: merged_metadata,
+                      p95_digest: merged_digest
+                    )
+                  else
+                    Catpm::Bucket.create!(
+                      kind: bucket_data[:kind],
+                      target: bucket_data[:target],
+                      operation: bucket_data[:operation],
+                      bucket_start: bucket_data[:bucket_start],
+                      count: bucket_data[:count],
+                      success_count: bucket_data[:success_count],
+                      failure_count: bucket_data[:failure_count],
+                      duration_sum: bucket_data[:duration_sum],
+                      duration_max: bucket_data[:duration_max],
+                      duration_min: bucket_data[:duration_min],
+                      metadata_sum: bucket_data[:metadata_sum],
+                      p95_digest: bucket_data[:p95_digest]
+                    )
+                  end
+                end
+              end
+            end
+          end
+        end
+
+        def persist_event_buckets(event_buckets)
+          return if event_buckets.empty?
+
+          ActiveRecord::Base.connection_pool.with_connection do |conn|
+            event_buckets.each_slice(Catpm.config.persistence_batch_size) do |batch|
+              batch.each do |bucket_data|
+                lock_id = advisory_lock_key("event_bucket:#{bucket_data[:name]}:#{bucket_data[:bucket_start]}")
+
+                ActiveRecord::Base.transaction do
+                  conn.execute("SELECT pg_advisory_xact_lock(#{lock_id})")
+
+                  existing = Catpm::EventBucket.find_by(
+                    name: bucket_data[:name],
+                    bucket_start: bucket_data[:bucket_start]
+                  )
+
+                  if existing
+                    existing.update!(count: existing.count + bucket_data[:count])
+                  else
+                    Catpm::EventBucket.create!(
+                      name: bucket_data[:name],
+                      bucket_start: bucket_data[:bucket_start],
+                      count: bucket_data[:count]
+                    )
+                  end
+                end
+              end
+            end
+          end
+        end
+
+        def persist_event_samples(event_samples)
+          return if event_samples.empty?
+
+          ActiveRecord::Base.connection_pool.with_connection do
+            max = Catpm.config.events_max_samples_per_name
+
+            event_samples.each_slice(Catpm.config.persistence_batch_size) do |batch|
+              records = batch.map do |sample_data|
+                { name: sample_data[:name], payload: sample_data[:payload], recorded_at: sample_data[:recorded_at] }
+              end
+              Catpm::EventSample.insert_all(records) if records.any?
+            end
+
+            # Rotate: delete oldest samples beyond max per name
+            event_samples.map { |s| s[:name] }.uniq.each do |name|
+              count = Catpm::EventSample.where(name: name).count
+              if count > max
+                excess_ids = Catpm::EventSample.where(name: name)
+                  .order(recorded_at: :asc)
+                  .limit(count - max)
+                  .pluck(:id)
+                Catpm::EventSample.where(id: excess_ids).delete_all
+              end
+            end
+          end
+        end
+
+        def persist_errors(error_records)
+          return if error_records.empty?
+
+          ActiveRecord::Base.connection_pool.with_connection do |conn|
+            error_records.each_slice(Catpm.config.persistence_batch_size) do |batch|
+              batch.each do |error_data|
+                lock_id = advisory_lock_key("error:#{error_data[:fingerprint]}")
+
+                ActiveRecord::Base.transaction do
+                  conn.execute("SELECT pg_advisory_xact_lock(#{lock_id})")
+
+                  existing = Catpm::ErrorRecord.find_by(fingerprint: error_data[:fingerprint])
+
+                  if existing
+                    merged_contexts = merge_contexts(
+                      existing.parsed_contexts, error_data[:new_contexts]
+                    )
+
+                    attrs = {
+                      occurrences_count: existing.occurrences_count + error_data[:occurrences_count],
+                      last_occurred_at: [existing.last_occurred_at, error_data[:last_occurred_at]].max,
+                      contexts: merged_contexts
+                    }
+                    attrs[:resolved_at] = nil if existing.resolved?
+
+                    existing.update!(attrs)
+                  else
+                    Catpm::ErrorRecord.create!(
+                      fingerprint: error_data[:fingerprint],
+                      kind: error_data[:kind],
+                      error_class: error_data[:error_class],
+                      message: error_data[:message],
+                      occurrences_count: error_data[:occurrences_count],
+                      first_occurred_at: error_data[:first_occurred_at],
+                      last_occurred_at: error_data[:last_occurred_at],
+                      contexts: error_data[:new_contexts]
+                    )
+                  end
+                end
+              end
+            end
+          end
+        end
+
+        def modulo_bucket_sql(interval)
+          "EXTRACT(EPOCH FROM bucket_start)::integer % #{interval.to_i} = 0"
+        end
+
+        private
+
+        def advisory_lock_key(identifier)
+          Zlib.crc32(identifier.to_s) & 0x7FFFFFFF
+        end
+      end
+    end
+  end
+end

data/lib/catpm/adapter/sqlite.rb

@@ -0,0 +1,159 @@
+# frozen_string_literal: true
+
+module Catpm
+  module Adapter
+    module SQLite
+      extend Base
+
+      class << self
+        def persist_buckets(aggregated_buckets)
+          return if aggregated_buckets.empty?
+
+          with_write_lock do
+            aggregated_buckets.each do |bucket_data|
+              existing = Catpm::Bucket.find_by(
+                kind: bucket_data[:kind],
+                target: bucket_data[:target],
+                operation: bucket_data[:operation],
+                bucket_start: bucket_data[:bucket_start]
+              )
+
+              if existing
+                merged_metadata = merge_metadata_sum(
+                  existing.metadata_sum, bucket_data[:metadata_sum]
+                )
+                merged_digest = merge_digest(
+                  existing.p95_digest, bucket_data[:p95_digest]
+                )
+
+                existing.update!(
+                  count: existing.count + bucket_data[:count],
+                  success_count: existing.success_count + bucket_data[:success_count],
+                  failure_count: existing.failure_count + bucket_data[:failure_count],
+                  duration_sum: existing.duration_sum + bucket_data[:duration_sum],
+                  duration_max: [existing.duration_max, bucket_data[:duration_max]].max,
+                  duration_min: [existing.duration_min, bucket_data[:duration_min]].min,
+                  metadata_sum: merged_metadata.to_json,
+                  p95_digest: merged_digest
+                )
+              else
+                Catpm::Bucket.create!(
+                  kind: bucket_data[:kind],
+                  target: bucket_data[:target],
+                  operation: bucket_data[:operation],
+                  bucket_start: bucket_data[:bucket_start],
+                  count: bucket_data[:count],
+                  success_count: bucket_data[:success_count],
+                  failure_count: bucket_data[:failure_count],
+                  duration_sum: bucket_data[:duration_sum],
+                  duration_max: bucket_data[:duration_max],
+                  duration_min: bucket_data[:duration_min],
+                  metadata_sum: bucket_data[:metadata_sum]&.to_json,
+                  p95_digest: bucket_data[:p95_digest]
+                )
+              end
+            end
+          end
+        end
+
+        def persist_event_buckets(event_buckets)
+          return if event_buckets.empty?
+
+          with_write_lock do
+            event_buckets.each do |bucket_data|
+              existing = Catpm::EventBucket.find_by(
+                name: bucket_data[:name],
+                bucket_start: bucket_data[:bucket_start]
+              )
+
+              if existing
+                existing.update!(count: existing.count + bucket_data[:count])
+              else
+                Catpm::EventBucket.create!(
+                  name: bucket_data[:name],
+                  bucket_start: bucket_data[:bucket_start],
+                  count: bucket_data[:count]
+                )
+              end
+            end
+          end
+        end
+
+        def persist_event_samples(event_samples)
+          return if event_samples.empty?
+
+          max = Catpm.config.events_max_samples_per_name
+
+          with_write_lock do
+            event_samples.each_slice(Catpm.config.persistence_batch_size) do |batch|
+              records = batch.map do |sample_data|
+                { name: sample_data[:name], payload: sample_data[:payload]&.to_json, recorded_at: sample_data[:recorded_at] }
+              end
+              Catpm::EventSample.insert_all(records) if records.any?
+            end
+
+            event_samples.map { |s| s[:name] }.uniq.each do |name|
+              count = Catpm::EventSample.where(name: name).count
+              if count > max
+                excess_ids = Catpm::EventSample.where(name: name)
+                  .order(recorded_at: :asc)
+                  .limit(count - max)
+                  .pluck(:id)
+                Catpm::EventSample.where(id: excess_ids).delete_all
+              end
+            end
+          end
+        end
+
+        def persist_errors(error_records)
+          return if error_records.empty?
+
+          with_write_lock do
+            error_records.each do |error_data|
+              existing = Catpm::ErrorRecord.find_by(fingerprint: error_data[:fingerprint])
+
+              if existing
+                merged_contexts = merge_contexts(
+                  existing.parsed_contexts, error_data[:new_contexts]
+                )
+
+                attrs = {
+                  occurrences_count: existing.occurrences_count + error_data[:occurrences_count],
+                  last_occurred_at: [existing.last_occurred_at, error_data[:last_occurred_at]].max,
+                  contexts: merged_contexts.to_json
+                }
+                attrs[:resolved_at] = nil if existing.resolved?
+
+                existing.update!(attrs)
+              else
+                Catpm::ErrorRecord.create!(
+                  fingerprint: error_data[:fingerprint],
+                  kind: error_data[:kind],
+                  error_class: error_data[:error_class],
+                  message: error_data[:message],
+                  occurrences_count: error_data[:occurrences_count],
+                  first_occurred_at: error_data[:first_occurred_at],
+                  last_occurred_at: error_data[:last_occurred_at],
+                  contexts: error_data[:new_contexts].to_json
+                )
+              end
+            end
+          end
+        end
+
+        def modulo_bucket_sql(interval)
+          "CAST(strftime('%s', bucket_start) AS INTEGER) % #{interval.to_i} = 0"
+        end
+
+        private
+
+        def with_write_lock(&block)
+          ActiveRecord::Base.connection_pool.with_connection do |conn|
+            conn.raw_connection.busy_timeout = Catpm.config.sqlite_busy_timeout
+            ActiveRecord::Base.transaction(&block)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/catpm/adapter.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+require 'catpm/adapter/base'
+require 'catpm/adapter/sqlite'
+require 'catpm/adapter/postgresql'
+
+module Catpm
+  module Adapter
+    def self.current
+      @current ||= resolve
+    end
+
+    def self.reset!
+      @current = nil
+    end
+
+    def self.resolve
+      adapter_name = ActiveRecord::Base.connection.adapter_name
+      case adapter_name
+      when /SQLite/i     then Catpm::Adapter::SQLite
+      when /PostgreSQL/i then Catpm::Adapter::PostgreSQL
+      else
+        raise Catpm::UnsupportedAdapter,
+          "catpm does not support #{adapter_name}. Supported: PostgreSQL, SQLite."
+      end
+    end
+  end
+end

data/lib/catpm/auto_instrument.rb

@@ -0,0 +1,145 @@
+# frozen_string_literal: true
+
+module Catpm
+  # Zero-config service auto-instrumentation.
+  #
+  # Detects common service base classes (ApplicationService, BaseService)
+  # and prepends span tracking on their .call class method. Since subclasses
+  # inherit .call from the base, ALL service objects get instrumented
+  # automatically — no code changes, no configuration lists.
+  #
+  # The typical Rails service pattern:
+  #   class ApplicationService
+  #     def self.call(...) = new(...).call
+  #   end
+  #
+  #   class Sync::Processor < ApplicationService
+  #     def call = ...
+  #   end
+  #
+  # After auto-instrumentation, Sync::Processor.call creates a span
+  # named "Sync::Processor#call" that wraps the entire service execution.
+  #
+  # Custom base classes:
+  #   Catpm.configure { |c| c.service_base_classes = ["MyBase"] }
+  #
+  # Explicit method list for edge cases:
+  #   Catpm.configure do |c|
+  #     c.auto_instrument_methods = ["Worker#process", "Gateway.charge"]
+  #   end
+  #
+  module AutoInstrument
+    DEFAULT_SERVICE_BASES = %w[
+      ApplicationService
+      BaseService
+    ].freeze
+
+    class << self
+      def apply!
+        instrument_service_bases
+        instrument_explicit_methods
+      end
+
+      def reset!
+        @applied = Set.new
+        @bases_applied = Set.new
+      end
+
+      private
+
+      # ─── Auto-detect service base classes ───
+
+      def instrument_service_bases
+        @bases_applied ||= Set.new
+
+        bases = Catpm.config.service_base_classes
+        bases = DEFAULT_SERVICE_BASES if bases.nil?
+
+        bases.each do |base_name|
+          next if @bases_applied.include?(base_name)
+
+          begin
+            klass = Object.const_get(base_name)
+          rescue NameError
+            next
+          end
+
+          next unless klass.is_a?(Class)
+
+          # Prepend on the class-level .call so ALL subclasses get instrumented.
+          # Since subclasses inherit .call from the base and only override
+          # instance #call, this single prepend covers everything.
+          if klass.respond_to?(:call)
+            # Guard against double-prepend (e.g. code reloading in development)
+            already = klass.singleton_class.ancestors.any? do |a|
+              a.instance_variable_defined?(:@catpm_service_span)
+            end
+            next if already
+
+            mod = Module.new do
+              @catpm_service_span = true
+
+              define_method(:call) do |*args, **kwargs, &block|
+                Catpm.span("#{name}#call", type: :code) { super(*args, **kwargs, &block) }
+              end
+            end
+            klass.singleton_class.prepend(mod)
+          end
+
+          @bases_applied << base_name
+        end
+      end
+
+      # ─── Explicit method list ───
+
+      def instrument_explicit_methods
+        methods = Catpm.config.auto_instrument_methods
+        return if methods.nil? || methods.empty?
+
+        @applied ||= Set.new
+
+        methods.each do |method_spec|
+          next if @applied.include?(method_spec)
+
+          if method_spec.include?('#')
+            class_name, method_name = method_spec.split('#', 2)
+            instrument_instance_method(class_name, method_name, method_spec)
+          elsif method_spec.include?('.')
+            class_name, method_name = method_spec.split('.', 2)
+            instrument_class_method(class_name, method_name, method_spec)
+          end
+        end
+      end
+
+      def instrument_instance_method(class_name, method_name, spec)
+        klass = Object.const_get(class_name)
+        span_name = spec
+
+        mod = Module.new do
+          define_method(method_name.to_sym) do |*args, **kwargs, &block|
+            Catpm.span(span_name) { super(*args, **kwargs, &block) }
+          end
+        end
+        klass.prepend(mod)
+        @applied << spec
+      rescue NameError
+        nil
+      end
+
+      def instrument_class_method(class_name, method_name, spec)
+        klass = Object.const_get(class_name)
+        span_name = spec
+
+        mod = Module.new do
+          define_method(method_name.to_sym) do |*args, **kwargs, &block|
+            Catpm.span(span_name) { super(*args, **kwargs, &block) }
+          end
+        end
+        klass.singleton_class.prepend(mod)
+        @applied << spec
+      rescue NameError
+        nil
+      end
+    end
+  end
+end

data/lib/catpm/buffer.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+module Catpm
+  class Buffer
+    attr_reader :current_bytes, :dropped_count
+
+    def initialize(max_bytes:)
+      @monitor = Monitor.new
+      @events = []
+      @current_bytes = 0
+      @max_bytes = max_bytes
+      @dropped_count = 0
+    end
+
+    # Called from request threads. Returns :accepted or :dropped.
+    # Never blocks — monitoring must not slow down the application.
+    def push(event)
+      @monitor.synchronize do
+        bytes = event.estimated_bytes
+        if @current_bytes + bytes > @max_bytes
+          @dropped_count += 1
+          Catpm.stats[:dropped_events] += 1
+          return :dropped
+        end
+
+        @events << event
+        @current_bytes += bytes
+        :accepted
+      end
+    end
+
+    # Called from flusher thread. Atomically swaps out the entire buffer.
+    # Returns the array of events and resets internal state.
+    def drain
+      @monitor.synchronize do
+        events = @events
+        @events = []
+        @current_bytes = 0
+        events
+      end
+    end
+
+    def size
+      @monitor.synchronize { @events.size }
+    end
+
+    def empty?
+      @monitor.synchronize { @events.empty? }
+    end
+
+    def reset!
+      @monitor.synchronize do
+        @events = []
+        @current_bytes = 0
+        @dropped_count = 0
+      end
+    end
+  end
+end

data/lib/catpm/circuit_breaker.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+module Catpm
+  class CircuitBreaker
+    attr_reader :state
+
+    def initialize(failure_threshold: Catpm.config.circuit_breaker_failure_threshold, recovery_timeout: Catpm.config.circuit_breaker_recovery_timeout)
+      @failure_threshold = failure_threshold
+      @recovery_timeout = recovery_timeout
+      @failures = 0
+      @state = :closed
+      @opened_at = nil
+      @mutex = Mutex.new
+    end
+
+    def open?
+      @mutex.synchronize do
+        case @state
+        when :closed
+          false
+        when :open
+          if Time.now - @opened_at >= @recovery_timeout
+            @state = :half_open
+            false # Allow one probe attempt
+          else
+            true
+          end
+        when :half_open
+          false
+        end
+      end
+    end
+
+    def record_success
+      @mutex.synchronize do
+        @failures = 0
+        @state = :closed
+      end
+    end
+
+    def record_failure
+      @mutex.synchronize do
+        @failures += 1
+        if @failures >= @failure_threshold
+          @state = :open
+          @opened_at = Time.now
+          Catpm.stats[:circuit_opens] += 1
+        end
+      end
+    end
+
+    def reset!
+      @mutex.synchronize do
+        @failures = 0
+        @state = :closed
+        @opened_at = nil
+      end
+    end
+  end
+end