Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Newer
Older
100644 106 lines (67 sloc) 3.544 kB
3b39438 @qrush right this wrong
qrush authored
1 # marginalia [![Build Status](https://secure.travis-ci.org/37signals/marginalia.png?branch=master)](http://travis-ci.org/37signals/marginalia)
941ef57 @qrush split out readme, license
qrush authored
2
da61252 @noahhl Readme tweaks
noahhl authored
3 Attach comments to your ActiveRecord queries. By default, it adds the application, controller, and action names as a
4 comment at the end of each query.
941ef57 @qrush split out readme, license
qrush authored
5
da61252 @noahhl Readme tweaks
noahhl authored
6 This helps when searching log files for queries, and seeing where slow queries came from.
941ef57 @qrush split out readme, license
qrush authored
7
10b4932 @qrush more blurbs about configuration
qrush authored
8 For example, once enabled, your logs will look like:
941ef57 @qrush split out readme, license
qrush authored
9
10 Account Load (0.3ms) SELECT `accounts`.* FROM `accounts`
11 WHERE `accounts`.`queenbee_id` = 1234567890
12 LIMIT 1
13 /*application:BCX,controller:project_imports,action:show*/
14
96979e4 @noahhl Fix grammar in readme, closes issue 1 (thanks to KL-7)
noahhl authored
15 You can also use these query comments along with a tool like [pt-query-digest](http://www.percona.com/doc/percona-toolkit/2.1/pt-query-digest.html#query-reviews)
da61252 @noahhl Readme tweaks
noahhl authored
16 to automate identification of controllers and actions that are hotspots forslow queries.
17
18 This gem was created at 37signals. You can read more about how we use it [on
19 our blog](http://37signals.com/svn/posts/3130-tech-note-mysql-query-comments-in-rails).
20
eb92bfa @noahhl Prefer running tests on all adapters by default
noahhl authored
21 This has been tested and used in production with both the mysql and mysql2 gems,
b4d340f @noahhl Release 1.0.3 with postgres support, update README
noahhl authored
22 tested on Rails 2.3.5 through 3.2-stable. It has also been tested for sqlite3 and postgres.
160f14c @noahhl Add travis-ci build status to readme, fix typo
noahhl authored
23
3b39438 @qrush right this wrong
qrush authored
24 Patches are welcome for other database adapters.
eb92bfa @noahhl Prefer running tests on all adapters by default
noahhl authored
25
da61252 @noahhl Readme tweaks
noahhl authored
26 ## Installation
941ef57 @qrush split out readme, license
qrush authored
27
1dc8d5a @noahhl readme formatting
noahhl authored
28 ### For Rails 3.x:
941ef57 @qrush split out readme, license
qrush authored
29
2cb6804 @noahhl Encourage explicitly loading the railtie
noahhl authored
30 # Gemfile
d6db872 @noahhl Rename to marginalia
noahhl authored
31 gem 'marginalia'
2cb6804 @noahhl Encourage explicitly loading the railtie
noahhl authored
32
33 #config/application.rb
34 require 'marginalia/railtie'
941ef57 @qrush split out readme, license
qrush authored
35
36
1dc8d5a @noahhl readme formatting
noahhl authored
37 ### For Rails 2.x:
941ef57 @qrush split out readme, license
qrush authored
38
da61252 @noahhl Readme tweaks
noahhl authored
39 If using cached externals, add to your `config/externals.yml` file.
40
41 Or, if your prefer using `config.gem`, you can use:
42
d6db872 @noahhl Rename to marginalia
noahhl authored
43 config.gem 'marginalia'
941ef57 @qrush split out readme, license
qrush authored
44
da61252 @noahhl Readme tweaks
noahhl authored
45 Finally, if bundled, you'll need to manually run the initialization step in an
46 initializer, e.g.:
47
48 # Gemfile
d6db872 @noahhl Rename to marginalia
noahhl authored
49 gem 'marginalia', :require => false
da61252 @noahhl Readme tweaks
noahhl authored
50
d6db872 @noahhl Rename to marginalia
noahhl authored
51 #config/initializers/marginalia.rb
52 require 'marginalia'
53 Marginalia::Railtie.insert
da61252 @noahhl Readme tweaks
noahhl authored
54
1dc8d5a @noahhl readme formatting
noahhl authored
55 ### Customization
d6db872 @noahhl Rename to marginalia
noahhl authored
56 Optionally, you can set the application name shown in the log like so in an initializer (e.g. `config/initializers/marginalia.rb`):
10b4932 @qrush more blurbs about configuration
qrush authored
57
d6db872 @noahhl Rename to marginalia
noahhl authored
58 Marginalia.application_name = "BCX"
10b4932 @qrush more blurbs about configuration
qrush authored
59
da61252 @noahhl Readme tweaks
noahhl authored
60 For Rails 3 applications, the name will default to your Rails application name.
61 For Rails 2 applications, "rails" is used as the default application name.
62
ac478ea @noahhl Document customization
noahhl authored
63 You can also configure the components of the comment that will be appended,
64 by setting `Marginalia::Comment.components`. By default, this is set to:
65
66 Marginalia::Comment.components = [:application, :controller, :action]
67
68 Which results in a comment of
69 `application:#{application_name},controller:#{controller.name},action:#{action_name}`.
70
71 You can re-order or remove these components. You can also add additional
72 comment components of your desire by defining new module methods for
73 `Marginalia::Comment` which return a string. For example:
74
75 module Marginalia
76 module Comment
77 def self.mycommentcomponent
78 "TEST"
79 end
80 end
81 end
82
83 Marginalia::Comment.components = [:application, :mycommentcomponent]
84
85 Which will result in a comment like
86 `application:#{application_name},mycommentcomponent:TEST`
87 The calling controller is available to these methods via `@controller`.
88
89 Marginalia ships with `:application`, `:controller`, and `:action` enabled by
54814cc @noahhl Add support for :line query comment
noahhl authored
90 default. In addition, implementation is provided for:
91 * `:line` (for file and line number calling query)
92
93 Pull requests for other included comment components are welcome.
ac478ea @noahhl Document customization
noahhl authored
94
cf59528 @qrush blurb about contributing
qrush authored
95 ## Contributing
96
97 Start by bundling and creating the test database:
98
99 bundle
100 rake db:create
101
eb92bfa @noahhl Prefer running tests on all adapters by default
noahhl authored
102 Then, running `rake` will run the tests on both the `mysql` and `mysql2` adapters:
cf59528 @qrush blurb about contributing
qrush authored
103
104 rake
105
Something went wrong with that request. Please try again.