semantic_logger 5.1.0 → 5.2.0

data/lib/semantic_logger/appender/syslog.rb

@@ -1,4 +1,3 @@
-require "syslog"
 require "uri"
 require "socket"
 # Send log messages to local syslog, or remote syslog servers over TCP or UDP.
@@ -78,7 +77,7 @@ module SemanticLogger
       #     Default: 1024 bytes
       #
       #   options: [Integer]
-      #     Default: ::Syslog::LOG_PID | ::Syslog::LOG_CONS
+      #     Default: ::Syslog::LOG_PID | ::Syslog::LOG_CONS (when logging to a local syslog daemon)
       #     Any of the following (options can be logically OR'd together)
       #       ::Syslog::LOG_CONS
       #       ::Syslog::LOG_NDELAY
@@ -91,7 +90,7 @@ module SemanticLogger
       #        I.e. When `url: 'syslog://localhost'`
       #
       #   facility: [Integer]
-      #     Default: ::Syslog::LOG_USER
+      #     Default: ::Syslog::LOG_USER (the same value as SemanticLogger::Formatters::Syslog::LOG_USER)
       #     Type of program (can be logically OR'd together)
       #       ::Syslog::LOG_AUTH
       #       ::Syslog::LOG_AUTHPRIV
@@ -124,19 +123,19 @@ module SemanticLogger
       #     # Change the warn level to LOG_NOTICE level instead of a the default of LOG_WARNING.
       #     SemanticLogger.add_appender(appender: :syslog, level_map: {warn: ::Syslog::LOG_NOTICE})
       def initialize(url: "syslog://localhost",
-                     facility: ::Syslog::LOG_USER,
-                     max_size: 1024,
+                     facility: SemanticLogger::Formatters::Syslog::LOG_USER,
+                     max_size: SemanticLogger::Formatters::Syslog::DEFAULT_MAX_SIZE,
                      level_map: SemanticLogger::Formatters::Syslog::LevelMap.new,
-                     options: ::Syslog::LOG_PID | ::Syslog::LOG_CONS,
+                     options: nil,
                      tcp_client: {},
                      **args,
                      &)
         @options            = options
         @facility           = facility
         @max_size           = max_size
-        @level_map          = level_map
+        @level_map          = SemanticLogger::Formatters::Syslog::LevelMap.build(level_map)
         @url                = url
-        uri                 = URI(@url)
+        uri                 = Utils.parse_url(@url)
         @server             = uri.host || "localhost"
         @protocol           = (uri.scheme || :syslog).to_sym
         @port               = uri.port || 514
@@ -145,28 +144,36 @@ module SemanticLogger
 
         raise "Unknown protocol #{@protocol}!" unless %i[syslog tcp udp].include?(@protocol)
 
-        # The syslog_protocol gem is required when logging over TCP or UDP.
-        if %i[tcp udp].include?(@protocol)
+        # The syslog gem, a bundled gem since Ruby 3.4, is only required when logging to a local syslog daemon.
+        if @protocol == :syslog
           begin
-            require "syslog_protocol"
+            require "syslog"
           rescue LoadError
             raise LoadError,
-                  "Missing gem: syslog_protocol. This gem is required when logging over TCP or UDP. " \
-                  "To fix this error: gem install syslog_protocol"
+                  "Missing gem: syslog. This gem is required when logging to a local syslog daemon on Ruby 3.4 " \
+                  'and later. Please add the gem "syslog" to your Gemfile.'
           end
+          @options ||= ::Syslog::LOG_PID | ::Syslog::LOG_CONS
+        end
 
-          # The net_tcp_client gem is required when logging over TCP.
-          if protocol == :tcp
-            begin
-              require "net/tcp_client"
-            rescue LoadError
-              raise LoadError,
-                    "Missing gem: net_tcp_client. This gem is required when logging over TCP. " \
-                    "To fix this error: gem install net_tcp_client"
-            end
+        # The net_tcp_client gem is required when logging over TCP.
+        # The syslog formatters load the syslog_protocol gem that they use to build remote syslog packets.
+        if @protocol == :tcp
+          begin
+            require "net/tcp_client"
+          rescue LoadError
+            raise LoadError,
+                  "Missing gem: net_tcp_client. This gem is required when logging over TCP. " \
+                  "To fix this error: gem install net_tcp_client"
           end
         end
 
+        if %i[tcp udp].include?(@protocol)
+          # Reject an invalid facility when the appender is created, even with a formatter that ignores it.
+          SemanticLogger::Formatters::Syslog.facility_number(@facility)
+          args[:formatter] = with_packet_options(args[:formatter]) if args.key?(:formatter)
+        end
+
         super(**args, &)
         reopen
       end
@@ -195,12 +202,12 @@ module SemanticLogger
         case @protocol
         when :syslog
           # Since the Ruby Syslog API supports sprintf format strings, double up all existing '%'
-          message = formatter.call(log, self).gsub "%", "%%"
+          message = format_log(log).gsub "%", "%%"
           ::Syslog.log @level_map[log.level], message
         when :tcp
-          @remote_syslog.retry_on_connection_failure { @remote_syslog.write("#{formatter.call(log, self)}\r\n") }
+          @remote_syslog.retry_on_connection_failure { @remote_syslog.write("#{format_log(log)}\r\n") }
         when :udp
-          @remote_syslog.send(formatter.call(log, self), 0, @server, @port)
+          @remote_syslog.send(format_log(log), 0, @server, @port)
         else
           raise "Unsupported protocol: #{protocol}"
         end
@@ -212,17 +219,48 @@ module SemanticLogger
         @remote_syslog.flush if @remote_syslog.respond_to?(:flush)
       end
 
+      # Over UDP, a log message too large for a datagram (Errno::EMSGSIZE) cannot be sent by retrying.
+      def message_error?(exception)
+        (@protocol == :udp && exception.is_a?(Errno::EMSGSIZE)) || super
+      end
+
       # Returns [SemanticLogger::Formatters::Base] default formatter for this Appender
       # depending on the protocol selected
       def default_formatter
         if protocol == :syslog
           # Format is text output without the time.
           # Escape control characters so untrusted log data cannot forge syslog entries.
-          SemanticLogger::Formatters::Default.new(time_format: :notime, escape_control_chars: true)
+          # Exception details are off, as with the remote syslog formatters, so existing records do not change.
+          SemanticLogger::Formatters::Default.new(
+            time_format: :notime, escape_control_chars: true, log_exception_details: false
+          )
         else
           SemanticLogger::Formatters::Syslog.new(facility: facility, level_map: level_map, max_size: max_size)
         end
       end
+
+      # The formatters that build remote syslog packets, and so need this appender's facility, level map,
+      # and maximum packet size.
+      PACKET_FORMATTERS = %i[syslog syslog_cee].freeze
+      private_constant :PACKET_FORMATTERS
+
+      # The url without any credentials. See Subscriber#inspect.
+      def inspect_details
+        "url=#{Utils.redacted_url(url).inspect}"
+      end
+
+      private
+
+      # Returns the supplied `formatter:` argument, with this appender's facility, level map, and
+      # maximum packet size added when it names one of the PACKET_FORMATTERS, so that they are not
+      # silently ignored. Options in a
+      # `{syslog: {...}}` Hash take precedence. A formatter instance keeps its own settings.
+      def with_packet_options(formatter)
+        name, options = formatter.is_a?(Hash) ? formatter.first : [formatter, {}]
+        return formatter unless name.respond_to?(:to_sym) && PACKET_FORMATTERS.include?(name.to_sym)
+
+        {name.to_sym => {facility: facility, level_map: level_map, max_size: max_size}.merge(options || {})}
+      end
     end
   end
 end

data/lib/semantic_logger/appender/tcp.rb

@@ -205,7 +205,7 @@ module SemanticLogger
 
       # Write the log using the specified protocol and server.
       def log(log)
-        message = formatter.call(log, self)
+        message = format_log(log)
         @tcp_client.retry_on_connection_failure do
           @tcp_client.write("#{message}#{separator}")
         end
@@ -222,6 +222,11 @@ module SemanticLogger
         @tcp_client&.close
       end
 
+      # Only the servers: the other options can hold TLS keys and passwords. See Subscriber#inspect.
+      def inspect_details
+        "server=#{(@tcp_client_args[:server] || @tcp_client_args[:servers]).inspect}"
+      end
+
       private
 
       # Returns [SemanticLogger::Formatters::Default] formatter default for this Appender

data/lib/semantic_logger/appender/udp.rb

@@ -80,7 +80,7 @@ module SemanticLogger
 
       # Write the log using the specified protocol and server.
       def log(log)
-        @socket.send(formatter.call(log, self), udp_flags)
+        @socket.send(format_log(log), udp_flags)
         true
       end
 
@@ -94,6 +94,16 @@ module SemanticLogger
         @socket&.close
       end
 
+      # A log message too large for a datagram (Errno::EMSGSIZE) cannot be sent by retrying.
+      def message_error?(exception)
+        exception.is_a?(Errno::EMSGSIZE) || super
+      end
+
+      # See Subscriber#inspect.
+      def inspect_details
+        "server=#{server.inspect}"
+      end
+
       private
 
       # Returns [SemanticLogger::Formatters::Default] formatter default for this Appender

data/lib/semantic_logger/appender/wrapper.rb

@@ -57,7 +57,7 @@ module SemanticLogger
       #  Ruby or Rails Loggers
       def log(log)
         level = log.level == :trace ? :debug : log.level
-        @logger.send(level, formatter.call(log, self))
+        @logger.send(level, format_log(log))
         true
       end
 

data/lib/semantic_logger/appenders.rb

@@ -37,7 +37,7 @@ module SemanticLogger
     # Returns [Array<Hash>] operational statistics for each appender.
     #
     # Appenders that run asynchronously (see SemanticLogger::Appender::Async#stats) report
-    # their queue size and processed/dropped counts. Appenders that log inline on the
+    # their queue size and processed/dropped/failed counts. Appenders that log inline on the
     # processor thread report only their name with `async: false`.
     def stats
       map do |appender|
@@ -49,9 +49,17 @@ module SemanticLogger
       end
     end
 
+    # Write the log message to every appender that should log it. An appender that fails is
+    # reported, and the others still write the message.
+    #
+    # A stack overflow is not a failure of the appender but of the thread, which must not overflow
+    # again: on macOS a second stack overflow on the same thread crashes Ruby. It is raised to the
+    # processor running this thread instead, and the message goes to no further appenders.
     def log(log)
       each do |appender|
         appender.log(log) if appender.should_log?(log)
+      rescue SystemStackError
+        raise
       rescue Exception => e
         logger.error "Failed to log to appender: #{appender.name}", e
       end

data/lib/semantic_logger/base.rb

@@ -28,23 +28,38 @@ module SemanticLogger
       end
     end
 
-    # Returns the current log level if set, otherwise it returns the global
-    # default log level
+    # Returns the level set by an enclosing `#with_level` block on the current fiber,
+    # otherwise the level set for this instance, otherwise the global default level.
     def level
-      @level || SemanticLogger.default_level
+      index = @with_level_used && with_level_index
+      return Levels.level(index) if index
+
+      @level || fallback_level
     end
 
-    # Set the logging level for this logger during the execution of the given block
+    # Change the log level of this instance while the block runs, on the current fiber only.
     #
-    # Refer to the documentation for `#level=` for more information about the possible log levels.
-    def with_level(new_level)
-      old_level = level
-
-      self.level = new_level
-
-      yield
-    ensure
-      self.level = old_level
+    # Other threads and fibers that share this instance keep logging at its own level.
+    # The level set with `#level=` is left untouched, so an instance that follows the
+    # global default level keeps following it after the block. Blocks can be nested.
+    #
+    # Matches Ruby's `Logger#with_level`, which Sidekiq calls to apply a job's `log_level`.
+    # Accepts the same levels as `#level=`. Returns the result of the block.
+    def with_level(level)
+      index            = Levels.index(level)
+      overrides        = (Thread.current[:semantic_logger_with_level] ||= {}.compare_by_identity)
+      previous         = overrides[self]
+      @with_level_used = true
+      overrides[self]  = index
+      begin
+        yield
+      ensure
+        if previous
+          overrides[self] = previous
+        else
+          overrides.delete(self)
+        end
+      end
     end
 
     # Implement the log level calls
@@ -150,7 +165,7 @@ module SemanticLogger
         if thread == Thread.current
           Utils.extract_backtrace(caller)
         else
-          log.thread_name = thread.name
+          log.thread_name = Log.thread_name_for(thread)
           log.tags        = (thread[:semantic_logger_tags] || []).clone
           log.named_tags  = (thread[:semantic_logger_named_tags] || {}).clone
           thread.backtrace
@@ -319,6 +334,10 @@ module SemanticLogger
       # (empty) instance tags allocate no garbage. Child loggers replace them via #tagged_child.
       @instance_tags       = [].freeze
       @instance_named_tags = {}.freeze
+      # Set the first time `#with_level` is called on this instance, so that instances that
+      # never use it skip the fiber-local lookup when checking their level. Only the fiber
+      # that sets an override needs to see the flag, and that fiber set it itself.
+      @with_level_used     = false
       if level.nil?
         # Allow the global default level to determine this loggers log level
         @level_index = nil
@@ -328,11 +347,25 @@ module SemanticLogger
       end
     end
 
-    # Return the level index for fast comparisons
-    # Returns the global default level index if the level has not been explicitly
-    # set for this instance
+    # Return the level index for fast comparisons, resolved in the same order as `#level`.
     def level_index
-      @level_index || SemanticLogger.default_level_index
+      (@with_level_used && with_level_index) || @level_index || fallback_level_index
+    end
+
+    # Level to use when no level has been set for this instance: the global default level.
+    def fallback_level
+      SemanticLogger.default_level
+    end
+
+    # Level index to use when no level has been set for this instance. Unlike
+    # `#fallback_level`, it honors `SemanticLogger.silence`.
+    def fallback_level_index
+      SemanticLogger.default_level_index
+    end
+
+    # Level index set for this instance by an enclosing `#with_level` block on the current fiber.
+    def with_level_index
+      Thread.current[:semantic_logger_with_level]&.[](self)
     end
 
     # Whether to log the supplied message based on the current filter if any
@@ -444,6 +477,9 @@ module SemanticLogger
     end
 
     # Measure the supplied block and log the message
+    #
+    # The options can hold untrusted data, so an option with a value that is not valid for it is
+    # ignored (see Log.argument?) and its default is used instead.
     def measure_internal(level, index, message, params)
       exception = nil
       # Single parameter is a hash
@@ -454,9 +490,7 @@ module SemanticLogger
       start = Process.clock_gettime(Process::CLOCK_MONOTONIC)
       begin
         if block_given?
-          if (silence_level = params[:silence])
-            # In case someone accidentally sets `silence: true` instead of `silence: :error`
-            silence_level = :error if silence_level == true
+          if (silence_level = measure_silence_level(params))
             silence(silence_level) { yield(params) }
           else
             yield(params)
@@ -467,13 +501,15 @@ module SemanticLogger
       ensure
         # Must use ensure block otherwise a `return` in the yield above will skip the log entry
         log = new_log(level, index)
-        exception ||= params[:exception]
-        message   = params[:message] if params[:message]
-        duration  =
+        # Only an Exception, since it is re-raised below
+        exception ||= params[:exception] if params[:exception].is_a?(Exception)
+        message     = measure_option(params, :message) || message
+        duration    =
           if block_given?
             1_000.0 * (Process.clock_gettime(Process::CLOCK_MONOTONIC) - start)
           else
-            params[:duration] || raise("Mandatory block missing when :duration option is not supplied")
+            measure_option(params, :duration) ||
+              raise("Mandatory block missing when :duration option is not supplied")
           end
 
         # Extract options after block completes so that block can modify any of the options
@@ -483,13 +519,13 @@ module SemanticLogger
         should_log = log.assign(
           message:            message,
           payload:            payload,
-          min_duration:       params[:min_duration] || 0.0,
+          min_duration:       measure_option(params, :min_duration) || 0.0,
           exception:          exception,
-          metric:             params[:metric],
-          metric_amount:      params[:metric_amount],
+          metric:             measure_option(params, :metric),
+          metric_amount:      measure_option(params, :metric_amount),
           duration:           duration,
-          log_exception:      params[:log_exception] || :partial,
-          on_exception_level: params[:on_exception_level]
+          log_exception:      measure_option(params, :log_exception) || :partial,
+          on_exception_level: measure_option(params, :on_exception_level)
         )
 
         # Log level may change during assign due to :on_exception_level
@@ -498,6 +534,22 @@ module SemanticLogger
       end
     end
 
+    # Returns the value of the measure option that is also a log argument, or nil when it is not
+    # supplied or its value is not valid for that argument.
+    def measure_option(params, key)
+      value = params[key]
+      value if Log.argument?(key, value)
+    end
+
+    # Returns the level to silence other log messages to within a measure block, or nil when none
+    # is supplied or it is not a valid level.
+    def measure_silence_level(params)
+      silence_level = params[:silence]
+      # In case someone accidentally sets `silence: true` instead of `silence: :error`
+      silence_level = :error if silence_level == true
+      silence_level if Levels.valid?(silence_level)
+    end
+
     # For measuring methods and logging their duration.
     def measure_method(index:,
                        level:,

data/lib/semantic_logger/exception_details.rb

@@ -0,0 +1,50 @@
+module SemanticLogger
+  # Separates the detail that Ruby's Exception#detailed_message adds to an exception's message,
+  # such as did_you_mean suggestions or error_highlight's source snippet, from the message itself.
+  #
+  # Internal: Log caches the result for each of its exceptions; see Log#exception_details.
+  module ExceptionDetails
+    # Ruby's own Exception#detailed_message: the message, decorated with the class name.
+    DETAILED_MESSAGE = Exception.instance_method(:detailed_message)
+    private_constant :DETAILED_MESSAGE
+
+    # Returns [String] the detail that #detailed_message adds to the exception's message, without
+    # the class name that Ruby also adds, or nil when there is none or it cannot be separated.
+    #
+    # Never raises, so that an exception's own #detailed_message cannot stop a log entry being
+    # written.
+    def self.extract(exception, source: false)
+      detailed = full_detailed_message(exception, source)
+      return unless detailed
+
+      base = DETAILED_MESSAGE.bind_call(exception, highlight: false)
+      # An override that does not build on Ruby's message cannot be separated from it.
+      return unless detailed.is_a?(String) && detailed.start_with?(base)
+
+      details = detailed.delete_prefix(base).sub(/\A\n+/, "").rstrip
+      details unless details.empty?
+    rescue StandardError
+      nil
+    end
+
+    # Returns [String] the exception's #detailed_message, with or without error_highlight's
+    # source snippet, or nil when the snippet cannot be left out.
+    def self.full_detailed_message(exception, source)
+      exception.detailed_message(highlight: false, error_highlight: source)
+    rescue ArgumentError
+      # An override of #detailed_message that does not accept extra keyword arguments. Calling it
+      # without `error_highlight: false` lets error_highlight add its source snippet, so only do so
+      # when the snippet was asked for, or error_highlight does not decorate this exception.
+      return if !source && error_highlighted?(exception)
+
+      exception.detailed_message(highlight: false)
+    end
+    private_class_method :full_detailed_message
+
+    # Whether error_highlight adds a source snippet to this exception's #detailed_message.
+    def self.error_highlighted?(exception)
+      defined?(ErrorHighlight::CoreExt) && exception.is_a?(ErrorHighlight::CoreExt)
+    end
+    private_class_method :error_highlighted?
+  end
+end

data/lib/semantic_logger/formatters/base.rb

@@ -3,7 +3,7 @@ module SemanticLogger
   module Formatters
     class Base
       attr_accessor :log, :logger, :time_format, :log_host, :log_application, :log_environment, :precision,
-                    :escape_control_chars
+                    :escape_control_chars, :log_exception_details
 
       # Printable escapes for the most common control characters. Any other
       # control character is escaped to its hexadecimal `\xHH` form by
@@ -50,25 +50,39 @@ module SemanticLogger
       #     Default: PRECISION (6, except on older JRuby, where 3)
       #   escape_control_chars: [Boolean]
       #     Replace control characters (newlines, the ANSI escape, etc.) in
-      #     untrusted log data (message, tags, named tags, and exception
-      #     message) with a printable escaped form, e.g. "\n".
+      #     untrusted log data (logger name, thread name, message, payload, tags,
+      #     named tags, and the message and backtrace lines of the exception and
+      #     of each exception that caused it) with a printable escaped form, e.g. "\n".
       #     This prevents log forging and terminal escape-sequence injection
       #     when logging data that may contain attacker-controlled content.
       #     Note: Has no effect on structured formatters such as :json, which
       #     already escape control characters via JSON encoding.
       #     Default: false (preserve newlines and ANSI colors in text output)
+      #   log_exception_details: [true|false|:with_source]
+      #     Whether to log the detail that Ruby's Exception#detailed_message adds to an
+      #     exception's message, such as did_you_mean suggestions ("Did you mean?  upcase") or
+      #     the detail an exception class supplies by overriding #detailed_message.
+      #     :with_source also logs error_highlight's snippet of the failing source line. It is
+      #     about 100 times slower, since it re-parses that source file, and it copies source
+      #     code into the log.
+      #     On Ruby 3.2 a NameError or NoMethodError builds its message from receiver.inspect each
+      #     time it is asked, and logging the details asks for it twice more, so turn this off when
+      #     inspecting the receivers of logged exceptions is slow.
+      #     Default: true for the Default, Color, and Pattern text formatters, false otherwise.
       def initialize(time_format: nil,
                      log_host: true,
                      log_application: true,
                      log_environment: true,
                      precision: PRECISION,
-                     escape_control_chars: false)
+                     escape_control_chars: false,
+                     log_exception_details: default_log_exception_details)
         @time_format          = time_format || self.class.build_time_format(precision)
         @log_host             = log_host
         @log_application      = log_application
         @log_environment      = log_environment
         @precision            = precision
-        @escape_control_chars = escape_control_chars
+        @escape_control_chars  = escape_control_chars
+        @log_exception_details = log_exception_details
       end
 
       # Return default time format string
@@ -101,10 +115,42 @@ module SemanticLogger
       # Note: This escapes (preserves) control characters, and is opt-in. It is
       # distinct from Log#cleansed_message, which unconditionally *strips* ANSI
       # colorization from the message for structured (JSON/Loki) output.
+      #
+      # A string with invalid byte sequences, for example an exception message that quotes
+      # untrusted binary input, or in another encoding, is first converted to valid UTF-8
+      # (dropping the invalid bytes), since matching against it would raise and the log entry
+      # would be lost.
       def escape_control_characters(value)
         return value unless escape_control_chars && value
 
-        value.to_s.gsub(CONTROL_CHARS) { |char| CONTROL_CHAR_ESCAPES[char] || format("\\x%02x", char.ord) }
+        string = Utils.encode_utf8_string(value.to_s)
+        string.gsub(CONTROL_CHARS) { |char| CONTROL_CHAR_ESCAPES[char] || format("\\x%02x", char.ord) }
+      end
+
+      # Whether this formatter logs exception details unless told otherwise. See #initialize.
+      def default_log_exception_details
+        false
+      end
+
+      # Returns [String] the detail Ruby adds to the message of the supplied exception (see
+      # Log#exception_details), or nil when there is none or this formatter does not log it.
+      def exception_details_for(exception)
+        return unless log_exception_details
+
+        log.exception_details(exception, source: log_exception_details == :with_source)
+      end
+
+      # Returns [String] the backtrace of the logged exception, followed by each exception
+      # that caused it, as laid out by Log#backtrace_to_s.
+      #
+      # When `escape_control_chars` is enabled, the message of each cause and each backtrace
+      # line is passed through #escape_control_characters, the same as the message of the
+      # logged exception: causes are often parser or validation errors that quote untrusted
+      # input, and a backtrace can be set from untrusted data.
+      def exception_backtrace
+        return log.backtrace_to_s unless escape_control_chars
+
+        log.backtrace_to_s { |text| escape_control_characters(text) }
       end
 
       # Return the Time as a formatted string

data/lib/semantic_logger/formatters/color.rb

@@ -71,6 +71,8 @@ module SemanticLogger
       #
       #    Note: The option :multiline is set to false if not supplied.
       #    Note: Has no effect if Awesome Print is not installed.
+      #    Note: With `escape_control_chars: true` the payload is always rendered plain
+      #          (without colors) and on a single line, then escaped.
       #
       #  color_map: [Hash | SemanticLogger::Formatters::Color::ColorMap]
       #    ColorMaps each of the log levels to a color
@@ -116,7 +118,7 @@ module SemanticLogger
 
         if log.payload.respond_to?(:ai)
           begin
-            "-- #{log.payload.ai(@ai_options)}"
+            "-- #{escape_control_characters(log.payload_to_s { |payload| payload.ai(ai_options) })}"
           rescue StandardError
             super
           end
@@ -128,14 +130,28 @@ module SemanticLogger
       def exception
         return unless log.exception
 
+        details = exception_details
         "-- Exception: #{color}#{log.exception.class}: " \
-          "#{escape_control_characters(log.exception.message)}#{color_map.clear}\n#{log.backtrace_to_s}"
+          "#{escape_control_characters(log.exception.message)}#{color_map.clear}\n" \
+          "#{"#{details}\n" if details}#{exception_backtrace}"
       end
 
       def call(log, logger)
         self.color = color_map[log.level]
         super
       end
+
+      private
+
+      # Returns [Hash] the Amazing Print options to render the payload with.
+      #
+      # When `escape_control_chars` is enabled the payload is rendered plain, on one line:
+      # the colors and line breaks Amazing Print adds cannot be told apart from control
+      # characters in the data (for example an object whose #inspect returns them), and
+      # escaping them all leaves no colors or line breaks to keep.
+      def ai_options
+        escape_control_chars ? @ai_options.merge(plain: true, multiline: false) : @ai_options
+      end
     end
   end
 end