posthog-ruby 3.28.4 → 3.29.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f6e3857125c3ca1a120a8ab1680b518c79ca92729186bf0dcc868d5d83126612
-  data.tar.gz: 5bce014fe04b202359313e36e6adae530dfc77a23be2824eb42c28b29a12fa8b
+  metadata.gz: dc3cd53140f36b4f77fb11d60a903858d5053362e7c8fd3d8d4bd55472ed1c4a
+  data.tar.gz: f1213ce104a582ae6b9e82315538e31b77fc85dbe7336cdf0e41cbb169b0b47e
 SHA512:
-  metadata.gz: 9df1007084659857d4f38c386cedc310a89a0c7adde2681b06bba0a8924b76545160092c2fd7140bc12a2f41038b69baf46ba40db5c3ef7c7b4394da1b30310e
-  data.tar.gz: 02c14a66f74f619b3da4f2e680f67a186e74f9193ffbb7149cdca12d5bb60d7b554983c8b66a69d46f38002c0caab6facadb5aa92bcd7b690969a6de25ddd038
+  metadata.gz: 489f3bd76d70c2034c62c02e217d6e09bd16e6600d9de7b757ae5bda1a0a24d7dafad88a735ddf13ab39fa18cffdab59fcb20e2d080689ff373238fce11f9925
+  data.tar.gz: ab7bb81da61fc82e4058355c95bc1d9b97018f0cbcfd5b476f380a058a39e9a0ce6ae3b8ce1fd11aa18acb4d4a1c4fb0cec3546f4729ee5a56dcf4e959e5ee3a

data/lib/posthog/client.rb

@@ -54,6 +54,9 @@ module PostHog
     RELEASE_ID_ENV_VAR = 'POSTHOG_RELEASE_ID'
     private_constant :RELEASE_ID_ENV_VAR
 
+    CAPTURED_EXCEPTION_IVAR = :@posthog_exception_captured
+    private_constant :CAPTURED_EXCEPTION_IVAR
+
     # Thread-safe tracking of client instances per API key for singleton warnings
     @instances_by_api_key = {}
     @instances_mutex = Mutex.new
@@ -410,13 +413,13 @@ module PostHog
     #   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, mechanism: nil)
-      return false if @disabled
+      return false if @disabled || exception_captured?(exception)
 
       exception_list = ExceptionCapture.build_exception_list(exception, mechanism: mechanism)
 
       return if exception_list.nil?
 
-      properties = { '$exception_list' => exception_list }
+      properties = { '$exception_list' => exception_list }.merge(active_trace_properties)
       properties.merge!(additional_properties) if additional_properties && !additional_properties.empty?
 
       event_data = {
@@ -427,7 +430,9 @@ module PostHog
       }
       event_data[:flags] = flags if flags
 
-      capture(event_data)
+      capture(event_data).tap do |captured|
+        mark_exception_captured(exception) if captured
+      end
     end
 
     # Identifies a user
@@ -635,7 +640,8 @@ module PostHog
     # @param [Hash] groups
     # @param [Hash] person_properties key-value pairs of properties to associate with the user
     # @param [Hash] group_properties
-    # @param [Boolean] only_evaluate_locally Skip the remote /flags call entirely
+    # @param [Boolean] only_evaluate_locally Skip the remote /flags call entirely. Flags that local evaluation
+    #   cannot resolve are left out of the snapshot and listed in {FeatureFlagEvaluations#unresolved_flags}.
     # @param [Boolean, nil] disable_geoip When true, disables GeoIP lookup for remote evaluation and stamps captured
     #   access events.
     # @param [Array<String, Symbol>, nil] flag_keys When set, scopes evaluation to only these flag keys.
@@ -665,12 +671,13 @@ module PostHog
         )
       end
 
-      person_properties, group_properties = add_local_person_and_group_properties(
+      groups, person_properties, group_properties = add_local_person_and_group_properties(
         groups, person_properties, group_properties
       )
 
       records = {}
       locally_evaluated_keys = Set.new
+      unresolved_flags = {}
       flag_keys_set = flag_keys&.to_set(&:to_s)
 
       @feature_flags_poller.load_feature_flags
@@ -685,7 +692,10 @@ module PostHog
             :_compute_flag_locally,
             definition, distinct_id, groups, person_properties, group_properties, snapshot: definition_snapshot
           )
-        rescue PostHog::RequiresServerEvaluation, PostHog::InconclusiveMatchError, StandardError
+        rescue PostHog::RequiresServerEvaluation, PostHog::InconclusiveMatchError => e
+          unresolved_flags[key.to_s] = e.reason
+          next
+        rescue StandardError
           next
         end
 
@@ -773,7 +783,8 @@ module PostHog
         flag_definitions_loaded_at: @feature_flags_poller.flag_definitions_loaded_at,
         errors_while_computing: errors_while_computing,
         quota_limited: quota_limited,
-        minimal_flag_called_events: minimal_flag_called_events
+        minimal_flag_called_events: minimal_flag_called_events,
+        unresolved_flags: unresolved_flags.reject { |key, _reason| records.key?(key) }
       )
     end
 
@@ -795,8 +806,9 @@ module PostHog
     )
       return {} if @disabled
 
-      person_properties, group_properties = add_local_person_and_group_properties(groups, person_properties,
-                                                                                  group_properties)
+      groups, person_properties, group_properties = add_local_person_and_group_properties(
+        groups, person_properties, group_properties
+      )
       @feature_flags_poller.get_all_flags(distinct_id, groups, person_properties, group_properties,
                                           only_evaluate_locally)
     end
@@ -835,8 +847,9 @@ module PostHog
       return nil if @disabled
 
       key = key.to_s
-      person_properties, group_properties = add_local_person_and_group_properties(groups, person_properties,
-                                                                                  group_properties)
+      groups, person_properties, group_properties = add_local_person_and_group_properties(
+        groups, person_properties, group_properties
+      )
       @feature_flags_poller.get_feature_flag_payload(key, distinct_id, match_value, groups, person_properties,
                                                      group_properties, only_evaluate_locally)
     end
@@ -862,7 +875,7 @@ module PostHog
     )
       return { featureFlags: {}, featureFlagPayloads: {} } if @disabled
 
-      person_properties, group_properties = add_local_person_and_group_properties(
+      groups, person_properties, group_properties = add_local_person_and_group_properties(
         groups, person_properties, group_properties
       )
       response = @feature_flags_poller.get_all_flags_and_payloads(
@@ -978,6 +991,44 @@ module PostHog
 
     private
 
+    def active_trace_properties
+      return {} unless defined?(::OpenTelemetry::Trace)
+
+      context = ::OpenTelemetry::Trace.current_span.context
+      return {} unless context.valid?
+
+      trace_id = context.hex_trace_id
+      span_id = context.hex_span_id
+      return {} unless trace_id.match?(/\A[0-9a-f]{32}\z/) && trace_id != '0' * 32
+      return {} unless span_id.match?(/\A[0-9a-f]{16}\z/) && span_id != '0' * 16
+
+      context_properties = Internal::Context.current&.properties
+      { '$trace_id' => trace_id, '$span_id' => span_id }.reject do |key, _|
+        property_key?(context_properties, key)
+      end
+    rescue StandardError, LoadError
+      {}
+    end
+
+    def exception_captured?(exception)
+      exception.is_a?(Exception) && exception.instance_variable_get(CAPTURED_EXCEPTION_IVAR).equal?(exception)
+    rescue StandardError
+      false
+    end
+
+    # Rails can unwrap template errors, so mark the causes included in the event too.
+    def mark_exception_captured(exception)
+      ExceptionCapture::MAX_CHAINED_EXCEPTIONS.times do
+        break unless exception.is_a?(Exception)
+        break if exception_captured?(exception)
+
+        exception.instance_variable_set(CAPTURED_EXCEPTION_IVAR, exception) unless exception.frozen?
+        exception = exception.cause
+      end
+    rescue StandardError
+      nil
+    end
+
     def enrich_capture_attrs_with_context(attrs)
       context = Internal::Context.current
       explicit_properties = attrs[:properties]
@@ -1075,7 +1126,7 @@ module PostHog
       return nil if @disabled
 
       key = key.to_s
-      person_properties, group_properties = add_local_person_and_group_properties(
+      groups, person_properties, group_properties = add_local_person_and_group_properties(
         groups, person_properties, group_properties
       )
       feature_flag_response, flag_was_locally_evaluated, request_id, evaluated_at, feature_flag_error, payload,
@@ -1152,10 +1203,7 @@ module PostHog
       action = process_before_send(action)
       return false if action.nil? || action.empty?
 
-      if @sync_mode
-        send_sync(action)
-        return true
-      end
+      return send_sync(action) if @sync_mode
 
       queued = @queue_mutex.synchronize do
         if @queue.length < @max_queue_size
@@ -1223,13 +1271,15 @@ module PostHog
         batch << action
       rescue MessageBatch::JSONGenerationError => e
         @on_error.call(-1, e.to_s)
-        return
+        return false
       end
-      return if batch.empty?
+      return false if batch.empty?
 
       @sync_lock.synchronize do
         res = @transport.send(@api_key, batch)
-        @on_error.call(res.status, res.error) unless res.status.between?(200, 299)
+        success = res.status.between?(200, 299)
+        @on_error.call(res.status, res.error) unless success
+        success
       end
     end
 
@@ -1242,17 +1292,9 @@ module PostHog
     end
 
     def add_local_person_and_group_properties(groups, person_properties, group_properties)
-      groups ||= {}
-      person_properties ||= {}
-      group_properties ||= {}
-
-      symbolize_keys! groups
-      symbolize_keys! person_properties
-      symbolize_keys! group_properties
-
-      group_properties.each_value do |value|
-        symbolize_keys! value
-      end
+      groups, person_properties, group_properties = normalize_flag_evaluation_inputs(
+        groups, person_properties, group_properties
+      )
 
       all_group_properties = {}
       groups&.each do |group_name, group_key|
@@ -1261,7 +1303,7 @@ module PostHog
         }.merge((group_properties && group_properties[group_name]) || {})
       end
 
-      [person_properties, all_group_properties]
+      [groups, person_properties, all_group_properties]
     end
   end
 end

data/lib/posthog/feature_flag_error.rb

@@ -10,6 +10,7 @@ module PostHog
   # Error values:
   #   ERRORS_WHILE_COMPUTING: Server returned errorsWhileComputingFlags=true
   #   FLAG_MISSING: Requested flag not in API response
+  #   LOCAL_EVALUATION_INCONCLUSIVE: Flag has a loaded local definition but local evaluation could not resolve it
   #   QUOTA_LIMITED: Rate/quota limit exceeded
   #   TIMEOUT: Request timed out
   #   CONNECTION_ERROR: Network connectivity issue
@@ -21,6 +22,7 @@ module PostHog
   class FeatureFlagError
     ERRORS_WHILE_COMPUTING = 'errors_while_computing_flags'
     FLAG_MISSING = 'flag_missing'
+    LOCAL_EVALUATION_INCONCLUSIVE = 'local_evaluation_inconclusive'
     QUOTA_LIMITED = 'quota_limited'
     TIMEOUT = 'timeout'
     CONNECTION_ERROR = 'connection_error'

data/lib/posthog/feature_flag_evaluations.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require 'set'
+require 'posthog/feature_flag_error'
 
 module PostHog
   # A snapshot of feature flag evaluations for one distinct_id, returned by
@@ -34,6 +35,15 @@ module PostHog
     # @return [Time, nil] When local flag definitions were loaded.
     attr_reader :flag_definitions_loaded_at
 
+    # Flags that have a loaded local definition but that neither local evaluation nor a remote
+    # fallback resolved, mapped to the reason local evaluation was inconclusive. These flags are not
+    # in {#keys}, and their accessors follow the missing-flag contract. Reading this does not count
+    # as an access and does not send any event. Always empty on snapshots returned by {#only} and
+    # {#only_accessed}.
+    #
+    # @return [Hash{String => String}] Frozen hash of flag key to an {UnresolvedFlagReason} value.
+    attr_reader :unresolved_flags
+
     # @param host [Host, nil] Internal host callbacks used to record flag access events.
     # @param distinct_id [String, nil] The distinct id these evaluations belong to.
     # @param flags [Hash] Evaluated flags keyed by flag key.
@@ -47,6 +57,8 @@ module PostHog
     # @param minimal_flag_called_events [Boolean] Server-controlled gate for minimal
     #   `$feature_flag_called` events.
     # @param accessed [Array<String>, Set<String>, nil] Flag keys already accessed by this snapshot.
+    # @param unresolved_flags [Hash{String => String}, nil] Unresolved flag keys mapped to an
+    #   {UnresolvedFlagReason} value.
     def initialize(
       host: nil,
       distinct_id: nil,
@@ -59,7 +71,8 @@ module PostHog
       errors_while_computing: false,
       quota_limited: false,
       minimal_flag_called_events: false,
-      accessed: nil
+      accessed: nil,
+      unresolved_flags: nil
     )
       @host = host
       @distinct_id = distinct_id || ''
@@ -73,6 +86,7 @@ module PostHog
       @quota_limited = quota_limited
       @minimal_flag_called_events = minimal_flag_called_events == true
       @accessed = Set.new(accessed || [])
+      @unresolved_flags = (unresolved_flags || {}).dup.freeze
     end
 
     # @return [Array<String>] The evaluated flag keys in this snapshot.
@@ -198,7 +212,11 @@ module PostHog
       errors = []
       errors << 'errors_while_computing_flags' if @errors_while_computing
       errors << 'quota_limited' if @quota_limited
-      errors << 'flag_missing' if flag.nil?
+      if flag.nil? && @unresolved_flags.key?(key)
+        errors << FeatureFlagError::LOCAL_EVALUATION_INCONCLUSIVE
+      elsif flag.nil?
+        errors << FeatureFlagError::FLAG_MISSING
+      end
       properties['$feature_flag_error'] = errors.join(',') unless errors.empty?
 
       # Emit a minimal event only when the server gate is on and the flag is