rails_semantic_logging 0.3.0 → 0.3.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8dabf186d9982fb21140d284857db16d25867425b0f9430bc51ba6513851bcc8
-  data.tar.gz: '03886b8629bef05d49a21f11d5e59dd434740e6d40b1b2e9de24bffe4929a1a0'
+  metadata.gz: 505f93635024c16b36a3535ec71c948ac41e570b2f0aef012672596733d38a16
+  data.tar.gz: a0fe323394001c28b2a1e34962ce5aa631b8641e137bf4438d747a1e39d7947e
 SHA512:
-  metadata.gz: 1bd15a9bbce788f3dbccac1f52d2ef0bbbddfe6838b1532abe0fce62c0982a7a29d84b71b3ac028eafa9a721d4485972e5b0d402d15189b21f07ea7110c79e62
-  data.tar.gz: 96836a1fd5830939269323239819805c293285d76889c86bdbef6fd3a343b5250ade36266a939658ee1f0fdb82b7cddac1cc5371238115860dcca5ce8cd7cf27
+  metadata.gz: 726ceadd1533d5dd4947eba6e4408ffb7344dc6a860a511327dea109eb4aca87ea102309d25e00d3a2aa8aa1f7a96b205adf88e934a14b7497a42ff73ae33675
+  data.tar.gz: 35fe8fbeb74a493deacb0bed229e64405ba04f28d4057836a1f7d375f5f7de62aaed1e26a55ed8af54a89bb5c313ed62a29718e3a2722c7d09494e5d1c31b986

data/README.md

@@ -279,6 +279,55 @@ The matcher passes a **duplicated** copy of the log event to the formatter, so a
 
 ## Puma Integration
 
+### Routing Puma's own output through SemanticLogger
+
+Puma writes its boot banner and lifecycle lines straight to stdout, so they stay
+plain text while everything else in the app is structured. In a container that
+means one unparsed event per line, carrying none of the attributes the rest of
+your logs have.
+
+Opt in from `config/puma.rb`:
+
+```ruby
+# config/puma.rb
+require 'rails_semantic_logging/puma'
+RailsSemanticLogging::Puma.activate(self)
+```
+
+`Puma starting in single mode...`, `* Puma version`, `* Ruby version`,
+`* Min/Max threads`, `* Environment`, `* PID`, `* Listening on`,
+`* Starting control server` and `Use Ctrl-C to stop` then go through the
+configured formatter under the logger name `Puma` (override with
+`activate(self, logger_name: '...')`), so they can be selected with
+`logger.name:Puma` alongside the rest of the application logs.
+
+Requires **Puma >= 6.2.0**, which introduced the `custom_logger` DSL option. On
+older versions `activate` returns `false` and changes nothing, so it is safe to
+leave in a shared config.
+
+It has to be called from `config/puma.rb` rather than wired automatically by the
+Railtie: `custom_logger` lives on Puma's configuration DSL, which only exists
+while that file is being evaluated. By the time Rails boots, `Puma::Launcher`
+has already read the option.
+
+Two things it deliberately does not cover:
+
+- The `=> Booting Puma` / `=> Rails ... starting` / `=> Run bin/rails server --help`
+  lines. Those come from `Rails::Command::ServerCommand#print_boot_information`,
+  which writes to `$stdout` through Thor's `say` with no logger in between.
+- Under `puma -C config/puma.rb` (as opposed to `rails server`) the banner is
+  emitted before Rails is loaded, so no appender exists yet. Rather than let
+  SemanticLogger drop those lines silently, the adapter falls back to writing
+  them to stdout until an appender is registered.
+- `- Gracefully stopping, waiting for requests to finish` is logged from inside
+  Puma's SIGTERM trap handler, and Ruby forbids `Mutex#synchronize` in a trap
+  context — which SemanticLogger reaches, directly or through the `datadog`
+  gem's SemanticLogger instrumentation. The adapter catches that and writes the
+  line to stdout instead, so a log line can never abort a shutdown. Since
+  SIGTERM is how containers are stopped, this one matters.
+
+### Forking and appender reopen
+
 With `semantic_logger` >= 5 appenders are reopened automatically after forking, so no Puma
 configuration is needed (opt out with `SemanticLogger.reopen_on_fork = false`).
 

data/VERSION

@@ -1 +1 @@
-0.3.0
+0.3.2

data/lib/rails_semantic_logging/puma.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+require 'semantic_logger'
+
+module RailsSemanticLogging
+  # Routes Puma's own output through SemanticLogger so the boot banner and
+  # lifecycle lines become structured events instead of raw text.
+  #
+  # Without this, Puma writes those lines straight to stdout. In a container
+  # that means the log collector ingests one plain-text event per line, tagged
+  # with whatever host it infers rather than the pod, and none of them carry
+  # the attributes every other line in the app has.
+  #
+  # This cannot be wired from the Railtie: `custom_logger` lives on Puma's
+  # configuration DSL, which only exists while `config/puma.rb` is evaluated.
+  # By the time Rails boots, `Puma::Launcher` has already read the option
+  # (launcher.rb applies `@options[:custom_logger]` in its constructor), and
+  # the `Puma::LogWriter` in use is a fresh instance built by the Rack handler
+  # rather than the reachable `Puma::LogWriter::DEFAULT` singleton. So the app
+  # has to opt in explicitly:
+  #
+  #   # config/puma.rb
+  #   require 'rails_semantic_logging/puma'
+  #   RailsSemanticLogging::Puma.activate(self)
+  #
+  # Note this covers Puma's own output only. The three `=> Booting Puma` /
+  # `=> Rails ... starting` / `=> Run bin/rails server --help` lines come from
+  # `Rails::Command::ServerCommand#print_boot_information`, which writes to
+  # `$stdout` through Thor's `say` with no logger in between, and cannot be
+  # captured here.
+  module Puma
+    # Puma calls `custom_logger.write(str)` when the object responds to
+    # `:write`, otherwise it writes the line to stdout itself.
+    class Adapter
+      def initialize(logger)
+        @logger = logger
+      end
+
+      def write(str)
+        message = str.to_s.chomp
+        return if message.empty?
+
+        # Under `puma -C config/puma.rb` the banner is emitted before Rails is
+        # loaded, so the Railtie has not registered an appender yet and
+        # SemanticLogger would drop the message with no output at all — worse
+        # than the plain-text line we set out to replace. Fall back to stdout
+        # until an appender exists. With `rails server` the app is loaded first
+        # and this branch is never taken.
+        if ::SemanticLogger.appenders.empty?
+          $stdout.puts(message)
+        else
+          @logger.info(message)
+        end
+      rescue StandardError
+        # Puma logs "- Gracefully stopping, waiting for requests to finish"
+        # from inside its SIGTERM trap handler (Single#stop_blocked, reached
+        # from Launcher#setup_signals). Ruby forbids Mutex#synchronize in a
+        # trap context, and SemanticLogger reaches one — directly or through
+        # the datadog gem's SemanticLogger instrumentation — which raises
+        # ThreadError and aborts the shutdown. Since SIGTERM is how containers
+        # are stopped, a log line must never be able to take the server down:
+        # emit it plainly and carry on.
+        $stdout.puts(message)
+      end
+    end
+
+    module_function
+
+    # @param puma_config [Puma::DSL] the `self` of `config/puma.rb`
+    # @param logger_name [String] name the events are logged under
+    # @return [Adapter, nil] the installed adapter, or nil when unsupported
+    def activate(puma_config, logger_name: 'Puma')
+      # `custom_logger` was added in Puma 6.2.0. Degrade quietly on older
+      # versions rather than raising from a boot file.
+      return unless puma_config.respond_to?(:custom_logger)
+
+      Adapter.new(::SemanticLogger[logger_name]).tap do |adapter|
+        puma_config.custom_logger(adapter)
+      end
+    end
+  end
+end

data/lib/rails_semantic_logging/railtie.rb

@@ -18,18 +18,10 @@ module RailsSemanticLogging
       # Declare a single stdout appender with the configured formatter.
       # IMPORTANT: Do NOT pass level: parameter. Subscriber#level defaults to :trace
       # when unset, which is required by the host app's spec/support/output.rb check.
-      if app.config.rails_semantic_logger.respond_to?(:appenders?)
-        # rails_semantic_logger >= 5: declaring an appender replaces the default
-        # file appender and the automatic console stderr appender.
-        app.config.rails_semantic_logger.appenders do |appenders|
-          appenders.add(io: $stdout, formatter: formatter)
-        end
-      else
-        # rails_semantic_logger 4.x: disable the built-in appenders and add ours.
-        app.config.rails_semantic_logger.console_logger = false
-        app.config.rails_semantic_logger.add_file_appender = false
-        app.config.rails_semantic_logger.format = formatter
-        app.config.semantic_logger.add_appender(io: $stdout, formatter: formatter)
+      # Declaring an appender replaces the default file appender and the
+      # automatic console stderr appender.
+      app.config.rails_semantic_logger.appenders do |appenders|
+        appenders.add(io: $stdout, formatter: formatter)
       end
 
       # Merge default tags (request_id, client_ip) with app-specific custom tags

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: rails_semantic_logging
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.3.2
 platform: ruby
 authors:
 - Fabio Napoleoni
@@ -29,7 +29,7 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '7.1'
+        version: '7.2'
     - - "<"
       - !ruby/object:Gem::Version
         version: '9'
@@ -39,7 +39,7 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '7.1'
+        version: '7.2'
     - - "<"
       - !ruby/object:Gem::Version
         version: '9'
@@ -49,7 +49,7 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '4.0'
+        version: '5.0'
     - - "<"
       - !ruby/object:Gem::Version
         version: '6'
@@ -59,7 +59,7 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '4.0'
+        version: '5.0'
     - - "<"
       - !ruby/object:Gem::Version
         version: '6'
@@ -82,6 +82,7 @@ files:
 - lib/rails_semantic_logging/formatters/datadog.rb
 - lib/rails_semantic_logging/job_logging/active_job_patch.rb
 - lib/rails_semantic_logging/job_logging/sidekiq_patch.rb
+- lib/rails_semantic_logging/puma.rb
 - lib/rails_semantic_logging/railtie.rb
 - lib/rails_semantic_logging/rspec/helpers.rb
 - lib/rails_semantic_logging/rspec/matchers.rb
@@ -100,7 +101,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '3.2'
+      version: '3.3'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="