Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

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