lantern-rails 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: b544123b390d3e7fee816bd3f27fdd485334fb5688f45754a52551294d39ef98
+  data.tar.gz: 74b280feb07f0d4bdac527c56d206c47b0fd009d293348c7924df76d46c900f8
+SHA512:
+  metadata.gz: a14c62f42e4b69f19ae193061a17d981f005e110c691f1f6b13200020cbb7bb1e50182d2c471814244a06b68d69bef54bab6f51230e5291226f3c3653f8bf788
+  data.tar.gz: d0f5344237d2684d8a8891a2ce9941669a26d455a3a05fdf01b6102c9c26322410f505db446c76b8043400e39b0b86491af165e5341d0a0b9366066ec92ffb48

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Eric Mumbower
+
+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.

data/README.md

@@ -0,0 +1,83 @@
+# lantern-rails
+
+Postgres health monitoring for Rails apps. Collects database metrics and sends them to [Lantern](https://uselantern.dev) — a hosted dashboard that scores your database health and surfaces actionable recommendations.
+
+## Installation
+
+Add to your Gemfile:
+
+```ruby
+gem "lantern-rails"
+```
+
+Then run:
+
+```
+bundle install
+```
+
+## Setup
+
+Generate an API key at [uselantern.dev](https://uselantern.dev), then create an initializer:
+
+```ruby
+# config/initializers/lantern.rb
+Lantern::Rails.configure do |config|
+  config.api_key = ENV["LANTERN_API_KEY"]
+end
+```
+
+That's it. The collector starts automatically when your Rails app boots in production.
+
+## Configuration
+
+```ruby
+Lantern::Rails.configure do |config|
+  config.api_key                  = ENV["LANTERN_API_KEY"]
+  config.host                     = "https://uselantern.dev"  # default
+  config.interval                 = 300                       # seconds, default 5 min
+  config.collect_in_environments  = %w[production staging]   # default
+end
+```
+
+## Deploy tracking
+
+To correlate deploys with health score changes, call this from your deploy pipeline or a Rails initializer that runs after deploy:
+
+```ruby
+Lantern::Rails.report_deploy
+```
+
+Or pass explicit values:
+
+```ruby
+Lantern::Rails.report_deploy(
+  git_sha:    ENV["GIT_SHA"],
+  git_author: ENV["GIT_AUTHOR"],
+  deployer:   "github-actions"
+)
+```
+
+## What gets collected
+
+Every collection interval, the gem queries your Postgres instance for:
+
+- Buffer and index cache hit ratios
+- Unused index count and total size
+- Table bloat ratio
+- Long-running queries (> 30 seconds)
+- Dead tuple counts and vacuum status
+- Active connections vs. max_connections
+- pg_stat_bgwriter stats_reset timestamp (to detect false positives)
+
+No query text, no table data, no PII. Only aggregate pg_stat_* metrics.
+
+## Requirements
+
+- Ruby >= 3.1
+- Rails >= 7.0
+- PostgreSQL (any version with pg_stat_statements)
+
+## License
+
+MIT

data/lib/lantern/rails/collector.rb

@@ -0,0 +1,192 @@
+module Lantern
+  module Rails
+    class Collector
+      def collect
+        connection = ActiveRecord::Base.connection
+
+        cache    = collect_cache_metrics(connection)
+        indexes  = collect_index_metrics(connection)
+        bloat    = collect_bloat_metrics(connection)
+        queries  = collect_query_metrics(connection)
+        vacuum   = collect_vacuum_metrics(connection)
+        conns    = collect_connection_metrics(connection)
+        git      = GitMetadata.collect
+
+        {
+          collected_at: Time.current.iso8601,
+
+          shared_buffer_hit_ratio: cache[:shared_buffer_hit_ratio],
+          index_hit_ratio:         cache[:index_hit_ratio],
+
+          unused_index_count:      indexes[:unused_index_count],
+          unused_index_size_bytes: indexes[:unused_index_size_bytes],
+          stats_reset_at:          indexes[:stats_reset_at],
+
+          estimated_bloat_bytes:   bloat[:estimated_bloat_bytes],
+          bloat_ratio:             bloat[:bloat_ratio],
+
+          long_running_query_count:  queries[:long_running_query_count],
+          longest_query_duration_ms: queries[:longest_query_duration_ms],
+
+          total_dead_tuples:         vacuum[:total_dead_tuples],
+          total_live_tuples:         vacuum[:total_live_tuples],
+          tables_needing_vacuum:     vacuum[:tables_needing_vacuum],
+          tables_never_vacuumed:     vacuum[:tables_never_vacuumed],
+          oldest_vacuum_age_seconds: vacuum[:oldest_vacuum_age_seconds],
+
+          active_connections:     conns[:active_connections],
+          max_connections:        conns[:max_connections],
+          connection_utilization: conns[:connection_utilization],
+
+          git_sha:     git[:sha],
+          git_message: git[:message]
+        }
+      rescue => e
+        ::Rails.logger.error("[Lantern] Collection failed: #{e.message}")
+        nil
+      end
+
+      private
+
+      def collect_cache_metrics(conn)
+        row = conn.select_one(<<~SQL)
+          SELECT
+            round(
+              sum(heap_blks_hit)::numeric /
+              nullif(sum(heap_blks_hit) + sum(heap_blks_read), 0) * 100,
+              4
+            ) AS shared_buffer_hit_ratio,
+            round(
+              sum(idx_blks_hit)::numeric /
+              nullif(sum(idx_blks_hit) + sum(idx_blks_read), 0) * 100,
+              4
+            ) AS index_hit_ratio
+          FROM pg_statio_user_tables
+        SQL
+
+        {
+          shared_buffer_hit_ratio: row["shared_buffer_hit_ratio"]&.to_f,
+          index_hit_ratio:         row["index_hit_ratio"]&.to_f
+        }
+      end
+
+      def collect_index_metrics(conn)
+        row = conn.select_one(<<~SQL)
+          SELECT
+            count(*)                                               AS unused_index_count,
+            coalesce(sum(pg_relation_size(indexrelid)), 0)::bigint AS unused_index_size_bytes,
+            (SELECT stats_reset FROM pg_stat_bgwriter)             AS stats_reset_at
+          FROM pg_stat_user_indexes
+          JOIN pg_index USING (indexrelid)
+          WHERE idx_scan = 0
+            AND NOT indisprimary
+            AND NOT indisunique
+        SQL
+
+        {
+          unused_index_count:      row["unused_index_count"].to_i,
+          unused_index_size_bytes: row["unused_index_size_bytes"].to_i,
+          stats_reset_at:          row["stats_reset_at"]
+        }
+      end
+
+      def collect_bloat_metrics(conn)
+        row = conn.select_one(<<~SQL)
+          SELECT
+            coalesce(
+              sum(
+                CASE
+                  WHEN n_dead_tup > 0 AND (n_live_tup + n_dead_tup) > 0
+                  THEN (n_dead_tup::numeric / (n_live_tup + n_dead_tup) * pg_total_relation_size(relid))
+                  ELSE 0
+                END
+              )::bigint,
+              0
+            ) AS estimated_bloat_bytes,
+            coalesce(
+              round(
+                sum(n_dead_tup)::numeric /
+                nullif(sum(n_live_tup + n_dead_tup), 0) * 100,
+                2
+              ),
+              0
+            ) AS bloat_ratio
+          FROM pg_stat_user_tables
+        SQL
+
+        {
+          estimated_bloat_bytes: row["estimated_bloat_bytes"].to_i,
+          bloat_ratio:           row["bloat_ratio"].to_f
+        }
+      end
+
+      def collect_query_metrics(conn)
+        row = conn.select_one(<<~SQL)
+          SELECT
+            count(*)                                                                          AS long_running_query_count,
+            coalesce(
+              max(extract(epoch from now() - query_start) * 1000)::bigint,
+              0
+            )                                                                                 AS longest_query_duration_ms
+          FROM pg_stat_activity
+          WHERE state = 'active'
+            AND query_start < now() - interval '30 seconds'
+            AND query NOT ILIKE '%pg_stat_activity%'
+        SQL
+
+        {
+          long_running_query_count:  row["long_running_query_count"].to_i,
+          longest_query_duration_ms: row["longest_query_duration_ms"].to_i
+        }
+      end
+
+      def collect_vacuum_metrics(conn)
+        row = conn.select_one(<<~SQL)
+          SELECT
+            coalesce(sum(n_dead_tup), 0)::bigint                                       AS total_dead_tuples,
+            coalesce(sum(n_live_tup), 0)::bigint                                       AS total_live_tuples,
+            count(*) FILTER (
+              WHERE n_dead_tup > n_live_tup * 0.1 AND n_live_tup > 0
+            )                                                                           AS tables_needing_vacuum,
+            count(*) FILTER (
+              WHERE last_vacuum IS NULL AND last_autovacuum IS NULL AND n_live_tup > 0
+            )                                                                           AS tables_never_vacuumed,
+            coalesce(
+              max(extract(epoch from now() - greatest(last_vacuum, last_autovacuum)))::int,
+              0
+            )                                                                           AS oldest_vacuum_age_seconds
+          FROM pg_stat_user_tables
+        SQL
+
+        {
+          total_dead_tuples:         row["total_dead_tuples"].to_i,
+          total_live_tuples:         row["total_live_tuples"].to_i,
+          tables_needing_vacuum:     row["tables_needing_vacuum"].to_i,
+          tables_never_vacuumed:     row["tables_never_vacuumed"].to_i,
+          oldest_vacuum_age_seconds: row["oldest_vacuum_age_seconds"].to_i
+        }
+      end
+
+      def collect_connection_metrics(conn)
+        row = conn.select_one(<<~SQL)
+          SELECT
+            count(*) FILTER (WHERE state IS NOT NULL)            AS active_connections,
+            current_setting('max_connections')::int              AS max_connections,
+            round(
+              count(*) FILTER (WHERE state IS NOT NULL)::numeric /
+              current_setting('max_connections')::numeric * 100,
+              2
+            )                                                    AS connection_utilization
+          FROM pg_stat_activity
+          WHERE datname = current_database()
+        SQL
+
+        {
+          active_connections:     row["active_connections"].to_i,
+          max_connections:        row["max_connections"].to_i,
+          connection_utilization: row["connection_utilization"].to_f
+        }
+      end
+    end
+  end
+end

data/lib/lantern/rails/configuration.rb

@@ -0,0 +1,25 @@
+module Lantern
+  module Rails
+    class Configuration
+      attr_accessor :api_key, :host, :interval, :environment, :enabled, :collect_in_environments
+
+      def initialize
+        @host                     = "https://uselantern.dev"
+        @interval                 = 300  # 5 minutes
+        @environment              = detect_environment
+        @enabled                  = true
+        @collect_in_environments  = %w[production staging]
+      end
+
+      def valid?
+        api_key.present?
+      end
+
+      private
+
+      def detect_environment
+        defined?(::Rails) ? ::Rails.env.to_s : "production"
+      end
+    end
+  end
+end

data/lib/lantern/rails/git_metadata.rb

@@ -0,0 +1,21 @@
+module Lantern
+  module Rails
+    module GitMetadata
+      def self.collect
+        sha     = run("git rev-parse --short HEAD")
+        message = run("git log -1 --pretty=%s")
+        author  = run("git log -1 --pretty=%ae")
+        { sha: sha, message: message, author: author }
+      rescue => e
+        ::Rails.logger.debug("[Lantern] Git metadata unavailable: #{e.message}")
+        { sha: nil, message: nil, author: nil }
+      end
+
+      def self.run(cmd)
+        result = `#{cmd} 2>/dev/null`.strip
+        result.empty? ? nil : result
+      end
+      private_class_method :run
+    end
+  end
+end

data/lib/lantern/rails/railtie.rb

@@ -0,0 +1,18 @@
+module Lantern
+  module Rails
+    class Railtie < ::Rails::Railtie
+      config.after_initialize do
+        config = Lantern::Rails.configuration
+        next unless config.valid?
+        next unless config.enabled
+        next unless config.collect_in_environments.include?(::Rails.env.to_s)
+
+        runner = Lantern::Rails::Runner.new(config)
+
+        at_exit { runner.stop }
+
+        runner.start
+      end
+    end
+  end
+end

data/lib/lantern/rails/reporter.rb

@@ -0,0 +1,48 @@
+require "net/http"
+require "json"
+require "uri"
+
+module Lantern
+  module Rails
+    class Reporter
+      def initialize(config)
+        @config = config
+      end
+
+      def report_snapshot(payload)
+        post("/api/v1/snapshots", payload)
+      end
+
+      def report_deploy(payload)
+        post("/api/v1/deploy_events", payload)
+      end
+
+      private
+
+      def post(path, payload)
+        uri  = URI("#{@config.host}#{path}")
+        http = Net::HTTP.new(uri.host, uri.port)
+        http.use_ssl     = uri.scheme == "https"
+        http.open_timeout = 5
+        http.read_timeout = 10
+
+        request = Net::HTTP::Post.new(uri)
+        request["Authorization"] = "Bearer #{@config.api_key}"
+        request["Content-Type"]  = "application/json"
+        request["Accept"]        = "application/json"
+        request.body = payload.to_json
+
+        response = http.request(request)
+
+        unless response.is_a?(Net::HTTPSuccess)
+          ::Rails.logger.warn("[Lantern] API returned #{response.code}: #{response.body}")
+        end
+
+        response
+      rescue => e
+        ::Rails.logger.error("[Lantern] Failed to report to #{path}: #{e.message}")
+        nil
+      end
+    end
+  end
+end

data/lib/lantern/rails/runner.rb

@@ -0,0 +1,44 @@
+module Lantern
+  module Rails
+    class Runner
+      def initialize(config)
+        @config   = config
+        @thread   = nil
+        @stopping = false
+      end
+
+      def start
+        return unless @config.valid? && @config.enabled
+
+        @thread = Thread.new do
+          ::Rails.logger.info("[Lantern] Collector started (interval: #{@config.interval}s)")
+          loop do
+            break if @stopping
+            collect_and_report
+            sleep @config.interval
+            break if @stopping
+          end
+        end
+
+        @thread.abort_on_exception = false
+        @thread.name = "lantern-collector"
+      end
+
+      def stop
+        @stopping = true
+        @thread&.join(5)
+      end
+
+      private
+
+      def collect_and_report
+        payload = Collector.new.collect
+        return unless payload
+
+        Reporter.new(@config).report_snapshot(payload)
+      rescue => e
+        ::Rails.logger.error("[Lantern] Runner error: #{e.message}")
+      end
+    end
+  end
+end

data/lib/lantern/rails/version.rb

@@ -0,0 +1,5 @@
+module Lantern
+  module Rails
+    VERSION = "0.1.0"
+  end
+end

data/lib/lantern-rails.rb

@@ -0,0 +1,43 @@
+require "lantern/rails/version"
+require "lantern/rails/configuration"
+require "lantern/rails/git_metadata"
+require "lantern/rails/collector"
+require "lantern/rails/reporter"
+require "lantern/rails/runner"
+require "lantern/rails/railtie" if defined?(::Rails)
+
+module Lantern
+  module Rails
+    class << self
+      def configuration
+        @configuration ||= Configuration.new
+      end
+
+      def configure
+        yield configuration
+      end
+
+      # Manually report a deploy event. Call this from your CI/CD pipeline
+      # or a deploy hook in your Rails app.
+      #
+      # Example (in a Rake task or initializer after deploy):
+      #   Lantern::Rails.report_deploy
+      def report_deploy(git_sha: nil, git_message: nil, git_author: nil, deployer: nil)
+        return unless configuration.valid?
+
+        git = GitMetadata.collect
+
+        payload = {
+          git_sha:     git_sha     || git[:sha],
+          git_message: git_message || git[:message],
+          git_author:  git_author  || git[:author],
+          deployer:    deployer,
+          environment: configuration.environment,
+          deployed_at: Time.current.iso8601
+        }
+
+        Reporter.new(configuration).report_deploy(payload)
+      end
+    end
+  end
+end

metadata

@@ -0,0 +1,61 @@
+--- !ruby/object:Gem::Specification
+name: lantern-rails
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Eric Mumbower
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- lib/lantern-rails.rb
+- lib/lantern/rails/collector.rb
+- lib/lantern/rails/configuration.rb
+- lib/lantern/rails/git_metadata.rb
+- lib/lantern/rails/railtie.rb
+- lib/lantern/rails/reporter.rb
+- lib/lantern/rails/runner.rb
+- lib/lantern/rails/version.rb
+homepage: https://uselantern.dev
+licenses:
+- MIT
+metadata: {}
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.1'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.9
+specification_version: 4
+summary: Postgres monitoring collector for Rails apps — sends health metrics to Lantern.
+test_files: []