request_metrics 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: c84c65399cbb0e8e971274bfff55901eb2c6dbd9be6f57ec8d58513aef27ef82
+  data.tar.gz: bb78391705582bf316869b46d6c218782147aaef1b86ef7ecfa0d2c078dc4590
+SHA512:
+  metadata.gz: daeae6fe180094f619ee6d847bcab51760d5cd194ed6f077ea6bfe4f339aafe97853fc49ada48784a22012feb5d646cd1892a1f0b23a2286f90616c1a498d0dd
+  data.tar.gz: 8ee55f06673430f59fdf3c6dba3bf20eb621d5af75b2ce41cd5dd9f9feb7a26e95e50e1261a3d675b2ed3645d1c2a445374501da07619a420ae922760e92a1b2

data/CHANGELOG.md

@@ -0,0 +1,5 @@
+## [Unreleased]
+
+## [0.1.0] - 2026-05-25
+
+- Initial release

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Elia Schito
+
+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,241 @@
+# RequestMetrics
+
+Per-request metric tracking and structured log summaries for Rails controllers.
+
+Subclass `RequestMetrics::Base`, declare counters with `metric_accessor`, implement `#log` to record each event, and Rails will append a summary to every `process_action` log line — zero boilerplate.
+
+```
+Completed 200 OK in 142ms (Views: 0.5ms | GQL: 87.3ms, 44 cost | Loop API: 31.1ms)
+```
+
+## Installation
+
+Add to your Gemfile:
+
+```ruby
+gem "request_metrics"
+```
+
+No initializer needed. A Railtie installs all registered subclasses into `ActionController::Base` automatically.
+
+## Usage
+
+### 1. Subclass `RequestMetrics::Base`
+
+```ruby
+class MyServiceMetrics < RequestMetrics::Base
+  metric_accessor :my_service_runtime  # declares counter + thread-safe accessors
+
+  # Called on each tracked event — add to the counter and log the line
+  def log(ms:, url:, status:)
+    add_my_service_runtime(ms)
+    name = color("  MyService (#{ms.round(1)}ms)", YELLOW, bold: true)
+    debug "#{name}  #{url} (status: #{status})"
+  end
+
+  # Optional — return a string to append to the controller summary log line
+  def self.summary_log(payload)
+    ms = payload[:my_service_runtime] || 0
+    "MyService: #{ms.round(1)}ms" if ms > 0
+  end
+end
+```
+
+### 2. Call `.log` from your HTTP client or wherever the event occurs
+
+```ruby
+ms = ActiveSupport::Benchmark.realtime(:float_millisecond) { response = do_request }
+MyServiceMetrics.log(ms:, url:, status: response.code)
+```
+
+### 3. Filter noise from source location output
+
+`verbose_query_logs` (default `true`) appends a `↳ app/...` caller hint below each log line. Add silencers to suppress framework internals:
+
+```ruby
+class MyServiceMetrics < RequestMetrics::Base
+  backtrace_cleaner.add_silencer { |line| line.include?("app/clients/") }
+  backtrace_cleaner.add_silencer { |line| line.include?("app/models/concerns/") }
+  # ...
+end
+```
+
+---
+
+## Real-world examples
+
+These are the two metrics classes from a Rails + Shopify app.
+
+### Loop API (HTTP client tracking)
+
+Tracks every outbound call to the [Loop Subscriptions](https://loopsubscriptions.com/) API, including cached responses.
+
+```ruby
+class LoopControllerMetrics < RequestMetrics::Base
+  backtrace_cleaner.add_silencer { |line| line.include?(__FILE__) }
+  backtrace_cleaner.add_silencer { |line| line.include?("app/clients/") }
+  backtrace_cleaner.add_silencer { |line| line.include?("app/models/concerns/") }
+  backtrace_cleaner.add_silencer { |line| line.include?("config/initializers/") }
+
+  metric_accessor :loop_runtime
+
+  def log(method:, url:, ms:, status:, data: nil, cached: false)
+    add_loop_runtime(ms)
+
+    http_color =
+      case status.to_i
+      when 200..299 then GREEN
+      when 300..399 then CYAN
+      when 400..499 then YELLOW
+      when 500..599 then RED
+      else               MAGENTA
+      end
+
+    name    = color("  #{cached ? "CACHE " : ""}Loop API (#{ms.round(1)}ms)", YELLOW, bold: true)
+    request = color("#{method} #{url}", http_color, bold: true)
+
+    debug "#{name}  #{request} #{data&.to_json} (status: #{status})"
+  end
+
+  def self.summary_log(payload)
+    ms = payload[:loop_runtime] || 0
+    "Loop API: #{ms.round(1)}ms" if ms > 0
+  end
+end
+```
+
+Called from the HTTP client:
+
+```ruby
+ms = ActiveSupport::Benchmark.realtime(:float_millisecond) { perform.call }
+LoopControllerMetrics.log(method: request.method, url: uri.to_s, ms:, status: response.code, data:)
+```
+
+Cached hits are logged with zero ms and `CACHE` prefix:
+
+```ruby
+LoopControllerMetrics.log(method: method.upcase, url:, ms: 0, status: 200, cached: true)
+```
+
+### Shopify GraphQL (API client patching)
+
+Tracks every Shopify Admin API GraphQL call, including query cost. Patches the official `shopify_api` gem's client via `prepend`.
+
+```ruby
+class ShopifyGraphqlMetrics < RequestMetrics::Base
+  backtrace_cleaner.add_silencer { |line| line.include?(__FILE__) }
+  backtrace_cleaner.add_silencer { |line| line.include?("app/models/shop.rb") }
+  backtrace_cleaner.add_silencer { |line| line.include?("app/models/concerns/") }
+  backtrace_cleaner.add_silencer { |line| line.include?("config/initializers/") }
+
+  metric_accessor :graphql_runtime
+  metric_accessor :graphql_cost
+
+  def self.install!
+    super
+    require "shopify_api/clients/graphql/admin"
+    ShopifyAPI::Clients::Graphql::Client.prepend(ShopifyAPIClientLoggingPatch)
+  end
+
+  module ShopifyAPIClientLoggingPatch
+    def query(query:, variables: nil, headers: nil, tries: 1, response_as_struct: ShopifyAPI::Context.response_as_struct, debug: false)
+      response = nil
+      ms = ActiveSupport::Benchmark.realtime(:float_millisecond) { response = super }
+      cost = response.body.dig("extensions", "cost")
+      ShopifyGraphqlMetrics.log(query:, ms:, cost:, variables:)
+      response
+    end
+  end
+
+  def log(query:, ms:, cost:, variables:, cached: false)
+    add_graphql_runtime(ms)
+    add_graphql_cost(cost.dig("requestedQueryCost")) if cost
+
+    graphql_color =
+      case query
+      when /\A\s*mutation/i    then GREEN
+      when /\A\s*query/i       then BLUE
+      when /\A\s*subscription/i then CYAN
+      else                          MAGENTA
+      end
+
+    name          = color("  #{cached ? "CACHE " : ""}GraphQL (#{ms.round(1)}ms)", YELLOW, bold: true)
+    colored_query = color(query.gsub(/\s+/, " ").strip, graphql_color, bold: true)
+    binds         = variables.present? ? "  #{variables.inspect}" : ""
+    cost_info     = "\n  ↳ cost: #{cost}" if cost
+
+    debug "#{name}  #{colored_query}#{binds}#{cost_info}"
+  end
+
+  def self.summary_log(payload)
+    runtime = payload[:graphql_runtime]
+    cost    = payload[:graphql_cost]
+
+    if runtime && runtime > 0
+      cost_info = cost && cost > 0 ? ", #{cost.round} cost" : ""
+      "GQL: #{runtime.round(1)}ms#{cost_info}"
+    end
+  end
+end
+```
+
+Result in logs:
+
+```
+  GraphQL (87.3ms)  query GetSubscription { ... }  { id: "gid://shopify/..." }
+  ↳ cost: {"requestedQueryCost"=>44, ...}
+  ↳ app/models/concerns/loop/subscription/persistence.rb:23:in `find'
+
+Completed 200 OK in 142ms (Views: 0.5ms | GQL: 87.3ms, 44 cost | Loop API: 31.1ms)
+```
+
+---
+
+## API reference
+
+### `metric_accessor(name)`
+
+Declares a per-request counter stored in a thread-local. Generates:
+
+| Method | Description |
+|---|---|
+| `MyMetrics.my_metric` | Read current value (default: `0`) |
+| `MyMetrics.my_metric = n` | Set value |
+| `MyMetrics.add_my_metric(delta)` | Increment |
+| `MyMetrics.reset_my_metric` | Return current value and reset to `0` |
+
+Thread-local keys are namespaced by subclass name, so two subclasses can both declare `metric_accessor :runtime` without collision.
+
+### `#log(**kwargs)` (instance, delegated to class)
+
+Called per event. Must be implemented by subclasses. Raise `NotImplementedError` if not.
+
+### `.summary_log(payload)` (class)
+
+Called once per request after `process_action`. Return a `String` to append to the log summary, or `nil` to skip. Default implementation returns `nil`.
+
+### `.install!` (class)
+
+Called automatically by the Railtie. Can be overridden to do additional setup (e.g., patching a third-party client) — call `super` to preserve the `ActionController` hook.
+
+### `backtrace_cleaner`
+
+Each subclass gets its own `ActiveSupport::BacktraceCleaner` instance (empty by default). Add silencers to filter which stack frame appears in the `↳` hint.
+
+### `verbose_query_logs`
+
+Boolean (default: `true`). Set to `false` to suppress the `↳ source` hint entirely.
+
+---
+
+## Development
+
+```bash
+bin/setup    # install dependencies
+rake test    # run tests
+bin/console  # interactive prompt
+```
+
+## License
+
+MIT.

data/Rakefile

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "minitest/test_task"
+
+Minitest::TestTask.create
+
+task default: :test

data/lib/request_metrics/base.rb

@@ -0,0 +1,89 @@
+# frozen_string_literal: true
+
+require "active_support/log_subscriber"
+require "active_support/backtrace_cleaner"
+require "active_support/core_ext/class/attribute"
+require "active_support/concern"
+
+module RequestMetrics
+  class Base < ActiveSupport::LogSubscriber
+    class_attribute :backtrace_cleaner, default: ActiveSupport::BacktraceCleaner.new
+    class_attribute :verbose_query_logs, default: true
+    class_attribute :metrics, default: []
+
+    def self.metric_accessor(name)
+      metrics << name
+
+      subclass = self
+      key = :"#{subclass.object_id}/#{name}"
+
+      define_singleton_method(name) { Thread.current[key] ||= 0 }
+      define_singleton_method("#{name}=") { |value| Thread.current[key] = value }
+      define_singleton_method("reset_#{name}") { send(name).tap { send("#{name}=", 0) } }
+      define_singleton_method("add_#{name}") { |delta| send("#{name}=", send(name) + delta) }
+
+      define_method(name) { subclass.send(name) }
+      define_method("#{name}=") { |v| subclass.send("#{name}=", v) }
+      define_method("reset_#{name}") { subclass.send("reset_#{name}") }
+      define_method("add_#{name}") { |delta| subclass.send("add_#{name}", delta) }
+    end
+
+    def self.inherited(subclass)
+      super
+
+      subclass.backtrace_cleaner = ActiveSupport::BacktraceCleaner.new
+      subclass.verbose_query_logs = verbose_query_logs
+      subclass.metrics = []
+
+      RequestMetrics.register(subclass)
+
+      controller_runtime_module = Module.new { extend ActiveSupport::Concern }
+
+      controller_runtime_module.class_methods do
+        define_method :log_process_action do |payload|
+          messages = super(payload)
+          subclass.summary_log(payload)&.then { messages << it }
+          messages
+        end
+      end
+
+      controller_runtime_module.define_method :append_info_to_payload do |payload|
+        super(payload)
+        subclass.metrics.each { |metric| payload[metric] = subclass.send("reset_#{metric}") }
+      end
+
+      subclass.const_set :ControllerRuntime, controller_runtime_module
+    end
+
+    def self.install!
+      runtime_module = const_get(:ControllerRuntime)
+      ActiveSupport.on_load(:action_controller) { include runtime_module }
+    end
+
+    def self.summary_log(payload)
+      nil
+    end
+
+    def log(**options)
+      raise NotImplementedError, "#{self.class} must implement #log"
+    end
+
+    singleton_class.delegate :log, to: :new
+
+    def debug(message)
+      logger.debug(message)
+      log_query_source if verbose_query_logs
+    end
+
+    private
+
+    def log_query_source
+      source = query_source_location
+      logger.debug("  ↳ #{source}") if source
+    end
+
+    def query_source_location
+      backtrace_cleaner.first_clean_frame
+    end
+  end
+end

data/lib/request_metrics/railtie.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+require "rails/railtie"
+
+module RequestMetrics
+  class Railtie < Rails::Railtie
+    initializer "request_metrics.install" do
+      ActiveSupport.on_load(:action_controller) do
+        RequestMetrics.registry.each(&:install!)
+      end
+    end
+  end
+end

data/lib/request_metrics/version.rb

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

data/lib/request_metrics.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+require_relative "request_metrics/version"
+require_relative "request_metrics/base"
+require_relative "request_metrics/railtie" if defined?(Rails::Railtie)
+
+module RequestMetrics
+  class << self
+    def registry
+      @registry ||= []
+    end
+
+    def register(subclass)
+      registry << subclass
+    end
+  end
+end

data/sig/request_metrics.rbs

@@ -0,0 +1,4 @@
+module RequestMetrics
+  VERSION: String
+  # See the writing guide of rbs: https://github.com/ruby/rbs#guides
+end

metadata

@@ -0,0 +1,70 @@
+--- !ruby/object:Gem::Specification
+name: request_metrics
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Elia Schito
+bindir: exe
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: activesupport
+  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'
+description: |
+  RequestMetrics provides a base class for attaching per-request counters and
+  timing metrics to Rails controller log lines. Subclass RequestMetrics::Base,
+  declare metrics with metric_accessor, implement #log and .summary_log, and
+  the gem wires everything into ActionController via a Railtie automatically.
+email:
+- elia@schito.me
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- Rakefile
+- lib/request_metrics.rb
+- lib/request_metrics/base.rb
+- lib/request_metrics/railtie.rb
+- lib/request_metrics/version.rb
+- sig/request_metrics.rbs
+homepage: https://github.com/nebulab/request_metrics
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/nebulab/request_metrics
+  source_code_uri: https://github.com/nebulab/request_metrics
+  changelog_uri: https://github.com/nebulab/request_metrics/blob/main/CHANGELOG.md
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.2.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.10
+specification_version: 4
+summary: Per-request metric tracking and log summaries for Rails controllers
+test_files: []