feat: Set $feature_flag_error on $feature_flag_called

If an error occurs while fetching flags, the property will be set to
indicate what happened.

Author: dustinbyrne

lib/posthog.rb

@@ -10,3 +10,4 @@
 require 'posthog/response'
 require 'posthog/logging'
 require 'posthog/exception_capture'
+require 'posthog/feature_flag_error'

lib/posthog/client.rb

@@ -285,7 +285,7 @@ def get_feature_flag(
         person_properties,
         group_properties
       )
-      feature_flag_response, flag_was_locally_evaluated, request_id, evaluated_at =
+      feature_flag_response, flag_was_locally_evaluated, request_id, evaluated_at, feature_flag_error =
         @feature_flags_poller.get_feature_flag(
           key,
           distinct_id,
@@ -304,6 +304,7 @@ def get_feature_flag(
         }
         properties['$feature_flag_request_id'] = request_id if request_id
         properties['$feature_flag_evaluated_at'] = evaluated_at if evaluated_at
+        properties['$feature_flag_error'] = feature_flag_error if feature_flag_error
 
         capture(
           {

lib/posthog/feature_flag_error.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module PostHog
+  # Error type constants for the $feature_flag_error property.
+  #
+  # These values are sent in analytics events to track flag evaluation failures.
+  # They should not be changed without considering impact on existing dashboards
+  # and queries that filter on these values.
+  #
+  # Error values:
+  #   ERRORS_WHILE_COMPUTING: Server returned errorsWhileComputingFlags=true
+  #   FLAG_MISSING: Requested flag not in API response
+  #   QUOTA_LIMITED: Rate/quota limit exceeded
+  #   TIMEOUT: Request timed out
+  #   CONNECTION_ERROR: Network connectivity issue
+  #   UNKNOWN_ERROR: Unexpected exceptions
+  #
+  # For API errors with status codes, use the api_error() method which returns
+  # a string like "api_error_500".
+  class FeatureFlagError
+    ERRORS_WHILE_COMPUTING = 'errors_while_computing_flags'
+    FLAG_MISSING = 'flag_missing'
+    QUOTA_LIMITED = 'quota_limited'
+    TIMEOUT = 'timeout'
+    CONNECTION_ERROR = 'connection_error'
+    UNKNOWN_ERROR = 'unknown_error'
+
+    # Generate API error string with status code.
+    #
+    # @param status [Integer, String] The HTTP status code
+    # @return [String] Error string in format "api_error_STATUS"
+    def self.api_error(status)
+      "api_error_#{status}"
+    end
+  end
+end

lib/posthog/feature_flags.rb

@@ -193,9 +193,11 @@ def get_feature_flag(
 
       request_id = nil
       evaluated_at = nil
+      feature_flag_error = nil
 
       if !flag_was_locally_evaluated && !only_evaluate_locally
         begin
+          errors = []
           flags_data = get_all_flags_and_payloads(distinct_id, groups, person_properties, group_properties,
                                                   only_evaluate_locally, true)
           if flags_data.key?(:featureFlags)
@@ -205,17 +207,44 @@ def get_feature_flag(
           else
             logger.debug "Missing feature flags key: #{flags_data.to_json}"
             flags = {}
+            errors << FeatureFlagError::UNKNOWN_ERROR
+          end
+
+          status = flags_data[:status]
+          if status && status >= 400
+            errors << FeatureFlagError.api_error(status)
+          end
+
+          if flags_data[:errorsWhileComputingFlags]
+            errors << FeatureFlagError::ERRORS_WHILE_COMPUTING
+          end
+
+          if flags_data[:quotaLimited]&.include?('feature_flags')
+            errors << FeatureFlagError::QUOTA_LIMITED
+          end
+
+          unless flags.key?(key.to_s)
+            errors << FeatureFlagError::FLAG_MISSING
           end
 
           response = flags[key]
           response = false if response.nil?
+          feature_flag_error = errors.join(',') unless errors.empty?
+
           logger.debug "Successfully computed flag remotely: #{key} -> #{response}"
+        rescue Timeout::Error, Net::ReadTimeout, Net::WriteTimeout
+          @on_error.call(-1, 'Timeout while fetching flags remotely')
+          feature_flag_error = FeatureFlagError::TIMEOUT
+        rescue Errno::ECONNRESET, Errno::ECONNREFUSED, EOFError, SocketError => e
+          @on_error.call(-1, "Connection error while fetching flags remotely: #{e}")
+          feature_flag_error = FeatureFlagError::CONNECTION_ERROR
         rescue StandardError => e
           @on_error.call(-1, "Error computing flag remotely: #{e}. #{e.backtrace.join("\n")}")
+          feature_flag_error = FeatureFlagError::UNKNOWN_ERROR
         end
       end
 
-      [response, flag_was_locally_evaluated, request_id, evaluated_at]
+      [response, flag_was_locally_evaluated, request_id, evaluated_at, feature_flag_error]
     end
 
     def get_all_flags(
@@ -270,19 +299,26 @@ def get_all_flags_and_payloads(
         fallback_to_server = true
       end
 
+      errors_while_computing = false
+      quota_limited = nil
+      status_code = nil
+
       if fallback_to_server && !only_evaluate_locally
         begin
           flags_and_payloads = get_flags(distinct_id, groups, person_properties, group_properties)
+          errors_while_computing = flags_and_payloads[:errorsWhileComputingFlags] || false
+          quota_limited = flags_and_payloads[:quotaLimited]
+          status_code = flags_and_payloads[:status]
 
           unless flags_and_payloads.key?(:featureFlags)
             raise StandardError, "Error flags response: #{flags_and_payloads}"
-          end
-
           # Check if feature_flags are quota limited
-          if flags_and_payloads[:quotaLimited]&.include?('feature_flags')
+          if quota_limited&.include?('feature_flags')
             logger.warn '[FEATURE FLAGS] Quota limited for feature flags'
             flags = {}
             payloads = {}
+            request_id = flags_and_payloads[:requestId]
+            evaluated_at = flags_and_payloads[:evaluatedAt]
           else
             flags = stringify_keys(flags_and_payloads[:featureFlags] || {})
             payloads = stringify_keys(flags_and_payloads[:featureFlagPayloads] || {})
@@ -299,7 +335,10 @@ def get_all_flags_and_payloads(
         featureFlags: flags,
         featureFlagPayloads: payloads,
         requestId: request_id,
-        evaluatedAt: evaluated_at
+        evaluatedAt: evaluated_at,
+        errorsWhileComputingFlags: errors_while_computing,
+        quotaLimited: quota_limited,
+        status: status_code
       }
     end