speedshop-cloudwatch 0.1.0

data/lib/speedshop/cloudwatch/puma.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+module Speedshop
+  module Cloudwatch
+    class Puma
+      def collect
+        stats = ::Puma.stats_hash
+
+        if stats[:worker_status]
+          %i[workers booted_workers old_workers].each do |m|
+            Reporter.instance.report(metric: metric_name_for(m), value: stats[m] || 0)
+          end
+          report_aggregate_worker_stats(stats)
+        else
+          # Single mode - report worker stats without dimensions
+          %i[running backlog pool_capacity max_threads].each do |m|
+            Reporter.instance.report(metric: metric_name_for(m), value: stats[m] || 0)
+          end
+        end
+      rescue => e
+        Speedshop::Cloudwatch.log_error("Failed to collect Puma metrics: #{e.message}", e)
+      end
+
+      private
+
+      def report_aggregate_worker_stats(stats)
+        statuses = stats[:worker_status].map { |w| w[:last_status] || {} }
+        metrics = %i[running backlog pool_capacity max_threads]
+
+        metrics.each do |m|
+          values = statuses.map { |s| s[m] }.compact
+          next if values.empty?
+
+          sample_count = values.length
+          sum = values.inject(0) { |acc, v| acc + v.to_f }
+          minimum = values.min.to_f
+          maximum = values.max.to_f
+
+          Reporter.instance.report(
+            metric: metric_name_for(m),
+            statistic_values: {
+              sample_count: sample_count,
+              sum: sum,
+              minimum: minimum,
+              maximum: maximum
+            },
+            integration: :puma
+          )
+        end
+      end
+
+      def metric_name_for(symbol)
+        symbol.to_s.split("_").map(&:capitalize).join.to_sym
+      end
+    end
+  end
+end

data/lib/speedshop/cloudwatch/rack.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Speedshop
+  module Cloudwatch
+    class Rack
+      def initialize(app)
+        @app = app
+      end
+
+      def call(env)
+        begin
+          if (header = env["HTTP_X_REQUEST_START"] || env["HTTP_X_QUEUE_START"])
+            queue_time = (Time.now.to_f * 1000) - header.gsub("t=", "").to_f
+            Reporter.instance.report(metric: :RequestQueueTime, value: queue_time)
+          end
+        rescue => e
+          Speedshop::Cloudwatch.log_error("Failed to collect Rack metrics: #{e.message}", e)
+        end
+        @app.call(env)
+      end
+    end
+  end
+end

data/lib/speedshop/cloudwatch/railtie.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module Speedshop
+  module Cloudwatch
+    class Railtie < ::Rails::Railtie
+      initializer "speedshop.cloudwatch.insert_middleware", before: :build_middleware_stack do |app|
+        unless caller.any? { |c| c.include?("console_command.rb") || c.include?("runner_command.rb") } || self.class.in_rake_task?
+          app.config.middleware.insert_before 0, Speedshop::Cloudwatch::Rack
+        end
+      end
+
+      def self.in_rake_task?
+        return false unless defined?(::Rake) && ::Rake.respond_to?(:application)
+        tasks = ::Rake.application&.top_level_tasks
+        tasks&.any? || false
+      end
+    end
+  end
+end

data/lib/speedshop/cloudwatch/reporter.rb

@@ -0,0 +1,315 @@
+# frozen_string_literal: true
+
+require "singleton"
+require_relative "metrics"
+
+module Speedshop
+  module Cloudwatch
+    class Reporter
+      include Singleton
+
+      def initialize
+        @mutex = Mutex.new
+        @condition_variable = ConditionVariable.new
+        @queue = []
+        @collectors = []
+        @thread = nil
+        @pid = Process.pid
+        @running = false
+        @dropped_since_last_flush = 0
+        @last_overflow_log = nil
+      end
+
+      def start!
+        return if !config.environment_enabled? || started?
+
+        @mutex.synchronize do
+          return if started?
+
+          initialize_collectors
+          if forked?
+            @collectors.clear
+            @queue.clear
+          end
+
+          Speedshop::Cloudwatch.log_info("Starting metric reporter (collectors: #{@collectors.map(&:class).join(", ")})")
+          @running = true
+          @thread = Thread.new do
+            Thread.current.thread_variable_set(:fork_safe, true)
+            Thread.current.name = "scw_reporter"
+            run_loop
+          end
+        end
+      end
+
+      def started?
+        @running && @thread&.alive?
+      end
+
+      def stop!
+        thread_to_join = nil
+        @mutex.synchronize do
+          return unless @running
+          Speedshop::Cloudwatch.log_info("Stopping metric reporter")
+          @running = false
+          @condition_variable.signal
+          thread_to_join = @thread
+          @thread = @pid = nil
+          @collectors.clear
+        end
+
+        return unless thread_to_join
+
+        result = thread_to_join.join(2)
+        if result.nil?
+          Speedshop::Cloudwatch.log_info("Reporter thread did not finish within 2s timeout")
+        else
+          Speedshop::Cloudwatch.log_info("Reporter thread stopped gracefully")
+        end
+      end
+
+      def report(metric:, value: nil, statistic_values: nil, dimensions: {}, integration: nil)
+        return unless config.environment_enabled?
+
+        metric_name = metric.to_sym
+        int = integration || find_integration_for_metric(metric_name)
+        return unless int
+        return unless metric_allowed?(int, metric_name)
+
+        metric_object = METRICS[int]&.find { |m| m.name == metric_name }
+        ns = config.namespaces[int]
+        unit = metric_object&.unit || "None"
+
+        dimensions_array = dimensions.map { |k, v| {name: k.to_s, value: v.to_s} }
+        all_dimensions = dimensions_array + custom_dimensions
+
+        datum = {metric_name: metric_name.to_s, namespace: ns, unit: unit,
+                 dimensions: all_dimensions, timestamp: Time.now}
+        if statistic_values
+          datum[:statistic_values] = statistic_values
+        else
+          datum[:value] = value
+        end
+
+        @mutex.synchronize do
+          if @queue.size >= config.queue_max_size
+            @queue.shift
+            @dropped_since_last_flush += 1
+          end
+          @queue << datum
+        end
+
+        start! unless started?
+      end
+
+      def clear_all
+        @mutex.synchronize do
+          @queue.clear
+          @collectors.clear
+        end
+      end
+
+      # Force immediate metrics collection and flush (for testing)
+      # This bypasses the normal interval-based flushing
+      def flush_now!
+        return unless @running
+
+        collect_metrics
+        flush_metrics
+      end
+
+      def self.reset
+        if instance_variable_defined?(:@singleton__instance__)
+          reporter = instance_variable_get(:@singleton__instance__)
+          reporter&.stop! if reporter&.started?
+          reporter&.clear_all
+        end
+        instance_variable_set(:@singleton__instance__, nil)
+      end
+
+      private
+
+      def config
+        Config.instance
+      end
+
+      def forked?
+        @pid != Process.pid
+      end
+
+      def initialize_collectors
+        config.collectors.each do |integration|
+          @collectors << Speedshop::Cloudwatch::Puma.new if integration == :puma
+          @collectors << Speedshop::Cloudwatch::Sidekiq.new if integration == :sidekiq
+        rescue => e
+          Speedshop::Cloudwatch.log_error("Failed to initialize collector for #{integration}: #{e.message}", e)
+        end
+      end
+
+      def run_loop
+        while @running
+          @mutex.synchronize do
+            @condition_variable.wait(@mutex, config.interval) if @running
+          end
+          break unless @running
+          collect_metrics
+          flush_metrics
+        end
+
+        flush_metrics
+      rescue => e
+        Speedshop::Cloudwatch.log_error("Reporter error: #{e.message}", e)
+      end
+
+      def collect_metrics
+        @collectors.each do |collector|
+          collector.collect
+        rescue => e
+          Speedshop::Cloudwatch.log_error("Collector error: #{e.message}", e)
+        end
+      end
+
+      def flush_metrics
+        metrics = drain_queue
+        log_overflow_if_needed
+        return unless metrics
+
+        high_resolution = config.interval.to_i < 60
+        metrics.group_by { |m| m[:namespace] }.each do |namespace, ns_metrics|
+          process_namespace(namespace, ns_metrics, high_resolution)
+        end
+      rescue => e
+        Speedshop::Cloudwatch.log_error("Failed to send metrics: #{e.message}", e)
+      end
+
+      def drain_queue
+        buf = nil
+        @mutex.synchronize do
+          return nil if @queue.empty?
+          buf = @queue
+          @queue = []
+        end
+        buf
+      end
+
+      def process_namespace(namespace, ns_metrics, high_resolution)
+        config.logger.debug "Speedshop::Cloudwatch: Sending #{ns_metrics.size} metrics to namespace #{namespace}"
+        aggregated = aggregate_namespace_metrics(ns_metrics)
+        metric_data = build_metric_data(aggregated, high_resolution)
+        send_batches(namespace, metric_data)
+      end
+
+      def build_metric_data(aggregated, high_resolution)
+        aggregated.map do |m|
+          datum = {
+            metric_name: m[:metric_name],
+            unit: m[:unit],
+            timestamp: m[:timestamp],
+            dimensions: m[:dimensions]
+          }
+          if m[:statistic_values]
+            datum[:statistic_values] = m[:statistic_values]
+          else
+            datum[:value] = m[:value]
+          end
+          datum[:storage_resolution] = 1 if high_resolution
+          datum
+        end
+      end
+
+      def send_batches(namespace, metric_data)
+        metric_data.each_slice(20) do |batch|
+          config.client.put_metric_data(namespace: namespace, metric_data: batch)
+        end
+      end
+
+      def aggregate_namespace_metrics(ns_metrics)
+        group_metrics(ns_metrics).map { |items| aggregate_group(items) }
+      end
+
+      def group_metrics(ns_metrics)
+        groups = {}
+        ns_metrics.each do |m|
+          key = [m[:metric_name], m[:unit], normalized_dimensions_key(m[:dimensions])]
+          (groups[key] ||= []) << m
+        end
+        groups.values
+      end
+
+      def aggregate_group(items)
+        return items.first if items.size == 1
+
+        sample_count, sum, minimum, maximum = aggregate_values(items)
+        {
+          metric_name: items.first[:metric_name],
+          unit: items.first[:unit],
+          dimensions: items.first[:dimensions],
+          timestamp: Time.now,
+          statistic_values: build_statistic_values(sample_count, sum, minimum, maximum)
+        }
+      end
+
+      def aggregate_values(items)
+        sample_count = 0.0
+        sum = 0.0
+        minimum = Float::INFINITY
+        maximum = -Float::INFINITY
+
+        items.each do |item|
+          if item[:statistic_values]
+            sv = item[:statistic_values]
+            sc = sv[:sample_count].to_f
+            sample_count += sc
+            sum += sv[:sum].to_f
+            minimum = [minimum, sv[:minimum].to_f].min
+            maximum = [maximum, sv[:maximum].to_f].max
+          elsif item.key?(:value)
+            v = item[:value].to_f
+            sample_count += 1.0
+            sum += v
+            minimum = [minimum, v].min
+            maximum = [maximum, v].max
+          end
+        end
+
+        [sample_count, sum, minimum, maximum]
+      end
+
+      def build_statistic_values(sample_count, sum, minimum, maximum)
+        {
+          sample_count: sample_count,
+          sum: sum,
+          minimum: minimum.finite? ? minimum : 0.0,
+          maximum: maximum.finite? ? maximum : 0.0
+        }
+      end
+
+      def normalized_dimensions_key(dims)
+        (dims || []).sort_by { |d| d[:name].to_s }.map { |d| "#{d[:name]}=#{d[:value]}" }.join("|")
+      end
+
+      def metric_allowed?(integration, metric_name)
+        config.metrics[integration].include?(metric_name.to_sym)
+      end
+
+      def custom_dimensions
+        config.dimensions.map { |name, value| {name: name.to_s, value: value.to_s} }
+      end
+
+      def find_integration_for_metric(metric_name)
+        METRICS.find { |int, metrics| metrics.any? { |m| m.name == metric_name } }&.first
+      end
+
+      def log_overflow_if_needed
+        dropped = nil
+        @mutex.synchronize do
+          dropped = @dropped_since_last_flush
+          @dropped_since_last_flush = 0
+        end
+        return unless dropped > 0
+
+        Speedshop::Cloudwatch.log_error("Queue overflow: dropped #{dropped} oldest metric(s) (max queue size: #{config.queue_max_size})")
+      end
+    end
+  end
+end

data/lib/speedshop/cloudwatch/sidekiq.rb

@@ -0,0 +1,118 @@
+# frozen_string_literal: true
+
+# Portions of this code adapted from sidekiq-cloudwatchmetrics
+# Copyright (c) 2018 Samuel Cochran
+# https://github.com/sj26/sidekiq-cloudwatchmetrics
+#
+# The MIT License (MIT)
+#
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+#
+# The above copyright notice and this permission notice shall be included in
+# all copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+# THE SOFTWARE.
+
+require "sidekiq/api" if defined?(::Sidekiq)
+
+module Speedshop
+  module Cloudwatch
+    class Sidekiq
+      def collect
+        stats = ::Sidekiq::Stats.new
+        processes = ::Sidekiq::ProcessSet.new.to_a
+
+        report_stats(stats)
+        report_utilization(processes)
+        report_queue_metrics
+      rescue => e
+        Speedshop::Cloudwatch.log_error("Failed to collect Sidekiq metrics: #{e.message}", e)
+      end
+
+      class << self
+        def setup_lifecycle_hooks
+          ::Sidekiq.configure_server do |sidekiq_config|
+            if defined?(Sidekiq::Enterprise)
+              sidekiq_config.on(:leader) do
+                Speedshop::Cloudwatch.configure { |c| c.collectors << :sidekiq }
+                Speedshop::Cloudwatch.start!
+              end
+            else
+              sidekiq_config.on(:startup) do
+                Speedshop::Cloudwatch.configure { |c| c.collectors << :sidekiq }
+                Speedshop::Cloudwatch.start!
+              end
+            end
+
+            sidekiq_config.on(:quiet) do
+              Speedshop::Cloudwatch.stop!
+            end
+
+            sidekiq_config.on(:shutdown) do
+              Speedshop::Cloudwatch.stop!
+            end
+          end
+        end
+      end
+
+      private
+
+      def reporter
+        Speedshop::Cloudwatch.reporter
+      end
+
+      def report_stats(stats)
+        {
+          EnqueuedJobs: stats.enqueued, ProcessedJobs: stats.processed, FailedJobs: stats.failed,
+          ScheduledJobs: stats.scheduled_size, RetryJobs: stats.retry_size, DeadJobs: stats.dead_size,
+          Workers: stats.workers_size, Processes: stats.processes_size,
+          DefaultQueueLatency: stats.default_queue_latency
+        }.each { |m, v| reporter.report(metric: m, value: v, integration: :sidekiq) }
+      end
+
+      def report_utilization(processes)
+        capacity = processes.sum { |p| p["concurrency"] }
+        reporter.report(metric: :Capacity, value: capacity)
+
+        utilization = avg_utilization(processes) * 100.0
+        reporter.report(metric: :Utilization, value: utilization) unless utilization.nan?
+      end
+
+      def report_queue_metrics
+        queues_to_monitor.each do |q|
+          reporter.report(metric: :QueueLatency, value: q.latency, dimensions: {QueueName: q.name})
+          reporter.report(metric: :QueueSize, value: q.size, dimensions: {QueueName: q.name})
+        end
+      end
+
+      def queues_to_monitor
+        all_queues = ::Sidekiq::Queue.all
+        configured = Speedshop::Cloudwatch.config.sidekiq_queues
+
+        if configured.nil? || configured.empty?
+          all_queues
+        else
+          all_queues.select { |q| configured.include?(q.name) }
+        end
+      end
+
+      def avg_utilization(processes)
+        utils = processes.map { |p| p["busy"] / p["concurrency"].to_f }.reject(&:nan?)
+        utils.sum / utils.size.to_f
+      end
+    end
+  end
+end
+
+Speedshop::Cloudwatch::Sidekiq.setup_lifecycle_hooks

data/lib/speedshop/cloudwatch/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Speedshop
+  module Cloudwatch
+    VERSION = "0.1.0"
+  end
+end

data/lib/speedshop/cloudwatch.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+require "aws-sdk-cloudwatch"
+require "speedshop/cloudwatch/config"
+require "speedshop/cloudwatch/reporter"
+require "speedshop/cloudwatch/version"
+
+module Speedshop
+  module Cloudwatch
+    class Error < StandardError; end
+
+    class << self
+      def configure
+        yield Config.instance if block_given?
+        Config.instance
+      end
+
+      def config
+        Config.instance
+      end
+
+      def reporter
+        Reporter.instance
+      end
+
+      def start!
+        reporter.start!
+      end
+
+      def stop!
+        reporter.stop!
+      end
+
+      def log_info(msg)
+        Config.instance.logger.info "Speedshop::Cloudwatch: #{msg}"
+      end
+
+      def log_error(msg, exception = nil)
+        Config.instance.logger.error "Speedshop::Cloudwatch: #{msg}"
+        Config.instance.logger.debug exception.backtrace.join("\n") if exception&.backtrace
+      end
+    end
+  end
+end
+
+at_exit do
+  Speedshop::Cloudwatch.stop!
+end

data/lib/speedshop-cloudwatch.rb

@@ -0,0 +1,3 @@
+# frozen_string_literal: true
+
+require "speedshop/cloudwatch/all"

data/speedshop-cloudwatch.gemspec

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+require_relative "lib/speedshop/cloudwatch/version"
+
+Gem::Specification.new do |spec|
+  spec.name = "speedshop-cloudwatch"
+  spec.version = Speedshop::Cloudwatch::VERSION
+  spec.authors = ["Nate Berkopec"]
+  spec.email = ["nate.berkopec@speedshop.co"]
+
+  spec.summary = "Ruby application integration with AWS CloudWatch for Puma, Rack, Sidekiq, and ActiveJob"
+  spec.description = "This gem helps integrate your Ruby application with AWS CloudWatch, reporting metrics from Puma, Rack, Sidekiq, and ActiveJob in background threads to avoid adding latency to requests and jobs."
+  spec.homepage = "https://github.com/nateberkopec/speedshop-cloudwatch"
+  spec.license = "MIT"
+  spec.required_ruby_version = ">= 2.7.0"
+
+  spec.metadata["allowed_push_host"] = "https://rubygems.org"
+  spec.metadata["homepage_uri"] = spec.homepage
+  spec.metadata["source_code_uri"] = "https://github.com/nateberkopec/speedshop-cloudwatch"
+
+  spec.files = IO.popen(%w[git ls-files -z], chdir: __dir__, err: IO::NULL) do |ls|
+    ls.readlines("\x0", chomp: true).select do |path|
+      path.start_with?("lib/", "bin/", "docs/") ||
+        %w[README.md LICENSE.txt speedshop-cloudwatch.gemspec Rakefile].include?(path)
+    end
+  end
+  spec.require_paths = ["lib"]
+
+  spec.add_dependency "aws-sdk-cloudwatch", ">= 1.81.0"
+end