Handle errors when refreshing the cache async

Author: drborges

lib/langfuse/client.rb

@@ -156,17 +156,22 @@ def create_cache
           max_size: config.cache_max_size
         )
       when :rails
-        RailsCacheAdapter.new(
-          ttl: config.cache_ttl,
-          lock_timeout: config.cache_lock_timeout,
-          stale_ttl: config.cache_stale_while_revalidate ? config.cache_stale_ttl : nil,
-          refresh_threads: config.cache_refresh_threads
-        )
+        create_rails_cache_adapter
       else
         raise ConfigurationError, "Unknown cache backend: #{config.cache_backend}"
       end
     end
 
+    def create_rails_cache_adapter
+      RailsCacheAdapter.new(
+        ttl: config.cache_ttl,
+        lock_timeout: config.cache_lock_timeout,
+        stale_ttl: config.cache_stale_while_revalidate ? config.cache_stale_ttl : nil,
+        refresh_threads: config.cache_refresh_threads,
+        logger: config.logger
+      )
+    end
+
     # Build the appropriate prompt client based on prompt type
     #
     # @param prompt_data [Hash] The prompt data from API

lib/langfuse/rails_cache_adapter.rb

@@ -2,6 +2,7 @@
 
 require "concurrent"
 require "json"
+require "logger"
 
 module Langfuse
   # rubocop:disable Metrics/ClassLength
@@ -16,7 +17,7 @@ module Langfuse
   #   adapter.get("greeting:1") # => prompt_data
   #
   class RailsCacheAdapter
-    attr_reader :ttl, :namespace, :lock_timeout, :stale_ttl, :thread_pool
+    attr_reader :ttl, :namespace, :lock_timeout, :stale_ttl, :thread_pool, :logger
 
     # Initialize a new Rails.cache adapter
     #
@@ -25,14 +26,16 @@ class RailsCacheAdapter
     # @param lock_timeout [Integer] Lock timeout in seconds for stampede protection (default: 10)
     # @param stale_ttl [Integer, nil] Stale TTL for SWR (default: nil, disabled)
     # @param refresh_threads [Integer] Number of background refresh threads (default: 5)
+    # @param logger [Logger, nil] Logger instance for error reporting (default: nil, creates new logger)
     # @raise [ConfigurationError] if Rails.cache is not available
-    def initialize(ttl: 60, namespace: "langfuse", lock_timeout: 10, stale_ttl: nil, refresh_threads: 5)
+    def initialize(ttl: 60, namespace: "langfuse", lock_timeout: 10, stale_ttl: nil, refresh_threads: 5, logger: nil)
       validate_rails_cache!
 
       @ttl = ttl
       @namespace = namespace
       @lock_timeout = lock_timeout
       @stale_ttl = stale_ttl
+      @logger = logger || default_logger
       @thread_pool = initialize_thread_pool(refresh_threads) if stale_ttl
     end
 
@@ -207,6 +210,8 @@ def initialize_thread_pool(refresh_threads)
     # Prevents duplicate refreshes by using a refresh lock. If another process
     # is already refreshing this key, this method returns immediately.
     #
+    # Errors during refresh are caught and logged to prevent thread crashes.
+    #
     # @param key [String] Cache key
     # @yield Block to execute to fetch fresh data
     # @return [void]
@@ -218,6 +223,8 @@ def schedule_refresh(key)
       thread_pool.post do
         value = yield
         set_with_metadata(key, value)
+      rescue StandardError => e
+        logger.error("Langfuse cache refresh failed for key '#{key}': #{e.class} - #{e.message}")
       ensure
         release_lock(refresh_lock_key)
       end
@@ -346,6 +353,17 @@ def validate_rails_cache!
       raise ConfigurationError,
             "Rails.cache is not available. Rails cache backend requires Rails with a configured cache store."
     end
+
+    # Create a default logger
+    #
+    # @return [Logger]
+    def default_logger
+      if defined?(Rails) && Rails.respond_to?(:logger) && Rails.logger
+        Rails.logger
+      else
+        Logger.new($stdout, level: Logger::WARN)
+      end
+    end
   end
   # rubocop:enable Metrics/ClassLength
 end

spec/langfuse/client_spec.rb

@@ -121,6 +121,36 @@ class << self
           described_class.new(config_with_rails_cache)
         end.not_to raise_error
       end
+
+      it "passes logger from config to RailsCacheAdapter" do
+        custom_logger = Logger.new($stdout)
+        config_with_rails_cache.logger = custom_logger
+        client = described_class.new(config_with_rails_cache)
+        expect(client.api_client.cache.logger).to eq(custom_logger)
+      end
+
+      it "configures RailsCacheAdapter with stale-while-revalidate settings" do
+        config_with_rails_cache.cache_stale_while_revalidate = true
+        config_with_rails_cache.cache_stale_ttl = 300
+        config_with_rails_cache.cache_refresh_threads = 3
+        config_with_rails_cache.cache_lock_timeout = 15
+
+        client = described_class.new(config_with_rails_cache)
+        adapter = client.api_client.cache
+
+        expect(adapter.stale_ttl).to eq(300)
+        expect(adapter.lock_timeout).to eq(15)
+        expect(adapter.thread_pool).to be_a(Concurrent::CachedThreadPool)
+      end
+
+      it "configures RailsCacheAdapter without SWR when disabled" do
+        config_with_rails_cache.cache_stale_while_revalidate = false
+        client = described_class.new(config_with_rails_cache)
+        adapter = client.api_client.cache
+
+        expect(adapter.stale_ttl).to be_nil
+        expect(adapter.thread_pool).to be_nil
+      end
     end
 
     context "with invalid cache backend" do

spec/langfuse/rails_cache_adapter_spec.rb

@@ -93,6 +93,36 @@ class << self
           expect(adapter.thread_pool).to be_nil
         end
       end
+
+      context "with logger parameter" do
+        it "uses provided logger" do
+          custom_logger = Logger.new($stdout)
+          adapter = described_class.new(logger: custom_logger)
+          expect(adapter.logger).to eq(custom_logger)
+        end
+
+        it "creates default stdout logger when no logger provided and Rails.logger not available" do
+          allow(Rails).to receive(:respond_to?).and_return(true)
+          allow(Rails).to receive(:respond_to?).with(:logger).and_return(false)
+          adapter = described_class.new
+          expect(adapter.logger).to be_a(Logger)
+        end
+
+        it "uses Rails.logger as default when Rails is available" do
+          rails_logger = Logger.new($stdout)
+          allow(Rails).to receive(:respond_to?).and_return(true)
+          allow(Rails).to receive(:logger).and_return(rails_logger)
+          adapter = described_class.new
+          expect(adapter.logger).to eq(rails_logger)
+        end
+
+        it "creates stdout logger when Rails.logger returns nil" do
+          allow(Rails).to receive(:respond_to?).and_return(true)
+          allow(Rails).to receive(:logger).and_return(nil)
+          adapter = described_class.new
+          expect(adapter.logger).to be_a(Logger)
+        end
+      end
     end
 
     context "when Rails.cache is not available" do
@@ -698,21 +728,62 @@ class << self
         adapter_with_swr.send(:schedule_refresh, cache_key) { "refreshed_value" }
       end
 
-      it "releases the refresh lock even if block raises" do
+      it "logs error and releases lock when refresh block raises error" do
         cache_key = "test_key"
         refresh_lock_key = "langfuse:#{cache_key}:refreshing"
+        mock_logger = instance_double(Logger)
 
-        allow(adapter_with_swr).to receive(:acquire_refresh_lock)
+        adapter_with_logger = described_class.new(
+          ttl: ttl,
+          stale_ttl: stale_ttl,
+          refresh_threads: refresh_threads,
+          logger: mock_logger
+        )
+
+        allow(adapter_with_logger).to receive(:acquire_refresh_lock)
           .with(refresh_lock_key)
           .and_return(true)
-        allow(adapter_with_swr.thread_pool).to receive(:post).and_yield
+        allow(adapter_with_logger.thread_pool).to receive(:post).and_yield
 
-        expect(adapter_with_swr).to receive(:release_lock)
+        expect(mock_logger).to receive(:error)
+          .with(/Langfuse cache refresh failed for key 'test_key': RuntimeError - test error/)
+
+        expect(adapter_with_logger).to receive(:release_lock)
           .with(refresh_lock_key)
 
+        # Error should be caught and logged, not raised
         expect do
-          adapter_with_swr.send(:schedule_refresh, cache_key) { raise "test error" }
-        end.to raise_error("test error")
+          adapter_with_logger.send(:schedule_refresh, cache_key) { raise "test error" }
+        end.not_to raise_error
+      end
+
+      it "logs error with correct exception class and message" do
+        cache_key = "greeting:1"
+        refresh_lock_key = "langfuse:#{cache_key}:refreshing"
+        mock_logger = instance_double(Logger)
+
+        adapter_with_logger = described_class.new(
+          ttl: ttl,
+          stale_ttl: stale_ttl,
+          refresh_threads: refresh_threads,
+          logger: mock_logger
+        )
+
+        allow(adapter_with_logger).to receive(:acquire_refresh_lock)
+          .with(refresh_lock_key)
+          .and_return(true)
+        allow(adapter_with_logger.thread_pool).to receive(:post).and_yield
+
+        expect(mock_logger).to receive(:error)
+          .with("Langfuse cache refresh failed for key 'greeting:1': ArgumentError - Invalid prompt data")
+
+        expect(adapter_with_logger).to receive(:release_lock)
+          .with(refresh_lock_key)
+
+        # Custom exception type
+        adapter_with_logger.send(:schedule_refresh, cache_key) do
+          raise ArgumentError, "Invalid prompt data"
+        end
       end
     end