mirror of
https://github.com/rails/rails.git
synced 2022-11-09 12:12:34 -05:00
96 lines
3.6 KiB
Text
96 lines
3.6 KiB
Text
h2. Active Support Instrumentation
|
|
|
|
Active Support is a part of core Rails that provides Ruby language extensions, utilities and other things. One of the things it includes is an instrumentation API that can be used inside an application to measure certain actions that occur within Ruby code, such as that inside a Rails application or the framework itself. It is not limited to Rails, however. It can be used independently in other Ruby scripts if it is so desired.
|
|
|
|
In this guide, you will learn how to use the instrumentation API inside of ActiveSupport to measure events inside of Rails and other Ruby code. We cover:
|
|
|
|
* What instrumentation can provide
|
|
* The hooks inside the Rails framework for instrumentation
|
|
* Adding a subscriber to a hook
|
|
* Building a custom instrumentation implementation
|
|
|
|
endprologue.
|
|
|
|
h3. Introduction to instrumentation
|
|
|
|
The instrumentation API provided by ActiveSupport allows developers to provide hooks which other developers may hook into. There are several of these within the Rails framework, as described below in <TODO: link to section detailing each hook point>. With this API, developers can choose to be notified when certain events occur inside their application or another piece of Ruby code.
|
|
|
|
For example, there is a hook provided within Active Record that is called every time Active Record uses a SQL query on a database. This hook could be *subscribed* to, and used to track the number of queries during a certain action. There's another hook around the processing of an action of a controller. This could be used, for instance, to track how long a specific action has taken.
|
|
|
|
You are even able to create your own events inside your application which you can later subscribe to.
|
|
|
|
h3. Rails framework hooks
|
|
|
|
Within the Ruby on Rails framework, there are a number of hooks provided for common events. These are detailed below.
|
|
|
|
h4. Action Mailer
|
|
|
|
h5. receive.action_mailer
|
|
|
|
This hook is called when the +receive+ method of an +ActionMailer::Base+ class is called:
|
|
|
|
<ruby>
|
|
class Mailer < ActionMailer::Base
|
|
def receive(mail)
|
|
|
|
end
|
|
end
|
|
</ruby>
|
|
|
|
The payload for this event has the following parameters related to the incoming email:
|
|
|
|
|_.Key |_.Value|
|
|
|mailer |Name of the mailer class|
|
|
|message_id |ID of the message, generated by the Mail gem|
|
|
|subject |Subject of the mail|
|
|
|to |To address(es) of the mail|
|
|
|from |From address of the mail|
|
|
|bcc |BCC addresses of the mail|
|
|
|cc |CC addresses of the mail|
|
|
|date |Date of the mail|
|
|
|mail |The encoded form of the mail|
|
|
|
|
h5. deliver.action_mailer
|
|
|
|
This hook is called when the +deliver+ method is called on a +Mail::Message+ object. This is due to a hook inserted by Action Mailer, rather than a specific feature of the Mail gem itself.
|
|
|
|
The payload for this event has the following parameters related to the outgoing email:
|
|
|
|
|_.Key |_.Value|
|
|
|mailer |Name of the mailer class|
|
|
|message_id |ID of the message, generated by the Mail gem|
|
|
|subject |Subject of the mail|
|
|
|to |To address(es) of the mail|
|
|
|from |From address of the mail|
|
|
|bcc |BCC addresses of the mail|
|
|
|cc |CC addresses of the mail|
|
|
|date |Date of the mail|
|
|
|mail |The encoded form of the mail|
|
|
|
|
|
|
h4. Action Controller
|
|
|
|
h5. write_fragment.action_controller
|
|
|
|
h5. read_fragment.action_controller
|
|
|
|
h5. exist_fragment?.action_controller
|
|
|
|
h5. expire_fragment.action_controller
|
|
|
|
h5. write_page.action_controller
|
|
|
|
h5. expire_page.action_controller
|
|
|
|
h4. Action View
|
|
|
|
h4. Active Record
|
|
|
|
h4. Active Resource
|
|
|
|
h4. Active Support
|
|
|
|
h3. Subscribing to an event
|
|
|
|
h3. Creating custom events
|
|
|