logbrew-sdk 0.1.2 → 0.1.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e9f3c896d1d43ab4b324623e3a121cbc675fa9780fcb157f01d2aa52c54d07b4
-  data.tar.gz: ef86c767dbcf0b73903f37aa5492f3a54fda28318b838725155229ed95cee368
+  metadata.gz: 233087ef98eb35d7df84720956a89dfbf66368ac55269900a38491192c7a67a3
+  data.tar.gz: 1720b83bf8dcc562771936091f0196996415005e6a5ea254ca4e0a803e3ea1ac
 SHA512:
-  metadata.gz: 90883b0323ec61e83561a09599cbcd3e1219fe25ad8ecbbd683ea10bb49f45e44d41aa66cfce8ea1818dc6858218c79dce654a5c68578a7f7ef82b80b209951f
-  data.tar.gz: c6af849cc5d6e96cfa8e8bfa2dedc536dd82d64ba9007a9faa9bbb13b5f7bed4b63f9e32661c879199ebf0c3b94f00ecbd6e74d3a21919fcee40e9b0f6f8942f
+  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"
 )
@@ -50,7 +144,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"
 )
@@ -339,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"
 )
@@ -364,7 +458,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 +487,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 +522,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 +555,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,
@@ -492,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"
 )
@@ -514,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"
 )
@@ -544,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"
 )
@@ -570,7 +675,13 @@ 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
 
@@ -586,6 +697,7 @@ The subscriber implements `report(error, handled:, severity:, context:, source:,
 - `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/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,

data/examples/sidekiq_tracing.rb

@@ -6,7 +6,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

data/lib/logbrew/rails.rb

@@ -0,0 +1,105 @@
+# frozen_string_literal: true
+
+require "logbrew"
+require "rails/railtie"
+require_relative "rails_integration"
+
+module LogBrew
+  # Process-safe Rails integration installed by RailsRailtie.
+  module Rails
+    class << self
+      attr_reader :runtime
+
+      def install(application:, environment: ENV)
+        @installation_mutex ||= Mutex.new
+        @installation_mutex.synchronize do
+          return @runtime unless @runtime.nil?
+
+          configuration = Configuration.from_environment(
+            environment,
+            application_name: application_name(application),
+            rails_environment: ::Rails.env.to_s,
+            rails_version: ::Rails.version.to_s
+          )
+          @runtime = Runtime.new(
+            configuration,
+            on_error: ->(stage, error) { log_capture_failure(application, stage, error) }
+          )
+          register_shutdown
+          @runtime
+        end
+      end
+
+      def client
+        @runtime&.client
+      end
+
+      def delivery_health
+        @runtime&.delivery_health
+      end
+
+      def shutdown
+        @runtime&.shutdown
+      end
+
+      private
+
+      def application_name(application)
+        application_class = application.class
+        if application_class.respond_to?(:module_parent_name)
+          name = application_class.module_parent_name.to_s
+          return name unless name.empty?
+        end
+
+        name = application_class.name.to_s.sub(/::Application\z/, "")
+        name.empty? ? "rails" : name
+      end
+
+      def register_shutdown
+        return if @shutdown_registered
+
+        at_exit { shutdown }
+        @shutdown_registered = true
+      end
+
+      def log_capture_failure(application, stage, error)
+        logger = application.respond_to?(:logger) ? application.logger : nil
+        logger ||= ::Rails.logger if ::Rails.respond_to?(:logger)
+        return unless logger.respond_to?(:warn)
+
+        logger.warn("LogBrew Rails #{stage} failed (#{error.class.name}); application behavior was preserved")
+      rescue StandardError
+        nil
+      end
+    end
+  end
+
+  class RailsRailtie < ::Rails::Railtie
+    initializer "logbrew.install", after: :load_config_initializers do |application|
+      runtime = LogBrew::Rails.install(application: application)
+      middleware = application.config.middleware
+      if defined?(::ActionDispatch::ShowExceptions)
+        middleware.insert_after(
+          ::ActionDispatch::ShowExceptions,
+          LogBrew::Rails::RequestMiddleware,
+          runtime: runtime
+        )
+      else
+        middleware.use(LogBrew::Rails::RequestMiddleware, runtime: runtime)
+      end
+    end
+
+    config.after_initialize do |application|
+      runtime = LogBrew::Rails.runtime
+      next if runtime.nil? || !runtime.configuration.enabled?
+
+      reporter = LogBrew::Rails::ErrorReporter.new(runtime)
+      if ::Rails.respond_to?(:error) && ::Rails.error.respond_to?(:subscribe)
+        ::Rails.error.subscribe(reporter)
+      elsif application.respond_to?(:executor) && application.executor.respond_to?(:error_reporter)
+        error_reporter = application.executor.error_reporter
+        error_reporter.subscribe(reporter) if error_reporter.respond_to?(:subscribe)
+      end
+    end
+  end
+end

data/lib/logbrew/rails_integration.rb

@@ -0,0 +1,622 @@
+# frozen_string_literal: true
+
+require_relative "../logbrew" unless defined?(LogBrew::Client)
+require "uri"
+
+module LogBrew
+  module Rails
+    # Immutable, environment-derived settings for the automatic Rails adapter.
+    class Configuration
+      DEFAULT_ENDPOINT = LogBrew::HttpTransport::DEFAULT_ENDPOINT
+      DEFAULT_REQUEST_TIMEOUT_MS = 10_000
+      DEFAULT_FLUSH_INTERVAL_MS = 5_000
+      DEFAULT_FLUSH_THRESHOLD = 100
+      MAX_LABEL_BYTES = 255
+      MAX_ENDPOINT_BYTES = 2_048
+      LOOPBACK_HOSTS = %w[localhost 127.0.0.1 ::1 [::1]].freeze
+
+      attr_reader(
+        :api_key,
+        :service_name,
+        :app_environment,
+        :rails_version,
+        :release,
+        :endpoint,
+        :request_timeout,
+        :flush_interval,
+        :flush_threshold
+      )
+
+      def self.from_environment(environment, application_name:, rails_environment:, rails_version:)
+        unless environment.respond_to?(:[]) && environment.respond_to?(:key?)
+          raise SdkError.new("configuration_error", "Rails environment must provide key lookup")
+        end
+
+        enabled_setting = boolean_value(environment, "LOGBREW_ENABLED", nil)
+        return disabled(application_name, rails_environment, rails_version) if enabled_setting == false
+
+        canonical_key = server_key_value(environment["LOGBREW_SERVER_API_KEY"])
+        if canonical_key.nil?
+          legacy_present = %w[LOGBREW_API_KEY LOGBREW_INGEST_KEY].any? do |name|
+            !optional_text(environment[name]).nil?
+          end
+          if enabled_setting == true || legacy_present || environment.key?("LOGBREW_SERVER_API_KEY")
+            raise SdkError.new(
+              "configuration_error",
+              "set LOGBREW_SERVER_API_KEY to a non-empty server API key, or set LOGBREW_ENABLED=false"
+            )
+          end
+          return disabled(application_name, rails_environment, rails_version)
+        end
+
+        new(
+          enabled: true,
+          api_key: canonical_key,
+          service_name: bounded_label(
+            optional_text(environment["LOGBREW_SERVICE_NAME"]) || application_name,
+            "LOGBREW_SERVICE_NAME"
+          ),
+          app_environment: bounded_label(
+            optional_text(environment["LOGBREW_ENVIRONMENT"]) || rails_environment,
+            "LOGBREW_ENVIRONMENT"
+          ),
+          rails_version: bounded_label(rails_version, "Rails version"),
+          release: optional_bounded_label(environment["LOGBREW_RELEASE"], "LOGBREW_RELEASE"),
+          endpoint: endpoint_value(environment["LOGBREW_ENDPOINT"]),
+          request_timeout: integer_value(
+            environment,
+            "LOGBREW_REQUEST_TIMEOUT_MS",
+            DEFAULT_REQUEST_TIMEOUT_MS,
+            1,
+            600_000
+          ) / 1_000.0,
+          flush_interval: integer_value(
+            environment,
+            "LOGBREW_FLUSH_INTERVAL_MS",
+            DEFAULT_FLUSH_INTERVAL_MS,
+            10,
+            3_600_000
+          ) / 1_000.0,
+          flush_threshold: integer_value(
+            environment,
+            "LOGBREW_FLUSH_THRESHOLD",
+            DEFAULT_FLUSH_THRESHOLD,
+            1,
+            1_000
+          ),
+          capture_exception_messages: boolean_value(
+            environment,
+            "LOGBREW_CAPTURE_EXCEPTION_MESSAGES",
+            false
+          ),
+          include_exception_backtrace: boolean_value(
+            environment,
+            "LOGBREW_INCLUDE_EXCEPTION_BACKTRACE",
+            false
+          )
+        )
+      end
+
+      def self.disabled(application_name, rails_environment, rails_version)
+        new(
+          enabled: false,
+          api_key: nil,
+          service_name: bounded_label(application_name, "Rails application name"),
+          app_environment: bounded_label(rails_environment, "Rails environment"),
+          rails_version: bounded_label(rails_version, "Rails version"),
+          release: nil,
+          endpoint: DEFAULT_ENDPOINT,
+          request_timeout: DEFAULT_REQUEST_TIMEOUT_MS / 1_000.0,
+          flush_interval: DEFAULT_FLUSH_INTERVAL_MS / 1_000.0,
+          flush_threshold: DEFAULT_FLUSH_THRESHOLD,
+          capture_exception_messages: false,
+          include_exception_backtrace: false
+        )
+      end
+
+      def self.optional_text(value)
+        return nil if value.nil?
+
+        text = value.to_s.strip
+        text.empty? ? nil : text
+      end
+      private_class_method :optional_text
+
+      def self.server_key_value(value)
+        text = optional_text(value)
+        return nil if text.nil?
+        if text.bytesize > 4_096 || !text.valid_encoding?
+          raise SdkError.new("configuration_error", "LOGBREW_SERVER_API_KEY is invalid")
+        end
+
+        text
+      end
+      private_class_method :server_key_value
+
+      def self.bounded_label(value, label)
+        text = optional_text(value)
+        raise SdkError.new("configuration_error", "#{label} must be non-empty") if text.nil?
+        if text.bytesize > MAX_LABEL_BYTES || !text.valid_encoding? || text.match?(/[[:cntrl:]]/)
+          raise SdkError.new("configuration_error", "#{label} must be at most #{MAX_LABEL_BYTES} bytes")
+        end
+
+        text.freeze
+      end
+      private_class_method :bounded_label
+
+      def self.optional_bounded_label(value, label)
+        text = optional_text(value)
+        return nil if text.nil?
+
+        bounded_label(text, label)
+      end
+      private_class_method :optional_bounded_label
+
+      def self.boolean_value(environment, name, default)
+        value = optional_text(environment[name])
+        return default if value.nil? && !environment.key?(name)
+
+        case value&.downcase
+        when "true", "1", "yes", "on" then true
+        when "false", "0", "no", "off" then false
+        else
+          raise SdkError.new("configuration_error", "#{name} must be true or false")
+        end
+      end
+      private_class_method :boolean_value
+
+      def self.integer_value(environment, name, default, minimum, maximum)
+        text = optional_text(environment[name])
+        return default if text.nil? && !environment.key?(name)
+
+        value = Integer(text, 10)
+        return value if value >= minimum && value <= maximum
+
+        raise ArgumentError
+      rescue ArgumentError, TypeError
+        raise SdkError.new(
+          "configuration_error",
+          "#{name} must be an integer between #{minimum} and #{maximum}"
+        )
+      end
+      private_class_method :integer_value
+
+      def self.endpoint_value(value)
+        text = optional_text(value) || DEFAULT_ENDPOINT
+        if text.bytesize > MAX_ENDPOINT_BYTES
+          raise SdkError.new("configuration_error", "LOGBREW_ENDPOINT is too long")
+        end
+
+        uri = URI.parse(text)
+        valid_http = uri.is_a?(URI::HTTP) && !uri.host.to_s.empty?
+        safe_scheme = uri.scheme == "https" || (
+          uri.scheme == "http" && LOOPBACK_HOSTS.include?(uri.host.to_s.downcase)
+        )
+        if !valid_http || !safe_scheme || !uri.userinfo.nil? || !uri.fragment.nil?
+          raise SdkError.new(
+            "configuration_error",
+            "LOGBREW_ENDPOINT must use https, or http on localhost, without embedded user info or a fragment"
+          )
+        end
+
+        uri.to_s.freeze
+      rescue URI::InvalidURIError
+        raise SdkError.new("configuration_error", "LOGBREW_ENDPOINT must be a valid HTTP URL")
+      end
+      private_class_method :endpoint_value
+
+      def initialize(
+        enabled:,
+        api_key:,
+        service_name:,
+        app_environment:,
+        rails_version:,
+        release:,
+        endpoint:,
+        request_timeout:,
+        flush_interval:,
+        flush_threshold:,
+        capture_exception_messages:,
+        include_exception_backtrace:
+      )
+        @enabled = enabled
+        @api_key = api_key&.dup&.freeze
+        @service_name = service_name
+        @app_environment = app_environment
+        @rails_version = rails_version
+        @release = release
+        @endpoint = endpoint
+        @request_timeout = request_timeout
+        @flush_interval = flush_interval
+        @flush_threshold = flush_threshold
+        @capture_exception_messages = capture_exception_messages
+        @include_exception_backtrace = include_exception_backtrace
+        freeze
+      end
+
+      def enabled?
+        @enabled
+      end
+
+      def capture_exception_messages?
+        @capture_exception_messages
+      end
+
+      def include_exception_backtrace?
+        @include_exception_backtrace
+      end
+    end
+
+    # Owns one lazy automatic-delivery client per operating-system process.
+    class Runtime
+      attr_reader :configuration
+
+      def initialize(
+        configuration,
+        transport_factory: nil,
+        client_factory: nil,
+        timestamp_provider: nil,
+        process_id_provider: nil,
+        on_error: nil
+      )
+        unless configuration.is_a?(Configuration)
+          raise SdkError.new("configuration_error", "Rails runtime requires a Rails configuration")
+        end
+
+        @configuration = configuration
+        @transport_factory = transport_factory || method(:build_transport)
+        @client_factory = client_factory || method(:build_client)
+        @timestamp_provider = timestamp_provider || -> { Time.now.utc }
+        @process_id_provider = process_id_provider || -> { Process.pid }
+        @on_error = on_error
+        @mutex = Mutex.new
+        @state_process_id = @process_id_provider.call
+        @client = nil
+        @shutdown_response = nil
+      end
+
+      def client
+        return nil unless @configuration.enabled?
+
+        prepare_process_state
+        @mutex.synchronize do
+          return nil unless @shutdown_response.nil?
+
+          @client ||= create_client
+        end
+      rescue StandardError => error
+        report_error("client_initialization", error)
+        nil
+      end
+
+      def delivery_health
+        active_client = client
+        active_client&.delivery_health
+      rescue StandardError => error
+        report_error("delivery_health", error)
+        nil
+      end
+
+      def shutdown
+        return nil unless @configuration.enabled?
+
+        prepare_process_state
+        @mutex.synchronize do
+          return @shutdown_response unless @shutdown_response.nil?
+          return nil if @client.nil?
+
+          @shutdown_response = @client.shutdown
+        end
+      rescue StandardError => error
+        report_error("shutdown", error)
+        nil
+      end
+
+      def report_error(stage, error)
+        return unless @on_error.respond_to?(:call)
+
+        @on_error.call(stage.to_s, error)
+      rescue StandardError
+        nil
+      end
+
+      private
+
+      def prepare_process_state
+        process_id = @process_id_provider.call
+        return if @state_process_id == process_id
+
+        @mutex = Mutex.new
+        @client = nil
+        @shutdown_response = nil
+        @state_process_id = process_id
+      end
+
+      def create_client
+        transport = @transport_factory.call(@configuration)
+        created = @client_factory.call(@configuration, transport)
+        record_process_context(created)
+        created
+      end
+
+      def build_transport(configuration)
+        LogBrew::HttpTransport.new(
+          endpoint: configuration.endpoint,
+          timeout: configuration.request_timeout
+        )
+      end
+
+      def build_client(configuration, transport)
+        LogBrew::Client.create_automatic(
+          api_key: configuration.api_key,
+          sdk_name: "logbrew-ruby-rails",
+          sdk_version: LogBrew::VERSION,
+          transport: transport,
+          flush_interval: configuration.flush_interval,
+          flush_threshold: configuration.flush_threshold
+        )
+      end
+
+      def record_process_context(created)
+        timestamp = logbrew_timestamp
+        metadata = base_metadata
+        created.environment(
+          "ruby_rails_environment_#{SecureRandom.hex(8)}",
+          timestamp,
+          name: @configuration.app_environment,
+          metadata: metadata
+        )
+        return if @configuration.release.nil?
+
+        created.release(
+          "ruby_rails_release_#{SecureRandom.hex(8)}",
+          timestamp,
+          version: @configuration.release,
+          metadata: metadata
+        )
+      end
+
+      def base_metadata
+        {
+          "service" => @configuration.service_name,
+          "environment" => @configuration.app_environment,
+          "framework" => "rails",
+          "framework.version" => @configuration.rails_version
+        }
+      end
+
+      def logbrew_timestamp
+        timestamp = @timestamp_provider.call
+        return timestamp.iso8601 if timestamp.respond_to?(:iso8601)
+
+        timestamp.to_s
+      end
+    end
+
+    # Internal Rack adapter that replaces concrete request paths with Rails
+    # route templates while reusing the core request/error lifecycle.
+    class RailsRackMiddleware < LogBrew::RackMiddleware
+      private
+
+      def request_name(env)
+        "#{request_method(env)} #{route_template(env)}"
+      end
+
+      def request_method(env)
+        value = env_value(env, "REQUEST_METHOD").to_s.upcase
+        value.match?(/\A[A-Z]{1,16}\z/) ? value : "GET"
+      end
+
+      def request_path(env)
+        route_template(env)
+      end
+
+      def request_metadata(env, status_code)
+        metadata = super
+        metadata.delete("http.path")
+        metadata.delete("action_dispatch.request_id")
+        metadata.delete("HTTP_X_REQUEST_ID")
+        metadata["source"] = "rails"
+        metadata["http.method"] = request_method(env)
+        metadata["http.route"] = route_template(env)
+        metadata["http.status_code"] = status_code
+        metadata["http.status_class"] = "#{status_code.to_i / 100}xx"
+        controller, action = controller_and_action(env)
+        metadata["rails.controller"] = controller unless controller.nil?
+        metadata["rails.action"] = action unless action.nil?
+        metadata
+      end
+
+      def route_template(env)
+        route = bounded_route(env_value(env, "action_dispatch.route_uri_pattern"))
+        return route unless route.nil?
+
+        route = bounded_route(matched_route_pattern(env))
+        return route unless route.nil?
+
+        controller, action = controller_and_action(env)
+        return "/#{controller}##{action}" unless controller.nil? || action.nil?
+
+        "<unmatched>"
+      end
+
+      def matched_route_pattern(env)
+        return nil unless env.respond_to?(:[])
+
+        route = env["action_dispatch.route"]
+        return nil unless route.respond_to?(:path)
+
+        path = route.path
+        return nil unless path.respond_to?(:spec)
+
+        path.spec.to_s
+      rescue StandardError
+        nil
+      end
+
+      def controller_and_action(env)
+        return [nil, nil] unless env.respond_to?(:[])
+
+        parameters = env["action_dispatch.request.path_parameters"]
+        return [nil, nil] unless parameters.is_a?(Hash)
+
+        [bounded_identifier(parameters[:controller] || parameters["controller"]),
+         bounded_identifier(parameters[:action] || parameters["action"])]
+      end
+
+      def bounded_route(value)
+        return nil if value.nil?
+
+        route = value.to_s.split(/[?#]/, 2).first.to_s.strip
+        return nil if route.empty? || route.bytesize > 255 || !route.valid_encoding?
+
+        route.start_with?("/") ? route : "/#{route}"
+      end
+
+      def bounded_identifier(value)
+        return nil if value.nil?
+
+        identifier = value.to_s
+        return nil unless identifier.match?(/\A[a-zA-Z0-9_\/.-]{1,128}\z/)
+
+        identifier
+      end
+    end
+    private_constant :RailsRackMiddleware
+
+    # Rails middleware entry point. Capture failures never call the app twice.
+    class RequestMiddleware
+      def initialize(app, runtime: LogBrew::Rails.runtime)
+        raise SdkError.new("validation_error", "Rails app must respond to call") unless app.respond_to?(:call)
+        raise SdkError.new("configuration_error", "LogBrew Rails runtime is not installed") if runtime.nil?
+
+        @app = app
+        @runtime = runtime
+        @mutex = Mutex.new
+        @adapter_client = nil
+        @adapter = nil
+      end
+
+      def call(environment)
+        active_client = @runtime.client
+        return @app.call(environment) if active_client.nil?
+
+        adapter = adapter_for(active_client)
+        return @app.call(environment) if adapter.nil?
+
+        adapter.call(environment)
+      end
+
+      private
+
+      def adapter_for(active_client)
+        @mutex.synchronize do
+          return @adapter if @adapter_client.equal?(active_client) && !@adapter.nil?
+
+          @adapter = RailsRackMiddleware.new(
+            @app,
+            client: active_client,
+            flush_on_response: false,
+            metadata: base_metadata,
+            include_exception_message: @runtime.configuration.capture_exception_messages?,
+            include_exception_backtrace: @runtime.configuration.include_exception_backtrace?,
+            on_error: ->(error) { @runtime.report_error("request_capture", error) }
+          )
+          @adapter_client = active_client
+          @adapter
+        end
+      rescue StandardError => error
+        @runtime.report_error("request_adapter", error)
+        nil
+      end
+
+      def base_metadata
+        configuration = @runtime.configuration
+        {
+          "service" => configuration.service_name,
+          "environment" => configuration.app_environment,
+          "framework" => "rails",
+          "framework.version" => configuration.rails_version
+        }.tap do |metadata|
+          metadata["release"] = configuration.release unless configuration.release.nil?
+        end
+      end
+    end
+
+    # Rails.error subscriber for handled reports. Unhandled errors stay owned
+    # by the request middleware so one exception cannot create two issues.
+    class ErrorReporter
+      CONTEXT_KEYS = %w[controller action].freeze
+
+      def initialize(runtime)
+        @runtime = runtime
+        @mutex = Mutex.new
+        @subscriber_client = nil
+        @subscriber = nil
+      end
+
+      def report(error, handled: true, severity: :error, context: nil, source: nil, **options)
+        return nil unless handled
+
+        active_client = @runtime.client
+        return nil if active_client.nil?
+
+        subscriber_for(active_client).report(
+          error,
+          handled: true,
+          severity: severity,
+          context: safe_context(context),
+          source: bounded_source(source),
+          **options
+        )
+      rescue StandardError => capture_error
+        @runtime.report_error("handled_error_capture", capture_error)
+        nil
+      end
+
+      private
+
+      def subscriber_for(active_client)
+        @mutex.synchronize do
+          return @subscriber if @subscriber_client.equal?(active_client) && !@subscriber.nil?
+
+          configuration = @runtime.configuration
+          @subscriber = LogBrew::RailsErrorSubscriber.new(
+            client: active_client,
+            flush_on_report: false,
+            metadata: {
+              "service" => configuration.service_name,
+              "environment" => configuration.app_environment,
+              "framework" => "rails",
+              "framework.version" => configuration.rails_version
+            },
+            include_exception_message: configuration.capture_exception_messages?,
+            include_exception_backtrace: configuration.include_exception_backtrace?,
+            on_error: ->(error) { @runtime.report_error("handled_error_capture", error) }
+          )
+          @subscriber_client = active_client
+          @subscriber
+        end
+      end
+
+      def safe_context(context)
+        return nil unless context.is_a?(Hash)
+
+        CONTEXT_KEYS.each_with_object({}) do |key, safe|
+          value = context[key] || context[key.to_sym]
+          next if value.nil?
+
+          text = value.to_s
+          safe[key] = text if text.match?(/\A[a-zA-Z0-9_\/.-]{1,128}\z/)
+        end
+      end
+
+      def bounded_source(source)
+        return nil if source.nil?
+
+        value = source.to_s
+        value.match?(/\A[a-zA-Z0-9_.:-]{1,64}\z/) ? value : "rails"
+      end
+    end
+  end
+end

data/lib/logbrew/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module LogBrew
+  VERSION = "0.1.3"
+end

data/lib/logbrew-sdk.rb

@@ -0,0 +1,4 @@
+# frozen_string_literal: true
+
+require "logbrew"
+require "logbrew/rails" if defined?(::Rails::Railtie)

data/lib/logbrew.rb

@@ -8,6 +8,8 @@ require "time"
 require "timeout"
 require "uri"
 
+require_relative "logbrew/version"
+
 module LogBrew
   SEVERITY_VALUES = %w[trace debug info warn warning error fatal critical].freeze
   SEVERITY_ALIASES = {
@@ -369,6 +371,7 @@ module LogBrew
       event_id_prefix: DEFAULT_EVENT_ID_PREFIX,
       metadata: nil,
       timestamp_provider: nil,
+      include_exception_message: true,
       include_exception_backtrace: false,
       on_error: nil,
       raise_errors: false
@@ -384,10 +387,12 @@ module LogBrew
       @event_id_prefix = event_id_prefix
       @metadata = metadata || {}
       @timestamp_provider = timestamp_provider
+      @include_exception_message = include_exception_message
       @include_exception_backtrace = include_exception_backtrace
       @on_error = on_error
       @raise_errors = raise_errors
       @next_event_number = 0
+      @event_id_mutex = Mutex.new
     end
 
     def call(env)
@@ -428,19 +433,20 @@ module LogBrew
     end
 
     def capture_exception_issue(env, error)
-      @client.issue(
-        next_event_id("issue"),
-        logbrew_timestamp,
+      attributes = {
         title: error.class.name,
         level: "error",
-        message: error.message,
         metadata: exception_metadata(env, error)
-      )
+      }
+      attributes[:message] = error.message if @include_exception_message
+      @client.issue(next_event_id("issue"), logbrew_timestamp, attributes)
     end
 
     def next_event_id(kind)
-      @next_event_number += 1
-      "#{@event_id_prefix}_#{kind}_#{@next_event_number}"
+      @event_id_mutex.synchronize do
+        @next_event_number += 1
+        "#{@event_id_prefix}_#{kind}_#{@next_event_number}"
+      end
     end
 
     def logbrew_timestamp
@@ -492,7 +498,7 @@ module LogBrew
     def exception_metadata(env, error)
       request_metadata(env, 500).tap do |metadata|
         metadata["exceptionType"] = error.class.name
-        metadata["exceptionMessage"] = error.message
+        metadata["exceptionMessage"] = error.message if @include_exception_message
         metadata["exceptionBacktrace"] = error.backtrace.join("\n") if @include_exception_backtrace && error.backtrace
       end
     end
@@ -573,6 +579,7 @@ module LogBrew
       event_id_prefix: DEFAULT_EVENT_ID_PREFIX,
       metadata: nil,
       timestamp_provider: nil,
+      include_exception_message: true,
       include_exception_backtrace: false,
       on_error: nil,
       raise_errors: false
@@ -586,23 +593,23 @@ module LogBrew
       @event_id_prefix = event_id_prefix
       @metadata = metadata || {}
       @timestamp_provider = timestamp_provider
+      @include_exception_message = include_exception_message
       @include_exception_backtrace = include_exception_backtrace
       @on_error = on_error
       @raise_errors = raise_errors
       @next_event_number = 0
+      @event_id_mutex = Mutex.new
     end
 
     def report(error, handled: true, severity: :error, context: nil, source: nil, **_options)
       capture_safely do
-        @next_event_number += 1
-        @client.issue(
-          "#{@event_id_prefix}_#{@next_event_number}",
-          logbrew_timestamp,
+        attributes = {
           title: error_title(error),
           level: issue_level(severity),
-          message: error_message(error),
           metadata: rails_metadata(error, handled, severity, context, source)
-        )
+        }
+        attributes[:message] = error_message(error) if @include_exception_message
+        @client.issue(next_event_id, logbrew_timestamp, attributes)
         flush_if_configured
       end
     end
@@ -629,6 +636,13 @@ module LogBrew
       error.inspect
     end
 
+    def next_event_id
+      @event_id_mutex.synchronize do
+        @next_event_number += 1
+        "#{@event_id_prefix}_#{@next_event_number}"
+      end
+    end
+
     def issue_level(severity)
       SEVERITY_TO_ISSUE_LEVEL.fetch(severity.to_s, "error")
     end
@@ -655,7 +669,7 @@ module LogBrew
 
     def add_exception_metadata(metadata, exception)
       metadata["exceptionType"] = exception.class.name
-      metadata["exceptionMessage"] = exception.message
+      metadata["exceptionMessage"] = exception.message if @include_exception_message
       metadata["exceptionBacktrace"] = exception.backtrace.join("\n") if @include_exception_backtrace && exception.backtrace
     end
 

metadata

@@ -1,17 +1,17 @@
 --- !ruby/object:Gem::Specification
 name: logbrew-sdk
 version: !ruby/object:Gem::Version
-  version: 0.1.2
+  version: 0.1.3
 platform: ruby
 authors:
 - LogBrew
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-07-23 00:00:00.000000000 Z
+date: 2026-08-01 00:00:00.000000000 Z
 dependencies: []
-description: Public LogBrew Ruby SDK for building, validating, and flushing event
-  batches.
+description: Public LogBrew Ruby SDK with automatic Rails request/error capture and
+  standard-library delivery.
 email:
 executables: []
 extensions: []
@@ -26,6 +26,7 @@ files:
 - examples/readme_example.rb
 - examples/real_user_smoke.rb
 - examples/sidekiq_tracing.rb
+- lib/logbrew-sdk.rb
 - lib/logbrew.rb
 - lib/logbrew/automatic_delivery.rb
 - lib/logbrew/bounded_event_queue.rb
@@ -35,11 +36,14 @@ files:
 - lib/logbrew/operation_tracing.rb
 - lib/logbrew/persistent_event_store.rb
 - lib/logbrew/product_timeline.rb
+- lib/logbrew/rails.rb
+- lib/logbrew/rails_integration.rb
 - lib/logbrew/sidekiq.rb
 - lib/logbrew/span_events.rb
 - lib/logbrew/support_ticket.rb
 - lib/logbrew/trace.rb
 - lib/logbrew/traceparent.rb
+- lib/logbrew/version.rb
 - lib/logbrew/worker_lifecycle.rb
 homepage: https://github.com/LogBrewCo/sdk
 licenses: