catpm 0.4.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 30a794032ccb0fcb32152d5ae6c7285758260c6a80c5241c217924a887040885
-  data.tar.gz: 7691f6480aa62e4efd41d657fda9e1501a2765584a3d926a5d9ac3a8b6ac0c98
+  metadata.gz: 527b9950df4630b2c22f992c2e3e604eac9365c7faa0ea2a892cac5ed47d69af
+  data.tar.gz: d39f675cb7bea8ab51762f78d2319d29e2f88769b37594a45bb0571cdcdd2d32
 SHA512:
-  metadata.gz: c902a837f12312f1f856d232b056eb3669c8648f5907e5088ced55972888d64682749f937a994d79b040688d1f59d929dccd11a1d28ffdcfe4e25f2458c02f49
-  data.tar.gz: 73dd36a0cb7ea32b405388bb62f54e9f327f30155b3b30794101feb056abe70b7b747cd5dda3dc67e6669e4289392964b37ae76385e6cb680c96e5a5bb550d55
+  metadata.gz: d47303a0a85e9f9773e37ef6ca2f0faf7627207ea1050ae456cf0bdff285d60f6ae043285216e5dbdcf61668ba6e4bffb91848bfd884f3e0c7548ea79a97ebf9
+  data.tar.gz: d4b68684377d6f350645dbfff66cd7faac777884c5dc0aae3b7ef5c2c612576bfc27c27ee55c7c3f3136e1897b3b2d48bc76e49b8aae5f6f9b0eb8240db7c543

data/app/views/catpm/shared/_segments_waterfall.html.erb

@@ -17,6 +17,11 @@
       end
     end
 
+    # Sort children of each parent by timeline offset so segments appear chronologically
+    children.each_value do |kids|
+      kids.sort_by! { |i| (segments[i]["offset"] || segments[i][:offset] || 0).to_f }
+    end
+
     depth_map = {}
     ordered = []
     build_order = ->(indices, depth) {

data/lib/catpm/adapter/base.rb

@@ -3,6 +3,9 @@
 module Catpm
   module Adapter
     module Base
+      MINUTE_BUCKET_RETENTION = 48 * 3600
+      HOUR_BUCKET_RETENTION = 90 * 86400
+      DAY_BUCKET_RETENTION = 2 * 365 * 86400
       def persist_buckets(aggregated_buckets)
         raise NotImplementedError
       end
@@ -66,7 +69,8 @@ module Catpm
 
       def merge_contexts(existing_contexts, new_contexts)
         combined = (existing_contexts + new_contexts)
-        combined.last(Catpm.config.max_error_contexts)
+        max = Catpm.config.max_error_contexts
+        max ? combined.last(max) : combined
       end
 
       # Merge new occurrence timestamps into the multi-resolution bucket structure.
@@ -90,9 +94,9 @@ module Catpm
 
         # Compact old entries
         now = Time.current.to_i
-        cutoff_m = now - 48 * 3600
-        cutoff_h = now - 90 * 86400
-        cutoff_d = now - 2 * 365 * 86400
+        cutoff_m = now - MINUTE_BUCKET_RETENTION
+        cutoff_h = now - HOUR_BUCKET_RETENTION
+        cutoff_d = now - DAY_BUCKET_RETENTION
 
         buckets['m'].reject! { |k, _| k.to_i < cutoff_m }
         buckets['h'].reject! { |k, _| k.to_i < cutoff_h }

data/lib/catpm/call_tracer.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+module Catpm
+  class CallTracer
+    def initialize(request_segments:)
+      @request_segments = request_segments
+      @call_stack = []
+      @path_cache = {}
+      @started = false
+
+      @tracepoint = TracePoint.new(:call, :return) do |tp|
+        case tp.event
+        when :call
+          handle_call(tp)
+        when :return
+          handle_return
+        end
+      end
+    end
+
+    def start
+      return if @started
+
+      @started = true
+      @tracepoint.enable(target_thread: Thread.current)
+    end
+
+    def stop
+      return unless @started
+
+      @tracepoint.disable
+      @started = false
+      flush_remaining_spans
+    end
+
+    private
+
+    def handle_call(tp)
+      path = tp.path
+      app = app_frame?(path)
+
+      unless app
+        @call_stack.push(:skip)
+        return
+      end
+
+      started_at = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+      detail = format_detail(tp.defined_class, tp.method_id)
+      index = @request_segments.push_span(type: :code, detail: detail, started_at: started_at)
+      @call_stack.push(index)
+    end
+
+    def handle_return
+      entry = @call_stack.pop
+      return if entry == :skip || entry.nil?
+
+      @request_segments.pop_span(entry)
+    end
+
+    def flush_remaining_spans
+      @call_stack.reverse_each do |entry|
+        next if entry == :skip || entry.nil?
+
+        @request_segments.pop_span(entry)
+      end
+      @call_stack.clear
+    end
+
+    def app_frame?(path)
+      cached = @path_cache[path]
+      return cached unless cached.nil?
+
+      @path_cache[path] = Fingerprint.app_frame?(path)
+    end
+
+    def format_detail(defined_class, method_id)
+      if defined_class.singleton_class?
+        owner = defined_class.attached_object
+        "#{owner.name || owner.inspect}.#{method_id}"
+      else
+        "#{defined_class.name || defined_class.inspect}##{method_id}"
+      end
+    end
+  end
+end

data/lib/catpm/collector.rb

@@ -2,6 +2,9 @@
 
 module Catpm
   module Collector
+    SYNTHETIC_MIDDLEWARE_OFFSET_MS = 0.5
+    MIN_GAP_MS = 1.0
+
     class << self
       def process_action_controller(event)
         return unless Catpm.enabled?
@@ -65,7 +68,7 @@ module Catpm
             if ctrl_idx
               has_real_middleware = segments.any? { |s| s[:type] == 'middleware' }
               ctrl_offset = (segments[ctrl_idx][:offset] || 0.0).to_f
-              if ctrl_offset > 0.5 && !has_real_middleware
+              if ctrl_offset > SYNTHETIC_MIDDLEWARE_OFFSET_MS && !has_real_middleware
                 middleware_seg = {
                   type: 'middleware',
                   detail: 'Middleware Stack',
@@ -98,7 +101,7 @@ module Catpm
               end
               gap = ctrl_dur - child_dur
 
-              if gap > 1.0
+              if gap > MIN_GAP_MS && Catpm.config.show_untracked_segments
                 inject_gap_segments(segments, req_segments, gap, ctrl_idx, ctrl_seg)
               end
             end
@@ -119,7 +122,7 @@ module Catpm
 
               context[:segments] << {
                 type: 'error',
-                detail: "#{payload[:exception].first}: #{payload[:exception].last}".truncate(200),
+                detail: "#{payload[:exception].first}: #{payload[:exception].last}".truncate(Catpm.config.max_error_detail_length),
                 source: payload[:exception_object]&.backtrace&.first,
                 duration: 0,
                 offset: error_offset,
@@ -253,7 +256,7 @@ module Catpm
               end
               gap = ctrl_dur - child_dur
 
-              if gap > 1.0
+              if gap > MIN_GAP_MS && Catpm.config.show_untracked_segments
                 inject_gap_segments(segments, req_segments, gap, ctrl_idx, ctrl_seg)
               end
             end
@@ -274,7 +277,7 @@ module Catpm
 
               context[:segments] << {
                 type: 'error',
-                detail: "#{error.class.name}: #{error.message}".truncate(200),
+                detail: "#{error.class.name}: #{error.message}".truncate(Catpm.config.max_error_detail_length),
                 source: error.backtrace&.first,
                 duration: 0,
                 offset: error_offset,
@@ -338,7 +341,8 @@ module Catpm
         # Filling phase: always sample until endpoint has enough random samples
         endpoint_key = [kind.to_s, target, operation.to_s]
         count = random_sample_counts[endpoint_key]
-        if count < Catpm.config.max_random_samples_per_endpoint
+        max_random = Catpm.config.max_random_samples_per_endpoint
+        if max_random.nil? || count < max_random
           random_sample_counts[endpoint_key] = count + 1
           return 'random'
         end
@@ -374,22 +378,75 @@ module Catpm
           end
 
           remaining = gap - sampler_dur
-          if remaining > 1.0
-            segments << {
-              type: 'other',
-              detail: 'Untracked',
-              duration: remaining.round(2),
-              offset: (ctrl_seg[:offset] || 0.0),
-              parent_index: ctrl_idx
-            }
+          if remaining > MIN_GAP_MS
+            inject_timeline_gaps(segments, ctrl_idx, ctrl_seg, remaining)
           end
         else
+          inject_timeline_gaps(segments, ctrl_idx, ctrl_seg, gap)
+        end
+      end
+
+      # Compute actual gap intervals between tracked child segments on the timeline,
+      # then create one Untracked entry per gap. This avoids placing a single large
+      # Untracked block that overlaps with real segments.
+      def inject_timeline_gaps(segments, ctrl_idx, ctrl_seg, total_gap)
+        ctrl_offset = (ctrl_seg[:offset] || 0.0).to_f
+        ctrl_dur = (ctrl_seg[:duration] || 0.0).to_f
+        ctrl_end = ctrl_offset + ctrl_dur
+
+        # Collect [start, end] intervals of direct children that have offsets
+        intervals = []
+        segments.each_with_index do |seg, i|
+          next if i == ctrl_idx
+          next unless seg[:parent_index] == ctrl_idx
+          off = seg[:offset]
+          dur = (seg[:duration] || 0).to_f
+          next unless off
+          intervals << [off.to_f, off.to_f + dur]
+        end
+
+        # If no children have offsets, place the gap at the controller start
+        if intervals.empty?
+          segments << {
+            type: 'other', detail: 'Untracked', duration: total_gap.round(2),
+            offset: ctrl_offset, parent_index: ctrl_idx
+          }
+          return
+        end
+
+        # Sort and merge overlapping intervals
+        intervals.sort_by!(&:first)
+        merged = [intervals.first.dup]
+        intervals[1..].each do |s, e|
+          if s <= merged.last[1]
+            merged.last[1] = e if e > merged.last[1]
+          else
+            merged << [s, e]
+          end
+        end
+
+        # Find gaps between controller start, merged intervals, and controller end
+        gaps = []
+        cursor = ctrl_offset
+        merged.each do |s, e|
+          gaps << [cursor, s] if s - cursor > 0
+          cursor = [cursor, e].max
+        end
+        gaps << [cursor, ctrl_end] if ctrl_end - cursor > 0
+
+        # Distribute total_gap proportionally across timeline gaps
+        raw_gap_sum = gaps.sum { |s, e| e - s }
+        return if raw_gap_sum <= 0
+
+        gaps.each do |gs, ge|
+          raw_dur = ge - gs
+          # Scale so all Untracked segments sum to total_gap
+          dur = (raw_dur / raw_gap_sum) * total_gap
+          next if dur < MIN_GAP_MS
+
           segments << {
-            type: 'other',
-            detail: 'Untracked',
-            duration: gap.round(2),
-            offset: (ctrl_seg[:offset] || 0.0),
-            parent_index: ctrl_idx
+            type: 'other', detail: 'Untracked', duration: dur.round(2),
+            offset: gs.round(2), parent_index: ctrl_idx
           }
         end
       end

data/lib/catpm/configuration.rb

@@ -43,7 +43,15 @@ module Catpm
                   :events_max_samples_per_name,
                   :track_own_requests,
                   :stack_sample_interval,
-                  :max_stack_samples_per_request
+                  :max_stack_samples_per_request,
+                  :downsampling_thresholds,
+                  :max_error_detail_length,
+                  :max_fingerprint_app_frames,
+                  :max_fingerprint_gem_frames,
+                  :cleanup_batch_size,
+                  :caller_scan_depth,
+                  :instrument_call_tree,
+                  :show_untracked_segments
 
     def initialize
       @enabled = true
@@ -88,6 +96,19 @@ module Catpm
       @track_own_requests = false
       @stack_sample_interval = 0.005 # seconds (5ms)
       @max_stack_samples_per_request = 200
+      @downsampling_thresholds = {
+        medium: 1.hour,
+        hourly: 24.hours,
+        daily: 1.week,
+        weekly: 90.days
+      }
+      @max_error_detail_length = 200
+      @max_fingerprint_app_frames = 5
+      @max_fingerprint_gem_frames = 3
+      @cleanup_batch_size = 1_000
+      @caller_scan_depth = 50
+      @instrument_call_tree = false
+      @show_untracked_segments = false
     end
 
     def slow_threshold_for(kind)

data/lib/catpm/fingerprint.rb

@@ -15,7 +15,7 @@ module Catpm
     def self.normalize_backtrace(backtrace)
       app_frames = backtrace
         .select { |line| app_frame?(line) }
-        .first(5)
+        .first(Catpm.config.max_fingerprint_app_frames)
         .map { |line| strip_line_number(line) }
 
       # If there are app frames, group by app code (like Sentry)
@@ -25,7 +25,7 @@ module Catpm
       # so the same bug is always one issue regardless of the caller.
       backtrace
         .reject { |line| line.include?('<internal:') }
-        .first(3)
+        .first(Catpm.config.max_fingerprint_gem_frames)
         .map { |line| strip_line_number(line) }
         .join("\n")
     end

data/lib/catpm/flusher.rb

@@ -2,6 +2,8 @@
 
 module Catpm
   class Flusher
+    ERROR_LOG_BACKTRACE_LINES = 5
+
     attr_reader :running
 
     def initialize(buffer:, interval: nil, jitter: nil)
@@ -104,7 +106,7 @@ module Catpm
       events&.each { |ev| @buffer.push(ev) }
       @circuit.record_failure
       Catpm.config.error_handler.call(e)
-      Rails.logger.error("[catpm] flush error: #{e.class}: #{e.message}\n#{e.backtrace&.first(5)&.join("\n")}")
+      Rails.logger.error("[catpm] flush error: #{e.class}: #{e.message}\n#{e.backtrace&.first(ERROR_LOG_BACKTRACE_LINES)&.join("\n")}")
     end
 
     def reset!
@@ -190,7 +192,8 @@ module Catpm
           error[:last_occurred_at] = [ error[:last_occurred_at], event.started_at ].max
           error[:occurrence_times] << event.started_at
 
-          if error[:new_contexts].size < Catpm.config.max_error_contexts
+          max_ctx = Catpm.config.max_error_contexts
+          if max_ctx.nil? || error[:new_contexts].size < max_ctx
             error[:new_contexts] << build_error_context(event)
           end
         end
@@ -254,31 +257,40 @@ module Catpm
 
         case sample[:sample_type]
         when 'random'
-          cache_key = [kind, target, operation, 'random']
-          if (counts_cache[cache_key] || 0) >= Catpm.config.max_random_samples_per_endpoint
-            oldest = Catpm::Sample.joins(:bucket)
-              .where(catpm_buckets: { kind: kind, target: target, operation: operation })
-              .where(sample_type: 'random').order(recorded_at: :asc).first
-            oldest&.destroy
+          max_random = Catpm.config.max_random_samples_per_endpoint
+          if max_random
+            cache_key = [kind, target, operation, 'random']
+            if (counts_cache[cache_key] || 0) >= max_random
+              oldest = Catpm::Sample.joins(:bucket)
+                .where(catpm_buckets: { kind: kind, target: target, operation: operation })
+                .where(sample_type: 'random').order(recorded_at: :asc).first
+              oldest&.destroy
+            end
           end
         when 'slow'
-          cache_key = [kind, target, operation, 'slow']
-          if (counts_cache[cache_key] || 0) >= Catpm.config.max_slow_samples_per_endpoint
-            weakest = Catpm::Sample.joins(:bucket)
-              .where(catpm_buckets: { kind: kind, target: target, operation: operation })
-              .where(sample_type: 'slow').order(duration: :asc).first
-            if weakest && sample[:duration] > weakest.duration
-              weakest.destroy
-            else
-              sample[:_skip] = true
+          max_slow = Catpm.config.max_slow_samples_per_endpoint
+          if max_slow
+            cache_key = [kind, target, operation, 'slow']
+            if (counts_cache[cache_key] || 0) >= max_slow
+              weakest = Catpm::Sample.joins(:bucket)
+                .where(catpm_buckets: { kind: kind, target: target, operation: operation })
+                .where(sample_type: 'slow').order(duration: :asc).first
+              if weakest && sample[:duration] > weakest.duration
+                weakest.destroy
+              else
+                sample[:_skip] = true
+              end
             end
           end
         when 'error'
-          fp = sample[:error_fingerprint]
-          if fp && (error_counts[fp] || 0) >= Catpm.config.max_error_samples_per_fingerprint
-            oldest = Catpm::Sample.where(sample_type: 'error', error_fingerprint: fp)
-              .order(recorded_at: :asc).first
-            oldest&.destroy
+          max_err = Catpm.config.max_error_samples_per_fingerprint
+          if max_err
+            fp = sample[:error_fingerprint]
+            if fp && (error_counts[fp] || 0) >= max_err
+              oldest = Catpm::Sample.where(sample_type: 'error', error_fingerprint: fp)
+                .order(recorded_at: :asc).first
+              oldest&.destroy
+            end
           end
         end
       end
@@ -335,7 +347,7 @@ module Catpm
 
         max = Catpm.config.events_max_samples_per_name
         if event.payload.any?
-          if sample_counts[event.name] < max
+          if max.nil? || sample_counts[event.name] < max
             samples << { name: event.name, payload: event.payload, recorded_at: event.recorded_at }
             sample_counts[event.name] += 1
           elsif rand(Catpm.config.random_sample_rate) == 0
@@ -357,41 +369,42 @@ module Catpm
 
     def downsample_buckets
       bucket_sizes = Catpm.config.bucket_sizes
+      thresholds = Catpm.config.downsampling_thresholds
       adapter = Catpm::Adapter.current
 
       # Phase 1: Merge 1-minute buckets older than 1 hour into 5-minute buckets
       downsample_tier(
         target_interval: bucket_sizes[:medium],
-        age_threshold: 1.hour,
+        age_threshold: thresholds[:medium],
         adapter: adapter
       )
 
       # Phase 2: Merge 5-minute buckets older than 24 hours into 1-hour buckets
       downsample_tier(
         target_interval: bucket_sizes[:hourly],
-        age_threshold: 24.hours,
+        age_threshold: thresholds[:hourly],
         adapter: adapter
       )
 
       # Phase 3: Merge 1-hour buckets older than 1 week into 1-day buckets
       downsample_tier(
         target_interval: bucket_sizes[:daily],
-        age_threshold: 1.week,
+        age_threshold: thresholds[:daily],
         adapter: adapter
       )
 
       # Phase 4: Merge 1-day buckets older than 3 months into 1-week buckets
       downsample_tier(
         target_interval: bucket_sizes[:weekly],
-        age_threshold: 90.days,
+        age_threshold: thresholds[:weekly],
         adapter: adapter
       )
 
       # Event buckets: same downsampling tiers
-      downsample_event_tier(target_interval: bucket_sizes[:medium], age_threshold: 1.hour, adapter: adapter)
-      downsample_event_tier(target_interval: bucket_sizes[:hourly], age_threshold: 24.hours, adapter: adapter)
-      downsample_event_tier(target_interval: bucket_sizes[:daily], age_threshold: 1.week, adapter: adapter)
-      downsample_event_tier(target_interval: bucket_sizes[:weekly], age_threshold: 90.days, adapter: adapter)
+      downsample_event_tier(target_interval: bucket_sizes[:medium], age_threshold: thresholds[:medium], adapter: adapter)
+      downsample_event_tier(target_interval: bucket_sizes[:hourly], age_threshold: thresholds[:hourly], adapter: adapter)
+      downsample_event_tier(target_interval: bucket_sizes[:daily], age_threshold: thresholds[:daily], adapter: adapter)
+      downsample_event_tier(target_interval: bucket_sizes[:weekly], age_threshold: thresholds[:weekly], adapter: adapter)
     end
 
     def downsample_tier(target_interval:, age_threshold:, adapter:)
@@ -496,7 +509,7 @@ module Catpm
 
     def cleanup_expired_data
       cutoff = Catpm.config.retention_period.ago
-      batch_size = 1_000
+      batch_size = Catpm.config.cleanup_batch_size
 
       [ Catpm::Bucket, Catpm::Sample ].each do |model|
         time_column = model == Catpm::Sample ? :recorded_at : :bucket_start

data/lib/catpm/middleware.rb

@@ -21,6 +21,12 @@ module Catpm
         )
         env['catpm.segments'] = req_segments
         Thread.current[:catpm_request_segments] = req_segments
+
+        if Catpm.config.instrument_call_tree
+          call_tracer = CallTracer.new(request_segments: req_segments)
+          call_tracer.start
+          env['catpm.call_tracer'] = call_tracer
+        end
       end
 
       @app.call(env)
@@ -29,6 +35,7 @@ module Catpm
       raise
     ensure
       if Catpm.config.instrument_segments
+        env['catpm.call_tracer']&.stop
         req_segments&.stop_sampler
         Thread.current[:catpm_request_segments] = nil
       end

data/lib/catpm/request_segments.rb

@@ -36,7 +36,7 @@ module Catpm
         @tracked_ranges << [started_at, started_at + duration / 1000.0]
       end
 
-      if @segments.size < @max_segments
+      if @max_segments.nil? || @segments.size < @max_segments
         @segments << segment
       else
         @overflow = true
@@ -54,7 +54,7 @@ module Catpm
       segment[:offset] = offset if offset
       segment[:parent_index] = @span_stack.last if @span_stack.any?
 
-      return nil if @segments.size >= @max_segments
+      return nil if @max_segments && @segments.size >= @max_segments
 
       index = @segments.size
       @segments << segment

data/lib/catpm/segment_subscribers.rb

@@ -2,6 +2,8 @@
 
 module Catpm
   module SegmentSubscribers
+    MIN_INSTANTIATION_DURATION_MS = 0.1
+    CALLER_OFFSET = 4 # frames to skip to reach user code from this call site
     # 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
@@ -146,7 +148,7 @@ module Catpm
         return unless req_segments
 
         duration = event.duration
-        return if duration < 0.1 # skip trivial instantiations
+        return if duration < MIN_INSTANTIATION_DURATION_MS # skip trivial instantiations
 
         payload = event.payload
         record_count = payload[:record_count] || 0
@@ -230,7 +232,7 @@ module Catpm
       end
 
       def extract_source_location
-        locations = caller_locations(4, 50)
+        locations = caller_locations(CALLER_OFFSET, Catpm.config.caller_scan_depth)
         locations&.each do |loc|
           path = loc.path.to_s
           if Fingerprint.app_frame?(path)

data/lib/catpm/stack_sampler.rb

@@ -3,6 +3,8 @@
 module Catpm
   class StackSampler
     MS_PER_SECOND = 1000.0
+    MIN_SEGMENT_DURATION_MS = 1.0
+    SAMPLING_THREAD_PRIORITY = -1
 
     # Single global thread that samples all active requests.
     # Avoids creating a thread per request.
@@ -33,7 +35,7 @@ module Catpm
             sample_all
           end
         end
-        @thread.priority = -1
+        @thread.priority = SAMPLING_THREAD_PRIORITY
       end
 
       def sample_all
@@ -118,7 +120,7 @@ module Catpm
 
       groups.filter_map do |group|
         duration = estimate_duration(group)
-        next if duration < 1.0
+        next if duration < MIN_SEGMENT_DURATION_MS
 
         offset = ((group[:start_time] - @request_start) * MS_PER_SECOND).round(2)
         app_frame = group[:app_frame]
@@ -205,7 +207,7 @@ module Catpm
           (span[:end_time] - span[:start_time]) * MS_PER_SECOND,
           span[:count] * Catpm.config.stack_sample_interval * MS_PER_SECOND
         ].max
-        next if duration < 1.0
+        next if duration < MIN_SEGMENT_DURATION_MS
 
         frame = span[:frame]
         path = frame.path.to_s

data/lib/catpm/trace.rb

@@ -83,6 +83,11 @@ module Catpm
       )
       Thread.current[:catpm_request_segments] = req_segments
       owns_segments = true
+
+      if config.instrument_call_tree
+        call_tracer = CallTracer.new(request_segments: req_segments)
+        call_tracer.start
+      end
     end
 
     if req_segments
@@ -100,6 +105,7 @@ module Catpm
       raise
     ensure
       duration = (Process.clock_gettime(Process::CLOCK_MONOTONIC) - start_time) * 1000.0
+      call_tracer&.stop
       req_segments&.pop_span(ctrl_idx) if ctrl_idx
       req_segments&.stop_sampler
 
@@ -152,8 +158,10 @@ module Catpm
 
   private
 
+  CALLER_OFFSET = 3 # frames to skip to reach user code from this call site
+
   def self.extract_trace_source
-    locations = caller_locations(3, 50)
+    locations = caller_locations(CALLER_OFFSET, Catpm.config.caller_scan_depth)
     locations&.each do |loc|
       path = loc.path.to_s
       if Fingerprint.app_frame?(path)

data/lib/catpm/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Catpm
-  VERSION = '0.4.0'
+  VERSION = '0.5.0'
 end

data/lib/catpm.rb

@@ -12,6 +12,7 @@ require 'catpm/adapter'
 require 'catpm/fingerprint'
 require 'catpm/stack_sampler'
 require 'catpm/request_segments'
+require 'catpm/call_tracer'
 require 'catpm/flusher'
 require 'catpm/collector'
 require 'catpm/middleware'

data/lib/generators/catpm/templates/initializer.rb.tt

@@ -1,78 +1,90 @@
 # frozen_string_literal: true
 
 Catpm.configure do |config|
+  # === Enable/Disable ===
+  # config.enabled = Rails.env.production? || Rails.env.staging?
+
   # === Security ===
-  # Protect the dashboard with HTTP Basic Auth or a custom policy.
-  # If neither is configured, the dashboard is accessible to everyone.
-  #
   # config.http_basic_auth_user = ENV["CATPM_USER"]
   # config.http_basic_auth_password = ENV["CATPM_PASSWORD"]
   # config.access_policy = ->(request) { request.env["warden"].user&.admin? }
 
   # === PII Filtering ===
-  # Rails' filter_parameters are inherited automatically.
-  # Add extra patterns here:
-  #
   # config.additional_filter_parameters = [:card_number, :ssn]
 
   # === Instrumentation ===
-  #
-  config.instrument_http = true              # Track HTTP requests (default: true)
-  config.instrument_jobs = false             # Track ActiveJob (default: false)
-  config.instrument_segments = true          # Track SQL/view/cache segments (default: true)
-  # config.track_own_requests = false           # Track catpm dashboard requests (default: false)
-  # config.instrument_net_http = false         # Patch Net::HTTP for outbound tracking (default: false)
-  # config.instrument_middleware_stack = false # Decompose middleware into per-middleware segments (default: false)
-  # config.max_segments_per_request = 50       # Cap segments per request (keeps slowest)
-  # config.segment_source_threshold = 0.0      # ms — capture caller_locations above this (raise to reduce overhead)
-  # config.max_sql_length = 200                # Truncate SQL queries to this length
-  # config.slow_threshold = 500                # ms — threshold for slow samples (all kinds)
-  # config.slow_threshold_per_kind = {         # Override per kind
-  #   http: 500,
-  #   job: 5_000,
-  #   custom: 1_000
-  # }
-  # config.ignored_targets = [                 # Patterns to exclude from tracking
-  #   "HealthcheckController#index",
-  #   "/assets/*",
-  # ]
+  config.instrument_http = true
+  config.instrument_jobs = false
+  config.instrument_segments = true
+  # config.instrument_net_http = false
+  # config.instrument_middleware_stack = false
+  # config.instrument_stack_sampler = false
+  # config.instrument_call_tree = false
+  # config.show_untracked_segments = false
+  # config.track_own_requests = false
+
+  # === Auto-instrumentation ===
+  # config.service_base_classes = nil                  # nil = auto-detect (ApplicationService, BaseService)
+  # config.auto_instrument_methods = []                # e.g. ["Worker#process", "Gateway.charge"]
+
+  # === Segments ===
+  # config.max_segments_per_request = 50               # nil = unlimited
+  # config.segment_source_threshold = 0.0              # ms — capture caller_locations above this
+  # config.max_sql_length = 200                        # nil = no truncation
+  # config.slow_threshold = 500                        # ms
+  # config.slow_threshold_per_kind = {}                # { http: 500, job: 5_000, custom: 1_000 }
+  # config.ignored_targets = []
+
+  # === Stack Sampling ===
+  # config.stack_sample_interval = 0.005               # seconds (5ms)
+  # config.max_stack_samples_per_request = 200         # nil = unlimited
 
   # === Sampling ===
-  #
-  # config.random_sample_rate = 20                   # 1 in N requests sampled randomly
-  # config.max_random_samples_per_endpoint = 5       # Random samples kept per endpoint
-  # config.max_slow_samples_per_endpoint = 5         # Slow samples kept per endpoint
-
-  # === Tuning ===
-  #
-  # config.retention_period = nil                    # nil = keep forever (default); set to e.g. 1.year to delete older data
-  # config.max_buffer_memory = 32.megabytes          # Maximum in-memory buffer size
-  # config.flush_interval = 30                       # seconds
-  # config.flush_jitter = 5                          # +/- seconds random offset per cycle
-  # config.max_error_contexts = 5                    # Contexts kept per error fingerprint
-  # config.cleanup_interval = 1.hour                 # How often to run downsampling
-  # config.persistence_batch_size = 100              # Records per DB batch operation
+  # config.random_sample_rate = 20                     # 1 in N requests sampled randomly
+  # config.max_random_samples_per_endpoint = 5         # nil = unlimited
+  # config.max_slow_samples_per_endpoint = 5           # nil = unlimited
+  # config.max_error_samples_per_fingerprint = 20      # nil = unlimited
+
+  # === Errors ===
+  # config.max_error_contexts = 5                      # nil = unlimited
+  # config.backtrace_lines = nil
+
+  # === Events ===
+  # config.events_enabled = false
+  # config.events_max_samples_per_name = 20            # nil = unlimited
+
+  # === Buffering & Flushing ===
+  # config.max_buffer_memory = 8.megabytes
+  # config.flush_interval = 30                         # seconds
+  # config.flush_jitter = 5                            # ±seconds
+  # config.persistence_batch_size = 100
+
+  # === Data Retention ===
+  # config.retention_period = nil                      # nil = keep forever
+  # config.cleanup_interval = 1.hour
 
   # === Downsampling ===
-  # Data is kept forever with progressively coarser resolution:
-  # - Last hour: 1-minute buckets
-  # - 1h–24h: 5-minute buckets
-  # - 1d–1w: 1-hour buckets
-  # - 1w–3mo: 1-day buckets
-  # - Older than 3 months: 1-week buckets
-  #
   # config.bucket_sizes = { recent: 1.minute, medium: 5.minutes, hourly: 1.hour, daily: 1.day, weekly: 1.week }
+  # config.downsampling_thresholds = {                 # Age before tier is merged into the next coarser tier
+  #   medium: 1.hour,
+  #   hourly: 24.hours,
+  #   daily:  1.week,
+  #   weekly: 90.days
+  # }
+
+  # === Database ===
+  # config.sqlite_busy_timeout = 5_000                 # ms
+
+  # === Circuit Breaker ===
+  # config.circuit_breaker_failure_threshold = 5
+  # config.circuit_breaker_recovery_timeout = 60       # seconds
 
   # === Advanced ===
-  #
-  # config.circuit_breaker_failure_threshold = 5     # Failures before circuit opens
-  # config.circuit_breaker_recovery_timeout = 60     # seconds before retry
-  # config.sqlite_busy_timeout = 5_000               # ms — SQLite lock wait
-  # config.backtrace_lines = 10                      # Backtrace lines in error contexts
-  # config.shutdown_timeout = 5                      # seconds — graceful shutdown wait
+  # config.shutdown_timeout = 5                        # seconds
+  # config.max_error_detail_length = 200               # truncate error detail segments
+  # config.max_fingerprint_app_frames = 5              # app frames used for error fingerprint
+  # config.max_fingerprint_gem_frames = 3              # gem frames used when no app frames
+  # config.cleanup_batch_size = 1_000                  # rows per cleanup batch
+  # config.caller_scan_depth = 50                      # max frames to scan for app code
   # config.error_handler = ->(e) { Rails.logger.error("[catpm] #{e.message}") }
-
-  # === Enable/Disable ===
-  #
-  # config.enabled = Rails.env.production? || Rails.env.staging?
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: catpm
 version: !ruby/object:Gem::Version
-  version: 0.4.0
+  version: 0.5.0
 platform: ruby
 authors:
 - ''
@@ -71,6 +71,7 @@ files:
 - lib/catpm/adapter/sqlite.rb
 - lib/catpm/auto_instrument.rb
 - lib/catpm/buffer.rb
+- lib/catpm/call_tracer.rb
 - lib/catpm/circuit_breaker.rb
 - lib/catpm/collector.rb
 - lib/catpm/configuration.rb