grape_rails_logger 1.1.3

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 2d1839d07980cee564c002812c19ab9a6a016e329c6607e0efd559631fee199c
+  data.tar.gz: 1a5e41ca402611b34b8784593b7153ead03aa7e6dcdc2b6296bfe346f97d8da7
+SHA512:
+  metadata.gz: 50480cc2aaf96b6ac140313ac150da9787913c083bb4925347540eb66d011831b6fd59d1fec128cbf766ff943d7dfd7a6d05c54c04b4392eabff23b25926be68
+  data.tar.gz: ac3223da238c2294dfff9bf59b86b88a204282898daf720caaea9e1c89a262f282e44c5b0418a4113f218e7b88e4b82ad0ec2baa2e20320acb037e08e4edecec

data/CHANGELOG.md

@@ -0,0 +1,32 @@
+# CHANGELOG
+
+## 1.1.2 (2025-11-05)
+
+- Fix autoloading: replace `require_relative` with `require` in main entry file to work when installed from RubyGems
+- Fix Railtie discovery: always require Railtie file (not conditionally) so Rails can discover it during initialization
+
+## 1.1.1 (2025-11-05)
+
+- Fix autoloading: explicitly set `require_paths` in gemspec so gem works without explicit `require` parameter in Gemfile
+
+## 1.1.0 (2025-11-05)
+
+- Removed `GrapeInstrumentation` middleware - instrumentation now happens automatically via Railtie
+- Refactored internal code into focused modules (Timings, StatusExtractor, Subscriber, EndpointPatch, EndpointWrapper)
+- Improved test coverage for core modules
+
+## 1.0.0 (2025-11-04)
+
+Initial stable release.
+
+- Automatic request logging for Grape API endpoints
+- Structured logging with method, path, status, duration, and database timings
+- Automatic parameter filtering for sensitive data (passwords, secrets, tokens)
+- Exception logging with error details and backtraces
+- Debug tracing mode for detailed request inspection (when TRACE env var is set)
+- Automatic Rails integration with zero configuration
+- Works standalone or integrates with activesupport-json_logging
+- Supports Rails 6.0 through 8.0+
+- Thread-safe DB timing using IsolatedExecutionState (Rails 7.1+) or Thread.current (Rails 6-7.0)
+- Controller and action extraction from Grape endpoint source locations
+- Source location tracking (file:line) for debugging

data/LICENSE.md

@@ -0,0 +1,23 @@
+MIT License
+
+Copyright (c) 2025
+
+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,108 @@
+# grape_rails_logger
+
+[![Gem Version](https://badge.fury.io/rb/grape_rails_logger.svg?v=1.1.0)](https://badge.fury.io/rb/grape_rails_logger) [![Test Status](https://github.com/amkisko/grape_rails_logger.rb/actions/workflows/ci.yml/badge.svg)](https://github.com/amkisko/grape_rails_logger.rb/actions/workflows/ci.yml) [![codecov](https://codecov.io/gh/amkisko/grape_rails_logger.rb/graph/badge.svg?token=RC5T0Y2Z5A)](https://codecov.io/gh/amkisko/grape_rails_logger.rb)
+
+Rails-compatible structured logging for Grape APIs with ActiveRecord timing, parameter filtering, and exception tracking.
+
+Sponsored by [Kisko Labs](https://www.kiskolabs.com).
+
+<a href="https://www.kiskolabs.com">
+  <img src="kisko.svg" width="200" alt="Sponsored by Kisko Labs" />
+</a>
+
+## Installation
+
+Add to your Gemfile:
+
+```ruby
+gem "grape_rails_logger"
+```
+
+Run `bundle install` or `gem install grape_rails_logger`.
+
+## Usage
+
+The gem works automatically in Rails applications. No configuration needed. It automatically patches `Grape::Endpoint#build_stack` to instrument requests and subscribes to `grape.request` notifications, logging structured data via `Rails.logger`. Works with any Rails logger or integrates with `activesupport-json_logging` for JSON output.
+
+## What gets logged
+
+Each request logs structured data with:
+- Request metadata: `method`, `path`, `status`, `duration`, `host`, `remote_addr`, `request_id`
+- Route information: `controller`, `action`, `source_location` (file:line)
+- Performance metrics: `duration` (ms), `db` (ActiveRecord query time in ms), `db_calls` (SQL query count)
+- Parameters: `params` (automatically filtered using Rails `filter_parameters`)
+- Exceptions: `exception` object with `class`, `message`, and `backtrace` (non-production only)
+
+## Configuration
+
+Configure parameter filtering in `config/initializers/filter_parameter_logging.rb`:
+
+```ruby
+Rails.application.config.filter_parameters += [
+  :passw, :secret, :token, :_key, :crypt, :salt, :certificate, :otp, :ssn
+]
+```
+
+When Rails `ParameterFilter` is not available, the gem falls back to manual filtering that detects sensitive patterns (password, secret, token, key) in parameter keys.
+
+## Debug tracing
+
+Optional `DebugTracer` middleware provides detailed request tracing when the `debug` gem is installed and `TRACE` environment variable is set:
+
+```ruby
+class API < Grape::API
+  use GrapeRailsLogger::DebugTracer
+end
+```
+
+Enable tracing: `TRACE=1 rails server`. The middleware gracefully degrades if the `debug` gem is not installed.
+
+## Compatibility
+
+- Rails 6.0, 6.1, 7.0, 7.1, 7.2, 8.0+
+- Grape >= 1.6
+- Ruby >= 2.7
+
+In Rails 7.1+, the gem uses `ActiveSupport::IsolatedExecutionState` for improved thread/Fiber safety. In Rails 6-7.0, it falls back to `Thread.current`.
+
+## Development
+
+```bash
+bundle install
+bundle exec appraisal install
+bundle exec rspec
+bin/appraisals
+bundle exec standardrb --fix
+```
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/amkisko/grape_rails_logger.rb
+
+Contribution policy:
+- New features are not necessarily added to the gem
+- Pull request should have test coverage for affected parts
+- Pull request should have changelog entry
+
+Review policy:
+- It might take up to 2 calendar weeks to review and merge critical fixes
+- It might take up to 6 calendar months to review and merge pull request
+- It might take up to 1 calendar year to review an issue
+
+## Publishing
+
+```sh
+rm grape_rails_logger-*.gem
+gem build grape_rails_logger.gemspec
+gem push grape_rails_logger-*.gem
+```
+
+Or use the release script:
+
+```sh
+usr/bin/release.sh
+```
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/lib/grape_rails_logger/debug_tracer.rb

@@ -0,0 +1,87 @@
+module GrapeRailsLogger
+  # Optional middleware for detailed request tracing when TRACE env var is set
+  #
+  # Requires the 'debug' gem to be installed. If TRACE is not set or Debug class
+  # is unavailable, this middleware passes through without tracing.
+  #
+  # This middleware is completely exception-safe: any error in tracing will
+  # cause the middleware to pass through without tracing, never breaking requests.
+  #
+  # @example Usage
+  #   class API < Grape::API
+  #     use GrapeRailsLogger::DebugTracer  # Only traces when TRACE=1
+  #   end
+  class DebugTracer < ::Grape::Middleware::Base
+    TRACE_ENABLED = ENV["TRACE"]
+
+    def call!(env)
+      # Fast path: if TRACE not enabled, pass through immediately
+      return @app.call(env) unless TRACE_ENABLED
+
+      # Try to trace, but if anything fails, just pass through
+      trace_request(env) do
+        @app.call(env)
+      end
+    rescue => e
+      # If tracing fails for any reason, log and pass through
+      # Never break the request flow
+      log_trace_error(e)
+      @app.call(env)
+    end
+
+    private
+
+    def trace_request(env)
+      # Check if Debug is available before attempting to use it
+      unless defined?(Debug)
+        log_debug_unavailable
+        return yield
+      end
+
+      request_method = safe_string(env["REQUEST_METHOD"])
+      request_path = safe_string(env["PATH_INFO"] || env["REQUEST_PATH"])
+      file_prefix = sanitize_file_prefix(request_method, request_path)
+      context = [request_method, request_path].compact.join(" ")
+
+      Debug.new(
+        with_sql: true,
+        with_stack: false,
+        store_file: true,
+        file_prefix: file_prefix,
+        context: context
+      ).trace do
+        yield
+      end
+    rescue => e
+      # If Debug.new or trace fails, log and continue without tracing
+      log_trace_error(e)
+      yield
+    end
+
+    def sanitize_file_prefix(method, path)
+      [method, path].compact.join("_").downcase.gsub(/[^a-z0-9_]+/, "_").slice(0, 100)
+    end
+
+    def safe_string(value)
+      value&.to_s
+    rescue
+      nil
+    end
+
+    def log_debug_unavailable
+      return unless defined?(Rails) && Rails.logger
+
+      Rails.logger.error("DebugTracer: Debug class not available. Install debug gem or disable TRACE.")
+    rescue
+      # Ignore logger errors - never raise from logging
+    end
+
+    def log_trace_error(error)
+      return unless defined?(Rails) && Rails.logger
+
+      Rails.logger.error("DebugTracer: Error during trace - #{error.class}: #{error.message}")
+    rescue
+      # Silently fail - debug tracing should never break requests
+    end
+  end
+end

data/lib/grape_rails_logger/endpoint_patch.rb

@@ -0,0 +1,15 @@
+module GrapeRailsLogger
+  # Monkey patch Grape::Endpoint#build_stack to wrap the final Rack app
+  # This ensures we capture the response AFTER Error middleware has fully processed it
+  module EndpointPatch
+    def build_stack(*args)
+      app = super
+      # Wrap the final Rack app to capture responses after Error middleware
+      if ::GrapeRailsLogger.effective_config.enabled
+        ::GrapeRailsLogger::EndpointWrapper.new(app, self)
+      else
+        app
+      end
+    end
+  end
+end

data/lib/grape_rails_logger/endpoint_wrapper.rb

@@ -0,0 +1,99 @@
+require "logger"
+
+module GrapeRailsLogger
+  # Wraps the final Rack app returned by Grape::Endpoint#build_stack to capture
+  # the response AFTER Error middleware has fully processed it (including rescue_from handlers).
+  #
+  # This is the correct place to log because:
+  # 1. Error middleware wraps everything and processes exceptions
+  # 2. rescue_from handlers run and set the correct status
+  # 3. The final response is returned with the correct status
+  # 4. We capture it here, AFTER all processing is complete
+  class EndpointWrapper
+    def initialize(app, endpoint)
+      @app = app
+      @endpoint = endpoint
+    end
+
+    def call(env)
+      return @app.call(env) unless GrapeRailsLogger.effective_config.enabled
+
+      logger = resolve_logger
+      start_time = Time.now
+      Timings.reset_db_runtime
+
+      # Wrap the entire request in ActiveSupport::Notifications
+      # This ensures we capture the final response AFTER Error middleware processes exceptions
+      ActiveSupport::Notifications.instrument("grape.request", env: env, logger: logger) do |payload|
+        # Call the wrapped app - Error middleware will process exceptions and return final response
+        # NOTE: We do NOT read the body here - Grape will process it and parse params
+        # We'll extract params later from already-parsed sources (endpoint.request.params)
+        response = @app.call(env)
+
+        # NOW collect all data AFTER Error middleware has processed exceptions
+        # At this point, response contains the final Rack response with correct status
+        # AND Grape has already parsed the params, so we can safely access endpoint.request.params
+        collect_response_metadata(response, env, payload, start_time)
+
+        # Return the response - subscriber will log it
+        response
+      end
+    rescue => e
+      # If notifications fail, still process the request
+      handle_instrumentation_error(e)
+      @app.call(env)
+    end
+
+    private
+
+    def resolve_logger
+      config = GrapeRailsLogger.effective_config
+      config.logger || (defined?(Rails) && Rails.logger) || Logger.new($stdout)
+    end
+
+    def collect_response_metadata(response, env, payload, start_time)
+      # Extract status from response - this is the FINAL status after Error middleware
+      status = extract_status_from_response(response)
+      payload[:status] = status if status.is_a?(Integer)
+      payload[:response] = response
+
+      # Extract endpoint info for exception tracking
+      endpoint = env[Grape::Env::API_ENDPOINT] if env.is_a?(Hash)
+      if endpoint
+        # Check for exception info that Grape might have stored
+        if endpoint.respond_to?(:options) && endpoint.options.is_a?(Hash)
+          exception = endpoint.options[:exception] || endpoint.options["exception"] ||
+            endpoint.options[:error] || endpoint.options["error"]
+          payload[:exception_object] = exception if exception.is_a?(Exception)
+        end
+        if endpoint.respond_to?(:exception) && endpoint.exception.is_a?(Exception) && !payload[:exception_object]
+          payload[:exception_object] = endpoint.exception
+        end
+      end
+
+      # Capture DB metrics (already collected by Timings module)
+      payload[:db_runtime] = Timings.db_runtime
+      payload[:db_calls] = Timings.db_calls
+
+      # Note: The subscriber will extract all other data (method, path, format, etc.)
+      # from the env using build_request and other helper methods
+    end
+
+    def extract_status_from_response(response)
+      return nil unless response
+
+      if response.is_a?(Array) && response[0].is_a?(Integer)
+        response[0]
+      elsif response.respond_to?(:to_a)
+        array = response.to_a
+        array[0] if array.is_a?(Array) && array[0].is_a?(Integer)
+      elsif response.respond_to?(:status) && response.status.is_a?(Integer)
+        response.status
+      end
+    end
+
+    def handle_instrumentation_error(error)
+      # Silently handle - don't break requests
+    end
+  end
+end

data/lib/grape_rails_logger/railtie.rb

@@ -0,0 +1,58 @@
+# Only define Railtie if Rails is available
+# This allows the gem to be loaded even when Rails isn't fully initialized yet
+if defined?(Rails) && defined?(Rails::Railtie)
+  require "rails/railtie"
+
+  module GrapeRailsLogger
+    class Railtie < ::Rails::Railtie
+      # Add configuration to Rails.application.config
+      config.grape_rails_logger = ActiveSupport::OrderedOptions.new
+      config.grape_rails_logger.enabled = true
+      config.grape_rails_logger.subscriber_class = GrapeRequestLogSubscriber
+      config.grape_rails_logger.logger = nil # Default to nil, will use Rails.logger
+      config.grape_rails_logger.tag = "Grape" # Default tag for TaggedLogging
+
+      config.after_initialize do
+        # Patch Grape::Endpoint#build_stack to wrap the final Rack app
+        # Use prepend to avoid method redefinition issues
+        Grape::Endpoint.prepend(GrapeRailsLogger::EndpointPatch)
+        # Subscribe to ActiveRecord SQL events for DB timing aggregation
+        # Only subscribe if ActiveRecord is loaded (optional dependency)
+        if defined?(ActiveRecord)
+          ActiveSupport::Notifications.subscribe("sql.active_record") do |*args|
+            GrapeRailsLogger::Timings.append_db_runtime(ActiveSupport::Notifications::Event.new(*args))
+          rescue => e
+            # Never let DB timing errors break anything
+            # Only warn in development to avoid noise in production
+            if Rails.env.development?
+              Rails.logger.warn("GrapeRailsLogger: Failed to append DB runtime - #{e.class}: #{e.message}")
+            end
+          end
+        end
+
+        # Subscribe to Grape request events for logging
+        # Only active if Rails.application.config.grape_rails_logger.enabled is true (default: true)
+        # This subscription can be disabled by users if they want to handle logging themselves
+        # Logging errors are caught and never propagate to avoid breaking requests
+        ActiveSupport::Notifications.subscribe("grape.request") do |*args|
+          # Check if logging is enabled before processing
+          next unless Rails.application.config.grape_rails_logger.enabled
+
+          begin
+            subscriber_class = Rails.application.config.grape_rails_logger.subscriber_class || GrapeRequestLogSubscriber
+            subscriber = subscriber_class.new
+            subscriber.grape_request(ActiveSupport::Notifications::Event.new(*args))
+          rescue => e
+            # Last resort: if subscriber creation or invocation fails, log
+            # This should never happen, but we're ultra-defensive
+            # Only warn in development to avoid noise in production
+            if Rails.env.development?
+              Rails.logger.warn("GrapeRailsLogger: Subscriber failed - #{e.class}: #{e.message}")
+              Rails.logger.warn(e.backtrace&.first(3)&.join("\n")) if e.respond_to?(:backtrace)
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/grape_rails_logger/status_extractor.rb

@@ -0,0 +1,56 @@
+module GrapeRailsLogger
+  # Shared utility for extracting HTTP status codes from exceptions
+  module StatusExtractor
+    module_function
+
+    # Common exception to status code mappings
+    EXCEPTION_STATUS_MAP = {
+      "ActiveRecord::RecordNotFound" => 404,
+      "ActiveRecord::RecordNotUnique" => 409,
+      "ActiveRecord::RecordInvalid" => 422,
+      "ActiveRecord::StatementInvalid" => 422,
+      "ActionController::RoutingError" => 404,
+      "ActionController::MethodNotAllowed" => 405,
+      "ActionController::NotImplemented" => 501,
+      "ActionController::UnknownFormat" => 406,
+      "ActionController::BadRequest" => 400,
+      "ActionController::ParameterMissing" => 400
+    }.freeze
+
+    # Extracts HTTP status code from an exception
+    #
+    # @param e [Exception] The exception to extract status from
+    # @return [Integer] HTTP status code, defaults to 500
+    def extract_status_from_exception(e)
+      return e.status if e.respond_to?(:status) && e.status.is_a?(Integer)
+
+      if e.instance_variable_defined?(:@status)
+        status = e.instance_variable_get(:@status)
+        return status if status.is_a?(Integer)
+      end
+
+      if e.respond_to?(:options) && e.options.is_a?(Hash)
+        return e.options[:status] if e.options[:status].is_a?(Integer)
+      end
+
+      # Check common exception type mappings
+      exception_class_name = e.class.name
+      return EXCEPTION_STATUS_MAP[exception_class_name] if EXCEPTION_STATUS_MAP.key?(exception_class_name)
+
+      # Check if any ancestor class matches
+      EXCEPTION_STATUS_MAP.each do |exception_name, status_code|
+        # Use safe_constantize if available (ActiveSupport), otherwise constantize
+        exception_class = if exception_name.respond_to?(:safe_constantize)
+          exception_name.safe_constantize
+        else
+          exception_name.constantize
+        end
+        return status_code if exception_class && e.is_a?(exception_class)
+      rescue NameError
+        # Exception class not available, skip
+      end
+
+      500
+    end
+  end
+end