rails_mind 0.1.0

data/lib/rails_mind/client.rb

@@ -0,0 +1,123 @@
+require "securerandom"
+require "time"
+require "digest"
+
+module RailsMind
+  class Client
+    KINDS = %w[request span error event visit flag job check].freeze
+    FIELDS = %i[id kind occurred_at name duration_ms status release trace_id span_id parent_span_id request_id job_id visitor_id user_id account_id properties].freeze
+    UUID = /\A[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}\z/i
+    attr_reader :config, :collector
+
+    def initialize(config, collector: nil)
+      @config = config.validate!
+      @redactor = Redactor.new
+      @collector = collector || (Collector.new(config) if config.enabled?)
+      @error_mutex = Mutex.new
+      @reported_errors = ObjectSpace::WeakMap.new
+    end
+
+    def emit(kind, name, properties: {}, **attributes)
+      return false if !collector || Context.suppressed? || !enabled_signal?(kind)
+      event = Context.snapshot.merge(otel_context).merge(attributes.slice(*FIELDS))
+      event.merge!(kind: kind.to_s, name: name.to_s, properties: properties,
+        id: stable_id(attributes[:id]), occurred_at: timestamp(attributes[:occurred_at]), release: config.release)
+      event = event.reject { |_, value| value.nil? }
+      check_id = event[:id] if kind.to_s == "check"
+      event = @redactor.call(event)
+      event = config.before_send.call(event) if config.before_send
+      return false unless event.is_a?(Hash)
+      # Hooks cannot add protocol keys or bypass the final redaction pass.
+      event = @redactor.call(event.transform_keys(&:to_s).slice(*FIELDS.map(&:to_s)))
+      if check_id
+        return false unless event["kind"] == "check" && event["id"] == check_id
+        event = event.slice("id", "kind", "occurred_at", "name", "properties")
+        event["properties"] = event["properties"].slice("sdk_version") if event["properties"].is_a?(Hash)
+      end
+      return false unless valid_event?(event)
+      collector.push(event)
+    rescue StandardError
+      false
+    end
+
+    def capture_exception(error, handled: false, severity: :error, context: {}, source: nil, **_options)
+      return false unless config.errors
+      # Rails reports an exception through more than one boundary. A weak key map
+      # avoids retaining exceptions; identity dedup applies only to this object.
+      @error_mutex.synchronize do
+        return false if @reported_errors.key?(error)
+        @reported_errors[error] = true
+      end
+      message = config.capture_exception_message ? @redactor.scrub(error.message.to_s) : "[Message omitted]"
+      frames = Array(error.backtrace).first(40).map { |frame| safe_frame(frame) }
+      Context.with(context.slice(*Context::KEYS)) do
+        emit(:error, error.class.name, status: "error", properties: {
+          exception_class: error.class.name, message: message, backtrace: frames,
+          handled: handled, severity: severity.to_s, source: source
+        })
+      end
+    rescue StandardError
+      false
+    end
+
+    def stable_id(value = nil)
+      return SecureRandom.uuid unless value
+      return value.to_s.downcase if value.to_s.match?(UUID)
+      # Deterministic UUID-shaped ID for existing Ahoy installations using ULIDs.
+      hex = Digest::SHA256.hexdigest("rails_mind:#{value}")[0, 32]
+      hex[12] = "8"
+      hex[16] = "8"
+      [ hex[0, 8], hex[8, 4], hex[12, 4], hex[16, 4], hex[20, 12] ].join("-")
+    end
+
+    private
+
+    def valid_event?(event)
+      return false unless KINDS.include?(event["kind"]) && event["id"].to_s.match?(UUID) && event["properties"].is_a?(Hash)
+      return false unless event["name"].is_a?(String) && !event["name"].empty?
+      # One malformed field must not poison a whole batch at the hosted boundary.
+      (FIELDS - %i[duration_ms properties]).each do |field|
+        key = field.to_s
+        next if event[key].nil?
+        return false unless event[key].is_a?(String)
+        event[key] = event[key].byteslice(0, 500).scrub("")
+      end
+      event["name"] = event["name"][0, 200]
+      Time.iso8601(event["occurred_at"])
+      duration = event["duration_ms"]
+      duration.nil? || ((duration.is_a?(Integer) || duration.is_a?(Float)) && duration.finite? && duration >= 0 && duration < 86_400_000)
+    end
+
+    def enabled_signal?(kind)
+      case kind.to_s
+      when "check" then true
+      when "request", "span", "job" then config.apm
+      when "error" then config.errors
+      when "event", "visit" then config.analytics
+      when "flag" then config.flags
+      else false
+      end
+    end
+
+    def timestamp(value)
+      time = value.respond_to?(:iso8601) ? value : (value ? Time.iso8601(value.to_s) : Time.now)
+      time.iso8601(6)
+    end
+
+    def safe_frame(frame)
+      frame = frame.to_s
+      frame = frame.delete_prefix("#{Rails.root}/") if defined?(Rails) && Rails.respond_to?(:root) && Rails.root
+      # Remove machine/user home paths, retaining source filename + line + method.
+      frame = frame.sub(%r{\A.*?/(app|lib|config|test|spec)/}, '\\1/')
+      frame = frame.sub(%r{\A/(?:[^/:]+/)*([^/:]+:\d+)}, '\\1')
+      @redactor.scrub(frame)
+    end
+
+    def otel_context
+      return {} unless defined?(::OpenTelemetry::Trace)
+      context = ::OpenTelemetry::Trace.current_span.context
+      return {} unless context.valid?
+      { trace_id: context.hex_trace_id, span_id: context.hex_span_id }
+    end
+  end
+end

data/lib/rails_mind/collector.rb

@@ -0,0 +1,153 @@
+module RailsMind
+  class Collector
+    def initialize(config, transport: Transport.new(config), autostart: true)
+      @config, @transport, @autostart = config, transport, autostart
+      reset_process
+    end
+
+    def push(event)
+      check_process
+      json = JSON.generate(event)
+      @mutex.synchronize do
+        reason = if @closed then :closed
+        elsif json.bytesize > @config.max_event_bytes || json.bytesize + 13 > @config.max_batch_bytes then :oversize
+        elsif @queue.size + @in_flight >= @config.queue_capacity then :overflow
+        end
+        if reason
+          drop(event[:kind] || event["kind"], reason)
+          return false
+        end
+        @queue << [ json.freeze, event[:kind] || event["kind"] ]
+        @stats[:enqueued] += 1
+        start_worker if @autostart
+        @condition.broadcast if @queue.size >= @config.batch_size
+        true
+      end
+    end
+
+    def stats
+      check_process
+      @mutex.synchronize { @stats.merge(queued: @queue.size, in_flight: @in_flight, losses: @losses.dup) }
+    end
+
+    def flush(timeout: @config.shutdown_timeout)
+      check_process
+      deadline = monotonic + timeout
+      @mutex.synchronize do
+        start_worker
+        @force_flush = true
+        @condition.broadcast
+        while @queue.any? || @in_flight.positive?
+          remaining = deadline - monotonic
+          return false if remaining <= 0
+          @condition.wait(@mutex, remaining)
+        end
+        true
+      end
+    end
+
+    def shutdown(timeout: @config.shutdown_timeout)
+      check_process
+      @mutex.synchronize { @closed = true }
+      success = flush(timeout: timeout)
+      @mutex.synchronize { @stopping = true; @condition.broadcast }
+      @worker&.join(0.05)
+      unless success
+        @worker&.kill
+        @worker&.join
+        @mutex.synchronize do
+          @queue.each { |_, kind| drop(kind, :shutdown) }
+          @queue.clear
+          @active_batch.to_a.each { |_, kind| drop(kind, :shutdown) }
+          @active_batch = nil
+          @in_flight = 0
+        end
+      end
+      success
+    end
+
+    private
+
+    def reset_process
+      @pid = Process.pid
+      @mutex = Mutex.new
+      @condition = ConditionVariable.new
+      @queue, @losses = [], Hash.new(0)
+      @stats = { enqueued: 0, delivered: 0, dropped: 0, retried: 0 }
+      @in_flight = 0
+      @worker = @active_batch = nil
+      @closed = @stopping = @force_flush = false
+    end
+
+    # Never resend a parent's inherited queue after Puma/worker forks.
+    def check_process
+      reset_process if @pid != Process.pid
+    end
+    def monotonic = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+
+    def start_worker
+      return if @worker&.alive?
+      @worker = Thread.new { run }
+      @worker.name = "rails_mind"
+      @worker.report_on_exception = false
+    end
+
+    def run
+      loop do
+        batch = @mutex.synchronize do
+          @condition.wait(@mutex, @config.flush_interval) if @queue.size < @config.batch_size && !@force_flush && !@stopping
+          return if @stopping && @queue.empty?
+          take_batch
+        end
+        next if batch.empty?
+        result = deliver(batch)
+        @mutex.synchronize do
+          if result
+            @stats[:delivered] += batch.size
+          else
+            batch.each { |_, kind| drop(kind, :delivery) }
+          end
+          @in_flight = 0
+          @active_batch = nil
+          @force_flush = false if @queue.empty?
+          @condition.broadcast
+        end
+      end
+    end
+
+    def take_batch
+      batch = []
+      bytes = 13
+      while batch.size < @config.batch_size && @queue.any?
+        entry = @queue.first
+        break if bytes + entry.first.bytesize + (batch.empty? ? 0 : 1) > @config.max_batch_bytes
+        bytes += entry.first.bytesize + (batch.empty? ? 0 : 1)
+        batch << @queue.shift
+      end
+      @in_flight = batch.size
+      @active_batch = batch
+      batch
+    end
+
+    def deliver(batch)
+      body = '{"events":[' + batch.map(&:first).join(",") + ']}'
+      attempts = 0
+      loop do
+        result = @transport.send_batch(body)
+        return true if result.success
+        return false unless result.retryable && attempts < @config.max_retries
+        delay = result.retry_after || @config.retry_base * (2**attempts) * (0.75 + rand * 0.5)
+        attempts += 1
+        @mutex.synchronize { @stats[:retried] += 1 }
+        sleep(delay) if delay.positive?
+      end
+    rescue StandardError
+      false # Telemetry errors cannot escape into the customer app.
+    end
+
+    def drop(kind, reason)
+      @stats[:dropped] += 1
+      @losses["#{kind}.#{reason}"] += 1
+    end
+  end
+end

data/lib/rails_mind/configuration.rb

@@ -0,0 +1,81 @@
+require "uri"
+
+module RailsMind
+  class Configuration
+    DEFAULT_ENDPOINT = "https://railsmind.com".freeze
+    RELEASE_ENV_VARS = %w[RAILS_MIND_RELEASE GIT_REVISION RENDER_GIT_COMMIT
+      RAILWAY_GIT_COMMIT_SHA HEROKU_BUILD_COMMIT HEROKU_SLUG_COMMIT KAMAL_VERSION].freeze
+
+    attr_accessor :endpoint, :token, :release, :apm, :errors, :analytics, :flags,
+      :queue_capacity, :batch_size, :max_batch_bytes, :max_event_bytes, :flush_interval,
+      :max_retries, :retry_base, :open_timeout, :read_timeout, :shutdown_timeout,
+      :before_send, :capture_exception_message
+
+    def initialize(env: ENV, root: nil)
+      @endpoint = nonblank(env["RAILS_MIND_ENDPOINT"]) || DEFAULT_ENDPOINT
+      @token = env["RAILS_MIND_KEY"]
+      @release = release_from_env(env) || release_from_file(root)
+      @apm = @errors = @analytics = @flags = true
+      @queue_capacity = 1_000
+      @batch_size = 100
+      @max_batch_bytes = 256 * 1024
+      @max_event_bytes = 16 * 1024
+      @flush_interval = 2.0
+      @max_retries = 3
+      @retry_base = 0.25
+      @open_timeout = 1.0
+      @read_timeout = 2.0
+      @shutdown_timeout = 2.0
+      @capture_exception_message = false
+    end
+
+    def enabled? = !token.to_s.strip.empty? && !endpoint.to_s.strip.empty?
+
+    def validate!
+      return self unless enabled?
+      uri = URI(endpoint)
+      loopback = %w[localhost 127.0.0.1 ::1].include?(uri.hostname)
+      raise ArgumentError, "endpoint must use HTTPS (HTTP only on loopback)" unless uri.is_a?(URI::HTTPS) || (uri.is_a?(URI::HTTP) && loopback)
+      raise ArgumentError, "endpoint must not contain credentials, query, or fragment" if uri.userinfo || uri.query || uri.fragment
+      raise ArgumentError, "batch_size must be 1..100" unless (1..100).cover?(batch_size)
+      raise ArgumentError, "max_batch_bytes must be 1024..262144" unless (1024..262_144).cover?(max_batch_bytes)
+      raise ArgumentError, "queue_capacity must be positive" unless queue_capacity.positive?
+      raise ArgumentError, "max_retries must be 0..5" unless (0..5).cover?(max_retries)
+      [ flush_interval, open_timeout, read_timeout, shutdown_timeout ].each do |value|
+        raise ArgumentError, "timeouts must be positive" unless value.positive?
+      end
+      self
+    end
+
+    private
+
+    def nonblank(value)
+      value = value.to_s.strip
+      value unless value.empty?
+    end
+
+    def release_from_env(env)
+      RELEASE_ENV_VARS.each do |name|
+        value = nonblank(env[name])
+        next unless value
+        # Kamal permits arbitrary version labels; Assist needs a Git revision.
+        next if name == "KAMAL_VERSION" && !value.match?(/\A(?:[a-f0-9]{40}|[a-f0-9]{64})\z/i)
+        return value
+      end
+      nil
+    end
+
+    def release_from_file(root)
+      root ||= Rails.root if defined?(Rails) && Rails.respond_to?(:root)
+      return unless root
+      path = File.join(root, "REVISION")
+      return unless File.file?(path)
+      # Hatchbox/Capistrano deployments may have no Git checkout at runtime.
+      value = File.read(path, 501).force_encoding(Encoding::UTF_8)
+      return if value.bytesize > 500 || !value.valid_encoding?
+      nonblank(value)
+    rescue SystemCallError, IOError
+      nil
+    end
+  end
+end

data/lib/rails_mind/context.rb

@@ -0,0 +1,35 @@
+module RailsMind
+  module Context
+    KEYS = %i[request_id job_id trace_id span_id parent_span_id visitor_id user_id account_id].freeze
+    module_function
+
+    # Thread#[] is fiber-local. Every request/job boundary restores its previous context.
+    def current = Thread.current[:rails_mind_context] ||= {}
+    def snapshot = current.select { |key, _| KEYS.include?(key) }.dup
+
+    def with(values)
+      previous = current
+      identifiers = values.transform_keys(&:to_sym).slice(*KEYS).transform_values do |value|
+        value.to_s if value.is_a?(String) || value.is_a?(Integer) || value.is_a?(Symbol)
+      end
+      Thread.current[:rails_mind_context] = previous.merge(identifiers)
+      yield
+    ensure
+      Thread.current[:rails_mind_context] = previous
+    end
+
+    def identify(user_id: nil, account_id: nil, visitor_id: nil)
+      current.merge!(user_id: user_id&.to_s, account_id: account_id&.to_s, visitor_id: visitor_id&.to_s)
+    end
+
+    def suppressed? = Thread.current[:rails_mind_suppressed] == true
+
+    def suppress
+      previous = Thread.current[:rails_mind_suppressed]
+      Thread.current[:rails_mind_suppressed] = true
+      yield
+    ensure
+      Thread.current[:rails_mind_suppressed] = previous
+    end
+  end
+end

data/lib/rails_mind/diagnostic.rb

@@ -0,0 +1,39 @@
+require "json"
+require "bundler"
+
+module RailsMind
+  class Diagnostic
+    GEMS = %w[rails ahoy_matey flipper opentelemetry-sdk opentelemetry-instrumentation-rails
+      opentelemetry-instrumentation-pg opentelemetry-instrumentation-net_http good_job sidekiq
+      solid_queue delayed_job sentry-rails honeybadger bugsnag rollbar bullet prosopite field_test].freeze
+
+    def initialize(root: Dir.pwd, config: RailsMind.configuration)
+      @root, @config = root, config
+    end
+
+    def report
+      lockfile = File.join(@root, "Gemfile.lock")
+      versions = File.exist?(lockfile) ? Bundler::LockfileParser.new(File.read(lockfile)).specs.to_h { |spec| [ spec.name, spec.version.to_s ] } : {}
+      detected = GEMS.to_h { |name| [ name, versions[name] ] }
+      {
+        sdk: VERSION, ruby: RUBY_VERSION, detected: detected.compact,
+        credential_present: !@config.token.to_s.strip.empty?,
+        endpoint_present: !@config.endpoint.to_s.strip.empty?,
+        release_present: !@config.release.to_s.strip.empty?,
+        enabled: @config.enabled?,
+        plan: [
+          "Add one initializer. No database migrations or Gemfile changes.",
+          "Requests and jobs: unsampled measurements via Rails notifications; errors via Rails.error.",
+          detected["ahoy_matey"] ? "Ahoy detected: keep current store; explicitly opt into mirror mode after review." : "Analytics: optionally add ahoy_matey; choose hosted-only store or existing database store.",
+          detected["opentelemetry-sdk"] ? "OpenTelemetry detected: attach RailsMind exporter after existing SDK setup; preserve sampler and exporters." : "APM traces: optionally add selected OpenTelemetry libraries and explicitly configure one provider.",
+          detected["flipper"] ? "Flipper detected: observe notifications only; preserve adapter, groups, targeting and cache." : "Flags: Flipper is optional. No flag configuration is created.",
+          "Existing error reporters stay installed. RailsMind deduplicates its own collector only.",
+          "Browser: optional Ahoy adapter; enable only after checking existing pageview handlers.",
+          "Business/request/error signals are not sampled; bounded queue losses remain possible. Inspect RailsMind.stats."
+        ],
+        limitations: [ "Compatibility applies to tested versions only; this is not a historical import.",
+          "No network check is performed and credential values are never printed." ]
+      }
+    end
+  end
+end

data/lib/rails_mind/installation_check.rb

@@ -0,0 +1,38 @@
+require_relative "../rails_mind"
+
+module RailsMind
+  class InstallationCheck
+    def initialize(config = RailsMind.configuration, transport: nil)
+      @config, @transport = config, transport
+    end
+
+    def run(timeout: 10)
+      return result(false, "Set RAILS_MIND_KEY in your app's environment, then try again. The endpoint defaults to https://railsmind.com; if you override it, provide a nonblank endpoint.") unless @config.enabled?
+      @config.validate!
+      # A dedicated collector gives this command an exact result without flushing
+      # or changing the running application's collector or its existing counters.
+      collector = Collector.new(@config, transport: @transport || Transport.new(@config), autostart: false)
+      client = Client.new(@config, collector: collector)
+      id = SecureRandom.uuid
+      unless client.emit(:check, "RailsMind installation check", id: id, properties: { sdk_version: VERSION })
+        return result(false, "The SDK did not enqueue the check. Review before_send and collector settings.", id)
+      end
+      unless collector.flush(timeout: timeout)
+        return result(false, "Delivery was not confirmed before the deadline. Check outbound HTTPS access and the endpoint, then look for this ID in Setup before retrying.", id)
+      end
+      if collector.stats[:delivered] == 1 && collector.stats[:dropped].zero?
+        result(true, "Check delivered. Open RailsMind Setup for your app and environment and match this ID. Installation is verified when it says Check processed.", id)
+      else
+        result(false, "Delivery failed. Check the endpoint, active ingest key, daily quota, and server support for installation checks. Run rails_mind:doctor for local settings.", id)
+      end
+    ensure
+      collector&.shutdown(timeout: 0.05)
+    end
+
+    private
+
+    def result(success, message, id = nil)
+      { success: success, check_id: id, message: message }
+    end
+  end
+end

data/lib/rails_mind/integrations/ahoy.rb

@@ -0,0 +1,68 @@
+require "ahoy"
+
+module RailsMind
+  module Integrations
+    module AhoyDelivery
+      def rails_mind_visit(data)
+        RailsMind.client.emit(:visit, "$visit", id: data[:visit_token], occurred_at: data[:started_at],
+          visitor_id: data[:visitor_token], user_id: data[:user_id]&.to_s,
+          properties: data.slice(:referring_domain, :utm_source, :utm_medium, :utm_campaign, :browser, :os, :device_type))
+      rescue StandardError
+        false
+      end
+
+      def rails_mind_event(data)
+        RailsMind.client.emit(:event, data[:name], id: data[:event_id], occurred_at: data[:time],
+          visitor_id: ahoy&.visitor_token, user_id: data[:user_id]&.to_s,
+          properties: data.fetch(:properties, {}).merge(visit_id: data[:visit_token]))
+      rescue StandardError
+        false
+      end
+
+      def rails_mind_authenticate(data)
+        RailsMind.client.emit(:event, "$identify", visitor_id: ahoy&.visitor_token,
+          user_id: data[:user_id]&.to_s, properties: { visit_id: data[:visit_token] })
+      rescue StandardError
+        false
+      end
+    end
+
+    # Explicit hosted-only option. Set `class Ahoy::Store < ...` in the app.
+    # This intentionally has no visit ActiveRecord model or geocoding persistence.
+    class AhoyStore < ::Ahoy::BaseStore
+      include AhoyDelivery
+
+      def track_visit(data) = rails_mind_visit(data)
+      def track_event(data) = rails_mind_event(data)
+      def authenticate(data) = rails_mind_authenticate(data)
+    end
+
+    # Explicit coexistence option. Prepend once to the customer's existing Store.
+    # The existing store runs first; its arguments, exceptions and return value survive.
+    module AhoyMirror
+      include AhoyDelivery
+
+      def track_visit(data)
+        result = super
+        rails_mind_visit(data)
+        result
+      end
+
+      def track_event(data)
+        result = super
+        rails_mind_event(data)
+        result
+      end
+
+      def authenticate(data)
+        result = super
+        rails_mind_authenticate(data)
+        result
+      end
+    end
+
+    def self.mirror_ahoy!(store = ::Ahoy::Store)
+      store.prepend(AhoyMirror) unless store.ancestors.include?(AhoyMirror)
+    end
+  end
+end

data/lib/rails_mind/integrations/open_telemetry.rb

@@ -0,0 +1,77 @@
+require "opentelemetry/sdk"
+
+module RailsMind
+  module Integrations
+    module OpenTelemetry
+      SAFE_ATTRIBUTES = %w[http.request.method http.method http.response.status_code http.status_code http.route
+        db.system db.system.name db.operation db.operation.name server.address server.port
+        code.function code.namespace code.filepath code.lineno messaging.system messaging.destination.name].freeze
+
+      # A local exporter: export only enqueues sanitized data in the shared bounded
+      # collector. SimpleSpanProcessor therefore performs no application-thread I/O.
+      class Exporter
+        def export(spans, timeout: nil)
+          return success if Context.suppressed?
+          spans.each do |span|
+            attributes = span.attributes || {}
+            safe = attributes.slice(*SAFE_ATTRIBUTES)
+            context = Context::KEYS.each_with_object({}) do |key, values|
+              value = attributes["rails_mind.#{key}"]
+              values[key] = value if value
+            end
+            RailsMind.client.emit(:span, safe_name(span, attributes), occurred_at: Time.at(Rational(span.start_timestamp, 1_000_000_000)).utc,
+              duration_ms: (span.end_timestamp - span.start_timestamp) / 1_000_000.0,
+              status: span.status.code == ::OpenTelemetry::Trace::Status::ERROR ? "error" : "ok",
+              trace_id: span.trace_id.unpack1("H*"), span_id: span.span_id.unpack1("H*"),
+              parent_span_id: span.parent_span_id.unpack1("H*"), properties: safe, **context.except(:trace_id, :span_id, :parent_span_id))
+          end
+          success
+        rescue StandardError
+          ::OpenTelemetry::SDK::Trace::Export::FAILURE
+        end
+
+        def force_flush(timeout: nil)
+          RailsMind.flush(timeout: timeout || RailsMind.configuration.shutdown_timeout) ? success : ::OpenTelemetry::SDK::Trace::Export::TIMEOUT
+        end
+
+        # The SDK owns the collector lifetime; never shut down another provider.
+        def shutdown(timeout: nil) = force_flush(timeout: timeout)
+
+        private
+
+        def success = ::OpenTelemetry::SDK::Trace::Export::SUCCESS
+
+        def safe_name(span, attributes)
+          if attributes["db.system"] || attributes["db.system.name"]
+            "db.#{attributes['db.operation'] || attributes['db.operation.name'] || 'query'}"
+          elsif attributes["http.route"]
+            "#{attributes['http.request.method'] || attributes['http.method']} #{attributes['http.route']}"
+          elsif attributes["http.method"] || attributes["http.request.method"]
+            "http.#{attributes['http.request.method'] || attributes['http.method']}"
+          else
+            # Span names can contain URLs, SQL, or user strings. Scope is bounded
+            # library metadata; customers can add reviewed code attributes instead.
+            span.instrumentation_scope&.name || "span"
+          end
+        end
+      end
+
+      class ContextProcessor < ::OpenTelemetry::SDK::Trace::Export::SimpleSpanProcessor
+        def on_start(span, parent_context)
+          Context.snapshot.each { |key, value| span.set_attribute("rails_mind.#{key}", value.to_s) if value }
+        rescue StandardError
+          nil
+        end
+      end
+
+      def self.attach!(provider: ::OpenTelemetry.tracer_provider)
+        raise ArgumentError, "Configure an OpenTelemetry SDK provider first; RailsMind never replaces an existing provider" unless provider.respond_to?(:add_span_processor)
+        return provider if provider.instance_variable_defined?(:@rails_mind_processor)
+        processor = ContextProcessor.new(Exporter.new)
+        provider.add_span_processor(processor)
+        provider.instance_variable_set(:@rails_mind_processor, processor)
+        provider
+      end
+    end
+  end
+end