rapitapir 0.1.0

data/lib/rapitapir/observability/metrics.rb

@@ -0,0 +1,203 @@
+# frozen_string_literal: true
+
+module RapiTapir
+  module Observability
+    # Metrics collection and management system
+    # Provides counters, gauges, and histograms for monitoring
+    module Metrics
+      # Registry for metrics collection and storage
+      # Manages metric definitions and their current values
+      class Registry
+        def initialize
+          @metrics = {}
+          @provider = nil
+        end
+
+        def configure(provider: :prometheus, namespace: 'rapitapir', custom_labels: {})
+          @provider = provider
+          @namespace = namespace
+          @custom_labels = custom_labels
+
+          case provider
+          when :prometheus
+            configure_prometheus
+          end
+        end
+
+        def counter(name, help: '', labels: [])
+          metric_name = "#{@namespace}_#{name}"
+          return @metrics[metric_name] if @metrics[metric_name]
+
+          case @provider
+          when :prometheus
+            require 'prometheus/client'
+            @metrics[metric_name] = ::Prometheus::Client::Counter.new(
+              metric_name.to_sym,
+              docstring: help,
+              labels: labels + @custom_labels.keys
+            )
+            ::Prometheus::Client.registry.register(@metrics[metric_name])
+          end
+
+          @metrics[metric_name]
+        end
+
+        def histogram(name, help: '', labels: [], buckets: nil)
+          metric_name = "#{@namespace}_#{name}"
+          return @metrics[metric_name] if @metrics[metric_name]
+
+          case @provider
+          when :prometheus
+            require 'prometheus/client'
+            buckets ||= [0.005, 0.01, 0.025, 0.05, 0.1, 0.25, 0.5, 1, 2.5, 5, 10]
+            @metrics[metric_name] = ::Prometheus::Client::Histogram.new(
+              metric_name.to_sym,
+              docstring: help,
+              labels: labels + @custom_labels.keys,
+              buckets: buckets
+            )
+            ::Prometheus::Client.registry.register(@metrics[metric_name])
+          end
+
+          @metrics[metric_name]
+        end
+
+        def gauge(name, help: '', labels: [])
+          metric_name = "#{@namespace}_#{name}"
+          return @metrics[metric_name] if @metrics[metric_name]
+
+          case @provider
+          when :prometheus
+            require 'prometheus/client'
+            @metrics[metric_name] = ::Prometheus::Client::Gauge.new(
+              metric_name.to_sym,
+              docstring: help,
+              labels: labels + @custom_labels.keys
+            )
+            ::Prometheus::Client.registry.register(@metrics[metric_name])
+          end
+
+          @metrics[metric_name]
+        end
+
+        def registry
+          case @provider
+          when :prometheus
+            require 'prometheus/client'
+            ::Prometheus::Client.registry
+          end
+        end
+
+        private
+
+        def configure_prometheus
+          require 'prometheus/client'
+          # Initialize default metrics
+          register_default_metrics
+        end
+
+        def register_default_metrics
+          # HTTP request metrics
+          counter(
+            :http_requests_total,
+            help: 'Total number of HTTP requests',
+            labels: %i[method endpoint status]
+          )
+
+          histogram(
+            :http_request_duration_seconds,
+            help: 'HTTP request duration in seconds',
+            labels: %i[method endpoint status]
+          )
+
+          # Error metrics
+          counter(
+            :http_errors_total,
+            help: 'Total number of HTTP errors',
+            labels: %i[method endpoint error_type]
+          )
+
+          # Active requests
+          gauge(
+            :http_active_requests,
+            help: 'Number of active HTTP requests',
+            labels: %i[method endpoint]
+          )
+        end
+      end
+
+      # Metrics collector for automatic metric gathering
+      # Automatically collects and updates metrics from various sources
+      class Collector
+        def initialize(registry)
+          @registry = registry
+        end
+
+        def record_request(method:, endpoint:, status:, duration:, error_type: nil)
+          labels = merge_custom_labels(method: method, endpoint: endpoint, status: status)
+
+          # Record request count
+          @registry.counter(:http_requests_total).increment(labels: labels)
+
+          # Record request duration
+          @registry.histogram(:http_request_duration_seconds).observe(duration, labels: labels)
+
+          # Record errors if present
+          return unless error_type
+
+          error_labels = merge_custom_labels(method: method, endpoint: endpoint, error_type: error_type)
+          @registry.counter(:http_errors_total).increment(labels: error_labels)
+        end
+
+        def increment_active_requests(method:, endpoint:)
+          labels = merge_custom_labels(method: method, endpoint: endpoint)
+          @registry.gauge(:http_active_requests).increment(labels: labels)
+        end
+
+        def decrement_active_requests(method:, endpoint:)
+          labels = merge_custom_labels(method: method, endpoint: endpoint)
+          @registry.gauge(:http_active_requests).decrement(labels: labels)
+        end
+
+        private
+
+        def merge_custom_labels(**labels)
+          custom_labels = @registry.instance_variable_get(:@custom_labels) || {}
+          labels.merge(custom_labels)
+        end
+      end
+
+      class << self
+        attr_reader :registry, :collector
+
+        def configure(provider: :prometheus, namespace: 'rapitapir', custom_labels: {})
+          @registry = Registry.new
+          @registry.configure(provider: provider, namespace: namespace, custom_labels: custom_labels)
+          @collector = Collector.new(@registry)
+        end
+
+        def enabled?
+          RapiTapir::Observability.config.metrics.enabled
+        end
+
+        def record_request(**args)
+          return unless enabled?
+
+          @collector&.record_request(**args)
+        end
+
+        def increment_active_requests(**args)
+          return unless enabled?
+
+          @collector&.increment_active_requests(**args)
+        end
+
+        def decrement_active_requests(**args)
+          return unless enabled?
+
+          @collector&.decrement_active_requests(**args)
+        end
+      end
+    end
+  end
+end

data/lib/rapitapir/observability/middleware.rb

@@ -0,0 +1,243 @@
+# frozen_string_literal: true
+
+require 'securerandom'
+
+module RapiTapir
+  module Observability
+    # Observability middleware for request tracking
+    # Middleware that collects metrics, logs, and traces for each request
+    class Middleware
+      def initialize(app)
+        @app = app
+      end
+
+      def call(env)
+        request_data = build_request_data(env)
+
+        # Increment active requests metric
+        if Metrics.enabled?
+          Metrics.increment_active_requests(method: request_data[:method],
+                                            endpoint: request_data[:path])
+        end
+
+        # Start tracing span
+        span_attributes = build_span_attributes(request_data)
+
+        Tracing.start_span("HTTP #{request_data[:method]}", attributes: span_attributes, kind: :server) do |span|
+          process_request_with_observability(request_data, span)
+        rescue StandardError => e
+          handle_request_error(request_data, span, e)
+        ensure
+          # Decrement active requests metric
+          if Metrics.enabled?
+            Metrics.decrement_active_requests(method: request_data[:method],
+                                              endpoint: request_data[:path])
+          end
+        end
+      end
+
+      private
+
+      def build_request_data(env)
+        request = Rack::Request.new(env)
+        request_id = extract_or_generate_request_id(env)
+
+        # Add request ID to environment for downstream use
+        env['HTTP_X_REQUEST_ID'] = request_id
+
+        {
+          request: request,
+          request_id: request_id,
+          method: request.request_method,
+          path: extract_path(request),
+          start_time: Time.now
+        }
+      end
+
+      def build_span_attributes(request_data)
+        request = request_data[:request]
+        {
+          'http.method' => request_data[:method],
+          'http.url' => request.url,
+          'http.route' => request_data[:path],
+          'http.user_agent' => request.user_agent,
+          'request.id' => request_data[:request_id]
+        }
+      end
+
+      def process_request_with_observability(request_data, span)
+        # Process request
+        status, headers, response = @app.call(request_data[:request].env)
+        duration = Time.now - request_data[:start_time]
+
+        # Add response attributes to span
+        span.set_attribute('http.status_code', status)
+        span.set_attribute('http.response.size', calculate_response_size(response))
+
+        # Record metrics and logs
+        record_request_observability(request_data, status, duration)
+
+        # Add request ID to response headers
+        headers['X-Request-ID'] = request_data[:request_id]
+
+        [status, headers, response]
+      end
+
+      def record_request_observability(request_data, status, duration)
+        # Record metrics
+        record_metrics(
+          method: request_data[:method],
+          endpoint: request_data[:path],
+          status: status,
+          duration: duration
+        )
+
+        # Log request
+        log_request(
+          method: request_data[:method],
+          path: request_data[:path],
+          status: status,
+          duration: duration,
+          request_id: request_data[:request_id],
+          user_agent: request_data[:request].user_agent,
+          remote_ip: request_data[:request].ip
+        )
+      end
+
+      def handle_request_error(request_data, span, error)
+        duration = Time.now - request_data[:start_time]
+        error_type = error.class.name
+
+        # Record error in span
+        span.record_exception(error)
+        span.set_attribute('error', true)
+
+        # Record error metrics
+        record_metrics(
+          method: request_data[:method],
+          endpoint: request_data[:path],
+          status: 500,
+          duration: duration,
+          error_type: error_type
+        )
+
+        # Log error
+        Logging.log_error(
+          error,
+          request_id: request_data[:request_id],
+          method: request_data[:method],
+          path: request_data[:path]
+        )
+
+        raise
+      end
+
+      def extract_or_generate_request_id(env)
+        # Try to extract from headers (X-Request-ID, X-Correlation-ID, etc.)
+        request_id = env['HTTP_X_REQUEST_ID'] ||
+                     env['HTTP_X_CORRELATION_ID'] ||
+                     env['HTTP_X_TRACE_ID']
+
+        request_id || SecureRandom.hex(8)
+      end
+
+      def extract_path(request)
+        # Extract the route pattern if available, otherwise use path
+        request.env['REQUEST_URI'] || request.path_info || request.path
+      end
+
+      def calculate_response_size(response)
+        return 0 unless response.respond_to?(:each)
+
+        size = 0
+        response.each { |chunk| size += chunk.bytesize if chunk.respond_to?(:bytesize) }
+        size
+      end
+
+      def record_metrics(method:, endpoint:, status:, duration:, error_type: nil)
+        return unless Metrics.enabled?
+
+        Metrics.record_request(
+          method: method,
+          endpoint: endpoint,
+          status: status,
+          duration: duration,
+          error_type: error_type
+        )
+      end
+
+      def log_request(**options)
+        return unless Logging.enabled?
+
+        Logging.log_request(**options)
+      end
+    end
+
+    # HTTP endpoint for exposing metrics
+    # Provides an HTTP interface for metrics scraping (Prometheus format)
+    class MetricsEndpoint
+      def initialize(registry = nil)
+        @registry = registry || Metrics.registry&.registry
+      end
+
+      def call(env)
+        return not_found unless @registry && Metrics.enabled?
+
+        request = Rack::Request.new(env)
+
+        case request.path_info
+        when '/metrics'
+          handle_prometheus_metrics
+        else
+          not_found
+        end
+      end
+
+      private
+
+      def handle_prometheus_metrics
+        require 'prometheus/client'
+
+        output = ::Prometheus::Client::Formats::Text.marshal(@registry)
+
+        [200, {
+          'Content-Type' => ::Prometheus::Client::Formats::Text::CONTENT_TYPE,
+          'Cache-Control' => 'no-cache'
+        }, [output]]
+      rescue StandardError => e
+        [500, { 'Content-Type' => 'text/plain' }, ["Error generating metrics: #{e.message}"]]
+      end
+
+      def not_found
+        [404, { 'Content-Type' => 'text/plain' }, ['Not Found']]
+      end
+    end
+
+    # Rack middleware for adding observability to the stack
+    class RackMiddleware
+      def self.new(app, **_options)
+        # Build middleware stack
+        stack = app
+
+        # Add health check endpoint if enabled
+        if RapiTapir::Observability.config.health_check.enabled
+          stack = Rack::URLMap.new({
+                                     RapiTapir::Observability.config.health_check.endpoint => HealthCheck.endpoint,
+                                     '/' => stack
+                                   })
+        end
+
+        # Add metrics endpoint if enabled
+        if RapiTapir::Observability.config.metrics.enabled
+          stack = Rack::URLMap.new({
+                                     '/metrics' => MetricsEndpoint.new,
+                                     '/' => stack
+                                   })
+        end
+
+        # Add observability middleware
+        Middleware.new(stack)
+      end
+    end
+  end
+end

data/lib/rapitapir/observability/tracing.rb

@@ -0,0 +1,143 @@
+# frozen_string_literal: true
+
+module RapiTapir
+  module Observability
+    # Distributed tracing system for request flow tracking
+    # Provides span creation and management for tracing requests
+    module Tracing
+      # Tracer for creating and managing spans
+      # Creates spans for tracking request execution across services
+      class Tracer
+        def initialize(service_name:, service_version:)
+          @service_name = service_name
+          @service_version = service_version
+          @provider = nil
+        end
+
+        def configure(provider: :opentelemetry)
+          @provider = provider
+          case provider
+          when :opentelemetry
+            configure_opentelemetry
+          end
+        end
+
+        def start_span(name, attributes: {}, kind: :server)
+          return yield(NoOpSpan.new) unless enabled?
+
+          case @provider
+          when :opentelemetry
+            require 'opentelemetry/api'
+            tracer = OpenTelemetry.tracer_provider.tracer(@service_name, @service_version)
+            span = tracer.start_span(name, kind: kind, attributes: attributes)
+            OpenTelemetry::Context.with_current_span(span) do
+              yield(span)
+            ensure
+              span.finish
+            end
+          end
+        end
+
+        def current_span
+          return NoOpSpan.new unless enabled?
+
+          case @provider
+          when :opentelemetry
+            require 'opentelemetry/api'
+            OpenTelemetry::Context.current_span
+          end
+        end
+
+        def add_event(name, attributes: {})
+          return unless enabled?
+
+          current_span.add_event(name, attributes: attributes)
+        end
+
+        def set_attribute(key, value)
+          return unless enabled?
+
+          current_span.set_attribute(key, value)
+        end
+
+        def record_exception(exception)
+          return unless enabled?
+
+          current_span.record_exception(exception)
+        end
+
+        private
+
+        def enabled?
+          RapiTapir::Observability.config.tracing.enabled
+        end
+
+        def configure_opentelemetry
+          require 'opentelemetry/sdk'
+          require 'opentelemetry/instrumentation/all'
+
+          OpenTelemetry::SDK.configure do |c|
+            c.service_name = @service_name
+            c.service_version = @service_version
+            c.use_all # Use all available instrumentation
+          end
+        rescue LoadError
+          warn 'OpenTelemetry SDK not available. Install opentelemetry-sdk and ' \
+               'opentelemetry-instrumentation-all gems.'
+        end
+      end
+
+      # No-operation span for disabled tracing
+      # Provides a null object pattern when tracing is disabled
+      class NoOpSpan
+        def add_event(name, attributes: {}); end
+        def set_attribute(key, value); end
+        def record_exception(exception); end
+        def finish; end
+      end
+
+      class << self
+        attr_reader :tracer
+
+        def configure(service_name:, service_version:, provider: :opentelemetry)
+          @tracer = Tracer.new(service_name: service_name, service_version: service_version)
+          @tracer.configure(provider: provider)
+        end
+
+        def enabled?
+          RapiTapir::Observability.config.tracing.enabled
+        end
+
+        def start_span(name, ...)
+          return yield(NoOpSpan.new) unless enabled?
+
+          @tracer&.start_span(name, ...)
+        end
+
+        def current_span
+          return NoOpSpan.new unless enabled?
+
+          @tracer&.current_span || NoOpSpan.new
+        end
+
+        def add_event(name, attributes: {})
+          return unless enabled?
+
+          @tracer&.add_event(name, attributes: attributes)
+        end
+
+        def set_attribute(key, value)
+          return unless enabled?
+
+          @tracer&.set_attribute(key, value)
+        end
+
+        def record_exception(exception)
+          return unless enabled?
+
+          @tracer&.record_exception(exception)
+        end
+      end
+    end
+  end
+end

data/lib/rapitapir/observability.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+require_relative 'observability/configuration'
+require_relative 'observability/metrics'
+require_relative 'observability/tracing'
+require_relative 'observability/logging'
+require_relative 'observability/health_check'
+require_relative 'observability/middleware'
+
+module RapiTapir
+  # Observability features for monitoring and debugging APIs
+  # Provides metrics collection, logging, tracing, and health checking
+  module Observability
+    class << self
+      attr_accessor :configuration
+
+      def configure
+        self.configuration ||= Configuration.new
+        yield(configuration) if block_given?
+        configuration
+      end
+
+      def config
+        self.configuration ||= Configuration.new
+      end
+    end
+  end
+end