Skip to content
This repository

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

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