rails_semantic_logging 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 489018fd333371c700b41e42079eedb52ecae7560a0d0fbecd2f354b62cd4a85
+  data.tar.gz: 9d3b301a0275c7b0fa18348192413c8d7359fa4dbccac5ffbb6225d04e753187
+SHA512:
+  metadata.gz: bf98ed4b1007f7a3085a0ea1d75bcc6c5a8158bd94ee2e246ec39ebb0e9934d89ee3b4287fc70f74aeff969e11e8c135d5c588940e72e34e37fc2539d5a4d8f9
+  data.tar.gz: bad27c3d7210034773745b1f8889ecba556af9db932e7c762cd69a86cc322449b90f2baf1a62285bcee583ca8c1d3c640a1369d2d5c906983a44a62cd6662dfd

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2025 Fabio Napoleoni
+
+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,254 @@
+# RailsSemanticLogging
+
+Opinionated Rails semantic logger configuration with Datadog support. Provides a consistent, structured JSON logging setup for Rails applications, with hooks for Sidekiq, ActiveJob, and Datadog-friendly formatters.
+
+## Features
+
+- **Datadog formatter** with [Standard Attributes](https://docs.datadoghq.com/standard-attributes/) mapping
+- **Default payload enrichment** for controllers (host, user_agent, referer) mapped to `http.*`
+- **JSON formatter** for structured logging without Datadog-specific fields
+- **ActiveJob integration** with named tags (`job_class`, `job_id`, `queue`) instead of array tags
+- **Sidekiq integration** with job context in all log lines
+- **Configurable** via [anyway_config](https://github.com/palkan/anyway_config) (YAML, env vars, or code)
+- **Environment-aware** defaults (Datadog JSON in production, color in development, fatal in test)
+- **RSpec matcher** for asserting log output in tests
+
+## Installation
+
+Add to your application's Gemfile:
+
+```ruby
+gem 'rails_semantic_logging'
+```
+
+Then run `bundle install`.
+
+## Usage
+
+### Basic Configuration
+
+The gem auto-configures via a Railtie when loaded by Rails. Out of the box:
+
+- Datadog JSON formatter in production, color formatter elsewhere
+- `request_id` and `client_ip` log tags
+- Default payload enrichment (host, user_agent, referer) on all controller actions
+- Quiet assets logging
+- Sync mode in test environment
+- Log level: INFO (production), DEBUG (development), FATAL (test)
+- `LOG_LEVEL` env var override supported
+
+### Custom Configuration
+
+```ruby
+# config/application.rb (inside class body)
+RailsSemanticLogging.configure do |config|
+  config.application_name = 'My App'
+  config.environment_name = ENV.fetch('NAMESPACE', Rails.env)
+
+  # Add custom log tags (merged with default request_id + client_ip)
+  config.custom_log_tags = {
+    user: ->(request) { extract_user_id(request) },
+    tenant: ->(request) { request.headers['X-Tenant-ID'] }
+  }
+
+  # Override formatters (default: :datadog for production, :color for development)
+  # config.production_formatter = :json     # plain JSON without Datadog mapping
+  # config.production_formatter = :datadog  # Datadog Standard Attributes (default)
+  # config.development_formatter = :color   # colorized console output (default)
+
+  # Disable automatic payload enrichment on controllers (default: true)
+  # config.default_payload = false
+end
+```
+
+Configuration can also be set via YAML (`config/rails_semantic_logging.yml`) or environment variables (`RAILS_SEMANTIC_LOGGING_QUIET_ASSETS=false`) thanks to [anyway_config](https://github.com/palkan/anyway_config).
+
+#### Formatter override via YAML
+
+```yaml
+# config/rails_semantic_logging.yml
+production:
+  production_formatter: json
+
+development:
+  development_formatter: color
+```
+
+#### Formatter override via environment variables
+
+```bash
+RAILS_SEMANTIC_LOGGING_PRODUCTION_FORMATTER=datadog bin/rails server
+RAILS_SEMANTIC_LOGGING_DEVELOPMENT_FORMATTER=color bin/rails server
+```
+
+Both string and symbol values are accepted for formatter options (e.g. `"datadog"` from YAML/ENV is equivalent to `:datadog` in Ruby).
+
+### Configuration Options
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `application_name` | Rails app name | SemanticLogger application name |
+| `environment_name` | `Rails.env` | SemanticLogger environment name |
+| `custom_log_tags` | `{}` | Extra log tags (merged with `request_id` + `client_ip`) |
+| `quiet_assets` | `true` | Silence asset pipeline logs |
+| `sync_in_test` | `true` | Use synchronous logging in test environment |
+| `default_payload` | `true` | Auto-include host, user_agent, referer in controller logs |
+| `production_formatter` | `:datadog` | Formatter for production (`:datadog`, `:json`, or instance) |
+| `development_formatter` | `:color` | Formatter for non-production environments |
+
+## Datadog Integration
+
+### Standard Attributes Mapping
+
+The `:datadog` formatter maps all log fields to [Datadog Standard Attributes](https://docs.datadoghq.com/standard-attributes/) so logs are automatically parsed and correlated in Datadog without custom pipelines.
+
+#### Core log fields
+
+| SemanticLogger field | Datadog Standard Attribute | Notes |
+|---------------------|---------------------------|-------|
+| Logger name | `logger.name` | Class/module that emitted the log |
+| Level | `status` | `debug`, `info`, `warn`, `error`, `fatal` |
+| Duration | `duration` | Converted to **nanoseconds** |
+| Exception class | `error.kind` | e.g. `RuntimeError` |
+| Exception message | `error.message` | Human-readable description |
+| Backtrace | `error.stack` | Full stack trace as string |
+
+#### HTTP fields (from controller payload)
+
+When `default_payload` is enabled (default), controller request logs include:
+
+| Payload field | Datadog Standard Attribute | Source |
+|--------------|---------------------------|--------|
+| `status` | `http.status_code` | Rails built-in |
+| `method` | `http.method` | Rails built-in |
+| `path` | `http.url` | Rails built-in |
+| `host` | `http.url_details.host` | `DefaultPayload` concern |
+| `user_agent` | `http.useragent` | `DefaultPayload` concern |
+| `referer` | `http.referer` | `DefaultPayload` concern |
+
+#### Datadog trace correlation
+
+When Datadog tracing is active, the formatter injects: `dd.trace_id`, `dd.span_id`, `dd.env`, `dd.service`, `dd.version`.
+
+### Example: Complete request log (production)
+
+```json
+{
+  "timestamp": "2025-10-26T10:30:45.123Z",
+  "status": "info",
+  "host": "web-01",
+  "logger.name": "Rails",
+  "message": "Completed 200 OK in 42ms",
+  "duration": 42500000,
+  "http.status_code": 200,
+  "http.method": "GET",
+  "http.url": "/api/v1/bikes",
+  "http.url_details.host": "api.example.com",
+  "http.useragent": "Mozilla/5.0 (iPhone; iOS 17.0)",
+  "http.referer": "https://app.example.com/dashboard",
+  "dd.trace_id": "1234567890",
+  "dd.span_id": "9876543210"
+}
+```
+
+### Example: Background job log
+
+```json
+{
+  "timestamp": "2025-10-26T10:31:00.456Z",
+  "status": "info",
+  "host": "worker-01",
+  "logger.name": "Rails",
+  "message": "Performing ImportBikesJob from Sidekiq(default)",
+  "named_tags": {
+    "job_class": "ImportBikesJob",
+    "job_id": "abc-123",
+    "queue": "default"
+  }
+}
+```
+
+### Example: Error log
+
+```json
+{
+  "timestamp": "2025-10-26T10:32:15.789Z",
+  "status": "error",
+  "host": "web-01",
+  "logger.name": "BikeService",
+  "message": "Failed to import bike",
+  "error.kind": "ActiveRecord::RecordInvalid",
+  "error.message": "Validation failed: VIN is not unique",
+  "error.stack": "app/services/bike_service.rb:42:in `import'\n..."
+}
+```
+
+## Formatters
+
+### JSON Formatter `:json`
+
+Plain structured JSON without Datadog-specific field mapping. Useful for non-Datadog log pipelines.
+
+```json
+{
+  "timestamp": "2025-10-26T10:30:45.123Z",
+  "level": "info",
+  "host": "server-1",
+  "name": "Rails",
+  "message": "Processing request",
+  "duration_ms": 42.5
+}
+```
+
+### Color Formatter `:color` (development default)
+
+Uses the built-in `SemanticLogger::Formatters::Color` for human-readable development output.
+
+## RSpec Matcher
+
+Include the matcher module in your spec config:
+
+```ruby
+require 'rails_semantic_logging/rspec/matchers'
+
+RSpec.configure do |config|
+  config.include RailsSemanticLogging::RSpec::Matchers
+end
+```
+
+Usage:
+
+```ruby
+expect { logger.info("hello") }.to log_semantic(level: :info, message: /hello/)
+expect { logger.warn("oops", key: "val") }.to log_semantic(payload: { key: "val" })
+expect { do_work }.to log_semantic(named_tags: { job_class: 'MyJob' })
+```
+
+## Puma Integration
+
+When using Puma in clustered mode, reopen log appenders after forking:
+
+```ruby
+# config/puma.rb
+if workers_number.positive?
+  preload_app!
+
+  before_worker_boot do
+    SemanticLogger.reopen
+  end
+end
+```
+
+## Development
+
+```bash
+git clone https://github.com/fabn/rails_semantic_logging.git
+cd rails_semantic_logging
+bundle install
+bundle exec rspec
+bundle exec rubocop
+```
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](LICENSE.txt).

data/lib/rails_semantic_logging/action_controller/default_payload.rb

@@ -0,0 +1,28 @@
+module RailsSemanticLogging
+  module ActionController
+    # Concern that enriches controller log payload with standard HTTP request fields.
+    # Include in ApplicationController (or a base controller) to automatically add
+    # host, user_agent, and referer to every request log line.
+    #
+    # These fields are then mapped to Datadog Standard Attributes by the Datadog formatter:
+    #   host       -> http.url_details.host
+    #   user_agent -> http.useragent
+    #   referer    -> http.referer
+    #   status     -> http.status_code  (already in Rails payload)
+    #   method     -> http.method       (already in Rails payload)
+    #   path       -> http.url          (already in Rails payload)
+    module DefaultPayload
+      extend ActiveSupport::Concern
+
+      # @see https://github.com/rails/rails/blob/main/actionpack/lib/action_controller/metal/instrumentation.rb
+      def append_info_to_payload(payload)
+        super
+        # Use :full_path because rails_semantic_logger strips query string from :path
+        payload[:full_path] = request.fullpath
+        payload[:host] = request.host
+        payload[:user_agent] = request.user_agent
+        payload[:referer] = request.referer if request.referer.present?
+      end
+    end
+  end
+end

data/lib/rails_semantic_logging/configuration.rb

@@ -0,0 +1,74 @@
+require 'anyway_config'
+
+module RailsSemanticLogging
+  class Configuration < Anyway::Config
+    config_name :rails_semantic_logging
+
+    attr_config(
+      application_name: nil,
+      environment_name: nil,
+      custom_log_tags: {},
+      quiet_assets: true,
+      sync_in_test: true,
+      stdout_sync: true,
+      default_payload: true,
+      production_formatter: nil,
+      development_formatter: :color
+    )
+
+    DEFAULT_LOG_TAGS = { request_id: :request_id, client_ip: :remote_ip }.freeze
+
+    VALID_LOG_LEVELS = %w[DEBUG INFO WARN ERROR FATAL UNKNOWN].freeze
+
+    # Merges built-in default tags with app-provided custom tags
+    def effective_log_tags
+      DEFAULT_LOG_TAGS.merge(custom_log_tags)
+    end
+
+    # Returns the appropriate formatter for the given environment
+    def formatter_for(env)
+      case env.to_s
+      when 'production'
+        resolve_formatter(production_formatter) || RailsSemanticLogging::Formatters::Datadog.new
+      else
+        resolve_formatter(development_formatter) || :color
+      end
+    end
+
+    # Returns the appropriate log level for the given environment, respecting LOG_LEVEL env var
+    def log_level_for(env)
+      default_level = case env.to_s
+                      when 'development' then 'DEBUG'
+                      when 'test' then 'FATAL'
+                      else 'INFO'
+                      end
+
+      requested = ENV.fetch('LOG_LEVEL', default_level).to_s.upcase
+      VALID_LOG_LEVELS.include?(requested) ? requested : default_level
+    end
+
+    private
+
+    def resolve_formatter(value)
+      value = value.to_sym if value.is_a?(String)
+      return value unless value.is_a?(Symbol)
+      return RailsSemanticLogging::Formatters::Datadog.new if value == :datadog
+
+      value
+    end
+  end
+
+  class << self
+    def config
+      @config ||= Configuration.new
+    end
+
+    def configure
+      yield(config)
+    end
+
+    def reset_config!
+      @config = Configuration.new
+    end
+  end
+end

data/lib/rails_semantic_logging/datadog/log_injection.rb

@@ -0,0 +1,36 @@
+# Monkey patch for Datadog's ActiveJob LogInjection to use hash-style
+# correlation tags instead of string-style. This is necessary because
+# we patch ActiveJob::Logging to use named tags (job_class, job_id, queue),
+# so Datadog must also use hash-style tags for compatibility with SemanticLogger.
+
+module RailsSemanticLogging
+  module Datadog
+    module LogInjection
+      def self.apply!
+        return unless defined?(::Datadog::Tracing::Contrib::ActiveJob::LogInjection)
+
+        # Ensure the SemanticLogger ActiveJob extension is loaded first
+        require 'rails_semantic_logger/extensions/active_job/logging'
+
+        # Replace the original module with our patched version
+        ::Datadog::Tracing::Contrib::ActiveJob.send(:remove_const, :LogInjection)
+        ::Datadog::Tracing::Contrib::ActiveJob.const_set(:LogInjection, PatchedLogInjection)
+      end
+
+      # Replacement module that uses correlation.to_h instead of log_correlation
+      module PatchedLogInjection
+        def self.included(base)
+          base.class_eval do
+            around_perform do |_, block|
+              if ::Datadog.configuration.tracing.log_injection && logger.respond_to?(:tagged)
+                logger.tagged(::Datadog::Tracing.correlation.to_h, &block)
+              else
+                block.call
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/rails_semantic_logging/formatters/datadog.rb

@@ -0,0 +1,189 @@
+require 'semantic_logger'
+
+module RailsSemanticLogging
+  module Formatters
+    # Datadog-optimized JSON formatter that maps log fields to
+    # Datadog Standard Attributes (https://docs.datadoghq.com/standard-attributes/).
+    #
+    # Key mappings:
+    #   name              -> logger.name
+    #   level             -> status
+    #   duration          -> duration (nanoseconds) + duration_human (Rails format)
+    #   exception         -> error: { kind, message, stack }
+    #   payload           -> http: { status_code, method, url, ... } (controller requests)
+    #   named_tags.dd     -> dd (top-level, for trace linking)
+    #   named_tags.user_* -> usr.{id, email, name, role}
+    class Datadog < ::SemanticLogger::Formatters::Raw
+      NANOSECONDS_PER_MILLISECOND = 1_000_000
+
+      # Mapping of Rails payload keys to Datadog http standard attribute names
+      HTTP_PAYLOAD_MAP = {
+        status: :status_code,
+        method: :method,
+        host: :host,
+        user_agent: :useragent,
+        referer: :referer
+      }.freeze
+
+      # Mapping of user-related named_tags to usr.* standard attributes
+      USER_NAMED_TAGS_MAP = {
+        user_id: :id,
+        user_email: :email,
+        user_name: :name,
+        user_role: :role
+      }.freeze
+
+      def initialize(time_format: :iso_8601, time_key: :timestamp, **args) # rubocop:disable Naming/VariableNumber
+        super(time_format:, time_key:, log_application: false, log_host: true, log_environment: false, **args)
+      end
+
+      def call(log, logger)
+        super
+        remap_named_tags
+        remap_http_payload
+        parse_url_details
+        apache_message
+        deep_compact_blank!(hash)
+        hash.to_json
+      end
+
+      def thread_name
+        # Exclude thread_name from output
+      end
+
+      def name
+        hash[:'logger.name'] = log.name if log.name
+      end
+
+      def level
+        hash[:status] = log.level
+      end
+
+      def duration
+        # Propagate duration from payload if not set on log
+        log.duration = log.payload[:duration] if log.duration.nil? && log.payload&.dig(:duration)
+        return unless log.duration
+
+        # Datadog standard: duration in nanoseconds
+        hash[:duration] = (log.duration * NANOSECONDS_PER_MILLISECOND).to_i
+        # Human-readable duration for readability (Rails format)
+        hash[:duration_human] = "#{log.duration.round(2)}ms"
+      end
+
+      def exception
+        return unless log.exception
+
+        hash[:error] = {
+          kind: log.exception.class.name,
+          message: log.exception.message,
+          stack: log.exception.backtrace&.join("\n")
+        }
+      end
+
+      private
+
+      # Parses http.url into url_details with host, path and queryString
+      def parse_url_details
+        return unless hash.dig(:http, :url)
+
+        url = hash[:http][:url]
+        path, query = url.split('?', 2)
+        details = { path: path }
+        details[:queryString] = Rack::Utils.parse_query(query) if query.present?
+        # Datadog standard: host belongs under http.url_details
+        details[:host] = hash[:http].delete(:host) if hash[:http][:host]
+
+        hash[:http][:url_details] = details
+      end
+
+      # For completed ActionController requests, replace the message with an
+      # Apache-like format: "GET /path JSON 200 1.17ms" for better readability on mobile
+      def apache_message
+        return unless hash[:http].is_a?(Hash) && hash[:http][:status_code] && log.duration
+
+        method = hash[:http][:method] || '-'
+        url = hash[:http][:url] || '-'
+        status = hash[:http][:status_code]
+        format = hash[:payload].is_a?(Hash) ? hash[:payload][:format] : nil
+
+        parts = [method, url]
+        parts << format if format.present?
+        parts << status
+        parts << "#{log.duration.round(2)}ms"
+        hash[:message] = parts.join(' ')
+      end
+
+      # Remaps known named_tags to Datadog standard attributes.
+      # Handles: client_ip, request_id, dd correlation, user_* tags.
+      def remap_named_tags
+        return unless hash[:named_tags].is_a?(Hash)
+
+        remap_network_and_request
+        remap_dd_correlation
+        remap_user_tags
+      end
+
+      def remap_network_and_request
+        if (ip = hash[:named_tags].delete(:client_ip))
+          hash[:network] = { client: { ip: ip } }
+        end
+
+        return unless (rid = hash[:named_tags].delete(:request_id))
+
+        hash[:http] ||= {}
+        hash[:http][:request_id] = rid
+      end
+
+      # Lifts Datadog correlation from named_tags (added by dd-trace-rb SemanticLogger
+      # instrumentation via Tracing.correlation.to_h) to top-level for trace linking.
+      # Skips the dd block entirely when there's no active trace (trace_id is "0").
+      def remap_dd_correlation
+        dd = hash[:named_tags].delete(:dd)
+        ddsource = hash[:named_tags].delete(:ddsource)
+
+        return unless dd.is_a?(Hash) && dd[:trace_id].to_s != '0'
+
+        hash[:dd] = dd
+        hash[:ddsource] = ddsource if ddsource
+      end
+
+      # Maps user_* named_tags to usr.* Datadog standard attributes
+      def remap_user_tags
+        usr = USER_NAMED_TAGS_MAP.each_with_object({}) do |(source, target), h|
+          value = hash[:named_tags].delete(source)
+          h[target] = value if value.present?
+        end
+
+        hash[:usr] = usr if usr.present?
+      end
+
+      # Remaps known HTTP payload fields to nested Datadog http standard attributes
+      def remap_http_payload
+        return unless hash[:payload].is_a?(Hash)
+
+        http = HTTP_PAYLOAD_MAP.each_with_object({}) do |(source, target), h|
+          h[target] = hash[:payload].delete(source) if hash[:payload].key?(source)
+        end
+
+        # Prefer full_path (with query string) over path (stripped by rails_semantic_logger).
+        # Delete both keys unconditionally to avoid duplication in payload.
+        full_path = hash[:payload].delete(:full_path)
+        path = hash[:payload].delete(:path)
+        url = full_path || path
+        http[:url] = url if url.present?
+        return if http.blank?
+
+        hash[:http].is_a?(Hash) ? hash[:http].merge!(http) : hash[:http] = http
+      end
+
+      # Recursively removes blank values from a hash
+      def deep_compact_blank!(h)
+        h.each do |key, value|
+          deep_compact_blank!(value) if value.is_a?(Hash)
+          h.delete(key) if value.blank?
+        end
+        h
+      end
+    end
+  end
+end

data/lib/rails_semantic_logging/job_logging/active_job_patch.rb

@@ -0,0 +1,20 @@
+require 'active_support/concern'
+
+module RailsSemanticLogging
+  module JobLogging
+    # ActiveJob patch to provide named tags instead of array tags.
+    # Converts the default tag_logger(class, id) call into named tags
+    # (job_class, job_id, queue) for structured logging.
+    module ActiveJobPatch
+      extend ActiveSupport::Concern
+
+      def tag_logger(job_class = nil, job_id = nil, &)
+        if job_class && job_id
+          super(job_class: job_class, job_id: job_id, queue: queue_name, &)
+        else
+          super(&)
+        end
+      end
+    end
+  end
+end

data/lib/rails_semantic_logging/job_logging/sidekiq_patch.rb

@@ -0,0 +1,17 @@
+module RailsSemanticLogging
+  module JobLogging
+    # Sidekiq patch to provide job context in every processed job log line.
+    # SemanticLogger uses its own thread for formatting, so Sidekiq::Context
+    # (stored in Thread.current) is lost. This patch wraps each job with
+    # SemanticLogger named tags for consistent structured output.
+    module SidekiqPatch
+      # @param [Hash] item Sidekiq job hash
+      # @param [String] queue Queue name
+      def call(item, queue)
+        Sidekiq.logger.tagged(job_class: item['class'], job_id: item['jid'], queue: queue) do
+          super(item, queue)
+        end
+      end
+    end
+  end
+end

data/lib/rails_semantic_logging/railtie.rb

@@ -0,0 +1,76 @@
+require 'rails/railtie'
+require 'rails_semantic_logger'
+
+module RailsSemanticLogging
+  class Railtie < Rails::Railtie
+    config.before_configuration do
+      $stdout.sync = true if RailsSemanticLogging.config.stdout_sync
+    end
+
+    # Runs BEFORE the upstream rails_semantic_logger Engine's :initialize_logger initializer.
+    # This ensures our configuration is applied before the logger is set up.
+    initializer 'rails_semantic_logging.configure', before: :initialize_logger do |app|
+      cfg = RailsSemanticLogging.config
+
+      # Configure rails_semantic_logger options
+      app.config.rails_semantic_logger.quiet_assets = cfg.quiet_assets
+      app.config.rails_semantic_logger.console_logger = false
+      app.config.rails_semantic_logger.add_file_appender = false
+
+      # Set formatter based on environment
+      app.config.rails_semantic_logger.format = cfg.formatter_for(Rails.env)
+
+      # Merge default tags (request_id, client_ip) with app-specific custom tags
+      app.config.log_tags = cfg.effective_log_tags
+
+      # Set log level based on environment, respecting LOG_LEVEL env var
+      app.config.log_level = cfg.log_level_for(Rails.env)
+
+      # Add 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.
+      app.config.semantic_logger.add_appender(io: $stdout, formatter: app.config.rails_semantic_logger.format)
+    end
+
+    config.to_prepare do
+      cfg = RailsSemanticLogging.config
+      SemanticLogger.application = cfg.application_name || Rails.application.class.module_parent_name
+      SemanticLogger.environment = cfg.environment_name || Rails.env
+      SemanticLogger.sync! if Rails.env.test? && cfg.sync_in_test
+    end
+
+    config.after_initialize do
+      # Include DefaultPayload in ActionController to enrich request logs
+      # with host, user_agent, and referer (mapped to http.* by Datadog formatter)
+      if RailsSemanticLogging.config.default_payload
+        require 'rails_semantic_logging/action_controller/default_payload'
+
+        ActiveSupport.on_load(:action_controller_base) do
+          include RailsSemanticLogging::ActionController::DefaultPayload
+        end
+        ActiveSupport.on_load(:action_controller_api) do
+          include RailsSemanticLogging::ActionController::DefaultPayload
+        end
+      end
+
+      # Apply ActiveJob logging patch for named tags
+      ActiveSupport.on_load(:active_job) do
+        require 'rails_semantic_logging/job_logging/active_job_patch'
+        prepend RailsSemanticLogging::JobLogging::ActiveJobPatch
+      end
+
+      # Apply Sidekiq logging patch if Sidekiq is loaded
+      if defined?(::Sidekiq::JobLogger)
+        require 'sidekiq/job_logger'
+        require 'rails_semantic_logging/job_logging/sidekiq_patch'
+        ::Sidekiq::JobLogger.prepend(RailsSemanticLogging::JobLogging::SidekiqPatch)
+      end
+
+      # Apply Datadog log injection patch if Datadog tracing is loaded
+      if defined?(::Datadog::Tracing::Contrib::ActiveJob::LogInjection)
+        require 'rails_semantic_logging/datadog/log_injection'
+        RailsSemanticLogging::Datadog::LogInjection.apply!
+      end
+    end
+  end
+end

data/lib/rails_semantic_logging/rspec/helpers.rb

@@ -0,0 +1,84 @@
+module RailsSemanticLogging
+  module RSpec
+    # Test helpers for applications using RailsSemanticLogging.
+    #
+    # Provides standalone helpers that work with or without TestProf:
+    # - LoggingHelpers: with_logging / with_ar_logging (uses SemanticLogger.silence)
+    # - SilenceOutput: capture stdout in tests
+    # - Appender validation (ensures single appender at trace level)
+    # - LOG env var support (LOG=all or LOG=ar to enable logging in tests)
+    #
+    # Usage:
+    #   require 'rails_semantic_logging/rspec/helpers'
+    #   RailsSemanticLogging::RSpec::Helpers.install!
+    #
+    module Helpers
+      # Standalone logging helpers using SemanticLogger.silence.
+      # Works without TestProf. If TestProf is present, also patches
+      # TestProf::Rails::LoggingHelpers for compatibility.
+      module LoggingHelpers
+        def with_logging(level = :trace, &)
+          SemanticLogger.silence(level, &)
+        end
+
+        def with_ar_logging(level = :trace, &)
+          SemanticLogger.appenders.first.filter = ->(log) { log.name == 'ActiveRecord' }
+          SemanticLogger.silence(level, &)
+        ensure
+          SemanticLogger.appenders.first.filter = nil
+        end
+      end
+
+      # Helper to silence stdout output in tests
+      module SilenceOutput
+        def silence_stdout
+          original_stdout = $stdout
+          $stdout = StringIO.new
+          yield
+        ensure
+          $stdout = original_stdout
+        end
+      end
+
+      class << self
+        # Installs all test helpers into RSpec configuration.
+        def install!
+          configure_rspec!
+          patch_test_prof!
+        end
+
+        private
+
+        def configure_rspec! # rubocop:disable Metrics/MethodLength
+          ::RSpec.configure do |config|
+            # Make logging helpers available in all specs
+            config.include LoggingHelpers
+
+            # Validate appender configuration
+            config.before(:suite) do
+              if SemanticLogger.appenders.size != 1 || SemanticLogger.appenders.first.level != :trace
+                raise 'Expected only one appender with trace level, ' \
+                      "got #{SemanticLogger.appenders.size} with #{SemanticLogger.appenders.map(&:level)}"
+              end
+            end
+
+            # Enable logging via LOG env var (LOG=all for all logs, LOG=ar for ActiveRecord only)
+            config.around do |ex|
+              next ex.call if ENV['LOG'].blank?
+
+              level = ENV.fetch('LOG_LEVEL', 'trace').to_sym
+              ENV['LOG'].casecmp('ar').zero? ? with_ar_logging(level, &ex) : with_logging(level, &ex)
+            end
+          end
+        end
+
+        # If TestProf is loaded, also patch its LoggingHelpers for compatibility
+        def patch_test_prof!
+          return unless defined?(TestProf::Rails::LoggingHelpers)
+
+          TestProf::Rails::LoggingHelpers.prepend(LoggingHelpers)
+        end
+      end
+    end
+  end
+end

data/lib/rails_semantic_logging/rspec/matchers.rb

@@ -0,0 +1,120 @@
+require 'semantic_logger'
+
+module RailsSemanticLogging
+  module RSpec
+    # In-memory appender that collects log entries for assertion
+    class InMemoryAppender < SemanticLogger::Subscriber
+      attr_reader :logs
+
+      def initialize
+        super(level: :trace)
+        @logs = []
+      end
+
+      def log(log_entry)
+        @logs << log_entry
+      end
+
+      def flush
+        # No-op for in-memory
+      end
+    end
+
+    # RSpec matcher for asserting log output from a block.
+    #
+    # Usage:
+    #   expect { logger.info("hello") }.to log_semantic(level: :info, message: /hello/)
+    #   expect { logger.warn("oops", payload: { key: "val" }) }.to log_semantic(payload: { key: "val" })
+    class LogSemanticMatcher
+      def initialize(expected)
+        @expected_level = expected[:level]
+        @expected_message = expected[:message]
+        @expected_named_tags = expected[:named_tags]
+        @expected_payload = expected[:payload]
+        @captured_logs = []
+      end
+
+      def matches?(block)
+        appender = InMemoryAppender.new
+        SemanticLogger.add_appender(appender: appender)
+        # Temporarily lower log level to capture all messages
+        previous_level = SemanticLogger.default_level
+        SemanticLogger.default_level = :trace
+        block.call
+        SemanticLogger.flush
+        SemanticLogger.default_level = previous_level
+        SemanticLogger.remove_appender(appender)
+
+        @captured_logs = appender.logs
+        @captured_logs.any? { |log| matches_log?(log) }
+      end
+
+      def supports_block_expectations?
+        true
+      end
+
+      def failure_message
+        "expected block to log a message matching #{expected_description}, but captured logs were:\n#{format_logs}"
+      end
+
+      def failure_message_when_negated
+        "expected block not to log a message matching #{expected_description}, but it did"
+      end
+
+      private
+
+      def matches_log?(log)
+        matches_level?(log) && matches_message?(log) && matches_named_tags?(log) && matches_payload?(log)
+      end
+
+      def matches_level?(log)
+        return true unless @expected_level
+
+        log.level == @expected_level
+      end
+
+      def matches_message?(log)
+        return true unless @expected_message
+
+        case @expected_message
+        when Regexp then @expected_message.match?(log.message.to_s)
+        else log.message.to_s == @expected_message.to_s
+        end
+      end
+
+      def matches_named_tags?(log)
+        return true unless @expected_named_tags
+
+        @expected_named_tags.all? { |key, value| log.named_tags[key] == value }
+      end
+
+      def matches_payload?(log)
+        return true unless @expected_payload
+        return false unless log.payload
+
+        @expected_payload.all? { |key, value| log.payload[key] == value }
+      end
+
+      def expected_description
+        parts = []
+        parts << "level: #{@expected_level.inspect}" if @expected_level
+        parts << "message: #{@expected_message.inspect}" if @expected_message
+        parts << "named_tags: #{@expected_named_tags.inspect}" if @expected_named_tags
+        parts << "payload: #{@expected_payload.inspect}" if @expected_payload
+        "{#{parts.join(', ')}}"
+      end
+
+      def format_logs
+        return '  (none)' if @captured_logs.empty?
+
+        @captured_logs.map { |log| "  [#{log.level}] #{log.message} tags=#{log.named_tags} payload=#{log.payload}" }.join("\n")
+      end
+    end
+
+    module Matchers
+      def log_semantic(expected = {})
+        LogSemanticMatcher.new(expected)
+      end
+    end
+  end
+end

data/lib/rails_semantic_logging/version.rb

@@ -0,0 +1,3 @@
+module RailsSemanticLogging
+  VERSION = '0.1.0'.freeze
+end

data/lib/rails_semantic_logging.rb

@@ -0,0 +1,9 @@
+require_relative 'rails_semantic_logging/version'
+require_relative 'rails_semantic_logging/configuration'
+require_relative 'rails_semantic_logging/formatters/datadog'
+
+module RailsSemanticLogging
+  class Error < StandardError; end
+end
+
+require_relative 'rails_semantic_logging/railtie'

metadata

@@ -0,0 +1,101 @@
+--- !ruby/object:Gem::Specification
+name: rails_semantic_logging
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Fabio Napoleoni
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: anyway_config
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.1'
+- !ruby/object:Gem::Dependency
+  name: rails_semantic_logger
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '4.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '4.0'
+description: Provides a consistent, opinionated setup for structured JSON logging
+  in Rails, with specific hooks for Sidekiq, ActiveJob, and Puma, as well as Datadog-friendly
+  formatters.
+email:
+- f.napoleoni@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE.txt
+- README.md
+- lib/rails_semantic_logging.rb
+- lib/rails_semantic_logging/action_controller/default_payload.rb
+- lib/rails_semantic_logging/configuration.rb
+- lib/rails_semantic_logging/datadog/log_injection.rb
+- 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/railtie.rb
+- lib/rails_semantic_logging/rspec/helpers.rb
+- lib/rails_semantic_logging/rspec/matchers.rb
+- lib/rails_semantic_logging/version.rb
+homepage: https://github.com/fabn/rails_semantic_logging
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/fabn/rails_semantic_logging
+  source_code_uri: https://github.com/fabn/rails_semantic_logging
+  changelog_uri: https://github.com/fabn/rails_semantic_logging/releases
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.2'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.9
+specification_version: 4
+summary: Opinionated Rails semantic logger configuration with Datadog support
+test_files: []