brainzlab 0.1.0

data/lib/brainzlab/instrumentation.rb

@@ -0,0 +1,132 @@
+# frozen_string_literal: true
+
+module BrainzLab
+  module Instrumentation
+    class << self
+      def install!
+        config = BrainzLab.configuration
+
+        # HTTP client instrumentation
+        if config.instrument_http
+          install_net_http!
+          install_faraday!
+          install_httparty!
+        end
+
+        # Database instrumentation (breadcrumbs for Reflex)
+        install_active_record! if config.instrument_active_record
+
+        # Redis instrumentation
+        install_redis! if config.instrument_redis
+
+        # Background job instrumentation
+        install_sidekiq! if config.instrument_sidekiq
+
+        # GraphQL instrumentation
+        install_graphql! if config.instrument_graphql
+
+        # MongoDB instrumentation
+        install_mongodb! if config.instrument_mongodb
+
+        # Elasticsearch instrumentation
+        install_elasticsearch! if config.instrument_elasticsearch
+
+        # ActionMailer instrumentation
+        install_action_mailer! if config.instrument_action_mailer
+
+        # Delayed::Job instrumentation
+        install_delayed_job! if config.instrument_delayed_job
+
+        # Grape API instrumentation
+        install_grape! if config.instrument_grape
+      end
+
+      def install_net_http!
+        require_relative "instrumentation/net_http"
+        NetHttp.install!
+      end
+
+      def install_faraday!
+        return unless defined?(::Faraday)
+
+        require_relative "instrumentation/faraday"
+        FaradayMiddleware.install!
+      end
+
+      def install_httparty!
+        return unless defined?(::HTTParty)
+
+        require_relative "instrumentation/httparty"
+        HTTPartyInstrumentation.install!
+      end
+
+      def install_active_record!
+        require_relative "instrumentation/active_record"
+        ActiveRecord.install!
+      end
+
+      def install_redis!
+        return unless defined?(::Redis)
+
+        require_relative "instrumentation/redis"
+        RedisInstrumentation.install!
+      end
+
+      def install_sidekiq!
+        return unless defined?(::Sidekiq)
+
+        require_relative "instrumentation/sidekiq"
+        SidekiqInstrumentation.install!
+      end
+
+      def install_graphql!
+        return unless defined?(::GraphQL)
+
+        require_relative "instrumentation/graphql"
+        GraphQLInstrumentation.install!
+      end
+
+      def install_mongodb!
+        return unless defined?(::Mongo) || defined?(::Mongoid)
+
+        require_relative "instrumentation/mongodb"
+        MongoDBInstrumentation.install!
+      end
+
+      def install_elasticsearch!
+        return unless defined?(::Elasticsearch) || defined?(::OpenSearch)
+
+        require_relative "instrumentation/elasticsearch"
+        ElasticsearchInstrumentation.install!
+      end
+
+      def install_action_mailer!
+        return unless defined?(::ActionMailer)
+
+        require_relative "instrumentation/action_mailer"
+        ActionMailerInstrumentation.install!
+      end
+
+      def install_delayed_job!
+        return unless defined?(::Delayed::Job) || defined?(::Delayed::Backend)
+
+        require_relative "instrumentation/delayed_job"
+        DelayedJobInstrumentation.install!
+      end
+
+      def install_grape!
+        return unless defined?(::Grape::API)
+
+        require_relative "instrumentation/grape"
+        GrapeInstrumentation.install!
+      end
+
+      # Manual installation methods for lazy-loaded libraries
+      def install_http!
+        install_net_http!
+        install_faraday!
+        install_httparty!
+      end
+    end
+  end
+end

data/lib/brainzlab/pulse/client.rb

@@ -0,0 +1,132 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "uri"
+require "json"
+
+module BrainzLab
+  module Pulse
+    class Client
+      MAX_RETRIES = 3
+      RETRY_DELAY = 0.5
+
+      def initialize(config)
+        @config = config
+        @buffer = []
+        @mutex = Mutex.new
+        @flush_thread = nil
+      end
+
+      def send_trace(payload)
+        return unless @config.pulse_enabled && @config.pulse_valid?
+
+        if @config.pulse_buffer_size > 1
+          buffer_trace(payload)
+        else
+          post("/api/v1/traces", payload)
+        end
+      end
+
+      def send_batch(payloads)
+        return unless @config.pulse_enabled && @config.pulse_valid?
+        return if payloads.empty?
+
+        post("/api/v1/traces/batch", { traces: payloads })
+      end
+
+      def send_metric(payload)
+        return unless @config.pulse_enabled && @config.pulse_valid?
+
+        post("/api/v1/metrics", payload)
+      end
+
+      def flush
+        traces_to_send = nil
+
+        @mutex.synchronize do
+          return if @buffer.empty?
+
+          traces_to_send = @buffer.dup
+          @buffer.clear
+        end
+
+        send_batch(traces_to_send) if traces_to_send&.any?
+      end
+
+      private
+
+      def buffer_trace(payload)
+        should_flush = false
+
+        @mutex.synchronize do
+          @buffer << payload
+          should_flush = @buffer.size >= @config.pulse_buffer_size
+        end
+
+        start_flush_timer unless @flush_thread&.alive?
+        flush if should_flush
+      end
+
+      def start_flush_timer
+        @flush_thread = Thread.new do
+          loop do
+            sleep(@config.pulse_flush_interval)
+            flush
+          end
+        end
+      end
+
+      def post(path, body)
+        uri = URI.join(@config.pulse_url, path)
+        request = Net::HTTP::Post.new(uri)
+        request["Content-Type"] = "application/json"
+        request["Authorization"] = "Bearer #{@config.pulse_auth_key}"
+        request["User-Agent"] = "brainzlab-sdk-ruby/#{BrainzLab::VERSION}"
+        request.body = JSON.generate(body)
+
+        execute_with_retry(uri, request)
+      rescue StandardError => e
+        log_error("Failed to send to Pulse: #{e.message}")
+        nil
+      end
+
+      def execute_with_retry(uri, request)
+        retries = 0
+        begin
+          http = Net::HTTP.new(uri.host, uri.port)
+          http.use_ssl = uri.scheme == "https"
+          http.open_timeout = 5
+          http.read_timeout = 10
+
+          response = http.request(request)
+
+          case response.code.to_i
+          when 200..299
+            JSON.parse(response.body) rescue {}
+          when 429, 500..599
+            raise RetryableError, "Server error: #{response.code}"
+          else
+            log_error("Pulse API error: #{response.code} - #{response.body}")
+            nil
+          end
+        rescue RetryableError, Net::OpenTimeout, Net::ReadTimeout => e
+          retries += 1
+          if retries <= MAX_RETRIES
+            sleep(RETRY_DELAY * retries)
+            retry
+          end
+          log_error("Failed after #{MAX_RETRIES} retries: #{e.message}")
+          nil
+        end
+      end
+
+      def log_error(message)
+        return unless @config.logger
+
+        @config.logger.error("[BrainzLab::Pulse] #{message}")
+      end
+
+      class RetryableError < StandardError; end
+    end
+  end
+end

data/lib/brainzlab/pulse/instrumentation.rb

@@ -0,0 +1,364 @@
+# frozen_string_literal: true
+
+module BrainzLab
+  module Pulse
+    class Instrumentation
+      class << self
+        def install!
+          return unless BrainzLab.configuration.pulse_enabled
+
+          install_active_record!
+          install_action_view!
+          install_active_support_cache!
+          install_action_controller!
+          install_http_clients!
+          install_active_job!
+          install_action_cable!
+        end
+
+        private
+
+        # Track SQL queries
+        def install_active_record!
+          return unless defined?(ActiveRecord)
+
+          ActiveSupport::Notifications.subscribe("sql.active_record") do |*args|
+            event = ActiveSupport::Notifications::Event.new(*args)
+            next if skip_query?(event.payload)
+
+            record_span(
+              name: event.payload[:name] || "SQL",
+              kind: "db",
+              started_at: event.time,
+              ended_at: event.end,
+              duration_ms: event.duration,
+              data: {
+                sql: truncate_sql(event.payload[:sql]),
+                name: event.payload[:name],
+                cached: event.payload[:cached] || false
+              }
+            )
+          end
+        end
+
+        # Track view rendering
+        def install_action_view!
+          return unless defined?(ActionView)
+
+          ActiveSupport::Notifications.subscribe("render_template.action_view") do |*args|
+            event = ActiveSupport::Notifications::Event.new(*args)
+
+            record_span(
+              name: short_path(event.payload[:identifier]),
+              kind: "render",
+              started_at: event.time,
+              ended_at: event.end,
+              duration_ms: event.duration,
+              data: {
+                identifier: event.payload[:identifier],
+                layout: event.payload[:layout]
+              }
+            )
+          end
+
+          ActiveSupport::Notifications.subscribe("render_partial.action_view") do |*args|
+            event = ActiveSupport::Notifications::Event.new(*args)
+
+            record_span(
+              name: short_path(event.payload[:identifier]),
+              kind: "render",
+              started_at: event.time,
+              ended_at: event.end,
+              duration_ms: event.duration,
+              data: {
+                identifier: event.payload[:identifier],
+                partial: true
+              }
+            )
+          end
+
+          ActiveSupport::Notifications.subscribe("render_collection.action_view") do |*args|
+            event = ActiveSupport::Notifications::Event.new(*args)
+
+            record_span(
+              name: short_path(event.payload[:identifier]),
+              kind: "render",
+              started_at: event.time,
+              ended_at: event.end,
+              duration_ms: event.duration,
+              data: {
+                identifier: event.payload[:identifier],
+                count: event.payload[:count],
+                collection: true
+              }
+            )
+          end
+        end
+
+        # Track cache operations
+        def install_active_support_cache!
+          %w[cache_read.active_support cache_write.active_support cache_delete.active_support].each do |event_name|
+            ActiveSupport::Notifications.subscribe(event_name) do |*args|
+              event = ActiveSupport::Notifications::Event.new(*args)
+              operation = event_name.split(".").first.sub("cache_", "")
+
+              record_span(
+                name: "Cache #{operation}",
+                kind: "cache",
+                started_at: event.time,
+                ended_at: event.end,
+                duration_ms: event.duration,
+                data: {
+                  key: truncate_key(event.payload[:key]),
+                  hit: event.payload[:hit],
+                  operation: operation
+                }
+              )
+            end
+          end
+        end
+
+        # Track controller processing for timing breakdown
+        def install_action_controller!
+          return unless defined?(ActionController)
+
+          ActiveSupport::Notifications.subscribe("process_action.action_controller") do |*args|
+            event = ActiveSupport::Notifications::Event.new(*args)
+            payload = event.payload
+
+            # Store timing breakdown in thread local for the middleware
+            Thread.current[:brainzlab_pulse_breakdown] = {
+              view_ms: payload[:view_runtime]&.round(2),
+              db_ms: payload[:db_runtime]&.round(2)
+            }
+          end
+        end
+
+        # Track external HTTP requests
+        def install_http_clients!
+          # Net::HTTP instrumentation
+          if defined?(Net::HTTP)
+            ActiveSupport::Notifications.subscribe("request.net_http") do |*args|
+              event = ActiveSupport::Notifications::Event.new(*args)
+
+              record_span(
+                name: "HTTP #{event.payload[:method]} #{event.payload[:host]}",
+                kind: "http",
+                started_at: event.time,
+                ended_at: event.end,
+                duration_ms: event.duration,
+                data: {
+                  method: event.payload[:method],
+                  host: event.payload[:host],
+                  path: event.payload[:path],
+                  status: event.payload[:code]
+                }
+              )
+            end
+          end
+
+          # Faraday instrumentation
+          if defined?(Faraday)
+            ActiveSupport::Notifications.subscribe("request.faraday") do |*args|
+              event = ActiveSupport::Notifications::Event.new(*args)
+              env = event.payload[:env]
+              next unless env
+
+              record_span(
+                name: "HTTP #{env.method.to_s.upcase} #{env.url.host}",
+                kind: "http",
+                started_at: event.time,
+                ended_at: event.end,
+                duration_ms: event.duration,
+                data: {
+                  method: env.method.to_s.upcase,
+                  host: env.url.host,
+                  path: env.url.path,
+                  status: env.status
+                }
+              )
+            end
+          end
+        end
+
+        # Track ActiveJob/SolidQueue
+        def install_active_job!
+          return unless defined?(ActiveJob)
+
+          # Track job enqueuing
+          ActiveSupport::Notifications.subscribe("enqueue.active_job") do |*args|
+            event = ActiveSupport::Notifications::Event.new(*args)
+            job = event.payload[:job]
+
+            record_span(
+              name: "Enqueue #{job.class.name}",
+              kind: "job",
+              started_at: event.time,
+              ended_at: event.end,
+              duration_ms: event.duration,
+              data: {
+                job_class: job.class.name,
+                job_id: job.job_id,
+                queue: job.queue_name
+              }
+            )
+          end
+
+          # Track job retry
+          ActiveSupport::Notifications.subscribe("retry_stopped.active_job") do |*args|
+            event = ActiveSupport::Notifications::Event.new(*args)
+            job = event.payload[:job]
+            error = event.payload[:error]
+
+            record_span(
+              name: "Retry stopped #{job.class.name}",
+              kind: "job",
+              started_at: event.time,
+              ended_at: event.end,
+              duration_ms: event.duration,
+              error: true,
+              error_class: error&.class&.name,
+              error_message: error&.message,
+              data: {
+                job_class: job.class.name,
+                job_id: job.job_id,
+                queue: job.queue_name,
+                executions: job.executions
+              }
+            )
+          end
+
+          # Track job discard
+          ActiveSupport::Notifications.subscribe("discard.active_job") do |*args|
+            event = ActiveSupport::Notifications::Event.new(*args)
+            job = event.payload[:job]
+            error = event.payload[:error]
+
+            record_span(
+              name: "Discarded #{job.class.name}",
+              kind: "job",
+              started_at: event.time,
+              ended_at: event.end,
+              duration_ms: event.duration,
+              error: true,
+              error_class: error&.class&.name,
+              error_message: error&.message,
+              data: {
+                job_class: job.class.name,
+                job_id: job.job_id,
+                queue: job.queue_name,
+                executions: job.executions
+              }
+            )
+          end
+        end
+
+        # Track ActionCable/SolidCable
+        def install_action_cable!
+          return unless defined?(ActionCable)
+
+          ActiveSupport::Notifications.subscribe("perform_action.action_cable") do |*args|
+            event = ActiveSupport::Notifications::Event.new(*args)
+
+            record_span(
+              name: "Cable #{event.payload[:channel_class]}##{event.payload[:action]}",
+              kind: "cable",
+              started_at: event.time,
+              ended_at: event.end,
+              duration_ms: event.duration,
+              data: {
+                channel: event.payload[:channel_class],
+                action: event.payload[:action]
+              }
+            )
+          end
+
+          ActiveSupport::Notifications.subscribe("transmit.action_cable") do |*args|
+            event = ActiveSupport::Notifications::Event.new(*args)
+
+            record_span(
+              name: "Cable transmit #{event.payload[:channel_class]}",
+              kind: "cable",
+              started_at: event.time,
+              ended_at: event.end,
+              duration_ms: event.duration,
+              data: {
+                channel: event.payload[:channel_class],
+                via: event.payload[:via]
+              }
+            )
+          end
+
+          ActiveSupport::Notifications.subscribe("broadcast.action_cable") do |*args|
+            event = ActiveSupport::Notifications::Event.new(*args)
+
+            record_span(
+              name: "Cable broadcast #{event.payload[:broadcasting]}",
+              kind: "cable",
+              started_at: event.time,
+              ended_at: event.end,
+              duration_ms: event.duration,
+              data: {
+                broadcasting: event.payload[:broadcasting],
+                coder: event.payload[:coder]
+              }
+            )
+          end
+        end
+
+        def record_span(name:, kind:, started_at:, ended_at:, duration_ms:, error: false, error_class: nil, error_message: nil, data: {})
+          spans = Thread.current[:brainzlab_pulse_spans]
+          return unless spans
+
+          span = {
+            span_id: SecureRandom.uuid,
+            name: name,
+            kind: kind,
+            started_at: started_at,
+            ended_at: ended_at,
+            duration_ms: duration_ms.round(2),
+            data: data.compact
+          }
+
+          if error
+            span[:error] = true
+            span[:error_class] = error_class
+            span[:error_message] = error_message
+          end
+
+          spans << span
+        end
+
+        def skip_query?(payload)
+          # Skip SCHEMA queries and internal Rails queries
+          return true if payload[:name] == "SCHEMA"
+          return true if payload[:name]&.start_with?("EXPLAIN")
+          return true if payload[:sql]&.include?("pg_")
+          return true if payload[:sql]&.include?("information_schema")
+          return true if payload[:cached] && !include_cached_queries?
+
+          false
+        end
+
+        def include_cached_queries?
+          false
+        end
+
+        def truncate_sql(sql)
+          return nil unless sql
+          sql.to_s[0, 1000]
+        end
+
+        def truncate_key(key)
+          return nil unless key
+          key.to_s[0, 200]
+        end
+
+        def short_path(path)
+          return nil unless path
+          path.to_s.split("/").last(2).join("/")
+        end
+      end
+    end
+  end
+end