Lograge: one clean line per request, with the timestamp left to you
An attempt to tame Rails' default policy to log everything.
At a glance
- What is it?
- roidrage/lograge replaces Rails' multi-line request logging with one key-value line and a nine-formatter output layer, but the default line carries no timestamp even though multi-server interleaving is the problem it names, the officially supported matrix still lists two dead MRI versions, and its own example config puts a user identifier on every request.
- Who is it for?
- Adopt it if you run more than one application server and want logs you can actually read, because the multi-line default it replaces is genuinely hostile to aggregation. Two things to configure before you rely on it.
- Can I use it commercially?
- Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository last received commits 1 day ago.
- What is it written in?
- Mainly Ruby, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on November 15, 2026, and from our analysis. They are not legal advice.
Star history
- roidrage/lograge3,572 ★ · +0
| Repository | 2026-09-24 | 2026-11-15 |
|---|---|---|
| roidrage/lograge | 3.6k | 3.6k |
0 Stars in the last 52 days, measured from the daily GitHub snapshot. Compare with other projects
Editorial analysis
The default log line has no timestamp, which is the one field multi-server interleaving needs
The pitch is stated in the second paragraph. Rails' default logging is great in development and terrible in production, and specifically it is unreadable in the context of running multiple processes and servers.
The replacement is one line of key-value pairs. The example given is:
method=GET path=/ format=json controller=HomeController action=index status=200 duration=79.0 view=78.8 db=0.0Method, path, format, controller, action, status, total duration, view time, database time. Nine fields, one line, easy to read at a glance.
And then the sentence that undercuts it: the line does not include any timestamp by default, and it assumes you use a proper log formatter instead.
So for the single-server case that is a fine default, and the README even shows how to add one with a lambda returning the current time. But the problem the gem names first is multiple servers. A log line with no timestamp cannot be interleaved with lines from other machines: you cannot tell whether a line emitted by host B at 14:28:14.2 came before or after one emitted by host A at 14:28:14.9. A logger formatter or collection system can add a timestamp outside the Lograge message; verify which clock and timestamp your logging pipeline uses before relying on event ordering.
The contrast with what it replaces is sharp. The Rails default it shows as the bad example opens with a timestamp on the first line of every request. So the single most useful field in the old format is the one the new format drops by default.
This is a design decision rather than a bug, and the README is upfront about it. It just means the gem's default is only correct once you have configured something else, in a world where the stated motivation is many servers.
The officially supported matrix still lists MRI 2.6 and 2.7
The support section is careful in a way that is worth reading before criticising it. It says the versions listed are verified green in continuous integration and are officially supported by this release, that older releases should also work but are not actively tested, and that the two unreleased development branches are exercised on a best-effort basis to catch incompatibilities early and are allowed to fail and are not yet officially supported.
It also links both the Rails list and the Ruby list to a public end-of-life tracker rather than to the projects' own pages. So the reader can see, in one click, which of the listed versions have stopped receiving support.
Now count what is in the list. Eight Rails versions, from 5.2 through 8.1 with nothing skipped in between. Eight MRI versions, from 2.6 through 4.0. Two JRuby releases and one TruffleRuby release.
MRI 2.6 stopped receiving fixes in early 2022 and 2.7 in early 2023, and Rails 5.2 has been unsupported for longer than that. A green compatibility test does not mean an upstream Ruby release still receives security fixes; check runtime and operating-system support separately.
Supporting them is not wrong. A logging gem is infrastructure, and infrastructure that keeps working on an old runtime is valuable precisely when you cannot upgrade the application. The point is only that the word officially and the phrase verified green describe a test matrix, not a support commitment, and the README is honest enough about that distinction that a reader could work it out.
That is better disclosure than most gem readmes manage, and the gemfiles directory at the top level of the repository is presumably how the matrix is tested: one gemfile per version, one job per gemfile.
The README still opens by calling itself a work in progress
The third paragraph of this readme says the project is a work in progress, that constructive feedback and criticism are appreciated, and that the main goal is to improve Rails' logging and to show people they do not need to stick with the defaults.
It is written in the first person throughout, including the phrase that Rails' default logging pretty much renders logs useless to me.
That framing sits directly above a compatibility matrix that lists eight Rails versions ending at the current one, eight MRI versions ending at the current one, two JRuby releases and a TruffleRuby release, with a continuous integration badge at the top of the page and a last commit five days before this material was fetched. The engineering underneath is current and carefully maintained. The self-description is a decade old.
There is a clue that the two halves have drifted apart. The prose refers to the project in the first person throughout, as though there is one author. The contributing guide, the code of conduct and the pull request template are all in the repository. Twenty-odd formatters and a compatibility matrix are the work of a group.
So the paragraph is doing two jobs at once, and neither is malicious. It is a founder's note about intent, left in place while the project became something with a wider contributor base. The cost is small and concrete: a reader deciding whether to adopt this in production sees work in progress, and reasonably discounts a library whose maintenance signals elsewhere say otherwise.
The fix is two sentences, and it is the same fix this readme applies to the compatibility matrix: update it when the thing it describes changes.
The gem patches your base controller class and the setting naming it is a bare string
How this gem works is not documented in so many words on this page. What is documented is a setting called base controller class, and the fact that you must set it if you use API-only mode, and that you must pass an array if your application has more than one base controller class.
The word in the README for the mechanism is that lograge will patch it. So the integration model is: the gem opens your controller base class and wraps its instrumentation, and the base controller setting is how you tell it which class to open.
That makes the setting load-bearing in a way its type does not suggest. It is a string, or an array of strings. There is no validation described, no error described, and no fallback described. If a class name is wrong or a base controller is omitted, verify startup behavior and whether requests through that controller produce the expected log lines; the README does not specify every failure mode.
Compare that with the ignore settings later on the page, which are also strings, listing controller and action pairs. Same problem, wider blast radius, because a typo there silently keeps logging something you asked it to drop, and an incorrect base controller setting can leave the intended requests uninstrumented or cause a configuration error.
None of this is unusual for a Rails engine of this vintage. Configuration that patches framework internals is inherently stringly typed. But the README does describe the failure behaviour of the other settings in passing, and not this one, which is the setting most likely to be got wrong.
The recommended configuration puts a user identifier in every request log line
There are two documented ways to add your own data, and both are shown as conveniences.
The first is to override a payload hook in your application controller, call super, and add whatever you want to the payload. Then a lambda reads that payload when it builds the log line.
The second is described as an alternative that gives you direct access to controller methods, with two named examples, and it comes with the note that the resulting hash is merged into the log data automatically. The example hash has two keys in it: the request host, and the identifier of the current user, obtained from the current user object with a null-safe call.
That second example is the interesting one, because it puts an authenticated user's identifier on every single request line by default.
Request logs are the most widely shipped data in most Rails deployments. They go to whatever aggregator you use, they are frequently retained for months, and they are frequently readable by people whose job is not to see your user base. Adding a user identifier to each line converts an infrastructure log into a per-subject activity record, and it does so with a copy-and-paste snippet that the README recommends.
None of this means you should not do it. Per-user request logs are genuinely useful, and correlating a slow request with a specific account is a real debugging need. But the snippet has no note attached to it, and the surrounding text is about convenience rather than data governance.
Worth knowing too that the hook name is an internal instrumentation method rather than part of Rails' documented public surface, so the first approach ties your controller to a private method name.
Nine formatters, two named after products, one of them pinned to a second major version
The formatter list is the longest single block in the readme and it is worth reading as a compatibility statement rather than as a feature list.
There are nine. One is the default, a key-value formatter, and there is a deep variant of it. One emits JSON. One emits a tab-separated format. One returns a hash object instead of a string. One is described as line based. One is the Logstash formatter, and using it requires a separate gem.
Two are named after commercial log products. One is a line format for a hosted logging service. The other is named for a specific major version of a log management product, with the major number in the class name itself.
That naming is the fragile part. A formatter class called after version two of somebody else's product encodes a promise about wire compatibility with a specific major release of a system you do not control. When the vendor moves to their own next major, the class name becomes a historical statement rather than a description, and the only way to find out whether it still works is to read their changelog.
The upside is real and worth stating: for most log aggregation systems, matching the ingest format is the whole integration problem, and a gem that ships the formats has removed a large amount of per-deployment work. Nine formats is more coverage than most alternatives offer.
The cost is that two of the nine are coupled to external products and one of those is coupled to a specific major version of one. That is two ninths of the output surface with a maintenance dependency the README does not flag.
The Logstash formatter needs a gem this one does not depend on
One of the nine formatters, the one for the Logstash format, has a note under it. Using it requires adding one additional gem to your application, and the note shows the line to add to the Gemfile.
So there is a formatter, listed among the nine without qualification, whose stated output format cannot be produced unless you install something else first. Nothing in the list marks which one it is; the requirement is a note below the block, phrased as if it were a footnote.
This is a small thing and it is the ordinary way a library grows: the Logstash event format comes from a particular event library, the dependency stays optional so that everyone else does not pay for it, and the documentation catches up later. The correct fix is one word in the list, marking which entries have requirements.
It is worth mentioning because the nine formatters are the feature most likely to be chosen on the basis of the list alone. Somebody picking a log destination picks the line that names their destination, copies the config, and only then discovers the extra line in the Gemfile. That is a two minute detour rather than a real problem, and it is entirely avoidable by annotating the list.
The same block also notes that the custom formatter path is open, which is the right escape hatch: if none of the nine fit, the readme's closing line is that you can manipulate the output yourself.
An example ignore_actions array contains a literal placeholder
Telling the gem to skip certain log lines is documented with two settings. One takes a list of controller and action pairs as strings. The other takes a lambda that receives the event and returns whether to skip it.
The example for the first one is an array of two strings. The first looks real: a controller name, a hash, an action name. The second reads as a controller class name with no namespace, a hash, and the words an action.
That second entry is a placeholder. It is what a template author writes to indicate where your own values go. But it appears inside a literal array, in a code block, formatted exactly like the real entry beside it, with no comment and no ellipsis marking it as a stand-in.
Copy that block and you have configured the gem to skip a controller and action that do not exist. Nothing breaks. Nothing warns. You have added a filter that matches nothing, which is indistinguishable at runtime from having added no filter at all.
The failure mode is the quiet kind. The setting exists to reduce log volume, so the symptom of getting it wrong is a log that is slightly larger than you expected, with no signal that one of your two filters is dead.
A comment on the second line, or writing the example with one entry instead of two, would remove the trap entirely. It is the kind of thing that survives in a readme for years because every reader substitutes their own values mentally and never notices the literal is there.
Editorial conclusion
Adopt it if you run more than one application server and want logs you can actually read, because the multi-line default it replaces is genuinely hostile to aggregation. Two things to configure before you rely on it. Ensure your logger or custom options add a timestamp, since the default Lograge message omits it. And read the ignore settings before you trust them, because the example array contains a literal placeholder that copies in as a filter matching nothing. If your deployment ships request logs to an aggregator, note that the recommended payload snippet adds an authenticated user identifier to every line.
Frequently asked questions
What does Lograge do to Rails request logging?
It replaces Rails' request logging entirely, reducing one request to a single key-value line carrying method, path, format, controller, action, status, total duration, view time and database time. The README says the syntax is modelled on the log output of a commercial platform's router.
Does Lograge include a timestamp in its log output?
Not by default. The README says it assumes you use a proper log formatter instead, and shows how to add one with a custom options lambda that returns the current time.
Which Ruby and Rails versions does Lograge support?
Eight Rails versions from 5.2 to 8.1, and eight MRI versions from 2.6 to 4.0, plus two JRuby releases and one TruffleRuby release. Older releases should work but are not actively tested, and the two unreleased development branches are exercised on a best-effort basis and are allowed to fail.
How do I configure Lograge in a Rails API-only app?
Set the base controller class setting to the API controller class, or to an array if the application uses more than one base controller class. The gem patches the base controller class, so that setting is what tells it which class to patch.
Can Lograge write JSON logs?
Yes, through the JSON and Logstash formatters. The Logstash formatter additionally needs a separate event gem added to your Gemfile, which is not a dependency of Lograge itself.
How do I add my own data to Lograge's log lines?
Two ways: override the payload hook in your application controller and call super, or use the custom payload hook, which receives the controller directly and whose hash is merged in automatically. Either feeds the custom options lambda that builds the line.
Official sources
Add this badge to your README
If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.
[](https://hysenlabs.com/projects/roidrage-lograge)Star history chart for your README
[](https://hysenlabs.com/projects/roidrage-lograge)Was this useful?