Rails Semantic Logger

If no configuration is provided, the gem automatically:

• Writes to log/<environment>.log (colorized if Rails colorized logging is enabled).
• Logs to standard out ($stdout) when running rails server.
• Logs to standard error ($stderr) when running rails console (to prevent log lines from mixing with command return values).
• Replaces multi-line Rails request logs with a single structured "Completed" line containing searchable fields like controller, action, status, and duration.

The project uses appraisal to manage and run tests across different versions of Rails and ActiveRecord. You can run the full suite, target a specific Rails version, or run individual test files and cases.

# Run all supported Rails/ActiveRecord versions
rake

# Run tests for a specific rails version
appraisal rails_4.2 rake

# Run a specific test file for a specific rails version
appraisal rails_5.0 ruby test/controllers/articles_controller_test.rb 

# Run a single test case within a file
appraisal rails_5.0 ruby test/controllers/articles_controller_test.rb -n "/shows new article/"

Add rails_semantic_logger to your Gemfile to replace the default Rails logger with structured logging. You may also optionally add amazing_print to colorize structured payloads in development.

Important: Remove lograge, rails_stdout_logging, or rails_12factor if they are present, as they conflict with this gem.

gem "rails_semantic_logger"
gem "amazing_print" # optional

The JobLogger automatically emits metrics for Sidekiq jobs:

1. Latency: The time between when the job was enqueued and when it started executing. It is logged with the metric name sidekiq.queue.latency.
2. Duration: The time taken to run the job. It is logged using measure_info with the metric name sidekiq.job.perform.

Latency calculation behavior:

• Sidekiq <= 7: Uses seconds since epoch. The logger converts this to milliseconds.
• Sidekiq 8+: Uses milliseconds since epoch.

While rails_semantic_logger automatically detects and sets up appenders for rails server and Sidekiq (server mode), it cannot reliably detect other app servers like bare Puma, Rackup, Passenger, or Unicorn. For these servers, you must manually call RailsSemanticLogger.add_server_appenders within the server's definitive boot hook.

Example for config/puma.rb:

on_booted { RailsSemanticLogger.add_server_appenders }

For platforms like Docker, Kubernetes, or Heroku, you should log JSON to standard out. This allows the platform to collect logs and enables centralized logging systems to parse fields (including payload and metric data) into a searchable hierarchy.

Note that by declaring this appender, you replace the default file appender, making JSON to stdout your only destination.

# Example: Container platform recipe
config.rails_semantic_logger.appenders do |appenders|
  appenders.add(io: $stdout, formatter: :json)
end

If you are using Sidekiq 8+, you can skip the default job logging (including latency and duration metrics) by setting :skip_default_job_logging to true in the configuration object passed to the JobLogger.

# Sidekiq 8+ configuration
# config[:skip_default_job_logging] = true

You can define custom log appenders within a config.rails_semantic_logger.appenders block in your Rails configuration.

Important Behavior: When you declare at least one appender using this block, Rails Semantic Logger stops building its own default file appender. Standard configuration options like format, ap_options, filter, and add_file_appender will no longer apply; instead, only the appenders explicitly declared in this block will be created.

config.rails_semantic_logger.appenders do |appenders|
  appenders.add(file_name: "log/#{Rails.env}.log", formatter: :json)
  appenders.add_server(io: $stdout, formatter: :color)
  appenders.add_console(io: $stderr, formatter: :color)
end