Zero-config structured logging for Ruby on Rails
LogStruct adds typed JSON logs to Ruby on Rails apps, and filters sensitive data out of them, which helps you meet SOC 2's logging requirements. Add the gem to your Gemfile, and in production your app writes JSON lines that are easy to search, filter, and turn into dashboards. To see them in development, start your server with LOGSTRUCT_ENABLED=true.
Installation
Enable JSON structured logging for your application:
1. Add to your Gemfile
gem "logstruct"2. Bundle install
bundle installMonitoring and Dashboards
Structured JSON logs are easy to parse, so you can quickly set up metrics, alerts, and dashboards.
Loading visualization examples...
Features
Type-safe with Sorbet
Every built-in log line is a Sorbet struct. A field with the wrong type raises in development and test, and is reported in production.
Filtering and Scrubbing
Values under sensitive keys (passwords, tokens, API keys) are replaced, and emails (hashed), card numbers, phone numbers and SSNs are scrubbed from strings. IP and MAC address scrubbing is opt-in.
Integrations
Structured lines for requests (Lograge), ActiveJob, ActionMailer, Sidekiq, GoodJob, Puma, ActiveStorage, Shrine, CarrierWave and more. (Open a PR to add support for your favorite gem!)
Error Reporting
Choose whether each kind of error is raised, logged or reported. Reports go to Sentry, Bugsnag, Rollbar, Honeybadger or your own reporter.
Cloud-Ready
Works with AWS CloudWatch, Datadog, Grafana and other services that parse JSON logs. A Terraform provider checks the source and event names in your CloudWatch metric filters when you plan.
Request and Job Context
Every line logged during a request has its request ID. Tags from logger.tagged and config.log_tags are written in each line, and Sidekiq lines include the job's context.
Project Status
Build Status
CI/CD pipeline status: Loading...
Code Coverage
Tests cover 92.84% of the codebase
Type Coverage
LogStruct is 100% typed with Sorbet
RubyGems
Latest version: 0.2.1
Frequently Asked Questions
Do I need to use Sorbet?
No. Log with the regular Rails logger as usual. sorbet-runtime is a dependency, and if your app has its own Sorbet signatures, LogStruct handles their runtime type errors too, as type_checking_errors says (raise in development and test, log and report in production).
Is LogStruct free?
Yes, LogStruct is completely free and open source under the MIT license. Pull requests and contributions are welcome!
Why was LogStruct built?
DocSpring was originally using the lograge gem to format our request logs as JSON. We realized that we had a lot of other plain text logs that would be useful for CloudWatch metrics and dashboards. We wrote much of this code in our own app before deciding to extract it and release it as a gem. (It was also a great opportunity to learn more about Sorbet.)
What about other logging gems?
Several other gems provide structured logging for Rails apps, including Rails Semantic Logger, Lograge, Logstasher, and Logcraft. LogStruct focuses on filtering and scrubbing, structured error handling, and typed lines for each integration. See the comparison page for a detailed breakdown.