rails-otel-context 0.5.0

data/lib/rails_otel_context/call_context_processor.rb

@@ -0,0 +1,153 @@
+# frozen_string_literal: true
+
+module RailsOtelContext
+  # SpanProcessor that enriches all spans with the calling Ruby class and method name,
+  # and optionally with user-defined custom attributes.
+  #
+  # Sets two attributes on every span (unless the call stack yields no app-code frame):
+  #   - code.namespace  – the class name, e.g. "OrderService", "InvoiceJob"
+  #   - code.function   – the method name, e.g. "create", "perform"
+  #
+  # Class names are extracted from the frame label when available (e.g. "User.find"),
+  # and inferred from the file-path basename otherwise (e.g. order_service.rb → OrderService).
+  #
+  # Frames inside gems or outside app_root are always skipped.
+  #
+  # Custom attributes (configured via +custom_span_attributes+) are applied to every span.
+  # The callable must return a Hash (or nil) and must be fast — it runs in the hot path
+  # of every span creation. Exceptions in the callable are silently rescued to avoid
+  # disrupting application request processing.
+  class CallContextProcessor
+    SPAN_CONTROLLER_ATTR = 'request.controller'
+    SPAN_ACTION_ATTR     = 'request.action'
+    AR_MODEL_ATTR        = 'code.activerecord.model'
+    AR_METHOD_ATTR       = 'code.activerecord.method'
+    AR_SCOPE_ATTR        = 'code.activerecord.scope'
+    ORIG_NAME_ATTR       = 'l9.orig.name'
+
+    def initialize(app_root:, config: RailsOtelContext.configuration)
+      @app_root = app_root.to_s
+      @call_context_enabled = config.call_context_enabled
+      @request_context_enabled = config.request_context_enabled
+      @custom_span_attributes = config.custom_span_attributes
+      @custom_span_attributes_enabled = config.custom_span_attributes_enabled
+      @span_name_formatter = config.span_name_formatter
+      @has_each_caller_location = Thread.respond_to?(:each_caller_location)
+    end
+
+    def on_start(span, _parent_context)
+      apply_call_context(span) if @call_context_enabled
+      apply_request_context(span) if @request_context_enabled
+      apply_db_context(span)
+      apply_custom_attributes(span) if @custom_span_attributes
+    end
+
+    def on_finish(_span); end
+
+    def force_flush(timeout: nil); end
+
+    def shutdown(timeout: nil); end
+
+    private
+
+    def apply_call_context(span)
+      return unless @has_each_caller_location
+
+      context = extract_caller_context
+      return unless context
+
+      span.set_attribute('code.namespace', context[:class_name])
+      span.set_attribute('code.function', context[:method_name]) if context[:method_name]
+      return unless context[:lineno]
+
+      span.set_attribute('code.filepath', context[:filepath])
+      span.set_attribute('code.lineno', context[:lineno])
+    end
+
+    def apply_request_context(span)
+      controller, action = RequestContext.fetch
+      return unless controller
+
+      span.set_attribute(SPAN_CONTROLLER_ATTR, controller)
+      span.set_attribute(SPAN_ACTION_ATTR, action) if action
+    end
+
+    def apply_db_context(span)
+      base_context = ActiveRecordContext.current
+      return unless base_context
+
+      # Shallow copy to avoid mutating the shared thread-local hash
+      ar_context = base_context.dup
+      enrich_ar_context(span, ar_context)
+      set_ar_attributes(span, ar_context)
+      apply_span_name_formatter(span, ar_context)
+    rescue StandardError
+      # Never let AR context or formatter errors break span processing
+    end
+
+    def enrich_ar_context(span, ar_context)
+      return unless span.respond_to?(:attributes)
+
+      ar_context[:code_namespace] = span.attributes['code.namespace']
+      ar_context[:code_function] = span.attributes['code.function']
+    end
+
+    def set_ar_attributes(span, ar_context)
+      span.set_attribute(AR_MODEL_ATTR, ar_context[:model_name]) if ar_context[:model_name]
+      span.set_attribute(AR_METHOD_ATTR, ar_context[:method_name]) if ar_context[:method_name]
+      span.set_attribute(AR_SCOPE_ATTR, ar_context[:scope_name]) if ar_context[:scope_name]
+    end
+
+    def apply_span_name_formatter(span, ar_context)
+      return unless @span_name_formatter
+
+      original_name = span.name
+      new_name = @span_name_formatter.call(original_name, ar_context)
+      return unless new_name && new_name != original_name && span.respond_to?(:name=)
+
+      span.set_attribute(ORIG_NAME_ATTR, original_name)
+      span.name = new_name
+    end
+
+    def apply_custom_attributes(span)
+      return unless @custom_span_attributes_enabled
+
+      attrs = @custom_span_attributes.call
+      return unless attrs.is_a?(Hash) && !attrs.empty?
+
+      attrs.each do |key, value|
+        span.set_attribute(key, value) unless value.nil?
+      end
+    rescue StandardError
+      # Never let a user-supplied callback break span processing.
+    end
+
+    def extract_caller_context
+      Thread.each_caller_location do |location|
+        path = location.absolute_path || location.path
+        next unless path&.start_with?(@app_root)
+        next if path.include?('/gems/')
+
+        label    = location.label || ''
+        lineno   = location.lineno
+        filepath = path.delete_prefix("#{@app_root}/")
+
+        # Try label first: "ClassName.method" or "ClassName#method"
+        if label =~ /^([A-Z][a-zA-Z0-9_]*(?:::[A-Z][a-zA-Z0-9_]*)*)(\.|\#)/
+          class_name  = Regexp.last_match(1)
+          method_name = label.split(/[.\#]/, 2).last
+                             &.sub(/^(?:block|rescue|ensure) in /, '')
+          return { class_name: class_name, method_name: method_name, lineno: lineno, filepath: filepath }
+        end
+
+        # Fallback: infer class from file-path basename (snake_case → CamelCase)
+        class_name  = File.basename(path, '.rb').split('_').map(&:capitalize).join
+        method_name = label.sub(/^(?:block|rescue|ensure) in /, '')
+        return { class_name: class_name, method_name: method_name.empty? ? nil : method_name,
+                 lineno: lineno, filepath: filepath }
+      end
+
+      nil
+    end
+  end
+end

data/lib/rails_otel_context/configuration.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+module RailsOtelContext
+  class Configuration
+    attr_accessor :pg_slow_query_enabled,
+                  :pg_slow_query_threshold_ms,
+                  :mysql2_slow_query_enabled,
+                  :mysql2_slow_query_threshold_ms,
+                  :trilogy_slow_query_enabled,
+                  :trilogy_slow_query_threshold_ms,
+                  :redis_source_enabled,
+                  :clickhouse_enabled,
+                  :clickhouse_slow_query_threshold_ms,
+                  :span_name_formatter,
+                  :call_context_enabled,
+                  :custom_span_attributes_enabled,
+                  :request_context_enabled
+
+    attr_reader :custom_span_attributes
+
+    def initialize
+      @pg_slow_query_enabled = true
+      @pg_slow_query_threshold_ms = 200.0
+      @mysql2_slow_query_enabled = true
+      @mysql2_slow_query_threshold_ms = 200.0
+      @trilogy_slow_query_enabled = true
+      @trilogy_slow_query_threshold_ms = 200.0
+      @redis_source_enabled = false
+      @clickhouse_enabled = true
+      @clickhouse_slow_query_threshold_ms = 200.0
+      @span_name_formatter = nil
+      @call_context_enabled = true
+      @custom_span_attributes = nil
+      @custom_span_attributes_enabled = true
+      @request_context_enabled = false
+    end
+
+    # Accepts a callable (lambda/proc) that returns a Hash of string keys to string values.
+    # The callable is invoked on every span start, so it must be fast.
+    # Returning nil or an empty hash is a no-op.
+    #
+    # Example:
+    #   config.custom_span_attributes = -> {
+    #     { "team" => Current.team } if Current.team.present?
+    #   }
+    def custom_span_attributes=(callable)
+      unless callable.nil? || callable.respond_to?(:call)
+        raise ArgumentError, 'custom_span_attributes must be a callable (lambda/proc) or nil'
+      end
+
+      @custom_span_attributes = callable
+    end
+  end
+end

data/lib/rails_otel_context/railtie.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+require 'rails_otel_context/adapters'
+require 'rails_otel_context/call_context_processor'
+
+module RailsOtelContext
+  class Railtie < Rails::Railtie
+    initializer 'rails_otel_context.configure' do
+      RailsOtelContext.apply_env_configuration!
+    end
+
+    initializer 'rails_otel_context.install_adapters' do
+      ActiveSupport.on_load(:active_record) do
+        RailsOtelContext::Adapters.install!(app_root: Rails.root, config: RailsOtelContext.configuration)
+        RailsOtelContext::ActiveRecordContext.install!
+      end
+    end
+
+    # Runs after config/initializers/ so the OTel SDK tracer_provider is already configured.
+    config.after_initialize do
+      otel_config = RailsOtelContext.configuration
+      needs_processor = otel_config.call_context_enabled ||
+                        otel_config.custom_span_attributes ||
+                        otel_config.request_context_enabled ||
+                        otel_config.span_name_formatter
+
+      if needs_processor && OpenTelemetry.tracer_provider.respond_to?(:add_span_processor)
+        processor = RailsOtelContext::CallContextProcessor.new(app_root: Rails.root)
+        OpenTelemetry.tracer_provider.add_span_processor(processor)
+      end
+    end
+
+    # Install request context capture on ActionController when it loads.
+    # Uses around_action with ensure for leak-proof cleanup on exceptions.
+    initializer 'rails_otel_context.install_request_context' do
+      ActiveSupport.on_load(:action_controller) do
+        if RailsOtelContext.configuration.request_context_enabled
+          around_action do |_controller, block|
+            RailsOtelContext::RequestContext.set(
+              controller: self.class.name,
+              action: action_name
+            )
+            block.call
+          ensure
+            RailsOtelContext::RequestContext.clear!
+          end
+        end
+      end
+    end
+  end
+end

data/lib/rails_otel_context/request_context.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module RailsOtelContext
+  # Thread-local storage for request-scoped context that gets propagated
+  # to all spans within a request. Uses raw Thread.current for minimal overhead —
+  # no object allocation, no mutex, ~5ns per read/write.
+  #
+  # Lifecycle:
+  #   1. Railtie's around_action sets controller + action at request start
+  #   2. CallContextProcessor reads them on every child span's on_start
+  #   3. around_action's ensure block clears them when the request ends
+  #
+  # Thread safety: each Puma thread has its own slot — no sharing, no contention.
+  module RequestContext
+    CONTROLLER_KEY = :_rails_otel_ctx_controller
+    ACTION_KEY     = :_rails_otel_ctx_action
+
+    class << self
+      def set(controller:, action:)
+        Thread.current[CONTROLLER_KEY] = controller
+        Thread.current[ACTION_KEY]     = action
+      end
+
+      # Returns [controller, action] in a single Thread.current access.
+      def fetch
+        t = Thread.current
+        [t[CONTROLLER_KEY], t[ACTION_KEY]]
+      end
+
+      def controller
+        Thread.current[CONTROLLER_KEY]
+      end
+
+      def action
+        Thread.current[ACTION_KEY]
+      end
+
+      def clear!
+        Thread.current[CONTROLLER_KEY] = nil
+        Thread.current[ACTION_KEY]     = nil
+      end
+    end
+  end
+end

data/lib/rails_otel_context/source_location.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module RailsOtelContext
+  # Shared helper for finding the first app-code source location in the call stack.
+  # Used by all DB adapters to attach source file/line to slow query spans.
+  module SourceLocation
+    def source_location_for_app
+      return unless Thread.respond_to?(:each_caller_location)
+
+      Thread.each_caller_location do |location|
+        path = location.absolute_path || location.path
+        next unless path&.start_with?(app_root)
+        next if path.include?('/gems/')
+
+        return [path.delete_prefix("#{app_root}/"), location.lineno]
+      end
+
+      nil
+    end
+  end
+end

data/lib/rails_otel_context/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module RailsOtelContext
+  VERSION = '0.5.0'
+end

data/lib/rails_otel_context.rb

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+# rails-otel-context is a Rails-specific gem
+# Skip Rails check in test environment to allow unit testing
+unless defined?(Rails) || ENV['RAILS_OTEL_CONTEXT_TEST']
+  raise LoadError, 'rails-otel-context requires Rails. This gem is designed for Rails applications only.'
+end
+
+require 'rails_otel_context/version'
+require 'rails_otel_context/configuration'
+require 'rails_otel_context/source_location'
+require 'rails_otel_context/activerecord_context'
+require 'rails_otel_context/adapters'
+require 'rails_otel_context/request_context'
+require 'rails_otel_context/call_context_processor'
+require 'rails_otel_context/railtie' if defined?(Rails::Railtie)
+
+module RailsOtelContext
+  class << self
+    def configuration
+      @configuration ||= Configuration.new
+    end
+
+    def configure
+      yield(configuration)
+    end
+
+    def reset_configuration!
+      @configuration = Configuration.new
+    end
+
+    def apply_env_configuration!(config = configuration)
+      config.pg_slow_query_enabled =
+        bool_env('RAILS_OTEL_CONTEXT_PG_SLOW_QUERY_ENABLED', config.pg_slow_query_enabled)
+      config.pg_slow_query_threshold_ms =
+        float_env('RAILS_OTEL_CONTEXT_PG_SLOW_QUERY_MS',
+                  float_env('OTEL_SLOW_QUERY_MS', config.pg_slow_query_threshold_ms))
+
+      config.mysql2_slow_query_enabled =
+        bool_env('RAILS_OTEL_CONTEXT_MYSQL2_SLOW_QUERY_ENABLED', config.mysql2_slow_query_enabled)
+      config.mysql2_slow_query_threshold_ms =
+        float_env('RAILS_OTEL_CONTEXT_MYSQL2_SLOW_QUERY_MS', config.mysql2_slow_query_threshold_ms)
+
+      config.trilogy_slow_query_enabled =
+        bool_env('RAILS_OTEL_CONTEXT_TRILOGY_SLOW_QUERY_ENABLED', config.trilogy_slow_query_enabled)
+      config.trilogy_slow_query_threshold_ms =
+        float_env('RAILS_OTEL_CONTEXT_TRILOGY_SLOW_QUERY_MS', config.trilogy_slow_query_threshold_ms)
+
+      config.redis_source_enabled =
+        bool_env('RAILS_OTEL_CONTEXT_REDIS_SOURCE_ENABLED', config.redis_source_enabled)
+      config.clickhouse_enabled =
+        bool_env('RAILS_OTEL_CONTEXT_CLICKHOUSE_ENABLED', config.clickhouse_enabled)
+      config.clickhouse_slow_query_threshold_ms =
+        float_env('RAILS_OTEL_CONTEXT_CLICKHOUSE_SLOW_QUERY_MS', config.clickhouse_slow_query_threshold_ms)
+
+      config.call_context_enabled =
+        bool_env('RAILS_OTEL_CONTEXT_CALL_CONTEXT_ENABLED', config.call_context_enabled)
+
+      config.custom_span_attributes_enabled =
+        bool_env('RAILS_OTEL_CONTEXT_CUSTOM_SPAN_ATTRIBUTES_ENABLED', config.custom_span_attributes_enabled)
+
+      config.request_context_enabled =
+        bool_env('RAILS_OTEL_CONTEXT_REQUEST_CONTEXT_ENABLED', config.request_context_enabled)
+
+      config
+    end
+
+    def float_env(key, default)
+      value = ENV.fetch(key, nil)
+      return default if value.nil? || value.strip.empty?
+
+      Float(value)
+    rescue ArgumentError, TypeError
+      default
+    end
+
+    def bool_env(key, default)
+      value = ENV.fetch(key, nil)
+      return default if value.nil? || value.strip.empty?
+
+      return true if %w[1 true yes on].include?(value.strip.downcase)
+      return false if %w[0 false no off].include?(value.strip.downcase)
+
+      default
+    end
+  end
+end

metadata

@@ -0,0 +1,100 @@
+--- !ruby/object:Gem::Specification
+name: rails-otel-context
+version: !ruby/object:Gem::Version
+  version: 0.5.0
+platform: ruby
+authors:
+- Last9
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: opentelemetry-api
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.0'
+- !ruby/object:Gem::Dependency
+  name: railties
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+- !ruby/object:Gem::Dependency
+  name: activerecord
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+description: Rails-specific OpenTelemetry enhancements for source location tracking
+  and database instrumentation. Maintained by Last9.
+email:
+- engineering@last9.io
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- lib/rails_otel_context.rb
+- lib/rails_otel_context/activerecord_context.rb
+- lib/rails_otel_context/adapters.rb
+- lib/rails_otel_context/adapters/clickhouse.rb
+- lib/rails_otel_context/adapters/mysql2.rb
+- lib/rails_otel_context/adapters/pg.rb
+- lib/rails_otel_context/adapters/redis.rb
+- lib/rails_otel_context/adapters/trilogy.rb
+- lib/rails_otel_context/call_context_processor.rb
+- lib/rails_otel_context/configuration.rb
+- lib/rails_otel_context/railtie.rb
+- lib/rails_otel_context/request_context.rb
+- lib/rails_otel_context/source_location.rb
+- lib/rails_otel_context/version.rb
+homepage: https://github.com/last9/rails-otel-context
+licenses:
+- MIT
+metadata:
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.1.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.2
+specification_version: 4
+summary: Production helpers for OpenTelemetry Ruby instrumentations in Rails.
+test_files: []