logister-ruby 0.5.1 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 831c1daef24ddf24e6b74e58b22abf58280881bc1b6db683819198e5f6808c03
-  data.tar.gz: 1682771b953d6db5f323b33013c97618945bf3ff95b1c3117ae513c09e565d4c
+  metadata.gz: b53f55583642650e335b75f813f6ed58db64039e24117579e7448fcd1b4cff42
+  data.tar.gz: afc66cf2bf7a07d36cd12ae1fbc0c8339a5fe5c513919cd8fc49c79ac922af6f
 SHA512:
-  metadata.gz: 5580094db13b735ec710752d10633d646f4975ebc48cc4720ea224af883e75c353f9afd724f4e7d41dddf32169498a4fea6f3c2bb1fb6bba0272cb72826ec094
-  data.tar.gz: bae736ef8c2fff8e37b87fe10b21d5ce9162917c5ae24d63aa58c52396f0f0f8b74101a782840d86aba98eb90d1a6b4ebe73c39bc76b61dc6aaaeb58c5771856
+  metadata.gz: 63ea3535fcf6cb865c38a34cd0a7b71d59ad97e49c4dd66db5e7b698b04dfff400c321093c1f3530844620712a6fc171bac6a3e7b8fe2eaa6b4dda6295080528
+  data.tar.gz: 83464fee6f652b3045e371a8722e51730ff6eb7933ba010df2cbc83db4db42848b67276c7f5a80005ca0e1349e0bdc3ba42724cee123b0738ebbe267f17c62ec

data/CHANGELOG.md

@@ -1,5 +1,26 @@
 # Changelog
 
+## v0.6.0 - 2026-10-23
+
+Security hardening. Several defaults change; review before upgrading.
+
+- Added the shared Logister redaction spec. Values of sensitive keys become `"[REDACTED]"`; `Bearer`/`Basic` credentials, JWTs, `lgst_` keys, and sensitive `name=value` pairs are scrubbed from strings. It applies to the message and the whole context (URL, referer, headers, params, user, tags, breadcrumbs, dependencies, job arguments, span attributes, log fields, exception data), never to envelope identifiers. Add keys with `config.redact_keys`.
+- **Changed default:** request headers are captured from an allowlist instead of a five-entry denylist, so `Proxy-Authorization`, `X-Auth-Token`, `X-Amz-Security-Token`, vendor signature headers, and similar are no longer sent. Add headers with `config.capture_headers`; sensitive names are still redacted.
+- Redacted sensitive query values and userinfo passwords in the captured request URL and referer, and dropped fragments.
+- `anonymize_ip` now also truncates `X-Forwarded-For` and `X-Real-Ip`.
+- **Changed default:** `capture_sql_breadcrumbs` is now `false`. When enabled, and for `capture_db_metrics`, string and numeric SQL literals are replaced with `?`.
+- `set_user` now stores the user in the request scope that the middleware and Active Job integration reset, fixing cross-request user attribution on reused threads. Added `Logister.set_user` and `Logister.clear_user`.
+- The middleware no longer lets a context-building or reporting failure replace the application's exception, and it now works on plain Rack without Action Dispatch (parameters are omitted there).
+- Telemetry never raises into the host: public `Logister.*` methods, the Active Job hook, and subscribers catch and log their own failures.
+- Only transport failures (timeouts, `IOError`, `SocketError`, `OpenSSL::SSL::SSLError`, `Errno::*`) and HTTP 408/425/429/5xx are retried.
+- Each event is sanitized and serialized individually before batching: invalid UTF-8 is scrubbed, non-finite floats become strings, and an event that cannot be serialized is dropped alone (`serialization_error`) instead of failing its whole batch after retries.
+- Bounded every event: strings at 16 KB, collections at 100 items, depth at 10, 400 keys, and `config.max_event_bytes` (default 256 KB) overall, with a compact second pass before dropping (`event_too_large`).
+- Synchronous delivery and deployment records use `config.sync_max_retries` (default 1) with waits capped at one second, instead of the background retry budget.
+- The client remembers an unsupported batch endpoint instead of retrying it before every fallback.
+- `Logister.configure` now shuts down the previous client, and a single `at_exit` hook flushes the current reporter.
+- The client warns when an endpoint uses `http://` on a non-loopback host.
+- Internal warnings log only error classes, never exception messages.
+
 ## v0.5.1 - 2026-09-26
 
 - Restore the enclosing request or job scope after inline and nested Active Job executions, including failures, preserving request tracing, breadcrumbs, and dependencies while keeping job telemetry isolated.

data/README.md

@@ -122,10 +122,15 @@ Logister.configure do |config|
   config.anonymize_ip = false
   config.max_breadcrumbs = 40
   config.max_dependencies = 20
-  config.capture_sql_breadcrumbs = true
+  config.capture_sql_breadcrumbs = false # default; literals are stripped when enabled
   config.sql_breadcrumb_min_duration_ms = 25.0
   config.capture_request_spans = true
 
+  # Redaction and payload bounds (see "Filtering and redaction")
+  config.redact_keys = []        # extra sensitive keys, e.g. ["tenant_ref"]
+  config.capture_headers = []    # extra request headers to capture
+  config.max_event_bytes = 262_144
+
   config.feature_flags_resolver = lambda do |request:, user:, **|
     { new_checkout: user&.respond_to?(:beta?) && user.beta? }
   end
@@ -136,7 +141,9 @@ Logister.configure do |config|
 end
 ```
 
-If you are using a self-hosted Logister install, point `config.endpoint` at your own Logister host instead of `logister.org`.
+If you are using a self-hosted Logister install, point `config.endpoint` at your own Logister host instead of `logister.org`. Use HTTPS: the client logs a warning when an endpoint uses `http://` on a host other than `localhost` or a loopback address, because the API key and events would travel unencrypted.
+
+Calling `Logister.configure` again replaces the reporter. The previous client drains what it already queued and stops, and one `at_exit` hook flushes whichever reporter is current when the process exits.
 
 Keep `LOGISTER_API_KEY` in your deployment secret store. Project API keys are write-only ingest credentials, but exposing one still lets another party submit unwanted telemetry to the project.
 
@@ -150,17 +157,36 @@ Logister.configure do |config|
   config.batch_interval = 0.05
   config.batch_compression = true
   config.max_retries = 3
+  config.sync_max_retries = 1
   config.retry_base_interval = 0.5
   config.max_retry_delay = 30.0
   config.retry_jitter = 0.2
 end
 ```
 
+Only transport failures are retried: timeouts, `IOError`, `SocketError`,
+`OpenSSL::SSL::SSLError`, `Errno::*`, and HTTP `408`, `425`, `429`, or `5xx`
+responses. Any other error fails the attempt once.
+
+With `config.async = false`, delivery runs on the caller's thread, so it uses
+`sync_max_retries` (default `1`, never more than `max_retries`) and caps each
+wait at one second. Deployment records are always sent this way.
+
+Each event is sanitized and serialized on its own before it is batched. Invalid
+UTF-8 is replaced, `NaN`/`Infinity` become strings, strings are truncated at
+16 KB, collections at 100 items, nesting at 10 levels, and each event at 400
+keys, with `logister_truncated: true` added to the context when anything was
+cut. An event larger than `max_event_bytes` (default 256 KB) after a second,
+tighter pass is dropped and counted as unconfirmed with reason
+`event_too_large`; an event that cannot be serialized is dropped with reason
+`serialization_error`. Neither affects the other events in its batch.
+
 Asynchronous delivery assigns a UUID before enqueueing, combines queued events into
 gzip/NDJSON batches, and retries the same identifiers. This makes a whole-batch retry
 safe against a Logister server that supports the batch endpoint. Older servers are
 detected automatically and receive the same stable events through the single-event
-endpoint. Call `Logister.flush` before a short-lived process exits.
+endpoint; the client remembers that answer for its lifetime instead of retrying
+the batch endpoint every time. Call `Logister.flush` before a short-lived process exits.
 
 ### Delivery outcomes
 
@@ -186,6 +212,56 @@ Retryable responses honor `Retry-After` when present, cap any individual wait at
 
 ## Filtering and redaction
 
+Every event is redacted in the client before it is serialized, using the default
+spec shared by all Logister SDKs:
+
+- **Sensitive keys.** A key is sensitive when, lowercased with every
+  non-alphanumeric character removed, it equals one of `password`, `passwd`,
+  `pwd`, `secret`, `token`, `apikey`, `authorization`, `proxyauthorization`,
+  `cookie`, `setcookie`, `sessiontoken`, `sessionkey`, `credential`,
+  `credentials`, `privatekey`, `clientsecret`, `accesstoken`, `refreshtoken`,
+  `idtoken`, `authtoken`, `xapikey`, `xauthtoken`, `xaccesstoken`,
+  `xcsrftoken`, `xxsrftoken`, `signature`, `ssn`, `creditcard`, `cardnumber`,
+  or `cvv`, or when it contains `token`, `secret`, `password`, `passwd`,
+  `apikey`, `authorization`, `credential`, or `cookie`. The whole value becomes
+  `"[REDACTED]"`.
+- **Credential-shaped strings.** `Bearer <x>` and `Basic <x>` become
+  `Bearer [REDACTED]` / `Basic [REDACTED]`; JWT-shaped strings and `lgst_` keys
+  become `[REDACTED]`; a `name=value` pair with a sensitive name keeps its name.
+- **URLs.** The captured request URL and referer keep scheme, host, and path;
+  sensitive query values and userinfo passwords become `[REDACTED]` and the
+  fragment is dropped.
+
+Redaction covers the message and the whole context: request URL, referer,
+headers, params, user context, tags, breadcrumbs, dependency calls, job
+arguments (after Rails `filter_parameters`), span attributes, log fields, and
+exception data. SDK envelope fields such as `uuid`, `event_type`, `trace_id`,
+`span_id`, `parent_span_id`, `request_id`, and `session_id` are never redacted.
+
+Add project-specific keys with `config.redact_keys`. Entries are normalized the
+same way and must match exactly:
+
+```ruby
+Logister.configure do |config|
+  config.redact_keys = ["tenant_ref", "X-Internal-Signature"]
+end
+```
+
+Request headers are captured from an allowlist: `Accept`, `Accept-Encoding`,
+`Accept-Language`, `Cache-Control`, `Content-Length`, `Content-Type`, `Dnt`,
+`Host`, `Origin`, `Referer`, `User-Agent`, `Via`, W3C, B3, Datadog, and AWS trace
+headers, `X-Request-Id`, `X-Forwarded-For/Host/Proto/Port`, `X-Real-Ip`, and
+`Sec-Fetch-*`/`Sec-Ch-Ua*` hints. Add headers with
+`config.capture_headers = ["X-Tenant"]`; the sensitive-key rule still applies,
+so a header such as `X-Auth-Token` is captured as `[REDACTED]`. With
+`config.anonymize_ip = true`, the client IP and every address in
+`X-Forwarded-For` and `X-Real-Ip` are truncated (`/24` for IPv4, `/64` for IPv6).
+
+Telemetry never raises into your application. The public `Logister.*` methods,
+the Rack middleware, the Active Job hook, and the SQL and request subscribers
+catch their own failures, log the error class through `config.logger`, and
+re-raise only the application's original exception.
+
 ```ruby
 Logister.configure do |config|
   config.ignore_environments = ["development", "test"]
@@ -211,7 +287,16 @@ This is especially important when a Rails application reports into a Logister pr
 
 ## Rails auto-reporting
 
-If Rails is present, the gem installs middleware that reports unhandled exceptions automatically. It attaches trace IDs, route and response data, performance context, breadcrumbs, dependency calls, and user metadata when available.
+If Rails is present, the gem installs middleware that reports unhandled exceptions automatically. Plain Rack apps can add it themselves:
+
+```ruby
+# config.ru
+require "logister"
+use Logister::Middleware
+run MyApp
+```
+
+Without Action Dispatch the middleware uses `Rack::Request` and omits request parameters, because there is no host parameter filter; the redacted URL still records the query string. It attaches trace IDs, route and response data, performance context, breadcrumbs, dependency calls, and user metadata when available.
 
 Set `config.capture_request_spans = true` to emit root `server` spans for request-load waterfall charts while keeping the existing transaction events. Manual `Logister.report_error` calls use the same enrichment path, including runtime, deployment, breadcrumb, dependency, user, and nested-exception context.
 
@@ -227,7 +312,7 @@ Logister.configure do |config|
 end
 ```
 
-This emits metric events with `message: "db.query"` and context fields such as `duration_ms`, `name`, `sql`, and `binds_count`.
+This emits metric events with `message: "db.query"` and context fields such as `duration_ms`, `name`, `sql`, and `binds_count`. String and numeric literals are replaced with `?` in the captured `sql`, so inlined values such as password hashes or reset tokens are not sent; bind placeholders like `$1` and quoted identifiers are kept.
 
 ## Breadcrumbs and dependencies
 
@@ -250,7 +335,7 @@ Logister.add_dependency(
 )
 ```
 
-The gem also captures request and SQL breadcrumbs automatically in Rails.
+The gem also captures request breadcrumbs automatically in Rails. SQL breadcrumbs are off by default because adapters without prepared statements inline literal values; set `config.capture_sql_breadcrumbs = true` to record queries slower than `sql_breadcrumb_min_duration_ms`, with string and numeric literals replaced by `?`.
 
 ## ActiveJob error context
 
@@ -262,6 +347,18 @@ Failed ActiveJob executions are auto-reported with `job` context:
 
 ## Manual reporting
 
+Attach the signed-in user to errors reported during the current request or job:
+
+```ruby
+Logister.set_user(id: current_user.id, email: current_user.email, name: current_user.name)
+Logister.clear_user
+```
+
+The user is stored in the request scope, which the Rack middleware and the
+Active Job integration reset when each request or job ends, so identity never
+carries over to the next request on a reused Puma or Sidekiq thread. In other
+long-lived threads, call `Logister.clear_user` when the unit of work ends.
+
 ```ruby
 Logister.report_error(StandardError.new("Something failed"), tags: { area: "checkout" })
 

data/lib/generators/logister/templates/logister.rb

@@ -22,10 +22,18 @@ Logister.configure do |config|
   config.ignore_exceptions = []
   config.ignore_paths = []
 
+  # Values of sensitive keys (password, token, secret, authorization, cookie,
+  # and more) are always replaced with "[REDACTED]". Add project-specific keys.
+  config.redact_keys = []
+  # Request headers are captured from an allowlist; add extra header names here.
+  config.capture_headers = []
+
   # Optional ActiveRecord SQL instrumentation.
   config.capture_db_metrics = false
   config.db_metric_min_duration_ms = 10.0
   config.db_metric_sample_rate = 1.0
+  # SQL breadcrumbs are off by default; literals are stripped when enabled.
+  config.capture_sql_breadcrumbs = false
 
   config.before_notify = lambda do |payload|
     payload

data/lib/logister/active_job_reporter.rb

@@ -26,10 +26,7 @@ module Logister
             begin
               block.call
             rescue StandardError => error
-              Logister.report_error(
-                error,
-                context: Logister::ActiveJobReporter.build_job_error_context(job, started_at: started_at)
-              )
+              Logister::ActiveJobReporter.report_job_error(job, error, started_at: started_at)
               raise
             end
           end
@@ -39,7 +36,16 @@ module Logister
 
     module_function
 
-    def build_job_error_context(job, started_at:)
+    # Context building and reporting run in their own rescue so a telemetry
+    # failure can never replace the job's exception.
+    def report_job_error(job, error, started_at:)
+      Logister.report_error(error, context: build_job_error_context(job, started_at: started_at))
+    rescue StandardError => e
+      Logister.log_internal_error('job error report', e)
+      nil
+    end
+
+    def build_job_error_context(job, started_at: nil) # rubocop:disable Lint/UnusedMethodArgument
       Logister::ContextHelpers.compact_deep(
         {
           job: {

data/lib/logister/client.rb

@@ -7,15 +7,47 @@ require 'securerandom'
 require 'time'
 require 'uri'
 require 'zlib'
+require 'ipaddr'
+begin
+  require 'openssl'
+rescue LoadError
+  nil
+end
+require_relative 'event_sanitizer'
+require_relative 'redaction'
 
 module Logister
   class Client
     CONTENT_TYPE = 'application/json'
     BATCH_CONTENT_TYPE = 'application/x-ndjson'
     UNSUPPORTED_BATCH_STATUSES = %w[404 405 415 501].freeze
+    RETRYABLE_STATUSES = [408, 425, 429].freeze
+    SYNC_MAX_RETRY_DELAY = 1.0
+    RETRYABLE_ERRORS = [
+      Timeout::Error, IOError, SocketError, SystemCallError,
+      (OpenSSL::SSL::SSLError if defined?(OpenSSL::SSL::SSLError))
+    ].compact.freeze
 
     class UnsupportedBatchEndpoint < StandardError; end
 
+    # One event serialized on its own before batching. A payload that cannot be
+    # encoded is dropped alone instead of failing every event batched with it.
+    class Event
+      attr_reader :uuid, :payload, :json
+
+      def initialize(uuid:, payload:, json:)
+        @uuid = uuid
+        @payload = payload
+        @json = json
+        freeze
+      end
+
+      def [](key) = payload[key]
+      def fetch(...) = payload.fetch(...)
+      def key?(key) = payload.key?(key)
+      def to_h = payload
+    end
+
     class RequestError < StandardError
       attr_reader :status, :retry_after
 
@@ -49,24 +81,34 @@ module Logister
       @batch_use_ssl  = @batch_uri.scheme == 'https'
       @deployment_use_ssl = @deployment_uri.scheme == 'https'
       @auth_header    = "Bearer #{@configuration.api_key}".freeze
+      @redact_keys    = Redaction.normalize_keys(@configuration.redact_keys)
+      @batch_unsupported = false
+      warn_insecure_endpoints
     end
 
     def publish(payload)
       return false if ReportingScope.suppressed?
       return false unless ready?
 
-      payload = with_stable_uuid(payload)
+      event = encode_event(with_stable_uuid(payload))
+      return false unless event
 
-      return publish_sync(payload) unless @configuration.async
+      return publish_sync(event) unless @configuration.async
 
       ensure_worker_started
-      enqueue(payload)
+      enqueue(event)
+    rescue StandardError => e
+      warn_internal("logister publish failed: #{e.class}")
+      false
     end
 
     def publish_deployment(payload)
       return false unless ready?
 
       publish_deployment_sync(payload)
+    rescue StandardError => e
+      warn_internal("logister deployment publish failed: #{e.class}")
+      false
     end
 
     def flush(timeout: 2)
@@ -122,7 +164,7 @@ module Logister
     rescue ThreadError
       complete_pending(1)
       record_delivery(:queue_full_events, 1, reason: 'queue_full')
-      @configuration.logger.warn('logister queue full; dropping event')
+      warn_internal('logister queue full; dropping event')
       false
     end
 
@@ -168,18 +210,27 @@ module Logister
         break if stop_after_batch || (@stopping && @queue.empty?)
       end
     rescue StandardError => e
-      @configuration.logger.warn("logister worker crashed: #{e.class} #{e.message}")
+      warn_internal("logister worker crashed: #{e.class}")
     ensure
       # Always clear running flag and attempt auto-restart after a crash so
       # events enqueued after the crash are not silently dropped.
       @running = false
     end
 
-    def publish_sync(payload)
+    # Synchronous mode delivers on the caller's thread, so it uses a small retry
+    # cap and short waits instead of the background worker's limits.
+    def publish_sync(event)
+      publish_single(event, max_retries: sync_max_retries, max_delay: SYNC_MAX_RETRY_DELAY)
+    end
+
+    def publish_single(event, max_retries: @configuration.max_retries.to_i, max_delay: nil)
+      event = coerce_event(event)
+      return false unless event
+
       attempts = 0
       begin
         attempts += 1
-        delivered = send_request(payload)
+        delivered = send_request(event)
         unless delivered
           record_delivery(:unconfirmed_events, 1, reason: 'no_acknowledgment')
           return false
@@ -187,19 +238,29 @@ module Logister
         record_delivery(:acknowledged_events, 1)
         true
       rescue StandardError => e
-        if attempts <= @configuration.max_retries && retryable_error?(e)
+        if attempts <= max_retries && retryable_error?(e)
           record_delivery(:retry_attempts, 1, reason: failure_reason(e))
-          sleep(retry_delay(e, attempts))
+          sleep(retry_delay(e, attempts, max_delay: max_delay))
           retry
         end
 
         record_delivery(:unconfirmed_events, 1, reason: failure_reason(e))
-        @configuration.logger.warn("logister publish failed: #{e.class}")
+        warn_internal("logister publish failed: #{e.class}")
         false
       end
     end
 
-    def publish_batch_sync(payloads)
+    def publish_batch_sync(items)
+      payloads = items.filter_map { |item| coerce_event(item) }
+      all_encoded = payloads.length == items.length
+      return all_encoded if payloads.empty?
+
+      deliver_batch(payloads) && all_encoded
+    end
+
+    def deliver_batch(payloads)
+      return publish_each(payloads) if @batch_unsupported
+
       attempts = 0
       begin
         attempts += 1
@@ -211,57 +272,54 @@ module Logister
         record_delivery(:acknowledged_events, payloads.length)
         true
       rescue UnsupportedBatchEndpoint
-        payloads.map { |payload| publish_sync(payload) }.all?
-      rescue RequestError => e
-        if e.status == 413 && payloads.length > 1
+        # Older servers keep this answer for the life of the client; stop paying
+        # for a failed batch request before every fallback.
+        @batch_unsupported = true
+        publish_each(payloads)
+      rescue StandardError => e
+        if e.is_a?(RequestError) && e.status == 413 && payloads.length > 1
           middle = (payloads.length / 2.0).ceil
-          first_half_delivered = publish_batch_sync(payloads.first(middle))
-          second_half_delivered = publish_batch_sync(payloads.drop(middle))
+          first_half_delivered = deliver_batch(payloads.first(middle))
+          second_half_delivered = deliver_batch(payloads.drop(middle))
           return first_half_delivered && second_half_delivered
         end
-        if attempts <= @configuration.max_retries && retryable_error?(e)
+        if attempts <= @configuration.max_retries.to_i && retryable_error?(e)
           record_delivery(:retry_attempts, 1, reason: failure_reason(e))
           sleep(retry_delay(e, attempts))
           retry
         end
 
         record_delivery(:unconfirmed_events, payloads.length, reason: failure_reason(e))
-        @configuration.logger.warn("logister batch publish failed: #{e.class}")
-        false
-      rescue StandardError => e
-        if attempts <= @configuration.max_retries && retryable_error?(e)
-          record_delivery(:retry_attempts, 1, reason: failure_reason(e))
-          sleep(retry_delay(e, attempts))
-          retry
-        end
-
-        record_delivery(:unconfirmed_events, payloads.length, reason: failure_reason(e))
-        @configuration.logger.warn("logister batch publish failed: #{e.class}")
+        warn_internal("logister batch publish failed: #{e.class}")
         false
       end
     end
 
+    def publish_each(events)
+      events.map { |event| publish_single(event) }.all?
+    end
+
     def publish_deployment_sync(payload)
       attempts = 0
       begin
         attempts += 1
         send_deployment_request(payload)
       rescue StandardError => e
-        if attempts <= @configuration.max_retries && retryable_error?(e)
-          sleep(retry_delay(e, attempts))
+        if attempts <= sync_max_retries && retryable_error?(e)
+          sleep(retry_delay(e, attempts, max_delay: SYNC_MAX_RETRY_DELAY))
           retry
         end
 
-        @configuration.logger.warn("logister deployment publish failed: #{e.class} #{e.message}")
+        warn_internal("logister deployment publish failed: #{e.class}")
         false
       end
     end
 
-    def send_request(payload)
+    def send_request(event)
       request = Net::HTTP::Post.new(@uri)
       request['Content-Type']  = CONTENT_TYPE
       request['Authorization'] = @auth_header
-      request.body             = { event: payload }.to_json
+      request.body             = coerce_event!(event).json
 
       response = Net::HTTP.start(
         @uri.host,
@@ -277,13 +335,14 @@ module Logister
       raise request_error(response)
     end
 
-    def send_batch_request(payloads)
+    def send_batch_request(events)
+      events = events.map { |event| coerce_event!(event) }
       request = Net::HTTP::Post.new(@batch_uri)
       request['Content-Type'] = BATCH_CONTENT_TYPE
       request['Authorization'] = @auth_header
-      request['X-Logister-Batch-Id'] = batch_id(payloads)
+      request['X-Logister-Batch-Id'] = batch_id(events)
 
-      body = payloads.map { |payload| { event: payload }.to_json }.join("\n") << "\n"
+      body = events.map(&:json).join("\n") << "\n"
       if @configuration.batch_compression
         request['Content-Encoding'] = 'gzip'
         body = Zlib.gzip(body)
@@ -309,7 +368,7 @@ module Logister
       request = Net::HTTP::Post.new(@deployment_uri)
       request['Content-Type']  = CONTENT_TYPE
       request['Authorization'] = @auth_header
-      request.body             = { deployment: payload }.to_json
+      request.body             = JSON.generate({ deployment: EventSanitizer.call(payload, extra_keys: @redact_keys) })
 
       response = Net::HTTP.start(
         @deployment_uri.host,
@@ -369,11 +428,74 @@ module Logister
 
     def batch_id(payloads)
       identifiers = payloads.map do |payload|
+        next payload.uuid if payload.is_a?(Event)
+
         payload[:uuid] || payload['uuid'] || payload[:event_id] || payload['event_id']
       end
       Digest::SHA256.hexdigest(identifiers.join("\n"))
     end
 
+    # Sanitizes, redacts, and serializes one event. Oversized events are retried
+    # with compact limits; an event that still cannot be encoded is dropped and
+    # counted without affecting any other event.
+    def encode_event(payload)
+      uuid = payload[:uuid] || payload['uuid']
+      [EventSanitizer::DEFAULT_LIMITS, EventSanitizer::COMPACT_LIMITS].each do |limits|
+        sanitized = EventSanitizer.call(payload, extra_keys: @redact_keys, limits: limits)
+        json = JSON.generate({ event: sanitized })
+        return Event.new(uuid: uuid.to_s, payload: sanitized, json: json) if json.bytesize <= max_event_bytes
+      end
+
+      record_delivery(:unconfirmed_events, 1, reason: 'event_too_large')
+      warn_internal('logister dropped an event larger than max_event_bytes')
+      nil
+    rescue StandardError => e
+      record_delivery(:unconfirmed_events, 1, reason: 'serialization_error')
+      warn_internal("logister could not serialize an event: #{e.class}")
+      nil
+    end
+
+    def coerce_event(item)
+      return item if item.is_a?(Event)
+
+      encode_event(with_stable_uuid(item))
+    end
+
+    def coerce_event!(item)
+      coerce_event(item) || raise(ArgumentError, 'event could not be encoded')
+    end
+
+    def max_event_bytes
+      [@configuration.max_event_bytes.to_i, 1024].max
+    end
+
+    def sync_max_retries
+      [[@configuration.sync_max_retries.to_i, 0].max, @configuration.max_retries.to_i].min
+    end
+
+    def warn_internal(message)
+      @configuration.logger&.warn(message)
+    rescue StandardError
+      nil
+    end
+
+    def warn_insecure_endpoints
+      [@uri, @batch_uri, @deployment_uri].uniq { |uri| [uri.host, uri.port] }.each do |uri|
+        next unless uri.scheme == 'http' && !loopback_host?(uri.host)
+
+        warn_internal("logister endpoint #{uri.scheme}://#{uri.host} is not HTTPS; the API key and events are sent unencrypted")
+      end
+    end
+
+    def loopback_host?(host)
+      name = host.to_s.downcase.delete_prefix('[').delete_suffix(']')
+      return true if name == 'localhost' || name.end_with?('.localhost')
+
+      IPAddr.new(name).loopback?
+    rescue ArgumentError
+      false
+    end
+
     def batch_size
       [@configuration.batch_size.to_i, 1].max
     end
@@ -393,10 +515,12 @@ module Logister
       end
     end
 
+    # Only transport failures and transient HTTP statuses are retried; a bug or
+    # an unencodable payload fails once instead of being repeated.
     def retryable_error?(error)
-      return true unless error.is_a?(RequestError)
+      return RETRYABLE_STATUSES.include?(error.status) || error.status >= 500 if error.is_a?(RequestError)
 
-      [408, 425, 429].include?(error.status) || error.status >= 500
+      RETRYABLE_ERRORS.any? { |klass| error.is_a?(klass) }
     end
 
     def request_error(response)
@@ -415,8 +539,9 @@ module Logister
       nil
     end
 
-    def retry_delay(error, attempt)
+    def retry_delay(error, attempt, max_delay: nil)
       configured_cap = [@configuration.max_retry_delay.to_f, 0.0].max
+      configured_cap = [configured_cap, max_delay].min if max_delay
       base_delay = if error.is_a?(RequestError) && !error.retry_after.nil?
                      error.retry_after.to_f
                    else

data/lib/logister/configuration.rb

@@ -10,7 +10,8 @@ module Logister
                   :capture_db_metrics, :db_metric_min_duration_ms, :db_metric_sample_rate,
                   :feature_flags_resolver, :dependency_resolver, :anonymize_ip,
                   :max_breadcrumbs, :max_dependencies, :capture_request_spans,
-                  :capture_sql_breadcrumbs, :sql_breadcrumb_min_duration_ms, :delivery_observer
+                  :capture_sql_breadcrumbs, :sql_breadcrumb_min_duration_ms, :delivery_observer,
+                  :redact_keys, :capture_headers, :max_event_bytes, :sync_max_retries
     attr_writer :deployment_endpoint, :batch_endpoint
 
     def initialize
@@ -37,6 +38,7 @@ module Logister
       @async = true
       @queue_size = 1000
       @max_retries = 3
+      @sync_max_retries = 1
       @retry_base_interval = 0.5
       @max_retry_delay = 30.0
       @retry_jitter = 0.2
@@ -54,8 +56,12 @@ module Logister
       @max_breadcrumbs = 40
       @max_dependencies = 20
       @capture_request_spans = false
-      @capture_sql_breadcrumbs = true
+      @capture_sql_breadcrumbs = false
       @sql_breadcrumb_min_duration_ms = 25.0
+
+      @redact_keys = []
+      @capture_headers = []
+      @max_event_bytes = 256 * 1024
     end
 
     def deployment_endpoint