foam-otel 0.1.0

data/lib/foam/otel/rack.rb

@@ -0,0 +1,243 @@
+# frozen_string_literal: true
+
+require "json"
+require "rack"
+require "securerandom"
+
+require_relative "config"
+require_relative "constants"
+require_relative "errors"
+require_relative "redaction"
+
+module Foam
+  module Otel
+    module Rack
+      # Inbound HTTP adapter — one span per request named "METHOD route",
+      # stamped inbound.http, per contract/SPEC.md sections 5, 6, and 10.
+      # Parent: traceparent header -> active context -> root. foam.rid baggage
+      # from x-request-id (or generated). request.context event with redacted
+      # query/headers/body/ip unless the route is exempted via health_routes.
+      # Anti-fabrication: exception event + ERROR only for unhandled raises;
+      # >=500 -> ERROR with no fabricated event; clean 4xx -> OK. Streaming
+      # (SSE) safe: the span ends when the response body closes, via
+      # Rack::BodyProxy — bodies are never buffered.
+      class Middleware
+        # `auto` is set only when the railtie inserts this middleware; when
+        # true, an init(rails: false) opt-out (or init never having run)
+        # makes it a passthrough. The check is per-request, so it doesn't
+        # depend on init() having run before Rails built the middleware stack
+        # (config/initializers run after that). A middleware added manually to
+        # a bare-Rack app has auto=false and is always active.
+        def initialize(app, auto = false)
+          @app = app
+          @auto = auto
+        end
+
+        def call(env)
+          return @app.call(env) if @auto && !Foam::Otel.rails_enabled?
+
+          Foam::Otel.check_fork!
+          begin
+            span, ctx, started_at, headers = start_span(env)
+          rescue StandardError
+            return @app.call(env) # never crash the request
+          end
+
+          token = OpenTelemetry::Context.attach(ctx)
+          begin
+            status, resp_headers, body = @app.call(env)
+            wrapped = ::Rack::BodyProxy.new(body) do
+              finish_span(span, env, status, started_at, headers)
+            end
+            [status, resp_headers, wrapped]
+          rescue Exception => e # rubocop:disable Lint/RescueException
+            record_unhandled(span, e)
+            finish_span(span, env, 500, started_at, headers, error: true)
+            raise
+          ensure
+            OpenTelemetry::Context.detach(token)
+          end
+        end
+
+        private
+
+        def start_span(env)
+          method = env["REQUEST_METHOD"] || "UNKNOWN"
+          path = env["PATH_INFO"] || "/"
+          # Parsed once and threaded to finish (never written into the caller's
+          # Rack env).
+          headers = request_headers(env)
+
+          parent_ctx = OpenTelemetry::Context.current
+          if headers.key?("traceparent")
+            extracted = OpenTelemetry.propagation.extract(headers)
+            parent_ctx = extracted if extracted
+          end
+
+          rid = presence(headers[REQUEST_ID_HEADER]) || SecureRandom.hex(16)
+          parent_ctx = OpenTelemetry::Baggage.set_value(RID_KEY, rid, context: parent_ctx)
+
+          span = Foam::Otel.tracer("foam-otel/rack").start_span(
+            "HTTP #{method}",
+            with_parent: parent_ctx,
+            kind: :server,
+            attributes: {
+              "http.method" => method,
+              "http.target" => env["REQUEST_URI"] || path,
+              INSTRUMENTATION_KEY => STAMPS::INBOUND_HTTP,
+            }
+          )
+          ctx = OpenTelemetry::Trace.context_with_span(span, parent_context: parent_ctx)
+          [span, ctx, monotonic_ms, headers]
+        end
+
+        def record_unhandled(span, error)
+          Errors.record_once(span, error)
+        end
+
+        def finish_span(span, env, status, started_at, headers, error: false)
+          return if span.nil? || !span.recording?
+
+          route = route_for(env)
+          span.name = "#{env['REQUEST_METHOD']} #{route}"
+          span.set_attribute("http.status_code", status.to_i)
+          span.set_attribute("http.route", route)
+          span.set_attribute("http.duration_ms", (monotonic_ms - started_at).round)
+
+          # An exception recorded by the raise path, the notification hook,
+          # the tracker bridge, or record_exception already set ERROR — a
+          # thrown-then-mapped error stays recorded (SPEC section 6); never
+          # override with OK. Otherwise: >=500 -> ERROR with NO fabricated
+          # exception event; anything else (clean 4xx included) -> OK.
+          unless error || Errors.recorded?(span)
+            span.status = if status.to_i >= 500
+                            OpenTelemetry::Trace::Status.error("")
+                          else
+                            OpenTelemetry::Trace::Status.ok
+                          end
+          end
+
+          config = Foam::Otel.active_config
+          path = env["PATH_INFO"] || "/"
+          unless config.health_routes.include?(route) || config.health_routes.include?(path)
+            capture_request_context(span, env, headers)
+          end
+        rescue StandardError
+          nil
+        ensure
+          begin
+            span&.finish
+          rescue StandardError
+            nil
+          end
+        end
+
+        # Each field is captured under its OWN rescue: a failure serializing
+        # one input (e.g. a header carrying invalid UTF-8 that JSON.generate
+        # rejects) must not drop the whole request.context event.
+        def capture_request_context(span, env, headers)
+          keys = Foam::Otel.active_config.redacted_keys
+          attrs = {}
+
+          begin
+            query = env["QUERY_STRING"].to_s
+            attrs["query"] = Redaction.redact_query(query, keys) unless query.empty?
+          rescue StandardError
+            nil
+          end
+
+          begin
+            unless headers.empty?
+              redacted = headers.to_h { |k, v| [k, keys.include?(k) ? "[REDACTED]" : safe_utf8(v)] }
+              attrs["headers"] = JSON.generate(redacted)
+            end
+          rescue StandardError
+            nil
+          end
+
+          begin
+            body = read_body(env)
+            if body && !body.empty?
+              redacted = Redaction.redact(body, keys)
+              redacted = "#{redacted[0, BODY_TRUNCATION_LIMIT]}...[truncated]" if redacted.length > BODY_TRUNCATION_LIMIT
+              attrs["body"] = redacted
+            end
+          rescue StandardError
+            nil
+          end
+
+          begin
+            ip = env["action_dispatch.remote_ip"]&.to_s || env["REMOTE_ADDR"]
+            attrs["ip"] = ip.to_s if ip
+          rescue StandardError
+            nil
+          end
+
+          span.add_event("request.context", attributes: attrs) unless attrs.empty?
+        rescue StandardError
+          nil
+        end
+
+        def read_body(env)
+          input = env["rack.input"]
+          return nil unless input.respond_to?(:read)
+
+          # Rewind BEFORE reading: at finish time the app has already consumed
+          # the stream (Rack 3 never auto-rewinds), so a read-then-rewind
+          # starts at EOF. Rewind after too, in case anything reads it later.
+          input.rewind if input.respond_to?(:rewind)
+          body = input.read(BODY_TRUNCATION_LIMIT)
+          input.rewind if input.respond_to?(:rewind)
+          safe_utf8(body)
+        rescue StandardError
+          nil
+        end
+
+        def safe_utf8(value)
+          return value if value.nil?
+
+          value.to_s.dup.force_encoding(Encoding::UTF_8).scrub
+        end
+
+        def route_for(env)
+          # The route TEMPLATE (e.g. "/users/:id") — a low-cardinality name,
+          # matching the path-style http.route the other language cores emit.
+          # Rails exposes it as action_dispatch.route_uri_pattern when the
+          # journey router populates it; strip the trailing "(.:format)".
+          # When it's absent (older Rails, bare Rack, or a route the router
+          # didn't stamp) the raw path is the honest fallback — see the
+          # cardinality note in the README.
+          pattern = env["action_dispatch.route_uri_pattern"]
+          return pattern.sub("(.:format)", "") if pattern.is_a?(String) && !pattern.empty?
+
+          env["PATH_INFO"] || "/"
+        rescue StandardError
+          env["PATH_INFO"] || "/"
+        end
+
+        def request_headers(env)
+          headers = {}
+          env.each do |key, value|
+            next unless key.is_a?(String) && key.start_with?("HTTP_")
+
+            headers[key[5..].downcase.tr("_", "-")] = value.to_s
+          end
+          %w[CONTENT_TYPE CONTENT_LENGTH].each do |key|
+            headers[key.downcase.tr("_", "-")] = env[key].to_s if env[key]
+          end
+          headers
+        rescue StandardError
+          {}
+        end
+
+        def presence(value)
+          value.is_a?(String) && !value.empty? ? value : nil
+        end
+
+        def monotonic_ms
+          Process.clock_gettime(Process::CLOCK_MONOTONIC, :millisecond)
+        end
+      end
+    end
+  end
+end

data/lib/foam/otel/railtie.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+require_relative "logger_bridge"
+require_relative "rack"
+
+module Foam
+  module Otel
+    # Rails auto-wiring (zero customer effort): inserts the Rack middleware at
+    # position 0, records controller exceptions that rescue paths swallow
+    # before Rack sees them (ActionDispatch::ShowExceptions renders the 500
+    # below any middleware), and attaches the logger bridge as a broadcast
+    # target. Loaded by lib/foam/otel.rb when Rails is present, but the hooks
+    # only ACTIVATE once init(rails: true) has run (Foam::Otel.rails_enabled?)
+    # — merely bundling the gem installs nothing, and rails: false opts out.
+    class Railtie < ::Rails::Railtie
+      initializer "foam_otel.middleware", before: :build_middleware_stack do |app|
+        # Inserted unconditionally (auto: true) so it never depends on init()
+        # having run before Rails built the middleware stack. The middleware
+        # passes through per-request until rails_enabled? — see Rack::Middleware.
+        app.middleware.insert_before(0, Foam::Otel::Rack::Middleware, true)
+      end
+
+      config.after_initialize do
+        # Installed unconditionally (once), like the middleware — each fires
+        # only when rails_enabled?, so activation doesn't depend on init()
+        # having run before after_initialize. A late init() therefore gets
+        # exception capture and log bridging along with inbound spans, and
+        # rails: false keeps them inert.
+        unless Foam::Otel::Railtie.hooks_installed
+          Foam::Otel::Railtie.hooks_installed = true
+
+          # Exceptions that escape controller actions surface here even when
+          # ShowExceptions (below our middleware) turns them into a rendered
+          # 500 — the raise never reaches Rack. Thrown-then-mapped errors are
+          # genuine fault signals (SPEC section 6). The shared Errors dedupe
+          # (carried on the span) guards against the middleware's own rescue
+          # and the tracker bridge double-recording.
+          ActiveSupport::Notifications.subscribe("process_action.action_controller") do |*args|
+            begin
+              if Foam::Otel.rails_enabled?
+                payload = args.last
+                error = payload[:exception_object] if payload.is_a?(Hash)
+                Foam::Otel::Errors.record_once(OpenTelemetry::Trace.current_span, error) if error
+              end
+            rescue StandardError
+              nil
+            end
+          end
+
+          begin
+            if ::Rails.logger.respond_to?(:broadcast_to)
+              bridge = Foam::Otel::LoggerBridge.new(tagged_source: ::Rails.logger)
+              ::Rails.logger.broadcast_to(bridge)
+            end
+          rescue StandardError
+            nil
+          end
+        end
+      end
+
+      class << self
+        attr_accessor :hooks_installed
+      end
+    end
+  end
+end

data/lib/foam/otel/redaction.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+require "json"
+require "uri"
+
+require_relative "constants"
+
+module Foam
+  module Otel
+    # Central redaction engine — the ONE place sensitive keys are stripped.
+    # Case-insensitive key match; deep-redacts nested structures with a depth
+    # guard; values become the literal "[REDACTED]".
+    module Redaction
+      module_function
+
+      def redact_value(obj, keys, depth = 0)
+        return "[depth limit]" if depth > MAX_REDACT_DEPTH
+
+        case obj
+        when Array
+          obj.map { |item| redact_value(item, keys, depth + 1) }
+        when Hash
+          obj.each_with_object({}) do |(key, val), result|
+            if key.is_a?(String) && keys.include?(key.downcase)
+              result[key] = "[REDACTED]"
+            else
+              result[key] = redact_value(val, keys, depth + 1)
+            end
+          end
+        else
+          obj
+        end
+      end
+
+      # Redacts a raw string: JSON payloads are deep-redacted; non-JSON
+      # strings pass through unchanged.
+      def redact(raw, keys)
+        parsed = JSON.parse(raw)
+        JSON.generate(redact_value(parsed, keys))
+      rescue StandardError
+        raw
+      end
+
+      # Per-key query-string redaction ('a=1&token=x' form), mirroring the
+      # other cores: split on '&', split each pair on the FIRST '=', URL-decode
+      # the key for matching ONLY, emit the RAW key + '=[REDACTED]' (matched)
+      # or the raw pair unchanged — never re-encode, never leak on failure.
+      def redact_query(query, keys)
+        return query if query.nil? || query.empty?
+
+        query.split("&", -1).map do |pair|
+          eq = pair.index("=")
+          next pair if eq.nil?
+
+          raw_key = pair[0...eq]
+          decoded_key = URI.decode_www_form_component(raw_key)
+          if keys.include?(decoded_key.downcase)
+            "#{raw_key}=[REDACTED]"
+          else
+            pair
+          end
+        end.join("&")
+      rescue StandardError
+        ""
+      end
+    end
+  end
+end

data/lib/foam/otel/sidekiq.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+require "securerandom"
+
+require_relative "constants"
+require_relative "errors"
+
+module Foam
+  module Otel
+    # Sidekiq consumer adapter (contract SPEC.md sections 2, 3, 10): one root
+    # span per job named "sidekiq.consume <queue>", kind consumer, stamped
+    # sidekiq.consume. foam.rid baggage is jid-derived (queue consumers with
+    # no inbound rid derive it from the job id). Failures record + ERROR and
+    # RE-RAISE identically — Sidekiq's retry behavior is untouched.
+    # Auto-registered by init() when Sidekiq is present (opt out with
+    # `sidekiq: false`).
+    module Sidekiq
+      def self.install!
+        return false if @installed
+        return false unless defined?(::Sidekiq) && ::Sidekiq.respond_to?(:configure_server)
+
+        ::Sidekiq.configure_server do |config|
+          config.server_middleware do |chain|
+            chain.add(ServerMiddleware)
+          end
+        end
+        @installed = true
+        true
+      rescue StandardError
+        false
+      end
+
+      class ServerMiddleware
+        def call(worker, job, queue)
+          Foam::Otel.check_fork!
+          begin
+            span, ctx = start_span(job, queue)
+          rescue StandardError
+            return yield # instrumentation must never break job processing
+          end
+
+          token = OpenTelemetry::Context.attach(ctx)
+          begin
+            yield
+            # Never clobber an ERROR recorded during the job (Rollbar hook,
+            # record_exception): a thrown-then-mapped error stays ERROR
+            # (SPEC section 6/12), matching the Rack adapter.
+            span.status = OpenTelemetry::Trace::Status.ok unless Errors.recorded?(span)
+          rescue Exception => e # rubocop:disable Lint/RescueException
+            Errors.record_once(span, e)
+            raise
+          ensure
+            OpenTelemetry::Context.detach(token)
+            begin
+              span.finish
+            rescue StandardError
+              nil
+            end
+          end
+        end
+
+        private
+
+        def start_span(job, queue)
+          jid = job["jid"].to_s
+          ctx = OpenTelemetry::Baggage.set_value(
+            RID_KEY, jid.empty? ? SecureRandom.hex(16) : jid,
+            context: OpenTelemetry::Context.current
+          )
+          span = Foam::Otel.tracer("foam-otel/sidekiq").start_span(
+            "sidekiq.consume #{queue}",
+            with_parent: ctx,
+            kind: :consumer,
+            attributes: {
+              INSTRUMENTATION_KEY => STAMPS::SIDEKIQ_CONSUME,
+              "messaging.system" => "sidekiq",
+              "messaging.destination" => queue.to_s,
+              "sidekiq.job_class" => (job["wrapped"] || job["class"]).to_s,
+              "sidekiq.jid" => jid,
+              "sidekiq.retry_count" => job["retry_count"].to_i,
+            }
+          )
+          [span, OpenTelemetry::Trace.context_with_span(span, parent_context: ctx)]
+        end
+      end
+    end
+  end
+end

data/lib/foam/otel/stamps.rb

@@ -0,0 +1,104 @@
+# frozen_string_literal: true
+
+require_relative "constants"
+require_relative "vendor/datadog"
+
+module Foam
+  module Otel
+    # Shared stamping logic for the span and log processors: default
+    # foam.instrumentation to app.custom, copy foam.rid from baggage, and
+    # attach dd.trace_id/dd.span_id verbatim when a Datadog trace is active
+    # (SPEC section 7.3). One implementation so spans and logs can never
+    # disagree. `get`/`set` abstract the two write shapes (span setter vs a
+    # plain attributes hash). Returns the number of attributes ADDED.
+    module Stamping
+      module_function
+
+      # The stamp attributes to apply, as [[key, value], ...]. The caller
+      # sets each only when absent. No per-call closures (this is the hottest
+      # path); Datadog correlation is resolved once here, not per attribute.
+      def candidates(context)
+        pairs = [[INSTRUMENTATION_KEY, STAMPS::APP_CUSTOM]]
+        rid = baggage_rid(context)
+        pairs << [RID_KEY, rid] if rid
+        Vendor::Datadog.correlation_attributes&.each { |key, value| pairs << [key, value] }
+        pairs
+      rescue StandardError
+        pairs || []
+      end
+
+      def baggage_rid(context)
+        value = OpenTelemetry::Baggage.value(RID_KEY, context: context)
+        value.is_a?(String) && !value.empty? ? value : nil
+      rescue StandardError
+        nil
+      end
+    end
+
+    class StampSpanProcessor
+      def on_start(span, parent_context)
+        # One frozen-clone read of the attributes to test presence against.
+        current = span.attributes
+        Stamping.candidates(parent_context).each do |key, value|
+          span.set_attribute(key, value) if current[key].nil?
+        end
+      rescue StandardError
+        nil # stamping must never break telemetry
+      end
+
+      def on_finish(span); end
+
+      def force_flush(timeout: nil)
+        OpenTelemetry::SDK::Trace::Export::SUCCESS
+      end
+
+      def shutdown(timeout: nil)
+        OpenTelemetry::SDK::Trace::Export::SUCCESS
+      end
+    end
+
+    class StampLogRecordProcessor
+      def on_emit(log_record, context)
+        attributes = log_record.attributes ||= {}
+        added = 0
+        Stamping.candidates(context).each do |key, value|
+          next unless attributes[key].nil?
+
+          attributes[key] = value
+          added += 1
+        end
+        sync_recorded_count(log_record, added)
+      rescue StandardError
+        nil
+      end
+
+      def force_flush(timeout: nil)
+        OpenTelemetry::SDK::Logs::Export::SUCCESS
+      end
+
+      def shutdown(timeout: nil)
+        OpenTelemetry::SDK::Logs::Export::SUCCESS
+      end
+
+      private
+
+      # The logs SDK snapshots total_recorded_attributes at record
+      # construction and the OTLP exporter encodes
+      # dropped = total_recorded - current_size; attributes ADDED by a
+      # processor make that negative and the uint32 protobuf field rejects
+      # the whole batch. Bump the snapshot by exactly the number we added
+      # (NOT max(), which would under-report genuine limit-drops). Guarded
+      # so a future SDK ivar rename can't crash — but a spec asserts the ivar
+      # still exists so the guard can't silently mask the regression.
+      def sync_recorded_count(log_record, added)
+        return if added.zero?
+        return unless log_record.instance_variable_defined?(:@total_recorded_attributes)
+
+        total = log_record.instance_variable_get(:@total_recorded_attributes).to_i
+        log_record.instance_variable_set(:@total_recorded_attributes, total + added)
+      rescue StandardError
+        nil
+      end
+    end
+  end
+end

data/lib/foam/otel/vendor/datadog.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module Foam
+  module Otel
+    module Vendor
+      # Datadog coexistence (contract SPEC.md section 7.3): correlation-only.
+      # Foam never parents from, mutates, or patches the DD tracer — it reads
+      # DD's correlation ids VERBATIM (no format conversion; DD ids are
+      # 64/128-bit numerics, not W3C hex) and attaches them to foam spans and
+      # log records so one record cross-links both backends. No active DD
+      # trace -> nil, and the attributes are simply absent (never fabricated).
+      module Datadog
+        module_function
+
+        # -> { "dd.trace_id" => ..., "dd.span_id" => ... } or nil. Never raises.
+        def correlation_attributes
+          return nil unless defined?(::Datadog::Tracing)
+
+          correlation = ::Datadog::Tracing.correlation
+          return nil if correlation.nil?
+
+          trace_id = correlation.trace_id
+          span_id = correlation.span_id
+          return nil if trace_id.nil? || trace_id.to_s == "0" || trace_id == 0
+
+          attrs = { "dd.trace_id" => trace_id.to_s }
+          attrs["dd.span_id"] = span_id.to_s unless span_id.nil? || span_id == 0
+          attrs
+        rescue StandardError
+          nil
+        end
+      end
+    end
+  end
+end

data/lib/foam/otel/vendor/rollbar.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+require_relative "../errors"
+
+module Foam
+  module Otel
+    module Vendor
+      # Error-tracker coexistence (contract SPEC.md section 12): the bridge
+      # direction is tracker -> foam only. When the app notifies Rollbar of an
+      # exception (e.g. inside a rescue_from handler foam's middleware never
+      # sees), the exception is also recorded on the active foam span — then
+      # Rollbar proceeds exactly as before (side-effect-free observation:
+      # arguments, result, and raise behavior untouched). Installed by
+      # presence detection at init(); opt out with `rollbar: false`. The
+      # shared Errors registry guarantees one exception event per span even
+      # when Rollbar's own middleware AND foam's middleware see the same raise.
+      module Rollbar
+        module_function
+
+        def install!
+          return false unless defined?(::Rollbar)
+          return false if @installed
+
+          ::Rollbar.singleton_class.prepend(Hook)
+          @installed = true
+          true
+        end
+
+        module Hook
+          # Rollbar.log(level, *args) is the funnel every Rollbar.error/
+          # critical/warning call goes through. Observe, then defer to Rollbar
+          # unchanged.
+          def log(level, *args, **kwargs, &block)
+            begin
+              error = args.find { |arg| arg.is_a?(Exception) }
+              Foam::Otel::Errors.record_once(OpenTelemetry::Trace.current_span, error) if error
+            rescue StandardError
+              # observation must never break tracker reporting
+            end
+            super
+          end
+        end
+      end
+    end
+  end
+end

data/lib/foam/otel/version.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module Foam
+  module Otel
+    # The publish pipeline parses this literal (tools/publish-packages) —
+    # strict semver only; gem-style prereleases (0.1.0.alpha1) are unsupported.
+    VERSION = "0.1.0"
+  end
+end

data/lib/foam/otel.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+# foam-otel — the shared foam OpenTelemetry core for Ruby services,
+# implementing contract/SPEC.md (see that file for every ruling).
+#
+#   Foam::Otel.init(service_name: "my-service")
+#
+# Zero customer effort: the Rails railtie, Rack middleware, Sidekiq server
+# middleware, logger bridge, and vendor coexistence (Datadog correlation,
+# Rollbar hook) all self-wire by presence detection. Opt-outs only.
+
+require_relative "otel/version"
+require_relative "otel/constants"
+require_relative "otel/config"
+require_relative "otel/redaction"
+require_relative "otel/errors"
+require_relative "otel/init"
+require_relative "otel/rack"
+require_relative "otel/logger_bridge"
+require_relative "otel/vendor/datadog"
+require_relative "otel/vendor/rollbar"
+
+require_relative "otel/railtie" if defined?(::Rails::Railtie)

data/lib/foam-otel.rb

@@ -0,0 +1,4 @@
+# frozen_string_literal: true
+
+# Bundler default-require shim: `gem "foam-otel"` loads the real entrypoint.
+require_relative "foam/otel"