README.md

Path: README.md
Last Update: Thu Apr 07 08:53:54 +0000 2016

# rack-mini-profiler

[![Code Climate](codeclimate.com/github/MiniProfiler/rack-mini-profiler/badges/gpa.svg)](https://codeclimate.com/github/MiniProfiler/rack-mini-profiler) [![Build Status](travis-ci.org/MiniProfiler/rack-mini-profiler.svg)](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

  • database profiling. Currently supports Mysql2, Postgres, Oracle (oracle_enhanced ~> 1.5.0) and Mongoid3 (with fallback support to ActiveRecord)

#### 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

[Validate]