Path: | README.md |
Last Update: | Thu Apr 07 08:53:54 +0000 2016 |
# rack-mini-profiler
[](https://codeclimate.com/github/MiniProfiler/rack-mini-profiler) [](https://travis-ci.org/MiniProfiler/rack-mini-profiler)
Middleware that displays speed badge for every html page. Designed to work both in production and in development.
#### Features
#### Learn more
## rack-mini-profiler needs your help
We have decided to restructure our repository so there is a central UI repo and the various language implementation have their own.
**WE NEED HELP.**
If you feel like taking on any of this start an issue and update us on your progress.
## Installation
Install/add to Gemfile
```ruby gem ‘rack-mini-profiler’ ```
NOTE: Be sure to require rack_mini_profiler below the `pg` and `mysql` gems in your Gemfile. rack_mini_profiler will identify these gems if they are loaded to insert instrumentation. If included too early no SQL will show up.
#### Rails
All you have to do is include the Gem and you‘re good to go in development. See notes below for use in production.
#### Rails and manual initialization
In case you need to make sure rack_mini_profiler initialized after all other gems. Or you want to execute some code before rack_mini_profiler required.
```ruby gem ‘rack-mini-profiler’, require: false ``` Note the `require: false` part - if omitted, it will cause the Railtie for the mini-profiler to be loaded outright, and an attempt to re-initialize it manually will raise an exception.
Then put initialize code in file like `config/initializers/rack_profiler.rb`
```ruby if Rails.env == ‘development‘
require 'rack-mini-profiler' # initialization is skipped so trigger it Rack::MiniProfilerRails.initialize!(Rails.application)
end ```
#### Rack Builder
```ruby require ‘rack-mini-profiler‘
home = lambda { |env|
[200, {'Content-Type' => 'text/html'}, ["<html><body>hello!</body></html>"]]
}
builder = Rack::Builder.new do
use Rack::MiniProfiler map('/') { run home }
end
run builder ```
#### Sinatra
```ruby require ‘rack-mini-profiler’ class MyApp < Sinatra::Base
use Rack::MiniProfiler
end ```
### Flamegraphs
To generate [flamegraphs](samsaffron.com/archive/2013/03/19/flame-graphs-in-ruby-miniprofiler):
Flamegraph generation is supported in MRI 2.0, 2.1, and 2.2 only.
## Access control in non-development environments
rack-mini-profiler is designed with production profiling in mind. To enable that just run `Rack::MiniProfiler.authorize_request` once you know a request is allowed to profile.
```ruby
# inside your ApplicationController before_action do if current_user && current_user.is_admin? Rack::MiniProfiler.authorize_request end end
```
## Configuration
Various aspects of rack-mini-profiler‘s behavior can be configured when your app boots. For example in a Rails app, this should be done in an initializer: **config/initializers/mini_profiler.rb**
### Caching behavior To fix some nasty bugs with rack-mini-profiler showing the wrong data, the middleware will remove headers relating to caching (Date & Etag on responses, If-Modified-Since & If-None-Match on requests). This probably won‘t ever break your application, but it can cause some unexpected behavior. For example, in a Rails app, calls to `stale?` will always return true.
To disable this behavior, use the following config setting:
```ruby # Do not let rack-mini-profiler disable caching Rack::MiniProfiler.config.disable_caching = false # defaults to true ```
### Storage
rack-mini-profiler stores its results so they can be shared later and aren‘t lost at the end of the request.
There are 4 storage options: `MemoryStore`, `RedisStore`, `MemcacheStore`, and `FileStore`.
`FileStore` is the default in Rails environments and will write files to `tmp/miniprofiler/*`. `MemoryStore` is the default otherwise.
```ruby # set MemoryStore Rack::MiniProfiler.config.storage = Rack::MiniProfiler::MemoryStore
# set RedisStore if Rails.env.production?
uri = URI.parse(ENV["REDIS_SERVER_URL"]) Rack::MiniProfiler.config.storage_options = { :host => uri.host, :port => uri.port, :password => uri.password } Rack::MiniProfiler.config.storage = Rack::MiniProfiler::RedisStore
end ```
`MemoryStore` stores results in a processes heap - something that does not work well in a multi process environment. `FileStore` stores results in the file system - something that may not work well in a multi machine environment. `RedisStore`/`MemcacheStore` work in multi process and multi machine environments (`RedisStore` only saves results for up to 24 hours so it won‘t continue to fill up Redis).
Additionally you may implement an `AbstractStore` for your own provider.
### User result segregation
MiniProfiler will attempt to keep all user results isolated, out-of-the-box the user provider uses the ip address:
```ruby Rack::MiniProfiler.config.user_provider = Proc.new{|env| Rack::Request.new(env).ip} ```
You can override (something that is very important in a multi-machine production setup):
```ruby Rack::MiniProfiler.config.user_provider = Proc.new{ |env| CurrentUser.get(env) } ```
The string this function returns should be unique for each user on the system (for anonymous you may need to fall back to ip address)
### Profiling specific methods
You can increase the granularity of profiling by measuring the performance of specific methods. Add methods of interest to an initializer.
```ruby Rails.application.config.to_prepare do
::Rack::MiniProfiler.profile_singleton_method(User, :non_admins) { |a| "executing all_non_admins" } ::Rack::MiniProfiler.profile_method(User, :favorite_post) { |a| "executing favorite_post" }
end ```
### Using in SPA applications
Single page applications built using Ember, Angular or other frameworks need some special care, as routes often change without a full page load.
On route transition always call:
``` window.MiniProfiler.pageTransition(); ```
This method will remove profiling information that was related to previous page and clear aggregate statistics.
### Configuration Options
You can set configuration options using the configuration accessor on `Rack::MiniProfiler`. For example:
```ruby Rack::MiniProfiler.config.position = ‘right’ Rack::MiniProfiler.config.start_hidden = true ``` The available configuration options are:
Option|Default|Description