Make framework log subscribers to consume structured events

[gmcgibbon]

Motivation / Background

This Pull Request has been created because framework log subscribers currently consume notification events. Since the introduction of structured event subscribers in #55690, this doesn't necessarily need to happen anymore. We can instead use the structured event subscribers to produce logs instead for environments like development.

Detail

This Pull Request adds a base class for framework structured event log subscribers, and changes current log subscribers (private API since #55755) to consume structured events instead of notification events.

Checklist

Before submitting the PR make sure the following are checked:

• This Pull Request is related to one change. Unrelated changes should be opened in separate PRs.
• Commit message has a detailed description of what changed and why. If this PR fixes a related issue include it in the commit message. Ex: [Fix #issue-number]
• Tests are added or updated if you fix a bug or add a feature.
• CHANGELOG files are updated for the changed libraries if there is a behavior change or additional feature. Minor bug fixes and documentation changes should not be included.

[rafaelfranca]

Shiped #55904 before this one.

[zzak]

Isn't this breaking API change?

Since mattr_accessor are not picked up by RDoc, it is not visible in the public API docs however:
https://api.rubyonrails.org/classes/ActiveSupport/LogSubscriber.html

I did find one case of it in the wild, when running rails_semantic_logger tests against this branch:
amazing-print/amazing_print@main...zzak:amazing_print:rails-log-subscribers-colorize_logging

[gmcgibbon]

I thought it wasn't because it wasn't visible in docs. I would opt to have private API users update their own code, but I'm open to suggestions. If someone else agrees, we can add deprecations, but I don't think it is necessary.

[zzak]

I thought it wasn't because it wasn't visible in docs.

This is the general rule, yes so I think we're fine. The public API which is documented is through configuration:
https://edgeapi.rubyonrails.org/classes/Rails/Application/Configuration.html#method-i-colorize_logging

But I think that using mattr_* is intentionally meant to be private is false, that is just a side-effect of missing RDoc support.

[jeromedalbert]

This breaks Rails projects that use Awesome Print (or its maintained fork Amazing Print):

# lib/amazing_print/ext/active_support.rb
if defined?(ActiveSupport::LogSubscriber)
  AwesomePrint.force_colors! ActiveSupport::LogSubscriber.colorize_logging
end

Source: https://github.com/awesome-print/awesome_print/blob/8a7ff0aabacbebf694c3e27242809219a96d5a3b/lib/awesome_print/ext/active_support.rb#L44-L46

While using the public ActiveSupport.colorize_logging API would be a quick fix for Amazing Print (I recently contributed there and the maintainers are responsive), Awesome Print has been stale for years and many projects probably still depend on it. So upgrading to Rails 8.2+ would mean requiring companies to switch to amazing_print.

I understand this is possibly a private API, but are we okay with proceeding as is? Or is this possibly private API used be enough "high profile" gems to warrant a deprecation or a mention in the upgrade guides?

The most "high profiles" result I see from https://sourcegraph.com/search?q=context:global+%22ActiveSupport::LogSubscriber.colorize_logging%22&patternType=keyword&sm=0 are awesome print, amazing print, a profiler in the gitlab repo.

[zzak]

Tried this branch with rails_semantic_logger tests and it seems they will have to change how they swap out subscribers, like:
reidmorrison/rails_semantic_logger@master...zzak:rails_semantic_logger:swap-structured_event_subscribers

If you unsubscribe from these do other things break, either intentionally or unintentionally. 🤔

Lograge also does something like this:
https://github.com/roidrage/lograge/blob/27066cd75d449cb91ed79b18c4271d62a76c9839/lib/lograge.rb#L109-L127

Not sure how actionable it is, just came to me when thinking about this and thought it might be valuable context. 🙏

[gmcgibbon]

rails/actionview/lib/action_view/log_subscriber.rb

Line 6 in 844fe07

class LogSubscriber < ActiveSupport::LogSubscriber # :nodoc:

Most log subscribers are nodoc. I made all log subscribers nodoc in #55755, and if that is released in 8.1, and this in 8.2, that should be sufficient IMO.

[gmcgibbon]

I'll backport the more recent structured logging additions here to 8.1 stable so that we can include that in the full release (or another RC). Looks like the pressure is off to get this out before 8.1, and its a pretty big change, so I'll leave it open for a few more days for feedback.

[chaadow]

Since there is a CHANGELOG entry for this class, should we add some rdoc documentation?

[gmcgibbon]

Yes, I'll put this on my TODO list, but PRs are welcome in the meantime!