Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Newer
Older
100644 149 lines (100 sloc) 5.733 kB
873b2a3 @bkayser First pass at new instrumentation
bkayser authored
1 # The RPM Contrib Gem
2
f468d60 @bkayser admin changes for resque
bkayser authored
3 The `rpm_contrib` gem contains instrumentation for the New Relic RPM
4 agent contributed by the community of RPM users. It requires the RPM
5 Agent to run.
873b2a3 @bkayser First pass at new instrumentation
bkayser authored
6
f468d60 @bkayser admin changes for resque
bkayser authored
7 To use the contrib gem, install the `rpm_contrib` gem off gemcutter.
8 It will also install the required version of the `newrelic_rpm` gem if
9 it's not already installed.
3b2e6a5 @bkayser Mongodb instrumentation by John Nunemaker
bkayser authored
10
f468d60 @bkayser admin changes for resque
bkayser authored
11 For Rails 2.1 and later, add these dependencies in this order to your
12 in your environment.rb:
3b2e6a5 @bkayser Mongodb instrumentation by John Nunemaker
bkayser authored
13
14 config.gem 'rpm_contrib'
f468d60 @bkayser admin changes for resque
bkayser authored
15 config.gem 'newrelic_rpm'
3b2e6a5 @bkayser Mongodb instrumentation by John Nunemaker
bkayser authored
16
f468d60 @bkayser admin changes for resque
bkayser authored
17 For other frameworks, make sure you load rubygems if it isn't already,
18 then just require the contrib gem:
3b2e6a5 @bkayser Mongodb instrumentation by John Nunemaker
bkayser authored
19
20 require 'rubygems'
21 require 'rpm_contrib'
22
f468d60 @bkayser admin changes for resque
bkayser authored
23 When you load the rpm_contrib gem, the `newrelic_rpm` gem will also be
24 initialized. No need for a separate require statement for
25 `newrelic_rpm`. The `rpm_contrib` gem must be loaded before the
26 `newrelic_rpm` gem initializes.
27
28 # Supported Frameworks
29
30 A number of frameworks are supported in the contrib gem. They are all
31 turned on by default but you can add settings to your newrelic.yml to
32 disable any of them.
33
34 ### Camping
35
36 ### Paperclip
37
38 ### Authlogic
39
40 ### MongoDB
41
42 ### Resque
43
44 To disable resque, add this to your newrelic.yml:
45
46 disable_resque: true
3706b92 @bkayser more doc updates
bkayser authored
47
48
49 # How to Add Custom Instrumentation
50
873b2a3 @bkayser First pass at new instrumentation
bkayser authored
51 We encourage contributions to this project and will provide whatever
52 assistance we can to those wishing to develop instrumentation for
53 other open source Ruby libraries.
54
cac8f9b @bkayser Updated docs
bkayser authored
55 When adding instrumentation to this gem, be sure and get familiar with the
56 [RPM Agent API](http://newrelic.github.com/rpm/classes/NewRelic/Agent.html)
57 and contact support@newrelic.com with any questions.
58
59 There are several extension points in the agent you can take advantage of
60 with this gem.
61
62 * Custom tracers which measure methods and give visibility to
63 otherwise unmeasured libraries.
64 * Samplers which sample some value about once a minute.
65 * Dispatcher support for web request handlers which would otherwise be undetected.
66 In order for the agent to turn on in 'auto' mode it needs to discover a
67 web dispatcher, or be [started manually](http://support.newrelic.com/faqs/general/manual-start).
68 * Framework support, for alternatives to Rails like Camping or Ramaze
69
70 ## Custom Tracers
71
72 Custom tracers for frameworks should be added to the `lib/rpm_contrib/instrumentation`
73 directory. These files are loaded at the time the Agent starts. **They will not
74 be loaded if the Agent does not start up.**
75
76 It is important that you wrap any instrumentation with the checks necessary
77 to determine if the code being instrumented is loaded. You can't add code to the
78 contrib gem that will break when run in any other context besides yours.
79
eba89e7 @bkayser more doc updates
bkayser authored
80
81 For details on how to define custom tracers, refer to the [support documentation on adding
82 custom tracers](http://support.newrelic.com/faqs/docs/custom-metric-collection). You
83 can also get detailed information on the API from the
84 [Agent method tracing rdocs](http://newrelic.github.com/rpm/classes/NewRelic/Agent/MethodTracer.html),
cac8f9b @bkayser Updated docs
bkayser authored
85 especially the [add_method_tracer](http://newrelic.github.com/rpm/classes/NewRelic/Agent/MethodTracer/ClassMethods.html)
86 docs.
87
88 A good example can be found in `lib/rpm_contrib/instrumentation/paperclip.rb`.
89
90 ## Samplers
91
92 You can add samplers which will record metrics approximately once a minute. Samplers
93 are useful for capturing generic instrumentation for display in
94 [custom views](http://support.newrelic.com/faqs/docs/custom-dashboard-specification).
95
96 Samplers should extend the [`NewRelic::Agent::Sampler`](http://newrelic.github.com/rpm/classes/NewRelic/Agent/Sampler.html)
97 class. They should be placed in the `samplers` directory.
98
99 Refer to examples in the RPM agent to see how to get started.
100
101 ## Supporting New Dispatchers
102
103 If you want to add support for a new dispatcher which is not being recognized by default
104 by the RPM agent, add code to the `rpm_contrib/detection` directory. This code needs
105 to define a module in the `NewRelic::LocalEnvironment` class. This module will be
106 accessed at the time environment detection takes place, when the agent is initialized.
107
108 This module should define the method `discover_dispatcher` and return the name of the
109 dispatcher if detected, or defer to super. See `rpm_contrib/detection/camping.rb`
110 for a good example.
111
112 ## Supporting New Frameworks
113
114 Supporting new frameworks can be pretty involved and generally involves both
115 adding custom instrumentation as well as framework and dispatcher detection.
116
117 In addition it will be necessary to define a new control class with the same
118 name as the framework. This control class must go in `new_relic/control`.
119
120 Refer to the camping example in this gem to see how this is done in general.
121
122 If you decide to tackle any new frameworks, contact support@newrelic.com and
123 we'll be happy to help you work through it.
124
125 # Note on Patches/Pull Requests
873b2a3 @bkayser First pass at new instrumentation
bkayser authored
126
127 * Fork the http://www.github.com/newrelic/rpm_contrib project.
128 * Add instrumentation files to `lib/rpm_contrib/instrumentation`. These
129 files will be loaded when the RPM agent is initialized.
130 * Add samplers to `lib/rpm_contrib/samplers`. These classes are
131 installed automatically when the RPM agent is initialized.
132 * Add tests.
133 * Commit, do not mess with the Rakefile, version, or history. (if you
134 want to have your own version, that is fine but bump version in a
135 commit by itself I can ignore when I pull)
136 * Send me a pull request. Bonus points for topic branches.
137
cac8f9b @bkayser Updated docs
bkayser authored
138 # Further Information
873b2a3 @bkayser First pass at new instrumentation
bkayser authored
139
d4dbb42 @bkayser Typo
bkayser authored
140 Refer to the [Agent API Documentation](http://newrelic.github.com/rpm).
873b2a3 @bkayser First pass at new instrumentation
bkayser authored
141
d4dbb42 @bkayser Typo
bkayser authored
142 See [the support site](http://support.newrelic.com/faqs) for additional tips and documentation.
873b2a3 @bkayser First pass at new instrumentation
bkayser authored
143
144 Contact support@newrelic.com for help.
145
cac8f9b @bkayser Updated docs
bkayser authored
146 ### Copyright
873b2a3 @bkayser First pass at new instrumentation
bkayser authored
147
148 Copyright (c) 2010 New Relic. See LICENSE for details.
Something went wrong with that request. Please try again.