solarwinds_apm 7.0.1 → 7.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 62a494962e1b42497287295bec1c5ad4ae5dfa9b57df068d8897707e89e31c73
-  data.tar.gz: dd32d8923f0f93776bad22e506aee1a639c59f153cb67b4c944f92d4018f36d8
+  metadata.gz: d565e746144994b5c3a81ee19665ee9b2d4e81fbad2e21da567465455c37e6c0
+  data.tar.gz: 949351c94748745d2ba19268a531ba5b4f805568132772dcfb9749b0af3698a8
 SHA512:
-  metadata.gz: f28f6c76e3baa28539dc87704f1199e336cea2024a5394e229594d81a77f21280a216738e3bd3a53f5f9a3922a237925e85dd86789e86ff5d47e00b831acb0d0
-  data.tar.gz: e9ad6b91c3d1da150dba81c28a974fbeafe376dbe24be277ec27aeabca58809083c526446d9d66b4b705fe1b304b2b337d3073f8bc094b6e3f5f827709f63388
+  metadata.gz: 209a50b78aa94dc85805ef8c6c08db7584966ca62293c53aa9744852170c3c84ac4ef24b2e43e508bad5d1e505f4cd82d72d984a00823232b9a9e13bddb061c6
+  data.tar.gz: '0962ab7325e66d3f330361b9f0187f75c07eabcd2d0d400db0d55e75c2124aefa2fe630cbe2eef506f48f58f6e6d3cb6ad1d36f1a816845618b6bd2649e8b951'

data/README.md

@@ -3,6 +3,7 @@
 The `solarwinds_apm` gem starting from version 6.0.0 is an [OpenTelemetry Ruby](https://opentelemetry.io/docs/instrumentation/ruby/) distribution. It provides automatic instrumentation and custom SolarWinds Observability features for Ruby applications.
 
 ## Requirements
+>
 > [!NOTE]
 > Versions before 7.0.0 only support Linux and will go into no-op mode on other platforms.
 

data/lib/solarwinds_apm/api/transaction_name.rb

@@ -21,15 +21,16 @@ module SolarWindsAPM
       #
       # === Example:
       #
-      #   class DogfoodsController < ApplicationController
+      #   class OrdersController < ApplicationController
       #
       #     def create
-      #       @dogfood = Dogfood.new(params.permit(:brand, :name))
-      #       @dogfood.save
+      #       @order = Order.new(params.permit(:item, :quantity))
+      #       if @order.save
+      #         custom_name = "orderscontroller.create_for_#{params[:item]}"
+      #         SolarWindsAPM::API.set_transaction_name(custom_name)
+      #       end
       #
-      #       SolarWindsAPM::API.set_transaction_name("dogfoodscontroller.create_for_#{params[:brand]}")
-      #
-      #       redirect_to @dogfood
+      #       redirect_to @order
       #     end
       #
       #   end

data/lib/solarwinds_apm/config.rb

@@ -87,21 +87,32 @@ module SolarWindsAPM
       SolarWindsAPM.logger.level = SW_LOG_LEVEL_MAPPING.dig(log_level, :stdlib) || ::Logger::INFO # default log level info
     end
 
+    # e.g. enable_disable_config('STRING', :key, value, false, bool: true)
     def self.enable_disable_config(env_var, key, value, default, bool: false)
-      env_value = ENV[env_var.to_s]&.downcase
+      raw_env_value  = ENV.fetch(env_var, '')
+      env_value      = raw_env_value.downcase
       valid_env_values = bool ? %w[true false] : %w[enabled disabled]
 
-      if env_var && valid_env_values.include?(env_value)
+      if !env_var.empty? && valid_env_values.include?(env_value)
         value = bool ? true?(env_value) : env_value.to_sym
-      elsif env_var && !env_value.to_s.empty?
-        SolarWindsAPM.logger.warn("[#{name}/#{__method__}] #{env_var} must be #{valid_env_values.join('/')} (current setting is #{ENV.fetch(env_var, nil)}). Using default value: #{default}.")
-        return @@config[key.to_sym] = default
+      elsif !env_var.empty? && !raw_env_value.empty?
+        SolarWindsAPM.logger.warn do
+          "[#{name}/#{__method__}] #{env_var} must be #{valid_env_values.join('/')} (current setting is #{raw_env_value}). Using default value: #{default}."
+        end
+        return @@config[key] = default
       end
 
-      return @@config[key.to_sym] = value unless (bool && !boolean?(value)) || (!bool && !symbol?(value))
+      # Validate final value efficiently
+      valid = bool ? boolean?(value) : symbol?(value)
+
+      unless valid
+        SolarWindsAPM.logger.warn do
+          "[#{name}/#{__method__}] :#{key} must be #{valid_env_values.join('/')}. Using default value: #{default}."
+        end
+        return @@config[key] = default
+      end
 
-      SolarWindsAPM.logger.warn("[#{name}/#{__method__}] :#{key} must be a #{valid_env_values.join('/')}. Using default value: #{default}.")
-      @@config[key.to_sym] = default
+      @@config[key] = value
     end
 
     def self.true?(obj)
@@ -211,7 +222,7 @@ module SolarWindsAPM
         enable_disable_config('SW_APM_TRIGGER_TRACING_MODE', key, value, :enabled)
 
       when :tracing_mode
-        enable_disable_config(nil, key, value, :enabled)
+        enable_disable_config('', key, value, :enabled)
 
       when :tag_sql
         enable_disable_config('SW_APM_TAG_SQL', key, value, false, bool: true)
@@ -242,9 +253,17 @@ module SolarWindsAPM
         return
       end
 
-      # `tracing: disabled` is the default
-      disabled = settings.select { |v| !v.key?(:tracing) || v[:tracing] == :disabled }
-      enabled  = settings.select { |v| v[:tracing] == :enabled }
+      # `tracing: disabled` is the default; below only separate the enabled and disabled settings
+      result = settings.each_with_object({ enabled: [], disabled: [] }) do |setting, acc|
+        if setting[:tracing] == :enabled
+          acc[:enabled] << setting
+        elsif !setting.key?(:tracing) || setting[:tracing] == :disabled
+          acc[:disabled] << setting
+        end
+      end
+
+      enabled = result[:enabled]
+      disabled = result[:disabled]
 
       SolarWindsAPM::Config[:enabled_regexps] = compile_regexp(enabled)
       SolarWindsAPM::Config[:disabled_regexps] = compile_regexp(disabled)

data/lib/solarwinds_apm/opentelemetry/otlp_processor.rb

@@ -21,12 +21,15 @@ module SolarWindsAPM
       HTTP_STATUS_CODE    = 'http.status_code'
       HTTP_URL            = 'http.url'
 
+      HTTP_RESPONSE_STATUS_CODE = 'http.response.status_code'
+      HTTP_REQUEST_METHOD = 'http.request.method'
+
       INVALID_HTTP_STATUS_CODE = 0
 
       def initialize(txn_manager)
         @txn_manager = txn_manager
-        @meters      = { 'sw.apm.request.metrics' => ::OpenTelemetry.meter_provider.meter('sw.apm.request.metrics') }
         @metrics     = init_response_time_metrics
+        @is_lambda   = SolarWindsAPM::Utils.determine_lambda
         @transaction_name = nil
       end
 
@@ -40,21 +43,24 @@ module SolarWindsAPM
         trace_flags = span.context.trace_flags.sampled? ? '01' : '00'
         @txn_manager&.set_root_context_h(span.context.hex_trace_id, "#{span.context.hex_span_id}-#{trace_flags}")
         span.add_attributes({ SW_IS_ENTRY_SPAN => true })
+        SolarWindsAPM.logger.debug { "[#{self.class}/#{__method__}] processor on_start end" }
       rescue StandardError => e
         SolarWindsAPM.logger.info { "[#{self.class}/#{__method__}] processor on_start error: #{e.message}" }
       end
 
       def on_finishing(span)
+        SolarWindsAPM.logger.debug { "[#{self.class}/#{__method__}] processor on_finishing span attributes: #{span.attributes}" }
         return if non_entry_span(span: span)
 
         @transaction_name = calculate_transaction_names(span)
         span.set_attribute(SW_TRANSACTION_NAME, @transaction_name)
         @txn_manager.delete_root_context_h(span.context.hex_trace_id)
+        SolarWindsAPM.logger.debug { "[#{self.class}/#{__method__}] processor on_finishing end" }
       end
 
       # @param [Span] span the (immutable) {Span} that just ended.
       def on_finish(span)
-        SolarWindsAPM.logger.debug { "[#{self.class}/#{__method__}] processor on_finish span: #{span.to_span_data.inspect}" }
+        SolarWindsAPM.logger.debug { "[#{self.class}/#{__method__}] processor on_finish span attributes: #{span.attributes}" }
         return if non_entry_span(span: span)
 
         record_request_metrics(span)
@@ -63,10 +69,9 @@ module SolarWindsAPM
         ::OpenTelemetry.meter_provider.metric_readers.each do |reader|
           reader.pull if reader.respond_to? :pull
         end
-
-        SolarWindsAPM.logger.debug { "[#{self.class}/#{__method__}] processor on_finish succeed" }
+        SolarWindsAPM.logger.debug { "[#{self.class}/#{__method__}] processor on_finish end" }
       rescue StandardError => e
-        SolarWindsAPM.logger.info { "[#{self.class}/#{__method__}] error processing span on_finish: #{e.message}" }
+        SolarWindsAPM.logger.info { "[#{self.class}/#{__method__}] processor on_finish error: #{e.message}" }
       end
 
       # @param [optional Numeric] timeout An optional timeout in seconds.
@@ -94,7 +99,9 @@ module SolarWindsAPM
                                                   unit: 'ms')
         end
 
-        instrument = @meters['sw.apm.request.metrics'].create_histogram('trace.service.response_time', unit: 'ms', description: 'Duration of each entry span for the service, typically meaning the time taken to process an inbound request.')
+        meter = ::OpenTelemetry.meter_provider.meter('sw.apm.request.metrics')
+        instrument = meter.create_histogram('trace.service.response_time', unit: 'ms', description: 'Duration of each entry span for the service, typically meaning the time taken to process an inbound request.')
+        SolarWindsAPM.logger.debug { "[#{self.class}/#{__method__}] Adding ExponentialBucketHistogram for response time metrics: #{instrument.inspect}" }
         { response_time: instrument }
       end
 
@@ -104,37 +111,43 @@ module SolarWindsAPM
           SW_TRANSACTION_NAME => @transaction_name
         }
 
-        if span_http?(span)
+        is_http_span = span_http?(span)
+
+        if is_http_span
           http_status_code = get_http_status_code(span)
-          meter_attrs['http.status_code'] = http_status_code if http_status_code != 0
-          meter_attrs['http.method'] = span.attributes[HTTP_METHOD] if span.attributes[HTTP_METHOD]
+          meter_attrs[HTTP_STATUS_CODE] = http_status_code if http_status_code != 0
+          meter_attrs[HTTP_METHOD] = span.attributes[HTTP_METHOD] if span.attributes[HTTP_METHOD]
+          meter_attrs[HTTP_METHOD] = span.attributes[HTTP_REQUEST_METHOD] if span.attributes[HTTP_REQUEST_METHOD]
         end
-        SolarWindsAPM.logger.debug { "[#{self.class}/#{__method__}] meter_attrs: #{meter_attrs.inspect}" }
+
+        SolarWindsAPM.logger.debug { "[#{self.class}/#{__method__}] is_http_span: #{is_http_span}; meter_attrs: #{meter_attrs.inspect}" }
         meter_attrs.compact!
         meter_attrs
       end
 
       def calculate_lambda_transaction_name(span_name)
-        (ENV['SW_APM_TRANSACTION_NAME'] || ENV['AWS_LAMBDA_FUNCTION_NAME'] || span_name || 'unknown').slice(0, SolarWindsAPM::Constants::MAX_TXN_NAME_LENGTH)
+        txn_name = (ENV['SW_APM_TRANSACTION_NAME'] || ENV['AWS_LAMBDA_FUNCTION_NAME'] || span_name || 'unknown').slice(0, SolarWindsAPM::Constants::MAX_TXN_NAME_LENGTH)
+        SolarWindsAPM.logger.debug { "[#{self.class}/#{__method__}] Lambda transaction name: #{txn_name} (from env_txn=#{ENV.fetch('SW_APM_TRANSACTION_NAME', nil)}, lambda_func=#{ENV.fetch('AWS_LAMBDA_FUNCTION_NAME', nil)}, span_name=#{span_name})" }
+        txn_name
       end
 
       # Get trans_name and url_tran of this span instance.
       # Predecessor order: custom SDK > env var SW_APM_TRANSACTION_NAME > automatic naming
       def calculate_transaction_names(span)
-        return calculate_lambda_transaction_name(span.name) if SolarWindsAPM::Utils.determine_lambda
+        return calculate_lambda_transaction_name(span.name) if @is_lambda
 
         trace_span_id = "#{span.context.hex_trace_id}-#{span.context.hex_span_id}"
         trans_name = @txn_manager.get(trace_span_id)
         if trans_name
-          SolarWindsAPM.logger.debug do
-            "[#{self.class}/#{__method__}] found trans name from txn_manager: #{trans_name} by #{trace_span_id}"
-          end
+          SolarWindsAPM.logger.debug { "[#{self.class}/#{__method__}] Using transaction name from txn_manager: #{trans_name} (#{trace_span_id})" }
           @txn_manager.del(trace_span_id)
         elsif !ENV['SW_APM_TRANSACTION_NAME'].to_s.empty?
           trans_name = ENV.fetch('SW_APM_TRANSACTION_NAME', nil)
+          SolarWindsAPM.logger.debug { "[#{self.class}/#{__method__}] Using transaction name from env var: #{trans_name}" }
         else
-          trans_name = span.attributes[HTTP_ROUTE] || nil
-          trans_name = span.name if trans_name.to_s.empty? && span.name
+          trans_name = span.attributes[HTTP_ROUTE]
+          trans_name = span.name if trans_name.to_s.empty?
+          SolarWindsAPM.logger.debug { "[#{self.class}/#{__method__}] Using transaction name from span.attributes: #{span.attributes[HTTP_ROUTE]} or span.name: #{span.name}" }
         end
         trans_name.to_s.slice(0, SolarWindsAPM::Constants::MAX_TXN_NAME_LENGTH)
       end
@@ -163,14 +176,14 @@ module SolarWindsAPM
 
       # This span from inbound HTTP request if from a SERVER by some http.method
       def span_http?(span)
-        span.kind == ::OpenTelemetry::Trace::SpanKind::SERVER && !span.attributes[HTTP_METHOD].nil?
+        (!span.attributes[HTTP_METHOD].nil? || !span.attributes[HTTP_REQUEST_METHOD].nil?) && span.kind == ::OpenTelemetry::Trace::SpanKind::SERVER
       end
 
       # Calculate HTTP status_code from span or default to UNAVAILABLE
       # Something went wrong in OTel or instrumented service crashed early
       # if no status_code in attributes of HTTP span
       def get_http_status_code(span)
-        span.attributes[HTTP_STATUS_CODE] || INVALID_HTTP_STATUS_CODE
+        span.attributes[HTTP_RESPONSE_STATUS_CODE] || span.attributes[HTTP_STATUS_CODE] || INVALID_HTTP_STATUS_CODE
       end
 
       # check if it's entry span based on no parent or parent is remote

data/lib/solarwinds_apm/opentelemetry/solarwinds_propagator.rb

@@ -40,6 +40,9 @@ module SolarWindsAPM
           context = ::OpenTelemetry::Context.new({}) if context.nil?
           context = inject_extracted_header(carrier, context, getter, XTRACEOPTIONS_HEADER_NAME, INTL_SWO_X_OPTIONS_KEY)
           inject_extracted_header(carrier, context, getter, XTRACEOPTIONS_SIGNATURE_HEADER_NAME, INTL_SWO_SIGNATURE_KEY)
+        rescue StandardError => e
+          SolarWindsAPM.logger.debug { "[#{self.class}/#{__method__}] Extraction failed: #{e.message}" }
+          context || ::OpenTelemetry::Context.current
         end
 
         # Inject trace context into the supplied carrier.
@@ -80,10 +83,13 @@ module SolarWindsAPM
             end
             setter.set(carrier, TRACESTATE_HEADER_NAME, Utils.trace_state_header(trace_state))
           end
+        rescue StandardError => e
+          SolarWindsAPM.logger.debug { "[#{self.class}/#{__method__}] Injection failed: #{e.message}" }
         end
 
-        # Returns the predefined propagation fields. If your carrier is reused, you
-        # should delete the fields returned by this method before calling +inject+.
+        # Returns the predefined propagation fields, required by upstream.
+        # If your carrier is reused, you should delete the fields returned by
+        # this method before calling +inject+.
         #
         # @return [Array<String>] a list of fields that will be used by this propagator.
         def fields

data/lib/solarwinds_apm/opentelemetry/solarwinds_response_propagator.rb

@@ -56,31 +56,21 @@ module SolarWindsAPM
                        xtraceoptions_response)
           end
           setter.set(carrier, HTTP_HEADER_ACCESS_CONTROL_EXPOSE_HEADERS, exposed_headers.join(','))
-        end
-
-        # Returns the predefined propagation fields. If your carrier is reused, you
-        # should delete the fields returned by this method before calling +inject+.
-        #
-        # @return [Array<String>] a list of fields that will be used by this propagator.
-        def fields
-          TRACESTATE_HEADER_NAME
+        rescue StandardError => e
+          SolarWindsAPM.logger.debug { "[#{self.class}/#{__method__}] Injection failed: #{e.message}" }
         end
 
         private
 
-        # sw_xtraceoptions_response_key -> xtrace_options_response
+        # SW_XTRACEOPTIONS_RESPONSE_KEY -> xtrace_options_response
         def recover_response_from_tracestate(span_context)
           sanitized = span_context.tracestate.value(SW_XTRACEOPTIONS_RESPONSE_KEY)
           sanitized = '' if sanitized.nil?
           sanitized = sanitized.gsub(SolarWindsAPM::Constants::INTL_SWO_EQUALS_W3C_SANITIZED,
                                      SolarWindsAPM::Constants::INTL_SWO_EQUALS)
           sanitized = sanitized.gsub(':', SolarWindsAPM::Constants::INTL_SWO_EQUALS)
-          sanitized = sanitized.gsub(SolarWindsAPM::Constants::INTL_SWO_COMMA_W3C_SANITIZED,
-                                     SolarWindsAPM::Constants::INTL_SWO_COMMA)
-          SolarWindsAPM.logger.debug do
-            "[#{self.class}/#{__method__}] recover_response_from_tracestate sanitized: #{sanitized.inspect}"
-          end
-          sanitized
+          sanitized.gsub(SolarWindsAPM::Constants::INTL_SWO_COMMA_W3C_SANITIZED,
+                         SolarWindsAPM::Constants::INTL_SWO_COMMA)
         end
       end
     end

data/lib/solarwinds_apm/opentelemetry.rb

@@ -11,6 +11,9 @@ require 'opentelemetry-metrics-sdk'
 require 'opentelemetry-exporter-otlp'
 require 'opentelemetry-exporter-otlp-metrics'
 require 'opentelemetry-instrumentation-all'
+require 'opentelemetry-logs-sdk'
+require 'opentelemetry-exporter-otlp-logs'
+require 'opentelemetry-instrumentation-logger'
 
 require_relative 'opentelemetry/solarwinds_propagator'
 require_relative 'opentelemetry/solarwinds_response_propagator'

data/lib/solarwinds_apm/otel_config.rb

@@ -25,8 +25,6 @@ module SolarWindsAPM
 
       is_lambda = SolarWindsAPM::Utils.determine_lambda
 
-      ENV['OTEL_TRACES_EXPORTER'] = ENV['OTEL_TRACES_EXPORTER'].to_s.split(',').tap { |e| e << 'otlp' unless e.include?('otlp') }.join(',')
-
       # add response propagator to rack instrumentation
       resolve_response_propagator
 
@@ -74,6 +72,9 @@ module SolarWindsAPM
         ENV['OTEL_LOG_LEVEL'] = SolarWindsAPM::Config::SW_LOG_LEVEL_MAPPING.dig(log_level, :otel)
       end
 
+      # disable log bridge by default
+      ENV['OTEL_RUBY_INSTRUMENTATION_LOGGER_ENABLED'] = 'false' unless %w[true false].include?(ENV['OTEL_RUBY_INSTRUMENTATION_LOGGER_ENABLED'].to_s)
+
       ::OpenTelemetry::SDK.configure do |c|
         c.resource = final_attributes
         c.use_all(@@config_map)

data/lib/solarwinds_apm/sampling/dice.rb

@@ -12,7 +12,7 @@ module SolarWindsAPM
     attr_reader :rate, :scale
 
     def initialize(settings)
-      @scale = settings[:scale]
+      @scale = settings[:scale] || 1_000_000
       @rate = settings[:rate] || 0
       @random_generator = Random.new
     end

data/lib/solarwinds_apm/sampling/http_sampler.rb

@@ -25,6 +25,7 @@ module SolarWindsAPM
       @pid = nil
       @thread = nil
 
+      @logger.debug { "[#{self.class}/#{__method__}] HttpSampler initialized: url=#{@url}, service=#{@service}, hostname=#{@hostname}, setting_url=#{@setting_url}" }
       reset_on_fork
     end
 
@@ -57,7 +58,6 @@ module SolarWindsAPM
     def fetch_with_timeout(url, timeout_seconds = nil)
       uri = url
       timeout = timeout_seconds || REQUEST_TIMEOUT
-
       deadline = Process.clock_gettime(Process::CLOCK_MONOTONIC) + timeout
 
       remaining = lambda {
@@ -94,26 +94,33 @@ module SolarWindsAPM
 
     # a endless loop within a thread (non-blocking)
     def settings_request
+      @logger.debug { "[#{self.class}/#{__method__}] Starting settings request loop" }
+      sleep_duration = GET_SETTING_DURATION
       loop do
-        @logger.debug { "Retrieving sampling settings from #{@setting_url}" }
-
         response = fetch_with_timeout(@setting_url)
-        parsed = response.nil? ? nil : JSON.parse(response.body)
 
-        @logger.debug { "parsed settings in json: #{parsed.inspect}" }
+        # Check for nil response from timeout
+        unless response.is_a?(Net::HTTPSuccess)
+          @logger.warn { "[#{self.class}/#{__method__}] Failed to retrieve settings due to timeout." }
+          next
+        end
+
+        parsed = JSON.parse(response.body)
 
         if update_settings(parsed)
           # update the settings before the previous ones expire with some time to spare
           expiry = (parsed['timestamp'].to_i + parsed['ttl'].to_i)
           expiry_timeout = expiry - REQUEST_TIMEOUT - Time.now.to_i
-          sleep([0, expiry_timeout].max)
+          sleep_duration = [0, expiry_timeout].max
         else
-          @logger.warn { 'Retrieved sampling settings are invalid. Ensure proper configuration.' }
-          sleep(GET_SETTING_DURATION)
+          @logger.warn { "[#{self.class}/#{__method__}] Retrieved sampling settings are invalid. Ensure proper configuration." }
         end
+      rescue JSON::ParserError => e
+        @logger.warn { "[#{self.class}/#{__method__}] JSON parsing error: #{e.message}" }
       rescue StandardError => e
-        @logger.warn { "Failed to retrieve sampling settings (#{e.message}), tracing will be disabled until valid ones are available." }
-        sleep(GET_SETTING_DURATION)
+        @logger.warn { "[#{self.class}/#{__method__}] Failed to retrieve sampling settings (#{e.message}), tracing will be disabled until valid ones are available." }
+      ensure
+        sleep(sleep_duration)
       end
     end
   end

data/lib/solarwinds_apm/sampling/json_sampler.rb

@@ -15,11 +15,12 @@ module SolarWindsAPM
 
       @path = path || DEFAULT_PATH
       @expiry = Time.now.to_i
+      @last_mtime = nil
+      @logger.debug { "[#{self.class}/#{__method__}] JsonSampler initialized: path=#{@path}, initial_expiry=#{@expiry}" }
       loop_check
     end
 
     # only json sampler will need to check if the settings.json file
-    # updated or not from collector extention
     def should_sample?(params)
       loop_check
       super
@@ -27,26 +28,40 @@ module SolarWindsAPM
 
     private
 
+    # multi-thread is rare in lambda environment,
+    # here we don't use mutex to guard the execution
     def loop_check
-      # Update if we're within 10s of expiry
-      return if Time.now.to_i + 10 < @expiry
+      return if Time.now.to_i < @expiry - 10
 
+      # 1. Read and parse settings from the file.
       begin
-        contents = File.read(@path)
-        unparsed = JSON.parse(contents)
-      rescue StandardError => e
-        @logger.debug { "missing or invalid settings file; Error: #{e.message}" }
+        current_mtime = File.mtime(@path)
+        return if @last_mtime && current_mtime == @last_mtime
+
+        settings_data = JSON.parse(File.read(@path))
+        @last_mtime = current_mtime
+      rescue Errno::ENOENT
+        # File doesn't exist due to timing, missing collector, etc
+        @logger.error { "[#{self.class}##{__method__}] Settings file not found at #{@path}." }
+        return
+      rescue JSON::ParserError => e
+        @logger.error { "[#{self.class}##{__method__}] JSON parsing error in #{@path}: #{e.message}" }
         return
       end
 
-      unless unparsed.is_a?(Array) && unparsed.length == 1
-        @logger.debug { "invalid settings file : #{unparsed}" }
+      # 2. Validate the structure of the parsed settings.
+      unless settings_data.is_a?(Array) && settings_data.length == 1
+        @logger.error { "[#{self.class}##{__method__}] Invalid settings file content: #{settings_data.inspect}" }
         return
       end
 
-      parsed = update_settings(unparsed.first)
-      @logger.debug { "update_settings: #{parsed}" }
-      @expiry = parsed[:timestamp].to_i + parsed[:ttl].to_i if parsed
+      # 3. Attempt to update the settings.
+      if (new_settings = update_settings(settings_data.first))
+        @expiry = new_settings[:timestamp].to_i + new_settings[:ttl].to_i
+        @logger.debug { "[#{self.class}##{__method__}] Settings #{new_settings} updated successfully. New expiry: #{@expiry}" }
+      else
+        @logger.debug { "[#{self.class}##{__method__}] Settings update failed, keeping current expiry: #{@expiry}" }
+      end
     end
   end
 end