Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Newer
Older
100644 288 lines (180 sloc) 10.642 kB
259e6c9 @bkayser Documentation back to Markdown
bkayser authored
1 # The RPM Contrib Gem
873b2a3 @bkayser First pass at new instrumentation
bkayser authored
2
2e8f0a2 @bkayser Add redis instrumentation contributed by ngmoco
bkayser authored
3 The `rpm_contrib` gem contains instrumentation for the New Relic RPM agent
4 contributed by the community of RPM users. It requires the RPM Agent to run.
873b2a3 @bkayser First pass at new instrumentation
bkayser authored
5
5bcaa2d @briandoll updating README
briandoll authored
6 To use the rpm_contrib gem, install the `rpm_contrib` gem from rubygems.org.
7 It will also install the required version of the `newrelic_rpm` gem if it's not
8 already installed.
9
66b71d3 @bkayser Release 2.1.4 gem and update README
bkayser authored
10 For Rails 3.0 and when using Bundler, add these dependencies to your Gemfile:
5bcaa2d @briandoll updating README
briandoll authored
11
12 gem 'rpm_contrib'
66b71d3 @bkayser Release 2.1.4 gem and update README
bkayser authored
13 gem 'newrelic_rpm'
3b2e6a5 @bkayser Mongodb instrumentation by John Nunemaker
bkayser authored
14
66b71d3 @bkayser Release 2.1.4 gem and update README
bkayser authored
15 For Rails 2.1 and later, add these dependencies to your in your environment.rb:
3b2e6a5 @bkayser Mongodb instrumentation by John Nunemaker
bkayser authored
16
17 config.gem 'rpm_contrib'
66b71d3 @bkayser Release 2.1.4 gem and update README
bkayser authored
18 config.gem 'newrelic_rpm'
3b2e6a5 @bkayser Mongodb instrumentation by John Nunemaker
bkayser authored
19
2e8f0a2 @bkayser Add redis instrumentation contributed by ngmoco
bkayser authored
20 For other frameworks, make sure you load rubygems if it isn't already, then just
5bcaa2d @briandoll updating README
briandoll authored
21 require the rpm_contrib gem:
3b2e6a5 @bkayser Mongodb instrumentation by John Nunemaker
bkayser authored
22
23 require 'rubygems'
24 require 'rpm_contrib'
25
259e6c9 @bkayser Documentation back to Markdown
bkayser authored
26 When you load the rpm_contrib gem, the `newrelic_rpm` gem will also be
66b71d3 @bkayser Release 2.1.4 gem and update README
bkayser authored
27 initialized. No need for a separate require statement for `newrelic_rpm`.
28
29 In non-Rails frameworks, it's important that the New Relic Agent gets
30 loaded as late as possible, or that the final initialization hook is called
31 after all other frameworks have loaded:
32
33 DependencyDetection.detect!
f468d60 @bkayser admin changes for resque
bkayser authored
34
1bb3f0a @bkayser Added some troubleshooting steps to the readme
bkayser authored
35 ### Troubleshooting Startup
36
37 If you've set up your gems to load as described above and you are still not seeing
3c0dcc8 @bkayser Remove requirement for load ordering the gems with resque
bkayser authored
38 data in RPM, there may be a bug in detecting your framework. Try setting the
39 environment variable `NEWRELIC_DISPATCHER` to the name of your app server (Camping,
40 Resque, Rake, etc), and please report to us if this fixes the problem so we can
41 fix the auto-detection logic.
1bb3f0a @bkayser Added some troubleshooting steps to the readme
bkayser authored
42
43 If this does not help then set the `log_level` to `debug` in the `newrelic.yml` file
44 and examine the `newrelic_agent.log` file for errors after restarting your app.
45
46 ## Supported Frameworks
f468d60 @bkayser admin changes for resque
bkayser authored
47
2e8f0a2 @bkayser Add redis instrumentation contributed by ngmoco
bkayser authored
48 A number of frameworks are supported in the contrib gem. They are all turned on
49 by default but you can add settings to your newrelic.yml to disable any of them.
f468d60 @bkayser admin changes for resque
bkayser authored
50
55efed0 @loe The project is called ActiveMessaging. ActiveMQ is a broker.
loe authored
51 ### ActiveMessaging
e34ac77 @jaggederest update documentation with new instrumentation, add disable flags to t…
jaggederest authored
52
53 The gem will detect the underlying ActiveMessaging::Processor class and instrument the `on_message` method
54
55efed0 @loe The project is called ActiveMessaging. ActiveMQ is a broker.
loe authored
55 It can be disabled with the `disable_active_messaging` flag in your newrelic.yml file.
e34ac77 @jaggederest update documentation with new instrumentation, add disable flags to t…
jaggederest authored
56
57 ### Cassandra
58
59 The gem will instrument Cassandra so it should be visible in transaction traces and the web transactions page.
60
61 You can disable it with `disable_cassandra_instrumentation` in your newrelic.yml file.
62
259e6c9 @bkayser Documentation back to Markdown
bkayser authored
63 ### Camping
f468d60 @bkayser admin changes for resque
bkayser authored
64
1700d6f @bkayser Read disable flags from newrelic.yml
bkayser authored
65 The gem will detect a Camping app but you need to manually add the
3c0dcc8 @bkayser Remove requirement for load ordering the gems with resque
bkayser authored
66 instrumentation to your configuration file. See
67 RPMContrib::Instrumentation::Camping for more information.
68
69 In addition you will need to load the gems in the following order: 1) Camping, 2) rpm_contrib,
70 3) newrelic_rpm.
1700d6f @bkayser Read disable flags from newrelic.yml
bkayser authored
71
e34ac77 @jaggederest update documentation with new instrumentation, add disable flags to t…
jaggederest authored
72 ### Crack
73
74 The gem will instrument the Crack parsers for JSON and XML - you
75 should see them in transaction traces and the web transactions page.
76
77 You can disable it with `disable_crack` in your newrelic.yml file.
78
79 ### Curb
80
81 The gem will instrument both Curl::Easy and Curl::Multi - they should show up similarly to Net::HTTP in the UI
82
83 You can disable it with `disable_curb` in your newrelic.yml file.
84
85 ## Elastic Search
86
87 The gem will instrument ElasticSearch::Client. The metrics should show up in the UI
88
89 You can disable it with `disable_elastic_search_instrumentation` in your newrelic.yml file.
90
29184e4 @samg Add KyotoTycoon to README
samg authored
91 ## KyotoTycoon
92
93 The gem will instrument KyotoTycoon.
94
95 You can disable it with `disable_kyototycoon` in your newrelic.yml file.
96
259e6c9 @bkayser Documentation back to Markdown
bkayser authored
97 ### Paperclip
f468d60 @bkayser admin changes for resque
bkayser authored
98
e34ac77 @jaggederest update documentation with new instrumentation, add disable flags to t…
jaggederest authored
99 No special configuration required for Paperclip visibility.
100
101 You can disable it by setting `disable_paperclip` to true in your newrelic.yml file.
1700d6f @bkayser Read disable flags from newrelic.yml
bkayser authored
102
259e6c9 @bkayser Documentation back to Markdown
bkayser authored
103 ### MongoDB
f468d60 @bkayser admin changes for resque
bkayser authored
104
e34ac77 @jaggederest update documentation with new instrumentation, add disable flags to t…
jaggederest authored
105 Our instrumentation works on the underlying 'Mongo' library.
106
107 You can disable it by setting 'disable_mongodb' to true in your newrelic.yml file.
1700d6f @bkayser Read disable flags from newrelic.yml
bkayser authored
108
259e6c9 @bkayser Documentation back to Markdown
bkayser authored
109 ### Resque
f468d60 @bkayser admin changes for resque
bkayser authored
110
66b71d3 @bkayser Release 2.1.4 gem and update README
bkayser authored
111 To instrument jobs you no longer need to have your Job class inherit from Resque::Job or include
112 the Resque::Plugins::NewRelicInstrumentation module. The module definition was left in for
113 backward compatibility.
8990ce6 @jaggederest update resque instrumentation to use a plugin for most of the work
jaggederest authored
114
5bcaa2d @briandoll updating README
briandoll authored
115 To disable resque, set 'disable_resque' to true in your newrelic.yml file.
3706b92 @bkayser more doc updates
bkayser authored
116
2e8f0a2 @bkayser Add redis instrumentation contributed by ngmoco
bkayser authored
117 ### Redis
118
119 Redis instrumentation will record operations as well as `allWeb` and `allOther`
5bcaa2d @briandoll updating README
briandoll authored
120 summary metrics under the `Database/Redis` metric namespace. This instrumentation
e34ac77 @jaggederest update documentation with new instrumentation, add disable flags to t…
jaggederest authored
121 supports Redis versions 1.x and 2.x.
122
123 To disable Redis instrumentation, set 'disable_redis' to true in your newrelic.yml file.
124
b253d53 @samg More README
samg authored
125 ### Riak
126
127 RiakClient is instrumented. Its opereations are recorded under Database in the
128 the response time graph.
129
130 To disable Riak instrumentation, set 'disable_riak_client' to true in your newrelic.yml file.
131
132 ### Ripple
133
134 Ripple is instrumented. Its opereations are recorded under Database in the
135 the response time graph.
136
137 To disable Riak instrumentation, set 'disable_ripple' to true in your newrelic.yml file.
138
e34ac77 @jaggederest update documentation with new instrumentation, add disable flags to t…
jaggederest authored
139 ### Sinatra view instrumentation
140
141 This adds instrumentation to the `render` methods in Sinatra::Base
142
143 You can disable it with `disable_sinatra_template` in your newrelic.yml file.
144
29184e4 @samg Add KyotoTycoon to README
samg authored
145 ### ThinkingSphinx instrumentation
146
147 This adds instrumentation to the `initialize` and `results` method of ThinkingSphinx::Search
148
149 You can disable it with `disable_thinking_sphinx` in your newrelic.yml file.
150
151
e34ac77 @jaggederest update documentation with new instrumentation, add disable flags to t…
jaggederest authored
152 ### Typhoeus instrumentation
153
154 This adds instrumentation to the Typhoeus::Request class for 'GET' requests
155
156 You can disable it with `disable_typhoeus` in your newrelic.yml file.
157
158 ### Ultrasphinx instrumentation
159
160 This adds basic instrumentation to the `run` and `results` method of Ultrasphinx::Search
161
162 You can disable it with `disable_ultrasphinx` in your newrelic.yml file.
163
164 ### Workling
165
166 This adds instrumentation to the Workling::Base and all children, for all defined public methods not inherited from the Workling::Base class
167
168 You can disable it with `disable_workling` in your newrelic.yml file.
169
170 ### YAJL
171
172 This adds instrumentation to the YAJL json parser
173
174 You can disable it with `disable_yajl_instrumentation` in your newrelic.yml file.
2e8f0a2 @bkayser Add redis instrumentation contributed by ngmoco
bkayser authored
175
5bcaa2d @briandoll updating README
briandoll authored
176 ### AWS/S3
2e8f0a2 @bkayser Add redis instrumentation contributed by ngmoco
bkayser authored
177
5bcaa2d @briandoll updating README
briandoll authored
178 Get metrics on how S3 is performing for you in production. To disable AWS/S3, set
179 'disable_aws-s3' to true in your newrelic.yml file. For more information on this
180 instrumentation, check out [our blog](http://blog.newrelic.com/2010/07/06/monitoring-aws-s3/).
3706b92 @bkayser more doc updates
bkayser authored
181
259e6c9 @bkayser Documentation back to Markdown
bkayser authored
182 # How to Add Custom Instrumentation
3706b92 @bkayser more doc updates
bkayser authored
183
2e8f0a2 @bkayser Add redis instrumentation contributed by ngmoco
bkayser authored
184 We encourage contributions to this project and will provide whatever assistance
185 we can to those wishing to develop instrumentation for other open source Ruby
186 libraries.
873b2a3 @bkayser First pass at new instrumentation
bkayser authored
187
2e8f0a2 @bkayser Add redis instrumentation contributed by ngmoco
bkayser authored
188 When adding instrumentation to this gem, be sure and get familiar with the [RPM
189 Agent API](http://newrelic.github.com/rpm/classes/NewRelic/Agent.html) and
190 contact support@newrelic.com with any questions.
cac8f9b @bkayser Updated docs
bkayser authored
191
2e8f0a2 @bkayser Add redis instrumentation contributed by ngmoco
bkayser authored
192 There are several extension points in the agent you can take advantage of with
193 this gem.
cac8f9b @bkayser Updated docs
bkayser authored
194
195 * Custom tracers which measure methods and give visibility to
196 otherwise unmeasured libraries.
197 * Samplers which sample some value about once a minute.
198 * Dispatcher support for web request handlers which would otherwise be undetected.
199 In order for the agent to turn on in 'auto' mode it needs to discover a
259e6c9 @bkayser Documentation back to Markdown
bkayser authored
200 web dispatcher, or be [started manually](http://support.newrelic.com/faqs/general/manual-start).
cac8f9b @bkayser Updated docs
bkayser authored
201 * Framework support, for alternatives to Rails like Camping or Ramaze
202
259e6c9 @bkayser Documentation back to Markdown
bkayser authored
203 ## Custom Tracers
cac8f9b @bkayser Updated docs
bkayser authored
204
259e6c9 @bkayser Documentation back to Markdown
bkayser authored
205 Custom tracers for frameworks should be added to the `lib/rpm_contrib/instrumentation`
206 directory. These files are loaded at the time the Agent starts. **They will not
207 be loaded if the Agent does not start up.**
cac8f9b @bkayser Updated docs
bkayser authored
208
2e8f0a2 @bkayser Add redis instrumentation contributed by ngmoco
bkayser authored
209 It is important that you wrap any instrumentation with the checks necessary to
210 determine if the code being instrumented is loaded. You can't add code to the
cac8f9b @bkayser Updated docs
bkayser authored
211 contrib gem that will break when run in any other context besides yours.
212
eba89e7 @bkayser more doc updates
bkayser authored
213
2e8f0a2 @bkayser Add redis instrumentation contributed by ngmoco
bkayser authored
214 For details on how to define custom tracers, refer to the [support documentation
215 on adding custom
216 tracers](http://support.newrelic.com/faqs/docs/custom-metric-collection). You
217 can also get detailed information on the API from the [Agent method tracing
218 rdocs](http://newrelic.github.com/rpm/classes/NewRelic/Agent/MethodTracer.html),
219 especially the
220 [add_method_tracer](http://newrelic.github.com/rpm/classes/NewRelic/Agent/MethodTracer/ClassMethods.html)
cac8f9b @bkayser Updated docs
bkayser authored
221 docs.
222
259e6c9 @bkayser Documentation back to Markdown
bkayser authored
223 A good example can be found in `lib/rpm_contrib/instrumentation/paperclip.rb`.
cac8f9b @bkayser Updated docs
bkayser authored
224
259e6c9 @bkayser Documentation back to Markdown
bkayser authored
225 ## Samplers
cac8f9b @bkayser Updated docs
bkayser authored
226
2e8f0a2 @bkayser Add redis instrumentation contributed by ngmoco
bkayser authored
227 You can add samplers which will record metrics approximately once a minute.
228 Samplers are useful for capturing generic instrumentation for display in [custom
229 views](http://support.newrelic.com/faqs/docs/custom-dashboard-specification).
cac8f9b @bkayser Updated docs
bkayser authored
230
2e8f0a2 @bkayser Add redis instrumentation contributed by ngmoco
bkayser authored
231 Samplers should extend the
232 [`NewRelic::Agent::Sampler`](http://newrelic.github.com/rpm/classes/NewRelic/Agent/Sampler.html)
259e6c9 @bkayser Documentation back to Markdown
bkayser authored
233 class. They should be placed in the `samplers` directory.
cac8f9b @bkayser Updated docs
bkayser authored
234
235 Refer to examples in the RPM agent to see how to get started.
236
259e6c9 @bkayser Documentation back to Markdown
bkayser authored
237 ## Supporting New Dispatchers
cac8f9b @bkayser Updated docs
bkayser authored
238
2e8f0a2 @bkayser Add redis instrumentation contributed by ngmoco
bkayser authored
239 If you want to add support for a new dispatcher which is not being recognized by
240 default by the RPM agent, add code to the `rpm_contrib/detection` directory.
241 This code needs to define a module in the `NewRelic::LocalEnvironment` class.
242 This module will be accessed at the time environment detection takes place, when
243 the agent is initialized.
cac8f9b @bkayser Updated docs
bkayser authored
244
2e8f0a2 @bkayser Add redis instrumentation contributed by ngmoco
bkayser authored
245 This module should define the method `discover_dispatcher` and return the name
246 of the dispatcher if detected, or defer to super. See
247 `rpm_contrib/detection/camping.rb` for a good example.
cac8f9b @bkayser Updated docs
bkayser authored
248
259e6c9 @bkayser Documentation back to Markdown
bkayser authored
249 ## Supporting New Frameworks
cac8f9b @bkayser Updated docs
bkayser authored
250
251 Supporting new frameworks can be pretty involved and generally involves both
252 adding custom instrumentation as well as framework and dispatcher detection.
253
254 In addition it will be necessary to define a new control class with the same
259e6c9 @bkayser Documentation back to Markdown
bkayser authored
255 name as the framework. This control class must go in `new_relic/control`.
cac8f9b @bkayser Updated docs
bkayser authored
256
257 Refer to the camping example in this gem to see how this is done in general.
258
259 If you decide to tackle any new frameworks, contact support@newrelic.com and
260 we'll be happy to help you work through it.
261
259e6c9 @bkayser Documentation back to Markdown
bkayser authored
262 # Note on Patches/Pull Requests
873b2a3 @bkayser First pass at new instrumentation
bkayser authored
263
264 * Fork the http://www.github.com/newrelic/rpm_contrib project.
259e6c9 @bkayser Documentation back to Markdown
bkayser authored
265 * Add instrumentation files to `lib/rpm_contrib/instrumentation`. These
873b2a3 @bkayser First pass at new instrumentation
bkayser authored
266 files will be loaded when the RPM agent is initialized.
259e6c9 @bkayser Documentation back to Markdown
bkayser authored
267 * Add samplers to `lib/rpm_contrib/samplers`. These classes are
873b2a3 @bkayser First pass at new instrumentation
bkayser authored
268 installed automatically when the RPM agent is initialized.
3804fd6 @samg Ask contributors to update README
samg authored
269 * Add tests.
270 * Update README.md
873b2a3 @bkayser First pass at new instrumentation
bkayser authored
271 * Commit, do not mess with the Rakefile, version, or history. (if you
272 want to have your own version, that is fine but bump version in a
273 commit by itself I can ignore when I pull)
274 * Send me a pull request. Bonus points for topic branches.
275
259e6c9 @bkayser Documentation back to Markdown
bkayser authored
276 # Further Information
873b2a3 @bkayser First pass at new instrumentation
bkayser authored
277
7cba0fc @bkayser Improved doc output
bkayser authored
278 Refer to the Agent API Documentation at http://newrelic.github.com/rpm
873b2a3 @bkayser First pass at new instrumentation
bkayser authored
279
2e8f0a2 @bkayser Add redis instrumentation contributed by ngmoco
bkayser authored
280 See the support site faqs at http://support.newrelic.com/faqs for additional
281 tips and documentation.
873b2a3 @bkayser First pass at new instrumentation
bkayser authored
282
283 Contact support@newrelic.com for help.
284
259e6c9 @bkayser Documentation back to Markdown
bkayser authored
285 ### Copyright
873b2a3 @bkayser First pass at new instrumentation
bkayser authored
286
7cba0fc @bkayser Improved doc output
bkayser authored
287 Copyright (c) 2009-2010 New Relic. See LICENSE for details.
Something went wrong with that request. Please try again.