Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 273 lines (171 sloc) 10.21 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
259e6c9 Bill Kayser Documentation back to Markdown
bkayser authored
103 ### MongoDB
f468d60 Bill Kayser admin changes for resque
bkayser authored
104
e34ac77 Justin George update documentation with new instrumentation, add disable flags to typh...
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 Bill Kayser Read disable flags from newrelic.yml
bkayser authored
108
259e6c9 Bill Kayser Documentation back to Markdown
bkayser authored
109 ### Resque
f468d60 Bill Kayser admin changes for resque
bkayser authored
110
66b71d3 Bill Kayser 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 Justin George update resque instrumentation to use a plugin for most of the work
jaggederest authored
114
5bcaa2d Brian Doll updating README
briandoll authored
115 To disable resque, set 'disable_resque' to true in your newrelic.yml file.
3706b92 Bill Kayser more doc updates
bkayser authored
116
2e8f0a2 Bill Kayser Add redis instrumentation contributed by ngmoco
bkayser authored
117 ### Redis
118
119 Redis instrumentation will record operations as well as `allWeb` and `allOther`
5bcaa2d Brian Doll updating README
briandoll authored
120 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
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
125 ### Sinatra view instrumentation
126
127 This adds instrumentation to the `render` methods in Sinatra::Base
128
129 You can disable it with `disable_sinatra_template` in your newrelic.yml file.
130
29184e4 Sam Goldstein Add KyotoTycoon to README
samg authored
131 ### ThinkingSphinx instrumentation
132
133 This adds instrumentation to the `initialize` and `results` method of ThinkingSphinx::Search
134
135 You can disable it with `disable_thinking_sphinx` in your newrelic.yml file.
136
137
e34ac77 Justin George update documentation with new instrumentation, add disable flags to typh...
jaggederest authored
138 ### Typhoeus instrumentation
139
140 This adds instrumentation to the Typhoeus::Request class for 'GET' requests
141
142 You can disable it with `disable_typhoeus` in your newrelic.yml file.
143
144 ### Ultrasphinx instrumentation
145
146 This adds basic instrumentation to the `run` and `results` method of Ultrasphinx::Search
147
148 You can disable it with `disable_ultrasphinx` in your newrelic.yml file.
149
150 ### Workling
151
152 This adds instrumentation to the Workling::Base and all children, for all defined public methods not inherited from the Workling::Base class
153
154 You can disable it with `disable_workling` in your newrelic.yml file.
155
156 ### YAJL
157
158 This adds instrumentation to the YAJL json parser
159
160 You can disable it with `disable_yajl_instrumentation` in your newrelic.yml file.
2e8f0a2 Bill Kayser Add redis instrumentation contributed by ngmoco
bkayser authored
161
5bcaa2d Brian Doll updating README
briandoll authored
162 ### AWS/S3
2e8f0a2 Bill Kayser Add redis instrumentation contributed by ngmoco
bkayser authored
163
5bcaa2d Brian Doll updating README
briandoll authored
164 Get metrics on how S3 is performing for you in production. To disable AWS/S3, set
165 'disable_aws-s3' to true in your newrelic.yml file. For more information on this
166 instrumentation, check out [our blog](http://blog.newrelic.com/2010/07/06/monitoring-aws-s3/).
3706b92 Bill Kayser more doc updates
bkayser authored
167
259e6c9 Bill Kayser Documentation back to Markdown
bkayser authored
168 # How to Add Custom Instrumentation
3706b92 Bill Kayser more doc updates
bkayser authored
169
2e8f0a2 Bill Kayser Add redis instrumentation contributed by ngmoco
bkayser authored
170 We encourage contributions to this project and will provide whatever assistance
171 we can to those wishing to develop instrumentation for other open source Ruby
172 libraries.
873b2a3 Bill Kayser First pass at new instrumentation
bkayser authored
173
2e8f0a2 Bill Kayser Add redis instrumentation contributed by ngmoco
bkayser authored
174 When adding instrumentation to this gem, be sure and get familiar with the [RPM
175 Agent API](http://newrelic.github.com/rpm/classes/NewRelic/Agent.html) and
176 contact support@newrelic.com with any questions.
cac8f9b Bill Kayser Updated docs
bkayser authored
177
2e8f0a2 Bill Kayser Add redis instrumentation contributed by ngmoco
bkayser authored
178 There are several extension points in the agent you can take advantage of with
179 this gem.
cac8f9b Bill Kayser Updated docs
bkayser authored
180
181 * Custom tracers which measure methods and give visibility to
182 otherwise unmeasured libraries.
183 * Samplers which sample some value about once a minute.
184 * Dispatcher support for web request handlers which would otherwise be undetected.
185 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
186 web dispatcher, or be [started manually](http://support.newrelic.com/faqs/general/manual-start).
cac8f9b Bill Kayser Updated docs
bkayser authored
187 * Framework support, for alternatives to Rails like Camping or Ramaze
188
259e6c9 Bill Kayser Documentation back to Markdown
bkayser authored
189 ## Custom Tracers
cac8f9b Bill Kayser Updated docs
bkayser authored
190
259e6c9 Bill Kayser Documentation back to Markdown
bkayser authored
191 Custom tracers for frameworks should be added to the `lib/rpm_contrib/instrumentation`
192 directory. These files are loaded at the time the Agent starts. **They will not
193 be loaded if the Agent does not start up.**
cac8f9b Bill Kayser Updated docs
bkayser authored
194
2e8f0a2 Bill Kayser Add redis instrumentation contributed by ngmoco
bkayser authored
195 It is important that you wrap any instrumentation with the checks necessary to
196 determine if the code being instrumented is loaded. You can't add code to the
cac8f9b Bill Kayser Updated docs
bkayser authored
197 contrib gem that will break when run in any other context besides yours.
198
eba89e7 Bill Kayser more doc updates
bkayser authored
199
2e8f0a2 Bill Kayser Add redis instrumentation contributed by ngmoco
bkayser authored
200 For details on how to define custom tracers, refer to the [support documentation
201 on adding custom
202 tracers](http://support.newrelic.com/faqs/docs/custom-metric-collection). You
203 can also get detailed information on the API from the [Agent method tracing
204 rdocs](http://newrelic.github.com/rpm/classes/NewRelic/Agent/MethodTracer.html),
205 especially the
206 [add_method_tracer](http://newrelic.github.com/rpm/classes/NewRelic/Agent/MethodTracer/ClassMethods.html)
cac8f9b Bill Kayser Updated docs
bkayser authored
207 docs.
208
259e6c9 Bill Kayser Documentation back to Markdown
bkayser authored
209 A good example can be found in `lib/rpm_contrib/instrumentation/paperclip.rb`.
cac8f9b Bill Kayser Updated docs
bkayser authored
210
259e6c9 Bill Kayser Documentation back to Markdown
bkayser authored
211 ## Samplers
cac8f9b Bill Kayser Updated docs
bkayser authored
212
2e8f0a2 Bill Kayser Add redis instrumentation contributed by ngmoco
bkayser authored
213 You can add samplers which will record metrics approximately once a minute.
214 Samplers are useful for capturing generic instrumentation for display in [custom
215 views](http://support.newrelic.com/faqs/docs/custom-dashboard-specification).
cac8f9b Bill Kayser Updated docs
bkayser authored
216
2e8f0a2 Bill Kayser Add redis instrumentation contributed by ngmoco
bkayser authored
217 Samplers should extend the
218 [`NewRelic::Agent::Sampler`](http://newrelic.github.com/rpm/classes/NewRelic/Agent/Sampler.html)
259e6c9 Bill Kayser Documentation back to Markdown
bkayser authored
219 class. They should be placed in the `samplers` directory.
cac8f9b Bill Kayser Updated docs
bkayser authored
220
221 Refer to examples in the RPM agent to see how to get started.
222
259e6c9 Bill Kayser Documentation back to Markdown
bkayser authored
223 ## Supporting New Dispatchers
cac8f9b Bill Kayser Updated docs
bkayser authored
224
2e8f0a2 Bill Kayser Add redis instrumentation contributed by ngmoco
bkayser authored
225 If you want to add support for a new dispatcher which is not being recognized by
226 default by the RPM agent, add code to the `rpm_contrib/detection` directory.
227 This code needs to define a module in the `NewRelic::LocalEnvironment` class.
228 This module will be accessed at the time environment detection takes place, when
229 the agent is initialized.
cac8f9b Bill Kayser Updated docs
bkayser authored
230
2e8f0a2 Bill Kayser Add redis instrumentation contributed by ngmoco
bkayser authored
231 This module should define the method `discover_dispatcher` and return the name
232 of the dispatcher if detected, or defer to super. See
233 `rpm_contrib/detection/camping.rb` for a good example.
cac8f9b Bill Kayser Updated docs
bkayser authored
234
259e6c9 Bill Kayser Documentation back to Markdown
bkayser authored
235 ## Supporting New Frameworks
cac8f9b Bill Kayser Updated docs
bkayser authored
236
237 Supporting new frameworks can be pretty involved and generally involves both
238 adding custom instrumentation as well as framework and dispatcher detection.
239
240 In addition it will be necessary to define a new control class with the same
259e6c9 Bill Kayser Documentation back to Markdown
bkayser authored
241 name as the framework. This control class must go in `new_relic/control`.
cac8f9b Bill Kayser Updated docs
bkayser authored
242
243 Refer to the camping example in this gem to see how this is done in general.
244
245 If you decide to tackle any new frameworks, contact support@newrelic.com and
246 we'll be happy to help you work through it.
247
259e6c9 Bill Kayser Documentation back to Markdown
bkayser authored
248 # Note on Patches/Pull Requests
873b2a3 Bill Kayser First pass at new instrumentation
bkayser authored
249
250 * Fork the http://www.github.com/newrelic/rpm_contrib project.
259e6c9 Bill Kayser Documentation back to Markdown
bkayser authored
251 * Add instrumentation files to `lib/rpm_contrib/instrumentation`. These
873b2a3 Bill Kayser First pass at new instrumentation
bkayser authored
252 files will be loaded when the RPM agent is initialized.
259e6c9 Bill Kayser Documentation back to Markdown
bkayser authored
253 * Add samplers to `lib/rpm_contrib/samplers`. These classes are
873b2a3 Bill Kayser First pass at new instrumentation
bkayser authored
254 installed automatically when the RPM agent is initialized.
255 * Add tests.
256 * Commit, do not mess with the Rakefile, version, or history. (if you
257 want to have your own version, that is fine but bump version in a
258 commit by itself I can ignore when I pull)
259 * Send me a pull request. Bonus points for topic branches.
260
259e6c9 Bill Kayser Documentation back to Markdown
bkayser authored
261 # Further Information
873b2a3 Bill Kayser First pass at new instrumentation
bkayser authored
262
7cba0fc Bill Kayser Improved doc output
bkayser authored
263 Refer to the Agent API Documentation at http://newrelic.github.com/rpm
873b2a3 Bill Kayser First pass at new instrumentation
bkayser authored
264
2e8f0a2 Bill Kayser Add redis instrumentation contributed by ngmoco
bkayser authored
265 See the support site faqs at http://support.newrelic.com/faqs for additional
266 tips and documentation.
873b2a3 Bill Kayser First pass at new instrumentation
bkayser authored
267
268 Contact support@newrelic.com for help.
269
259e6c9 Bill Kayser Documentation back to Markdown
bkayser authored
270 ### Copyright
873b2a3 Bill Kayser First pass at new instrumentation
bkayser authored
271
7cba0fc Bill Kayser Improved doc output
bkayser authored
272 Copyright (c) 2009-2010 New Relic. See LICENSE for details.
Something went wrong with that request. Please try again.