Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 112 lines (73 sloc) 3.961 kb
4c22cf0 @arthurnn Use svg badge [skip ci]
arthurnn authored
1 # marginalia [![Build Status](https://travis-ci.org/basecamp/marginalia.svg?branch=master)](https://travis-ci.org/basecamp/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)
65b80d3 @nate00 README: Fix typo
nate00 authored
16 to automate identification of controllers and actions that are hotspots for slow queries.
da61252 @noahhl Readme tweaks
noahhl authored
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,
fe8d0c3 @arthurnn update readme [skip ci]
arthurnn authored
22 tested on Rails 2.3.5 through 4.1.x. 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
fe8d0c3 @arthurnn update readme [skip ci]
arthurnn authored
28 ### For Rails 3.x and 4.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
dd1193d @arthurnn space on readme [skip ci]
arthurnn authored
33 # config/application.rb
2cb6804 @noahhl Encourage explicitly loading the railtie
noahhl authored
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:
8a9d2f5 @noahhl Update readme to reflect ability to configure lines_to_ignore regexp
noahhl authored
91 * `:line` (for file and line number calling query). :line supports
b60ad22 @nragaz Fix typo in README
nragaz authored
92 a configuration by setting a regexp in `Marginalia::Comment.lines_to_ignore`
8a9d2f5 @noahhl Update readme to reflect ability to configure lines_to_ignore regexp
noahhl authored
93 to exclude parts of the stacktrace from inclusion in the line comment.
28cdf0e @klausmeyer Add new component `controller_with_namespace` (closes #40)
klausmeyer authored
94 * `:controller_with_namespace` to include the full classname (including namespace)
95 of the controller.
d2b51b7 @nate00 Add ActiveJob component
nate00 authored
96 * `:job` to include the classname of the ActiveJob being performed.
54814cc @noahhl Add support for :line query comment
noahhl authored
97
98 Pull requests for other included comment components are welcome.
ac478ea @noahhl Document customization
noahhl authored
99
cf59528 @qrush blurb about contributing
qrush authored
100 ## Contributing
101
102 Start by bundling and creating the test database:
103
104 bundle
9fc1974 @nate00 README: Update Contributing section adapters
nate00 authored
105 rake db:mysql:create
106 rake db:postgresql:create
cf59528 @qrush blurb about contributing
qrush authored
107
9fc1974 @nate00 README: Update Contributing section adapters
nate00 authored
108 Then, running `rake` will run the tests on all the database adapters (`mysql`, `mysql2`, `postgresql` and `sqlite`):
cf59528 @qrush blurb about contributing
qrush authored
109
110 rake
111
Something went wrong with that request. Please try again.