brainzlab 0.1.0

data/lib/brainzlab/instrumentation/elasticsearch.rb

@@ -0,0 +1,210 @@
+# frozen_string_literal: true
+
+module BrainzLab
+  module Instrumentation
+    module ElasticsearchInstrumentation
+      @installed = false
+
+      class << self
+        def install!
+          return if @installed
+
+          installed_any = false
+
+          # Elasticsearch gem (elasticsearch-ruby)
+          if defined?(::Elasticsearch::Transport::Client)
+            install_elasticsearch_transport!
+            installed_any = true
+          end
+
+          # OpenSearch gem
+          if defined?(::OpenSearch::Client)
+            install_opensearch!
+            installed_any = true
+          end
+
+          # Elasticsearch 8.x with new client
+          if defined?(::Elastic::Transport::Client)
+            install_elastic_transport!
+            installed_any = true
+          end
+
+          return unless installed_any
+
+          @installed = true
+          BrainzLab.debug_log("Elasticsearch instrumentation installed")
+        end
+
+        def installed?
+          @installed
+        end
+
+        def reset!
+          @installed = false
+        end
+
+        private
+
+        def install_elasticsearch_transport!
+          ::Elasticsearch::Transport::Client.prepend(ClientPatch)
+        end
+
+        def install_opensearch!
+          ::OpenSearch::Client.prepend(ClientPatch)
+        end
+
+        def install_elastic_transport!
+          ::Elastic::Transport::Client.prepend(ClientPatch)
+        end
+      end
+
+      # Patch for Elasticsearch/OpenSearch clients
+      module ClientPatch
+        def perform_request(method, path, params = {}, body = nil, headers = nil)
+          return super unless should_track?
+
+          started_at = Time.now.utc
+          error_info = nil
+
+          begin
+            response = super
+            record_request(method, path, params, started_at, response.status)
+            response
+          rescue StandardError => e
+            error_info = e
+            record_request(method, path, params, started_at, nil, e)
+            raise
+          end
+        end
+
+        private
+
+        def should_track?
+          BrainzLab.configuration.instrument_elasticsearch
+        end
+
+        def record_request(method, path, params, started_at, status, error = nil)
+          duration_ms = ((Time.now.utc - started_at) * 1000).round(2)
+          operation = extract_operation(method, path)
+          index = extract_index(path)
+          level = error || (status && status >= 400) ? :error : :info
+
+          # Add breadcrumb for Reflex
+          if BrainzLab.configuration.reflex_enabled
+            BrainzLab::Reflex.add_breadcrumb(
+              "ES #{operation}",
+              category: "elasticsearch",
+              level: level,
+              data: {
+                method: method.to_s.upcase,
+                path: truncate_path(path),
+                index: index,
+                status: status,
+                duration_ms: duration_ms,
+                error: error&.class&.name
+              }.compact
+            )
+          end
+
+          # Record span for Pulse
+          record_span(
+            operation: operation,
+            method: method,
+            path: path,
+            index: index,
+            started_at: started_at,
+            duration_ms: duration_ms,
+            status: status,
+            error: error
+          )
+
+          # Log to Recall
+          if BrainzLab.configuration.recall_enabled
+            log_method = error ? :warn : :debug
+            BrainzLab::Recall.send(
+              log_method,
+              "ES #{method.to_s.upcase} #{path} -> #{status || 'ERROR'} (#{duration_ms}ms)",
+              method: method.to_s.upcase,
+              path: path,
+              index: index,
+              status: status,
+              duration_ms: duration_ms,
+              error: error&.message
+            )
+          end
+        rescue StandardError => e
+          BrainzLab.debug_log("Elasticsearch recording failed: #{e.message}")
+        end
+
+        def record_span(operation:, method:, path:, index:, started_at:, duration_ms:, status:, error:)
+          spans = Thread.current[:brainzlab_pulse_spans]
+          return unless spans
+
+          span = {
+            span_id: SecureRandom.uuid,
+            name: "ES #{operation}",
+            kind: "elasticsearch",
+            started_at: started_at,
+            ended_at: Time.now.utc,
+            duration_ms: duration_ms,
+            data: {
+              method: method.to_s.upcase,
+              path: truncate_path(path),
+              index: index,
+              status: status
+            }.compact
+          }
+
+          if error
+            span[:error] = true
+            span[:error_class] = error.class.name
+            span[:error_message] = error.message&.slice(0, 500)
+          end
+
+          spans << span
+        end
+
+        def extract_operation(method, path)
+          method_str = method.to_s.upcase
+
+          case path
+          when %r{/_search} then "search"
+          when %r{/_bulk} then "bulk"
+          when %r{/_count} then "count"
+          when %r{/_mget} then "mget"
+          when %r{/_msearch} then "msearch"
+          when %r{/_update_by_query} then "update_by_query"
+          when %r{/_delete_by_query} then "delete_by_query"
+          when %r{/_refresh} then "refresh"
+          when %r{/_mapping} then "mapping"
+          when %r{/_settings} then "settings"
+          when %r{/_alias} then "alias"
+          when %r{/_analyze} then "analyze"
+          else
+            case method_str
+            when "GET" then "get"
+            when "POST" then "index"
+            when "PUT" then "update"
+            when "DELETE" then "delete"
+            when "HEAD" then "exists"
+            else method_str.downcase
+            end
+          end
+        end
+
+        def extract_index(path)
+          # Extract index name from path like /my-index/_search
+          match = path.match(%r{^/([^/_]+)})
+          match[1] if match && !match[1].start_with?("_")
+        rescue StandardError
+          nil
+        end
+
+        def truncate_path(path)
+          return nil unless path
+          path.to_s[0, 200]
+        end
+      end
+    end
+  end
+end

data/lib/brainzlab/instrumentation/faraday.rb

@@ -0,0 +1,182 @@
+# frozen_string_literal: true
+
+module BrainzLab
+  module Instrumentation
+    module FaradayMiddleware
+      @installed = false
+
+      class << self
+        def install!
+          return unless defined?(::Faraday)
+          return if @installed
+
+          # Register the middleware with Faraday
+          ::Faraday::Middleware.register_middleware(brainzlab: Middleware)
+
+          @installed = true
+          BrainzLab.debug_log("Faraday instrumentation installed")
+        end
+
+        def installed?
+          @installed
+        end
+
+        def reset!
+          @installed = false
+        end
+      end
+
+      # Faraday middleware for HTTP request instrumentation
+      # Usage:
+      #   conn = Faraday.new do |f|
+      #     f.use :brainzlab
+      #     # or
+      #     f.use BrainzLab::Instrumentation::FaradayMiddleware::Middleware
+      #   end
+      class Middleware < ::Faraday::Middleware
+        def initialize(app, options = {})
+          super(app)
+          @options = options
+        end
+
+        def call(env)
+          return @app.call(env) unless should_track?(env)
+
+          # Inject distributed tracing context
+          inject_trace_context(env)
+
+          started_at = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+          error_info = nil
+
+          begin
+            response = @app.call(env)
+            track_request(env, response.status, started_at)
+            response
+          rescue ::Faraday::Error => e
+            error_info = e.class.name
+            track_request(env, e.response&.dig(:status), started_at, error_info)
+            raise
+          rescue StandardError => e
+            error_info = e.class.name
+            track_request(env, nil, started_at, error_info)
+            raise
+          end
+        end
+
+        private
+
+        def should_track?(env)
+          return false unless BrainzLab.configuration.instrument_http
+
+          ignore_hosts = BrainzLab.configuration.http_ignore_hosts || []
+          host = env.url.host
+          !ignore_hosts.include?(host)
+        end
+
+        def inject_trace_context(env)
+          return unless BrainzLab.configuration.pulse_enabled
+
+          headers = {}
+          BrainzLab::Pulse.inject(headers, format: :all)
+
+          headers.each do |key, value|
+            env.request_headers[key] = value
+          end
+        rescue StandardError => e
+          BrainzLab.debug_log("Failed to inject trace context: #{e.message}")
+        end
+
+        def track_request(env, status, started_at, error = nil)
+          duration_ms = ((Process.clock_gettime(Process::CLOCK_MONOTONIC) - started_at) * 1000).round(2)
+          method = env.method.to_s.upcase
+          url = sanitize_url(env.url)
+          host = env.url.host
+          path = env.url.path
+          level = error || (status && status >= 400) ? :error : :info
+
+          # Add breadcrumb for Reflex
+          if BrainzLab.configuration.reflex_enabled
+            BrainzLab::Reflex.add_breadcrumb(
+              "#{method} #{url}",
+              category: "http.faraday",
+              level: level,
+              data: {
+                method: method,
+                url: url,
+                host: host,
+                path: path,
+                status_code: status,
+                duration_ms: duration_ms,
+                error: error
+              }.compact
+            )
+          end
+
+          # Record span for Pulse APM
+          record_pulse_span(method, host, path, status, duration_ms, error)
+
+          # Log to Recall at debug level
+          if BrainzLab.configuration.recall_enabled
+            BrainzLab::Recall.debug(
+              "HTTP #{method} #{url} -> #{status || 'ERROR'}",
+              method: method,
+              url: url,
+              host: host,
+              status_code: status,
+              duration_ms: duration_ms,
+              error: error
+            )
+          end
+        rescue StandardError => e
+          BrainzLab.debug_log("Faraday instrumentation error: #{e.message}")
+        end
+
+        def record_pulse_span(method, host, path, status, duration_ms, error)
+          spans = Thread.current[:brainzlab_pulse_spans]
+          return unless spans
+
+          span = {
+            span_id: SecureRandom.uuid,
+            name: "HTTP #{method} #{host}",
+            kind: "http",
+            started_at: Time.now.utc - (duration_ms / 1000.0),
+            ended_at: Time.now.utc,
+            duration_ms: duration_ms,
+            data: {
+              method: method,
+              host: host,
+              path: path,
+              status: status
+            }.compact
+          }
+
+          if error
+            span[:error] = true
+            span[:error_class] = error
+          end
+
+          spans << span
+        end
+
+        def sanitize_url(url)
+          # Remove sensitive query parameters
+          uri = url.dup
+          if uri.query
+            params = URI.decode_www_form(uri.query).reject do |key, _|
+              sensitive_param?(key)
+            end
+            uri.query = params.empty? ? nil : URI.encode_www_form(params)
+          end
+          uri.to_s
+        rescue StandardError
+          url.to_s
+        end
+
+        def sensitive_param?(key)
+          key = key.to_s.downcase
+          %w[token api_key apikey secret password auth key].any? { |s| key.include?(s) }
+        end
+      end
+    end
+  end
+end

data/lib/brainzlab/instrumentation/grape.rb

@@ -0,0 +1,293 @@
+# frozen_string_literal: true
+
+module BrainzLab
+  module Instrumentation
+    module GrapeInstrumentation
+      @installed = false
+
+      class << self
+        def install!
+          return unless defined?(::Grape::API)
+          return if @installed
+
+          # Subscribe to Grape's ActiveSupport notifications
+          install_notifications!
+
+          @installed = true
+          BrainzLab.debug_log("Grape instrumentation installed")
+        end
+
+        def installed?
+          @installed
+        end
+
+        def reset!
+          @installed = false
+        end
+
+        private
+
+        def install_notifications!
+          # Grape emits these notifications
+          ActiveSupport::Notifications.subscribe("endpoint_run.grape") do |*args|
+            event = ActiveSupport::Notifications::Event.new(*args)
+            record_endpoint(event)
+          end
+
+          ActiveSupport::Notifications.subscribe("endpoint_render.grape") do |*args|
+            event = ActiveSupport::Notifications::Event.new(*args)
+            record_render(event)
+          end
+
+          ActiveSupport::Notifications.subscribe("endpoint_run_filters.grape") do |*args|
+            event = ActiveSupport::Notifications::Event.new(*args)
+            record_filters(event)
+          end
+
+          # Format validation
+          ActiveSupport::Notifications.subscribe("format_response.grape") do |*args|
+            event = ActiveSupport::Notifications::Event.new(*args)
+            record_format(event)
+          end
+        rescue StandardError => e
+          BrainzLab.debug_log("Grape notifications setup failed: #{e.message}")
+        end
+
+        def record_endpoint(event)
+          payload = event.payload
+          endpoint = payload[:endpoint]
+          env = payload[:env] || {}
+
+          method = env["REQUEST_METHOD"] || "GET"
+          path = endpoint&.options&.dig(:path)&.first || env["PATH_INFO"] || "/"
+          route_pattern = extract_route_pattern(endpoint)
+          duration_ms = event.duration.round(2)
+
+          status = env["api.endpoint"]&.status || 200
+          level = status >= 400 ? :error : :info
+
+          # Add breadcrumb for Reflex
+          if BrainzLab.configuration.reflex_enabled
+            BrainzLab::Reflex.add_breadcrumb(
+              "Grape #{method} #{route_pattern}",
+              category: "grape.endpoint",
+              level: level,
+              data: {
+                method: method,
+                path: path,
+                route: route_pattern,
+                status: status,
+                duration_ms: duration_ms
+              }.compact
+            )
+          end
+
+          # Record span for Pulse
+          record_span(
+            name: "Grape #{method} #{route_pattern}",
+            kind: "grape",
+            started_at: event.time,
+            ended_at: event.end,
+            duration_ms: duration_ms,
+            data: {
+              method: method,
+              path: path,
+              route: route_pattern,
+              status: status
+            }.compact,
+            error: status >= 500
+          )
+
+          # Log to Recall
+          if BrainzLab.configuration.recall_enabled
+            BrainzLab::Recall.info(
+              "Grape #{method} #{path} -> #{status} (#{duration_ms}ms)",
+              method: method,
+              path: path,
+              route: route_pattern,
+              status: status,
+              duration_ms: duration_ms
+            )
+          end
+        rescue StandardError => e
+          BrainzLab.debug_log("Grape endpoint recording failed: #{e.message}")
+        end
+
+        def record_render(event)
+          duration_ms = event.duration.round(2)
+
+          record_span(
+            name: "Grape render",
+            kind: "grape.render",
+            started_at: event.time,
+            ended_at: event.end,
+            duration_ms: duration_ms,
+            data: { phase: "render" }
+          )
+        rescue StandardError => e
+          BrainzLab.debug_log("Grape render recording failed: #{e.message}")
+        end
+
+        def record_filters(event)
+          payload = event.payload
+          duration_ms = event.duration.round(2)
+          filter_type = payload[:type] || "filter"
+
+          record_span(
+            name: "Grape #{filter_type} filters",
+            kind: "grape.filter",
+            started_at: event.time,
+            ended_at: event.end,
+            duration_ms: duration_ms,
+            data: { type: filter_type }
+          )
+        rescue StandardError => e
+          BrainzLab.debug_log("Grape filters recording failed: #{e.message}")
+        end
+
+        def record_format(event)
+          duration_ms = event.duration.round(2)
+
+          record_span(
+            name: "Grape format response",
+            kind: "grape.format",
+            started_at: event.time,
+            ended_at: event.end,
+            duration_ms: duration_ms,
+            data: { phase: "format" }
+          )
+        rescue StandardError => e
+          BrainzLab.debug_log("Grape format recording failed: #{e.message}")
+        end
+
+        def record_span(name:, kind:, started_at:, ended_at:, duration_ms:, data:, error: false)
+          spans = Thread.current[:brainzlab_pulse_spans]
+          return unless spans
+
+          spans << {
+            span_id: SecureRandom.uuid,
+            name: name,
+            kind: kind,
+            started_at: started_at,
+            ended_at: ended_at,
+            duration_ms: duration_ms,
+            data: data,
+            error: error
+          }
+        end
+
+        def extract_route_pattern(endpoint)
+          return "/" unless endpoint
+
+          route = endpoint.route
+          return "/" unless route
+
+          route.pattern&.path || route.path || "/"
+        rescue StandardError
+          "/"
+        end
+      end
+
+      # Middleware for Grape (alternative installation)
+      # Usage: use BrainzLab::Instrumentation::GrapeInstrumentation::Middleware
+      class Middleware
+        def initialize(app)
+          @app = app
+        end
+
+        def call(env)
+          return @app.call(env) unless should_trace?
+
+          started_at = Time.now.utc
+          request = Rack::Request.new(env)
+
+          # Initialize Pulse tracing
+          Thread.current[:brainzlab_pulse_spans] = []
+          Thread.current[:brainzlab_pulse_breakdown] = nil
+
+          # Extract parent trace context
+          parent_context = BrainzLab::Pulse.extract!(env)
+
+          begin
+            status, headers, response = @app.call(env)
+
+            record_trace(request, env, started_at, status, parent_context)
+
+            [status, headers, response]
+          rescue StandardError => e
+            record_trace(request, env, started_at, 500, parent_context, e)
+            raise
+          ensure
+            cleanup_context
+          end
+        end
+
+        private
+
+        def should_trace?
+          BrainzLab.configuration.pulse_enabled
+        end
+
+        def cleanup_context
+          Thread.current[:brainzlab_pulse_spans] = nil
+          Thread.current[:brainzlab_pulse_breakdown] = nil
+          BrainzLab::Context.clear!
+          BrainzLab::Pulse::Propagation.clear!
+        end
+
+        def record_trace(request, env, started_at, status, parent_context, error = nil)
+          ended_at = Time.now.utc
+          duration_ms = ((ended_at - started_at) * 1000).round(2)
+
+          method = request.request_method
+          path = request.path
+
+          # Get route pattern from Grape if available
+          route_pattern = env["grape.routing_args"]&.dig(:route_info)&.pattern&.path || path
+
+          spans = Thread.current[:brainzlab_pulse_spans] || []
+
+          payload = {
+            trace_id: SecureRandom.uuid,
+            name: "#{method} #{route_pattern}",
+            kind: "request",
+            started_at: started_at.utc.iso8601(3),
+            ended_at: ended_at.utc.iso8601(3),
+            duration_ms: duration_ms,
+            request_method: method,
+            request_path: path,
+            status: status,
+            error: error.present? || status >= 500,
+            error_class: error&.class&.name,
+            error_message: error&.message&.slice(0, 1000),
+            spans: spans.map { |s| format_span(s) },
+            environment: BrainzLab.configuration.environment,
+            commit: BrainzLab.configuration.commit,
+            host: BrainzLab.configuration.host
+          }
+
+          if parent_context&.valid?
+            payload[:parent_trace_id] = parent_context.trace_id
+            payload[:parent_span_id] = parent_context.span_id
+          end
+
+          BrainzLab::Pulse.client.send_trace(payload.compact)
+        rescue StandardError => e
+          BrainzLab.debug_log("Grape trace recording failed: #{e.message}")
+        end
+
+        def format_span(span)
+          {
+            span_id: span[:span_id],
+            name: span[:name],
+            kind: span[:kind],
+            started_at: span[:started_at]&.utc&.iso8601(3),
+            ended_at: span[:ended_at]&.utc&.iso8601(3),
+            duration_ms: span[:duration_ms],
+            data: span[:data]
+          }.compact
+        end
+      end
+    end
+  end
+end