pg-locks-monitor 0.0.1 → 0.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 38fe7be18449c8a637a4f6a756228055f217f4e2fa1c47eb84609009c31793cf
-  data.tar.gz: 19e9b7bcacde528b1b0c34d4c2c28f2f482e6573742fe10536af51cbeb68db75
+  metadata.gz: dcbbfc8c0f63bbfd2f2c06abfb5db0e98ed2f5d6da39dc227089501f9734ec86
+  data.tar.gz: 370e8706b301323367dd9685be5ac5e5e8fcb7c47a73c06e6a337cf590db331c
 SHA512:
-  metadata.gz: 9b947dcacbdaccc1d2ce67244c7c054882b9120a996ea3a8c7b3b99ae9e516065920201fa42d5c0f536fcef3296c86a6a4066c3319d464a3d726f19ca2e6e481
-  data.tar.gz: ad98c65cf24043c9381579442731e74d26784df9886a6633913fc9c9fb1ba20e76470a53b12b11b24b588fa3d8014364194eca34f0b7c96caaa8e632e1edd66f
+  metadata.gz: e4ce44f0a435f65a9cbb3e69b185bcfe6939a7e4e44cb5ac687abeab7e2a7b83eb794b2407fae7fae34db152e5fd4b0332e65c01e895e851e5c2dc1a791d8a30
+  data.tar.gz: 585cd6b764cc4a42582b8f0eca28ec4569f8e5cb9b7175df15745aef4af1a0e5634803c4dfe06af4737e759ad8cc4d2ea9d992ef39f6fa21e0b1ee4e8bd57186

data/README.md

@@ -1,3 +1,200 @@
 # PG Locks Monitor [![Gem Version](https://badge.fury.io/rb/pg-locks-monitor.svg)](https://badge.fury.io/rb/pg-locks-monitor) [![GH Actions](https://github.com/pawurb/pg-locks-monitor/actions/workflows/ci.yml/badge.svg)](https://github.com/pawurb/pg-locks-monitor/actions)
 
-WIP
+This gem allows to observe database locks generated by a Rails application. By default, locks data is not persisted anywhere in the PostgreSQL logs, so the only way to monitor it is via analyzing the transient state of the `pg_locks` metadata table. `pg-locks-monitor` is a simple tool that makes this process quick to implement and adjust to each app's individual requirements.
+
+## Usage
+
+`PgLocksMonitor` class provides a `snapshot!` method, which notifies selected channels about database locks that match configured criteria.
+
+Start by adding the gem to your Gemfile:
+
+```ruby
+gem "pg-locks-monitor"
+```
+
+Then run `bundle install` and `rake pg_locks_monitor:init`. It creates a default configuration file with the following settings:
+
+`config/initializers/pg_locks_monitor.rb`
+```ruby
+PgLocksMonitor.configure do |config|
+  config.locks_limit = 5
+
+  config.monitor_locks = true
+  config.locks_min_duration_ms = 200
+
+  config.monitor_blocking = true
+  config.blocking_min_duration_ms = 100
+
+  config.notify_logs = true
+
+  config.notify_slack = false
+  config.slack_webhook_url = ""
+  config.slack_channel = ""
+
+  config.notifier_class = PgLocksMonitor::DefaultNotifier
+end
+```
+
+- `locks_limit` - specify the max number of locks to report in a single notification
+- `notify_locks` - observe database locks even if they don't conflict with a different SQL query
+- `locks_min_duration_ms` - notify about locks that execeed this duration threshold in milliseconds
+- `notify_blocking` - observe database locks which cause other SQL query to wait from them to release
+- `blocking_min_duration_ms` - notify about blocking locks that execeed this duration threshold in milliseconds
+- `notify_logs` - send notifications about detected locks using `Rails.logger.info` method
+- `notify_slack` - send notifications about detected locks to the configured Slack channel
+- `slack_webhook_url` - webhook necessary for Slack notification to work
+- `slack_channel` - the name of the target Slack channel
+- `notifier_class` - customizable notifier class
+
+
+## Testing the notification channels
+
+Before configuring a recurring invocation of the `snapshot!` method, it's recommended to first manually trigger the notification to test the configured channels.
+
+You can generate an _"artificial"_ blocking lock and observe it by running the following code in the Rails console:
+
+```ruby
+user = User.last
+
+Thread.new do
+  User.transaction do
+    user.update(email: "email-#{SecureRandom.hex(2)}@example.com")
+    sleep 5
+    raise ActiveRecord::Rollback
+  end
+end
+
+Thread.new do
+  User.transaction do
+    user.update(email: "email-#{SecureRandom.hex(2)}@example.com")
+    sleep 5
+    raise ActiveRecord::Rollback
+  end
+end
+
+sleep 0.5
+PgLocksMonitor.snapshot!
+```
+
+Please remember to adjust the update operation to match your app's schema.
+
+As a result of running the above snippet, you should receive a notification about the acquired blocking database lock.
+
+### Sample notification
+
+Received notifications contain data helpful in debugging the cause of long lasting-locks.
+
+And here's a sample blocking lock notification: 
+
+```ruby
+[
+  {
+    # PID of the process which was blocking another query
+    "blocking_pid": 29,
+    # SQL query blocking other SQL query
+    "blocking_statement": "UPDATE \"users\" SET \"updated_at\" = $1 WHERE \"users\".\"id\" = $2 from/sidekiq_job:UserUpdater/",
+    # the duration of blocking SQL query
+    "blocking_duration": "PT0.972116S",
+    # app that triggered the blocking SQL query
+    "blocking_sql_app": "bin/sidekiq",
+
+    # PID of the process which was blocked by another query
+    "blocked_pid": 30,
+    # SQL query blocked by other SQL query
+    "blocked_statement": "UPDATE \"users\" SET \"last_active_at\" = $1 WHERE \"users\".\"id\" = $2 from/controller_with_namespace:UsersController,action:update/",
+    # the duration of the blocked SQL query
+    "blocked_duration": "PT0.483309S",
+    # app that triggered the blocked SQL query
+    "blocked_sql_app": "bin/puma"
+  }
+]
+```
+
+This sample blocking notification shows than a query originating from the `UserUpdater` Sidekiq job is blocking an update operation on the same user for the `UsersController#update` action. Remember to configure the [marginalia gem](https://github.com/basecamp/marginalia) to enable these helpful query source annotations.
+
+Here's a sample lock notification:
+
+```ruby
+[
+  {
+    # PID of the process which acquired the lock
+    "pid": 50,
+    # name of affected table/index
+    "relname": "users",
+    # ID of the source transaction
+    "transactionid": null,
+    # bool indicating if the lock is already granted
+    "granted": true,
+    # type of the acquired lock
+    "mode": "RowExclusiveLock",
+    # SQL query which acquired the lock
+    "query_snippet": "UPDATE \"users\" SET \"updated_at\" = $1 WHERE \"users\".\"id\" = $2 from/sidekiq_job:UserUpdater/",
+    # age of the lock
+    "age": "PT0.94945S",
+    # app that acquired the lock
+    "application": "bin/sidekiq"
+  },
+```
+
+You can read [this blogpost](https://pawelurbanek.com/rails-postgresql-locks) for more detailed info on locks in the Rails apps.
+
+## Background job config
+
+This gem is intended to be used via a recurring background job, but it is agnostic to the background job provider. Here's a sample Sidekiq implementation:
+
+`app/jobs/pg_locks_monitor_job.rb`
+```ruby
+require 'pg-locks-monitor'
+
+class PgLocksMonitoringJob
+  include Sidekiq::Worker
+  sidekiq_options retry: false
+
+  def perform
+    PgLocksMonitor.snapshot!
+  ensure
+    if ENV["PG_LOCKS_MONITOR_ENABLED"]
+      PgLocksMonitoringJob.perform_in(1.minute)
+    end
+  end
+end
+```
+
+Remember to schedule this job when your app starts:
+`config/pg_locks_monitor.rb`
+
+```ruby
+#... 
+
+if ENV["PG_LOCKS_MONITOR_ENABLED"]
+  PgLocksMonitoringJob.perform
+end
+```
+
+A background job that schedules itself is not the cleanest pattern. So alternatively you can use [sidekiq-cron](https://github.com/sidekiq-cron/sidekiq-cron), [whenever](https://github.com/javan/whenever) or [clockwork](https://github.com/adamwiggins/clockwork) gems to trigger the `PgLocksMonitor.snapshot!` invocation periodically.
+
+A recommended frequency of invocation depends on your app's traffic. From my experience, even 1 minute apart snapshots can provide a lot of valuable data, but it all depends on how often the locks are occurring in your Rails application.
+
+## Custom notifier class
+
+`PgLocksMonitor::DefaultNotifier` supports sending lock notifications with `Rails.logger` or to a Slack channel. If you want to use different notification channels you can define your custom notifier like that:
+
+`config/initializers/pg_locks_monitor.rb`
+```ruby
+class PgLocksEmailNotifier
+  def self.call(locks_data)
+    LocksMailer.with(locks_data: locks_data).notification.deliver_now
+  end
+end
+
+PgLocksMonitor.configure do |config|
+  # ...
+
+  config.notifier_class = PgLocksEmailNotifier
+end
+
+```
+
+## Contributions
+
+This gem is in a very early stage of development so feedback and PRs are welcome.

data/lib/pg-locks-monitor.rb

@@ -4,4 +4,37 @@ require "uri"
 require "pg"
 
 module PgLocksMonitor
+  def self.snapshot!
+    locks = RailsPgExtras.locks(
+      in_format: :hash, args: {
+        limit: configuration.locks_limit,
+      },
+    ).select do |lock|
+      (ActiveSupport::Duration.parse(lock.fetch("age")).to_f * 1000) > configuration.locks_min_duration_ms
+    end
+
+    if locks.present? && configuration.monitor_locks
+      configuration.notifier_class.call(locks)
+    end
+
+    blocking = RailsPgExtras.blocking(in_format: :hash).select do |block|
+      (ActiveSupport::Duration.parse(block.fetch("blocking_duration")).to_f * 1000) > configuration.blocking_min_duration_ms
+    end
+
+    if blocking.present? && configuration.monitor_blocking
+      configuration.notifier_class.call(blocking)
+    end
+  end
+
+  def self.configuration
+    @configuration ||= Configuration.new(Configuration::DEFAULT)
+  end
+
+  def self.configure
+    yield(configuration)
+  end
 end
+
+require "pg_locks_monitor/default_notifier"
+require "pg_locks_monitor/configuration"
+require "pg_locks_monitor/railtie" if defined?(Rails)

data/lib/pg_locks_monitor/configuration.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module PgLocksMonitor
+  class Configuration
+    DEFAULT = {
+      locks_limit: 5,
+      monitor_locks: true,
+      monitor_blocking: true,
+      locks_min_duration_ms: 200,
+      blocking_min_duration_ms: 100,
+      notify_logs: true,
+      notify_slack: false,
+      slack_webhook_url: nil,
+      slack_channel: nil,
+      notifier_class: PgLocksMonitor::DefaultNotifier,
+    }
+
+    attr_accessor *DEFAULT.keys
+
+    def initialize(attrs)
+      DEFAULT.keys.each do |key|
+        value = attrs.fetch(key) { DEFAULT.fetch(key) }
+        public_send("#{key}=", value)
+      end
+    end
+
+    DEFAULT_CONFIG_FILE = <<-CONFIG
+# Configuration for pg-locks-monitor
+
+PgLocksMonitor.configure do |config|
+  config.locks_limit = #{DEFAULT[:locks_limit]}
+
+  config.monitor_locks = #{DEFAULT[:monitor_locks]}
+  config.monitor_blocking = #{DEFAULT[:monitor_blocking]}
+
+  config.locks_min_duration_ms = #{DEFAULT[:locks_min_duration_ms]}
+  config.blocking_min_duration_ms = #{DEFAULT[:blocking_min_duration_ms]}
+
+  config.notify_logs = #{DEFAULT[:notify_logs]}
+
+  config.notify_slack = #{DEFAULT[:notify_slack]}
+  config.slack_webhook_url = "#{DEFAULT[:slack_webhook_url]}"
+  config.slack_channel = "#{DEFAULT[:slack_channel]}"
+
+  config.notifier_class = #{DEFAULT[:notifier_class]}
+end
+CONFIG
+  end
+end

data/lib/pg_locks_monitor/default_notifier.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+require "slack-notifier"
+
+module PgLocksMonitor
+  class DefaultNotifier
+    def self.call(locks_data)
+      config = PgLocksMonitor.configuration
+
+      if config.notify_logs && defined?(Rails)
+        Rails.logger.info locks_data.to_s
+      end
+
+      if config.notify_slack
+        slack_webhook_url = config.slack_webhook_url
+        if slack_webhook_url.nil? || slack_webhook_url.strip.length == 0
+          raise "Missing pg-locks-monitor slack_webhook_url config"
+        end
+
+        slack_channel = config.slack_channel
+        if slack_channel.nil? || slack_channel.strip.length == 0
+          raise "Missing pg-locks-monitor slack_channel config"
+        end
+
+        Slack::Notifier.new(
+          slack_webhook_url,
+          channel: slack_channel,
+        ).ping JSON.pretty_generate(locks_data)
+      end
+    end
+  end
+end

data/lib/pg_locks_monitor/railtie.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+class PgLocksMonitor::Railtie < Rails::Railtie
+  rake_tasks do
+    load "pg_locks_monitor/tasks/all.rake"
+  end
+end

data/lib/pg_locks_monitor/tasks/all.rake

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+require "pg-locks-monitor"
+require "fileutils"
+
+namespace :pg_locks_monitor do
+  desc "Initialize a config file"
+  task :init do
+    file_path = "config/initializers/pg_locks_monitor.rb"
+    if File.exist?(file_path)
+      puts "#{file_path} config file has already been initialized!"
+    else
+      File.write(file_path, PgLocksMonitor::Configuration::DEFAULT_CONFIG_FILE)
+      puts "Config file created at #{file_path}"
+    end
+  end
+
+  desc "Check for currently active locks"
+  task :snapshot do
+    PgLocksMonitor.snapshot!
+  end
+end

data/lib/pg_locks_monitor/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module PgLocksMonitor
-  VERSION = "0.0.1"
+  VERSION = "0.1.0"
 end

data/pg-locks-monitor.gemspec

@@ -8,7 +8,7 @@ Gem::Specification.new do |s|
   s.version = PgLocksMonitor::VERSION
   s.authors = ["pawurb"]
   s.email = ["contact@pawelurbanek.com"]
-  s.summary = %q{ Observe PostgreSQL database locks obtained by your Ruby application. }
+  s.summary = %q{ Observe PostgreSQL database locks obtained by a Rails application. }
   s.description = %q{ This gem allows to monitor and notify about PostgreSQL database locks which meet certain criteria. You can report locks which are held for a certain amount of time, or locks which are held by a certain query. }
   s.homepage = "http://github.com/pawurb/pg-locks-monitor"
   s.files = `git ls-files`.split("\n")
@@ -16,6 +16,7 @@ Gem::Specification.new do |s|
   s.require_paths = ["lib"]
   s.license = "MIT"
   s.add_dependency "ruby-pg-extras"
+  s.add_dependency "slack-notifier"
   s.add_development_dependency "rake"
   s.add_development_dependency "rspec"
   s.add_development_dependency "rufo"

data/spec/configuration_spec.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+require "spec_helper"
+
+describe "PgLocksMonitor::Configuration" do
+  it "has a default configuration" do
+    config = PgLocksMonitor.configuration
+    expect(config.monitor_locks).to eq true
+    expect(config.monitor_blocking).to eq true
+    expect(config.locks_min_duration_ms).to eq 200
+    expect(config.blocking_min_duration_ms).to eq 100
+    expect(config.notifier_class).to eq PgLocksMonitor::DefaultNotifier
+  end
+
+  it "can be configured" do
+    PgLocksMonitor.configure do |config|
+      config.monitor_locks = false
+    end
+
+    expect(PgLocksMonitor.configuration.monitor_locks).to eq false
+  end
+end

data/spec/default_notifier_spec.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+require "spec_helper"
+
+describe PgLocksMonitor::DefaultNotifier do
+  before do
+    # Mock Rails and its logger
+    Rails = nil
+    logger_double = double("Logger")
+    allow(logger_double).to receive(:info)
+    allow(Rails).to receive(:logger).and_return(logger_double)
+  end
+
+  it "requires correct config if Slack notifications enabled" do
+    expect {
+      PgLocksMonitor::DefaultNotifier.call({})
+    }.not_to raise_error
+    PgLocksMonitor.configure do |config|
+      config.notify_slack = true
+    end
+
+    expect {
+      PgLocksMonitor::DefaultNotifier.call({})
+    }.to raise_error(RuntimeError)
+  end
+
+  it "sends the Slack notification if enabled" do
+    PgLocksMonitor.configure do |config|
+      config.notify_slack = true
+      config.slack_webhook_url = "https://hooks.slack.com/services/123456789/123456789/123456789"
+      config.slack_channel = "pg-locks-monitor"
+    end
+
+    expect_any_instance_of(Slack::Notifier).to receive(:ping)
+    PgLocksMonitor::DefaultNotifier.call({ locks: "data" })
+  end
+end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: pg-locks-monitor
 version: !ruby/object:Gem::Version
-  version: 0.0.1
+  version: 0.1.0
 platform: ruby
 authors:
 - pawurb
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2024-08-20 00:00:00.000000000 Z
+date: 2024-08-27 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: ruby-pg-extras
@@ -24,6 +24,20 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
+- !ruby/object:Gem::Dependency
+  name: slack-notifier
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: rake
   requirement: !ruby/object:Gem::Requirement
@@ -83,8 +97,14 @@ files:
 - Rakefile
 - docker-compose.yml.sample
 - lib/pg-locks-monitor.rb
+- lib/pg_locks_monitor/configuration.rb
+- lib/pg_locks_monitor/default_notifier.rb
+- lib/pg_locks_monitor/railtie.rb
+- lib/pg_locks_monitor/tasks/all.rake
 - lib/pg_locks_monitor/version.rb
 - pg-locks-monitor.gemspec
+- spec/configuration_spec.rb
+- spec/default_notifier_spec.rb
 - spec/smoke_spec.rb
 - spec/spec_helper.rb
 homepage: http://github.com/pawurb/pg-locks-monitor
@@ -110,7 +130,9 @@ requirements: []
 rubygems_version: 3.5.4
 signing_key:
 specification_version: 4
-summary: Observe PostgreSQL database locks obtained by your Ruby application.
+summary: Observe PostgreSQL database locks obtained by a Rails application.
 test_files:
+- spec/configuration_spec.rb
+- spec/default_notifier_spec.rb
 - spec/smoke_spec.rb
 - spec/spec_helper.rb