logbrew-sdk 0.1.1 → 0.1.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: dd015a45db45c66bd30d0d2a273a9aab8c8c4ec8b4d486545bf778bb0eba8fbf
-  data.tar.gz: edc117c673cb97a6321cc0a58029673cd0ecdba0b5e2c1d48d41e71e8e967a30
+  metadata.gz: 233087ef98eb35d7df84720956a89dfbf66368ac55269900a38491192c7a67a3
+  data.tar.gz: 1720b83bf8dcc562771936091f0196996415005e6a5ea254ca4e0a803e3ea1ac
 SHA512:
-  metadata.gz: 2b610b4733c474a40fbb55725281966fc708332f5d3215f807205ff8b31c38dafdf6ad24764b816a30d303584948a15925d48910b4b6b04e5d7cd5a90f5c516c
-  data.tar.gz: 24dbb604cebc482ccc8d9450d58e523a678d284387908bf907eb1d8f70daa1649fb8898f9a41ef27ebdfa649be67329ba3cbea1aba44745ecbda637eac7a3e82
+  metadata.gz: 1e67486d07bb9334f6cf553111e8e198f1b448105cc491cad566d03e4356a190b00891c054552f9022c9dc982019bce506dc7ab09f7340d3321785935b34fef7
+  data.tar.gz: 66c92e704c995f6a0ab73586eefa8a65cf7aef4af621a3dbbc68c925b6063851ebc422c8d23d5f30de40ea7b111989bd0154ed740fc334d109ce72cfabe8971b

data/README.md

@@ -4,9 +4,10 @@
   <img src="https://raw.githubusercontent.com/LogBrewCo/sdk/main/assets/brand/logbrew-logo-transparent-512.png" alt="LogBrew logo" width="96" height="96">
 </p>
 
-Public Ruby SDK for building, validating, previewing, and flushing LogBrew event batches, with standard-library `Net::HTTP` delivery, opt-in standard-library `Logger` support, Rack-compatible middleware, and a Rails error subscriber for Rails apps.
+Public Ruby SDK for building, validating, previewing, and flushing LogBrew event batches, with automatic Rails request/error capture, standard-library `Net::HTTP` delivery, opt-in standard-library `Logger` support, and manual Rack helpers.
 
-The package uses only Ruby standard-library features at runtime.
+The core package has no runtime gem dependencies. Its automatic integration
+activates only inside an application that has already loaded Rails.
 
 ## Install
 
@@ -14,13 +15,106 @@ The package uses only Ruby standard-library features at runtime.
 gem install logbrew-sdk
 ```
 
+## Rails Quick Start
+
+Add the gem normally. Its package-name require shim loads the Rails integration
+when Rails is present, so `require: "logbrew"` and a custom initializer are not
+needed:
+
+```ruby
+# Gemfile
+gem "logbrew-sdk", "~> 0.1.3"
+```
+
+```bash
+bundle install
+export LOGBREW_SERVER_API_KEY="your project-scoped server ingest key"
+bin/rails server
+```
+
+That is the complete Rails application change. The Railtie installs one
+request middleware, subscribes to handled Rails errors, creates a fresh client
+inside each server process, delivers in the background, and performs one
+bounded shutdown drain. Without `LOGBREW_SERVER_API_KEY`, the integration stays
+disabled and the application behaves normally. Set `LOGBREW_ENABLED=false` to
+disable it explicitly. If the Gemfile uses `require: false`, load
+`logbrew/rails` yourself after Rails.
+
+The automatic integration records route-template request spans and type-only
+issues. It does not record concrete request paths, query strings, request or
+response bodies, arbitrary headers, authorization values, cookies, user IDs,
+exception messages, or exception backtraces. Exception messages and backtraces
+are separate opt-ins:
+
+| Environment variable | Default | Purpose |
+| --- | --- | --- |
+| `LOGBREW_ENABLED` | inferred | Optional explicit `true` or `false` override |
+| `LOGBREW_SERVER_API_KEY` | unset | Project-scoped server ingest key; enables the integration |
+| `LOGBREW_SERVICE_NAME` | Rails application name | Bounded service metadata |
+| `LOGBREW_ENVIRONMENT` | `Rails.env` | Bounded environment metadata |
+| `LOGBREW_RELEASE` | unset | Optional release identifier |
+| `LOGBREW_ENDPOINT` | `https://api.logbrew.co/v1/events` | HTTPS intake URL; loopback HTTP is accepted for local development |
+| `LOGBREW_REQUEST_TIMEOUT_MS` | `10000` | Per-request delivery timeout from 1 to 600000 ms |
+| `LOGBREW_FLUSH_INTERVAL_MS` | `5000` | Automatic delivery interval from 10 to 3600000 ms |
+| `LOGBREW_FLUSH_THRESHOLD` | `100` | Queue size from 1 to 1000 that requests an earlier flush |
+| `LOGBREW_CAPTURE_EXCEPTION_MESSAGES` | `false` | Opt in to exception message capture |
+| `LOGBREW_INCLUDE_EXCEPTION_BACKTRACE` | `false` | Opt in to exception backtrace capture |
+
+`LOGBREW_API_KEY` and `LOGBREW_INGEST_KEY` are not Rails aliases. If either is
+set without the canonical server key, startup reports the exact
+`LOGBREW_SERVER_API_KEY` correction without printing any key value.
+
+### Create a Project and Confirm Hosted Rails Delivery
+
+LogBrew CLI 0.1.32 or newer can create a project and one-time key without a
+dashboard handoff. The destination key file must not already exist:
+
+```bash
+logbrew status --json
+install -d -m 700 "$HOME/.logbrew"
+
+project_result="$(
+  logbrew projects create rails-service \
+    --runtime ruby \
+    --environment development \
+    --ingest-key-file "$HOME/.logbrew/rails-service.ingest" \
+    --json
+)"
+export LOGBREW_PROJECT_ID="$(jq -er '.project.id' <<<"$project_result")"
+unset project_result
+export LOGBREW_SERVER_API_KEY="$(< "$HOME/.logbrew/rails-service.ingest")"
+export LOGBREW_SERVICE_NAME="rails-service"
+```
+
+Start Rails and request one application route. Then inspect the same project
+through the approved CLI session:
+
+```bash
+logbrew doctor --project "$LOGBREW_PROJECT_ID" --json
+logbrew traces --project "$LOGBREW_PROJECT_ID" \
+  --service rails-service \
+  --since 1h \
+  --json
+```
+
+When the temporary project is no longer needed, archive it and remove the
+revoked one-time key:
+
+```bash
+unset LOGBREW_SERVER_API_KEY
+unset LOGBREW_SERVICE_NAME
+logbrew projects archive "$LOGBREW_PROJECT_ID" --yes --json
+rm -f "$HOME/.logbrew/rails-service.ingest"
+unset LOGBREW_PROJECT_ID
+```
+
 ## Usage
 
 ```ruby
 require "logbrew"
 
 client = LogBrew::Client.create(
-  api_key: "LOGBREW_API_KEY",
+  api_key: ENV.fetch("LOGBREW_SERVER_API_KEY"),
   sdk_name: "my-ruby-app",
   sdk_version: "1.0.0"
 )
@@ -43,6 +137,56 @@ response = client.shutdown(LogBrew::RecordingTransport.always_accept)
 warn response.status_code
 ```
 
+## Serialized Worker Lifecycle
+
+Use `LogBrew::WorkerLifecycle` when a prefork or long-running worker processes
+one work item at a time and needs an explicit telemetry boundary:
+
+```ruby
+client = LogBrew::Client.create(
+  api_key: ENV.fetch("LOGBREW_SERVER_API_KEY"),
+  sdk_name: "checkout-worker",
+  sdk_version: "1.0.0"
+)
+transport = LogBrew::HttpTransport.new
+lifecycle = LogBrew::WorkerLifecycle.create(
+  client: client,
+  transport: transport,
+  on_delivery_failure: ->(failure) {
+    warn "LogBrew delivery #{failure.code}; #{failure.pending_events} events retained"
+  }
+)
+
+result = lifecycle.run do
+  client.log(
+    "evt_job_started",
+    Time.now.utc.iso8601,
+    message: "job started",
+    level: "info",
+    logger: "checkout-worker"
+  )
+  perform_one_job
+end
+
+lifecycle.shutdown
+```
+
+Create the client, transport, and lifecycle inside each child process after
+forking. An inherited lifecycle rejects both work and shutdown before touching
+its copied queue or transport, and ownership is checked again after application
+work so a process change cannot flush copied parent state. `run` attempts one
+bounded flush whether the application returns or raises, but always preserves
+the exact application result or original exception. Delivery diagnostics expose
+only a stable stage/code and aggregate queued/dropped counts; they never include
+event content, request bodies, authorization values, exception messages,
+process IDs, paths, or transport state.
+
+This helper is intentionally explicit and installs no background thread,
+timer, signal hook, global fork patch, destructor, or `at_exit` flush. It is for
+serialized worker loops, not concurrent Sidekiq-style job execution. Keep using
+direct `client.flush`/`client.shutdown`, or a framework-specific integration,
+when that lifecycle fits the application better.
+
 ## First Useful Service Telemetry
 
 For a service request, combine release, environment, log, product action, network milestone, metric, and span events around one shared W3C trace:
@@ -121,7 +265,7 @@ headers = LogBrew::Traceparent.create_headers(
 )
 ```
 
-The helper accepts W3C-shaped values, rejects forbidden or all-zero IDs, normalizes uppercase hex to lowercase, exposes the sampled flag, and creates LogBrew child span attributes with a new caller-provided span ID. It does not patch Ruby HTTP clients.
+The helper accepts W3C-shaped values, rejects forbidden or all-zero IDs, normalizes uppercase hex to lowercase, exposes the sampled flag, and creates LogBrew child span attributes with a new caller-provided span ID. It does not patch Ruby HTTP clients globally.
 
 ## HTTP Request Trace Correlation
 
@@ -167,7 +311,38 @@ result = LogBrew::OperationTracing.database_operation(
 end
 ```
 
-`database_operation`, `cache_operation`, and `queue_operation` run your block under a child `LogBrew::Trace` context, preserve the block result or original exception, and emit exactly one span with primitive metadata. Capture failures can be observed with `on_error:` without replacing app behavior. The helpers intentionally drop SQL statements, query params, connection strings, cache keys/values, message bodies, job IDs, headers, cookies, URLs, auth-like fields, and other sensitive-looking metadata; exception spans include only the exception type by default.
+`database_operation`, `cache_operation`, and `queue_operation` run your block under a child `LogBrew::Trace` context, preserve the block result or original exception, and emit exactly one span with primitive metadata. Capture failures can be observed with `on_error:` without replacing app behavior. The helpers intentionally drop SQL statements, query params, connection strings, cache keys/values, message bodies, job IDs, headers, cookies, URLs, auth-like fields, and other sensitive-looking metadata. Failed dependency spans include only the exception type in metadata plus one bounded `exception` span event with `exceptionType` and `exceptionEscaped: true`; exception messages and stacks stay out by default.
+
+## Outbound HTTP Tracing
+
+Wrap an app-owned `Net::HTTP` connection explicitly when outbound work should become a child of the active LogBrew trace:
+
+```ruby
+uri = URI("https://service.example/health")
+http = LogBrew::HttpClientTracing.wrap_net_http(
+  Net::HTTP.new(uri.host, uri.port),
+  client: client,
+  on_capture_error: ->(error) { warn(error.class.name) }
+)
+
+response = http.request(Net::HTTP::Get.new(uri.request_uri))
+```
+
+Faraday remains optional. Apps that already use Faraday can load the integration and place its middleware inside retry middleware so every actual retry receives a distinct child span:
+
+```ruby
+require "faraday"
+require "logbrew/faraday_tracing"
+
+connection = Faraday.new("https://service.example") do |builder|
+  builder.use LogBrew::FaradayTracingMiddleware, client: client
+  builder.adapter :net_http
+end
+```
+
+Both adapters are literal pass-throughs when `LogBrew::Trace.current` is absent. With an active parent, they propagate one W3C `traceparent`, return the caller-visible header and trace scope to their prior values, and capture one completion span per actual execution. Duplicate wrappers, nested LogBrew HTTP middleware, and SDK delivery are suppressed without process-wide hooks. Net::HTTP start blocks, response streaming, Faraday middleware ordering, responses, and exceptions retain their normal behavior; telemetry capture failures are advisory.
+
+Outbound HTTP spans allow only method, normalized host, status code, duration, adapter source, sampled state, and exception type. They never record scheme, port, path, query, fragment, full URL, request or response headers, bodies or sizes, exception messages or stacks, authentication material, cookies, baggage, tracestate, resolved addresses, or arbitrary request options.
 
 ## Metrics
 
@@ -258,7 +433,7 @@ Use `LogBrew::HttpTransport` when you want the SDK to POST queued batches to Log
 require "logbrew"
 
 client = LogBrew::Client.create(
-  api_key: "LOGBREW_API_KEY",
+  api_key: ENV.fetch("LOGBREW_SERVER_API_KEY"),
   sdk_name: "my-ruby-app",
   sdk_version: "1.0.0"
 )
@@ -276,6 +451,129 @@ warn response.status_code
 
 `HttpTransport` sends JSON with the SDK key in the `authorization` header, supports a custom endpoint, headers, timeout, and app-owned HTTP client object, maps HTTP statuses through the client's retry rules, and converts request/time-out failures into retryable transport errors.
 
+## Bounded Delivery
+
+The client bounds queued telemetry and each transport request independently. Queue defaults are 1,000 events and 4 MiB of compact event JSON. Request defaults are 100 events and 256 KiB. When a queue limit is reached, LogBrew rejects the new event so earlier release, environment, and trace context stays available for the next flush. An event that cannot fit one request is rejected before it enters the queue.
+
+```ruby
+dropped = 0
+client = LogBrew::Client.create(
+  api_key: ENV.fetch("LOGBREW_SERVER_API_KEY"),
+  sdk_name: "my-ruby-app",
+  sdk_version: "1.0.0",
+  max_queue_size: 1_000,
+  max_queue_bytes: 4 * 1024 * 1024,
+  max_batch_size: 100,
+  max_batch_bytes: 256 * 1024,
+  on_event_dropped: lambda do |notice|
+    dropped = notice.dropped_events
+    warn "LogBrew queue pressure: #{notice.reason} (#{dropped} dropped)"
+  end
+)
+```
+
+`pending_events`, `pending_event_bytes`, and `dropped_events` expose local pressure without a network call. Events are serialized once at capture, so later mutation of caller-owned strings or metadata cannot change queued content, byte accounting, or retry bodies. `LogBrew::DroppedEvent` contains only the rejected event ID/type, the stable reason `queue_overflow`, `event_too_large`, or opt-in `persistence_failure`, cumulative loss, and retained count/bytes; it never includes event attributes or payload content. Callback errors are isolated from application capture.
+
+Transport bodies use compact JSON and stay under both request limits. `response.attempts` aggregates every request attempt and `response.batches` reports accepted request batches. Each successful request removes only its accepted queue prefix. If a later batch fails, its events and every later event remain queued in order. The failed body is frozen across later `flush` or `shutdown` calls, so events captured after failure cannot change retry bytes. A flush drains only the events present when it started; events captured during transport I/O remain queued.
+
+Existing custom transports keep the same `send(api_key, body)` interface, but they must allow one `flush` to call `send` more than once. Treat each call as an independent compact request and use `response.batches` when application code needs the accepted request count; do not assume one transport call per flush.
+
+`shutdown` rejects new capture while its final flush is running, closes only after every start-snapshot batch is accepted, and reopens capture if delivery fails. Clients created with `Client.create` own no background worker or timer; applications keep explicit control over when network delivery happens.
+
+## Automatic Delivery
+
+Applications that own their transport can opt into one lazy delivery worker. Manual clients remain the default.
+
+```ruby
+transport = LogBrew::HttpTransport.new(timeout: 10)
+client = LogBrew::Client.create_automatic(
+  api_key: ENV.fetch("LOGBREW_SERVER_API_KEY"),
+  sdk_name: "checkout-worker",
+  sdk_version: "1.0.0",
+  transport: transport,
+  flush_interval: 5,
+  flush_threshold: 100,
+  retry_base_delay: 0.25,
+  retry_max_delay: 30,
+  persistent_queue_path: ENV["LOGBREW_PERSISTENT_QUEUE_PATH"]
+)
+
+client.log("evt_job_started", Time.now.utc.iso8601, message: "job started", level: "info")
+warn JSON.generate(client.delivery_health.to_h)
+client.shutdown
+```
+
+The worker starts only after accepted queue work exists, then wakes when the queue reaches `flush_threshold` or `flush_interval` expires. Restart-hydrated persistent work wakes it immediately. Automatic and manual sends share the existing serialized flush, immutable failed prefix, accepted-prefix acknowledgement, batch bounds, and persistence format; no second queue or transport path is created.
+
+Retryable network, `408`, and `5xx` failures retain the exact failed body and use capped equal-jitter backoff. Authentication (`401`/`403`), quota (`429`), validation (`400`/`422`), and other non-retryable responses pause automatic sends without dropping queued work. `recover_automatic_delivery` performs one explicit synchronous flush through the owned transport and resumes scheduling only after success. Calling `flush(transport)` directly provides the same explicit recovery boundary. `stop_automatic_delivery` joins the worker without draining or discarding work; a later manual flush remains available.
+
+`delivery_health` returns an immutable, JSON-serializable `LogBrew::DeliveryHealth` snapshot. Its fixed fields are lifecycle state, queued event/byte counts, dropped count, in-flight state, bounded outcome/failure/flush counters, pause reason, and current retry delay. It never contains event data, event IDs, API keys, endpoints, headers, response bodies, filesystem paths, process or thread IDs, exception messages, or server text.
+
+Automatic ownership is process-local. An inherited automatic client rejects capture, flush, purge, stop, and shutdown after `fork`; each child must create a fresh client, transport, and persistent queue owner. No signal handler, global fork hook, `at_exit`, or finalizer is installed. `shutdown` stops and joins the worker before its final drain, and a failed drain reopens the client with retryable failures scheduled or terminal failures paused. Application transport timeouts still bound how promptly an in-flight send can stop.
+
+## Sidekiq Tracing
+
+Sidekiq integration is explicit and optional. Sidekiq is not a dependency of the base gem. Create the LogBrew client and instrumentation in the process that owns the middleware, then register the client and server sides you use:
+
+```ruby
+require "logbrew"
+require "logbrew/sidekiq"
+require "sidekiq"
+
+transport = LogBrew::HttpTransport.new(timeout: 10)
+client = LogBrew::Client.create_automatic(
+  api_key: ENV.fetch("LOGBREW_SERVER_API_KEY"),
+  sdk_name: "checkout-worker",
+  sdk_version: "1.0.0",
+  transport: transport
+)
+sidekiq_tracing = LogBrew::Sidekiq::Instrumentation.create(
+  client: client,
+  max_retries: 25
+)
+
+Sidekiq.configure_client { |config| sidekiq_tracing.register_client(config) }
+Sidekiq.configure_server do |config|
+  sidekiq_tracing.register_client(config)
+  sidekiq_tracing.register_server(config)
+  config.on(:quiet) { sidekiq_tracing.quiet }
+  config.on(:shutdown) { sidekiq_tracing.shutdown }
+end
+```
+
+Registration is app-owned, idempotent, and reversible with `unregister_client` and `unregister_server`; the first instrumentation registered for each middleware class owns that entry. `disable` and `enable` provide reversible capture control. `quiet` stops new Sidekiq instrumentation while already queued LogBrew events remain under the existing delivery owner. `shutdown` is idempotent and delegates draining to the existing client; automatic clients use their owned transport, while manual clients must pass `transport:` when the instrumentation is created.
+
+The client middleware adds one bounded `logbrew` carrier containing only a version, W3C `traceparent`, and enqueue time. Valid retries keep that carrier without creating another enqueue span. The server middleware continues a valid carrier or starts a fresh trace when it is absent or malformed, returns the caller trace state after every result, and records bounded queue-wait and execution timing. Set `max_retries` to the same default retry limit used by your Sidekiq configuration; per-job integer or disabled retry settings are honored. Retryable failures keep only error spans, while the terminal escaped failure adds one deduplicated fixed-title issue and preserves the original exception.
+
+Sidekiq spans contain only fixed source, sampled state, bounded retry count, bounded queue-wait duration, execution duration, status, and real cancellation. The integration does not capture job arguments, payload fields, job identifiers, worker names, queue values, connection data, exception messages or stacks, baggage, or tracestate. Capture failures are advisory and never replace job execution or retry behavior. Create fresh clients and instrumentation after `fork`; inherited instances fail closed without changing jobs.
+
+## Persistent Worker Delivery
+
+Server workers that need restart recovery can opt into an app-owned persistent queue. Create the client after forking and give every worker its own normalized absolute directory:
+
+```ruby
+queue_path = ENV.fetch("LOGBREW_PERSISTENT_QUEUE_PATH")
+
+client = LogBrew::Client.create(
+  api_key: ENV.fetch("LOGBREW_SERVER_API_KEY"),
+  sdk_name: "checkout-worker",
+  sdk_version: "1.0.0",
+  persistent_queue_path: queue_path,
+  on_event_dropped: lambda do |notice|
+    warn "LogBrew delivery pressure: #{notice.reason} (#{notice.dropped_events} dropped)"
+  end
+)
+
+client.log("evt_job_started", Time.now.utc.iso8601, message: "job started", level: "info")
+client.shutdown(LogBrew::HttpTransport.new)
+```
+
+Persistence is disabled by default and adds no background thread, timer, or `at_exit` hook. Admission writes and syncs each validated event with an atomic same-directory rename. If that rename completes but directory sync cannot be confirmed, capture raises the content-free `persistence_commit_error`; the event remains pending and cannot be sent or purged until a later sync succeeds, and it is never reported as dropped. Restart reads the oldest records first, preserves the normal 1,000-event/4 MiB bounds, and keeps the same 100-event/256 KiB transport splitting. A server-accepted prefix is recorded before local compaction, so interrupted compaction does not replay it. A crash before that marker may replay a stable event ID; delivery is intentionally at-least-once, not exactly-once.
+
+The queue directory must be dedicated, owner-only, and used by one process. Symlinks, unexpected files, corrupt records, concurrent owners, and inherited pre-fork clients fail closed. Build each child client after fork with a unique path. Successful `shutdown` releases ownership; failed delivery remains restartable. Use `client.purge_pending_events` only when the application explicitly chooses to discard pending telemetry.
+
+Event files contain the same validated event JSON your application submitted, including message and metadata values. Protect the directory and do not put API keys or other sensitive values in telemetry. The SDK never adds the API key, endpoint, request headers, process ID, SDK request envelope, or queue path to stored records. Persistence failures before an event rename reject the new event with the content-free `persistence_failure` drop reason; they do not fall back to an in-memory-only event.
+
 ## Example Source
 
 The `examples` directory contains copyable snippets for creating a client, sending through `HttpTransport`, using the standard logger wrapper, attaching Rack middleware, and subscribing to Rails errors in your own Ruby app.
@@ -288,7 +586,7 @@ The `examples` directory contains copyable snippets for creating a client, sendi
 require "logbrew"
 
 client = LogBrew::Client.create(
-  api_key: "LOGBREW_API_KEY",
+  api_key: ENV.fetch("LOGBREW_SERVER_API_KEY"),
   sdk_name: "my-ruby-app",
   sdk_version: "1.0.0"
 )
@@ -310,13 +608,15 @@ The adapter respects Ruby logger levels and lazy block messages, maps `DEBUG`/`I
 
 ## Rack And Rails Middleware
 
-Use `LogBrew::RackMiddleware` when a Rails, Sinatra, or Rack app should capture request spans and unhandled app exceptions without adding a framework dependency to the SDK.
+Rails applications should use the automatic Rails quick start above. Use
+`LogBrew::RackMiddleware` directly only for Sinatra, plain Rack, or a Rails app
+that intentionally owns custom middleware wiring.
 
 ```ruby
 require "logbrew"
 
 client = LogBrew::Client.create(
-  api_key: "LOGBREW_API_KEY",
+  api_key: ENV.fetch("LOGBREW_SERVER_API_KEY"),
   sdk_name: "my-rails-app",
   sdk_version: "1.0.0"
 )
@@ -340,17 +640,26 @@ app = LogBrew::RackMiddleware.new(
 )
 ```
 
-The middleware records successful responses as span events, records unhandled app exceptions as issue plus error-span events, and re-raises app exceptions so Rails or Rack keeps normal response handling. It captures method, path without query text, status code, request id when present, primitive base metadata, exception type/message, and duration. Exception backtrace text is omitted unless `include_exception_backtrace: true` is set. Events queue by default; pass `transport:` plus `flush_on_response: true` when each response should flush.
+The manual middleware records successful responses as span events, records
+unhandled app exceptions as issue plus error-span events, and re-raises app
+exceptions so Rack keeps normal response handling. Its compatibility defaults
+retain path, request-ID, and exception-message capture. Set
+`include_exception_message: false` for type-only issues. Exception backtrace
+text is omitted unless `include_exception_backtrace: true` is set. Events queue
+by default; pass `transport:` plus `flush_on_response: true` when each response
+should flush.
 
 ## Rails Error Subscriber
 
-Use `LogBrew::RailsErrorSubscriber` when handled or manually reported Rails errors should queue LogBrew issue events through Rails' own error reporter.
+The automatic Rails integration already subscribes to handled Rails errors.
+Use `LogBrew::RailsErrorSubscriber` directly only when an application owns a
+custom Rails error-reporting lifecycle.
 
 ```ruby
 require "logbrew"
 
 client = LogBrew::Client.create(
-  api_key: "LOGBREW_API_KEY",
+  api_key: ENV.fetch("LOGBREW_SERVER_API_KEY"),
   sdk_name: "my-rails-app",
   sdk_version: "1.0.0"
 )
@@ -366,18 +675,29 @@ Rails.error.subscribe(
 )
 ```
 
-The subscriber implements `report(error, handled:, severity:, context:, source:, **options)`, captures handled state, severity, Rails source, primitive context values, primitive base metadata, and exception type/message, and omits exception backtrace text unless `include_exception_backtrace: true` is set. It queues by default; pass `transport:` plus `flush_on_report: true` when each report should flush. If you also use `LogBrew::RackMiddleware`, keep the subscriber focused on handled/manual reports so unhandled request exceptions are not captured twice.
+The manual subscriber implements
+`report(error, handled:, severity:, context:, source:, **options)`. Its
+compatibility default includes primitive context values and exception messages;
+set `include_exception_message: false` for type-only issues. Backtrace text is
+omitted unless `include_exception_backtrace: true` is set. If you also use the
+manual Rack middleware, keep this subscriber focused on handled reports so
+unhandled request exceptions are not captured twice.
 
 ## Behavior
 
 - `preview_json` returns the queued batch as pretty JSON.
-- `flush(transport)` sends queued events, retries retryable failures, and clears the queue only after a 2xx response.
+- `persistent_queue_path:` enables explicit owner-only, single-process restart recovery; `purge_pending_events` explicitly discards its pending prefix.
+- `Client.create_automatic(...)` opts an owned transport into one lazy interval/threshold worker; `delivery_health`, `recover_automatic_delivery`, and `stop_automatic_delivery` expose fixed process-local lifecycle control.
+- `LogBrew::Sidekiq::Instrumentation` explicitly installs optional client/server middleware with bounded W3C propagation, fixed telemetry, and app-owned quiet/shutdown hooks.
+- `flush(transport)` splits its queue snapshot into compact 100-event/256 KiB requests, freezes failed retry bytes, acknowledges only accepted prefixes, and leaves transport-time capture queued.
+- Queues default to 1,000 events and 4 MiB of compact serialized event data; `pending_event_bytes`, `dropped_events`, and `on_event_dropped` expose pressure locally. `TransportResponse#attempts` and `#batches` expose request work.
 - `metric(...)` queues explicit, application-owned metric events with name, kind, value, unit, temporality, and low-cardinality metadata validation.
 - `LogBrew::ProductTimeline` builds explicit, application-owned product action and network milestone timeline events with primitive metadata and query/hash-free routes.
 - `LogBrew::SupportTicketDraft.create` builds explicit, local-only support-ticket create payload drafts with redacted diagnostics and no backend route calls.
 - `LogBrew::HttpTransport` sends queued batches through Ruby's standard `Net::HTTP` with configurable endpoint, headers, timeout, and app-owned HTTP client support.
 - `LogBrew::RackMiddleware` captures Rack request spans and unhandled app exceptions without requiring Rails or Rack at runtime.
 - `LogBrew::RailsErrorSubscriber` captures handled/manual Rails error reports without requiring Rails at runtime.
+- `LogBrew::Rails` automatically installs privacy-bounded Rails request spans, handled-error issues, per-process delivery, health access, and idempotent shutdown when the canonical server key is configured.
 - `shutdown(transport)` flushes queued events and rejects later writes.
 - `LogBrew::RecordingTransport.always_accept` is useful when you want to inspect queued JSON before network delivery.
 - `LogBrew::SdkError` exposes stable `code` and `message` values for user-facing failure handling.

data/examples/Makefile

@@ -1,4 +1,4 @@
-.PHONY: help run run-readme-example run-real-user-smoke run-first-useful-telemetry run-http-trace-correlation
+.PHONY: help run run-readme-example run-real-user-smoke run-first-useful-telemetry run-http-trace-correlation run-persistent-worker-delivery run-automatic-delivery run-sidekiq-tracing
 
 help:
 	@printf '%s\n' 'run-readme-example -> make run-readme-example'
@@ -6,6 +6,9 @@ help:
 	@printf '%s\n' 'run-real-user-smoke -> make run-real-user-smoke'
 	@printf '%s\n' 'run-first-useful-telemetry -> make run-first-useful-telemetry'
 	@printf '%s\n' 'run-http-trace-correlation -> make run-http-trace-correlation'
+	@printf '%s\n' 'run-persistent-worker-delivery -> make run-persistent-worker-delivery'
+	@printf '%s\n' 'run-automatic-delivery -> make run-automatic-delivery'
+	@printf '%s\n' 'run-sidekiq-tracing -> make run-sidekiq-tracing'
 
 run: run-real-user-smoke
 
@@ -20,3 +23,12 @@ run-first-useful-telemetry:
 
 run-http-trace-correlation:
 	@ruby http_trace_correlation.rb
+
+run-persistent-worker-delivery:
+	@ruby persistent_worker_delivery.rb
+
+run-automatic-delivery:
+	@ruby automatic_delivery.rb
+
+run-sidekiq-tracing:
+	@ruby sidekiq_tracing.rb

data/examples/automatic_delivery.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+require "json"
+require "logbrew"
+
+transport = LogBrew::RecordingTransport.always_accept
+client = LogBrew::Client.create_automatic(
+  api_key: ENV.fetch("LOGBREW_SERVER_API_KEY", "local-example-key"),
+  sdk_name: "automatic-delivery-example",
+  sdk_version: "1.0.0",
+  transport: transport,
+  flush_interval: 1,
+  flush_threshold: 1
+)
+
+client.log(
+  "evt_automatic_example",
+  Time.now.utc.iso8601,
+  message: "automatic delivery example",
+  level: "info"
+)
+
+deadline = Process.clock_gettime(Process::CLOCK_MONOTONIC) + 2
+sleep(0.01) until client.pending_events.zero? || Process.clock_gettime(Process::CLOCK_MONOTONIC) >= deadline
+health = client.delivery_health.to_h
+response = client.shutdown
+
+puts JSON.generate(
+  "ok" => response.status_code == 204 && health.fetch("last_outcome") == "accepted",
+  "state" => client.delivery_health.state,
+  "sentBodies" => transport.sent_bodies.length
+)

data/examples/persistent_worker_delivery.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+require "json"
+require "logbrew"
+
+queue_path = ENV.fetch("LOGBREW_PERSISTENT_QUEUE_PATH")
+dropped = 0
+last_drop_reason = nil
+loaded_spec = Gem.loaded_specs["logbrew-sdk"]
+client = LogBrew::Client.create(
+  api_key: "LOGBREW_API_KEY",
+  sdk_name: "logbrew-ruby-persistent-worker",
+  sdk_version: loaded_spec ? loaded_spec.version.to_s : "0.1.0",
+  persistent_queue_path: queue_path,
+  on_event_dropped: lambda do |notice|
+    dropped = notice.dropped_events
+    last_drop_reason = notice.reason
+  end
+)
+
+client.release("evt_worker_release", "2026-07-13T18:00:00Z", version: "2.0.0")
+client.environment("evt_worker_environment", "2026-07-13T18:00:01Z", name: "production")
+client.log("evt_worker_started", "2026-07-13T18:00:02Z", message: "worker started", level: "info")
+
+response = client.shutdown(LogBrew::RecordingTransport.always_accept)
+puts JSON.generate(
+  ok: response.status_code == 202,
+  status: response.status_code,
+  attempts: response.attempts,
+  batches: response.batches,
+  dropped: dropped,
+  lastDropReason: last_drop_reason
+)

data/examples/sidekiq_tracing.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+require "logbrew"
+require "logbrew/sidekiq"
+require "sidekiq"
+
+transport = LogBrew::HttpTransport.new(timeout: 10)
+client = LogBrew::Client.create_automatic(
+  api_key: ENV.fetch("LOGBREW_SERVER_API_KEY"),
+  sdk_name: "checkout-worker",
+  sdk_version: "1.0.0",
+  transport: transport
+)
+instrumentation = LogBrew::Sidekiq::Instrumentation.create(client: client, max_retries: 25)
+
+Sidekiq.configure_client { |config| instrumentation.register_client(config) }
+Sidekiq.configure_server do |config|
+  instrumentation.register_client(config)
+  instrumentation.register_server(config)
+  config.on(:quiet) { instrumentation.quiet }
+  config.on(:shutdown) { instrumentation.shutdown }
+end