marginalia
Attach comments to ActiveRecord SQL queries to trace their origin in Rails applications.
What is marginalia?
Marginalia is a Ruby gem that attaches contextual comments to ActiveRecord SQL queries in Rails applications. It helps developers trace queries back to their source by appending information like application name, controller, and action directly into the SQL. This is particularly useful for identifying slow queries in logs and performance hotspots.
Rails developers and teams who need to debug database performance issues, trace query origins in production logs, or automate slow query analysis with tools like pt-query-digest.
Developers choose Marginalia for its simplicity, configurability, and seamless integration with ActiveRecord. It provides a non-invasive way to add query tracing without modifying application logic, and it's battle-tested in production environments.
Overview
Attach comments to ActiveRecord's SQL queries
Use Cases
Best For
- Identifying slow ActiveRecord queries in Rails application logs
- Tracing SQL queries back to specific controllers and actions
- Automating performance analysis with query digest tools
- Debugging database performance hotspots in production
- Adding custom metadata to SQL queries for auditing
- Monitoring query origins in multi-tenant Rails applications
Not Ideal For
- Rails 7+ applications, as query logging is built-in via ActiveRecord::QueryLogs
- Applications heavily relying on prepared statements with dynamic metadata, due to potential resource exhaustion
- Teams needing real-time query monitoring without log parsing, as Marginalia relies on post-query inspection
Pros & Cons
Pros
Automatically attaches comments to ActiveRecord queries without invasive code changes, as shown in the default setup adding controller and action names.
Allows reordering and adding custom comment components like line numbers or hostname, detailed in the customization section with module method examples.
Tested with MySQL, PostgreSQL, and SQLite, and used in production, ensuring reliability across various database environments.
Designed to work with query digest tools like pt-query-digest, enabling automated identification of performance hotspots from logs.
Cons
Since Rails 7 includes ActiveRecord::QueryLogs, using Marginalia adds an unnecessary dependency for new projects, as noted in the README.
Using high-cardinality components like request_id can exhaust system resources by creating unique prepared statements, a caveat explicitly warned in the documentation.
Benefits are only realized through log parsing, which may not suit real-time debugging or applications where SQL logging is disabled for performance.
Frequently Asked Questions
Related Projects
deviseFlexible authentication solution for Rails with Warden.
spreeOpen Source eCommerce Platform for B2B, Marketplace, and Enterprise. REST API, TypeScript SDK, and production-ready Next.js storefront. Self-host it. Own your stack. No vendor lock-in. Zero platform fees.
activeadminThe administration framework for Ruby on Rails applications.
CarrierwaveClassier solution for file uploads for Rails, Sinatra and other Ruby web frameworks
Found a gem we're missing?
Open-Awesome is built by the community, for the community. Submit a project, suggest an awesome list, or help improve the catalog on GitHub.