posthog-ruby 3.15.3 → 3.17.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 36a73ef4ffe63b9e2c722441bd8d3c5732e8e162ea1431bdc68bc861b2c8a452
-  data.tar.gz: cf1f040865ce0df9fc7c68d0cac9f0903114b959b1b162d83afecfbdfe8697d1
+  metadata.gz: 187ed0ab3a49d0137a8a5516792d00eb6baf5242ed6665df879563656a6541ac
+  data.tar.gz: cf463f7135031a7d6975bac3eb72ad48ead37729c577738f80fe03e83a6c8f9c
 SHA512:
-  metadata.gz: 5214a1df75497519ac214d1134549a9d41e98bb16ca7e82df800fca062957ecc17c382472902cd7a8161fe4a6a92786c2fe243ec10663dbbaeb7ae1ddd54562f
-  data.tar.gz: 3adf9801fe9b1a64427d8c7a0fd4abbc15b78c77fa80566e2be23bc97ff9d3d9808be9ba0513f71d00b814ae9e70da532e82495ce3c4bf763b00ac1adf30b076
+  metadata.gz: 5f0906fded5049de9de8638ffee0345e7db4bee9a73387fcc602247a9e62193e011fa89358a1001d8818ec216116aec3750548e0c056a6488a7c3360784da038
+  data.tar.gz: 5d7c036bfccdb96b1343287a7349c5ab95ec7184b88db2189f9ba4d805756e050edc3f14533517b79a30377253649ceb1ccecf95a0f9950fdc28812cf18ec629

data/lib/posthog/client.rb

@@ -311,15 +311,18 @@ module PostHog
     # @param flags [PostHog::FeatureFlagEvaluations, nil] A snapshot returned by {#evaluate_flags}.
     #   Forwarded to the inner {#capture} call so the captured `$exception` event carries the
     #   same `$feature/<key>` and `$active_feature_flags` properties as the snapshot.
+    # @param mechanism [Hash, nil] How the exception was captured, e.g.
+    #   `{ 'type' => 'rails', 'handled' => false }` for automatic integrations.
+    #   Defaults to `{ 'type' => 'generic', 'handled' => true }` for manual captures.
     # @return [Boolean, nil] Whether the exception event was queued or sent, or nil if the input could not be parsed.
-    def capture_exception(exception, distinct_id = nil, additional_properties = {}, flags: nil)
+    def capture_exception(exception, distinct_id = nil, additional_properties = {}, flags: nil, mechanism: nil)
       return false if @disabled
 
-      exception_info = ExceptionCapture.build_parsed_exception(exception)
+      exception_list = ExceptionCapture.build_exception_list(exception, mechanism: mechanism)
 
-      return if exception_info.nil?
+      return if exception_list.nil?
 
-      properties = { '$exception_list' => [exception_info] }
+      properties = { '$exception_list' => exception_list }
       properties.merge!(additional_properties) if additional_properties && !additional_properties.empty?
 
       event_data = {

data/lib/posthog/exception_capture.rb

@@ -22,27 +22,72 @@ module PostHog
         (?: :in\s('|`)(?:([\w:]+)\#)?([^']+)')?$
       /x
 
+    # Maximum number of exceptions extracted from a single `cause` chain.
+    MAX_CHAINED_EXCEPTIONS = 50
+
+    DEFAULT_MECHANISM = { 'type' => 'generic', 'handled' => true }.freeze
+
+    # Builds the `$exception_list` payload for an exception, walking its
+    # `cause` chain outermost-first (wrapper first, root cause last).
+    #
+    # @param value [Exception, String, Object] Exception input to parse.
+    # @param mechanism [Hash, nil] Mechanism applied to the outermost exception,
+    #   e.g. `{ 'type' => 'rails', 'handled' => false }`. Chained causes are
+    #   tagged with `{ 'type' => 'chained', ... }` and parent linkage.
+    # @return [Array<Hash>, nil] Parsed exception payloads, or nil when the input is unsupported.
+    def self.build_exception_list(value, mechanism: nil)
+      root_mechanism = DEFAULT_MECHANISM.merge(mechanism || {})
+
+      exceptions = []
+      seen = {}.compare_by_identity
+      current = value
+
+      while current && exceptions.length < MAX_CHAINED_EXCEPTIONS && !seen.key?(current)
+        parsed = build_parsed_exception(current, mechanism: chain_mechanism(root_mechanism, exceptions.length))
+        break if parsed.nil?
+
+        exceptions << parsed
+        seen[current] = true
+        current = current.respond_to?(:cause) ? current.cause : nil
+      end
+
+      exceptions.empty? ? nil : exceptions
+    end
+
+    # @param root_mechanism [Hash] Mechanism of the outermost exception.
+    # @param exception_id [Integer] Zero-based position in the cause chain.
+    # @return [Hash]
+    def self.chain_mechanism(root_mechanism, exception_id)
+      mechanism = root_mechanism.merge('exception_id' => exception_id)
+      return mechanism if exception_id.zero?
+
+      mechanism.merge(
+        'type' => 'chained',
+        'source' => 'cause',
+        'parent_id' => exception_id - 1
+      )
+    end
+
     # @param value [Exception, String, Object] Exception input to parse.
+    # @param mechanism [Hash, nil] Mechanism describing how the exception was captured.
     # @return [Hash, nil] Parsed exception payload, or nil when the input is unsupported.
-    def self.build_parsed_exception(value)
+    def self.build_parsed_exception(value, mechanism: nil)
       title, message, backtrace = coerce_exception_input(value)
       return nil if title.nil?
 
-      build_single_exception_from_data(title, message, backtrace)
+      build_single_exception_from_data(title, message, backtrace, mechanism: mechanism)
     end
 
     # @param title [String]
     # @param message [String, nil]
     # @param backtrace [Array<String>, nil]
+    # @param mechanism [Hash, nil]
     # @return [Hash]
-    def self.build_single_exception_from_data(title, message, backtrace)
+    def self.build_single_exception_from_data(title, message, backtrace, mechanism: nil)
       {
         'type' => title,
         'value' => message || '',
-        'mechanism' => {
-          'type' => 'generic',
-          'handled' => true
-        },
+        'mechanism' => DEFAULT_MECHANISM.merge(mechanism || {}),
         'stacktrace' => build_stacktrace(backtrace)
       }
     end
@@ -52,8 +97,10 @@ module PostHog
     def self.build_stacktrace(backtrace)
       return nil unless backtrace && !backtrace.empty?
 
+      root = project_root
+      roots = dependency_roots(root)
       frames = backtrace.first(50).map do |line|
-        parse_backtrace_line(line)
+        parse_backtrace_line(line, project_root: root, dependency_roots: roots)
       end.compact.reverse
 
       {
@@ -63,8 +110,10 @@ module PostHog
     end
 
     # @param line [String]
+    # @param project_root [String, nil] Project root used to derive project-relative filenames.
+    # @param dependency_roots [Array<String>, nil] Cached gem and stdlib roots.
     # @return [Hash, nil]
-    def self.parse_backtrace_line(line)
+    def self.parse_backtrace_line(line, project_root: self.project_root, dependency_roots: nil)
       match = line.match(RUBY_INPUT_FORMAT)
       return nil unless match
 
@@ -73,11 +122,11 @@ module PostHog
       method_name = match[5]
 
       frame = {
-        'filename' => File.basename(file),
+        'filename' => frame_filename(file, project_root),
         'abs_path' => file,
         'lineno' => lineno,
         'function' => method_name,
-        'in_app' => !gem_path?(file),
+        'in_app' => !gem_path?(file, dependency_roots || self.dependency_roots(project_root)),
         'platform' => 'ruby'
       }
 
@@ -86,13 +135,71 @@ module PostHog
       frame
     end
 
+    # Root directory the application runs from, used to derive stable
+    # project-relative filenames from per-host deploy paths
+    # (e.g. `/app/releases/20240101/...`).
+    #
+    # @return [String]
+    def self.project_root
+      if defined?(::Rails) && ::Rails.respond_to?(:root) && ::Rails.root
+        ::Rails.root.to_s
+      else
+        Dir.pwd
+      end
+    rescue StandardError
+      Dir.pwd
+    end
+
+    # Stable filename used for fingerprinting: the project-relative path when
+    # the file lives inside the project root, its basename otherwise. The raw
+    # absolute path is kept separately in `abs_path`.
+    #
+    # @param path [String]
+    # @param project_root [String, nil]
+    # @return [String]
+    def self.frame_filename(path, project_root)
+      if project_root && !project_root.empty? && path_within?(path, project_root)
+        relative = path[project_root.length..]
+        relative = relative[1..] while relative.start_with?(File::SEPARATOR)
+        return relative unless relative.empty?
+      end
+
+      File.basename(path)
+    end
+
+    # Whether the path belongs to an installed gem or the Ruby standard library,
+    # based on gem install locations rather than path substrings.
+    #
+    # @param path [String]
+    # @param dependency_roots [Array<String>]
+    # @return [Boolean]
+    def self.gem_path?(path, dependency_roots = self.dependency_roots)
+      dependency_roots.any? { |root| path_within?(path, root) }
+    end
+
+    # @param project_root [String]
+    # @return [Array<String>] Directories containing installed gems and the Ruby stdlib.
+    def self.dependency_roots(project_root = self.project_root)
+      roots = []
+      if defined?(Gem)
+        roots.concat(Gem.path) if Gem.respond_to?(:path)
+        roots << Gem.default_dir if Gem.respond_to?(:default_dir)
+        roots.concat(Gem.loaded_specs.each_value.map(&:full_gem_path)) if Gem.respond_to?(:loaded_specs)
+      end
+      roots << RbConfig::CONFIG['rubylibprefix'] if defined?(RbConfig)
+      # The project itself can be a loaded spec (e.g. a gem developed in place,
+      # or a Rails engine); its frames are still application code.
+      roots.compact.reject(&:empty?).uniq - [project_root]
+    rescue StandardError
+      []
+    end
+
     # @param path [String]
+    # @param root [String]
     # @return [Boolean]
-    def self.gem_path?(path)
-      path.include?('/gems/') ||
-        path.include?('/ruby/') ||
-        path.include?('/.rbenv/') ||
-        path.include?('/.rvm/')
+    def self.path_within?(path, root)
+      root = root.chomp(File::SEPARATOR)
+      path == root || path.start_with?("#{root}#{File::SEPARATOR}")
     end
 
     # @param frame [Hash]

data/lib/posthog/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module PostHog
-  VERSION = '3.15.3'
+  VERSION = '3.17.0'
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: posthog-ruby
 version: !ruby/object:Gem::Version
-  version: 3.15.3
+  version: 3.17.0
 platform: ruby
 authors:
 - ''