rapitapir 0.1.0

data/lib/rapitapir/observability/configuration.rb

@@ -0,0 +1,108 @@
+# frozen_string_literal: true
+
+module RapiTapir
+  module Observability
+    # Configuration for observability features
+    # Manages settings for metrics, tracing, logging, and health checks
+    class Configuration
+      attr_accessor :metrics, :tracing, :logging, :health_check
+
+      def initialize
+        @metrics = MetricsConfig.new
+        @tracing = TracingConfig.new
+        @logging = LoggingConfig.new
+        @health_check = HealthCheckConfig.new
+      end
+
+      # Configuration for metrics collection
+      # Defines which metrics to collect and how to expose them
+      class MetricsConfig
+        attr_accessor :enabled, :provider, :namespace, :custom_labels
+
+        def initialize
+          @enabled = false
+          @provider = :prometheus
+          @namespace = 'rapitapir'
+          @custom_labels = {}
+        end
+
+        def enable_prometheus(namespace: 'rapitapir', labels: {})
+          @enabled = true
+          @provider = :prometheus
+          @namespace = namespace
+          @custom_labels = labels
+        end
+
+        def disable
+          @enabled = false
+        end
+      end
+
+      # Configuration for distributed tracing
+      # Manages tracing setup and span collection settings
+      class TracingConfig
+        attr_accessor :enabled, :provider, :service_name, :service_version
+
+        def initialize
+          @enabled = false
+          @provider = :opentelemetry
+          @service_name = 'rapitapir-api'
+          @service_version = RapiTapir::VERSION
+        end
+
+        def enable_opentelemetry(service_name: 'rapitapir-api', service_version: nil)
+          @enabled = true
+          @provider = :opentelemetry
+          @service_name = service_name
+          @service_version = service_version || RapiTapir::VERSION
+        end
+
+        def disable
+          @enabled = false
+        end
+      end
+
+      # Configuration for structured logging
+      # Controls log levels, formats, and output destinations
+      class LoggingConfig
+        attr_accessor :enabled, :structured, :level, :format, :fields
+
+        def initialize
+          @enabled = true
+          @structured = false
+          @level = :info
+          @format = :text
+          @fields = %i[timestamp level message request_id method path status duration]
+        end
+
+        def enable_structured(level: :info, fields: nil)
+          @enabled = true
+          @structured = true
+          @level = level
+          @fields = fields if fields
+        end
+      end
+
+      # Configuration for health check endpoints
+      # Defines which health checks to run and how to expose them
+      class HealthCheckConfig
+        attr_accessor :enabled, :endpoint, :checks
+
+        def initialize
+          @enabled = false
+          @endpoint = '/health'
+          @checks = []
+        end
+
+        def enable(endpoint: '/health')
+          @enabled = true
+          @endpoint = endpoint
+        end
+
+        def add_check(name, &block)
+          @checks << { name: name, check: block }
+        end
+      end
+    end
+  end
+end

data/lib/rapitapir/observability/health_check.rb

@@ -0,0 +1,236 @@
+# frozen_string_literal: true
+
+module RapiTapir
+  module Observability
+    # Health check system for monitoring application status
+    # Provides health check registration and execution
+    module HealthCheck
+      # Individual health check definition
+      # Represents a single health check with execution logic
+      class Check
+        attr_reader :name, :description, :check_block
+
+        def initialize(name, description = nil, &block)
+          @name = name
+          @description = description || name.to_s.gsub('_', ' ').capitalize
+          @check_block = block
+        end
+
+        def call
+          start_time = Time.now
+
+          begin
+            result = @check_block.call
+            duration = Time.now - start_time
+            process_check_result(result, duration)
+          rescue StandardError => e
+            duration = Time.now - start_time
+            create_result(:unhealthy, "#{e.class}: #{e.message}", duration)
+          end
+        end
+
+        private
+
+        def process_check_result(result, duration)
+          case result
+          when TrueClass, FalseClass
+            handle_boolean_result(result, duration)
+          when Hash
+            handle_hash_result(result, duration)
+          else
+            create_result(:healthy, result.to_s, duration)
+          end
+        end
+
+        def handle_boolean_result(result, duration)
+          status = result ? :healthy : :unhealthy
+          create_result(status, nil, duration)
+        end
+
+        def handle_hash_result(result, duration)
+          status = result.fetch(:status, :healthy)
+          message = result[:message]
+          create_result(status, message, duration)
+        end
+
+        def create_result(status, message, duration)
+          {
+            name: @name,
+            description: @description,
+            status: status,
+            message: message,
+            duration_ms: (duration * 1000).round(2),
+            timestamp: Time.now.utc.iso8601
+          }
+        end
+      end
+
+      # Registry for managing health checks
+      # Centralized registry for registering and executing health checks
+      class Registry
+        def initialize
+          @checks = []
+          register_default_checks
+        end
+
+        def register(name, description = nil, &block)
+          @checks << Check.new(name, description, &block)
+        end
+
+        def run_all
+          results = @checks.map(&:call)
+          overall_status = results.all? { |r| r[:status] == :healthy } ? :healthy : :unhealthy
+
+          {
+            status: overall_status,
+            timestamp: Time.now.utc.iso8601,
+            service: 'rapitapir',
+            version: RapiTapir::VERSION,
+            checks: results
+          }
+        end
+
+        def run_check(name)
+          check = @checks.find { |c| c.name.to_s == name.to_s }
+          return { error: "Check '#{name}' not found" } unless check
+
+          check.call
+        end
+
+        def check_names
+          @checks.map(&:name)
+        end
+
+        private
+
+        def register_default_checks
+          # Basic Ruby runtime check
+          register(:ruby_runtime, 'Ruby runtime health') do
+            {
+              status: :healthy,
+              message: "Ruby #{RUBY_VERSION} running on #{RUBY_PLATFORM}"
+            }
+          end
+
+          # Memory usage check
+          register(:memory_usage, 'Memory usage') do
+            if defined?(GC)
+              stats = GC.stat
+              {
+                status: :healthy,
+                message: "Heap size: #{stats[:heap_available_slots]}, Live objects: #{stats[:heap_live_slots]}"
+              }
+            else
+              { status: :healthy, message: 'GC stats not available' }
+            end
+          end
+
+          # Thread count check
+          register(:thread_count, 'Active thread count') do
+            count = Thread.list.count
+            status = count > 100 ? :warning : :healthy
+            {
+              status: status,
+              message: "Active threads: #{count}"
+            }
+          end
+        end
+      end
+
+      # HTTP endpoint for health check exposure
+      # Provides an HTTP interface for accessing health check results
+      class Endpoint
+        def initialize(registry, path = '/health')
+          @registry = registry
+          @path = path
+        end
+
+        def call(env)
+          request = Rack::Request.new(env)
+
+          case request.path_info
+          when @path
+            handle_overall_health
+          when "#{@path}/check"
+            handle_individual_check(request.params['name'])
+          when "#{@path}/checks"
+            handle_checks_list
+          else
+            [404, {}, ['Not Found']]
+          end
+        rescue StandardError => e
+          [500, { 'Content-Type' => 'application/json' }, [JSON.generate({
+                                                                           error: 'Internal server error',
+                                                                           message: e.message
+                                                                         })]]
+        end
+
+        private
+
+        def handle_overall_health
+          result = @registry.run_all
+          status_code = result[:status] == :healthy ? 200 : 503
+
+          [status_code, json_headers, [JSON.generate(result)]]
+        end
+
+        def handle_individual_check(name)
+          return [400, json_headers, [JSON.generate({ error: 'Missing check name parameter' })]] unless name
+
+          result = @registry.run_check(name)
+          status_code = result[:status] == :healthy ? 200 : 503
+
+          [status_code, json_headers, [JSON.generate(result)]]
+        end
+
+        def handle_checks_list
+          checks = @registry.check_names.map do |name|
+            {
+              name: name,
+              url: "#{@path}/check?name=#{name}"
+            }
+          end
+
+          [200, json_headers, [JSON.generate({
+                                               available_checks: checks,
+                                               total: checks.length
+                                             })]]
+        end
+
+        def json_headers
+          { 'Content-Type' => 'application/json' }
+        end
+      end
+
+      class << self
+        attr_reader :registry
+
+        def configure(endpoint: '/health')
+          @registry = Registry.new
+          @endpoint_path = endpoint
+        end
+
+        def register(name, description = nil, &block)
+          @registry ||= Registry.new
+          @registry.register(name, description, &block)
+        end
+
+        def endpoint
+          @registry ||= Registry.new
+          Endpoint.new(@registry, @endpoint_path || '/health')
+        end
+
+        def enabled?
+          RapiTapir::Observability.config.health_check.enabled
+        end
+
+        def run_all
+          return { error: 'Health checks disabled' } unless enabled?
+
+          @registry ||= Registry.new
+          @registry.run_all
+        end
+      end
+    end
+  end
+end

data/lib/rapitapir/observability/logging.rb

@@ -0,0 +1,270 @@
+# frozen_string_literal: true
+
+require 'logger'
+require 'json'
+require 'securerandom'
+
+module RapiTapir
+  module Observability
+    # Structured logging system for RapiTapir
+    # Provides structured logging with multiple formatters and levels
+    module Logging
+      # Structured logger with contextual information
+      # Enhanced logger that adds structured data to log entries
+      class StructuredLogger
+        attr_reader :logger, :formatter
+
+        def initialize(output: $stdout, level: :info, format: :json)
+          @logger = ::Logger.new(output)
+          @logger.level = log_level(level)
+          @format = format
+          @formatter = create_formatter
+          @logger.formatter = @formatter
+        end
+
+        def debug(message = nil, **fields, &block)
+          log(:debug, message, **fields, &block)
+        end
+
+        def info(message = nil, **fields, &block)
+          log(:info, message, **fields, &block)
+        end
+
+        def warn(message = nil, **fields, &block)
+          log(:warn, message, **fields, &block)
+        end
+
+        def error(message = nil, **fields, &block)
+          log(:error, message, **fields, &block)
+        end
+
+        def fatal(message = nil, **fields, &block)
+          log(:fatal, message, **fields, &block)
+        end
+
+        def log_request(**options)
+          fields = build_request_log_fields(options)
+          status = options.fetch(:status)
+          method = options.fetch(:method)
+          path = options.fetch(:path)
+
+          level = determine_log_level_from_status(status)
+          message = build_request_log_message(method, path, status, fields[:duration_ms])
+
+          log(level, message, **fields)
+        end
+
+        private
+
+        def build_request_log_fields(options)
+          method = options.fetch(:method)
+          path = options.fetch(:path)
+          status = options.fetch(:status)
+          duration = options.fetch(:duration)
+          request_id = options[:request_id]
+          extra_fields = options.except(:method, :path, :status, :duration, :request_id)
+
+          request_data = {
+            method: method,
+            path: path,
+            status: status,
+            duration: duration,
+            request_id: request_id,
+            extra_fields: extra_fields
+          }
+
+          create_log_fields(request_data)
+        end
+
+        def create_log_fields(data)
+          {
+            event_type: 'http_request',
+            method: data[:method].to_s.upcase,
+            path: data[:path],
+            status: data[:status],
+            duration_ms: (data[:duration] * 1000).round(2),
+            request_id: data[:request_id] || generate_request_id
+          }.merge(data[:extra_fields])
+        end
+
+        def determine_log_level_from_status(status)
+          if status >= 500
+            :error
+          else
+            (status >= 400 ? :warn : :info)
+          end
+        end
+
+        def build_request_log_message(method, path, status, duration_ms)
+          "#{method.to_s.upcase} #{path} #{status} (#{duration_ms}ms)"
+        end
+
+        public
+
+        def log_error(exception, request_id: nil, **extra_fields)
+          fields = {
+            event_type: 'error',
+            error_class: exception.class.name,
+            error_message: exception.message,
+            error_backtrace: exception.backtrace&.first(10),
+            request_id: request_id
+          }.merge(extra_fields)
+
+          error("#{exception.class}: #{exception.message}", **fields)
+        end
+
+        private
+
+        def log(level, message = nil, **fields, &block)
+          return unless enabled?
+
+          message = block.call if block_given? && message.nil?
+
+          # Add common fields
+          fields = common_fields.merge(fields)
+          fields[:message] = message if message
+
+          @logger.public_send(level, fields)
+        end
+
+        def enabled?
+          RapiTapir::Observability.config.logging.enabled
+        end
+
+        def create_formatter
+          case @format
+          when :json
+            JsonFormatter.new
+          when :logfmt
+            LogfmtFormatter.new
+          else
+            TextFormatter.new
+          end
+        end
+
+        def common_fields
+          {
+            timestamp: Time.now.utc.iso8601,
+            service: 'rapitapir',
+            version: RapiTapir::VERSION,
+            process_id: Process.pid
+          }
+        end
+
+        def log_level(level)
+          case level.to_sym
+          when :debug then ::Logger::DEBUG
+          when :warn then ::Logger::WARN
+          when :error then ::Logger::ERROR
+          when :fatal then ::Logger::FATAL
+          else ::Logger::INFO # Default for :info and unknown levels
+          end
+        end
+
+        def generate_request_id
+          SecureRandom.hex(8)
+        end
+      end
+
+      # JSON formatter for structured log output
+      # Formats log entries as JSON for machine-readable logs
+      class JsonFormatter
+        def call(severity, timestamp, _progname, msg)
+          case msg
+          when Hash
+            msg_with_metadata = msg.merge(
+              level: severity,
+              timestamp: timestamp.utc.iso8601
+            )
+            "#{JSON.generate(msg_with_metadata)}\n"
+          else
+            "#{JSON.generate(
+              level: severity,
+              timestamp: timestamp.utc.iso8601,
+              message: msg.to_s
+            )}\n"
+          end
+        end
+      end
+
+      # Logfmt formatter for key-value log output
+      # Formats log entries using the logfmt key=value format
+      class LogfmtFormatter
+        def call(severity, timestamp, _progname, msg)
+          case msg
+          when Hash
+            fields = msg.map { |k, v| "#{k}=#{format_value(v)}" }
+            "#{fields.join(' ')}\n"
+          else
+            "level=#{severity} timestamp=#{timestamp.utc.iso8601} message=#{format_value(msg)}\n"
+          end
+        end
+
+        private
+
+        def format_value(value)
+          case value
+          when String
+            value.include?(' ') ? "\"#{value}\"" : value
+          when Array
+            "[#{value.join(',')}]"
+          else
+            value.to_s
+          end
+        end
+      end
+
+      # Plain text formatter for human-readable logs
+      # Formats log entries as readable text for development
+      class TextFormatter
+        def call(severity, timestamp, _progname, msg)
+          case msg
+          when Hash
+            message = msg.delete(:message) || ''
+            extra = msg.map { |k, v| "#{k}=#{v}" }.join(' ')
+            "#{timestamp.strftime('%Y-%m-%d %H:%M:%S')} [#{severity}] #{message} #{extra}\n"
+          else
+            "#{timestamp.strftime('%Y-%m-%d %H:%M:%S')} [#{severity}] #{msg}\n"
+          end
+        end
+      end
+
+      class << self
+        attr_reader :logger
+
+        def configure(output: $stdout, level: :info, format: :json, structured: true)
+          if structured
+            @logger = StructuredLogger.new(output: output, level: level, format: format)
+          else
+            @logger = ::Logger.new(output)
+            @logger.level = log_level(level)
+          end
+        end
+
+        def enabled?
+          RapiTapir::Observability.config.logging.enabled
+        end
+
+        %i[debug info warn error fatal].each do |level|
+          define_method(level) do |*args, **kwargs, &block|
+            return unless enabled?
+
+            @logger&.public_send(level, *args, **kwargs, &block)
+          end
+        end
+
+        def log_request(**args)
+          return unless enabled?
+
+          @logger&.log_request(**args)
+        end
+
+        def log_error(exception, **extra_fields)
+          return unless enabled?
+
+          @logger&.log_error(exception, **extra_fields)
+        end
+      end
+    end
+  end
+end