foam-otel 3.0.0.alpha.4 → 3.0.0.alpha.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1c7362be48b291f5a1c52aca227430f7ded8a223dfd289108f1bf97b3254b184
-  data.tar.gz: b876b8f462eccad1ce7f39e4ced08da44243755c0e615109a89891ef563078d6
+  metadata.gz: 34ec502fdc38ac38099bba65f1fc37c91f1edb79476bff598c6a0dda7245fcf0
+  data.tar.gz: 9596d8c1d746b66103b87587f5c52006e024d0498d93816912ed916014e563e4
 SHA512:
-  metadata.gz: 157e5f359ca4d872a7106377d0315c767ff6fc624952408ce85383a8b8c2a4a2e0de62b97c15fc3d8fd261ea09b276b79c0b1b0c4205105a6ab44b45043ea5ab
-  data.tar.gz: c731cca87d8ccf41524ae89da935e8878efb45d3d7ae11c84b7172ddc490ac579da0cd363079fbce6ed8dd24750fa939fa65d30fc2c8611ec8f1b0ce341a2b9d
+  metadata.gz: 85207e2233f8a986bb874f68215960f20216e010978e5d1355808ec2ed6bfb44f19c9b8f8947cc3164cca65864326dab8b5ef95fb8ef6c37a1150fe06923ae2a
+  data.tar.gz: 3a3bc463b06b32e1d1bd4b6c439e5f8a92b031859301f8681e78a32e4e1db655ef73d4439a0755e336abc9fc1b068bca48049172046732da4adb514eb12c00cb

data/README.md

@@ -29,7 +29,20 @@ Store the ingest token as `FOAM_OTEL_TOKEN` and pass `ENV["FOAM_OTEL_TOKEN"]` to
 
 ### Rails
 
-TODO(jhartquist): Rails setup. The Railtie that adds Foam's Rack middleware is not written, so a Rails app is not covered by header and body capture on server spans until it is.
+Create `config/initializers/foam.rb`:
+
+```ruby
+Foam.init(
+  name: "checkout-api",
+  environment: Rails.env,
+  enabled: true,
+  token: ENV["FOAM_OTEL_TOKEN"]
+)
+```
+
+During boot, `init` adds Foam's Rack middleware to the app directly after the OpenTelemetry Rack middleware, so server spans get the same header and body capture as under plain Rack. `init` must run before the app initializes: an initializer file or `config/application.rb`. An `init` from `after_initialize` or later warns on stderr and adds no middleware.
+
+Nothing else changes; `config.ru` stays as generated. A `RUBYOPT` preload runs before Rails loads, so it installs no Rails instrumentation and adds no middleware.
 
 ### Plain Ruby and Rack
 
@@ -372,7 +385,7 @@ There is no option to record other headers.
 
 ### Header capture
 
-Server spans get the headers from `Foam::Rack::Middleware`, placed after the OpenTelemetry Rack middleware. A Rails app is not covered yet.
+Server spans get the headers from `Foam::Rack::Middleware`, placed after the OpenTelemetry Rack middleware (added by `init` in Rails apps).
 
 Client spans get the headers from Foam's hooks on `Net::HTTP`, Excon, HTTPClient, and Faraday, applied unless `network_capture` is `:off`. The `Net::HTTP` hook is always installed; the others install only when their gem is loaded before `init`, and Faraday's covers connections built after `init`. Faraday is covered on the Faraday span whatever the adapter. `http`, `httpx`, `ethon`, and `restclient` are not covered.
 
@@ -392,7 +405,7 @@ In `:advanced` mode each captured body arrives as `foam.http.body.chunk` log rec
 
 ### Rack bodies
 
-Server bodies need `Foam::Rack::Middleware` after the OpenTelemetry Rack middleware, as shown under "Plain Ruby and Rack". A Rails app is not covered yet.
+Server bodies need `Foam::Rack::Middleware` after the OpenTelemetry Rack middleware, as shown under "Plain Ruby and Rack" (added by `init` in Rails apps).
 
 - The request body is captured whether or not the app reads it when the input is rewindable, as it is under Puma, which buffers request bodies. Otherwise what the app reads is captured.
 - A streamed response is observed as the server sends it, without buffering or delaying it. The records are emitted when the body closes; a stream idle for over 60 seconds is closed as incomplete and the rest is dropped.

data/lib/foam/otel/internal/init.rb

@@ -83,6 +83,10 @@ module Foam
             # Foam's logger provider where it flushes the tracer and meter providers.
             Safely.call("aws_lambda") { AwsLambda.install }
 
+            # A Rails app cannot add the middleware in config.ru the way a plain Rack app does, so
+            # Foam adds it through Rails itself.
+            Safely.call("rails middleware") { RailsMiddleware.install } unless options[:network_capture] == :off
+
             # Recorded last so a failed init leaves the state uninitialized.
             State.record_init(
               providers: providers,

data/lib/foam/otel/internal/rails_middleware.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+module Foam
+  module Otel
+    module Internal
+      # Adds Foam::Rack::Middleware to a Rails app directly after the OpenTelemetry Rack middleware:
+      # under it, because Foam reads the server span it opens and needs it open until the response
+      # body closes; with nothing in between, so Foam sees the bytes that leave the server.
+      # The ActionPack instrumentation inserts that middleware from a before_initialize hook, so Foam
+      # uses a before_initialize hook too. Rails runs these hooks in registration order and init
+      # registers Foam's after installing ActionPack, so the OpenTelemetry middleware is always in
+      # place to anchor on, whether init runs before the app class exists or from config/initializers.
+      module RailsMiddleware
+        ACTION_PACK = "OpenTelemetry::Instrumentation::ActionPack"
+        RACK = "OpenTelemetry::Instrumentation::Rack"
+
+        class << self
+          def install
+            return unless defined?(::Rails::Railtie)
+
+            # Rails records middleware changes on a proxy until it builds the stack late in
+            # initialize! (before the after_initialize hooks).
+            if stack_built?
+              Diagnostics.warn(
+                "init ran after the Rails app built its middleware stack, so Foam's middleware " \
+                "was not added; call init from config/initializers"
+              )
+              return
+            end
+
+            # A hook cannot be removed, so an init that rolled back and then succeeded adds one, not two.
+            return if @registered
+
+            @registered = true
+            ::ActiveSupport.on_load(:before_initialize, yield: true) do |app|
+              Safely.call("rails middleware insert") { RailsMiddleware.insert(app) }
+            end
+          end
+
+          def stack_built?
+            app = ::Rails.application
+            !app.nil? && !app.middleware.is_a?(::Rails::Configuration::MiddlewareStackProxy)
+          end
+
+          # Queues the insert on the app's middleware proxy; Rails applies queued inserts in order when
+          # it builds the real stack late in initialize!. Anchored on the OpenTelemetry class, not
+          # position 0, so another SDK inserting at the top cannot come between the two.
+          def insert(app)
+            return unless Instrumentations.instance(ACTION_PACK).installed?
+
+            otel = Instrumentations.instance(RACK).middleware_args.first
+            app.middleware.insert_after(otel, Foam::Rack::Middleware)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/foam/otel/version.rb

@@ -2,6 +2,6 @@
 
 module Foam
   module Otel
-    VERSION = "3.0.0.alpha.4"
+    VERSION = "3.0.0.alpha.5"
   end
 end

data/lib/foam/otel.rb

@@ -23,6 +23,7 @@ require_relative "otel/internal/clients/excon"
 require_relative "otel/internal/clients/http_client"
 require_relative "otel/internal/clients/faraday"
 require_relative "otel/internal/aws_lambda"
+require_relative "otel/internal/rails_middleware"
 require_relative "otel/internal/before_send"
 require_relative "otel/internal/instrumentations"
 require_relative "otel/internal/ignored_hosts"

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: foam-otel
 version: !ruby/object:Gem::Version
-  version: 3.0.0.alpha.4
+  version: 3.0.0.alpha.5
 platform: ruby
 authors:
 - Foam
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-09-17 00:00:00.000000000 Z
+date: 2026-09-18 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: opentelemetry-exporter-otlp
@@ -188,6 +188,7 @@ files:
 - lib/foam/otel/internal/propagation.rb
 - lib/foam/otel/internal/rack/body_tee.rb
 - lib/foam/otel/internal/rack/input_tee.rb
+- lib/foam/otel/internal/rails_middleware.rb
 - lib/foam/otel/internal/redactor.rb
 - lib/foam/otel/internal/redactor/keys.rb
 - lib/foam/otel/internal/report.rb