launchdarkly-observability 0.2.0

data/lib/launchdarkly_observability/hook.rb

@@ -0,0 +1,199 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'launchdarkly-server-sdk'
+
+module LaunchDarklyObservability
+  # Evaluation hook that instruments LaunchDarkly flag evaluations with OpenTelemetry spans and events.
+  #
+  # This hook creates spans for each flag evaluation, capturing:
+  # - Flag key and provider
+  # - Context information
+  # - Evaluation result (value, variation index)
+  # - Any errors
+  #
+  # Additionally, a "feature_flag" event is added to the span with evaluation results,
+  # following the OpenTelemetry semantic conventions for feature flags and matching
+  # the pattern used by other LaunchDarkly observability SDKs (Android, Node).
+  #
+  # @example The hook is automatically registered when using the Plugin
+  #   plugin = LaunchDarklyObservability::Plugin.new(project_id: 'my-project')
+  #   config = LaunchDarkly::Config.new(plugins: [plugin])
+  #   client = LaunchDarkly::LDClient.new('sdk-key', config)
+  #
+  #   # Flag evaluations are now automatically traced
+  #   client.variation('my-flag', context, false)
+  #
+  class Hook
+    include LaunchDarkly::Interfaces::Hooks::Hook
+
+    TRACER_NAME = 'launchdarkly-ruby'
+    SPAN_NAME = 'evaluation'
+    FEATURE_FLAG_EVENT_NAME = 'feature_flag'
+
+    # @return [LaunchDarkly::Interfaces::Hooks::Metadata]
+    def metadata
+      LaunchDarkly::Interfaces::Hooks::Metadata.new('launchdarkly-observability-hook')
+    end
+
+    # Called before flag evaluation.
+    # Creates an OpenTelemetry span and captures initial context information.
+    #
+    # @param series_context [LaunchDarkly::Interfaces::Hooks::EvaluationSeriesContext]
+    # @param data [Hash] Data passed between hook stages
+    # @return [Hash] Updated data hash with span information
+    def before_evaluation(series_context, data)
+      return data unless opentelemetry_available?
+
+      tracer = OpenTelemetry.tracer_provider.tracer(TRACER_NAME, LaunchDarklyObservability::VERSION)
+
+      span = tracer.start_span(SPAN_NAME, attributes: build_before_attributes(series_context))
+
+      data.merge(__ld_observability_span: span)
+    rescue StandardError => e
+      warn "[LaunchDarklyObservability] Error in before_evaluation: #{e.message}"
+      data
+    end
+
+    # Called after flag evaluation.
+    # Completes the span with evaluation results and a "feature_flag" event.
+    #
+    # @param series_context [LaunchDarkly::Interfaces::Hooks::EvaluationSeriesContext]
+    # @param data [Hash] Data passed between hook stages
+    # @param detail [LaunchDarkly::EvaluationDetail] The evaluation result
+    # @return [Hash] Updated data hash
+    def after_evaluation(series_context, data, detail)
+      span = data[:__ld_observability_span]
+      return data unless span
+
+      add_result_attributes(span, detail)
+      handle_evaluation_error(span, detail)
+      add_feature_flag_event(span, series_context, detail)
+
+      span.finish
+
+      data
+    rescue StandardError => e
+      warn "[LaunchDarklyObservability] Error in after_evaluation: #{e.message}"
+      span&.finish
+      data
+    end
+
+    private
+
+    def opentelemetry_available?
+      defined?(OpenTelemetry) && OpenTelemetry.tracer_provider
+    end
+
+    def build_before_attributes(series_context)
+      attrs = {
+        FEATURE_FLAG_KEY => series_context.key,
+        FEATURE_FLAG_PROVIDER_NAME => 'LaunchDarkly'
+      }
+
+      context = series_context.context
+      if context
+        attrs[FEATURE_FLAG_CONTEXT_ID] = context.fully_qualified_key
+      end
+
+      attrs
+    end
+
+    def serialize_value(value)
+      case value
+      when String, Numeric, TrueClass, FalseClass, NilClass
+        value.to_s
+      when Hash, Array
+        value.to_json
+      else
+        value.to_s
+      end
+    end
+
+    def add_result_attributes(span, detail)
+      if detail.variation_index
+        span.set_attribute(FEATURE_FLAG_RESULT_VARIANT, detail.variation_index.to_s)
+        span.set_attribute(FEATURE_FLAG_RESULT_VARIATION_INDEX, detail.variation_index.to_s)
+      end
+
+      span.set_attribute(FEATURE_FLAG_RESULT_VALUE, serialize_value(detail.value))
+    end
+
+    # Adds a "feature_flag" event with evaluation results.
+    # Attribute names match the ClickHouse schema and other LaunchDarkly SDKs.
+    def add_feature_flag_event(span, series_context, detail)
+      event_attributes = {
+        FEATURE_FLAG_KEY => series_context.key,
+        FEATURE_FLAG_PROVIDER_NAME => 'LaunchDarkly'
+      }
+
+      context = series_context.context
+      if context
+        event_attributes[FEATURE_FLAG_CONTEXT_ID] = context.fully_qualified_key
+      end
+
+      if detail.variation_index
+        event_attributes[FEATURE_FLAG_RESULT_VARIANT] = detail.variation_index.to_s
+        event_attributes[FEATURE_FLAG_RESULT_VARIATION_INDEX] = detail.variation_index.to_s
+      end
+
+      event_attributes[FEATURE_FLAG_RESULT_VALUE] = serialize_value(detail.value)
+
+      reason = detail.reason
+      if reason.respond_to?(:kind)
+        event_attributes[FEATURE_FLAG_RESULT_REASON_KIND] = reason.kind.to_s
+
+        add_reason_event_details(event_attributes, reason)
+      end
+
+      span.add_event(FEATURE_FLAG_EVENT_NAME, attributes: event_attributes)
+    end
+
+    def add_reason_event_details(event_attributes, reason)
+      if reason.respond_to?(:in_experiment) && !reason.in_experiment.nil?
+        event_attributes[FEATURE_FLAG_RESULT_REASON_IN_EXPERIMENT] = reason.in_experiment
+      end
+
+      case reason.kind
+      when :RULE_MATCH
+        if reason.respond_to?(:rule_index) && reason.rule_index
+          event_attributes[FEATURE_FLAG_RESULT_REASON_RULE_INDEX] = reason.rule_index
+        end
+        if reason.respond_to?(:rule_id) && reason.rule_id
+          event_attributes[FEATURE_FLAG_RESULT_REASON_RULE_ID] = reason.rule_id
+        end
+      when :ERROR
+        if reason.respond_to?(:error_kind) && reason.error_kind
+          event_attributes[FEATURE_FLAG_RESULT_REASON_ERROR_KIND] = reason.error_kind.to_s
+        end
+      end
+    end
+
+    def handle_evaluation_error(span, detail)
+      reason = detail.reason
+      return unless reason.respond_to?(:kind) && reason.kind == :ERROR
+
+      error_kind = reason.respond_to?(:error_kind) ? reason.error_kind.to_s : 'general'
+
+      error_type = case error_kind.upcase
+                   when 'FLAG_NOT_FOUND'
+                     'flag_not_found'
+                   when 'MALFORMED_FLAG'
+                     'parse_error'
+                   when 'USER_NOT_SPECIFIED', 'CLIENT_NOT_READY'
+                     'provider_not_ready'
+                   when 'WRONG_TYPE'
+                     'type_mismatch'
+                   else
+                     'general'
+                   end
+
+      span.set_attribute(ERROR_TYPE, error_type)
+
+      error_message = "Flag evaluation error: #{error_kind}"
+      span.set_attribute(ERROR_MESSAGE, error_message)
+
+      span.status = OpenTelemetry::Trace::Status.error(error_message)
+    end
+  end
+end

data/lib/launchdarkly_observability/middleware.rb

@@ -0,0 +1,116 @@
+# frozen_string_literal: true
+
+module LaunchDarklyObservability
+  # Rack middleware for request tracing
+  #
+  # This middleware wraps incoming HTTP requests in OpenTelemetry spans,
+  # providing context for flag evaluations that occur during request processing.
+  #
+  # Works with any Rack-compatible framework (Rails, Sinatra, Grape, Hanami, etc.).
+  # In Rails, the Railtie inserts this middleware automatically. For other frameworks,
+  # add it manually to your middleware stack:
+  #
+  # @example Sinatra
+  #   use LaunchDarklyObservability::Middleware
+  #
+  # @example Rack::Builder
+  #   use LaunchDarklyObservability::Middleware
+  #   run MyApp
+  #
+  class Middleware
+    # Header for observability request context (session/request ID propagation)
+    OBSERVABILITY_REQUEST_HEADER = 'HTTP_X_HIGHLIGHT_REQUEST'
+
+    # Baggage keys for context propagation
+    SESSION_BAGGAGE_KEY = 'launchdarkly.session_id'
+    REQUEST_BAGGAGE_KEY = 'launchdarkly.request_id'
+
+    def initialize(app)
+      @app = app
+    end
+
+    # Process the request with tracing context
+    #
+    # @param env [Hash] Rack environment
+    # @return [Array] Rack response tuple
+    def call(env)
+      return @app.call(env) unless tracing_available?
+
+      request = Rack::Request.new(env)
+      session_id, request_id = extract_observability_context(env)
+      ctx = set_baggage_context(session_id, request_id)
+      app_error = nil
+
+      OpenTelemetry::Context.with_current(ctx) do
+        tracer.in_span(span_name(request), attributes: request_attributes(request)) do |span|
+          span.set_attribute(SESSION_BAGGAGE_KEY, session_id) if session_id
+          span.set_attribute(REQUEST_BAGGAGE_KEY, request_id) if request_id
+
+          begin
+            status, headers, body = @app.call(env)
+          rescue StandardError => e
+            app_error = e
+            span.record_exception(e, attributes: SourceContext.exception_attributes(e))
+            span.status = OpenTelemetry::Trace::Status.error(e.message)
+            raise
+          end
+
+          span.set_attribute('http.status_code', status)
+          span.status = OpenTelemetry::Trace::Status.error("HTTP #{status}") if status >= 500
+          [status, headers, body]
+        end
+      end
+    rescue StandardError => e
+      raise if app_error
+
+      warn "[LaunchDarklyObservability] Middleware error: #{e.message}"
+      @app.call(env)
+    end
+
+    private
+
+    def tracing_available?
+      defined?(OpenTelemetry) && OpenTelemetry.tracer_provider
+    end
+
+    def tracer
+      @tracer ||= OpenTelemetry.tracer_provider.tracer(
+        'launchdarkly-ruby',
+        LaunchDarklyObservability::VERSION
+      )
+    end
+
+    def span_name(request)
+      "#{request.request_method} #{request.path}"
+    end
+
+    def request_attributes(request)
+      {
+        'http.method' => request.request_method,
+        'http.url' => request.url,
+        'http.target' => request.path,
+        'http.host' => request.host,
+        'http.scheme' => request.scheme,
+        'http.user_agent' => request.user_agent
+      }.compact
+    end
+
+    def extract_observability_context(env)
+      header_value = env[OBSERVABILITY_REQUEST_HEADER]
+      return [nil, nil] unless header_value
+
+      parts = header_value.to_s.split('/')
+      session_id = parts[0]&.then { |s| s.empty? ? nil : s }
+      request_id = parts[1]&.then { |s| s.empty? ? nil : s }
+
+      [session_id, request_id]
+    end
+
+    def set_baggage_context(session_id, request_id)
+      ctx = OpenTelemetry::Context.current
+      ctx = OpenTelemetry::Baggage.set_value(SESSION_BAGGAGE_KEY, session_id, context: ctx) if session_id
+      ctx = OpenTelemetry::Baggage.set_value(REQUEST_BAGGAGE_KEY, request_id, context: ctx) if request_id
+      ctx
+    end
+  end
+end

data/lib/launchdarkly_observability/opentelemetry_config.rb

@@ -0,0 +1,272 @@
+# frozen_string_literal: true
+
+require 'opentelemetry/sdk'
+require 'opentelemetry/exporter/otlp'
+require 'opentelemetry/instrumentation/all'
+require 'opentelemetry/semantic_conventions'
+
+module LaunchDarklyObservability
+  # Configures OpenTelemetry SDK with appropriate providers and exporters
+  # for traces, logs, and metrics.
+  #
+  # This class handles the setup of:
+  # - Tracer provider with OTLP exporter and batch processing
+  # - Logger provider with OTLP log exporter (included by default)
+  # - Meter provider with OTLP metrics exporter (if available)
+  # - Auto-instrumentation for Rails, ActiveRecord, Net::HTTP, etc.
+  #
+  class OpenTelemetryConfig
+    # Default batch processor configuration
+    BATCH_SCHEDULE_DELAY_MS = 1000
+    BATCH_MAX_EXPORT_SIZE = 128
+    BATCH_MAX_QUEUE_SIZE = 1024
+
+    # Metrics export interval
+    METRICS_EXPORT_INTERVAL_MS = 60_000
+
+    # @return [String] The LaunchDarkly project ID
+    attr_reader :project_id
+
+    # @return [String] The OTLP endpoint
+    attr_reader :otlp_endpoint
+
+    # @return [String] The deployment environment
+    attr_reader :environment
+
+    # @return [OpenTelemetry::SDK::Logs::LoggerProvider, nil] The logger provider (nil if logs disabled or setup failed)
+    attr_reader :logger_provider
+
+    # Initialize OpenTelemetry configuration
+    #
+    # @param project_id [String] LaunchDarkly project ID
+    # @param otlp_endpoint [String] OTLP collector endpoint
+    # @param environment [String, nil] Deployment environment name (optional - inferred from SDK key if not provided)
+    # @param sdk_metadata [LaunchDarkly::Interfaces::Plugins::SdkMetadata, nil]
+    # @param options [Hash] Additional options
+    def initialize(project_id:, otlp_endpoint:, environment: nil, sdk_metadata: nil, **options)
+      @project_id = project_id
+      @otlp_endpoint = otlp_endpoint
+      @environment = environment
+      @sdk_metadata = sdk_metadata
+      @options = options
+      @configured = false
+      @logger_provider = nil
+      @meter_provider = nil
+    end
+
+    # Configure OpenTelemetry SDK
+    #
+    # Sets up tracer provider with OTLP exporter, logger provider
+    # for OTLP log export, and optionally meter provider if available.
+    def configure
+      return if @configured
+
+      configure_traces if @options.fetch(:enable_traces, true)
+      configure_logs if @options.fetch(:enable_logs, true)
+      configure_metrics if @options.fetch(:enable_metrics, true)
+
+      setup_shutdown_hook
+
+      @configured = true
+    end
+
+    # Flush all pending telemetry data
+    def flush
+      OpenTelemetry.tracer_provider&.force_flush
+      @logger_provider&.force_flush
+      @meter_provider&.force_flush
+    rescue StandardError => e
+      warn "[LaunchDarklyObservability] Error flushing telemetry: #{e.message}"
+    end
+
+    # Shutdown all providers
+    def shutdown
+      OpenTelemetry.tracer_provider&.shutdown
+      @logger_provider&.shutdown
+      @meter_provider&.shutdown
+    rescue StandardError => e
+      warn "[LaunchDarklyObservability] Error shutting down telemetry: #{e.message}"
+    end
+
+    private
+
+    # Configure OpenTelemetry traces with OTLP exporter
+    def configure_traces
+      OpenTelemetry::SDK.configure do |c|
+        c.resource = create_resource
+        c.add_span_processor(create_batch_span_processor)
+
+        # Enable auto-instrumentation
+        configure_instrumentations(c)
+      end
+    end
+
+    # Configure auto-instrumentations with sensible defaults.
+    # User-provided instrumentation config is merged on top of defaults,
+    # so users only need to specify the instrumentations they want to override.
+    def configure_instrumentations(config)
+      defaults = {
+        'OpenTelemetry::Instrumentation::Rails' => { enable_recognize_route: true },
+        'OpenTelemetry::Instrumentation::ActiveRecord' => { db_statement: :include },
+        'OpenTelemetry::Instrumentation::Net::HTTP' => { untraced_hosts: [] },
+        'OpenTelemetry::Instrumentation::Rack' => { untraced_endpoints: ['/health', '/healthz', '/ready'] }
+      }
+
+      user_config = @options.fetch(:instrumentations, {})
+      config.use_all(defaults.merge(user_config))
+    rescue StandardError => e
+      warn "[LaunchDarklyObservability] Error configuring instrumentations: #{e.message}"
+    end
+
+    # Configure OpenTelemetry logs with OTLP exporter.
+    # The log gems are runtime dependencies, so require should always succeed.
+    # If anything goes wrong, we warn once and leave traces unaffected.
+    def configure_logs
+      require 'opentelemetry-logs-sdk'
+      require 'opentelemetry-exporter-otlp-logs'
+
+      @logger_provider = OpenTelemetry::SDK::Logs::LoggerProvider.new(resource: create_resource)
+
+      logs_processor = OpenTelemetry::SDK::Logs::Export::BatchLogRecordProcessor.new(
+        create_logs_exporter,
+        schedule_delay: BATCH_SCHEDULE_DELAY_MS
+      )
+
+      @logger_provider.add_log_record_processor(logs_processor)
+
+      OpenTelemetry.logger_provider = @logger_provider if OpenTelemetry.respond_to?(:logger_provider=)
+    rescue LoadError => e
+      warn "[LaunchDarklyObservability] Log gems not available, skipping log configuration: #{e.message}"
+    rescue StandardError => e
+      warn "[LaunchDarklyObservability] Error configuring logs: #{e.message}"
+    end
+
+    # Configure OpenTelemetry metrics with OTLP exporter
+    def configure_metrics
+      # Check if metrics SDK is available
+      return unless metrics_sdk_available?
+
+      require 'opentelemetry-metrics-sdk'
+      require 'opentelemetry/exporter/otlp/metrics'
+
+      metric_reader = OpenTelemetry::SDK::Metrics::Export::PeriodicMetricReader.new(
+        create_metrics_exporter,
+        export_interval_millis: METRICS_EXPORT_INTERVAL_MS
+      )
+
+      @meter_provider = OpenTelemetry::SDK::Metrics::MeterProvider.new(
+        resource: create_resource,
+        metric_readers: [metric_reader]
+      )
+
+      # Set global meter provider if the method exists
+      OpenTelemetry.meter_provider = @meter_provider if OpenTelemetry.respond_to?(:meter_provider=)
+    rescue LoadError
+      # Metrics SDK not available, skip metrics configuration
+      nil
+    rescue StandardError => e
+      warn "[LaunchDarklyObservability] Error configuring metrics: #{e.message}"
+    end
+
+    # Create OpenTelemetry resource with LaunchDarkly attributes
+    def create_resource
+      attrs = {
+        PROJECT_ID_ATTRIBUTE => @project_id,
+        SDK_NAME_ATTRIBUTE => 'opentelemetry',
+        SDK_VERSION_ATTRIBUTE => OpenTelemetry::SDK::VERSION,
+        SDK_LANGUAGE_ATTRIBUTE => 'ruby',
+        DISTRO_NAME_ATTRIBUTE => 'launchdarkly-observability-ruby',
+        DISTRO_VERSION_ATTRIBUTE => LaunchDarklyObservability::VERSION
+      }
+
+      # Only set deployment.environment if explicitly provided
+      # Otherwise, backend infers it from the SDK key
+      if @environment && !@environment.empty?
+        attrs[OpenTelemetry::SemanticConventions::Resource::DEPLOYMENT_ENVIRONMENT] = @environment
+      end
+
+      # Add service name
+      service_name = @options[:service_name] || infer_service_name
+      attrs[OpenTelemetry::SemanticConventions::Resource::SERVICE_NAME] = service_name if service_name
+
+      # Add service version
+      service_version = @options[:service_version]
+      attrs[OpenTelemetry::SemanticConventions::Resource::SERVICE_VERSION] = service_version if service_version
+
+      # Add SDK metadata if available
+      if @sdk_metadata
+        attrs['launchdarkly.sdk.name'] = @sdk_metadata.name if @sdk_metadata.respond_to?(:name)
+        attrs['launchdarkly.sdk.version'] = @sdk_metadata.version if @sdk_metadata.respond_to?(:version)
+      end
+
+      OpenTelemetry::SDK::Resources::Resource.create(attrs)
+    end
+
+    # Create batch span processor with OTLP exporter
+    def create_batch_span_processor
+      OpenTelemetry::SDK::Trace::Export::BatchSpanProcessor.new(
+        create_trace_exporter,
+        schedule_delay: BATCH_SCHEDULE_DELAY_MS,
+        max_export_batch_size: BATCH_MAX_EXPORT_SIZE,
+        max_queue_size: BATCH_MAX_QUEUE_SIZE
+      )
+    end
+
+    # Create OTLP trace exporter
+    def create_trace_exporter
+      OpenTelemetry::Exporter::OTLP::Exporter.new(
+        endpoint: "#{@otlp_endpoint}/v1/traces",
+        compression: 'gzip'
+      )
+    end
+
+    # Create OTLP logs exporter
+    def create_logs_exporter
+      OpenTelemetry::Exporter::OTLP::Logs::LogsExporter.new(
+        endpoint: "#{@otlp_endpoint}/v1/logs",
+        compression: 'gzip'
+      )
+    end
+
+    # Create OTLP metrics exporter
+    def create_metrics_exporter
+      OpenTelemetry::Exporter::OTLP::Metrics::MetricsExporter.new(
+        endpoint: "#{@otlp_endpoint}/v1/metrics",
+        compression: 'gzip'
+      )
+    end
+
+    # Infer service name from Rails or environment
+    def infer_service_name
+      if defined?(::Rails) && ::Rails.respond_to?(:application)
+        app_class = ::Rails.application.class
+        if app_class.respond_to?(:module_parent_name)
+          app_class.module_parent_name.underscore
+        else
+          app_class.parent_name&.underscore
+        end
+      else
+        ENV.fetch('OTEL_SERVICE_NAME', nil)
+      end
+    end
+
+    # Check if metrics SDK gem is available
+    def metrics_sdk_available?
+      Gem::Specification.find_by_name('opentelemetry-metrics-sdk')
+      true
+    rescue Gem::MissingSpecError
+      false
+    end
+
+    # Setup graceful exit hook to flush pending telemetry data.
+    #
+    # Only flushes (not shuts down) because frameworks like Sinatra start
+    # their servers inside at_exit handlers. Since at_exit runs in LIFO
+    # order, a shutdown registered after the framework's handler would
+    # execute BEFORE the server starts, stopping the TracerProvider and
+    # causing all spans to be non-recording for the server's lifetime.
+    def setup_shutdown_hook
+      at_exit { flush }
+    end
+  end
+end

data/lib/launchdarkly_observability/otel_log_bridge.rb

@@ -0,0 +1,108 @@
+# frozen_string_literal: true
+
+module LaunchDarklyObservability
+  # A Logger that forwards messages to the OpenTelemetry Logs pipeline.
+  #
+  # When used as a broadcast target (Rails), pass only the logger_provider.
+  # When used standalone (Sinatra, plain Ruby), pass `io:` to also write
+  # to a local destination such as $stdout.
+  #
+  # @example Standalone usage (non-Rails)
+  #   logger = LaunchDarklyObservability.logger          # writes to $stdout + OTel
+  #
+  # @example Manually attaching (the Railtie does this automatically)
+  #   bridge = LaunchDarklyObservability::OtelLogBridge.new(logger_provider)
+  #   Rails.logger.broadcast_to(bridge)   # Rails >= 7.1
+  #
+  class OtelLogBridge < ::Logger
+    # OpenTelemetry severity numbers (base value per level).
+    # See: https://opentelemetry.io/docs/specs/otel/logs/data-model/#severity-fields
+    SEVERITY_NUMBER = {
+      ::Logger::DEBUG   => 5,
+      ::Logger::INFO    => 9,
+      ::Logger::WARN    => 13,
+      ::Logger::ERROR   => 17,
+      ::Logger::FATAL   => 21,
+      ::Logger::UNKNOWN => 0
+    }.freeze
+
+    SEVERITY_TEXT = {
+      ::Logger::DEBUG   => 'DEBUG',
+      ::Logger::INFO    => 'INFO',
+      ::Logger::WARN    => 'WARN',
+      ::Logger::ERROR   => 'ERROR',
+      ::Logger::FATAL   => 'FATAL',
+      ::Logger::UNKNOWN => 'UNKNOWN'
+    }.freeze
+
+    # @param logger_provider [OpenTelemetry::SDK::Logs::LoggerProvider]
+    # @param io [IO, nil] Optional IO for local output (e.g. $stdout).
+    #   When nil the bridge only emits to OTel (suitable for broadcast).
+    def initialize(logger_provider, io: nil)
+      super(File::NULL)
+      @otel_logger = logger_provider.logger(
+        name: 'launchdarkly-observability-ruby',
+        version: LaunchDarklyObservability::VERSION
+      )
+      @local_logger = io ? ::Logger.new(io) : nil
+    end
+
+    # Propagate level changes to the local logger so filtering stays in sync.
+    def level=(severity)
+      super
+      @local_logger&.level = severity
+    end
+
+    # Propagate formatter changes to the local logger.
+    def formatter=(formatter)
+      super
+      @local_logger&.formatter = formatter
+    end
+
+    # Core method that debug/info/warn/error/fatal all delegate to.
+    def add(severity, message = nil, progname = nil)
+      severity ||= ::Logger::UNKNOWN
+      return true if severity < level
+
+      if message.nil?
+        if block_given?
+          message = yield
+        else
+          message = progname
+          progname = nil
+        end
+      end
+
+      return true if message.nil?
+
+      attributes = {}
+      if message.is_a?(Hash)
+        attributes = message.each_with_object({}) { |(k, v), h| h[k.to_s] = v.to_s }
+        body = message.inspect
+      else
+        body = message.to_s
+      end
+
+      begin
+        @otel_logger.on_emit(
+          body: body,
+          severity_number: SEVERITY_NUMBER.fetch(severity, 0),
+          severity_text: SEVERITY_TEXT.fetch(severity, 'UNKNOWN'),
+          timestamp: Time.now,
+          context: OpenTelemetry::Context.current,
+          attributes: attributes
+        )
+      rescue StandardError
+        # OTel export failures must not suppress local IO output.
+      end
+
+      begin
+        @local_logger&.add(severity, message, progname)
+      rescue StandardError
+        # Local IO failures must not propagate.
+      end
+
+      true
+    end
+  end
+end