foam-otel 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 8650474eaaa3dec06f5500839b073d5c2b211750da4ad2a068459cbbb5feb3f1
+  data.tar.gz: 6c7b40fe1a9297f0c81547222f4ea7a36c716a9bc1eb6a2f97c5e44d49f6b9eb
+SHA512:
+  metadata.gz: 39fd5531d0478acdff0ae4e36ae901ee3975a2b2c55e84319bba959683ac3fa69dd226639f2c1c7f4682eec9d064843071209f7ed56bf149d30591cecc732ba8
+  data.tar.gz: b32886c34c0b60fd1f7751a7cb7e1a81152804c7c495078217ef7e63a83025b15b5336acffad32ebc23e730c42120aa8e32519cd3a9d1154f049130b75ad8160

data/README.md

@@ -0,0 +1,76 @@
+# foam-otel
+
+The shared foam OpenTelemetry core for Ruby services — traces, logs, and
+metrics over OTLP HTTP, implementing the fleet wire contract
+([`contract/SPEC.md`](../../contract/SPEC.md)). Verified end-to-end by the
+`test-apps/ruby-rails` conformance gate on every PR.
+
+```ruby
+# Gemfile
+gem "foam-otel"
+
+# config/initializers/foam.rb (or before Rails loads)
+Foam::Otel.init(service_name: "my-service")
+```
+
+That's the whole integration. Everything else self-wires by presence
+detection (zero customer effort):
+
+- **Rails**: railtie inserts the Rack middleware at position 0, captures
+  controller exceptions that `rescue_from` swallows (via
+  `process_action.action_controller`), and broadcasts `Rails.logger` lines to
+  foam as `log.rails` records — the app's own logger chain is never touched.
+- **Sidekiq**: server middleware auto-registers; one `sidekiq.consume <queue>`
+  consumer span per job, failures re-raised identically (retries untouched).
+- **Datadog** (SPEC §7.3): foam spans and logs carry `dd.trace_id`/`dd.span_id`
+  verbatim from the DD correlation API when a DD trace is active. Foam never
+  patches, parents from, or reconfigures the DD tracer.
+- **Rollbar** (SPEC §12): exceptions the app reports to Rollbar (e.g. inside
+  `rescue_from` handlers) are also recorded on the active foam span — Rollbar
+  itself is untouched, and each exception records at most once per span.
+
+| option | default | |
+|---|---|---|
+| `service_name:` | (required) | resource `service.name` |
+| `token:` | `FOAM_OTEL_TOKEN` env | missing → warn + inert |
+| `endpoint:` | `OTEL_EXPORTER_OTLP_ENDPOINT` env → `https://otel.api.foam.ai` | |
+| `force_export:` | `false` | export outside production |
+| `redact_contact_info:` | `false` | append email/phone/telefono/celular to redaction |
+| `redact_keys:` | `[]` | extra redacted keys |
+| `health_routes:` | `[]` | routes exempted from request-context capture (none by default — health checks are captured) |
+| `sidekiq:` / `rollbar:` / `rails:` | `true` | opt out of auto-wiring that adapter |
+
+Export is production-gated (`RAILS_ENV`/`RACK_ENV`/`ENVIRONMENT`/`ENV`/
+`NODE_ENV` ∈ {production, prod}) unless `force_export`. Batch cadence comes
+from the standard OTel env vars (`OTEL_BSP_SCHEDULE_DELAY`,
+`OTEL_BLRP_SCHEDULE_DELAY`, `OTEL_METRIC_EXPORT_INTERVAL`).
+
+**Route names**: span names and `http.route` use Rails' route template
+(`action_dispatch.route_uri_pattern`, e.g. `/users/:id`) when available. On
+older Rails or bare Rack where it isn't populated, the raw path is used —
+which raises span-name cardinality for routes with dynamic segments; prefer
+Rails 7.1+ for automatic low-cardinality route names.
+
+**Forked servers** (Puma workers, Sidekiq): span/log pipelines self-heal
+after fork; the metrics reader is re-armed automatically by the first
+request/job in the child via a pid check. Belt-and-braces:
+`on_worker_boot { Foam::Otel.after_fork! }`.
+
+Custom telemetry passthrough (stamped `app.custom` automatically). Create
+each instrument ONCE and reuse it — creating an instrument per call
+re-registers it under a mutex and logs a duplicate-registration warning:
+
+```ruby
+Foam::Otel.tracer.in_span("work") { |span| ... }
+
+JOBS_DONE = Foam::Otel.meter.create_counter("jobs_done")   # once, at load
+JOBS_DONE.add(1)                                            # per event
+
+Foam::Otel.logger.on_emit(severity_number: 9, body: "hi", context: OpenTelemetry::Context.current)
+Foam::Otel.record_exception(error)   # foam span only; never notifies a tracker
+```
+
+```sh
+bundle exec rspec           # unit suite
+bash ../../test-apps/ruby-rails/run-verify.sh   # full conformance gate
+```

data/lib/foam/otel/config.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+require "set"
+
+require_relative "constants"
+
+module Foam
+  module Otel
+    # Resolved configuration — options + env vars, per contract/SPEC.md:
+    # endpoint is option > OTEL_EXPORTER_OTLP_ENDPOINT > default; batch
+    # cadence comes from the standard OTel env vars, which the Ruby SDK reads
+    # natively (never hardcoded here).
+    Config = Struct.new(:service_name, :endpoint, :redacted_keys, :health_routes, keyword_init: true)
+
+    DEFAULT_CONFIG = Config.new(
+      service_name: "",
+      endpoint: FOAM_OTEL_ENDPOINT,
+      redacted_keys: DEFAULT_REDACTED_KEYS.to_set.freeze,
+      health_routes: DEFAULT_HEALTH_ROUTES.to_set.freeze
+    ).freeze
+
+    @active_config = DEFAULT_CONFIG
+
+    class << self
+      # The config of the most recently initialized service. Adapters read
+      # through this so they work (with safe defaults) even before init().
+      def active_config
+        @active_config
+      end
+
+      def active_config=(config)
+        @active_config = config
+      end
+
+      def resolve_endpoint(endpoint)
+        resolved = endpoint || ENV.fetch("OTEL_EXPORTER_OTLP_ENDPOINT", nil) || FOAM_OTEL_ENDPOINT
+        resolved.sub(%r{/+\z}, "")
+      end
+
+      def resolve_config(service_name:, endpoint: nil, redact_contact_info: false,
+                         redact_keys: nil, health_routes: nil)
+        keys = DEFAULT_REDACTED_KEYS.to_set
+        keys.merge(CONTACT_INFO_KEYS) if redact_contact_info
+        (redact_keys || []).each { |key| keys.add(key.downcase) }
+
+        routes = DEFAULT_HEALTH_ROUTES.to_set
+        (health_routes || []).each { |route| routes.add(route) }
+
+        Config.new(
+          service_name: service_name,
+          endpoint: resolve_endpoint(endpoint),
+          redacted_keys: keys.freeze,
+          health_routes: routes.freeze
+        ).freeze
+      end
+
+      # Production detection across common conventions (RAILS_ENV/RACK_ENV
+      # first — the Ruby idioms — then the fleet-shared names).
+      def production?
+        %w[RAILS_ENV RACK_ENV ENVIRONMENT ENV NODE_ENV].any? do |var|
+          %w[production prod].include?(ENV.fetch(var, "").downcase)
+        end
+      end
+    end
+  end
+end

data/lib/foam/otel/constants.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+module Foam
+  module Otel
+    # Fleet-wide defaults. The canonical source is contract/defaults.json;
+    # contract/verify/check-defaults.mjs extracts the literals below from THIS
+    # file on every conformance run — keep them flat quoted-string array
+    # literals (no %w[], no computed values) or extraction breaks.
+
+    FOAM_OTEL_ENDPOINT = "https://otel.api.foam.ai"
+
+    BODY_TRUNCATION_LIMIT = 4096
+    MAX_REDACT_DEPTH = 10
+
+    DEFAULT_REDACTED_KEYS = [
+      "password",
+      "token",
+      "authorization",
+      "secret",
+      "api_key",
+      "apikey",
+      "access_token",
+      "accesstoken",
+      "jwt",
+      "x-api-key",
+      "x-service-token",
+      "cookie",
+      "set-cookie",
+      "creditcard",
+      "credit_card",
+      "card_number",
+      "cardnumber",
+      "cvv",
+      "cvc",
+      "dni",
+      "ssn",
+    ].freeze
+
+    # Opt-in contact-PII list. Enabled via `redact_contact_info: true`.
+    CONTACT_INFO_KEYS = ["email", "phone", "telefono", "celular"].freeze
+
+    # Empty by default: health checks are captured like any other route
+    # (contract SPEC.md section 5); services exempt routes via health_routes.
+    DEFAULT_HEALTH_ROUTES = [].freeze
+
+    REQUEST_ID_HEADER = "x-request-id"
+
+    INSTRUMENTATION_KEY = "foam.instrumentation"
+    RID_KEY = "foam.rid"
+
+    module STAMPS
+      INBOUND_HTTP = "inbound.http"
+      OUTBOUND_HTTP = "outbound.http"
+      SQS_CONSUME = "sqs.consume"
+      SIDEKIQ_CONSUME = "sidekiq.consume"
+      QUEUE_PRODUCE = "queue.produce"
+      LOG_RAILS = "log.rails"
+      LOG_CONSOLE = "log.console"
+      APP_CUSTOM = "app.custom"
+    end
+  end
+end

data/lib/foam/otel/errors.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+module Foam
+  module Otel
+    # One exception, one event (contract SPEC.md section 12): every capture
+    # path — the Rack middleware's unhandled-raise rescue, the railtie's
+    # process_action notification hook, the error-tracker bridge, and the
+    # public record_exception API — records through here, deduped per span by
+    # exception object identity.
+    #
+    # The seen-set lives ON the span object (an instance variable), not in a
+    # thread-local: a request span can be recorded on one thread and finished
+    # on another (ActionController::Live streams the response body from a
+    # separate thread), so a thread-local would both miss the dedupe/recorded
+    # check across threads and leak entries for spans that never pass back
+    # through their owning thread. Span-carried state is GC'd with the span
+    # and travels with it across threads.
+    module Errors
+      IVAR = :@__foam_otel_recorded
+
+      module_function
+
+      # Records `error` on `span` (exception event + status ERROR) unless this
+      # exact exception object was already recorded there. Never raises.
+      def record_once(span, error)
+        return false unless span.respond_to?(:context) && span.context.valid?
+        return false unless span.respond_to?(:recording?) && span.recording?
+
+        seen = span.instance_variable_get(IVAR)
+        unless seen
+          seen = []
+          span.instance_variable_set(IVAR, seen)
+        end
+        return false if seen.include?(error.object_id)
+
+        seen << error.object_id
+        span.record_exception(error)
+        span.status = OpenTelemetry::Trace::Status.error(error.message.to_s)
+        true
+      rescue StandardError
+        false
+      end
+
+      # Whether any exception has been recorded on this span (so a later OK
+      # status never clobbers a thrown-then-mapped ERROR — SPEC section 6).
+      def recorded?(span)
+        seen = span.instance_variable_get(IVAR)
+        !seen.nil? && !seen.empty?
+      rescue StandardError
+        false
+      end
+    end
+  end
+end

data/lib/foam/otel/init.rb

@@ -0,0 +1,351 @@
+# frozen_string_literal: true
+
+require "opentelemetry/sdk"
+require "opentelemetry-logs-sdk"
+require "opentelemetry-metrics-sdk"
+require "opentelemetry-exporter-otlp"
+require "opentelemetry-exporter-otlp-logs"
+require "opentelemetry-exporter-otlp-metrics"
+
+require_relative "config"
+require_relative "stamps"
+require_relative "errors"
+require_relative "vendor/rollbar"
+
+module Foam
+  module Otel
+    # Handle returned by init(). Providers are global — this mostly carries
+    # the resolved config and shutdown.
+    class Instance
+      attr_reader :service_name, :config
+      attr_accessor :providers
+
+      def initialize(service_name, config)
+        @service_name = service_name
+        @config = config
+        @providers = []
+      end
+
+      def shutdown
+        if @providers.empty?
+          # This instance owns no providers (inert, or a later init whose
+          # signals were already wired). It must not tear down the owner's
+          # pipelines, but — flush parity — it still best-effort flushes
+          # foam's live pipelines so buffered telemetry isn't dropped.
+          Foam::Otel.flush_foam_pipelines
+          return
+        end
+        @providers.each do |provider|
+          begin
+            provider.shutdown
+          rescue StandardError
+            nil
+          end
+          Foam::Otel.forget_provider(provider)
+        end
+        Foam::Otel.clear_fallback_meter_provider_if_in(@providers)
+        @providers = []
+      end
+    end
+
+    @instances = {}
+    # Providers foam itself created AND registered globally. A second init()
+    # must not attach another stamp+batch pipeline to them (double export) and
+    # must not misclassify them as "another SDK's" provider.
+    @foam_providers = []
+    # Foreign providers foam already attached its stamp+batch pipeline to.
+    @attached_providers = []
+    # Live flushable pipelines foam owns (providers foam created + batch
+    # processors foam attached to foreign providers).
+    @flushables = []
+    # Metrics-coexistence fallback (SPEC section 9): when another SDK owns the
+    # global MeterProvider, foam's provider lives here and meter() serves it.
+    @fallback_meter_provider = nil
+    # Foam-owned periodic metric readers — the one pipeline piece that does
+    # NOT self-heal across forks (batch span/log processors reset_on_fork
+    # automatically; verified upstream) and needs an explicit after_fork.
+    @metric_readers = []
+    # PID at last check_fork! — re-arms metric readers once per fork.
+    @pid = Process.pid
+
+    class << self
+      # rubocop:disable Metrics/MethodLength
+      def init(service_name:, token: nil, endpoint: nil, force_export: false,
+               redact_contact_info: false, redact_keys: nil, health_routes: nil,
+               sidekiq: true, rollbar: true, rails: true)
+        existing = @instances[service_name]
+        if existing
+          warn "[foam] init() already called for \"#{service_name}\" — returning existing instance"
+          return existing
+        end
+        unless @instances.empty?
+          warn "[foam] init(\"#{service_name}\") called after #{@instances.keys.sort} — " \
+               "the active adapter config is process-global and last-write-wins"
+        end
+
+        # The resolved config becomes the active config on EVERY path — even
+        # inert init: another SDK may own the global providers and the
+        # adapters still emit real spans through it.
+        config = resolve_config(
+          service_name: service_name, endpoint: endpoint,
+          redact_contact_info: redact_contact_info, redact_keys: redact_keys,
+          health_routes: health_routes
+        )
+        self.active_config = config
+
+        # Zero-customer-effort: adapters and vendor bridges self-wire by
+        # presence detection on every init path (inert included — a foreign
+        # SDK may still export what the adapters produce). Opt-outs only.
+        auto_wire(sidekiq: sidekiq, rollbar: rollbar, rails: rails)
+
+        unless production? || force_export
+          warn "[foam] skipping init for \"#{service_name}\" (not production, force_export false)"
+          return remember(Instance.new(service_name, config))
+        end
+
+        resolved_token = token || ENV.fetch("FOAM_OTEL_TOKEN", nil)
+        if resolved_token.nil? || resolved_token.empty?
+          warn "[foam] token is missing — telemetry will not be exported. " \
+               "Set token or the FOAM_OTEL_TOKEN env var."
+          return remember(Instance.new(service_name, config))
+        end
+
+        instance = Instance.new(service_name, config)
+        headers = { "Authorization" => "Bearer #{resolved_token}" }
+        resource = OpenTelemetry::SDK::Resources::Resource.create("service.name" => service_name)
+
+        # We bypass OpenTelemetry::SDK.configure, so propagation must be set
+        # explicitly: W3C TraceContext + Baggage.
+        OpenTelemetry.propagation = OpenTelemetry::Context::Propagation::CompositeTextMapPropagator
+          .compose_propagators([
+            OpenTelemetry::Trace::Propagation::TraceContext.text_map_propagator,
+            OpenTelemetry::Baggage::Propagation.text_map_propagator,
+          ])
+
+        # Each signal is independent — a failure in one never blocks the rest.
+        %i[setup_traces setup_logs setup_metrics].each do |setup|
+          provider = send(setup, config.endpoint, headers, resource)
+          instance.providers << provider if provider
+        rescue StandardError => e
+          warn "[foam] #{setup} failed: #{e.class}: #{e.message}"
+        end
+
+        at_exit { instance.shutdown }
+        warn "[foam] OTLP export enabled for #{service_name} -> #{config.endpoint}"
+        remember(instance)
+      end
+      # rubocop:enable Metrics/MethodLength
+
+      # Signal passthrough: a tracer/meter/logger that exports to foam after
+      # init(). meter() serves the fallback provider when another SDK owns the
+      # global MeterProvider (SPEC section 9).
+      def tracer(name = "foam")
+        OpenTelemetry.tracer_provider.tracer(name)
+      end
+
+      def meter(name = "foam")
+        return @fallback_meter_provider.meter(name) if @fallback_meter_provider
+
+        OpenTelemetry.meter_provider.meter(name)
+      end
+
+      def logger(name = "foam")
+        OpenTelemetry.logger_provider.logger(name: name)
+      end
+
+      # Records an exception on the active span (status ERROR) when one
+      # exists. Records to the foam span ONLY — never notifies any error
+      # tracker (SPEC section 12). Never raises.
+      def record_exception(error)
+        Errors.record_once(OpenTelemetry::Trace.current_span, error)
+        nil
+      rescue StandardError
+        nil
+      end
+
+      # Metrics readers do not self-heal across forks (unlike the batch
+      # span/log processors, which reset_on_fork automatically). Call in
+      # Puma's on_worker_boot / Sidekiq lifecycle — the Rack and Sidekiq
+      # adapters also invoke it via check_fork! per call.
+      def after_fork!
+        @metric_readers.each do |reader|
+          reader.after_fork if reader.respond_to?(:after_fork)
+        rescue StandardError
+          nil
+        end
+      end
+
+      # One authoritative process-level fork check the adapters call per
+      # request/job — re-arms the metric readers exactly once per fork.
+      def check_fork!
+        pid = Process.pid
+        return if @pid == pid
+
+        @pid = pid
+        after_fork!
+      end
+
+      # Whether Rails adapter hooks (middleware / exception notification /
+      # logger bridge) should activate. False until an init() with rails:true
+      # runs, so merely bundling the gem never installs global Rails hooks —
+      # the railtie checks this in after_initialize (opt-out symmetry with
+      # sidekiq:/rollbar:).
+      def rails_enabled?
+        @rails_enabled == true
+      end
+
+      # --- registries (used by Instance#shutdown and the pipelines) ---------
+
+      def flush_foam_pipelines
+        flushables = @flushables.dup
+        flushables << @fallback_meter_provider if @fallback_meter_provider
+        flushables.each do |flushable|
+          flushable.force_flush
+        rescue StandardError
+          nil
+        end
+      end
+
+      def forget_provider(provider)
+        @foam_providers.delete_if { |p| p.equal?(provider) }
+        @flushables.delete_if { |p| p.equal?(provider) }
+      end
+
+      def clear_fallback_meter_provider_if_in(providers)
+        return unless @fallback_meter_provider
+
+        @fallback_meter_provider = nil if providers.any? { |p| p.equal?(@fallback_meter_provider) }
+      end
+
+      # Test hook: full reset of module state (NOT for production use — OTel
+      # globals cannot be re-registered after a real shutdown).
+      def reset_for_tests!
+        @instances = {}
+        @foam_providers = []
+        @attached_providers = []
+        @flushables = []
+        @fallback_meter_provider = nil
+        @metric_readers = []
+        @pid = Process.pid
+        @rails_enabled = false
+        self.active_config = DEFAULT_CONFIG
+      end
+
+      private
+
+      def remember(instance)
+        @instances[instance.service_name] = instance
+        instance
+      end
+
+      def foam_provider?(provider)
+        @foam_providers.any? { |p| p.equal?(provider) }
+      end
+
+      def attached?(provider)
+        @attached_providers.any? { |p| p.equal?(provider) }
+      end
+
+      def auto_wire(sidekiq:, rollbar:, rails:)
+        # install! calls are individually idempotent, so a later init() can
+        # still wire an integration an earlier one opted out of.
+        @rails_enabled ||= rails
+        Vendor::Rollbar.install! if rollbar
+        if sidekiq && defined?(::Sidekiq) && ::Sidekiq.respond_to?(:configure_server)
+          require_relative "sidekiq"
+          Foam::Otel::Sidekiq.install!
+        end
+        # Rails hooks activate lazily in the railtie's after_initialize once
+        # rails_enabled? is true (see railtie.rb).
+      rescue StandardError => e
+        warn "[foam] adapter auto-wiring failed: #{e.class}: #{e.message}"
+      end
+
+      def setup_traces(endpoint, headers, resource)
+        current = OpenTelemetry.tracer_provider
+        return nil if foam_provider?(current)
+
+        exporter = OpenTelemetry::Exporter::OTLP::Exporter.new(
+          endpoint: "#{endpoint}/v1/traces", headers: headers
+        )
+        if current.is_a?(OpenTelemetry::SDK::Trace::TracerProvider)
+          return nil if attached?(current)
+
+          # Another SDK registered a real provider — attach foam's pipeline to
+          # it rather than displacing it (SPEC section 9).
+          current.add_span_processor(StampSpanProcessor.new)
+          batch = OpenTelemetry::SDK::Trace::Export::BatchSpanProcessor.new(exporter)
+          current.add_span_processor(batch)
+          @attached_providers << current
+          @flushables << batch
+          return batch
+        end
+
+        provider = OpenTelemetry::SDK::Trace::TracerProvider.new(resource: resource)
+        provider.add_span_processor(StampSpanProcessor.new)
+        provider.add_span_processor(OpenTelemetry::SDK::Trace::Export::BatchSpanProcessor.new(exporter))
+        OpenTelemetry.tracer_provider = provider
+        @foam_providers << provider
+        @flushables << provider
+        provider
+      end
+
+      def setup_logs(endpoint, headers, resource)
+        current = OpenTelemetry.logger_provider
+        return nil if foam_provider?(current)
+
+        exporter = OpenTelemetry::Exporter::OTLP::Logs::LogsExporter.new(
+          endpoint: "#{endpoint}/v1/logs", headers: headers
+        )
+        if current.is_a?(OpenTelemetry::SDK::Logs::LoggerProvider)
+          return nil if attached?(current)
+
+          current.add_log_record_processor(StampLogRecordProcessor.new)
+          batch = OpenTelemetry::SDK::Logs::Export::BatchLogRecordProcessor.new(exporter)
+          current.add_log_record_processor(batch)
+          @attached_providers << current
+          @flushables << batch
+          return batch
+        end
+
+        provider = OpenTelemetry::SDK::Logs::LoggerProvider.new(resource: resource)
+        provider.add_log_record_processor(StampLogRecordProcessor.new)
+        provider.add_log_record_processor(OpenTelemetry::SDK::Logs::Export::BatchLogRecordProcessor.new(exporter))
+        OpenTelemetry.logger_provider = provider
+        @foam_providers << provider
+        @flushables << provider
+        provider
+      end
+
+      def setup_metrics(endpoint, headers, resource)
+        current = OpenTelemetry.meter_provider
+        return nil if foam_provider?(current)
+        return nil if @fallback_meter_provider
+
+        exporter = OpenTelemetry::Exporter::OTLP::Metrics::MetricsExporter.new(
+          endpoint: "#{endpoint}/v1/metrics", headers: headers
+        )
+        reader = OpenTelemetry::SDK::Metrics::Export::PeriodicMetricReader.new(exporter: exporter)
+        provider = OpenTelemetry::SDK::Metrics::MeterProvider.new(resource: resource)
+        provider.add_metric_reader(reader)
+        @metric_readers << reader
+
+        # Ruby's global meter_provider setter does not refuse replacement the
+        # way Python's does — so foam refuses for it: when another real SDK
+        # MeterProvider owns the global, keep foam's as the fallback served by
+        # Foam::Otel.meter (SPEC section 9) instead of displacing theirs.
+        if current.is_a?(OpenTelemetry::SDK::Metrics::MeterProvider)
+          @fallback_meter_provider = provider
+          warn "[foam] another MeterProvider is already registered globally — " \
+               "foam metrics are available through Foam::Otel.meter only; " \
+               "metrics created via the OTel metrics API will not export to foam"
+        else
+          OpenTelemetry.meter_provider = provider
+          @foam_providers << provider
+          @flushables << provider
+        end
+        provider
+      end
+    end
+  end
+end

data/lib/foam/otel/logger_bridge.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+require "logger"
+
+require_relative "constants"
+
+module Foam
+  module Otel
+    # Rails.logger bridge — a broadcast target (Rails 7.1+ BroadcastLogger)
+    # that re-emits every log line as an OTel log record stamped log.rails.
+    # Attached via `Rails.logger.broadcast_to(bridge)` so the app's own logger
+    # chain (devices, formatters, TaggedLogging tags) is never wrapped or
+    # altered; trace correlation comes from the active context through the
+    # stamp/batch pipeline.
+    class LoggerBridge < ::Logger
+      SEVERITY_TEXT = { 0 => "DEBUG", 1 => "INFO", 2 => "WARN", 3 => "ERROR", 4 => "FATAL", 5 => "UNKNOWN" }.freeze
+      # OTel severity numbers: DEBUG 5, INFO 9, WARN 13, ERROR 17, FATAL 21.
+      SEVERITY_NUMBER = { 0 => 5, 1 => 9, 2 => 13, 3 => 17, 4 => 21, 5 => 1 }.freeze
+
+      def initialize(tagged_source: nil)
+        super(nil) # no device — emission goes to the OTel logs pipeline
+        @tagged_source = tagged_source
+      end
+
+      # Memoized so the hot per-line path is an ivar read, not a
+      # LoggerProvider#logger call (which takes a registry mutex + allocates
+      # a lookup key on every call).
+      def otel_logger
+        @otel_logger ||= Foam::Otel.logger("foam-otel/rails")
+      end
+
+      def add(severity, message = nil, progname = nil, &block)
+        # The bridge is attached unconditionally by the railtie; it stays
+        # inert until init(rails: true) and honors rails: false.
+        return true unless Foam::Otel.rails_enabled?
+
+        severity ||= ::Logger::UNKNOWN
+        return true if severity < level
+
+        body = message || (block ? yield : progname)
+        return true if body.nil?
+
+        attributes = { INSTRUMENTATION_KEY => STAMPS::LOG_RAILS }
+        tags = current_tags
+        attributes["rails.tags"] = tags.join(" ") unless tags.empty?
+
+        otel_logger.on_emit(
+          severity_text: SEVERITY_TEXT.fetch(severity, "UNKNOWN"),
+          severity_number: SEVERITY_NUMBER.fetch(severity, 1),
+          timestamp: Time.now,
+          body: body.to_s,
+          attributes: attributes,
+          context: OpenTelemetry::Context.current
+        )
+        true
+      rescue StandardError
+        true # the bridge must never break application logging
+      end
+
+      private
+
+      # TaggedLogging tags (e.g. the request_id from config.log_tags) live on
+      # the SOURCE logger's formatter; the bridge reads them without touching
+      # the source chain.
+      def current_tags
+        formatter = @tagged_source&.formatter
+        return [] unless formatter.respond_to?(:current_tags)
+
+        Array(formatter.current_tags).map(&:to_s)
+      rescue StandardError
+        []
+      end
+    end
+  end
+end