logbrew-sdk 0.1.2 → 0.1.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e9f3c896d1d43ab4b324623e3a121cbc675fa9780fcb157f01d2aa52c54d07b4
-  data.tar.gz: ef86c767dbcf0b73903f37aa5492f3a54fda28318b838725155229ed95cee368
+  metadata.gz: d461f01e0341b81cbdd17c4903f50726cd7966f26e50d7fd6fbef97a8fbf83dc
+  data.tar.gz: 42efb0bf7c1312d5c0bb3337885b00de0921e043952e8c57d6571391110e2c7d
 SHA512:
-  metadata.gz: 90883b0323ec61e83561a09599cbcd3e1219fe25ad8ecbbd683ea10bb49f45e44d41aa66cfce8ea1818dc6858218c79dce654a5c68578a7f7ef82b80b209951f
-  data.tar.gz: c6af849cc5d6e96cfa8e8bfa2dedc536dd82d64ba9007a9faa9bbb13b5f7bed4b63f9e32661c879199ebf0c3b94f00ecbd6e74d3a21919fcee40e9b0f6f8942f
+  metadata.gz: d7f55a9b0a8f8813762a2f497382a78c6678d22972ffe8bd0512359c53a8927491ea4fd7fc5bc92b40aaefab156cd8a57e27a090eedbd012c4b786360d1c6514
+  data.tar.gz: bc21387db2691a355300645a333d4f57f878815415e6b52d1d56d7f38a5bca6be4eb27a4e205ba65ce777d9d05b04e018feeacb752a0ba5df7db5f1ecc83fab4

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,109 @@ 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.4"
+```
+
+```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 typed
+exception issues. Escaped request failures include exception identity,
+`rails.middleware` with `handled: false`, and up to 32 newest-first sanitized
+frames. Handled Rails reports use `rails.error_reporter` with `handled: true`.
+It does not record concrete request paths, query strings, request or response
+bodies, arbitrary headers, authorization values, cookies, user IDs, exception
+messages, raw backtrace text, source snippets, locals, arguments, or absolute
+paths. Exception messages and raw backtrace text 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 raw exception backtrace text; sanitized structured frames are always captured |
+
+`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 +140,76 @@ response = client.shutdown(LogBrew::RecordingTransport.always_accept)
 warn response.status_code
 ```
 
+## Shared Telemetry Context
+
+Use one versioned context when a human or coding agent must correlate releases,
+issues, logs, spans, metrics, and product actions without reverse-engineering a
+flat metadata map:
+
+```ruby
+resource = LogBrew::TelemetryResource.create
+  .with_service(name: "checkout-api", version: "1.4.0")
+  .with_deployment(environment: "production", release: "checkout@1.4.0")
+  .with_framework(name: "rails", version: "8.1.3")
+  .with_application(name: "checkout", version: "1.4.0", build: "140")
+  .build
+client_context = LogBrew::TelemetryContext.create
+  .with_resource(resource)
+  .with_tag("region", "eu")
+  .build
+
+client = LogBrew::Client.create(
+  api_key: ENV.fetch("LOGBREW_SERVER_API_KEY"),
+  sdk_name: "checkout-api",
+  sdk_version: "1.4.0",
+  context: client_context
+)
+
+request_context = LogBrew::TelemetryContext.create
+  .with_session(id: "session_checkout_123")
+  .with_subject(id: "subject_checkout_123", kind: "user")
+  .with_tags("journey" => "checkout", "surface" => "payment")
+  .build
+
+LogBrew::Telemetry.with_context(request_context) do
+  client.log(
+    "evt_checkout_started",
+    Time.now.utc.iso8601,
+    message: "checkout started",
+    level: "info"
+  )
+end
+```
+
+Client context is merged into all seven signal types. Resource sections and
+tags merge field by field; event context replaces trace, session, or subject
+sections and wins on conflicting resource fields or tags. Pass a built
+`TelemetryContext` as an event's `context:` value for an explicit override.
+`LogBrew::Telemetry.with_context` provides a fiber/thread-local request or job
+scope and returns to the exact prior scope even when application work raises.
+When `LogBrew::Trace.current` is active, its W3C trace and span IDs are added to
+the typed context on every signal. Explicit event context remains the final
+override.
+
+The client adds only Ruby engine/version, operating-system family/release, and
+architecture beneath explicit context by default. Set
+`capture_runtime_context: false` to disable those defaults without removing
+explicit context. The automatic Rails adapter also promotes its already
+validated service, environment, release, and Rails version configuration into
+the corresponding resource sections. Automatic context never reads host names,
+process IDs, commands or arguments, environment variables, local account names,
+working directories, files, network addresses, cloud metadata, memory, or CPU
+values.
+
+Context is detached and validated before queue admission. Strings, IDs, trace
+identifiers, resource sections, and tags follow the shared event schema; tags
+are sorted and capped at 32. Session and subject IDs are application-owned,
+opaque correlation values. Never put names, email addresses, authentication
+material, network addresses, or other direct personal data in them. Use
+`TelemetryContext.from_hash(...)` or `TelemetryResource.from_hash(...)` only
+when adapting an already schema-shaped object; the builders are clearer for
+new code.
+
 ## Serialized Worker Lifecycle
 
 Use `LogBrew::WorkerLifecycle` when a prefork or long-running worker processes
@@ -50,7 +217,7 @@ one work item at a time and needs an explicit telemetry boundary:
 
 ```ruby
 client = LogBrew::Client.create(
-  api_key: "LOGBREW_API_KEY",
+  api_key: ENV.fetch("LOGBREW_SERVER_API_KEY"),
   sdk_name: "checkout-worker",
   sdk_version: "1.0.0"
 )
@@ -95,7 +262,9 @@ 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:
+For a service request, combine release, environment, log, product action,
+network milestone, metric, and span events around one typed request context and
+one shared W3C trace:
 
 ```ruby
 incoming = "00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01"
@@ -103,51 +272,66 @@ trace = LogBrew::Traceparent.parse(incoming)
 child_span_id = "b7ad6b7169203331"
 route_template = "/checkout/:cart_id"
 session_id = "sess_checkout_123"
-
-client.log(
-  "evt_log_checkout_started",
-  "2026-06-02T10:00:02Z",
-  message: "checkout request started",
-  level: "info",
-  logger: "checkout",
-  metadata: { traceId: trace.trace_id, sessionId: session_id, routeTemplate: route_template }
-)
-client.action(
-  "evt_action_checkout_submit",
-  "2026-06-02T10:00:03Z",
-  LogBrew::ProductTimeline.product_action(
-    name: "checkout.submit",
-    route_template: "/checkout/:cart_id",
-    session_id: session_id,
-    trace_id: trace.trace_id,
-    screen: "Checkout",
-    funnel: "checkout",
-    step: "submit"
-  )
-)
-client.metric(
-  "evt_metric_http_server_duration",
-  "2026-06-02T10:00:05Z",
-  name: "http.server.duration",
-  kind: "histogram",
-  value: 183.4,
-  unit: "ms",
-  temporality: "delta",
-  metadata: { method: "POST", routeTemplate: route_template, statusCode: 202, traceId: trace.trace_id }
+request_context = LogBrew::TelemetryContext.create
+  .with_session(id: session_id)
+  .with_subject(id: "subject_checkout_123", kind: "user")
+  .with_tag("journey", "checkout")
+  .build
+active_trace = LogBrew::Trace.create(
+  trace_id: trace.trace_id,
+  span_id: child_span_id,
+  parent_span_id: trace.parent_span_id,
+  trace_flags: trace.trace_flags
 )
-client.span(
-  "evt_span_checkout_request",
-  "2026-06-02T10:00:06Z",
-  LogBrew::Traceparent.span_attributes_from_traceparent(
-    trace,
-    LogBrew::TraceparentSpanInput.new(
-      name: "POST /checkout/:cart_id",
-      span_id: child_span_id,
-      duration_ms: 183.4,
-      metadata: { sampled: trace.sampled, routeTemplate: route_template, sessionId: session_id }
+
+LogBrew::Telemetry.with_context(request_context) do
+  LogBrew::Trace.with_context(active_trace) do
+    client.log(
+      "evt_log_checkout_started",
+      "2026-06-02T10:00:02Z",
+      message: "checkout request started",
+      level: "info",
+      logger: "checkout",
+      metadata: { routeTemplate: route_template }
     )
-  )
-)
+    client.action(
+      "evt_action_checkout_submit",
+      "2026-06-02T10:00:03Z",
+      LogBrew::ProductTimeline.product_action(
+        name: "checkout.submit",
+        route_template: route_template,
+        session_id: session_id,
+        trace_id: trace.trace_id,
+        screen: "Checkout",
+        funnel: "checkout",
+        step: "submit"
+      )
+    )
+    client.metric(
+      "evt_metric_http_server_duration",
+      "2026-06-02T10:00:05Z",
+      name: "http.server.duration",
+      kind: "histogram",
+      value: 183.4,
+      unit: "ms",
+      temporality: "delta",
+      metadata: { method: "POST", routeTemplate: route_template, statusCode: 202 }
+    )
+    client.span(
+      "evt_span_checkout_request",
+      "2026-06-02T10:00:06Z",
+      LogBrew::Traceparent.span_attributes_from_traceparent(
+        trace,
+        LogBrew::TraceparentSpanInput.new(
+          name: "POST /checkout/:cart_id",
+          span_id: child_span_id,
+          duration_ms: 183.4,
+          metadata: { sampled: trace.sampled, routeTemplate: route_template }
+        )
+      )
+    )
+  end
+end
 
 outgoing_headers = LogBrew::Traceparent.create_headers(
   trace_id: trace.trace_id,
@@ -156,7 +340,11 @@ outgoing_headers = LogBrew::Traceparent.create_headers(
 )
 ```
 
-The packaged `examples/first_useful_telemetry.rb` file shows the full flow, including release, environment, and network milestone events. Route templates stay query-free, metadata is primitive-only, and the SDK does not capture request bodies or arbitrary transport metadata.
+The packaged `examples/first_useful_telemetry.rb` file shows the full flow,
+including client resource/deployment context, release, environment, opaque
+subject/session correlation, and a network milestone. Route templates stay
+query-free, metadata is primitive-only, and the SDK does not capture request
+bodies or arbitrary transport metadata.
 
 ## W3C Trace Context
 
@@ -250,6 +438,63 @@ Both adapters are literal pass-throughs when `LogBrew::Trace.current` is absent.
 
 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.
 
+## Typed Issue Diagnostics
+
+Use `LogBrew::IssueDiagnostics` when an application wants issue evidence that a
+human or coding agent can understand without parsing a flattened metadata map:
+
+```ruby
+breadcrumbs = [
+  LogBrew::IssueDiagnostics.breadcrumb(
+    timestamp: "2026-08-02T10:14:58.125Z",
+    category: "checkout.navigation",
+    type: "navigation",
+    message: "User reached payment review",
+    data: { step: "payment" }
+  ),
+  LogBrew::IssueDiagnostics.breadcrumb(
+    timestamp: "2026-08-02T10:14:59Z",
+    category: "checkout.request",
+    level: "warn",
+    data: { method: "POST", statusCode: 503 }
+  )
+]
+
+begin
+  checkout.call
+rescue RuntimeError => error
+  client.issue(
+    "evt_checkout_failure",
+    Time.now.utc.iso8601,
+    LogBrew::IssueDiagnostics.from_exception(
+      error,
+      message: "Checkout could not be completed.",
+      mechanism_type: "ruby.exception",
+      handled: true,
+      context: request_context,
+      metadata: { routeTemplate: "/checkout/:cart_id" },
+      breadcrumbs: breadcrumbs
+    )
+  )
+end
+```
+
+The typed payload exposes exception type, mechanism and handled state, up to 32
+newest-first stack frames, and up to 64 oldest-to-newest breadcrumbs. Generated
+frames contain only basename, positive coordinates, and bounded function
+identity. Explicit frames can also carry module, `inApp`, and debug ID. A
+breadcrumb accepts a stable category/type, normalized level, bounded message,
+and at most eight flat finite primitive data values. Set
+`breadcrumbs_truncated: true` when the supplied list omits earlier history.
+
+`from_exception` deliberately omits exception text unless `message:` is
+provided. Pass `context:` to correlate the issue with the same typed resource,
+trace, session, opaque subject, and tags as its surrounding signals. Automatic
+and manual structured frame projection never captures raw backtrace strings,
+source code, locals, arguments, or absolute paths. The raw Rails/Rack backtrace
+option is separate and remains off by default. Run
+`make -C examples run-issue-diagnostics` for a complete inspectable payload.
+
 ## Metrics
 
 Use `metric` for explicit, application-owned measurements. LogBrew validates the metric name, kind, value, unit, temporality, and optional metadata before queueing the event:
@@ -259,6 +504,7 @@ client.metric(
   "evt_metric_queue_depth",
   "2026-06-02T10:00:06Z",
   name: "queue.depth",
+  description: "Number of items waiting in the checkout queue.",
   kind: "gauge",
   value: 42,
   unit: "{items}",
@@ -267,7 +513,7 @@ client.metric(
 )
 ```
 
-Supported metric kinds are `counter`, `gauge`, and `histogram`. Counters and histograms require `delta` or `cumulative` temporality and non-negative values; gauges require `instant` temporality and may be negative. Keep metadata low-cardinality and primitive. This SDK does not automatically collect Ruby runtime, Rack, Rails, or database metrics yet.
+Supported metric kinds are `counter`, `gauge`, and `histogram`. Counters and histograms require `delta` or `cumulative` temporality and non-negative values; gauges require `instant` temporality and may be negative. An optional `description` gives people and investigation tools the stable meaning of the measurement. Keep it generic, single-line, between 1 and 1,024 Unicode scalar values, and free of identifiers, personal data, or changing values. It is not a query dimension. Keep metadata low-cardinality and primitive. This SDK does not automatically collect Ruby runtime, Rack, Rails, or database metrics yet.
 
 ## Product And Network Timelines
 
@@ -339,7 +585,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"
 )
@@ -364,7 +610,7 @@ The client bounds queued telemetry and each transport request independently. Que
 ```ruby
 dropped = 0
 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",
   max_queue_size: 1_000,
@@ -393,7 +639,7 @@ Applications that own their transport can opt into one lazy delivery worker. Man
 ```ruby
 transport = LogBrew::HttpTransport.new(timeout: 10)
 client = LogBrew::Client.create_automatic(
-  api_key: ENV.fetch("LOGBREW_API_KEY"),
+  api_key: ENV.fetch("LOGBREW_SERVER_API_KEY"),
   sdk_name: "checkout-worker",
   sdk_version: "1.0.0",
   transport: transport,
@@ -428,7 +674,7 @@ require "sidekiq"
 
 transport = LogBrew::HttpTransport.new(timeout: 10)
 client = LogBrew::Client.create_automatic(
-  api_key: ENV.fetch("LOGBREW_API_KEY"),
+  api_key: ENV.fetch("LOGBREW_SERVER_API_KEY"),
   sdk_name: "checkout-worker",
   sdk_version: "1.0.0",
   transport: transport
@@ -461,7 +707,7 @@ Server workers that need restart recovery can opt into an app-owned persistent q
 queue_path = ENV.fetch("LOGBREW_PERSISTENT_QUEUE_PATH")
 
 client = LogBrew::Client.create(
-  api_key: ENV.fetch("LOGBREW_API_KEY"),
+  api_key: ENV.fetch("LOGBREW_SERVER_API_KEY"),
   sdk_name: "checkout-worker",
   sdk_version: "1.0.0",
   persistent_queue_path: queue_path,
@@ -482,7 +728,10 @@ Event files contain the same validated event JSON your application submitted, in
 
 ## 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.
+The `examples` directory contains copyable snippets for creating a client,
+building typed issue diagnostics, sending through `HttpTransport`, using the
+standard logger wrapper, attaching Rack middleware, and subscribing to Rails
+errors in your own Ruby app.
 
 ## Standard Logger
 
@@ -492,7 +741,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"
 )
@@ -514,13 +763,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"
 )
@@ -544,17 +795,27 @@ 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 typed issue plus error-span events, and re-raises
+the exact app exception so Rack keeps normal response handling. Escaped issues
+use `rack.middleware`, `handled: false`, and bounded structured frames. Its
+compatibility defaults retain path, request-ID, and exception-message capture.
+Set `include_exception_message: false` for type-only issues. Raw backtrace text
+is omitted unless `include_exception_backtrace: true` is set; sanitized
+structured frames remain available either way. 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"
 )
@@ -570,7 +831,15 @@ 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)`. Exception
+reports include typed identity, `rails.error_reporter`, the supplied handled
+state, and bounded structured frames. Its compatibility default includes
+primitive context values and exception messages; set
+`include_exception_message: false` for type-only issues. Raw 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
 
@@ -583,9 +852,11 @@ The subscriber implements `report(error, handled:, severity:, context:, source:,
 - `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::IssueDiagnostics` builds typed exception identity, mechanism/handled state, basename-only structured frames, and bounded ordered breadcrumbs without raw exception internals.
 - `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,10 +1,11 @@
-.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
+.PHONY: help run run-readme-example run-real-user-smoke run-first-useful-telemetry run-issue-diagnostics 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'
 	@printf '%s\n' 'run (real-user-smoke) -> make run'
 	@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-issue-diagnostics -> make run-issue-diagnostics'
 	@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'
@@ -21,6 +22,9 @@ run-real-user-smoke:
 run-first-useful-telemetry:
 	@ruby first_useful_telemetry.rb
 
+run-issue-diagnostics:
+	@ruby issue_diagnostics.rb
+
 run-http-trace-correlation:
 	@ruby http_trace_correlation.rb
 

data/examples/automatic_delivery.rb

@@ -5,7 +5,7 @@ require "logbrew"
 
 transport = LogBrew::RecordingTransport.always_accept
 client = LogBrew::Client.create_automatic(
-  api_key: ENV.fetch("LOGBREW_API_KEY", "local-example-key"),
+  api_key: ENV.fetch("LOGBREW_SERVER_API_KEY", "local-example-key"),
   sdk_name: "automatic-delivery-example",
   sdk_version: "1.0.0",
   transport: transport,