semantic_logger 5.1.0 → 5.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f18701015c0b556099814aff1b79e251df13f556c103a8366b58357d9d10fd8c
-  data.tar.gz: cf18f050902946ac09a065a52a6f4cee9841f5c250ef30162d39347977e071d2
+  metadata.gz: 5b42624348f8dc147462cc1f2d26f7cf0d4ef3df91fe3157a119591e8f6bd23b
+  data.tar.gz: ca1f00571b5280a9cd5b4bf0f116944ba4850eb1536b50aff53bfba9b6ba540b
 SHA512:
-  metadata.gz: f62d59fc517122f6da01702c62cf5a33e47d629605f0dd5e096f953ebdcd7d3e6dbb9bf2e25d166d32f171dbe16ba1470726ebe760343e6e04994cef7b5c6dcd
-  data.tar.gz: 3c741614f72b723e50ed3e3ec2a785de85eb6a026b9ed52d67bb064c1617814d77afeb67e5f8f7f4cb6f20f339affd14f54a82ffe23194e256ba66da9e8aedf0
+  metadata.gz: 31f5b285c287b386979f89b794d71f9084276b13510dc5b7798a510815f512e713bdf44a87743808890a8f4cef1e74a8263a8ca78edba8f7247235bf53aa6fd5
+  data.tar.gz: 3f114bc7d9352eb40c1a4e8a31ecfa13b20e0bfec61c72fceaba522ffc041c97ffe50e0f788b63415c4265ac68586a185473a7c4320d59e8f708ac8facedbd72

data/README.md

@@ -1,5 +1,5 @@
 # Semantic Logger
-[![Gem Version](https://img.shields.io/gem/v/semantic_logger.svg)](https://rubygems.org/gems/semantic_logger) [![Build Status](https://github.com/reidmorrison/semantic_logger/workflows/build/badge.svg)](https://github.com/reidmorrison/semantic_logger/actions?query=workflow%3Abuild) [![Downloads](https://img.shields.io/gem/dt/semantic_logger.svg)](https://rubygems.org/gems/semantic_logger) [![License](https://img.shields.io/badge/license-Apache%202.0-brightgreen.svg)](http://opensource.org/licenses/Apache-2.0) ![](https://img.shields.io/badge/status-Production%20Ready-blue.svg)
+[![Gem Version](https://img.shields.io/gem/v/semantic_logger.svg)](https://rubygems.org/gems/semantic_logger) [![Build Status](https://github.com/reidmorrison/semantic_logger/workflows/build/badge.svg)](https://github.com/reidmorrison/semantic_logger/actions?query=workflow%3Abuild) [![Downloads](https://img.shields.io/gem/dt/semantic_logger.svg)](https://rubygems.org/gems/semantic_logger) [![Coverage](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/reidmorrison/semantic_logger/badges/coverage.json)](https://github.com/reidmorrison/semantic_logger/actions/workflows/ci.yml) [![License](https://img.shields.io/badge/license-Apache%202.0-brightgreen.svg)](http://opensource.org/licenses/Apache-2.0) ![](https://img.shields.io/badge/status-Production%20Ready-blue.svg)
 
 Semantic Logger is a high-performance, asynchronous structured logging framework for Ruby
 and Rails.
@@ -38,12 +38,12 @@ replaces the Rails default logger with Semantic Logger automatically.
 
 ## Documentation
 
-Start with the [Introduction](https://logger.rocketjob.io/), then the
-[Programmer's Guide](https://logger.rocketjob.io/api.html).
+Start with the [Introduction](https://logger.reidmorrison.com/), then the
+[Programmer's Guide](https://logger.reidmorrison.com/api.html).
 
-* Full guide: [https://logger.rocketjob.io/](https://logger.rocketjob.io/)
-* For AI assistants: [llms.txt](https://logger.rocketjob.io/llms.txt) (documentation index) and
-  [llms-full.txt](https://logger.rocketjob.io/llms-full.txt) (complete documentation in one file).
+* Full guide: [https://logger.reidmorrison.com/](https://logger.reidmorrison.com/)
+* For AI assistants: [llms.txt](https://logger.reidmorrison.com/llms.txt) (documentation index) and
+  [llms-full.txt](https://logger.reidmorrison.com/llms-full.txt) (complete documentation in one file).
   The same pages are also included as markdown in the installed gem, under `docs/`.
 
 ## Logging Destinations
@@ -82,7 +82,7 @@ instead of Semantic Logger directly since it will automatically replace the Rail
 
 ## Rocket Job
 
-Checkout the sister project [Rocket Job](http://rocketjob.io): Ruby's missing batch system.
+Checkout the sister project [Rocket Job](https://rocketjob.reidmorrison.com): Ruby's missing batch system.
 
 Fully supports Semantic Logger when running jobs in the background. Complete support for job metrics
 sent via Semantic Logger to your favorite dashboards.
@@ -97,9 +97,10 @@ and are therefore not automatically included by this gem:
 - HoneybadgerInsights Appender: gem 'honeybadger'
 - NewRelic Appender: gem 'newrelic_rpm'
 - NewRelicLogs Appender: gem 'newrelic_rpm'
-- Syslog Appender: gem 'syslog_protocol' 0.9.2 or above
-- Syslog Appender to a remote syslogng server over TCP or UDP: gem 'net_tcp_client'
-- Splunk Appender: gem 'splunk-sdk-ruby'
+- Syslog Appender to a local syslog daemon: gem 'syslog' (a bundled gem since Ruby 3.4)
+- Syslog Appender to a remote syslog server over TCP or UDP: gem 'syslog_protocol' 0.9.2 or above
+- Syslog Appender to a remote syslog server over TCP: gem 'net_tcp_client'
+- Splunk Appender (deprecated, use the Splunk HTTP appender): gem 'splunk-sdk-ruby'
 - Elasticsearch Appender: gem 'elasticsearch'
 - OpenSearch Appender: gem 'opensearch-ruby'
 - Kafka Appender: gem 'ruby-kafka'
@@ -109,7 +110,7 @@ and are therefore not automatically included by this gem:
 
 ## Upgrading
 
-See the [Upgrading Guide](https://logger.rocketjob.io/upgrading.html) for instructions on
+See the [Upgrading Guide](https://logger.reidmorrison.com/upgrading.html) for instructions on
 upgrading between major versions.
 
 ## Install
@@ -128,7 +129,7 @@ SemanticLogger.default_level = :trace
 SemanticLogger.add_appender(file_name: 'development.log', formatter: :color)
 ~~~
 
-If running rails, see: [Semantic Logger Rails](https://logger.rocketjob.io/rails.html)
+If running rails, see: [Semantic Logger Rails](https://logger.reidmorrison.com/rails.html)
 
 ## Contributing
 

data/Rakefile

@@ -25,19 +25,30 @@ task :llms_full do
 
     > Semantic Logger is a high-performance, asynchronous structured logging framework for Ruby and Rails.
 
-    This file concatenates every page of https://logger.rocketjob.io for consumption by AI assistants.
+    This file concatenates every page of https://logger.reidmorrison.com for consumption by AI assistants.
     It is generated from the markdown sources in docs/ by `bundle exec rake llms_full`; do not edit it directly.
-    A per-page index is available at https://logger.rocketjob.io/llms.txt
+    A per-page index is available at https://logger.reidmorrison.com/llms.txt
   HEADER
 
   sections = pages.map do |page|
-    text = File.read("docs/#{page}.md").
+    raw = File.read("docs/#{page}.md")
+
+    # The page title lives in front matter, which the shared docs theme renders
+    # as the h1. This file strips front matter, so lift the title back out and
+    # re-emit it as a heading; without this every section here would open with
+    # no indication of which page it is.
+    front_matter = raw[/\A---\n(.*?)\n---\n/m, 1].to_s
+    title        = front_matter[/^(?:title|heading):[ \t]*(.+)$/, 1].to_s.strip.delete_prefix('"').delete_suffix('"')
+
+    text = raw.
            sub(/\A---\n.*?\n---\n/m, ""). # Jekyll front matter
            gsub(/^\{:.*\}\n/, "").        # kramdown attribute lines ({:toc}, {:.no_toc}, ...)
            gsub(/^\* TOC\n/, "").
            gsub(/^\*\*Contents\*\*\n/, "").
            gsub(/^!\[.*\n/, "")           # images (relative paths, useless in plain text)
-    "<!-- source: docs/#{page}.md -->\n\n#{text.strip}\n"
+
+    body = title.empty? ? text.strip : "## #{title}\n\n#{text.strip}"
+    "<!-- source: docs/#{page}.md -->\n\n#{body}\n"
   end
 
   File.write("docs/llms-full.txt", ([header] + sections).join("\n\n---\n\n"))

data/docs/api.md

@@ -1,9 +1,12 @@
 ---
 layout: default
+title: Programming Guide
+description: >-
+  How to log with Semantic Logger: getting a logger, log levels, structured
+  payloads, exceptions, the block form, measuring durations, and tagging
+  related entries.
 ---
 
-## Programming Guide
-{:.no_toc}
 
 **Contents**
 
@@ -175,6 +178,11 @@ logger.error(message: "Calling Supplier", duration: 100)
 logger.error(message: "Calling Supplier", metric: "Supplier/inquiry", metric_amount: 21)
 ~~~
 
+In both forms, a key such as `duration` or `exception` is only used as an argument when its value is
+valid for it; otherwise it is logged as part of the payload. Any other keys supplied alongside
+`payload:` are merged into it, without overwriting its own values. When the Hash holds untrusted
+data, see [Logging untrusted hashes](security.html#logging-untrusted-hashes).
+
 ## Step 6: Measure how long something takes
 
 It is good practice to "measure everything" in production, so that when things slow down it is
@@ -252,12 +260,16 @@ The second argument to a measure call is a Hash of options:
 - `:duration` [Float]: the duration in ms, used when no block is supplied (then it is mandatory; with
   a block it is ignored).
 - `:log_exception` [Symbol]: how to report an exception raised in the block. `:full` logs the class,
-  message, and backtrace; `:partial` logs the class and message only; `:off` does not log it.
+  message, and backtrace; `:partial` logs the class and message only; `:none` does not log it.
   Default `:partial`.
 - `:on_exception_level` [Symbol]: if an exception is raised, raise the log level to this level.
 - `:silence` [Symbol]: the level to silence other log messages to within the block (current thread
   only).
 
+An option with a value that is not valid for it, such as a non-numeric `:min_duration` or an unknown
+level, is ignored and its default is used. Other keys in the Hash are not logged; pass the data to
+log as `:payload`.
+
 Putting several together:
 
 ~~~ruby
@@ -347,11 +359,11 @@ The features above cover everyday logging. The rest of this guide covers less co
 
 ### Name your threads
 
-Semantic Logger includes the thread name (or id) in every entry. On Ruby MRI the name defaults to the
-thread's object id:
+Semantic Logger includes the thread name in every entry. A thread that has no name is identified by
+its object id instead:
 
 ~~~
-2013-11-07 16:25:14.279 I [35841:70184354571980] (0.0ms) ExternalSupplier -- Calling external interface
+2013-11-07 16:25:14.279 I [35841:16] (0.0ms) ExternalSupplier -- Calling external interface
 ~~~
 
 Give a thread a readable name so it stands out in the logs:
@@ -364,15 +376,29 @@ Thread.current.name = "User calculation thread 32"
 2013-11-07 16:26:02.744 I [35841:User calculation thread 32] (0.0ms) ExternalSupplier -- Calling external interface
 ~~~
 
-Keep the name unique, otherwise concurrent threads are hard to tell apart. Including the object id is
-one way to guarantee that:
+Keep the name unique, otherwise concurrent threads are hard to tell apart. For example, number the
+threads in a pool:
 
 ~~~ruby
-Thread.current.name = "Worker Thread:#{Thread.current.object_id}"
+workers = Array.new(5) do |i|
+  Thread.new do
+    Thread.current.name = "calc #{i + 1}"
+    # ...
+  end
+end
 ~~~
 
-On JRuby this also sets the underlying JVM thread name, which is useful when monitoring the JVM over
-JMX with tools such as jconsole.
+This is Ruby's own `Thread#name=`, so the name must be a String, and Ruby raises for one that
+contains a NUL byte or is not in an ASCII-compatible encoding. Ruby also gives the name to the
+operating system, so it shows up in tools that list threads, such as `top -H`, debuggers, and
+profilers. Log entries show the whole name, but Linux keeps only its first 15 bytes, so keep the
+name short, or put the part that tells threads apart first. Semantic Logger keeps its own thread
+names short for the same reason, naming each after its appender, such as `SL Appenders` and
+`SL File`.
+
+On JRuby, naming a thread also names the underlying JVM thread, which shows up when monitoring the
+JVM with tools such as jconsole or jstack. JRuby names the main thread `main`, and a thread created
+by Java code, such as a servlet container's request thread, is logged with its JVM thread name.
 
 ### Change one class's level at runtime
 

data/docs/appenders.md

@@ -1,9 +1,12 @@
 ---
 layout: default
+title: Appenders
+description: >-
+  Every destination Semantic Logger writes to and how to configure it: files
+  and streams, structured formats, network protocols, log aggregators, and
+  error monitors.
 ---
 
-## Appenders
-{:.no_toc}
 
 **Contents**
 
@@ -83,7 +86,7 @@ time the appender is used, and is never a hard dependency of Semantic Logger its
 | [HTTP(S)](#https) | `appender: :http` | |
 | [TCP (+SSL)](#tcp-appender-ssl) | `appender: :tcp` | `net_tcp_client` |
 | [UDP](#udp-appender) | `appender: :udp` | |
-| [Syslog](#syslog) | `appender: :syslog` | `syslog_protocol`, `net_tcp_client` (remote) |
+| [Syslog](#syslog) | `appender: :syslog` | `syslog` (local, Ruby 3.4+), `syslog_protocol` (remote), `net_tcp_client` (TCP) |
 
 **Centralized logging and log aggregators**
 
@@ -93,7 +96,7 @@ time the appender is used, and is never a hard dependency of Semantic Logger its
 | [OpenSearch](#opensearch) | `appender: :opensearch` | `opensearch-ruby` |
 | [Graylog](#graylog) | `appender: :graylog` | `gelf` |
 | [Splunk over HTTP](#splunk-http) | `appender: :splunk_http` | |
-| [Splunk SDK](#splunk-sdk) | `appender: :splunk` | `splunk-sdk-ruby` |
+| [Splunk SDK](#splunk-sdk) (deprecated) | `appender: :splunk` | `splunk-sdk-ruby` |
 | [Grafana Loki](#grafana-loki) | `appender: :loki` | |
 | [CloudWatch Logs](#cloudwatch-logs) | `appender: :cloudwatch_logs` | `aws-sdk-cloudwatchlogs` |
 | [OpenTelemetry](#opentelemetry) | `appender: :open_telemetry` | `opentelemetry-logs-sdk` |
@@ -158,6 +161,14 @@ file is created and to an existing log file:
 SemanticLogger.add_appender(file_name: "production.log", permissions: 0o640)
 ~~~
 
+With `permissions:`, the log file must be a regular file owned by the process, with a single hard
+link, that the file name names directly rather than through a symbolic link. Nothing is written to
+any other file, such as a log file linked to `/dev/stdout`, nor when the file cannot be opened:
+`add_appender` raises `IOError` giving the reason, and a file that fails the check when it is
+reopened later, for example on a rotation, is reported and not written to until it is fixed. To log
+to standard output, use `io: $stdout` instead. See
+[Log file permissions](security.html#log-file-permissions).
+
 ### IO Streams
 
 Log to any IO stream instance, such as `$stdout` or `$stderr`:
@@ -259,6 +270,9 @@ Notes:
 * The layout above is formatted for readability. The real output is a single line terminated by one
   newline, with no embedded newlines.
 * A field with a `nil` value is excluded from the output.
+* To also log the detail Ruby adds to an exception's message, such as did_you_mean suggestions, as
+  `exception.details`, enable `log_exception_details`: `formatter: {json: {log_exception_details: true}}`.
+  See [Exception details](config.html#exception-details).
 
 ### Fluentd
 
@@ -351,13 +365,30 @@ timestamp="2024-07-20T08:32:05.375276Z" level="info" name="MyClass" message="Hel
 
 Notes:
 
-* The timestamp is ISO 8601. All values are quoted and escaped, so a newline in the data cannot
-  forge or split a record.
-* Named tags and payload fields are merged into the top-level `key=value` pairs. On a name
-  conflict the payload wins.
+* The timestamp is ISO 8601, under the key `timestamp` unless the formatter's `time_key` is set
+  (`formatter: {logfmt: {time_key: :ts}}`). All values are quoted and escaped, so a newline in the
+  data cannot forge or split a record.
+* Keys (from tags, named tags, and the payload) cannot be quoted in logfmt, so spaces, control
+  characters (including the Unicode line and paragraph separators), invisible format characters
+  (such as a zero width space), `=`, and `"` in a key are replaced with `_`, and invalid UTF-8 is
+  dropped. For example the tag `second breakfast` is emitted as `second_breakfast=true`.
+* Named tags and payload fields are merged into the top-level `key=value` pairs. A key named like
+  one of the entry's own fields (the time key, `level`, `name`, `message`, `duration`,
+  `duration_ms`, `tag`, or an exception field) is emitted with its source as a prefix, so that
+  logged data cannot replace those fields: `payload.level="fatal"`, `named_tags.message="..."`, or
+  `tags.message=true`. A key that starts with `tags.`, `named_tags.`, or `payload.` is prefixed
+  too, as in `payload.named_tags.level`, so that it cannot pass for another source's field.
+* Other keys that are the same once encoded, including keys that only differ by type (such as
+  `:user` and `"user"`), are emitted once, with the value from the later source: the payload wins
+  over named tags, and named tags over tags.
 * Unnamed tags are emitted as keys with a `true` value.
+* A nested value, such as a Hash or an Array in the payload, is emitted as its JSON text, quoted:
+  `user="{\"id\":7}"`.
 * `tag="success"` is emitted on every entry, becoming `tag="exception"` when the entry carries an
-  exception (the exception class, message, and backtrace are then included as fields).
+  exception, which is then included as the fields `exception_name`, `exception_message`,
+  `stack_trace`, and, when the exception has a cause, `cause`. With `log_exception_details: true`
+  (off by default), the detail Ruby adds to the exception's message is included as
+  `exception_details`; see [Exception details](config.html#exception-details).
 
 ## Network protocols
 
@@ -388,6 +419,31 @@ end
 SemanticLogger.add_appender(appender: :http, url: "https://localhost:8088/path", formatter: formatter)
 ~~~
 
+#### Query parameters
+
+Some log servers are configured through the query string of the ingestion url rather than through
+headers or the body. A query string on `url:` is kept and sent with every request that submits log
+data, for example when pointing at
+[VictoriaLogs](https://docs.victoriametrics.com/victorialogs/data-ingestion/):
+
+~~~ruby
+SemanticLogger.add_appender(
+  appender: :http,
+  url:      "http://localhost:9428/insert/jsonline?_msg_field=message&_time_field=timestamp"
+)
+~~~
+
+The query is applied after the request path, so it also works for the appenders built on top of the
+HTTP appender (`:elasticsearch_http`, `:splunk_http`, `:loki`, and the `:signalfx` metrics appender),
+each of which appends its own path to the url:
+
+~~~ruby
+SemanticLogger.add_appender(
+  appender: :elasticsearch_http,
+  url:      "http://localhost:9428/insert/elasticsearch?_msg_field=message&_time_field=timestamp"
+)
+~~~
+
 #### Batching
 
 By default each entry is sent in its own HTTP request. To send multiple entries in one request as a
@@ -424,11 +480,12 @@ SemanticLogger.add_appender(appender: :tcp, server: "localhost:8088")
 # TCP with SSL:
 SemanticLogger.add_appender(appender: :tcp, server: "localhost:8088", ssl: true)
 
-# With self-signed certificates, or to disable server certificate verification:
+# With a self-signed certificate, or one from a private certificate authority, trust that
+# certificate instead of disabling verification:
 SemanticLogger.add_appender(
   appender: :tcp,
   server:   "localhost:8088",
-  ssl:      {verify_mode: OpenSSL::SSL::VERIFY_NONE}
+  ssl:      {ca_file: "/path/to/ca.pem"}
 )
 ~~~
 
@@ -449,8 +506,10 @@ options.
 
 The TCP and UDP appenders separate records with a newline, so they default to the JSON formatter,
 which escapes embedded newlines and is safe with untrusted data. If you switch to a text formatter
-such as `:default` or `:color`, enable `escape_control_chars` so a newline in the data cannot forge or
-split a record:
+such as `:default` or `:color`, enable `escape_control_chars` so a newline in the logged data cannot
+forge a record. Those formatters still write an entry with an exception over several lines (the
+exception, then its backtrace), so a receiver that frames records by newline splits such an entry;
+use the JSON formatter or the `:syslog` formatter when every record must be a single line:
 
 ~~~ruby
 SemanticLogger.add_appender(
@@ -482,7 +541,8 @@ SemanticLogger.add_appender(appender: :udp, server: "localhost:8088", formatter:
 
 ### Syslog
 
-Log to a local Syslog daemon:
+Log to a local Syslog daemon. Since Ruby 3.4 `syslog` is a bundled gem, so add `gem "syslog"` to the
+Gemfile:
 
 ~~~ruby
 SemanticLogger.add_appender(appender: :syslog)
@@ -495,12 +555,32 @@ The default packet size is 1024 bytes:
 SemanticLogger.add_appender(appender: :syslog, url: "tcp://myloghost:514", max_size: 2048)
 ~~~
 
+`max_size` also applies when `formatter:` names the `:syslog` or `:syslog_cee` formatter. A
+formatter passed as an instance uses its own `max_size`, which also defaults to 1024 bytes:
+
+~~~ruby
+SemanticLogger.add_appender(appender: :syslog, url: "udp://myloghost:514", formatter: :syslog_cee, max_size: 2048)
+~~~
+
 Or over UDP (the `syslog_protocol` gem is required):
 
 ~~~ruby
 SemanticLogger.add_appender(appender: :syslog, url: "udp://myloghost:514")
 ~~~
 
+Set the facility with one of Ruby's `::Syslog::LOG_*` facility constants (the default is
+`::Syslog::LOG_USER`). For remote syslog without the `syslog` gem, the same constants are available
+from `SemanticLogger::Formatters::Syslog`, for example `SemanticLogger::Formatters::Syslog::LOG_LOCAL0`:
+
+~~~ruby
+SemanticLogger.add_appender(appender: :syslog, url: "udp://myloghost:514", facility: ::Syslog::LOG_LOCAL0)
+~~~
+
+The `facility:`, `level_map:`, and `max_size:` options also apply when `formatter:` names the `:syslog` or
+`:syslog_cee` formatter, for example `formatter: :syslog_cee`. Options given to the formatter itself,
+as in `formatter: {syslog: {facility: ::Syslog::LOG_LOCAL1}}`, take precedence. A formatter passed
+as an instance keeps its own settings.
+
 Add a filter to exclude noisy entries such as health checks:
 
 ~~~ruby
@@ -512,8 +592,10 @@ SemanticLogger.add_appender(
 ~~~
 
 Syslog frames each record, so embedded newlines or other control characters in untrusted data could
-forge or split records. The syslog formatters therefore escape control characters by default. To pass
-them through unchanged:
+forge or split records. The syslog formatters therefore escape control characters by default. The
+`:syslog` formatter also escapes the newlines between an exception and its backtrace lines (written
+as `\n`), so that an entry with an exception is a single line. To pass control characters through
+unchanged, which also restores the multi-line exception layout:
 
 ~~~ruby
 SemanticLogger.add_appender(
@@ -603,24 +685,13 @@ instead, which reached about 1,400 entries per second (1,200 with SSL).
 
 ### Splunk SDK
 
-`appender: :splunk` submits entries through the official `splunk-sdk-ruby` gem to the Splunk
-management port (8089 by default). Authenticate with either a username and password, or a
-pre-authenticated `token:`:
+> **Deprecated:** `appender: :splunk` is deprecated and will be removed in v6. Use the
+> [HTTP Event Collector](#splunk-http) (`appender: :splunk_http`) or the
+> [TCP appender](#tcp-appender-ssl) instead.
 
-~~~ruby
-SemanticLogger.add_appender(
-  appender: :splunk,
-  username: "username",
-  password: "password",
-  host:     "localhost",
-  port:     8089,
-  scheme:   :https,
-  index:    "main"
-)
-~~~
-
-For most deployments the [HTTP Event Collector](#splunk-http) or the [TCP appender](#tcp-appender-ssl)
-is the simpler choice; use the SDK appender when the management API is the only ingress available.
+`appender: :splunk` submits entries through the `splunk-sdk-ruby` gem to the Splunk management
+port. That gem was last released in 2015 and does not verify the server's TLS certificate, so the
+connection, including the login credentials, is open to interception.
 
 ### Grafana Loki
 
@@ -638,7 +709,8 @@ SemanticLogger.add_appender(
 ~~~
 
 Set the URL, username, and password to match your Loki instance. Set `compress: true` to compress the
-log messages.
+log messages. The ingestion path is appended to the url, so a query string on the url is kept and sent
+with every push.
 
 ### CloudWatch Logs
 
@@ -804,19 +876,27 @@ Some logging context is forwarded to Sentry:
 
 * From named tags, `transaction_name`. See
   <https://docs.sentry.io/platforms/ruby/enriching-events/transaction-name/>.
-* From named tags or payload, `user` is built from the `user_id`, `username`, `user_email`, and
+* From named tags, `user` is built from the `user_id`, `username`, `user_email`, and
   `ip_address` keys, plus any `user` key that is itself a hash. See
   <https://docs.sentry.io/platforms/ruby/enriching-events/identify-user/>.
-* From the payload, `fingerprint` configures grouping granularity. See
+* From named tags, `fingerprint` (an Array of Strings, Symbols, or numbers) configures grouping
+  granularity. See
   <https://docs.sentry.io/platforms/ruby/usage/sdk-fingerprinting/>.
 * Named tags are sent as Sentry tags. See
   <https://docs.sentry.io/platforms/ruby/enriching-events/tags/>.
 * Unnamed tags are sent as the `:tag` tag, separated by commas.
-* Everything else from the payload and context is added to `extras`.
+* Everything else from the payload and context is added to `extras`, including a value of the
+  wrong type for one of the keys above.
+
+> **Deprecated:** the `user` and `fingerprint` keys are also still taken from the payload, but that
+> is deprecated and will be removed in v6, since the payload often holds untrusted data, such as a
+> request body, that could set the user an error is reported for. Set them with named tags. The
+> named tags win over the payload, and a user field is only taken from the payload when it is a
+> String, Symbol, or Integer.
 
 ~~~ruby
-SemanticLogger.tagged(transaction_name: "foo", user_id: 42, baz: "quz") do
-  logger.error("some message", username: "joe", fingerprint: ["bar"])
+SemanticLogger.tagged(transaction_name: "foo", user_id: 42, username: "joe", fingerprint: ["bar"], baz: "quz") do
+  logger.error("some message")
 end
 ~~~
 
@@ -868,6 +948,10 @@ SemanticLogger.on_log do |log|
 end
 ~~~
 
+It sends the whole entry, payload included, so register it after any `on_log` subscriber that
+[redacts sensitive data](security.html#redacting-sensitive-data): subscribers run in the order they
+were registered.
+
 ## Databases and message queues
 
 ### MongoDB