Wor-Prof¶ ↑
Wor-prof (Wprof
) is a gem for Ruby On Rails which its only purpose is to measure a RoR app's performance through a profile with different times of response. In order to accomplish that, Wprof
uses ActiveSupport::Notifications (available in Rails since v4.0.2) to capture every action from his controllers. However, there's more. when using httparty in your project, you can capture every done request to external services. Do you have one or two methods that would like to know how long they take to execute? With Wprof
you can find out.
Then, every data obtained can be reported in several ways, choose one from the Rails logger: database file, CSV text or go ahead and do a Post request wherever you want… Do it both synchronously or asynchronously.
Let's begin.¶ ↑
The first step is the gem install (of course) and the way to do it is well known. However, just in case, you'll find the steps to follow next.
Installation¶ ↑
Add the next line to the gemfile from your Rails application:
gem 'wor-prof'
execute:
$ bundle install
And then, execute:
$ rails generate wprof (or copy initializer by yourself)
That's it!! At server execution, WProf
immediately begins to work with default settings, so you won't need to configure anything if it matches with your needs, otherwise you can check Available Settings.
If you don't run wprof generator, you must be initialized Wprof. For do this, add the next line into any rails initializers
WProf::Configuration.initiate_wprof
We highest recommended execute "rails generate wprof"
Register Types and how they works.¶ ↑
As register types, Wprof
counts with the following.
-
Controllers: every request realized to Rails' App that is handled by a Controller. (this is a default setting and cannot be disabled)
-
HTTParty: every time an HTTParty method is involved.
-
Own methods: an array of methods can be defined to be captured.
Only "controllers" are automatically profiled by just adding the gem, every other one will need an extra configuration or operation.
HTTparty¶ ↑
HTTParty is a popular tool for Ruby that allows to easily make HTTP's requests. If you're not used to the gem I recommend you to read more information in its repository, right here!
In order to profile the requests made by HTTParty, you must include Wprof
right after Httparty. This is:
class FooClass include HTTParty include Wprof
What that does mean? Wprof
make a wrapper over every called method as class methods, waits for the response and captures some of the needed data to generate the profile. This is why you must include the module right after HTTParty… Otherwise, it would simply not work.
By default, WProf
defines the methods that are commonly used to generate a request (Get, Put, Delete, Post), however you can define or exclude some of that list. It's strongly recommended not to add HTTParty's methods without being completely certain that the result is what WProf
will try to capture (See 'captured Data' to know which are they)
Own methods¶ ↑
Sometimes it may result useful to know how much an specific method is taking to execute, to this end Wor-prof can help you out.
There are two steps to accomplish that.
-
Prepare an array of methods which you want to trace (check configuration section: “custom_methods”)
-
Include
WProf
to that method's class
Done, with this WProf
will be registering the execution time of said method every time is being called and then it will report it.
Available Configurations.¶ ↑
WProf
contains a list of default settings which can all be altered by others availables as user's preferences demands. In order to do that, create a file in 'config/initializers' (RailsApp.Root >> config >> initializers >> wprof.rb). Inside, you must define the following configuration:
WProf::Configuration.configure do |config| config.db_runtime = true config.reporter_type = 'FILE' end
In case of not correctly configuring an option or just skip it, the value would be default.
To avoid this configuration manually using the configuration generator with the command “rails generate wprof” (see generator section).
Following the complete list of available settings and their meaning.
config.db_runtime¶ ↑
Sets whether it shows or not the data “db_runtime” inside the report.
Possible values: true o false
Default: true
config.reporter_type¶ ↑
Sets report type, meaning, how to show the obtained data. There are currently 4 available types, see “Reports” section for more information.
Possible values: LOGGER, FILE, DATABASE, EXTERNAL
Default: LOGGER
config.csv_type¶ ↑
When the report is defined as a CSV file there are two ways of generate it. * MIX: generates one CSV file where every data captured by WProf
is saved. This file only contains 2 columns: in the first one is the field and in the second one the data. * SPLIT: Divides storage in three different files, one for each record type. This significantly improves reading since every field is held as the file's header and the data in rows is split by comma… As it should be, of course… Why mix then?, I don't know, it could be useful for someone!
Possible values: MIX, SPLIT. Default: SPLIT
config.async¶ ↑
Sets whether the report is being generated sinchronously or not. Take note: asynchronous mode requires extra steps, see “asynchronism” section for more information.
Possible values: false, true Default: false
config.httparty_methods_to_trace¶ ↑
HTTParty's method captured by WProf
. By default, more common ones are set and it's recommended not to modify. This being said, there's no problem in taking out some of the array, however take special care in adding HTTParty's methods which doesn't return an http request.
Possible values: what you want and need, must be an array of strings. Default: ['get', 'put', 'delete', 'post']
config.external_url¶ ↑
In case you configure reporter_type as External, you must indicate the URL which will receive the HTTP petition.
Possible values: any string that corresponds to an URL. Example: 'example-url/reporter' Default: nil
config.external_headers¶ ↑
To add a header to the http request (“external” report type), you must define it in this setting. This must be a HASH of RUBY, exactly as HTTParty expects (internally Wprof
uses HTTParty to send a request). An example would be:
config.external_headers = { headers: {'User-Agent' => 'Httparty'}}
Possible : Any valid hash, must respect primary key as “headers” (check example below) Default: nil
config.custom_methods¶ ↑
If you want to capture response times of an specific method inside a class, it's not enough including the module, you'll need to indicate WProf
exactly which is the one it has to capture. This list of methods must be contained in this option in a array of Ruby and it has to be strings. Example:
config.custom_methods = [ 'my_great_method' ]
Possible values: any method's name in string format, within an array. Default: nil
config.file_path¶ ↑
When “FILE” is used as an output, this option allows you to choose the files destination. This must be a valid route, as string, with reading permission for Rails and also be a folder. Example:
config.file_path = '/home/mcolombo/examplefolder'
Possible values: any string that correctly represents a PATH to a directory. Default: Rails.root is used, so, root is Rails application.
config.disable_wprof¶ ↑
Enable or Disable Wprof
when this single line.
Possible values: true or false. Default: false.
Generators.¶ ↑
WProf
has two Rails generators availables.
Configuration file Generator.¶ ↑
To begin to modify options from available settings, you must create a config file inside the 'config/initializers' (as mentioned in “available configurations” section). To avoid unnecessary steps and possible mistakes in the well known dangerous 'copy/paste', you can generate this file as a template with the following Rails command:
rails generate wprof
This generates a model of the configuration's file with all the available options seen in “available configurations” section. It's necessary for initializer Wprof
.
Data Model Generator¶ ↑
An available option to report captured information is the same database Rails uses, the problem is, this requires defining the model. This generator will create all of the migration files and the models for using this option without having to worry for anything else.
rails generate wprof_model
This will generate the migration files and the models (even controllers in case you want to handle them!) Remember: in order to models be available in the case you still must run the migration.
rails db:migrate
Captured Data.¶ ↑
Data captured and reported by WProf
vary depending on which record they come, although, all of them share some base data.
Base data (common to all)¶ ↑
-
transaction_id: unique identifier for each transaction. This field is vital due to HTTParty's records and methods share this same identifier with the request that triggered this execution, allowing a complete execution trace of each one of them.
-
total_time: Total execution time registered (in milliseconds).
-
start_dt: Date and time field when register began.
-
end_dt: Date and time field when register ended.
Unique for the controller.¶ ↑
-
code: Response code sensed by the controller (Status), eg. 200, 404, etc.
-
controller: Controller that handled the request.
-
url: Endpoint that received the petition.
-
db_runtime: total time when it was absorbed by the database (included in total_time).
Unique for the services (Httparty).¶ ↑
-
code: Response code received (Status), eg. 200, 404, etc.
-
service_hostname: Hostname of service.
-
request_uri: Uri of endpoint.
Unique for services (Httparty).¶ ↑
-
method: measured method's name.
Reports.¶ ↑
Destination of the data, once is captured and processed, varies in order of user’s preferences Wor-Prof offers the following destinations for the information: * LOGGER: Uses Rails.logger to show the information. * FILE: Saves the info in one or several text files, split by comma (csv) * DATABASE: Saves obtained data in the same database used by Rails (requires model preparation, see generator/s of data model) * EXTERNAL: Does a POST petition with the data sended in the body in a JSON format (requires additional configuration)
“Logger” as well as “File” don’t need additional configuration to work, however “Database” and “External” require some previous step.
Database Reporter¶ ↑
For DATABASE is necessary to generate a schema that allows information storage. To accomplish this, we provide a generator, however, if you want to manually generate WProf
you need the following models (Migration files are exposed).
Modelo: WprofController
“` ruby class CreateWprofControllers < ActiveRecord::Migration def change create_table :wprof_controllers do |t| t.string :transaction_id t.float :total_time t.datetime :start_dt t.datetime :end_dt t.integer :code t.string :controller t.string :url t.float :db_runtime
t.timestamps end add_index :wprof_controllers, :transaction_id add_index :wprof_controllers, :code add_index :wprof_controllers, :url
end end
> Modelo: WprofService
ruby class CreateWprofServices < ActiveRecord::Migration def change create_table :wprof_services do |t| t.string :transaction_id t.float :total_time t.datetime :start_dt t.datetime :end_dt t.integer :code t.string :service_hostname t.string :request_uri
t.timestamps end add_index :wprof_services, :transaction_id add_index :wprof_services, :code add_index :wprof_services, :service_hostname add_index :wprof_services, :request_uri
end end
> Modelo: WprofMethod
ruby class CreateWprofMethods < ActiveRecord::Migration def change create_table :wprof_methods do |t| t.string :transaction_id t.float :total_time t.datetime :start_dt t.datetime :end_dt t.string :method
t.timestamps end add_index :wprof_methods, :transaction_id add_index :wprof_methods, :method
end end
### External Request Reporter. An option is sending data by HTTP wherever you want. Data obtained by Wprof will be sended in the body as JSON format. In order for this to work well it’s **necessary to configure destination’s URL**. Petition generated is POST and, when needed, you can configure the necessary HEADERS. If the URL is not configured, petition won’t be sended. The options to be set are: external_url and external_headers. See Configurations section for more information. --- ## Asynchronism. WProf by default reports all the information **synchronous**, although it’s possible to configure the tool in order to do this process **asynchronous**. To achieve this, you must first activate the option through config field "config.async = true", however this is not enough. For all of the report be made asynchronous, you must have functional and operational **Sidekiq**, since WProf uses it to that purpose. If you’re not familiar with the tool, you could give it a look to its [repository by clicking here!.](https://github.com/mperham/sidekiq). --- ## Handled errors. Any error among the capture and report of the information **MUSTN’T** interrupt the normal functioning of your Rails application. If this is the case, please report it. During the execution, could show up two errors in application’s logger.
WProf
ERROR when try parsing service response:“` This error may appear if HTTParty wouldn’t be able to capture some data.
error was raised when WProf tried to send data to reporter:
This is the most common error and it will appear if the data sending to the selected destination (meaning Logger, Database, File o External) has failed.