semantic_logger 5.1.0 → 5.2.0

data/docs/security.md

@@ -1,9 +1,12 @@
 ---
 layout: default
+title: Security
+description: >-
+  Keeping logs trustworthy: log injection and forging, redacting sensitive
+  data, transport encryption, log file permissions, and the gem's dependency
+  footprint.
 ---
 
-## Security
-{:.no_toc}
 
 **Contents**
 
@@ -52,6 +55,45 @@ The record-framed network appenders are already safe by default:
 If you replace the formatter on any of these appenders with a text formatter, enable
 `escape_control_chars` as shown above.
 
+### Logging untrusted hashes
+
+A hash passed after the message is the payload, but a few of its keys are also log arguments:
+`duration`, `min_duration`, `metric`, `metric_amount`, `exception`, `log_exception`, and so on.
+That is convenient for code you write, but when the hash holds untrusted data, such as parsed
+request parameters or a webhook body with Symbol keys, it can set those arguments too. For
+example `{duration: 0, min_duration: 1}` would suppress the entry.
+
+Semantic Logger only uses such a key as an argument when its value is valid for it: for example
+`duration` must be a finite real number, `backtrace` an Array of Strings, and `on_exception_level` a
+valid level. Any other value stays in the payload as data, and a `nil` value is ignored, so an
+untrusted hash passed to a level method such as `info` can never make the logging call raise.
+
+To make sure none of its keys are treated as arguments, pass it as the explicit `payload:`. Any other
+keys supplied alongside an explicit `payload:` are merged into it, and win over the explicit
+payload's values of the same name, so that the untrusted data cannot replace a value your code
+supplies. A String key, as `JSON.parse` returns without `symbolize_names`, has the same name as the
+Symbol key it spells:
+
+~~~ruby
+# The hash is logged as-is, and none of its keys are interpreted. Its own account_id, if any,
+# cannot replace the one supplied here:
+logger.info("Webhook received", payload: JSON.parse(body, symbolize_names: true), account_id: account.id)
+~~~
+
+A hash returned from a logging block, such as
+`logger.debug("Webhook received") { JSON.parse(body, symbolize_names: true) }`, is checked the
+same way, and never replaces a value the log call supplied. A key is only used as an argument when
+its value is valid for it and the log entry does not have that argument yet: an empty `message`
+counts as none, and a backtrace captured at the `backtrace_level` counts as supplied. Its `payload`
+is only used when it is a Hash. Every other key, including an argument the entry already has, is
+added to the payload without replacing the log call's values, and wins over the block's own
+`payload` values of the same name. The caller's own payload Hash is left unchanged.
+
+The options of a `measure_*` call are checked the same way: an option with a value that is not valid
+for it is ignored, and its default is used. Keys that are not measure options are not logged at all,
+so pass untrusted data to a measure call as its `payload:` too. A measure call without a block still
+raises unless it is given a valid `:duration`.
+
 ### Redacting sensitive data
 
 Semantic Logger does not automatically redact secrets or personal information; it logs
@@ -60,37 +102,144 @@ numbers, and similar values in the first place.
 
 When sensitive values can reach the logs indirectly, redact them. A global `on_log`
 subscriber runs inline, once per log event, before the event is handed to any appender,
-so it can scrub the message or payload for every destination:
+so it can scrub the payload for every destination. The example below matches keys at any depth,
+whether they are Strings, as in parsed JSON and Rails params, or Symbols, in any case and style,
+such as `api_key`, `apiKey`, or `X-Api-Key`. It builds a new payload rather than changing the logged
+one, which can be the application's own Hash. It fails closed: a payload that it cannot redact is
+replaced, never written as it is.
 
 ~~~ruby
-SECRET_KEYS = %i[password token authorization secret].freeze
+module LogRedaction
+  # Matched against each key in lower case with "_" between its words, see sensitive_key?.
+  SENSITIVE_KEY = Regexp.union(
+    # Anywhere in the key, like the default filter_parameters of Rails.
+    /passw|passphrase|secret|token|_key|apikey|credential|authorization|cookie|crypt|certificate|email/,
+    # Only as a whole word, so that "otp" does not match "footprint", nor "ssn" "business_name".
+    /(?<![a-z])(?:auth|pwd|otp|ssn|salt|cvv|cvc)(?![a-z])/
+  )
+  REDACTED  = "[REDACTED]".freeze
+  MAX_DEPTH = 32
 
-SemanticLogger.on_log do |log|
-  log.payload&.each_key do |key|
-    log.payload[key] = "[REDACTED]" if SECRET_KEYS.include?(key)
+  # Returns a copy of the value with the value of every sensitive key replaced, at any depth.
+  #
+  # copies maps each structure already walked to its copy, so that a structure held more than once
+  # is walked only once, and one that holds itself is cut off.
+  def self.redact(value, copies = {}.compare_by_identity, depth = 0)
+    return copies[value] || "[REDACTED: circular]" if copies.key?(value)
+
+    members = members(value)
+    return value if members.nil?
+    return "[REDACTED: nested too deeply]" if depth >= MAX_DEPTH
+
+    copies[value] = nil # Until its copy is complete.
+    copies[value] =
+      if members.is_a?(Hash)
+        members.each_with_object({}) do |(key, val), copy|
+          copy[key] = sensitive_key?(key) ? REDACTED : redact(val, copies, depth + 1)
+        end
+      else
+        members.map { |val| redact(val, copies, depth + 1) }
+      end
+  end
+
+  def self.sensitive_key?(key)
+    # As valid UTF-8, since a key with invalid bytes, as from a query string, makes a match raise.
+    name = key.to_s.encode(Encoding::UTF_8, invalid: :replace, undef: :replace)
+    # "apiKey", "API_KEY", and "X-Api-Key" become "api_key", "api_key", and "x_api_key".
+    name = name.gsub(/([a-z\d])([A-Z])/, '\1_\2').downcase.gsub(/[^a-z\d]+/, "_")
+    SENSITIVE_KEY.match?(name)
+  end
+
+  # Returns the members of a Hash, Array, Struct, Data, Set, OpenStruct, or
+  # ActionController::Parameters, as a Hash or an Array. Returns nil for any other value.
+  def self.members(value)
+    case value
+    when Hash, Array then value
+    when Struct, Data then value.to_h
+    when Set then value.to_a
+    else
+      if defined?(OpenStruct) && value.is_a?(OpenStruct)
+        value.to_h
+      elsif value.respond_to?(:to_unsafe_h) # ActionController::Parameters
+        value.to_unsafe_h
+      end
+    end
   end
 end
+
+# Register it before any other on_log subscriber.
+SemanticLogger.on_log do |log|
+  log.payload = LogRedaction.redact(log.payload) unless log.payload.nil?
+rescue Exception => e
+  # Fail closed. Any Exception, since Semantic Logger rescues whatever an on_log subscriber raises
+  # and goes on to write the entry.
+  log.payload = {redaction_failed: e.class.name}
+end
 ~~~
 
-Redaction can also be applied to a single logger or appender with a `filter` that
-mutates the log and returns `true`. See [Filtering](config.html#filtering) for examples.
+`SENSITIVE_KEY` is a starting point: adapt it to the keys that your application logs. Like the
+default `filter_parameters` of Rails, it also matches some keys that are not secret, such as
+`max_tokens` or `cache_key`.
+
+The example looks inside Hashes and Arrays, and inside the Struct, Data, Set, and OpenStruct values
+that the JSON formatters write as objects and arrays, which it replaces with Hashes and Arrays. It
+reads `ActionController::Parameters` with `to_unsafe_h`. Any other object is left as it is, and is
+written the way the formatter writes it, which for some objects includes all of their attributes:
+for example a JSON formatter writes an Active Record model with `as_json`. Log a Hash of the values
+you need instead.
+
+Register it before any other `on_log` subscriber that reads the payload. Subscribers run in the
+order they were registered, so one registered before it, such as the [Rollbar](appenders.html#rollbar)
+integration that sends `log.to_h`, receives the payload before it is redacted.
+
+It only redacts the payload. The message, the tags and named tags, the message of the exception and
+those of its causes, the context that `on_log` subscribers add, and metric dimensions are written
+as they are, so keep secrets out of them. That includes a value other than a Hash passed after the
+message, such as `logger.info("Login", user)`, which is added to the message: pass it as
+`payload: user` instead.
+
+It copies the payload of every entry that is logged, even when there is nothing to redact, on the
+thread that logs it, so its cost grows with the size of the payloads.
+
+A `filter` on a logger instance can redact the same way for that logger's entries; see
+[Filtering](config.html#filtering). Do not redact in an appender's `filter`: every appender writes
+the same log entry, so that only protects the appenders added after it, while the ones added before
+it have already written the secret.
 
 Rails applications should use the sister gem
 [rails_semantic_logger](https://github.com/reidmorrison/rails_semantic_logger), which
 honours `config.filter_parameters` so that parameters Rails already considers sensitive
-are filtered out of the logs.
+are filtered out of the logs. To match the payload's keys against the same list, `sensitive_key?`
+can return `!filter.filter_param(name, nil).nil?`, where `filter` is
+`ActiveSupport::ParameterFilter.new(Rails.application.config.filter_parameters)`, created once the
+application has initialized, since one created from an incomplete list filters less. Proc filters
+in the list are not applied this way. Do not call its `#filter` in place of `redact`: it only looks
+inside Hashes and Arrays, raises for a key with invalid UTF-8, and has no protection against a Hash
+that holds itself or is held more than once.
 
 ### Transport encryption
 
 Appenders that send logs over the network support TLS. The appenders built on the
-`:http` appender (`:http`, `:splunk_http`, and `:elasticsearch_http`) default to
+`:http` appender (`:http`, `:splunk_http`, `:elasticsearch_http`, and `:loki`) default to
 verifying the server certificate (`OpenSSL::SSL::VERIFY_PEER`) when an `https` URL is
-used.
+used. The `:tcp` appender, and the `:syslog` appender over TCP, verify both the certificate
+and the host name when `ssl:` is enabled.
+
+The deprecated `:splunk` appender is the exception: its `splunk-sdk-ruby` gem never verifies
+the certificate. Use `:splunk_http` instead.
 
-Do not disable certificate verification in production. Settings such as
+Do not disable certificate verification. Settings such as
 `ssl: {verify_mode: OpenSSL::SSL::VERIFY_NONE}` expose the connection to
-man-in-the-middle attacks and should be limited to local development against
-self-signed certificates.
+man-in-the-middle attacks. To connect to a server with a self-signed certificate, or one issued
+by a private certificate authority, trust that certificate instead, for example with
+`ssl: {ca_file: "/path/to/ca.pem"}`.
+
+Credentials can be supplied in the url of the HTTP based appenders, for example
+`https://user:password@host`, or as a query parameter. They are removed from the url
+written to the internal logger when the server rejects a request, and from the error raised
+for an invalid url. `#inspect` on any appender, for example when `SemanticLogger.appenders` is
+printed in a console, shows only what that appender says is safe, such as its url without
+credentials, and none of its passwords, tokens, keys, or client options.
 
 ### Log file permissions
 
@@ -104,9 +253,27 @@ an existing log file:
 SemanticLogger.add_appender(file_name: "production.log", permissions: 0o640)
 ~~~
 
+With `permissions`, the log file is opened without following a symbolic link at its name, so a
+link planted in the log directory can neither create nor open the file it points at. The file must
+be a regular file owned by the process, with a single hard link, that the file name still names
+once it is open. Otherwise, or when the file cannot be opened, nothing is written to it:
+`add_appender` raises `IOError` giving the reason, with the error from opening the file, if any, as
+its `cause`. When a file only fails the check once it is reopened later, on a rotation or after a
+fork, the appender reports the reason once for each file, drops the log messages instead of
+raising, and tries the file again every few seconds and at the next scheduled reopen, so that
+logging resumes once the file is fixed. A symbolic link, hard link, or file planted in a shared log
+directory, for example under the name of tomorrow's log file, can therefore neither loosen the
+permissions of another file nor receive the log messages. A FIFO planted there fails to open
+instead of blocking the process.
+
+Without `permissions`, the file appender opens the log file the way Ruby's own `Logger` does,
+following symbolic links, so that a log file can for example be linked to `/dev/stdout`. Keep the
+log directory writable only by the application.
+
 ### Dependencies and supply chain
 
-Semantic Logger has a single runtime dependency, `concurrent-ruby`. Appenders for
+Semantic Logger has two runtime dependencies, `concurrent-ruby` and `logger` (part of
+Ruby's standard library until Ruby 4.0 moved it to the bundled gems). Appenders for
 third-party services (Kafka, MongoDB, Sentry, etc.) keep their backing gem optional: it
 is required lazily inside the appender only when that appender is used, and is never
 added to the gemspec. This keeps the dependency surface of an application that only uses

data/docs/testing.md

@@ -1,9 +1,11 @@
 ---
 layout: default
+title: Testing
+description: >-
+  Assert that your code logged the expected message, level, payload or metric,
+  using the capture helpers for Minitest, RSpec, and other test frameworks.
 ---
 
-## Testing
-{:.no_toc}
 
 **Contents**
 
@@ -106,7 +108,7 @@ test. The available checks are:
 | `time` | When the entry was created. |
 | `duration` | Duration of a measure call, in milliseconds. |
 | `backtrace` | The captured backtrace, if any. |
-| `thread_name` | Name of the thread that logged the entry. |
+| `thread_name` | Name of the thread that logged the entry, or its object id when the thread has no name. |
 
 ### Match part of a message or payload
 

data/docs/upgrading.md

@@ -1,22 +1,290 @@
 ---
 layout: default
+title: Upgrading
+description: >-
+  Version-by-version upgrade notes for Semantic Logger, from v4.0 through the
+  v5.2 security fixes, remote syslog facility fix, and deprecation of the Splunk SDK appender.
 ---
 
-## Upgrading
-{:.no_toc}
 
 **Contents**
 
 * TOC
 {:toc}
 
+### Upgrading to Semantic Logger v5.2
+
+v5.2 sends the configured facility to remote syslog, deprecates the `:splunk` appender, stops
+replacing Ruby's `Thread#name`, and fixes several security issues. None of the security fixes change
+the public API, but a few change the output, which matters if you parse the logs or alert on them,
+and the file appender's `permissions:` option can now make `add_appender` raise for a log file that
+worked in v5.1.
+
+#### Set the Sentry user and fingerprint with named tags
+
+The `:sentry_ruby` appender takes the Sentry user (`user_id`, `username`, `user_email`, `ip_address`,
+and `user`) and `fingerprint` from named tags or the payload. Taking them from the payload is
+deprecated and will be **removed in v6**, since the payload often holds untrusted data, such as a
+request body, which could then set the user an error is reported for. It emits a deprecation warning
+the first time it happens. Until then, the named tags win over the payload, which no longer replaces
+a user field they set, and only a String, Symbol, or Integer is taken from the payload for a user
+field. Set them with named tags instead, which can now also hold the `fingerprint`:
+
+~~~ruby
+# Before:
+logger.error("Payment failed", user_id: user.id, fingerprint: ["payment-failed"])
+
+# After:
+SemanticLogger.tagged(user_id: user.id, fingerprint: ["payment-failed"]) do
+  logger.error("Payment failed")
+end
+~~~
+
+#### Replace the `:splunk` appender with `:splunk_http`
+
+The `:splunk` appender depends on the `splunk-sdk-ruby` gem, which was last released in 2015 and
+does not verify the server's TLS certificate. It now emits a deprecation warning and will be
+**removed in v6**. Send logs to the Splunk HTTP Event Collector instead:
+
+~~~ruby
+# Before:
+SemanticLogger.add_appender(appender: :splunk, index: "main")
+
+# After:
+SemanticLogger.add_appender(
+  appender: :splunk_http,
+  url:      "https://splunk.example.com:8088/services/collector/event",
+  token:    "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
+  index:    "main"
+)
+~~~
+
+#### Remote syslog sends the configured facility
+
+When logging to a remote syslog server over TCP or UDP, earlier versions sent the wrong facility.
+The `facility:` option is documented as one of Ruby's `::Syslog::LOG_*` facility constants, but the
+value was sent as if it were already the syslog protocol's facility number. Those constants are the
+facility number shifted left by 3 bits, so the default `::Syslog::LOG_USER` (8) went out as facility
+8, which is `uucp`, instead of facility 1, `user`. For example a `:info` message, at the default
+`LOG_NOTICE` severity, was sent as `<69>` rather than `<13>`. Logging to a local syslog daemon was
+not affected.
+
+v5.2 sends the facility the constant names. If your syslog server filters or routes on facility,
+for example an rsyslog rule for `uucp.*`, change it to the facility you configured: `user` unless
+you set one.
+
+The `facility:` option now only accepts the `::Syslog::LOG_*` facility constants, and raises
+`ArgumentError` for other values when the appender is created. Previously a constant other than
+`::Syslog::LOG_KERN`, `::Syslog::LOG_USER`, or `::Syslog::LOG_MAIL` raised `ArgumentError` while
+logging. If you passed a bare facility number to get around that, switch to the constant. Check
+this even if nothing raises: a bare 0, 8, or 16 is now read as `::Syslog::LOG_KERN`,
+`::Syslog::LOG_USER`, or `::Syslog::LOG_MAIL`, so `16`, which used to send `local0`, now sends
+`mail`:
+
+~~~ruby
+# Before (16 was sent as facility local0, and is now read as ::Syslog::LOG_MAIL):
+SemanticLogger.add_appender(appender: :syslog, url: "udp://myloghost:514", facility: 16)
+
+# After:
+SemanticLogger.add_appender(appender: :syslog, url: "udp://myloghost:514", facility: ::Syslog::LOG_LOCAL0)
+~~~
+
+This applies to the `:syslog` and `:syslog_cee` formatters. An application that logs only to a remote
+server, and so does not need the `syslog` gem, can use the same constants from
+`SemanticLogger::Formatters::Syslog`, for example `SemanticLogger::Formatters::Syslog::LOG_LOCAL0`.
+
+#### The file appender's `permissions:` refuses a log file it cannot secure
+
+With `permissions:`, the file appender only writes to a regular file owned by the process, with a
+single hard link, that the file name names directly rather than through a symbolic link.
+`SemanticLogger.add_appender` now raises `IOError`, giving the reason, for any other log file,
+which v5.1 wrote to, changing the permissions of whatever a link pointed at. So a configuration
+that worked in v5.1 can now fail at boot, for example `permissions:` on a log file that is a
+symbolic link to `/dev/stdout`, or on a log file that another user created. With `permissions:`,
+a log file that cannot be opened also raises `IOError`, instead of the operating system's error,
+such as `Errno::ENOENT`, which is its `cause`. A log file that fails the check, or to open, when it
+is reopened later, on a rotation or after a fork, is reported to the internal logger and not
+written to until it is fixed, instead of raising from the logging thread.
+
+If you set `permissions:` on such a log file, either fix the file or remove `permissions:`. To log
+to standard output, use `io: $stdout`:
+
+~~~ruby
+# Before, with log/production.log a symbolic link to /dev/stdout:
+SemanticLogger.add_appender(file_name: "log/production.log", permissions: 0o640)
+
+# After:
+SemanticLogger.add_appender(io: $stdout)
+~~~
+
+#### Ruby's own `Thread#name` is no longer replaced
+
+Earlier versions replaced `Thread#name` and `Thread#name=` with Semantic Logger's own versions,
+which were written before Ruby had them and kept the name away from Ruby itself. v5.2 leaves Ruby's
+own in place, so the name now also reaches the operating system, profilers, and `Thread#inspect`.
+On MRI, log entries do not change: a thread that has no name is still logged with its object id.
+
+Code anywhere in the application that calls `Thread#name` or `Thread#name=` now gets Ruby's
+behaviour:
+
+* `Thread#name` returns `nil` for a thread that has no name, where it returned the thread's object
+  id as a String (on JRuby, its JVM thread name). The main thread has no name on MRI; JRuby names it
+  `main`.
+* `Thread#name=` is Ruby's built-in implementation again, with Ruby's standard behaviour, instead of
+  Semantic Logger's version, which accepted any value and converted it with `to_s`. Ruby's version
+  raises `TypeError` for a value that is not a String or `nil`, such as a Symbol or an Integer. It
+  raises `ArgumentError` for a String that contains a NUL byte (`"\0"`), or whose encoding is not
+  ASCII-compatible, such as UTF-16. Setting `nil` leaves the thread with no name, where it set the
+  name to `""`.
+
+~~~ruby
+# Before:
+Thread.current.name = worker_number
+Thread.current.name.start_with?("worker")
+
+# After:
+Thread.current.name = "worker-#{worker_number}"
+Thread.current.name&.start_with?("worker")
+~~~
+
+Tests that expect `thread_name: Thread.current.name` from the
+[test helpers](testing.html) no longer work on a thread that has no name, such as the main thread
+on MRI: `Thread.current.name` is now `nil`, while the log entry still holds the thread's object id.
+The RSpec matchers `be_a_semantic_logger_event` and `log_semantic_logger_event` then fail. Worse,
+`assert_semantic_logger_event` in Minitest takes `nil` to mean "do not check", so the test still
+passes but no longer checks the thread name. Expect the object id when the thread has no name:
+
+~~~ruby
+# Before:
+assert_semantic_logger_event(event, thread_name: Thread.current.name)
+
+# After:
+assert_semantic_logger_event(event, thread_name: Thread.current.name || Thread.current.object_id.to_s)
+~~~
+
+Semantic Logger's own threads are now named after their appender, such as `SL File`, with
+`SL Appenders` for the main one, instead of `SemanticLogger::Appender::File` and
+`SemanticLogger::Appenders`. Linux keeps only the first 15 bytes of a thread name, so the longer
+names all looked the same in tools that list threads, such as `top -H`. The new names also appear
+in the thread column of the messages Semantic Logger logs about its own problems, such as an
+appender that cannot write.
+
+On JRuby:
+
+* A Ruby thread that has no name is logged with its object id, instead of its JVM thread name, such
+  as `Ruby-0-Thread-1: app/worker.rb:12`. Name the thread to give it a readable name in the logs. A
+  thread created by Java code, such as a servlet container's request thread, is still logged with
+  its JVM thread name, which now also stays current when Java code renames the thread.
+* Naming a Ruby thread sets its JVM thread name in JRuby's own format, such as
+  `Ruby-0-Thread-2@My Worker: app/worker.rb:12`, instead of exactly `My Worker`. Update any JVM
+  monitoring that matches thread names exactly.
+
+#### Output changes
+
+* `:logfmt`: spaces, control characters, invisible format characters (such as a zero width space),
+  `=`, `"`, and Unicode line separators in keys are replaced with `_`, and invalid UTF-8 bytes are
+  dropped. A tag such as `second breakfast` is now emitted as `second_breakfast=true`. A tag,
+  named tag, or payload key named like one of the entry's own fields, which are the time key
+  (`timestamp` by default), `level`, `name`, `message`, `duration`, `duration_ms`, `tag`, and the
+  exception fields, is emitted with its source as a prefix, such as `payload.name="shrek"` or
+  `tags.message=true`, instead of replacing the field, and so is a key that starts with `tags.`,
+  `named_tags.`, or `payload.`. A logged exception's class and message are emitted as
+  `exception_name` and `exception_message` (followed by `stack_trace` and `cause` as before),
+  instead of replacing the entry's `name` and `message`, and the detail that
+  `log_exception_details: true` adds as `exception_details`. Other keys that are the same once
+  encoded, such as `:user` and `"user"`, are emitted once, with the value from the later source:
+  the payload over named tags, and named tags over tags. A payload that is not a Hash is emitted
+  as a single `payload` field. A nested value (a Hash, Array, `Struct`,
+  `Data`, `Set`, or any other value whose JSON is an object or an array, such as the exception
+  backtrace) is emitted as quoted JSON, `user="{\"id\":7}"`, instead of its `#inspect` text.
+* `:syslog`: an entry with an exception stays on one line; the newlines between the exception and
+  its backtrace are escaped as `\n`.
+* `:default`, `:color`, `:pattern`, and `:syslog`: with `escape_control_chars`, the logger name,
+  thread name, file name, payload, the messages of the exceptions that caused the logged exception,
+  and the backtrace lines are escaped too. Invalid UTF-8 bytes are dropped instead of the entry failing to
+  format. With escaping on, `:color` renders the payload plain and on one line, since Amazing
+  Print's colors and line breaks cannot be told apart from control characters in the data.
+* `:one_line`: line breaks are removed from every field (name, thread name, file name, tags, named
+  tags, payload, message, and exception), carriage returns as well as newlines, and
+  `escape_control_chars` is honoured.
+* JSON based formatters: `Infinity` and `NaN` payload values are serialized as strings, and
+  structures nested deeper than 32 levels are replaced with a placeholder such as
+  `#<Hash nested too deeply>`, instead of the whole entry being dropped. A `Struct`, `Data`, or
+  `OpenStruct` value is written as an object of its members, and a `Set` as an array, as Rails
+  already does, instead of its `#inspect` text. An exception in the payload is written as its
+  message, and any other object whose JSON fails because of invalid UTF-8 as its `#to_s`, with
+  the invalid bytes dropped. The `:elasticsearch` and `:opensearch` appenders write their bulk lines the same way.
+* JSON based formatters and `:one_line`: invalid UTF-8 bytes in the message are dropped, and a
+  message in another encoding is converted to UTF-8, instead of the entry failing to format.
+* `:loki`: a nested Hash, Array, `Struct`, or `Set` in the payload is written once as JSON, keeping
+  the JSON types of its values, so `{number: 1}` is written as `{"number":1}` rather than
+  `{"number":"1"}`, and `[1, 2, 3]` as `[1,2,3]`. A payload that is not a Hash is written as a
+  single `payload` field.
+* `:open_telemetry`: a `Struct`, `Set`, or other structure in the payload, or in an Array in it, is
+  written as JSON instead of its `#inspect`. A payload that is not a Hash is submitted as a single
+  `payload` attribute.
+* Hashes logged as the payload, for example `logger.info("Webhook", params)`: a key that is also
+  a log argument (`duration`, `metric_amount`, `backtrace`, `log_exception`, ...) is only used as
+  that argument when its value is valid for it. Otherwise it stays in the payload, where it was
+  previously consumed or made the call raise. A `nil` value is ignored. When an explicit
+  `payload:` is also given, the other keys win over its values of the same name, a String key such
+  as `"account_id"` having the same name as `:account_id`.
+* Hashes returned from a logging block, for example `logger.info("Webhook") { {user: "bob"} }`, are
+  checked the same way. A log argument from the block, such as `message`, `duration`, `exception`,
+  or `backtrace`, is only used when the log entry does not have it yet, and is otherwise kept in the
+  payload. A backtrace captured because the level is at or above `backtrace_level` counts, so the
+  block's `backtrace` no longer replaces it. The block's keys no longer replace values the log call
+  supplied under the same name, whether as a String or a Symbol, and win over the values of the
+  block's own `payload` with the same name.
+* The HTTP appender and the appenders built on it (`:elasticsearch_http`, `:splunk_http`, `:loki`,
+  `:signalfx`): the url in the error logged for a rejected request shows only the scheme, host,
+  and port, and `#inspect` shows only the object address and that url.
+* The `:statsd` metrics appender sends a counter as a single `metric:amount|c` packet.
+
+#### Other behaviour changes
+
+* An async or batching appender discards a log message that it cannot format, instead of
+  retrying it. Discarded messages are reported to the internal logger and counted in the new
+  `failed` key of the appender's stats. Every error raised by a built-in appender's formatter
+  counts, as does a message too large for a UDP datagram, a MongoDB document that BSON cannot
+  serialize, and a message GELF cannot send. A custom appender can format through
+  `format_log(log)` (or `format_batch(logs)`) instead of `formatter.call` to get the same
+  treatment, or override `#message_error?` for errors its own client raises.
+* The text formatters write a payload nested more than 32 levels deep as the JSON formatters
+  write it, cut off with their placeholder, such as `"#<Hash nested too deeply>"`.
+* A log message that overflows the stack while it is written is discarded, and the worker
+  thread carries on in a new thread, instead of the worker stopping for good.
+* `#inspect` on every appender shows only its class, object address, and what it says is safe to
+  show, such as `url="https://es.example.com:9200"`, `queue_name="logs"`, or `group="/my/app"`,
+  instead of its instance variables. A custom appender can show more by overriding
+  `#inspect_details`. An appender added with `async: true` or `batch: true` shows as
+  `#<SemanticLogger::Appender::Async:0x... batch=true appender=#<...>>`.
+* `:cloudwatch_logs` sends the buffered messages in as many requests as the PutLogEvents limits
+  need, oldest first, cuts short a message larger than 1 MB, and reports to the internal logger a
+  request that fails, and the messages that AWS rejects as too new, too old, or expired. It formats each message when it is logged, writes invalid UTF-8 as valid
+  UTF-8, and discards a message that its formatter cannot write, or writes as something other than
+  a String with content, instead of failing the whole request.
+* `:sentry_ruby` leaves the log entry's payload and named tags unchanged, so every appender after
+  it, and your own Hash, keep the keys it reads. A user field, or `user` Hash, in the payload no
+  longer replaces one from the named tags. A payload user field that is not a String, Symbol, or
+  Integer, a `fingerprint` that is not an Array of Strings, Symbols, or numbers, and a payload that
+  is not a Hash, are sent as data instead.
+
+#### Stricter `logger_measure_method` arguments
+
+`logger_measure_method` now raises `ArgumentError` for a method name that is not a valid Ruby
+method name, a `min_duration` that is not a finite number, and an invalid `log_exception` or
+level. Numeric Strings, such as `min_duration: "100"`, are still accepted.
+
 ### Upgrading to Semantic Logger v5.1
 
-v5.1 deprecates several legacy appenders and one appender option. They all still work in v5.1, but
-each now emits a Ruby deprecation warning and will be **removed in v6**. The warnings use
-`category: :deprecated`, so they are silent by default and appear when deprecation warnings are
-enabled (for example `ruby -W:deprecated`, or Rails development mode). Switch away now to be ready
-for v6.
+v5.1 deprecates several legacy appenders and one appender option, and changes when the file appender
+opens its log file.
+
+The deprecated appenders and option all still work in v5.1, but each now emits a Ruby deprecation
+warning and will be **removed in v6**. The warnings use `category: :deprecated`, so they are silent
+by default and appear when deprecation warnings are enabled (for example `ruby -W:deprecated`, or
+Rails development mode). Switch away now to be ready for v6.
 
 #### Replace the `:sentry` appender with `:sentry_ruby`
 
@@ -75,6 +343,26 @@ SemanticLogger.add_appender(appender: :elasticsearch, url: "http://localhost:920
 SemanticLogger.add_appender(appender: :elasticsearch, url: "http://localhost:9200")
 ~~~
 
+#### The file appender opens its log file when it is created
+
+The file appender now opens its log file at creation rather than on the first write, matching the
+other appenders. A bad path or insufficient permissions therefore raises immediately from
+`SemanticLogger.add_appender`, instead of surfacing later on the appender thread while log messages
+are lost. This restores the pre-4.9 behavior.
+
+As a result the log file is created as soon as the appender is added, even if nothing has been
+logged yet, the same as the standard Ruby and Rails loggers. If you add appenders inside a `rescue`
+or a conditional that assumed creation could never fail, review it: the failure now happens earlier
+and in the calling thread.
+
+#### Rails: log file failures are caught at boot
+
+If you use [rails_semantic_logger](rails.html), the companion gem's v5.1 release pairs with the
+eager open above: a log file that cannot be opened is now caught during boot and the app falls back
+to standard error at the `:warn` level, rather than booting against a silently broken appender. v5.1
+also drops support for Sidekiq v4, v5, and v6. See
+[Upgrading to v5.1](rails.html#upgrading-to-v51) for details.
+
 ### Upgrading to Semantic Logger v5.0
 
 #### Minimum Ruby version is now 3.2

data/lib/semantic_logger/appender/async.rb

@@ -21,13 +21,14 @@ module SemanticLogger
       # Methods forwarded to the queue processor that owns the thread and queue.
       # Tuning options (max_queue_size, batch_size, non_blocking, ...) are set once at
       # construction via SemanticLogger.add_appender, so only the values that callers actually
-      # read back are re-exposed here. lag_* backs the public SemanticLogger.lag_* API.
+      # read back are re-exposed here. lag_* and non_blocking= back the public
+      # SemanticLogger.lag_* and SemanticLogger.non_blocking= API on the main Processor.
       def_delegators :@processor,
                      :log, :flush, :close, :thread, :active?, :queue, :max_queue_size,
-                     :capped?, :non_blocking?, :batch?,
+                     :capped?, :non_blocking?, :non_blocking=, :batch?,
                      :lag_check_interval, :lag_check_interval=,
                      :lag_threshold_s, :lag_threshold_s=,
-                     :processed_count, :dropped_count
+                     :processed_count, :dropped_count, :failed_count
 
       # Appender proxy to allow an existing appender to run asynchronously in a separate thread.
       #
@@ -73,7 +74,8 @@ module SemanticLogger
       #
       #   dropped_message_report_seconds: [Integer]
       #     When non_blocking is enabled, log the count of dropped messages to the internal logger
-      #     at most once every this number of seconds.
+      #     at most once every this number of seconds. Also limits how often messages discarded
+      #     because their content could not be written are reported, after the first.
       #     Default: 30
       #
       #   async_max_retries: [Integer]
@@ -87,6 +89,14 @@ module SemanticLogger
         @processor = QueueProcessor.start(appender: appender, **args)
       end
 
+      # Returns [String] the class and object address of this proxy, whether it batches, and the
+      # wrapped appender's own #inspect, which shows only what that appender says is safe, but none of
+      # the instance variables of this proxy or its queue processor. See Subscriber#inspect.
+      def inspect
+        address = Kernel.instance_method(:to_s).bind_call(self).delete_suffix(">")
+        "#{address} batch=#{batch?} appender=#{appender.inspect}>"
+      end
+
       # Re-open appender after a fork.
       def reopen
         appender.reopen if appender.respond_to?(:reopen)
@@ -104,6 +114,8 @@ module SemanticLogger
       #   processed:      [Integer] Cumulative number of log messages written since startup.
       #   dropped:        [Integer] Cumulative number of log messages dropped because the queue
       #                             was full (only possible when non_blocking is enabled).
+      #   failed:         [Integer] Cumulative number of log messages discarded because their
+      #                             content could not be written (see Subscriber#message_error?).
       def stats
         {
           name:           name,
@@ -113,7 +125,8 @@ module SemanticLogger
           capped:         capped?,
           max_queue_size: capped? ? max_queue_size : nil,
           processed:      processed_count,
-          dropped:        dropped_count
+          dropped:        dropped_count,
+          failed:         failed_count
         }
       end
     end