Skip to content
Newer
Older
100644 108 lines (71 sloc) 3.8 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'
941ef57 @qrush split out readme, license
qrush authored
32
1dc8d5a @noahhl readme formatting
noahhl authored
33 ### For Rails 2.x:
941ef57 @qrush split out readme, license
qrush authored
34
da61252 @noahhl Readme tweaks
noahhl authored
35 If using cached externals, add to your `config/externals.yml` file.
36
37 Or, if your prefer using `config.gem`, you can use:
38
d6db872 @noahhl Rename to marginalia
noahhl authored
39 config.gem 'marginalia'
941ef57 @qrush split out readme, license
qrush authored
40
da61252 @noahhl Readme tweaks
noahhl authored
41 Finally, if bundled, you'll need to manually run the initialization step in an
42 initializer, e.g.:
43
44 # Gemfile
d6db872 @noahhl Rename to marginalia
noahhl authored
45 gem 'marginalia', :require => false
da61252 @noahhl Readme tweaks
noahhl authored
46
d6db872 @noahhl Rename to marginalia
noahhl authored
47 #config/initializers/marginalia.rb
48 require 'marginalia'
49 Marginalia::Railtie.insert
da61252 @noahhl Readme tweaks
noahhl authored
50
1dc8d5a @noahhl readme formatting
noahhl authored
51 ### Customization
d6db872 @noahhl Rename to marginalia
noahhl authored
52 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
53
d6db872 @noahhl Rename to marginalia
noahhl authored
54 Marginalia.application_name = "BCX"
10b4932 @qrush more blurbs about configuration
qrush authored
55
da61252 @noahhl Readme tweaks
noahhl authored
56 For Rails 3 applications, the name will default to your Rails application name.
57 For Rails 2 applications, "rails" is used as the default application name.
58
ac478ea @noahhl Document customization
noahhl authored
59 You can also configure the components of the comment that will be appended,
60 by setting `Marginalia::Comment.components`. By default, this is set to:
61
62 Marginalia::Comment.components = [:application, :controller, :action]
63
64 Which results in a comment of
65 `application:#{application_name},controller:#{controller.name},action:#{action_name}`.
66
67 You can re-order or remove these components. You can also add additional
68 comment components of your desire by defining new module methods for
69 `Marginalia::Comment` which return a string. For example:
70
71 module Marginalia
72 module Comment
73 def self.mycommentcomponent
74 "TEST"
75 end
76 end
77 end
78
79 Marginalia::Comment.components = [:application, :mycommentcomponent]
80
81 Which will result in a comment like
82 `application:#{application_name},mycommentcomponent:TEST`
83 The calling controller is available to these methods via `@controller`.
84
85 Marginalia ships with `:application`, `:controller`, and `:action` enabled by
54814cc @noahhl Add support for :line query comment
noahhl authored
86 default. In addition, implementation is provided for:
8a9d2f5 @noahhl Update readme to reflect ability to configure lines_to_ignore regexp
noahhl authored
87 * `:line` (for file and line number calling query). :line supports
b60ad22 @nragaz Fix typo in README
nragaz authored
88 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
89 to exclude parts of the stacktrace from inclusion in the line comment.
28cdf0e @klausmeyer Add new component `controller_with_namespace` (closes #40)
klausmeyer authored
90 * `:controller_with_namespace` to include the full classname (including namespace)
91 of the controller.
d2b51b7 @nate00 Add ActiveJob component
nate00 authored
92 * `:job` to include the classname of the ActiveJob being performed.
54814cc @noahhl Add support for :line query comment
noahhl authored
93
94 Pull requests for other included comment components are welcome.
ac478ea @noahhl Document customization
noahhl authored
95
cf59528 @qrush blurb about contributing
qrush authored
96 ## Contributing
97
98 Start by bundling and creating the test database:
99
100 bundle
9fc1974 @nate00 README: Update Contributing section adapters
nate00 authored
101 rake db:mysql:create
102 rake db:postgresql:create
cf59528 @qrush blurb about contributing
qrush authored
103
9fc1974 @nate00 README: Update Contributing section adapters
nate00 authored
104 Then, running `rake` will run the tests on all the database adapters (`mysql`, `mysql2`, `postgresql` and `sqlite`):
cf59528 @qrush blurb about contributing
qrush authored
105
106 rake
107
Something went wrong with that request. Please try again.