Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

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