LogStruct

Adds JSON structured logging to any Rails app. Simply add the gem to your Gemfile and add an initializer to configure it. By default, your Rails app prints JSON logs to STDOUT (or to the configured destination when RAILS_LOG_TO_STDOUT is set). They're easy to search and filter, you can turn them into metrics and alerts, and they're great for building dashboards in CloudWatch, Grafana, or Datadog.

We support all your other favorite gems too, like Sidekiq, Sentry, and Shrine. (And if not, please open a PR!)

Features

  • JSON logging enabled by default in production and test environments
  • ActionMailer integration for email delivery logging
  • ActiveJob integration for job execution logging
  • Sidekiq integration for background job logging
  • Shrine integration for file upload logging
  • Error handling and reporting
  • Metadata collection for rich context
  • Lograge integration for structured request logging
  • Sensitive data scrubbing for strings (inspired by the Logstop gem)
  • Host authorization logging for security violations
  • Rack middleware for enhanced error logging
  • ActionMailer delivery callbacks for Rails 7.0.x (backported from Rails 7.1)
  • Type checking with Sorbet and RBS annotations

Installation

Add this line to your application's Gemfile:

gem 'logstruct'

And then execute:

$ bundle install

Or install it yourself as:

$ gem install logstruct

Configuration and Initialization

LogStruct is designed to be highly opinionated and work out of the box with minimal configuration.

Please see the documentation for configuration options.

Important Notes on Integration

Once initialized, the gem automatically includes its modules into the appropriate base classes:

  • ActiveSupport::TaggedLogging is patched to support both Hashes and Strings
  • ActionMailer::Base includes error handling and event logging modules
  • We configure Lograge for request logging
  • A Rack middleware is inserted to catch and log errors, including security violations (IP spoofing, CSRF, blocked hosts, etc.)
  • Structured logging is set up for ActiveJob, Sidekiq, Shrine, etc.
  • Rails config.filter_parameters are merged into LogStruct's filters and then cleared (to avoid double filtering). Configure sensitive keys via LogStruct.config.filters.
  • When RAILS_LOG_TO_STDOUT is set, we log to STDOUT only. Otherwise, we log to STDOUT by default without adding a file appender to avoid duplicate logs.

Documentation

Please see the documentation for more details. (All code examples are type-checked and tested, and it's harder to keep a README up to date.)

License

This project is licensed under the MIT License. See the LICENSE file for details.