launchdarkly-observability 0.2.0

data/lib/launchdarkly_observability/plugin.rb

@@ -0,0 +1,133 @@
+# frozen_string_literal: true
+
+require 'launchdarkly-server-sdk'
+
+module LaunchDarklyObservability
+  # LaunchDarkly SDK Plugin that provides observability instrumentation.
+  #
+  # This plugin integrates with the LaunchDarkly Ruby SDK to automatically
+  # instrument flag evaluations with OpenTelemetry traces, logs, and metrics.
+  #
+  # @example Basic usage (SDK key and environment automatically extracted)
+  #   plugin = LaunchDarklyObservability::Plugin.new
+  #   config = LaunchDarkly::Config.new(plugins: [plugin])
+  #   client = LaunchDarkly::LDClient.new(ENV['LAUNCHDARKLY_SDK_KEY'], config)
+  #
+  class Plugin
+    include LaunchDarkly::Interfaces::Plugins::Plugin
+
+    # @return [String] The LaunchDarkly project ID
+    attr_reader :project_id
+
+    # @return [String] The OTLP endpoint URL
+    attr_reader :otlp_endpoint
+
+    # @return [String] The deployment environment
+    attr_reader :environment
+
+    # @return [Hash] Additional options
+    attr_reader :options
+
+    # Initialize a new observability plugin
+    #
+    # @param project_id [String, nil] LaunchDarkly project ID for routing telemetry.
+    #   If not provided, the SDK key from the client will be used automatically.
+    # @param sdk_key [String, nil] LaunchDarkly SDK key (optional - will be extracted from client if not provided).
+    #   The backend will derive the project and environment from the SDK key.
+    # @param otlp_endpoint [String] OTLP collector endpoint (default: LaunchDarkly's endpoint)
+    # @param environment [String, nil] Deployment environment name (optional - inferred from SDK key by default).
+    #   Only specify this for advanced scenarios like deployment-specific suffixes (e.g., 'production-canary').
+    # @param options [Hash] Additional configuration options
+    # @option options [String] :service_name Service name for resource attributes
+    # @option options [String] :service_version Service version for resource attributes
+    # @option options [Hash] :instrumentations Configuration for OpenTelemetry auto-instrumentations
+    # @option options [Boolean] :enable_traces Enable trace instrumentation (default: true)
+    # @option options [Boolean] :enable_logs Enable log instrumentation (default: true)
+    # @option options [Boolean] :enable_metrics Enable metrics instrumentation (default: true)
+    def initialize(project_id: nil, sdk_key: nil, otlp_endpoint: DEFAULT_ENDPOINT, environment: nil, **options)
+      @project_id = project_id || sdk_key
+      @otlp_endpoint = otlp_endpoint
+      @environment = environment&.to_s
+      @options = default_options.merge(options)
+      @hook = Hook.new
+      @otel_config = nil
+      @registered = false
+    end
+
+    # Returns metadata about this plugin
+    #
+    # @return [LaunchDarkly::Interfaces::Plugins::PluginMetadata]
+    def metadata
+      LaunchDarkly::Interfaces::Plugins::PluginMetadata.new('launchdarkly-observability')
+    end
+
+    # Returns the hooks provided by this plugin
+    #
+    # @param _environment_metadata [LaunchDarkly::Interfaces::Plugins::EnvironmentMetadata]
+    # @return [Array<LaunchDarkly::Interfaces::Hooks::Hook>]
+    def get_hooks(_environment_metadata)
+      [@hook]
+    end
+
+    # Register the plugin with the LaunchDarkly client
+    #
+    # This method is called during SDK initialization. It sets up the
+    # OpenTelemetry SDK with appropriate providers and exporters.
+    #
+    # @param _client [LaunchDarkly::LDClient] The LaunchDarkly client instance
+    # @param environment_metadata [LaunchDarkly::Interfaces::Plugins::EnvironmentMetadata]
+    def register(_client, environment_metadata)
+      return if @registered
+
+      # Use provided project_id, or extract SDK key from the client
+      project_id = @project_id || environment_metadata&.sdk_key
+
+      if project_id.nil? || project_id.empty?
+        raise ArgumentError, 'Unable to determine project_id: no project_id or sdk_key provided, and client SDK key is unavailable'
+      end
+
+      @otel_config = OpenTelemetryConfig.new(
+        project_id: project_id,
+        otlp_endpoint: @otlp_endpoint,
+        environment: @environment,
+        sdk_metadata: environment_metadata&.sdk,
+        **@options
+      )
+
+      @otel_config.configure
+
+      @registered = true
+    end
+
+    # Check if the plugin has been registered
+    #
+    # @return [Boolean]
+    def registered?
+      @registered
+    end
+
+    # Flush all pending telemetry data
+    def flush
+      @otel_config&.flush
+    end
+
+    # Shutdown the plugin and flush remaining data
+    def shutdown
+      @otel_config&.shutdown
+      @registered = false
+    end
+
+    private
+
+    def default_options
+      {
+        enable_traces: true,
+        enable_logs: true,
+        enable_metrics: true,
+        service_name: nil,
+        service_version: nil,
+        instrumentations: {}
+      }
+    end
+  end
+end

data/lib/launchdarkly_observability/rails.rb

@@ -0,0 +1,141 @@
+# frozen_string_literal: true
+
+require_relative 'middleware'
+
+module LaunchDarklyObservability
+  if defined?(::Rails::Railtie)
+    # Rails Railtie for automatic integration
+    #
+    # This Railtie automatically:
+    # - Inserts the LaunchDarkly middleware into the Rails middleware stack
+    # - Bridges Rails.logger to the OpenTelemetry Logs pipeline (if logger provider is available)
+    # - Provides helper methods for controllers and views
+    #
+    # @example The Railtie is automatically loaded when Rails is detected
+    #   # In config/initializers/launchdarkly.rb
+    #   LaunchDarklyObservability.init(project_id: ENV['LD_PROJECT_ID'])
+    #
+    class Railtie < ::Rails::Railtie
+      initializer 'launchdarkly_observability.configure_rails' do |app|
+        app.middleware.insert_before(0, LaunchDarklyObservability::Middleware)
+      end
+
+      config.after_initialize do
+        if defined?(ActionController::Base)
+          ActionController::Base.include(LaunchDarklyObservability::ControllerHelpers)
+        end
+
+        if defined?(ActionController::API)
+          ActionController::API.include(LaunchDarklyObservability::ControllerHelpers)
+        end
+
+        attach_otel_log_bridge
+      end
+
+      class << self
+        private
+
+        def attach_otel_log_bridge
+          return unless otel_logger_provider_available?
+
+          bridge = LaunchDarklyObservability::OtelLogBridge.new(OpenTelemetry.logger_provider)
+
+          if ::Rails.logger.respond_to?(:broadcast_to)
+            ::Rails.logger.broadcast_to(bridge)
+          elsif defined?(ActiveSupport::Logger) && ActiveSupport::Logger.respond_to?(:broadcast)
+            ::Rails.logger.extend(ActiveSupport::Logger.broadcast(bridge))
+          end
+        rescue StandardError => e
+          warn "[LaunchDarklyObservability] Could not attach log bridge to Rails.logger: #{e.message}"
+        end
+
+        def otel_logger_provider_available?
+          LaunchDarklyObservability.send(:otel_logger_provider_available?)
+        end
+      end
+    end
+
+    # Controller helper methods for Rails
+    #
+    # These helpers provide convenient access to observability features
+    # within Rails controllers.
+    #
+    module ControllerHelpers
+      extend ActiveSupport::Concern
+
+      included do
+        helper_method :launchdarkly_trace_id if respond_to?(:helper_method)
+      end
+
+      # @return [String, nil] The current OpenTelemetry trace ID
+      def launchdarkly_trace_id
+        return nil unless defined?(OpenTelemetry)
+
+        span = OpenTelemetry::Trace.current_span
+        return nil unless span&.context&.valid?
+
+        span.context.hex_trace_id
+      end
+
+      # @param name [String] The span name
+      # @param attributes [Hash] Span attributes
+      # @yield [span] Block to execute within the span
+      # @return The result of the block
+      def with_launchdarkly_span(name, attributes: {}, &block)
+        return yield unless defined?(OpenTelemetry) && OpenTelemetry.tracer_provider
+
+        tracer = OpenTelemetry.tracer_provider.tracer(
+          'launchdarkly-ruby-rails',
+          LaunchDarklyObservability::VERSION
+        )
+
+        tracer.in_span(name, attributes: attributes, &block)
+      end
+
+      # @param exception [Exception] The exception to record
+      # @param attributes [Hash] Additional attributes
+      def record_launchdarkly_exception(exception, attributes: {})
+        return unless defined?(OpenTelemetry)
+
+        span = OpenTelemetry::Trace.current_span
+        return unless span
+
+        span.record_exception(exception, attributes: SourceContext.exception_attributes(exception).merge(attributes))
+        span.status = OpenTelemetry::Trace::Status.error(exception.message)
+      end
+    end
+
+    # View helpers for Rails
+    #
+    # These helpers can be used in views to inject tracing context
+    # into the rendered HTML for client-side correlation.
+    #
+    module ViewHelpers
+      # @return [String] HTML meta tag with traceparent value
+      def launchdarkly_traceparent_meta_tag
+        traceparent = launchdarkly_traceparent
+        return '' unless traceparent
+
+        tag.meta(name: 'traceparent', content: traceparent)
+      end
+
+      # @return [String, nil] The traceparent header value
+      def launchdarkly_traceparent
+        return nil unless defined?(OpenTelemetry)
+
+        span = OpenTelemetry::Trace.current_span
+        return nil unless span&.context&.valid?
+
+        trace_id = span.context.hex_trace_id
+        span_id = span.context.hex_span_id
+        trace_flags = span.context.trace_flags.sampled? ? '01' : '00'
+
+        "00-#{trace_id}-#{span_id}-#{trace_flags}"
+      end
+    end
+
+    if defined?(ActionView::Base)
+      ActionView::Base.include(ViewHelpers)
+    end
+  end
+end

data/lib/launchdarkly_observability/source_context.rb

@@ -0,0 +1,112 @@
+# frozen_string_literal: true
+
+require 'json'
+
+module LaunchDarklyObservability
+  module SourceContext
+    CONTEXT_LINES = 4
+    MAX_FRAMES = 20
+    MAX_LINE_LENGTH = 1000
+    BACKTRACE_LINE_PATTERN = /^(.+):(\d+)(?::in [`'](.+?)')?$/
+
+    @file_cache = {}
+
+    module_function
+
+    def build_structured_stacktrace(exception)
+      return nil unless exception
+
+      backtrace = exception.backtrace
+      return nil unless backtrace&.any?
+
+      error_message = begin
+        exception.full_message(highlight: false, order: :top).to_s.lines.first&.chomp
+      rescue StandardError
+        exception.message
+      end
+      frames = backtrace.first(MAX_FRAMES).filter_map do |backtrace_line|
+        build_frame(backtrace_line, error_message)
+      end
+
+      frames.empty? ? nil : frames
+    rescue StandardError
+      nil
+    end
+
+    # Build a Hash of span attributes for an exception's structured stacktrace.
+    # Returns an empty hash when no stacktrace can be built, so the result is
+    # safe to merge directly into an attributes hash.
+    #
+    # @param exception [Exception]
+    # @return [Hash]
+    def exception_attributes(exception)
+      stacktrace = build_structured_stacktrace(exception)
+      return {} unless stacktrace
+
+      { 'exception.structured_stacktrace' => stacktrace.to_json }
+    end
+
+    def read_source_context(file_name, line_number)
+      return nil unless file_name && line_number
+      return nil unless File.exist?(file_name) && File.readable?(file_name)
+
+      source_lines = cached_source_lines(file_name)
+      return nil unless source_lines
+      return nil if line_number <= 0 || line_number > source_lines.length
+
+      target_index = line_number - 1
+      before_start = [target_index - CONTEXT_LINES, 0].max
+      before_lines = source_lines[before_start...target_index] || []
+      after_end = [target_index + CONTEXT_LINES, source_lines.length - 1].min
+      after_lines = source_lines[(target_index + 1)..after_end] || []
+
+      {
+        lineContent: source_lines[target_index],
+        linesBefore: before_lines.empty? ? nil : before_lines.join("\n"),
+        linesAfter: after_lines.empty? ? nil : after_lines.join("\n")
+      }
+    rescue StandardError
+      nil
+    end
+
+    def build_frame(backtrace_line, error_message)
+      matches = BACKTRACE_LINE_PATTERN.match(backtrace_line)
+      return nil unless matches
+
+      file_name = matches[1]
+      line_number = matches[2].to_i
+      function_name = matches[3]
+
+      frame = {
+        fileName: file_name,
+        lineNumber: line_number,
+        error: error_message
+      }
+      frame[:functionName] = function_name if function_name
+
+      source_context = read_source_context(file_name, line_number)
+      if source_context
+        frame[:lineContent] = source_context[:lineContent]
+        frame[:linesBefore] = source_context[:linesBefore] if source_context[:linesBefore]
+        frame[:linesAfter] = source_context[:linesAfter] if source_context[:linesAfter]
+      end
+
+      frame
+    end
+    private_class_method :build_frame
+
+    def cached_source_lines(file_name)
+      return @file_cache[file_name] if @file_cache.key?(file_name)
+
+      lines = File.readlines(file_name, chomp: true).map do |line|
+        line.length > MAX_LINE_LENGTH ? line[0...MAX_LINE_LENGTH] : line
+      end
+      @file_cache[file_name] = lines
+      lines
+    rescue StandardError
+      @file_cache[file_name] = nil
+      nil
+    end
+    private_class_method :cached_source_lines
+  end
+end

data/lib/launchdarkly_observability/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module LaunchDarklyObservability
+  VERSION = '0.2.0' # x-release-please-version
+end

data/lib/launchdarkly_observability.rb

@@ -0,0 +1,181 @@
+# frozen_string_literal: true
+
+require 'opentelemetry/sdk'
+require 'opentelemetry/exporter/otlp'
+require 'opentelemetry/instrumentation/all'
+require 'opentelemetry/semantic_conventions'
+
+require_relative 'launchdarkly_observability/version'
+require_relative 'launchdarkly_observability/hook'
+require_relative 'launchdarkly_observability/opentelemetry_config'
+require_relative 'launchdarkly_observability/plugin'
+require_relative 'launchdarkly_observability/source_context'
+
+require_relative 'launchdarkly_observability/middleware'
+require_relative 'launchdarkly_observability/otel_log_bridge'
+require_relative 'launchdarkly_observability/rails'
+
+module LaunchDarklyObservability
+  # Default OTLP endpoint for LaunchDarkly Observability
+  DEFAULT_ENDPOINT = 'https://otel.observability.app.launchdarkly.com:4318'
+
+  # Resource attribute keys
+  PROJECT_ID_ATTRIBUTE = 'launchdarkly.project_id'
+  SDK_NAME_ATTRIBUTE = 'telemetry.sdk.name'
+  SDK_VERSION_ATTRIBUTE = 'telemetry.sdk.version'
+  SDK_LANGUAGE_ATTRIBUTE = 'telemetry.sdk.language'
+  DISTRO_NAME_ATTRIBUTE = 'telemetry.distro.name'
+  DISTRO_VERSION_ATTRIBUTE = 'telemetry.distro.version'
+
+  # OpenTelemetry semantic convention attribute keys for feature flags
+  # See: https://opentelemetry.io/docs/specs/semconv/feature-flags/feature-flags-events/
+  FEATURE_FLAG_KEY = 'feature_flag.key'
+  FEATURE_FLAG_PROVIDER_NAME = 'feature_flag.provider.name'
+  FEATURE_FLAG_CONTEXT_ID = 'feature_flag.context.id'
+  FEATURE_FLAG_SET_ID = 'feature_flag.set.id'
+  FEATURE_FLAG_RESULT_VALUE = 'feature_flag.result.value'
+  FEATURE_FLAG_RESULT_VARIANT = 'feature_flag.result.variant'
+  FEATURE_FLAG_RESULT_VARIATION_INDEX = 'feature_flag.result.variationIndex'
+  FEATURE_FLAG_RESULT_REASON_KIND = 'feature_flag.result.reason.kind'
+  FEATURE_FLAG_RESULT_REASON_IN_EXPERIMENT = 'feature_flag.result.reason.inExperiment'
+  FEATURE_FLAG_RESULT_REASON_ERROR_KIND = 'feature_flag.result.reason.errorKind'
+  FEATURE_FLAG_RESULT_REASON_RULE_ID = 'feature_flag.result.reason.ruleId'
+  FEATURE_FLAG_RESULT_REASON_RULE_INDEX = 'feature_flag.result.reason.ruleIndex'
+  ERROR_TYPE = 'error.type'
+  ERROR_MESSAGE = 'error.message'
+
+  class << self
+    # @return [Plugin, nil] The current plugin instance
+    attr_reader :instance
+
+    # Initialize the observability plugin
+    #
+    # @param project_id [String, nil] LaunchDarkly project ID (optional - SDK key will be extracted from client if not provided)
+    # @param sdk_key [String, nil] LaunchDarkly SDK key (optional - will be extracted from client if not provided)
+    # @param options [Hash] Additional configuration options
+    # @option options [String] :otlp_endpoint Custom OTLP endpoint URL
+    # @option options [String] :environment Deployment environment (optional - inferred from SDK key by default)
+    # @option options [String] :service_name Service name for traces
+    # @option options [String] :service_version Service version
+    # @option options [Hash] :instrumentations Configuration for auto-instrumentations
+    # @return [Plugin] The initialized plugin
+    def init(project_id: nil, sdk_key: nil, **options)
+      @instance = Plugin.new(project_id: project_id, sdk_key: sdk_key, **options)
+    end
+
+    # Check if the plugin has been initialized
+    #
+    # @return [Boolean] true if initialized
+    def initialized?
+      !@instance.nil?
+    end
+
+    # Create a custom span for manual instrumentation
+    #
+    # This method matches the OpenTelemetry API naming convention for consistency.
+    #
+    # @param name [String] The span name
+    # @param attributes [Hash] Optional span attributes
+    # @yield [span] Block to execute within the span context
+    # @return The result of the block
+    #
+    # @example Create a custom span
+    #   LaunchDarklyObservability.in_span('database-query') do |span|
+    #     span.set_attribute('db.table', 'users')
+    #     perform_query
+    #   end
+    def in_span(name, attributes: {})
+      unless defined?(OpenTelemetry) && OpenTelemetry.tracer_provider
+        return yield if block_given?
+        return
+      end
+
+      tracer = OpenTelemetry.tracer_provider.tracer(
+        'launchdarkly-observability',
+        LaunchDarklyObservability::VERSION
+      )
+
+      tracer.in_span(name, attributes: attributes) do |span|
+        yield(span) if block_given?
+      end
+    end
+
+    # Record an exception in the current span
+    #
+    # @param exception [Exception] The exception to record
+    # @param attributes [Hash] Additional attributes
+    #
+    # @example Record an exception
+    #   begin
+    #     risky_operation
+    #   rescue => e
+    #     LaunchDarklyObservability.record_exception(e, foo: 'bar')
+    #     raise
+    #   end
+    def record_exception(exception, attributes: {})
+      return unless defined?(OpenTelemetry)
+
+      span = OpenTelemetry::Trace.current_span
+      return unless span
+
+      span.record_exception(exception, attributes: SourceContext.exception_attributes(exception).merge(attributes))
+      span.status = OpenTelemetry::Trace::Status.error(exception.message)
+    end
+
+    # Create a Logger that writes to both a local IO and the OTel Logs pipeline.
+    #
+    # Use this in non-Rails applications (Sinatra, Grape, plain Ruby) to get
+    # log export with trace correlation out of the box. Must be called after
+    # the Plugin has been registered (i.e. after LDClient.new).
+    #
+    # @param output [IO] Local IO destination (default: $stdout)
+    # @return [OtelLogBridge, Logger] An OTel-bridged logger, or a plain
+    #   Logger if the OTel logger provider is not yet available.
+    #
+    # @example Sinatra
+    #   $logger = LaunchDarklyObservability.logger
+    #   $logger.info 'This goes to stdout AND is exported as an OTLP log record'
+    def logger(output = $stdout)
+      if otel_logger_provider_available?
+        OtelLogBridge.new(OpenTelemetry.logger_provider, io: output)
+      else
+        ::Logger.new(output)
+      end
+    end
+
+    # Get the current trace ID
+    #
+    # @return [String, nil] The current trace ID in hex format
+    #
+    # @example Get trace ID for logging
+    #   trace_id = LaunchDarklyObservability.current_trace_id
+    #   logger.info "Processing request: #{trace_id}"
+    def current_trace_id
+      return nil unless defined?(OpenTelemetry)
+
+      span = OpenTelemetry::Trace.current_span
+      return nil unless span&.context&.valid?
+
+      span.context.hex_trace_id
+    end
+
+    # Flush all pending telemetry data
+    def flush
+      @instance&.flush
+    end
+
+    # Shutdown the plugin and flush remaining data
+    def shutdown
+      @instance&.shutdown
+      @instance = nil
+    end
+
+    private
+
+    def otel_logger_provider_available?
+      defined?(OpenTelemetry::SDK::Logs::LoggerProvider) &&
+        OpenTelemetry.respond_to?(:logger_provider) &&
+        OpenTelemetry.logger_provider.is_a?(OpenTelemetry::SDK::Logs::LoggerProvider)
+    end
+  end
+end