logtail-rails 0.2.15 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 69e0f9b99939d4b4ab4c3b5b185f09fcc824120618371f8881e10b671b49a218
-  data.tar.gz: 47c66f5323fbab6dd1b1fe2e559cce6097c13c540cd5ce7b5c2b8cb857a65b4b
+  metadata.gz: 2c5828f2141c9b70b0f47591b7dcf8855a648c0297477637fd7029cfd5e39a8d
+  data.tar.gz: 0a88a29844cdbbc76a20a827f0575fc3f3aa4befe32dde404315bb55a733cfa2
 SHA512:
-  metadata.gz: 3378d7cf4c494bc061759ca956239472c8ad9d1f4066d47cba0e0ef7c975ea50e0be2ecc91ec9a778a9d00d78e3f79e8347092505b5a4b8a03de03c902e7fa67
-  data.tar.gz: 6b873bad4830cfe29f52958d5b9493e0c3b0c7ddb634eabe3f6719860722e947548f710ac9b99aecd0e997105a3a1350933df4e85436889b9c0e3db08296a5f5
+  metadata.gz: 9238c31e5e7945f99fdc3acae8a7006f6f0568e3e2269469a0498da0d5010718d2a3dc884bfd64cc471be0c7a54283e32ff327f8fa1dd11d70b76d1baf84dc2c
+  data.tar.gz: 76f5185abcdc9efafbe564d65a543cb924dcfb75326686645f346a7e30201b053cad5380701f8abe3d0ed01db85f0a54b631522dca449bf4aba2164967f6d840

data/README.md

@@ -14,7 +14,7 @@ Experience SQL-compatible structured log management based on ClickHouse. [Learn
 
 [Getting started ⇗](https://betterstack.com/docs/logs/ruby-and-rails/#logging-from-rails)
 
-To turn the integration off in an environment, e.g. development or test, set `config.logtail.enabled = false` in `config/environments/<environment>.rb`. Rails then logs to `log/<environment>.log` as usual, even if `config/application.rb` creates the Better Stack logger.
+[Example project](example-project/README.md): logging, structured data and [adding context to every log line of a request](example-project/README.md#context).
 
 ## Need help?
 Please let us know at [hello@betterstack.com](mailto:hello@betterstack.com). We're happy to help!

data/example-project/README.md

@@ -185,12 +185,53 @@ This will generate the following JSON output:
 }
 ```
 
-We will automatically add the information about the current user to each log if you're using Ruby on Rails and the Devise gem.
+We will automatically add the information about the current user to each log if you're using Ruby on Rails with Devise (or any other Warden-based authentication) or with Clearance.
 
-If you're not using Devise or you want to log some additional information for every request your Rails app handles, you can easily implement this using Rails' `around_action` in your application controller. A simple implementation could look like this:
+### Context for every log line of a request
+
+The request and response lines (`Started GET "/" for 127.0.0.1` and `Completed 200 OK in 12.3ms`) are logged by a Rack middleware, before the request reaches your controller. Context set from inside a controller is therefore attached to the logs from the controller action on, but not to these two lines. To attach context to every log line of a request, set it in a Rack middleware instead.
+
+The user context from Devise or Clearance is set this way, by the `Logtail::Integrations::Rack::UserContext` middleware. If you authenticate differently, give it a lambda that finds the user in the Rack environment and returns a hash, or `nil` when nobody is signed in:
 
 ```ruby
-class ApplicationController < ActionController::Base
+# config/initializers/logtail.rb
+Logtail::Integrations::Rack::UserContext.custom_user_hash = lambda do |rack_env|
+  user_id = rack_env["rack.session"]["user_id"]
+  user = User.find_by(id: user_id) if user_id
+  user && { id: user.id, email: user.email }
+end
+```
+
+The hash is logged as `context.user` on every log line of the request, including the request and response lines. The lambda runs on every request, so keep it cheap. It can read anything from the Rack environment, for example an API token from `rack_env["HTTP_AUTHORIZATION"]`.
+
+For any other per-request context (a tenant, an API client, a GraphQL operation name), write your own middleware that wraps the request in `Logtail.with_context` and insert it before the middleware that logs the request and response lines:
+
+```ruby
+# config/initializers/logtail.rb
+class LogtailTenantContext
+  def initialize(app)
+    @app = app
+  end
+
+  def call(env)
+    tenant = env["HTTP_X_TENANT"]
+    return @app.call(env) unless tenant
+
+    Logtail.with_context(tenant: { name: tenant }) { @app.call(env) }
+  end
+end
+
+Rails.application.config.middleware.insert_before Logtail::Integrations::Rack::HTTPEvents, LogtailTenantContext
+```
+
+Inserting it before `Logtail::Integrations::Rack::HTTPEvents` also places it after your authentication middleware (such as Warden), so the session and the signed-in user are already available in `env`.
+
+### Context from a controller
+
+If the user is only known once your controller runs (for example, you authenticate from a token in a `before_action`), you can still set the context with Rails' `around_action`. It covers the logs from the controller action and everything it calls, but not the request and response lines, which are logged before the action runs. A simple implementation could look like this:
+
+```ruby
+class ApplicationController < ActionController::Base # or ActionController::API
   around_action :with_logtail_context
 
   private
@@ -202,7 +243,7 @@ class ApplicationController < ActionController::Base
         yield
       end
     end
-    
+
     def user_context
       Logtail::Contexts::User.new(
         id: current_user.id,

data/lib/logtail-rails/error_event.rb

@@ -18,9 +18,11 @@ module Logtail
         # We determine this when the app loads to avoid the overhead on a per request basis.
         EXCEPTION_WRAPPER_TAKES_CLEANER = defined?(::ActionDispatch::ExceptionWrapper) &&
           !::ActionDispatch::ExceptionWrapper.instance_methods.include?(:env)
-        # config.action_dispatch.log_rescued_responses (Rails 7.0+), as ActionDispatch::DebugExceptions
-        # reads it. This gem silences its logging and logs the exception here instead.
+        # config.action_dispatch.log_rescued_responses (Rails 7.0+) and
+        # config.action_dispatch.debug_exception_log_level (Rails 7.1+), as ActionDispatch::DebugExceptions
+        # reads them. This gem silences its logging and logs the exception here instead.
         LOG_RESCUED_RESPONSES_KEY = "action_dispatch.log_rescued_responses".freeze
+        DEBUG_EXCEPTION_LOG_LEVEL_KEY = "action_dispatch.debug_exception_log_level".freeze
 
         def call(env)
           begin
@@ -38,7 +40,7 @@ module Logtail
         def log_exception(env, exception)
           return if !log_exception?(env, exception)
 
-          Config.instance.logger.fatal do
+          Config.instance.logger.add(env[DEBUG_EXCEPTION_LOG_LEVEL_KEY] || ::Logger::FATAL) do
             backtrace = extract_backtrace(env, exception)
             Events::Error.new(
               name: exception.class.name,

data/lib/logtail-rails/logger.rb

@@ -65,10 +65,15 @@ module Logtail
       options[:ingesting_port] ||= options[:telemetry_port] if options[:telemetry_port].present?
       options[:ingesting_scheme] ||= options[:telemetry_scheme] if options[:telemetry_scheme].present?
 
-      if ENV['LOGTAIL_SKIP_LOGS'].blank? && !Rails.env.test?
-        io_device = Logtail::LogDevices::HTTP.new(source_token, options)
-      else
+      if ENV['LOGTAIL_SKIP_LOGS'].present? || Rails.env.test?
         io_device = STDOUT
+      elsif source_token.blank?
+        # Don't break booting the app without the token, e.g. for `assets:precompile` in a Docker build
+        @blank_source_token = true
+        io_device = STDOUT
+      else
+        io_device = Logtail::LogDevices::HTTP.new(source_token, options)
+        @better_stack_logger_created = true
       end
 
       logger = self.create_logger(io_device)
@@ -87,5 +92,12 @@ module Logtail
 
       logger
     end
+
+    class << self
+      # What {create_default_logger} did, Logtail::Frameworks::Rails::Railtie warns about it once the app has booted
+      #
+      # @private
+      attr_reader :blank_source_token, :better_stack_logger_created
+    end
   end
 end

data/lib/logtail-rails/railtie.rb

@@ -43,6 +43,31 @@ module Logtail
             config.app_middleware.use middleware_class
           end
         end
+
+        # Warns about problems with the logger create_default_logger created, unless the integration is turned off.
+        # Registered here, so that it runs after the app's own after_initialize blocks, which may still broadcast to it.
+        initializer(:logtail_logger_check, after: :load_config_initializers) do |app|
+          app.config.after_initialize do
+            next unless Integrations::Rails.enabled?
+
+            if Logtail::Logger.blank_source_token
+              Kernel.warn("Logtail: the source token passed to Logtail::Logger.create_default_logger is blank, logging to STDOUT instead of sending logs to Better Stack.")
+              next
+            end
+            next unless Logtail::Logger.better_stack_logger_created
+
+            # A `config.logger = ...` line after config/application.rb, like the one generated in
+            # config/environments/production.rb, replaces the Better Stack logger without any error
+            loggers = ::Rails.logger.respond_to?(:broadcasts) ? ::Rails.logger.broadcasts : [::Rails.logger]
+            next if loggers.any? { |logger| logger.is_a?(Logtail::Logger) }
+
+            # Before Rails 7.1, broadcasting extends the logger with an anonymous module, which hides the target
+            extended_modules = ::Rails.logger.singleton_class.included_modules - ::Rails.logger.class.included_modules
+            next if extended_modules.any? { |mod| mod.name.nil? }
+
+            Kernel.warn("Logtail: Rails.logger isn't the Better Stack logger created by Logtail::Logger.create_default_logger, and doesn't broadcast to it, so your logs don't reach Better Stack. Most likely config.logger is set again later, e.g. in config/environments/production.rb.")
+          end
+        end
       end
     end
   end

data/lib/logtail-rails/version.rb

@@ -1,7 +1,7 @@
 module Logtail
   module Integrations
     module Rails
-      VERSION = "0.2.15"
+      VERSION = "0.3.0"
     end
   end
 end

data/lib/logtail-rails.rb

@@ -50,6 +50,7 @@ module Logtail
         ActionView.integrate!
         ActiveRecord.integrate!
         RackLogger.integrate!
+        filter_parameters_in_urls(::Rails.application.config.filter_parameters)
       end
 
       def self.enabled=(value)
@@ -71,6 +72,16 @@ module Logtail
         @middlewares ||= [Logtail::Integrations::Rack::HTTPContext, SessionContext, Logtail::Integrations::Rack::UserContext,
           Logtail::Integrations::Rack::HTTPEvents, Logtail::Integrations::Rails::ErrorEvent].select(&:enabled?)
       end
+
+      # Filters the app's filter_parameters from the query strings and the Referer and Location
+      # URLs that Rack::HTTPEvents logs, unless the app customised its query_string_filters.
+      # Procs are left out: they rewrite values, while query string filters match names.
+      def self.filter_parameters_in_urls(filter_parameters)
+        http_events = Logtail::Integrations::Rack::HTTPEvents
+        return if http_events.query_string_filters != http_events::DEFAULT_QUERY_STRING_FILTERS
+
+        http_events.query_string_filters = filter_parameters.reject { |filter| filter.is_a?(Proc) }
+      end
     end
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: logtail-rails
 version: !ruby/object:Gem::Version
-  version: 0.2.15
+  version: 0.3.0
 platform: ruby
 authors:
 - Better Stack