From 2784e6433bd8590a51e3dacc5fcc01e9dcdcea26 Mon Sep 17 00:00:00 2001 From: adman65 Date: Thu, 15 Mar 2012 10:08:16 +0100 Subject: [PATCH] [ci skip] Add examples to instrumentation guide --- .../active_support_instrumentation.textile | 366 ++++++++++++++++-- 1 file changed, 323 insertions(+), 43 deletions(-) diff --git a/railties/guides/source/active_support_instrumentation.textile b/railties/guides/source/active_support_instrumentation.textile index 8e2866dfc3..18500949e0 100644 --- a/railties/guides/source/active_support_instrumentation.textile +++ b/railties/guides/source/active_support_instrumentation.textile @@ -23,72 +23,352 @@ 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 +h3. ActionController -h5. receive.action_mailer +h4. write_fragment.action_controller -This hook is called when the +receive+ method of an +ActionMailer::Base+ class is called: +|_.Key |_.Value| +|+:key+ |The complete key| - class Mailer < ActionMailer::Base - def receive(mail) - - end - end +{ + :key => 'posts/1-dasboard-view' +} -The payload for this event has the following parameters related to the incoming email: +h4. read_fragment.action_controller -|_.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| +|_.Key |_.Value| +|+:key+ |The complete key| -h5. deliver.action_mailer + +{ + :key => 'posts/1-dasboard-view' +} + -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. +h4. expire_fragment.action_controller -The payload for this event has the following parameters related to the outgoing email: +|_.Key |_.Value| +|+:key+ |The complete key| -|_.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| + +{ + :key => 'posts/1-dasboard-view' +} + + +h4. exist_fragment?.action_controller + +|_.Key |_.Value| +|+:key+ |The complete key| + + +{ + :key => 'posts/1-dasboard-view' +} + + +h4. write_page.action_controller + +|_.Key |_.Value| +|+:path+ |The complete path| + + +{ + :path => '/users/1' +} + + +h4. expire_page.action_controller + +|_.Key |_.Value| +|+:path+ |The complete path| + + +{ + :path => '/users/1' +} + + +h4. start_processing.action_controller + +|_.Key |_.Value | +|+:controller+ |The controller name| +|+:action+ |The action| +|+:params+ |Hash of request parameters without any filtered parameter| +|+:format+ |html/js/json/xml etc| +|+:method+ |HTTP request verb| +|+:path+ |Request path| + + +{ + :controller => "PostsController", + :action => "new", + :params => { "action" => "new", "controller" => "posts" }, + :format => :html, + :method => "GET", + :path => "/posts/new" +} + + +h4. process_action.action_controller + +|_.Key |_.Value | +|+:controller+ |The controller name| +|+:action+ |The action| +|+:params+ |Hash of request parameters without any filtered parameter| +|+:format+ |html/js/json/xml etc| +|+:method+ |HTTP request verb| +|+:path+ |Request path| +|+:view_runtime+ |Amount spent in view in ms| + + +{ + :controller => "PostsController", + :action => "index", + :params => {"action" => "index", "controller" => "posts"}, + :format => :html, + :method => "GET", + :path => "/posts", + :status => 200, + :view_runtime => 46.848, + :db_runtime => 0.157 +} + + +h4. send_file.action_controller + +|_.Key |_.Value | +|+:path+ |Complete path to the file| + +INFO. Additional keys may be added by the caller. + +h4. send_data.action_controller + ++ActionController+ does not had any specific information to the payload. All options are passed through to the payload. + +h4. redirect_to.action_controller + +|_.Key |_.Value | +|+:status+ |HTTP response code| +|+:location+ |URL to redirect to| + + +{ + :status => 302, + :location => "http://localhost:3000/posts/new" +} + + +h4. halted_callback.action_controller + +|_.Key |_.Value | +|+:filter+ |Filter that halted the action| + + +{ + :filter => ":halting_filter" +} + + +h3. ActionView + +h4. render_template.action_view + +|_.Key |_.Value | +|+:identifier+ |Full path to template| +|+:layout+ |Applicable layout| + + +{ + :identifier => "/Users/adam/projects/notifications/app/views/posts/index.html.erb", + :layout => "layouts/application" +} + + +h4. render_partial.action_view + +|_.Key |_.Value | +|+:identifier+ |Full path to template| + + +{ + :identifier => "/Users/adam/projects/notifications/app/views/posts/_form.html.erb", +} + + +h3. ActiveRecord + +h4. sql.active_record + +|_.Key |_.Value | +|+:sql+ |SQL statement| +|+:name+ |Name of the operation| +|+:object_id+ |+self.object_id+| + +INFO. The adapters will add their own data as well. + + +{ + :sql => "SELECT \"posts\".* FROM \"posts\" ", + :name => "Post Load", + :connection_id => 70307250813140, + :binds => [] +} + + +h4. identity.active_record + +|_.Key |_.Value | +|+:line+ |Primary Key of object in the identity map| +|+:name+ |Record's class| +|+:connection_id+ |+self.object_id+| + +h3. ActionMailer + +h4. receive.action_mailer + +|_.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| + + +{ + :mailer => "Notification", + :message_id => "4f5b5491f1774_181b23fc3d4434d38138e5@mba.local.mail", + :subject => "Rails Guides", + :to => ["users@rails.com", "ddh@rails.com"], + :from => ["me@rails.com"], + :date => Sat, 10 Mar 2012 14:18:09 +0100, + :mail=> "..." # ommitted for beverity +} + + +h4. deliver.action_mailer + +|_.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| + + +{ + :mailer => "Notification", + :message_id => "4f5b5491f1774_181b23fc3d4434d38138e5@mba.local.mail", + :subject => "Rails Guides", + :to => ["users@rails.com", "ddh@rails.com"], + :from => ["me@rails.com"], + :date => Sat, 10 Mar 2012 14:18:09 +0100, + :mail=> "..." # ommitted for beverity +} + + +h3. ActiveResource + +h4. request.active_resource + +|_.Key |_.Value| +|+:method+ |HTTP method| +|+:request_uri+ |Complete URI| +|+:result+ |HTTP response object| + +h3. ActiveSupport + +h4. cache_read.active_support + +|_.Key |_.Value| +|+:key+ |Key used in the store| +|+:hit+ |If this read is a hit| +|+:super_operation+ |:fetch is added when a read is used with +#fetch+| + +h4. cache_generate.active_support + +This event is only used when +#fetch+ is called with a block. + +|_.Key |_.Value| +|+:key+ |Key used in the store| + +INFO. Options passed to fetch will be merged with the payload when writing to the store + + +{ + :key => 'name-of-complicated-computation' +} + -h4. Action Controller +h4. cache_fetch_hit.active_support -h5. write_fragment.action_controller +This event is only used when +#fetch+ is called with a block. -h5. read_fragment.action_controller +|_.Key |_.Value| +|+:key+ |Key used in the store| -h5. exist_fragment?.action_controller +INFO. Options passed to fetch will be merged with the payload. -h5. expire_fragment.action_controller + +{ + :key => 'name-of-complicated-computation' +} + -h5. write_page.action_controller +h4. cache_write.active_support -h5. expire_page.action_controller +|_.Key |_.Value| +|+:key+ |Key used in the store| -h4. Action View +INFO. Cache stores my add their own keys -h4. Active Record + +{ + :key => 'name-of-complicated-computation' +} + -h4. Active Resource +h4. cache_delete.active_support -h4. Active Support +|_.Key |_.Value| +|+:key+ |Key used in the store| + + +{ + :key => 'name-of-complicated-computation' +} + + +h4. cache_exist?.active_support + +|_.Key |_.Value| +|+:key+ |Key used in the store| + + +{ + :key => 'name-of-complicated-computation' +} + + + +h3. Rails + +h4. deprecation.rails + +|_.Key |_.Value| +|+:message+ |The deprecation warning| +|+:callstack+ |Where the deprecation came from| h3. Subscribing to an event