Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 294 lines (183 sloc) 10.89 kb
259e6c9 Bill Kayser Documentation back to Markdown
bkayser authored
1 # The RPM Contrib Gem
873b2a3 Bill Kayser First pass at new instrumentation
bkayser authored
2
2e8f0a2 Bill Kayser 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 Bill Kayser First pass at new instrumentation
bkayser authored
5
5bcaa2d Brian Doll 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 Bill Kayser 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 Brian Doll updating README
briandoll authored
11
12 gem 'rpm_contrib'
66b71d3 Bill Kayser Release 2.1.4 gem and update README
bkayser authored
13 gem 'newrelic_rpm'
3b2e6a5 Bill Kayser Mongodb instrumentation by John Nunemaker
bkayser authored
14
66b71d3 Bill Kayser 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 Bill Kayser Mongodb instrumentation by John Nunemaker
bkayser authored
16
17 config.gem 'rpm_contrib'
66b71d3 Bill Kayser Release 2.1.4 gem and update README
bkayser authored
18 config.gem 'newrelic_rpm'
3b2e6a5 Bill Kayser Mongodb instrumentation by John Nunemaker
bkayser authored
19
2e8f0a2 Bill Kayser 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 Brian Doll updating README
briandoll authored
21 require the rpm_contrib gem:
3b2e6a5 Bill Kayser Mongodb instrumentation by John Nunemaker
bkayser authored
22
23 require 'rubygems'
24 require 'rpm_contrib'
25
259e6c9 Bill Kayser Documentation back to Markdown
bkayser authored
26 When you load the rpm_contrib gem, the `newrelic_rpm` gem will also be
66b71d3 Bill Kayser 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 Bill Kayser admin changes for resque
bkayser authored
34
1bb3f0a Bill Kayser 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 Bill Kayser 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 Bill Kayser 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 Bill Kayser admin changes for resque
bkayser authored
47
2e8f0a2 Bill Kayser 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 Bill Kayser admin changes for resque
bkayser authored
50
55efed0 W. Andrew Loe III The project is called ActiveMessaging. ActiveMQ is a broker.
loe authored
51 ### ActiveMessaging
e34ac77 Justin George update documentation with new instrumentation, add disable flags to typh...
jaggederest authored
52
53 The gem will detect the underlying ActiveMessaging::Processor class and instrument the `on_message` method
54
55efed0 W. Andrew Loe III 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 Justin George update documentation with new instrumentation, add disable flags to typh...
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 Bill Kayser Documentation back to Markdown
bkayser authored
63 ### Camping
f468d60 Bill Kayser admin changes for resque
bkayser authored
64
1700d6f Bill Kayser Read disable flags from newrelic.yml
bkayser authored
65 The gem will detect a Camping app but you need to manually add the
3c0dcc8 Bill Kayser 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 Bill Kayser Read disable flags from newrelic.yml
bkayser authored
71
e34ac77 Justin George update documentation with new instrumentation, add disable flags to typh...
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 Sam Goldstein 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 Bill Kayser Documentation back to Markdown
bkayser authored
97 ### Paperclip
f468d60 Bill Kayser admin changes for resque
bkayser authored
98
e34ac77 Justin George update documentation with new instrumentation, add disable flags to typh...
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 Bill Kayser Read disable flags from newrelic.yml
bkayser authored
102
da63144 Niko Dittmann + Picky instrumentation
niko authored
103 ### Picky
104
105 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.
106
107 You can disable it with `disable_picky` in your newrelic.yml file.
108
259e6c9 Bill Kayser Documentation back to Markdown
bkayser authored
109 ### MongoDB
f468d60 Bill Kayser admin changes for resque
bkayser authored
110
e34ac77 Justin George update documentation with new instrumentation, add disable flags to typh...
jaggederest authored
111 Our instrumentation works on the underlying 'Mongo' library.
112
113 You can disable it by setting 'disable_mongodb' to true in your newrelic.yml file.
1700d6f Bill Kayser Read disable flags from newrelic.yml
bkayser authored
114
259e6c9 Bill Kayser Documentation back to Markdown
bkayser authored
115 ### Resque
f468d60 Bill Kayser admin changes for resque
bkayser authored
116
66b71d3 Bill Kayser Release 2.1.4 gem and update README
bkayser authored
117 To instrument jobs you no longer need to have your Job class inherit from Resque::Job or include
118 the Resque::Plugins::NewRelicInstrumentation module. The module definition was left in for
119 backward compatibility.
8990ce6 Justin George update resque instrumentation to use a plugin for most of the work
jaggederest authored
120
5bcaa2d Brian Doll updating README
briandoll authored
121 To disable resque, set 'disable_resque' to true in your newrelic.yml file.
3706b92 Bill Kayser more doc updates
bkayser authored
122
2e8f0a2 Bill Kayser Add redis instrumentation contributed by ngmoco
bkayser authored
123 ### Redis
124
125 Redis instrumentation will record operations as well as `allWeb` and `allOther`
5bcaa2d Brian Doll updating README
briandoll authored
126 summary metrics under the `Database/Redis` metric namespace. This instrumentation
e34ac77 Justin George update documentation with new instrumentation, add disable flags to typh...
jaggederest authored
127 supports Redis versions 1.x and 2.x.
128
129 To disable Redis instrumentation, set 'disable_redis' to true in your newrelic.yml file.
130
b253d53 Sam Goldstein More README
samg authored
131 ### Riak
132
133 RiakClient is instrumented. Its opereations are recorded under Database in the
134 the response time graph.
135
136 To disable Riak instrumentation, set 'disable_riak_client' to true in your newrelic.yml file.
137
138 ### Ripple
139
140 Ripple is instrumented. Its opereations are recorded under Database in the
141 the response time graph.
142
143 To disable Riak instrumentation, set 'disable_ripple' to true in your newrelic.yml file.
144
e34ac77 Justin George update documentation with new instrumentation, add disable flags to typh...
jaggederest authored
145 ### Sinatra view instrumentation
146
147 This adds instrumentation to the `render` methods in Sinatra::Base
148
149 You can disable it with `disable_sinatra_template` in your newrelic.yml file.
150
29184e4 Sam Goldstein Add KyotoTycoon to README
samg authored
151 ### ThinkingSphinx instrumentation
152
153 This adds instrumentation to the `initialize` and `results` method of ThinkingSphinx::Search
154
155 You can disable it with `disable_thinking_sphinx` in your newrelic.yml file.
156
157
e34ac77 Justin George update documentation with new instrumentation, add disable flags to typh...
jaggederest authored
158 ### Typhoeus instrumentation
159
160 This adds instrumentation to the Typhoeus::Request class for 'GET' requests
161
162 You can disable it with `disable_typhoeus` in your newrelic.yml file.
163
164 ### Ultrasphinx instrumentation
165
166 This adds basic instrumentation to the `run` and `results` method of Ultrasphinx::Search
167
168 You can disable it with `disable_ultrasphinx` in your newrelic.yml file.
169
170 ### Workling
171
172 This adds instrumentation to the Workling::Base and all children, for all defined public methods not inherited from the Workling::Base class
173
174 You can disable it with `disable_workling` in your newrelic.yml file.
175
176 ### YAJL
177
178 This adds instrumentation to the YAJL json parser
179
180 You can disable it with `disable_yajl_instrumentation` in your newrelic.yml file.
2e8f0a2 Bill Kayser Add redis instrumentation contributed by ngmoco
bkayser authored
181
5bcaa2d Brian Doll updating README
briandoll authored
182 ### AWS/S3
2e8f0a2 Bill Kayser Add redis instrumentation contributed by ngmoco
bkayser authored
183
5bcaa2d Brian Doll updating README
briandoll authored
184 Get metrics on how S3 is performing for you in production. To disable AWS/S3, set
185 'disable_aws-s3' to true in your newrelic.yml file. For more information on this
186 instrumentation, check out [our blog](http://blog.newrelic.com/2010/07/06/monitoring-aws-s3/).
3706b92 Bill Kayser more doc updates
bkayser authored
187
259e6c9 Bill Kayser Documentation back to Markdown
bkayser authored
188 # How to Add Custom Instrumentation
3706b92 Bill Kayser more doc updates
bkayser authored
189
2e8f0a2 Bill Kayser Add redis instrumentation contributed by ngmoco
bkayser authored
190 We encourage contributions to this project and will provide whatever assistance
191 we can to those wishing to develop instrumentation for other open source Ruby
192 libraries.
873b2a3 Bill Kayser First pass at new instrumentation
bkayser authored
193
2e8f0a2 Bill Kayser Add redis instrumentation contributed by ngmoco
bkayser authored
194 When adding instrumentation to this gem, be sure and get familiar with the [RPM
195 Agent API](http://newrelic.github.com/rpm/classes/NewRelic/Agent.html) and
196 contact support@newrelic.com with any questions.
cac8f9b Bill Kayser Updated docs
bkayser authored
197
2e8f0a2 Bill Kayser Add redis instrumentation contributed by ngmoco
bkayser authored
198 There are several extension points in the agent you can take advantage of with
199 this gem.
cac8f9b Bill Kayser Updated docs
bkayser authored
200
201 * Custom tracers which measure methods and give visibility to
202 otherwise unmeasured libraries.
203 * Samplers which sample some value about once a minute.
204 * Dispatcher support for web request handlers which would otherwise be undetected.
205 In order for the agent to turn on in 'auto' mode it needs to discover a
259e6c9 Bill Kayser Documentation back to Markdown
bkayser authored
206 web dispatcher, or be [started manually](http://support.newrelic.com/faqs/general/manual-start).
cac8f9b Bill Kayser Updated docs
bkayser authored
207 * Framework support, for alternatives to Rails like Camping or Ramaze
208
259e6c9 Bill Kayser Documentation back to Markdown
bkayser authored
209 ## Custom Tracers
cac8f9b Bill Kayser Updated docs
bkayser authored
210
259e6c9 Bill Kayser Documentation back to Markdown
bkayser authored
211 Custom tracers for frameworks should be added to the `lib/rpm_contrib/instrumentation`
212 directory. These files are loaded at the time the Agent starts. **They will not
213 be loaded if the Agent does not start up.**
cac8f9b Bill Kayser Updated docs
bkayser authored
214
2e8f0a2 Bill Kayser Add redis instrumentation contributed by ngmoco
bkayser authored
215 It is important that you wrap any instrumentation with the checks necessary to
216 determine if the code being instrumented is loaded. You can't add code to the
cac8f9b Bill Kayser Updated docs
bkayser authored
217 contrib gem that will break when run in any other context besides yours.
218
eba89e7 Bill Kayser more doc updates
bkayser authored
219
2e8f0a2 Bill Kayser Add redis instrumentation contributed by ngmoco
bkayser authored
220 For details on how to define custom tracers, refer to the [support documentation
221 on adding custom
222 tracers](http://support.newrelic.com/faqs/docs/custom-metric-collection). You
223 can also get detailed information on the API from the [Agent method tracing
224 rdocs](http://newrelic.github.com/rpm/classes/NewRelic/Agent/MethodTracer.html),
225 especially the
226 [add_method_tracer](http://newrelic.github.com/rpm/classes/NewRelic/Agent/MethodTracer/ClassMethods.html)
cac8f9b Bill Kayser Updated docs
bkayser authored
227 docs.
228
259e6c9 Bill Kayser Documentation back to Markdown
bkayser authored
229 A good example can be found in `lib/rpm_contrib/instrumentation/paperclip.rb`.
cac8f9b Bill Kayser Updated docs
bkayser authored
230
259e6c9 Bill Kayser Documentation back to Markdown
bkayser authored
231 ## Samplers
cac8f9b Bill Kayser Updated docs
bkayser authored
232
2e8f0a2 Bill Kayser Add redis instrumentation contributed by ngmoco
bkayser authored
233 You can add samplers which will record metrics approximately once a minute.
234 Samplers are useful for capturing generic instrumentation for display in [custom
235 views](http://support.newrelic.com/faqs/docs/custom-dashboard-specification).
cac8f9b Bill Kayser Updated docs
bkayser authored
236
2e8f0a2 Bill Kayser Add redis instrumentation contributed by ngmoco
bkayser authored
237 Samplers should extend the
238 [`NewRelic::Agent::Sampler`](http://newrelic.github.com/rpm/classes/NewRelic/Agent/Sampler.html)
259e6c9 Bill Kayser Documentation back to Markdown
bkayser authored
239 class. They should be placed in the `samplers` directory.
cac8f9b Bill Kayser Updated docs
bkayser authored
240
241 Refer to examples in the RPM agent to see how to get started.
242
259e6c9 Bill Kayser Documentation back to Markdown
bkayser authored
243 ## Supporting New Dispatchers
cac8f9b Bill Kayser Updated docs
bkayser authored
244
2e8f0a2 Bill Kayser Add redis instrumentation contributed by ngmoco
bkayser authored
245 If you want to add support for a new dispatcher which is not being recognized by
246 default by the RPM agent, add code to the `rpm_contrib/detection` directory.
247 This code needs to define a module in the `NewRelic::LocalEnvironment` class.
248 This module will be accessed at the time environment detection takes place, when
249 the agent is initialized.
cac8f9b Bill Kayser Updated docs
bkayser authored
250
2e8f0a2 Bill Kayser Add redis instrumentation contributed by ngmoco
bkayser authored
251 This module should define the method `discover_dispatcher` and return the name
252 of the dispatcher if detected, or defer to super. See
253 `rpm_contrib/detection/camping.rb` for a good example.
cac8f9b Bill Kayser Updated docs
bkayser authored
254
259e6c9 Bill Kayser Documentation back to Markdown
bkayser authored
255 ## Supporting New Frameworks
cac8f9b Bill Kayser Updated docs
bkayser authored
256
257 Supporting new frameworks can be pretty involved and generally involves both
258 adding custom instrumentation as well as framework and dispatcher detection.
259
260 In addition it will be necessary to define a new control class with the same
259e6c9 Bill Kayser Documentation back to Markdown
bkayser authored
261 name as the framework. This control class must go in `new_relic/control`.
cac8f9b Bill Kayser Updated docs
bkayser authored
262
263 Refer to the camping example in this gem to see how this is done in general.
264
265 If you decide to tackle any new frameworks, contact support@newrelic.com and
266 we'll be happy to help you work through it.
267
259e6c9 Bill Kayser Documentation back to Markdown
bkayser authored
268 # Note on Patches/Pull Requests
873b2a3 Bill Kayser First pass at new instrumentation
bkayser authored
269
270 * Fork the http://www.github.com/newrelic/rpm_contrib project.
259e6c9 Bill Kayser Documentation back to Markdown
bkayser authored
271 * Add instrumentation files to `lib/rpm_contrib/instrumentation`. These
873b2a3 Bill Kayser First pass at new instrumentation
bkayser authored
272 files will be loaded when the RPM agent is initialized.
259e6c9 Bill Kayser Documentation back to Markdown
bkayser authored
273 * Add samplers to `lib/rpm_contrib/samplers`. These classes are
873b2a3 Bill Kayser First pass at new instrumentation
bkayser authored
274 installed automatically when the RPM agent is initialized.
3804fd6 Sam Goldstein Ask contributors to update README
samg authored
275 * Add tests.
276 * Update README.md
873b2a3 Bill Kayser First pass at new instrumentation
bkayser authored
277 * Commit, do not mess with the Rakefile, version, or history. (if you
278 want to have your own version, that is fine but bump version in a
279 commit by itself I can ignore when I pull)
280 * Send me a pull request. Bonus points for topic branches.
281
259e6c9 Bill Kayser Documentation back to Markdown
bkayser authored
282 # Further Information
873b2a3 Bill Kayser First pass at new instrumentation
bkayser authored
283
7cba0fc Bill Kayser Improved doc output
bkayser authored
284 Refer to the Agent API Documentation at http://newrelic.github.com/rpm
873b2a3 Bill Kayser First pass at new instrumentation
bkayser authored
285
2e8f0a2 Bill Kayser Add redis instrumentation contributed by ngmoco
bkayser authored
286 See the support site faqs at http://support.newrelic.com/faqs for additional
287 tips and documentation.
873b2a3 Bill Kayser First pass at new instrumentation
bkayser authored
288
289 Contact support@newrelic.com for help.
290
259e6c9 Bill Kayser Documentation back to Markdown
bkayser authored
291 ### Copyright
873b2a3 Bill Kayser First pass at new instrumentation
bkayser authored
292
7cba0fc Bill Kayser Improved doc output
bkayser authored
293 Copyright (c) 2009-2010 New Relic. See LICENSE for details.
Something went wrong with that request. Please try again.