Skip to content

HTTPS clone URL

Subversion checkout URL

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