pg_reports 0.6.1 → 0.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 77275298b8ef6a1dba986e9b47849d1685e2d09cacdd64e3b086b20ab403574c
-  data.tar.gz: 893da425321112adf5d4f9944fb72028898c77119ec95ad92d27c21681a80a0e
+  metadata.gz: 67cc51703472362dd188536abd8196660d5e4bb928d9f9ee53d7e2939290772e
+  data.tar.gz: 99fe7733e13344ac1e6b0a9a981728525005437a36e6c17846da455de5365a9b
 SHA512:
-  metadata.gz: c99a83908899a5896734b7025b4b593dad0c0d4045b9578e1912ccb332aa9f29dcb0c1e79fe69a403f4a248e99a540fc1b0627af44d7ddc1c1c889c738c1ffa7
-  data.tar.gz: 4ff3fe8ae5a907dee4a6eb9186adb1e9819d49e62c84c7447c49999dd2c4f09d01cd962711461437f18f1853ba1c3ea9b226af5a822a373034f61f93521ef1f5
+  metadata.gz: f408472b95f858f7770511b89885afd98b14074ee5fa3ed67c75ae36b29cb34a96adf1ac17ec0f6cf69bb9cbb51843def46483ff60ee121e2317d930da23deaf
+  data.tar.gz: fb4760d0e84fbe5a29b157cb37ee765454e7a26863a01b64aee1ba4262d83b28272e16664b7e797981f72594deb192e7f1a22a0c93ef6fb1399d584932446d91

data/CHANGELOG.md

@@ -7,6 +7,34 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.7.0] - 2026-04-26
+
+### Added
+
+- **Experimental Grafana / Prometheus support.** Selected reports can now be exposed at `<mount_point>/metrics` in Prometheus exposition format. Severity (`ok` / `warning` / `critical`) is derived automatically from the existing `REPORT_CONFIG` thresholds, including inverted ones (`cache_hit_ratio` etc.). Per-row data is emitted as `pg_reports_row` with each row column as a label, suitable for Grafana table panels via the "Labels to fields" transformation.
+  - New config: `grafana_favorites`, `grafana_metrics_token`, `grafana_cache_ttl`. Reports are cached via `Rails.cache` with a per-report TTL override to keep frequent scrapes from hammering the database.
+  - New endpoint: `MetricsController` with timing-safe bearer-token auth.
+  - New rake tasks: `pg_reports:grafana:dashboard` (writes a ready-to-import Grafana dashboard JSON) and `pg_reports:grafana:metrics` (prints the current metrics payload).
+  - New module `PgReports::Grafana::Exporter` and `PgReports::Grafana::DashboardBuilder`.
+  - Documentation: [docs/grafana.md](docs/grafana.md) (integration guide) and [docs/grafana-local-setup.md](docs/grafana-local-setup.md) (local Prometheus + Grafana setup without Docker).
+  - **Note:** the metric format may change in future minor versions until 1.0.
+
+## [0.6.2] - 2026-04-25
+
+### Added
+
+- **Native Rails QueryLogs source_location support** — `AnnotationParser` now recognizes the `source_location` tag emitted by `ActiveRecord::QueryLogs` and splits it into separate `:file` / `:line` fields for the dashboard's source column. Values are URL-decoded first, since Rails CGI-escapes tag values (so `%2F.../%3A19` becomes `/.../foo.rb:19`).
+
+### Fixed
+
+- **`counter_cache_issues` crashed/misreported on Rails 7.1+ Hash form.** `belongs_to :user, counter_cache: :col` is internally normalized to `{active: true, column: :col}` on Rails 7.1+, but the helper only handled `true` / Symbol / String — so the column came out as `Hash#inspect` (`{active: true, column: "usage_count"}`) and the suggested migration was malformed. `counter_cache_column_name` now handles all four forms (Boolean, Symbol, String, Hash with `:column` key, Hash without `:column`).
+- **`polymorphic_without_index` crashed with `NoMethodError: undefined method '&' for an instance of String`** when a table had an expression index (e.g. `CREATE INDEX ON x (LOWER(email))`). PostgreSQL returns `IndexDefinition#columns` as a String for expression indexes, not an Array. Both the polymorphic check and `coverage_label` now filter out non-array indexes.
+
+### Changed
+
+- **README simplified** — full reports listing moved to [docs/reports.md](docs/reports.md), long sections (EXPLAIN ANALYZE, SQL Query Monitor, Connection pool analytics, IDE integration, Telegram delivery, raw query execution, source tracking) collapsed into `<details>` blocks. From 582 lines to ~340.
+- **Query source tracking** documentation now leads with native `ActiveRecord::QueryLogs` (Rails 7.0+) including a `source_location` lambda example. Marginalia mentioned only as the option for Rails < 7.0.
+
 ## [0.6.1] - 2026-04-24
 
 ### Added

data/README.md

@@ -18,6 +18,7 @@ A comprehensive PostgreSQL monitoring and analysis library for Rails application
 - 🖥️ **System Overview** - Database sizes, PostgreSQL settings, installed extensions
 - 🌐 **Web Dashboard** - Beautiful dark-themed UI with sortable tables and expandable rows
 - 📨 **Telegram Integration** - Send reports directly to Telegram
+- 📈 **Grafana / Prometheus Exporter** - Expose selected reports at `/metrics` with severity derived from configured thresholds
 - 📥 **Export** - Download reports in TXT, CSV, or JSON format
 - 🔗 **IDE Integration** - Open source locations in VS Code, Cursor, RubyMine, or IntelliJ (with WSL support)
 - 📌 **Comparison Mode** - Save records to compare before/after optimization
@@ -131,25 +132,40 @@ end
 </details>
 
 <details>
-<summary><strong>Query source tracking (Marginalia / Rails query logs)</strong></summary>
+<summary><strong>Query source tracking (Rails query logs)</strong></summary>
 
-PgReports parses query annotations to show **where queries originated**.
+PgReports parses query annotations to show **where queries originated**. On Rails 7.0+ use the built-in `ActiveRecord::QueryLogs` (no extra gem needed). On older Rails, install [Marginalia](https://github.com/basecamp/marginalia) — PgReports auto-detects both formats.
 
-[Marginalia](https://github.com/basecamp/marginalia):
+Minimal setup — adds controller/action:
 
 ```ruby
-gem "marginalia"
+# config/application.rb
+config.active_record.query_log_tags_enabled = true
+config.active_record.query_log_tags = [:controller, :action]
 ```
 
-Rails 7+ query logs:
+To also surface **file path and line number** (so source links jump to the actual call site, not just the controller), add a custom `source_location` lambda that walks `caller_locations` and skips gem/framework frames:
 
 ```ruby
 # config/application.rb
 config.active_record.query_log_tags_enabled = true
-config.active_record.query_log_tags = [:controller, :action]
+config.active_record.query_log_tags = [
+  :controller,
+  :action,
+  :job,
+  {
+    source_location: -> {
+      ignore = %r{/(gems|active_record|active_support|active_model|railties|
+                    action_controller|action_view|action_pack|action_dispatch|
+                    rack|core_ext|relation|associations|scoping|connection_adapters)/}x
+      loc = caller_locations.find { |l| !l.path.match?(ignore) }
+      "#{loc.path}:#{loc.lineno}" if loc
+    }
+  }
+]
 ```
 
-Either form is auto-detected; controller/action and file:line appear in the **source** column on report rows.
+PgReports recognizes the `source_location` tag and splits it into file and line for the **source** column.
 
 </details>
 
@@ -284,7 +300,57 @@ The Export dropdown includes **Copy Prompt** (visible on actionable reports). It
 
 </details>
 
-## Telegram
+<details>
+<summary><strong>Grafana / Prometheus exporter</strong></summary>
+
+Expose selected reports at `<mount_point>/metrics` in Prometheus exposition format. The default mount is `/pg_reports`, so the endpoint is typically `/pg_reports/metrics` — but it follows whatever path you used in `mount PgReports::Engine, at: "..."`. Severity (`ok` / `warning` / `critical`) is derived automatically from the thresholds defined in [`Dashboard::ReportsRegistry::REPORT_CONFIG`](lib/pg_reports/dashboard/reports_registry.rb).
+
+```ruby
+PgReports.configure do |config|
+  config.grafana_favorites = [
+    :slow_queries,
+    :unused_indexes,
+    :bloated_tables,
+    :missing_validations,
+    :polymorphic_without_index
+  ]
+  config.grafana_metrics_token = ENV["PG_REPORTS_METRICS_TOKEN"]  # optional bearer token
+  config.grafana_cache_ttl     = 60                                # seconds
+end
+```
+
+Scrape with Prometheus:
+
+```yaml
+scrape_configs:
+  - job_name: pg_reports
+    metrics_path: /pg_reports/metrics    # adjust to your Engine mount point
+    scrape_interval: 60s
+    authorization: { credentials: "${PG_REPORTS_METRICS_TOKEN}" }
+    static_configs:
+      - targets: ["app.internal:3000"]
+```
+
+> [!WARNING]
+> Reports are cached via `Rails.cache` for `grafana_cache_ttl` so frequent scrapes don't hammer the database. Without it, Prometheus' default 15s scrape interval against heavy reports like `missing_validations` will DDoS your own DB. Always set a TTL ≥ scrape interval, and consider a longer per-report TTL for expensive reports.
+
+The exporter also emits a `pg_reports_row` series per report row (each column becomes a Prometheus label), so the auto-generated dashboard can show a **table panel** with the actual rows that need fixing — not just an aggregate count.
+
+Generate a matching Grafana dashboard from the same favorites:
+
+```bash
+bundle exec rake pg_reports:grafana:dashboard
+# writes pg_reports.json in pwd; then Dashboards → Import in Grafana
+```
+
+**[Full Grafana integration guide →](docs/grafana.md)** &nbsp;·&nbsp; **[Local Prometheus + Grafana without Docker →](docs/grafana-local-setup.md)**
+
+</details>
+
+<details>
+<summary><strong>Telegram delivery</strong></summary>
+
+Get a bot token from [@BotFather](https://t.me/BotFather) and your chat ID from [@userinfobot](https://t.me/userinfobot), then:
 
 ```ruby
 PgReports.configure do |config|
@@ -296,7 +362,9 @@ PgReports.slow_queries.send_to_telegram
 PgReports.health_report.send_to_telegram_as_file
 ```
 
-Get a bot token from [@BotFather](https://t.me/BotFather) and your chat ID from [@userinfobot](https://t.me/userinfobot).
+Reports under ~50 rows go as a message; larger ones are sent as a file attachment.
+
+</details>
 
 ## Development
 

data/app/controllers/pg_reports/metrics_controller.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+require "digest/sha2"
+
+module PgReports
+  class MetricsController < ActionController::Base
+    CONTENT_TYPE = "text/plain; version=0.0.4; charset=utf-8"
+
+    before_action :authenticate_metrics!, if: -> { PgReports.config.grafana_metrics_token.present? }
+
+    def show
+      render plain: PgReports::Grafana::Exporter.render, content_type: CONTENT_TYPE
+    end
+
+    private
+
+    def authenticate_metrics!
+      expected = PgReports.config.grafana_metrics_token.to_s
+      provided = request.headers["Authorization"].to_s.sub(/\Abearer\s+/i, "")
+
+      a = ::Digest::SHA256.digest(expected)
+      b = ::Digest::SHA256.digest(provided)
+
+      head :unauthorized unless ActiveSupport::SecurityUtils.secure_compare(a, b) && expected.present?
+    end
+  end
+end

data/config/routes.rb

@@ -3,6 +3,8 @@
 PgReports::Engine.routes.draw do
   root to: "dashboard#index"
 
+  get "metrics", to: "metrics#show", as: :metrics
+
   get "live_metrics", to: "dashboard#live_metrics", as: :live_metrics
 
   post "enable_pg_stat_statements", to: "dashboard#enable_pg_stat_statements", as: :enable_pg_stat_statements

data/lib/pg_reports/annotation_parser.rb

@@ -1,10 +1,12 @@
 # frozen_string_literal: true
 
+require "cgi"
+
 module PgReports
   # Parses SQL query comments to extract source location and metadata
   # Supports:
   # - Marginalia format: /*application:myapp,controller:users,action:index*/
-  # - Rails QueryLogs: /*action='index',controller='users'*/
+  # - Rails QueryLogs: /*action='index',controller='users',source_location='app/foo.rb:42'*/
   #
   module AnnotationParser
     class << self
@@ -32,6 +34,16 @@ module PgReports
           end
         end
 
+        # Rails QueryLogs custom tag — Rails URL-encodes tag values (CGI.escape) to keep
+        # SQL comments safe, so "/" → "%2F" and ":" → "%3A". Decode then split into :file/:line.
+        if result[:source_location] && !result[:file]
+          decoded = CGI.unescape(result[:source_location].to_s)
+          if (match = decoded.match(%r{^(.+):(\d+)$}))
+            result[:file] = match[1]
+            result[:line] = match[2]
+          end
+        end
+
         result
       end
 

data/lib/pg_reports/configuration.rb

@@ -42,6 +42,11 @@ module PgReports
     # Security settings
     attr_accessor :allow_raw_query_execution    # Allow execute_query and explain_analyze from dashboard
 
+    # Grafana / Prometheus exporter settings
+    attr_accessor :grafana_favorites            # Reports exposed at /metrics (Array of keys or Hash with per-report opts)
+    attr_accessor :grafana_metrics_token        # Bearer token required to access /metrics (nil = no auth)
+    attr_accessor :grafana_cache_ttl            # Default cache TTL for collected reports, seconds
+
     def initialize
       # Telegram
       @telegram_bot_token = ENV.fetch("PG_REPORTS_TELEGRAM_TOKEN", nil)
@@ -87,6 +92,11 @@ module PgReports
       @allow_raw_query_execution = ActiveModel::Type::Boolean.new.cast(
         ENV.fetch("PG_REPORTS_ALLOW_RAW_QUERY_EXECUTION", false)
       )
+
+      # Grafana / Prometheus exporter
+      @grafana_favorites = []
+      @grafana_metrics_token = ENV.fetch("PG_REPORTS_METRICS_TOKEN", nil)
+      @grafana_cache_ttl = 60
     end
 
     def connection

data/lib/pg_reports/grafana/dashboard_builder.rb

@@ -0,0 +1,277 @@
+# frozen_string_literal: true
+
+require "json"
+
+module PgReports
+  module Grafana
+    # Builds an importable Grafana dashboard JSON from configured favorites.
+    # Each report becomes a row with two panels:
+    #   - "rows" stat (total)
+    #   - "issues by severity" timeseries (ok / warning / critical)
+    # Severity colours are wired so that any warning lights yellow, any critical lights red.
+    class DashboardBuilder
+      DATASOURCE_INPUT = "DS_PROMETHEUS"
+
+      DEFAULT_TITLE = "PgReports — PostgreSQL Health"
+      DEFAULT_UID = "pg-reports"
+
+      SEVERITY_COLORS = {
+        "ok" => "green",
+        "warning" => "yellow",
+        "critical" => "red"
+      }.freeze
+
+      GRID_WIDTH = 24
+      ROW_HEIGHT = 1
+      TIMESERIES_HEIGHT = 8
+      TABLE_HEIGHT = 10
+      REPORT_BLOCK_HEIGHT = TIMESERIES_HEIGHT + TABLE_HEIGHT
+
+      def self.build(**opts)
+        new(**opts).build
+      end
+
+      def initialize(favorites: PgReports.config.grafana_favorites,
+        title: DEFAULT_TITLE,
+        uid: DEFAULT_UID,
+        refresh: "1m",
+        time_from: "now-6h")
+        @favorites = normalize(favorites)
+        @title = title
+        @uid = uid
+        @refresh = refresh
+        @time_from = time_from
+        @panel_id = 0
+      end
+
+      def build
+        if @favorites.empty?
+          raise ArgumentError,
+            "No favorites configured. Set PgReports.config.grafana_favorites or pass favorites:."
+        end
+
+        {
+          "__inputs" => [datasource_input],
+          "__requires" => [grafana_require, prometheus_require],
+          "annotations" => {"list" => []},
+          "editable" => true,
+          "graphTooltip" => 1,
+          "panels" => build_panels,
+          "refresh" => @refresh,
+          "schemaVersion" => 38,
+          "tags" => ["pg_reports", "postgresql"],
+          "templating" => {"list" => []},
+          "time" => {"from" => @time_from, "to" => "now"},
+          "timezone" => "browser",
+          "title" => @title,
+          "uid" => @uid,
+          "version" => 1,
+          "weekStart" => ""
+        }
+      end
+
+      def to_json(*)
+        JSON.pretty_generate(build)
+      end
+
+      private
+
+      def normalize(favorites)
+        case favorites
+        when Hash then favorites.keys.map(&:to_sym)
+        when Array then favorites.map(&:to_sym)
+        else []
+        end
+      end
+
+      def build_panels
+        panels = []
+        y = 0
+
+        grouped_favorites.each do |category, keys|
+          panels << row_panel(category_label(category), y)
+          y += ROW_HEIGHT
+
+          keys.each do |key|
+            info = report_info(category, key)
+            panels << timeseries_panel(key, info, y)
+            panels << table_panel(key, info, y + TIMESERIES_HEIGHT)
+            y += REPORT_BLOCK_HEIGHT
+          end
+        end
+
+        panels
+      end
+
+      def grouped_favorites
+        groups = {}
+        @favorites.each do |key|
+          category = category_for(key)
+          next unless category # silently skip unknown keys; exporter logs them
+          groups[category] ||= []
+          groups[category] << key
+        end
+        groups
+      end
+
+      def category_for(key)
+        Dashboard::ReportsRegistry::REPORTS.each do |category, info|
+          return category if info[:reports].key?(key)
+        end
+        nil
+      end
+
+      def category_label(category)
+        Dashboard::ReportsRegistry::REPORTS.dig(category, :name) || category.to_s.humanize
+      end
+
+      def report_info(category, key)
+        Dashboard::ReportsRegistry::REPORTS.dig(category, :reports, key) || {name: key.to_s.humanize, description: ""}
+      end
+
+      def row_panel(title, y)
+        {
+          "id" => next_id,
+          "type" => "row",
+          "title" => title,
+          "collapsed" => false,
+          "gridPos" => {"h" => ROW_HEIGHT, "w" => GRID_WIDTH, "x" => 0, "y" => y},
+          "panels" => []
+        }
+      end
+
+      def timeseries_panel(key, info, y)
+        {
+          "id" => next_id,
+          "type" => "timeseries",
+          "title" => "#{info[:name]} — issues by severity",
+          "description" => info[:description].to_s,
+          "datasource" => datasource_ref,
+          "gridPos" => {"h" => TIMESERIES_HEIGHT, "w" => GRID_WIDTH, "x" => 0, "y" => y},
+          "targets" => severity_targets(key),
+          "options" => {
+            "legend" => {"displayMode" => "table", "placement" => "right", "calcs" => ["lastNotNull"]},
+            "tooltip" => {"mode" => "multi", "sort" => "desc"}
+          },
+          "fieldConfig" => {
+            "defaults" => {
+              "custom" => {
+                "drawStyle" => "bars",
+                "stacking" => {"mode" => "normal", "group" => "A"},
+                "fillOpacity" => 60,
+                "lineWidth" => 1
+              },
+              "color" => {"mode" => "fixed"},
+              "mappings" => []
+            },
+            "overrides" => severity_color_overrides
+          }
+        }
+      end
+
+      def table_panel(key, info, y)
+        {
+          "id" => next_id,
+          "type" => "table",
+          "title" => "#{info[:name]} — current rows",
+          "description" => "#{info[:description]}\n\nLatest snapshot of report rows. Each row's columns are unpacked from Prometheus labels via the Labels-to-fields transformation.".strip,
+          "datasource" => datasource_ref,
+          "gridPos" => {"h" => TABLE_HEIGHT, "w" => GRID_WIDTH, "x" => 0, "y" => y},
+          "targets" => [
+            {
+              "refId" => "A",
+              "expr" => %(pg_reports_row{report="#{key}"}),
+              "datasource" => datasource_ref,
+              "format" => "table",
+              "instant" => true,
+              "legendFormat" => "__auto"
+            }
+          ],
+          "transformations" => [
+            {
+              "id" => "labelsToFields",
+              "options" => {"mode" => "columns"}
+            },
+            {
+              "id" => "organize",
+              "options" => {
+                "excludeByName" => {
+                  "Time" => true,
+                  "Value" => true,
+                  "__name__" => true,
+                  "instance" => true,
+                  "job" => true,
+                  "report" => true,
+                  "row" => true
+                },
+                "indexByName" => {},
+                "renameByName" => {}
+              }
+            }
+          ],
+          "options" => {
+            "showHeader" => true,
+            "cellHeight" => "sm",
+            "footer" => {"show" => false}
+          },
+          "fieldConfig" => {
+            "defaults" => {
+              "custom" => {"align" => "auto", "displayMode" => "auto"},
+              "mappings" => []
+            },
+            "overrides" => []
+          }
+        }
+      end
+
+      def severity_targets(key)
+        SEVERITY_COLORS.keys.each_with_index.map do |severity, i|
+          {
+            "refId" => ("A".ord + i).chr,
+            "expr" => %(pg_reports_issues{report="#{key}",severity="#{severity}"}),
+            "datasource" => datasource_ref,
+            "legendFormat" => severity
+          }
+        end
+      end
+
+      def severity_color_overrides
+        SEVERITY_COLORS.map do |severity, color|
+          {
+            "matcher" => {"id" => "byName", "options" => severity},
+            "properties" => [
+              {"id" => "color", "value" => {"mode" => "fixed", "fixedColor" => color}}
+            ]
+          }
+        end
+      end
+
+      def datasource_input
+        {
+          "name" => DATASOURCE_INPUT,
+          "label" => "Prometheus",
+          "description" => "Datasource that scrapes /pg_reports/metrics",
+          "type" => "datasource",
+          "pluginId" => "prometheus",
+          "pluginName" => "Prometheus"
+        }
+      end
+
+      def datasource_ref
+        {"type" => "prometheus", "uid" => "${#{DATASOURCE_INPUT}}"}
+      end
+
+      def grafana_require
+        {"type" => "grafana", "id" => "grafana", "name" => "Grafana", "version" => "9.0.0"}
+      end
+
+      def prometheus_require
+        {"type" => "datasource", "id" => "prometheus", "name" => "Prometheus", "version" => "1.0.0"}
+      end
+
+      def next_id
+        @panel_id += 1
+      end
+    end
+  end
+end

data/lib/pg_reports/grafana/exporter.rb

@@ -0,0 +1,240 @@
+# frozen_string_literal: true
+
+module PgReports
+  module Grafana
+    # Renders selected reports in Prometheus exposition format.
+    # Severity is derived from REPORT_CONFIG thresholds in Dashboard::ReportsRegistry.
+    class Exporter
+      SEVERITY_ORDER = {"ok" => 0, "warning" => 1, "critical" => 2}.freeze
+      MAX_LABEL_VALUE_LENGTH = 200
+      RESERVED_LABEL_NAMES = %w[report severity row error].freeze
+
+      MODULES = {
+        queries: -> { Modules::Queries },
+        indexes: -> { Modules::Indexes },
+        tables: -> { Modules::Tables },
+        connections: -> { Modules::Connections },
+        system: -> { Modules::System },
+        schema_analysis: -> { Modules::SchemaAnalysis }
+      }.freeze
+
+      def self.render
+        new.render
+      end
+
+      def initialize(favorites: PgReports.config.grafana_favorites,
+        cache_ttl: PgReports.config.grafana_cache_ttl,
+        clock: Time)
+        @favorites = normalize(favorites)
+        @cache_ttl = cache_ttl
+        @clock = clock
+      end
+
+      def render
+        results = @favorites.map { |key, opts| collect(key, opts) }
+
+        lines = []
+        emit(lines, "pg_reports_issues", "Number of rows by severity for the report") do |emit|
+          results.each do |r|
+            next unless r[:ok]
+            r[:severities].each { |sev, count| emit.call({report: r[:key], severity: sev}, count) }
+          end
+        end
+
+        emit(lines, "pg_reports_rows", "Total rows returned by the report") do |emit|
+          results.each { |r| emit.call({report: r[:key]}, r[:rows]) if r[:ok] }
+        end
+
+        emit(lines, "pg_reports_run_seconds", "Time spent collecting the report") do |emit|
+          results.each { |r| emit.call({report: r[:key]}, r[:duration].round(4)) if r[:ok] }
+        end
+
+        emit(lines, "pg_reports_last_run_timestamp", "Unix timestamp of last collection") do |emit|
+          results.each { |r| emit.call({report: r[:key]}, r[:timestamp]) if r[:ok] }
+        end
+
+        emit(lines, "pg_reports_up", "Whether collection succeeded (1) or failed (0)") do |emit|
+          results.each do |r|
+            labels = {report: r[:key]}
+            labels[:error] = r[:error] unless r[:ok]
+            emit.call(labels, r[:ok] ? 1 : 0)
+          end
+        end
+
+        emit(lines, "pg_reports_row", "One series per row of the report (drives Grafana table panels). Each row column becomes a label.") do |emit|
+          results.each do |r|
+            next unless r[:ok] && r[:rows_data]
+            r[:rows_data].each_with_index do |row_labels, idx|
+              emit.call(row_labels.merge(report: r[:key], row: idx), 1)
+            end
+          end
+        end
+
+        (lines << "").join("\n")
+      end
+
+      private
+
+      def normalize(favorites)
+        case favorites
+        when Hash
+          favorites.each_with_object({}) { |(k, v), h| h[k.to_sym] = (v || {}).symbolize_keys }
+        when Array
+          favorites.each_with_object({}) { |k, h| h[k.to_sym] = {} }
+        else
+          {}
+        end
+      end
+
+      def collect(key, opts)
+        cached(key, opts) { run(key, opts) }
+      rescue => e
+        {key: key, ok: false, error: e.class.name, message: e.message}
+      end
+
+      def cached(key, opts)
+        ttl = opts[:ttl] || @cache_ttl
+        if ttl && defined?(Rails) && Rails.respond_to?(:cache) && Rails.cache
+          Rails.cache.fetch("pg_reports/grafana/#{key}", expires_in: ttl) { yield }
+        else
+          yield
+        end
+      end
+
+      def run(key, opts)
+        mod = module_for(key) or raise ArgumentError, "Unknown report: #{key}"
+
+        started = @clock.now
+        report = mod.public_send(key, **report_args(opts))
+        finished = @clock.now
+
+        {
+          key: key,
+          ok: true,
+          rows: report.size,
+          severities: severity_counts(key, report),
+          rows_data: opts.fetch(:expose_rows, true) ? row_label_sets(report) : nil,
+          duration: finished - started,
+          timestamp: finished.to_i
+        }
+      end
+
+      def row_label_sets(report)
+        report.map { |row| row_to_labels(row) }
+      end
+
+      def row_to_labels(row)
+        labels = {}
+        row.each do |column, value|
+          next if value.nil?
+
+          name = sanitize_label_name(column.to_s)
+          next if name.empty? || RESERVED_LABEL_NAMES.include?(name)
+
+          formatted = format_label_value(value)
+          next if formatted.length > MAX_LABEL_VALUE_LENGTH
+
+          labels[name] = formatted
+        end
+        labels
+      end
+
+      def sanitize_label_name(name)
+        cleaned = name.gsub(/[^a-zA-Z0-9_]/, "_")
+        cleaned = "_#{cleaned}" if cleaned.match?(/\A[0-9]/)
+        cleaned
+      end
+
+      def format_label_value(value)
+        case value
+        when Float then format("%g", value)
+        when Time, DateTime then value.iso8601
+        else value.to_s
+        end
+      end
+
+      def module_for(key)
+        Dashboard::ReportsRegistry::REPORTS.each do |category, info|
+          next unless info[:reports].key?(key.to_sym)
+          factory = MODULES[category] or return nil
+          return factory.call
+        end
+        nil
+      end
+
+      def report_args(opts)
+        # Only forward kwargs that report methods accept; keep the surface tiny.
+        opts.slice(:limit).compact
+      end
+
+      def severity_counts(key, report)
+        thresholds = Dashboard::ReportsRegistry.thresholds(key)
+        counts = Hash.new(0)
+
+        if thresholds.empty?
+          counts["ok"] = report.size
+          return counts
+        end
+
+        report.each { |row| counts[row_severity(row, thresholds)] += 1 }
+        counts
+      end
+
+      def row_severity(row, thresholds)
+        worst = "ok"
+        thresholds.each do |field, t|
+          value = row[field.to_s] || row[field]
+          next if value.nil?
+
+          worst = max_severity(worst, severity_for(value.to_f, t))
+        end
+        worst
+      end
+
+      def severity_for(value, thresholds)
+        critical = thresholds[:critical]
+        warning = thresholds[:warning]
+
+        if thresholds[:inverted]
+          return "critical" if critical && value <= critical
+          return "warning" if warning && value <= warning
+        else
+          return "critical" if critical && value >= critical
+          return "warning" if warning && value >= warning
+        end
+        "ok"
+      end
+
+      def max_severity(a, b)
+        (SEVERITY_ORDER[a] >= SEVERITY_ORDER[b]) ? a : b
+      end
+
+      def emit(lines, metric, help)
+        buffer = []
+        emitter = ->(labels, value) {
+          buffer << "#{metric}#{format_labels(labels)} #{value}"
+        }
+        yield emitter
+        return if buffer.empty?
+
+        lines << "# HELP #{metric} #{help}"
+        lines << "# TYPE #{metric} gauge"
+        lines.concat(buffer)
+      end
+
+      def format_labels(labels)
+        return "" if labels.nil? || labels.empty?
+
+        pairs = labels.map { |k, v| %(#{k}="#{escape_label(v)}") }
+        "{#{pairs.join(",")}}"
+      end
+
+      def escape_label(value)
+        value.to_s
+          .gsub("\\", "\\\\\\\\")
+          .gsub('"', '\\"')
+          .gsub("\n", '\\n')
+      end
+    end
+  end
+end

data/lib/pg_reports/module_generator.rb

@@ -3,42 +3,43 @@
 module PgReports
   # Generates module methods dynamically from YAML report definitions
   class ModuleGenerator
-    def self.generate!
-      ReportLoader.load_all.each do |module_name, reports|
-        module_class = get_module(module_name)
-        next unless module_class
-
-        reports.each do |report_name, definition|
-          define_report_method(module_class, report_name, definition)
+    class << self
+      def generate!
+        ReportLoader.load_all.each do |module_name, reports|
+          module_class = get_module(module_name)
+          next unless module_class
+
+          reports.each do |report_name, definition|
+            define_report_method(module_class, report_name, definition)
+          end
         end
       end
-    end
 
-    private
+      private
 
-    def self.get_module(module_name)
-      const_name = module_name.to_s.split("_").map(&:capitalize).join
-      PgReports::Modules.const_get(const_name)
-    rescue NameError
-      # Module doesn't exist, skip it
-      # We don't auto-create modules to avoid conflicts
-      nil
-    end
+      def get_module(module_name)
+        const_name = module_name.to_s.split("_").map(&:capitalize).join
+        PgReports::Modules.const_get(const_name)
+      rescue NameError
+        # Module doesn't exist, skip it
+        # We don't auto-create modules to avoid conflicts
+        nil
+      end
 
-    def self.define_report_method(module_class, report_name, definition)
-      params_config = definition.config["parameters"] || {}
+      def define_report_method(module_class, report_name, definition)
+        params_config = definition.config["parameters"] || {}
 
-      # Extract default parameter values
-      defaults = params_config.transform_values { |v| v["default"] }
+        # Extract default parameter values
+        defaults = params_config.transform_values { |v| v["default"] }
 
-      # Define the method on the module
-      # We capture the definition in a local variable to avoid closure issues
-      captured_definition = definition
-      captured_defaults = defaults
+        # Capture definition + defaults so the singleton method closes over them
+        captured_definition = definition
+        captured_defaults = defaults
 
-      module_class.define_singleton_method(report_name) do |**params|
-        merged_params = captured_defaults.merge(params)
-        captured_definition.generate_report(**merged_params)
+        module_class.define_singleton_method(report_name) do |**params|
+          merged_params = captured_defaults.merge(params)
+          captured_definition.generate_report(**merged_params)
+        end
       end
     end
   end

data/lib/pg_reports/modules/schema_analysis.rb

@@ -112,7 +112,7 @@ module PgReports
           counter_belongs_to(model).each do |assoc|
             counter_col = counter_cache_column_name(model, assoc)
             parent = parent_class_for(assoc)
-            next unless parent && parent.table_exists?
+            next unless parent&.table_exists?
 
             unless parent.column_names.include?(counter_col)
               results << {

data/lib/pg_reports/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module PgReports
-  VERSION = "0.6.1"
+  VERSION = "0.7.0"
 end

data/lib/pg_reports.rb

@@ -33,6 +33,10 @@ require_relative "pg_reports/modules/schema_analysis"
 # Dashboard
 require_relative "pg_reports/dashboard/reports_registry"
 
+# Grafana / Prometheus exporter
+require_relative "pg_reports/grafana/exporter"
+require_relative "pg_reports/grafana/dashboard_builder"
+
 # Rails Engine
 require_relative "pg_reports/engine" if defined?(Rails::Engine)
 

data/lib/tasks/pg_reports.rake

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+require "json"
+
+namespace :pg_reports do
+  namespace :grafana do
+    desc "Write importable Grafana dashboard JSON for the configured grafana_favorites. " \
+         "Defaults to pg_reports.json in pwd. Override with OUTPUT=, FAVORITES=, TITLE=, UID=, REFRESH=, TIME_FROM=."
+    task dashboard: :environment do
+      favorites = if ENV["FAVORITES"]
+        ENV["FAVORITES"].split(",").map { |k| k.strip.to_sym }
+      else
+        PgReports.config.grafana_favorites
+      end
+
+      builder = PgReports::Grafana::DashboardBuilder.new(
+        favorites: favorites,
+        title: ENV.fetch("TITLE", PgReports::Grafana::DashboardBuilder::DEFAULT_TITLE),
+        uid: ENV.fetch("UID", PgReports::Grafana::DashboardBuilder::DEFAULT_UID),
+        refresh: ENV.fetch("REFRESH", "1m"),
+        time_from: ENV.fetch("TIME_FROM", "now-6h")
+      )
+
+      output_path = ENV.fetch("OUTPUT", "pg_reports.json")
+      File.write(output_path, JSON.pretty_generate(builder.build))
+      warn "Wrote #{output_path}"
+    end
+
+    desc "Write the current /metrics payload to a file. Defaults to pg_reports.metrics in pwd. Override with OUTPUT=."
+    task metrics: :environment do
+      output_path = ENV.fetch("OUTPUT", "pg_reports.metrics")
+      File.write(output_path, PgReports::Grafana::Exporter.render)
+      warn "Wrote #{output_path}"
+    end
+  end
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: pg_reports
 version: !ruby/object:Gem::Version
-  version: 0.6.1
+  version: 0.7.0
 platform: ruby
 authors:
 - Eldar Avatov
@@ -148,6 +148,7 @@ files:
 - LICENSE.txt
 - README.md
 - app/controllers/pg_reports/dashboard_controller.rb
+- app/controllers/pg_reports/metrics_controller.rb
 - app/views/layouts/pg_reports/application.html.erb
 - app/views/pg_reports/dashboard/_fake_source_data.html.erb
 - app/views/pg_reports/dashboard/_show_modals.html.erb
@@ -214,6 +215,8 @@ files:
 - lib/pg_reports/executor.rb
 - lib/pg_reports/explain_analyzer.rb
 - lib/pg_reports/filter.rb
+- lib/pg_reports/grafana/dashboard_builder.rb
+- lib/pg_reports/grafana/exporter.rb
 - lib/pg_reports/module_generator.rb
 - lib/pg_reports/modules/connections.rb
 - lib/pg_reports/modules/indexes.rb
@@ -278,6 +281,7 @@ files:
 - lib/pg_reports/sql_loader.rb
 - lib/pg_reports/telegram_sender.rb
 - lib/pg_reports/version.rb
+- lib/tasks/pg_reports.rake
 homepage: https://github.com/deadalice/pg_reports
 licenses:
 - MIT
@@ -285,6 +289,16 @@ metadata:
   homepage_uri: https://github.com/deadalice/pg_reports
   source_code_uri: https://github.com/deadalice/pg_reports
   changelog_uri: https://github.com/deadalice/pg_reports/blob/main/CHANGELOG.md
+post_install_message: |
+  Thanks for installing pg_reports v0.7.0!
+
+  New in 0.7.0 — experimental Grafana / Prometheus support
+  ────────────────────────────────────────────────────────
+  Expose selected reports at <mount_point>/metrics in Prometheus exposition
+  format and import a ready-to-use Grafana dashboard:
+
+  Setup guide:
+    https://github.com/deadalice/pg_reports/blob/main/docs/grafana.md
 rdoc_options: []
 require_paths:
 - lib