catpm 0.1.0

data/lib/catpm/patches/net_http.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module Catpm
+  module Patches
+    module NetHttp
+      def request(req, body = nil, &block)
+        segments = Thread.current[:catpm_request_segments]
+        return super unless segments
+
+        start = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+        response = super
+        duration = (Process.clock_gettime(Process::CLOCK_MONOTONIC) - start) * 1000.0
+
+        detail = "#{req.method} #{@address}#{req.path} (#{response.code})"
+        source = duration >= Catpm.config.segment_source_threshold ? extract_catpm_source : nil
+
+        segments.add(
+          type: :http, duration: duration, detail: detail,
+          source: source, started_at: start
+        )
+
+        response
+      end
+
+      private
+
+      def extract_catpm_source
+        locations = caller_locations(2, 30)
+        locations&.each do |loc|
+          path = loc.path.to_s
+          if Catpm::Fingerprint.app_frame?(path)
+            return "#{path}:#{loc.lineno}"
+          end
+        end
+        nil
+      end
+    end
+  end
+end

data/lib/catpm/request_segments.rb

@@ -0,0 +1,101 @@
+# frozen_string_literal: true
+
+module Catpm
+  class RequestSegments
+    attr_reader :segments, :summary, :request_start
+
+    def initialize(max_segments:, request_start: nil, stack_sample: false)
+      @max_segments = max_segments
+      @request_start = request_start || Process.clock_gettime(Process::CLOCK_MONOTONIC)
+      @segments = []
+      @overflow = false
+      @summary = Hash.new(0)
+      @span_stack = []
+      @tracked_ranges = []
+
+      if stack_sample
+        @sampler = StackSampler.new(target_thread: Thread.current, request_start: @request_start)
+        @sampler.start
+      end
+    end
+
+    def add(type:, duration:, detail:, source: nil, started_at: nil)
+      type_key = type.to_sym
+      @summary[:"#{type_key}_count"] += 1
+      @summary[:"#{type_key}_duration"] += duration
+
+      offset = started_at ? ((started_at - @request_start) * 1000.0).round(2) : nil
+
+      segment = { type: type.to_s, duration: duration.round(2), detail: detail }
+      segment[:offset] = offset if offset
+      segment[:source] = source if source
+      segment[:parent_index] = @span_stack.last if @span_stack.any?
+
+      # Record time range so sampler can skip already-tracked periods
+      if started_at && duration > 0
+        @tracked_ranges << [started_at, started_at + duration / 1000.0]
+      end
+
+      if @segments.size < @max_segments
+        @segments << segment
+      else
+        @overflow = true
+        min_idx = @segments.each_with_index.min_by { |s, _| s[:duration] || Float::INFINITY }.last
+        if duration > (@segments[min_idx][:duration] || Float::INFINITY)
+          @segments[min_idx] = segment
+        end
+      end
+    end
+
+    def push_span(type:, detail:, started_at: nil)
+      offset = started_at ? ((started_at - @request_start) * 1000.0).round(2) : nil
+
+      segment = { type: type.to_s, detail: detail }
+      segment[:offset] = offset if offset
+      segment[:parent_index] = @span_stack.last if @span_stack.any?
+
+      return nil if @segments.size >= @max_segments
+
+      index = @segments.size
+      @segments << segment
+      @span_stack.push(index)
+      index
+    end
+
+    def pop_span(index)
+      return unless index
+
+      @span_stack.delete(index)
+      segment = @segments[index]
+      return unless segment
+
+      started_at = segment[:offset] ? @request_start + (segment[:offset] / 1000.0) : @request_start
+      duration = (Process.clock_gettime(Process::CLOCK_MONOTONIC) - started_at) * 1000.0
+      segment[:duration] = duration.round(2)
+
+      type_key = segment[:type].to_sym
+      @summary[:"#{type_key}_count"] += 1
+      @summary[:"#{type_key}_duration"] += duration
+    end
+
+    def stop_sampler
+      @sampler&.stop
+    end
+
+    def sampler_segments
+      @sampler&.to_segments(tracked_ranges: @tracked_ranges) || []
+    end
+
+    def overflowed?
+      @overflow
+    end
+
+    def to_h
+      {
+        segments: @segments,
+        segment_summary: @summary,
+        segments_capped: @overflow
+      }
+    end
+  end
+end

data/lib/catpm/segment_subscribers.rb

@@ -0,0 +1,242 @@
+# frozen_string_literal: true
+
+module Catpm
+  module SegmentSubscribers
+    # Subscriber with start/finish callbacks so all segments (SQL, views, etc.)
+    # fired during a controller action are automatically nested under the controller span.
+    class ControllerSpanSubscriber
+      def start(_name, _id, payload)
+        req_segments = Thread.current[:catpm_request_segments]
+        return unless req_segments
+
+        detail = "#{payload[:controller]}##{payload[:action]}"
+        started_at = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+        index = req_segments.push_span(type: :controller, detail: detail, started_at: started_at)
+        payload[:_catpm_controller_span_index] = index
+      end
+
+      def finish(_name, _id, payload)
+        req_segments = Thread.current[:catpm_request_segments]
+        return unless req_segments
+
+        req_segments.pop_span(payload[:_catpm_controller_span_index])
+      end
+    end
+
+    # Subscriber object with start/finish callbacks so SQL queries
+    # fired during view rendering are automatically nested under the view span.
+    class ViewSpanSubscriber
+      def start(_name, _id, payload)
+        req_segments = Thread.current[:catpm_request_segments]
+        return unless req_segments
+
+        identifier = payload[:identifier].to_s
+        if defined?(Rails.root) && identifier.start_with?(Rails.root.to_s)
+          identifier = identifier.sub("#{Rails.root}/", '')
+        end
+
+        started_at = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+        index = req_segments.push_span(type: :view, detail: identifier, started_at: started_at)
+        payload[:_catpm_span_index] = index
+      end
+
+      def finish(_name, _id, payload)
+        req_segments = Thread.current[:catpm_request_segments]
+        return unless req_segments
+
+        req_segments.pop_span(payload[:_catpm_span_index])
+      end
+    end
+
+    IGNORED_SQL_NAMES = Set.new([
+      'SCHEMA', 'EXPLAIN',
+      'ActiveRecord::SchemaMigration Load',
+      'ActiveRecord::InternalMetadata Load'
+    ]).freeze
+
+    class << self
+      def subscribe!
+        unsubscribe!
+
+        @controller_span_subscriber = ActiveSupport::Notifications.subscribe(
+          'process_action.action_controller', ControllerSpanSubscriber.new
+        )
+
+        @sql_subscriber = ActiveSupport::Notifications.subscribe(
+          'sql.active_record'
+        ) do |event|
+          record_sql_segment(event)
+        end
+
+        @instantiation_subscriber = ActiveSupport::Notifications.subscribe(
+          'instantiation.active_record'
+        ) do |event|
+          record_instantiation_segment(event)
+        end
+
+        @render_template_subscriber = ActiveSupport::Notifications.subscribe(
+          'render_template.action_view', ViewSpanSubscriber.new
+        )
+
+        @render_partial_subscriber = ActiveSupport::Notifications.subscribe(
+          'render_partial.action_view', ViewSpanSubscriber.new
+        )
+
+        @cache_read_subscriber = ActiveSupport::Notifications.subscribe(
+          'cache_read.active_support'
+        ) do |event|
+          record_cache_segment(event, 'read')
+        end
+
+        @cache_write_subscriber = ActiveSupport::Notifications.subscribe(
+          'cache_write.active_support'
+        ) do |event|
+          record_cache_segment(event, 'write')
+        end
+
+        if defined?(ActionMailer)
+          @mailer_subscriber = ActiveSupport::Notifications.subscribe(
+            'deliver.action_mailer'
+          ) do |event|
+            record_mailer_segment(event)
+          end
+        end
+
+        if defined?(ActiveStorage)
+          @storage_upload_subscriber = ActiveSupport::Notifications.subscribe(
+            'service_upload.active_storage'
+          ) do |event|
+            record_storage_segment(event, 'upload')
+          end
+
+          @storage_download_subscriber = ActiveSupport::Notifications.subscribe(
+            'service_download.active_storage'
+          ) do |event|
+            record_storage_segment(event, 'download')
+          end
+        end
+      end
+
+      def unsubscribe!
+        [
+          @controller_span_subscriber,
+          @sql_subscriber, @instantiation_subscriber,
+          @render_template_subscriber, @render_partial_subscriber,
+          @cache_read_subscriber, @cache_write_subscriber,
+          @mailer_subscriber, @storage_upload_subscriber, @storage_download_subscriber
+        ].each do |sub|
+          ActiveSupport::Notifications.unsubscribe(sub) if sub
+        end
+        @controller_span_subscriber = nil
+        @sql_subscriber = nil
+        @instantiation_subscriber = nil
+        @render_template_subscriber = nil
+        @render_partial_subscriber = nil
+        @cache_read_subscriber = nil
+        @cache_write_subscriber = nil
+        @mailer_subscriber = nil
+        @storage_upload_subscriber = nil
+        @storage_download_subscriber = nil
+      end
+
+      private
+
+      def record_instantiation_segment(event)
+        req_segments = Thread.current[:catpm_request_segments]
+        return unless req_segments
+
+        duration = event.duration
+        return if duration < 0.1 # skip trivial instantiations
+
+        payload = event.payload
+        record_count = payload[:record_count] || 0
+        class_name = payload[:class_name] || 'ActiveRecord'
+        detail = "#{class_name} x#{record_count}"
+        source = duration >= Catpm.config.segment_source_threshold ? extract_source_location : nil
+
+        # Fold into sql summary for cleaner breakdown
+        req_segments.add(
+          type: :sql, duration: duration, detail: detail,
+          source: source, started_at: event.time
+        )
+      end
+
+      def record_sql_segment(event)
+        req_segments = Thread.current[:catpm_request_segments]
+        return unless req_segments
+
+        payload = event.payload
+        return if payload[:name].nil? || IGNORED_SQL_NAMES.include?(payload[:name])
+        return if payload[:sql].nil?
+
+        duration = event.duration
+        sql = payload[:sql].to_s
+        source = duration >= Catpm.config.segment_source_threshold ? extract_source_location : nil
+
+        req_segments.add(
+          type: :sql, duration: duration, detail: sql,
+          source: source, started_at: event.time
+        )
+      end
+
+      def record_cache_segment(event, operation)
+        req_segments = Thread.current[:catpm_request_segments]
+        return unless req_segments
+
+        duration = event.duration
+        key = event.payload[:key].to_s
+        hit = event.payload[:hit]
+        detail = "cache.#{operation} #{key}"
+        detail += hit ? ' (hit)' : ' (miss)' if operation == 'read' && !hit.nil?
+        source = duration >= Catpm.config.segment_source_threshold ? extract_source_location : nil
+
+        req_segments.add(
+          type: :cache, duration: duration, detail: detail,
+          source: source, started_at: event.time
+        )
+      end
+
+      def record_mailer_segment(event)
+        req_segments = Thread.current[:catpm_request_segments]
+        return unless req_segments
+
+        payload = event.payload
+        mailer = payload[:mailer].to_s
+        to = Array(payload[:to]).first.to_s
+        detail = to.empty? ? mailer : "#{mailer} to #{to}"
+        source = event.duration >= Catpm.config.segment_source_threshold ? extract_source_location : nil
+
+        req_segments.add(
+          type: :mailer, duration: event.duration, detail: detail,
+          source: source, started_at: event.time
+        )
+      end
+
+      def record_storage_segment(event, operation)
+        req_segments = Thread.current[:catpm_request_segments]
+        return unless req_segments
+
+        payload = event.payload
+        key = payload[:key].to_s
+        detail = "#{operation} #{key}"
+        source = event.duration >= Catpm.config.segment_source_threshold ? extract_source_location : nil
+
+        req_segments.add(
+          type: :storage, duration: event.duration, detail: detail,
+          source: source, started_at: event.time
+        )
+      end
+
+      def extract_source_location
+        locations = caller_locations(4, 50)
+        locations&.each do |loc|
+          path = loc.path.to_s
+          if Fingerprint.app_frame?(path)
+            return "#{path}:#{loc.lineno}"
+          end
+        end
+        nil
+      end
+    end
+  end
+end

data/lib/catpm/span_helpers.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module Catpm
+  # Declarative method tracing, similar to Elastic APM's SpanHelpers.
+  #
+  #   class PaymentService
+  #     include Catpm::SpanHelpers
+  #
+  #     def process(order)
+  #       # ...
+  #     end
+  #     span_method :process
+  #
+  #     def self.bulk_charge(users)
+  #       # ...
+  #     end
+  #     span_class_method :bulk_charge
+  #   end
+  #
+  module SpanHelpers
+    def self.included(base)
+      base.extend(ClassMethods)
+    end
+
+    module ClassMethods
+      def span_method(method_name, span_name = nil)
+        method_name = method_name.to_sym
+        span_name ||= "#{name}##{method_name}"
+
+        mod = Module.new do
+          define_method(method_name) do |*args, **kwargs, &block|
+            Catpm.span(span_name) { super(*args, **kwargs, &block) }
+          end
+        end
+        prepend(mod)
+      end
+
+      def span_class_method(method_name, span_name = nil)
+        method_name = method_name.to_sym
+        span_name ||= "#{name}.#{method_name}"
+
+        mod = Module.new do
+          define_method(method_name) do |*args, **kwargs, &block|
+            Catpm.span(span_name) { super(*args, **kwargs, &block) }
+          end
+        end
+        singleton_class.prepend(mod)
+      end
+    end
+  end
+end

data/lib/catpm/stack_sampler.rb

@@ -0,0 +1,226 @@
+# frozen_string_literal: true
+
+module Catpm
+  class StackSampler
+    SAMPLE_INTERVAL = 0.005 # 5ms
+
+    def initialize(target_thread:, request_start:)
+      @target = target_thread
+      @request_start = request_start
+      @samples = []
+      @running = false
+    end
+
+    def start
+      @running = true
+      @thread = Thread.new do
+        while @running
+          locs = @target.backtrace_locations
+          @samples << [Process.clock_gettime(Process::CLOCK_MONOTONIC), locs] if locs
+          sleep(SAMPLE_INTERVAL)
+        end
+      end
+      @thread.priority = -1
+    end
+
+    def stop
+      @running = false
+      @thread&.join(0.1)
+    end
+
+    # Returns array of { parent: {segment}, children: [{segment}, ...] }
+    # Parent = app code frame that initiated the work
+    # Children = gem internals (collapsed by default in UI)
+    def to_segments(tracked_ranges: [])
+      return [] if @samples.size < 2
+
+      untracked = @samples.reject do |time, _|
+        tracked_ranges.any? { |s, e| time >= s && time <= e }
+      end
+      return [] if untracked.empty?
+
+      # Annotate: [time, app_frame (caller), leaf_frame (execution point)]
+      annotated = untracked.filter_map do |time, locs|
+        pair = extract_frame_pair(locs)
+        next unless pair
+        [time, pair[0], pair[1]]
+      end
+      return [] if annotated.empty?
+
+      # Group consecutive samples by app_frame
+      groups = []
+      current = nil
+
+      annotated.each do |time, app_frame, leaf_frame|
+        app_key = app_frame ? frame_key(app_frame) : nil
+
+        if current && current[:app_key] == app_key
+          current[:end_time] = time
+          current[:count] += 1
+          current[:leaves] << [time, leaf_frame]
+        else
+          groups << current if current
+          current = {
+            app_key: app_key,
+            app_frame: app_frame,
+            start_time: time,
+            end_time: time,
+            count: 1,
+            leaves: [[time, leaf_frame]]
+          }
+        end
+      end
+      groups << current if current
+
+      groups.filter_map do |group|
+        duration = estimate_duration(group)
+        next if duration < 1.0
+
+        offset = ((group[:start_time] - @request_start) * 1000.0).round(2)
+        app_frame = group[:app_frame]
+        leaf = group[:leaves].first&.last
+
+        # Build parent segment — always the app frame if available
+        if app_frame
+          app_path = app_frame.path.to_s
+          parent = {
+            type: 'code',
+            detail: build_app_detail(app_frame),
+            duration: duration.round(2),
+            offset: offset,
+            source: "#{app_path}:#{app_frame.lineno}",
+            started_at: group[:start_time]
+          }
+
+          # Children = gem internals (only if leaf differs from app frame)
+          children = build_children(group[:leaves])
+          # Skip children that are identical to parent (pure app code)
+          children.reject! { |c| c[:detail] == parent[:detail] }
+
+          { parent: parent, children: children }
+        elsif leaf
+          # No app frame — show leaf directly, no children
+          path = leaf.path.to_s
+          parent = {
+            type: classify_path(path),
+            detail: build_gem_detail(leaf),
+            duration: duration.round(2),
+            offset: offset,
+            started_at: group[:start_time]
+          }
+          { parent: parent, children: [] }
+        end
+      end
+    end
+
+    private
+
+    # Walk the stack: find the leaf (deepest interesting frame)
+    # and the app_frame (nearest app code above the leaf)
+    def extract_frame_pair(locations)
+      leaf_frame = nil
+      app_frame = nil
+
+      locations.each do |loc|
+        path = loc.path.to_s
+        next if path.start_with?('<internal:')
+        next if path.include?('/catpm/')
+        next if path.include?('/ruby/') && !path.include?('/gems/')
+
+        leaf_frame ||= loc
+
+        if Fingerprint.app_frame?(path)
+          app_frame = loc
+          break
+        end
+      end
+
+      return nil unless leaf_frame
+      [app_frame, leaf_frame]
+    end
+
+    def build_children(leaves)
+      spans = []
+      current = nil
+
+      leaves.each do |time, frame|
+        key = frame_key(frame)
+
+        if current && current[:key] == key
+          current[:end_time] = time
+          current[:count] += 1
+        else
+          spans << current if current
+          current = { key: key, frame: frame, start_time: time, end_time: time, count: 1 }
+        end
+      end
+      spans << current if current
+
+      spans.filter_map do |span|
+        duration = [
+          (span[:end_time] - span[:start_time]) * 1000.0,
+          span[:count] * SAMPLE_INTERVAL * 1000.0
+        ].max
+        next if duration < 1.0
+
+        frame = span[:frame]
+        path = frame.path.to_s
+
+        {
+          type: classify_path(path),
+          detail: build_gem_detail(frame),
+          duration: duration.round(2),
+          offset: ((span[:start_time] - @request_start) * 1000.0).round(2),
+          started_at: span[:start_time]
+        }
+      end
+    end
+
+    def estimate_duration(group)
+      [
+        (group[:end_time] - group[:start_time]) * 1000.0,
+        group[:count] * SAMPLE_INTERVAL * 1000.0
+      ].max
+    end
+
+    def frame_key(frame)
+      "#{frame.path}:#{frame.label}"
+    end
+
+    def classify_path(path)
+      return 'code' if Fingerprint.app_frame?(path)
+
+      gem = extract_gem_name(path)
+      case gem
+      when /\A(httpclient|net-http|faraday|httpx|typhoeus|excon|http)\z/ then 'http'
+      when /\A(pg|mysql2|sqlite3|trilogy)\z/ then 'sql'
+      when /\A(redis|dalli|hiredis)\z/ then 'cache'
+      when /\A(aws-sdk|google-cloud|fog)\z/ then 'storage'
+      when /\A(mail|net-smtp)\z/ then 'mailer'
+      else 'gem'
+      end
+    end
+
+    def build_app_detail(frame)
+      path = frame.path.to_s
+      short = path.sub(%r{.*/app/}, 'app/').sub(%r{.*/lib/}, 'lib/')
+      "#{short} in #{frame.label}"
+    end
+
+    def build_gem_detail(frame)
+      path = frame.path.to_s
+      if Fingerprint.app_frame?(path)
+        build_app_detail(frame)
+      else
+        gem = extract_gem_name(path) || 'unknown'
+        "#{gem}: #{frame.label}"
+      end
+    end
+
+    def extract_gem_name(path)
+      if path =~ /\/gems\/([a-zA-Z0-9_-]+)-[\d.]+/
+        $1
+      end
+    end
+  end
+end

data/lib/catpm/subscribers.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module Catpm
+  module Subscribers
+    class << self
+      def subscribe!
+        unsubscribe!
+
+        # IMPORTANT: SegmentSubscribers must be subscribed BEFORE the Collector.
+        # ActiveSupport::Notifications calls finish callbacks in subscription order.
+        # ControllerSpanSubscriber.finish (pop_span) must set the controller span
+        # duration BEFORE the Collector reads the segments.
+        SegmentSubscribers.subscribe! if Catpm.config.instrument_segments
+
+        if Catpm.config.instrument_http
+          @http_subscriber = ActiveSupport::Notifications.subscribe(
+            'process_action.action_controller'
+          ) do |event|
+            Collector.process_action_controller(event)
+          end
+        end
+
+        if Catpm.config.instrument_jobs
+          @job_subscriber = ActiveSupport::Notifications.subscribe(
+            'perform.active_job'
+          ) do |event|
+            Collector.process_active_job(event)
+          end
+        end
+      end
+
+      def unsubscribe!
+        if @http_subscriber
+          ActiveSupport::Notifications.unsubscribe(@http_subscriber)
+          @http_subscriber = nil
+        end
+
+        if @job_subscriber
+          ActiveSupport::Notifications.unsubscribe(@job_subscriber)
+          @job_subscriber = nil
+        end
+
+        SegmentSubscribers.unsubscribe!
+      end
+    end
+  end
+end