solid_apm 0.9.0 → 0.10.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: dc8464230e852711199328548a375cc742873a408f04b34fd793e305d854420a
-  data.tar.gz: 27a42427c5fb310b459bcf673c9fedd4dc1a0d0852a15fb4fa367bc6fed475a8
+  metadata.gz: e3d5be7324da26b5f4720bc0ba9e61717be304286b9ecad84e09adf503095699
+  data.tar.gz: 8969d758c906bb7de44b4024e1f7353bc63f1f4dda0f2ee5631df1e2fa436e2e
 SHA512:
-  metadata.gz: c249809b73d29facaccf681ba95bf60fce23debccc69850f8bb309d826d5b13e7ec093d2acb5346518e0e1c8b5a479743735fa7071a69b63e5a3672f3c5edb00
-  data.tar.gz: '093e4a4e39e436b26307a67559517ac2e1cc3e3375aa7afeb980db674301e0571b74e74ad68ca8895667557465461e790b1158d0ab8c48f16f53ad301cb37eb8'
+  metadata.gz: 1ed2237e30cabd350515555a5e6a66006777835d4e07adcc2dc2758f0fe8e474e931e3da204f44309671923ba1eb1fbcbc32203eaf459a6cebffc2eb3030f3fa
+  data.tar.gz: fb86bb4e14bf08207255ca5e0121b6e50a5ba43e3a4d394d777362df614d47d25e0d54508a66660c01c7ecccf3c53cc00b395981bee6a32378a5903ca64dd268

data/README.md

@@ -52,6 +52,113 @@ class ApplicationController
 end
 ```
 
+## Configuration
+
+SolidAPM can be configured using the following options in your `config/initializers/solid_apm.rb` file:
+
+### Database Connection
+
+Configure the database connection for SolidAPM:
+
+```ruby
+SolidApm.connects_to = { database: { writing: :solid_apm } }
+```
+
+### ActiveRecord Logger Silencing
+
+Control whether ActiveRecord logger is silenced during SolidAPM operations (default: `true`):
+
+```ruby
+# Disable ActiveRecord logger silencing to see SQL queries in logs
+SolidApm.silence_active_record_logger = false
+```
+
+### Transaction Sampling
+
+Control the sampling rate for transactions using a "1 out of N" approach (default: `1`):
+
+```ruby
+# Sample every transaction (default behavior)
+SolidApm.transaction_sampling = 1
+
+# Sample 1 out of every 2 transactions (50% sampling)
+SolidApm.transaction_sampling = 2
+
+# Sample 1 out of every 5 transactions (20% sampling)  
+SolidApm.transaction_sampling = 5
+
+# Sample 1 out of every 10 transactions (10% sampling)
+SolidApm.transaction_sampling = 10
+```
+
+The sampling is done per-thread using a round-robin counter, ensuring even distribution across requests.
+This is useful for high-traffic applications where you want to reduce the volume of
+APM data while still maintaining representative performance insights.
+
+### Transaction Name Filtering
+
+Filter specific transactions by name using exact string matches or regular expressions:
+
+```ruby
+# Filter specific transactions by exact name
+SolidApm.transaction_filters += ['HomeController#index', /^Rails::HealthController/]
+```
+
+## Data Cleanup
+
+SolidAPM provides a rake task to clean up old transaction data to manage database size over time.
+
+### Manual Cleanup
+
+Clean up transactions older than 1 month (default):
+
+```shell
+bin/rails solid_apm:cleanup
+```
+
+Clean up transactions with custom time periods:
+
+```shell
+# Delete transactions older than 1 week
+bin/rails solid_apm:cleanup[1.week.ago]
+```
+
+### Automated Cleanup with ActiveJob
+
+For production applications, it's recommended to set up automated cleanup.
+
+Example with SolidQueue. Configure recurring cleanup in your `config/recurring.yml`:
+
+```yaml
+solid_apm_cleanup_weekly:
+  class: SolidApm::CleanupJob  
+  cron: "0 3 * * *"   # Every day at 3 AM
+  args: ["1.week.ago"]
+```
+
+## How it works
+
+SolidAPM stores information in the form of transactions, representing incoming HTTP requests which
+listen to a variety of spans (events) from `ActiveSupport::Instrument`. Each span
+saves backtrace information to easily find the source of issues.
+
+### Request transaction
+
+It is based on [ActionDispatch](https://guides.rubyonrails.org/active_support_instrumentation.html#action-dispatch)
+events to start and end a transaction.
+
+A Rack middleware uses [`rack.after_reply`](https://github.blog/engineering/architecture-optimization/performance-at-github-deferring-stats-with-rack-after_reply/)
+to bulk insert transactions and spans after delivering the response, so tracking your application
+doesn't add delay to the client.
+
+### Spans saved
+
+* Request
+* Rendering
+* SQL requests and transactions 
+* Rails cache
+* Net/HTTP
+
 ## MCP Server
 
 SolidAPM offers an optional MCP server to allow an AI agent to interact with SolidAPM

data/app/jobs/solid_apm/cleanup_job.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module SolidApm
+  class CleanupJob < ApplicationJob
+    def perform(older_than = '1.month.ago')
+      result = CleanupService.new(older_than: older_than).call
+
+      Rails.logger.info "SolidApm::CleanupJob completed: deleted #{result[:deleted_count]} transactions older than #{result[:cutoff_time]} (#{result[:older_than]})"
+
+      result
+    end
+  end
+end

data/app/models/solid_apm/span_subscriber/base.rb

@@ -1,4 +1,5 @@
 # frozen_string_literal: true
+
 module SolidApm
   module SpanSubscriber
     class Base

data/lib/solid_apm/cleanup_service.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module SolidApm
+  class CleanupService
+    # Regex to match safe time expressions like "1.week.ago", "2.months.ago", etc.
+    DURATION_PATTERN = /\A(\d+)\.(second|minute|hour|day|week|month|year)s?\.ago\z/.freeze
+    def initialize(older_than: '1.month.ago')
+      @older_than = older_than
+    end
+
+    def call
+      cutoff_time = parse_time_expression(@older_than)
+      deleted_count = Transaction.where(timestamp: ...cutoff_time).destroy_all.size
+
+      {
+        cutoff_time: cutoff_time,
+        deleted_count: deleted_count,
+        older_than: @older_than
+      }
+    end
+
+    private
+
+    def parse_time_expression(expression)
+      match = expression.match(DURATION_PATTERN)
+      raise ArgumentError, 'Invalid time expression format' unless match
+
+      number = match[1].to_i
+      unit = match[2]
+
+      case unit
+      when 'second'
+        number.seconds.ago
+      when 'minute'
+        number.minutes.ago
+      when 'hour'
+        number.hours.ago
+      when 'day'
+        number.days.ago
+      when 'week'
+        number.weeks.ago
+      when 'month'
+        number.months.ago
+      when 'year'
+        number.years.ago
+      else
+        raise ArgumentError, "Unsupported time unit: #{unit}"
+      end
+    end
+  end
+end

data/lib/solid_apm/middleware.rb

@@ -23,7 +23,11 @@ module SolidApm
     def self.call
       transaction = SpanSubscriber::Base.transaction
       SpanSubscriber::Base.transaction = nil
-      if transaction.nil? || transaction.name.start_with?('SolidApm::') || transaction.name.start_with?('ActionDispatch::Request::PASS_NOT_FOUND')
+
+      if transaction.nil? ||
+          transaction_filtered?(transaction.name) ||
+          !Sampler.should_sample?
+
         SpanSubscriber::Base.spans = nil
         return
       end
@@ -41,8 +45,21 @@ module SolidApm
       SpanSubscriber::Base.spans = nil
     end
 
+    def self.transaction_filtered?(transaction_name)
+      SolidApm.transaction_filters.any? do |filter|
+        case filter
+        when String
+          transaction_name == filter
+        when Regexp
+          filter.match?(transaction_name)
+        else
+          false
+        end
+      end
+    end
+
     def self.with_silence_logger
-      if ActiveRecord::Base.logger
+      if SolidApm.silence_active_record_logger && ActiveRecord::Base.logger
         ActiveRecord::Base.logger.silence { yield }
       else
         yield

data/lib/solid_apm/sampler.rb

@@ -0,0 +1,12 @@
+module SolidApm
+  class Sampler
+    def self.should_sample?
+      return true if SolidApm.transaction_sampling <= 1
+
+      thread_counter = Thread.current[:solid_apm_counter] ||= 0
+      Thread.current[:solid_apm_counter] = (thread_counter + 1) % SolidApm.transaction_sampling
+
+      Thread.current[:solid_apm_counter] == 0
+    end
+  end
+end

data/lib/solid_apm/version.rb

@@ -1,3 +1,3 @@
 module SolidApm
-  VERSION = "0.9.0"
+  VERSION = "0.10.0"
 end

data/lib/solid_apm.rb

@@ -3,12 +3,23 @@ require 'groupdate'
 require 'active_median'
 require 'apexcharts'
 
-require "solid_apm/version"
-require "solid_apm/engine"
+require 'solid_apm/version'
+require 'solid_apm/engine'
+require 'solid_apm/sampler'
+require 'solid_apm/cleanup_service'
 
 module SolidApm
   mattr_accessor :connects_to
   mattr_accessor :mcp_server_config, default: {}
+  mattr_accessor :silence_active_record_logger, default: true
+  mattr_accessor :transaction_sampling, default: 1
+  mattr_accessor(
+    :transaction_filters, default: [
+      /^SolidApm::/,
+      /^ActionDispatch::Request::PASS_NOT_FOUND/,
+      'Rails::HealthController#show'
+    ]
+  )
 
   def self.set_context(context)
     SpanSubscriber::Base.context = context

data/lib/tasks/solid_apm_tasks.rake

@@ -1,4 +1,18 @@
-# desc "Explaining what the task does"
-# task :solid_apm do
-#   # Task goes here
-# end
+namespace :solid_apm do
+  desc 'Delete old transactions (default: older than 1 month). Usage: rake solid_apm:cleanup[1.week.ago]'
+  task :cleanup, [:older_than] => :environment do |_task, args|
+    older_than = args[:older_than] || '1.month.ago'
+
+    begin
+      result = SolidApm::CleanupService.new(older_than: older_than).call
+
+      puts "Deleting transactions older than #{result[:cutoff_time]}..."
+      puts "Deleted #{result[:deleted_count]} transactions"
+    rescue StandardError => e
+      puts "Error: #{e.message}"
+      puts "Please provide a valid time expression like '1.week.ago', '2.months.ago', etc."
+      puts 'Supported formats: [number].[unit].ago where unit is: second(s), minute(s), hour(s), day(s), week(s), month(s), year(s)'
+      exit 1
+    end
+  end
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: solid_apm
 version: !ruby/object:Gem::Version
-  version: 0.9.0
+  version: 0.10.0
 platform: ruby
 authors:
 - Jean-Francis Bastien
@@ -125,6 +125,7 @@ files:
 - app/controllers/solid_apm/transactions_controller.rb
 - app/helpers/solid_apm/application_helper.rb
 - app/jobs/solid_apm/application_job.rb
+- app/jobs/solid_apm/cleanup_job.rb
 - app/models/solid_apm/application_record.rb
 - app/models/solid_apm/span.rb
 - app/models/solid_apm/span_subscriber/action_dispatch.rb
@@ -145,10 +146,12 @@ files:
 - db/migrate/20240608015633_create_solid_apm_transactions.rb
 - db/migrate/20240608021940_create_solid_apm_spans.rb
 - lib/solid_apm.rb
+- lib/solid_apm/cleanup_service.rb
 - lib/solid_apm/engine.rb
 - lib/solid_apm/mcp/impactful_transactions_resource.rb
 - lib/solid_apm/mcp/spans_for_transaction_tool.rb
 - lib/solid_apm/middleware.rb
+- lib/solid_apm/sampler.rb
 - lib/solid_apm/version.rb
 - lib/tasks/solid_apm_tasks.rake
 homepage: https://github.com/Bhacaz/solid_apm
@@ -172,7 +175,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.6.7
+rubygems_version: 3.6.9
 specification_version: 4
 summary: SolidApm is a DB base engine for Application Performance Monitoring.
 test_files: []