Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Newer
Older
100644 104 lines (72 sloc) 4.51 kb
873b2a3 @bkayser First pass at new instrumentation
bkayser authored
1 # The RPM Contrib Gem
2
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
5 to run.
6
7 We encourage contributions to this project and will provide whatever
8 assistance we can to those wishing to develop instrumentation for
9 other open source Ruby libraries.
10
cac8f9b @bkayser Updated docs
bkayser authored
11 When adding instrumentation to this gem, be sure and get familiar with the
12 [RPM Agent API](http://newrelic.github.com/rpm/classes/NewRelic/Agent.html)
13 and contact support@newrelic.com with any questions.
14
15 # How to Add Custom Instrumentation
16
17 There are several extension points in the agent you can take advantage of
18 with this gem.
19
20 * Custom tracers which measure methods and give visibility to
21 otherwise unmeasured libraries.
22 * Samplers which sample some value about once a minute.
23 * Dispatcher support for web request handlers which would otherwise be undetected.
24 In order for the agent to turn on in 'auto' mode it needs to discover a
25 web dispatcher, or be [started manually](http://support.newrelic.com/faqs/general/manual-start).
26 * Framework support, for alternatives to Rails like Camping or Ramaze
27
28 ## Custom Tracers
29
30 Custom tracers for frameworks should be added to the `lib/rpm_contrib/instrumentation`
31 directory. These files are loaded at the time the Agent starts. **They will not
32 be loaded if the Agent does not start up.**
33
34 It is important that you wrap any instrumentation with the checks necessary
35 to determine if the code being instrumented is loaded. You can't add code to the
36 contrib gem that will break when run in any other context besides yours.
37
38 For details on the instrumentation API, refer to the
39 [Agent method tracing rdocs](http://newrelic.github.com/rpm/classes/NewRelic/Agent/MethodTracer.html)
40 especially the [add_method_tracer](http://newrelic.github.com/rpm/classes/NewRelic/Agent/MethodTracer/ClassMethods.html)
41 docs.
42
43 A good example can be found in `lib/rpm_contrib/instrumentation/paperclip.rb`.
44
45 ## Samplers
46
47 You can add samplers which will record metrics approximately once a minute. Samplers
48 are useful for capturing generic instrumentation for display in
49 [custom views](http://support.newrelic.com/faqs/docs/custom-dashboard-specification).
50
51 Samplers should extend the [`NewRelic::Agent::Sampler`](http://newrelic.github.com/rpm/classes/NewRelic/Agent/Sampler.html)
52 class. They should be placed in the `samplers` directory.
53
54 Refer to examples in the RPM agent to see how to get started.
55
56 ## Supporting New Dispatchers
57
58 If you want to add support for a new dispatcher which is not being recognized by default
59 by the RPM agent, add code to the `rpm_contrib/detection` directory. This code needs
60 to define a module in the `NewRelic::LocalEnvironment` class. This module will be
61 accessed at the time environment detection takes place, when the agent is initialized.
62
63 This module should define the method `discover_dispatcher` and return the name of the
64 dispatcher if detected, or defer to super. See `rpm_contrib/detection/camping.rb`
65 for a good example.
66
67 ## Supporting New Frameworks
68
69 Supporting new frameworks can be pretty involved and generally involves both
70 adding custom instrumentation as well as framework and dispatcher detection.
71
72 In addition it will be necessary to define a new control class with the same
73 name as the framework. This control class must go in `new_relic/control`.
74
75 Refer to the camping example in this gem to see how this is done in general.
76
77 If you decide to tackle any new frameworks, contact support@newrelic.com and
78 we'll be happy to help you work through it.
79
80 # Note on Patches/Pull Requests
873b2a3 @bkayser First pass at new instrumentation
bkayser authored
81
82 * Fork the http://www.github.com/newrelic/rpm_contrib project.
83 * Add instrumentation files to `lib/rpm_contrib/instrumentation`. These
84 files will be loaded when the RPM agent is initialized.
85 * Add samplers to `lib/rpm_contrib/samplers`. These classes are
86 installed automatically when the RPM agent is initialized.
87 * Add tests.
88 * Commit, do not mess with the Rakefile, version, or history. (if you
89 want to have your own version, that is fine but bump version in a
90 commit by itself I can ignore when I pull)
91 * Send me a pull request. Bonus points for topic branches.
92
cac8f9b @bkayser Updated docs
bkayser authored
93 # Further Information
873b2a3 @bkayser First pass at new instrumentation
bkayser authored
94
d4dbb42 @bkayser Typo
bkayser authored
95 Refer to the [Agent API Documentation](http://newrelic.github.com/rpm).
873b2a3 @bkayser First pass at new instrumentation
bkayser authored
96
d4dbb42 @bkayser Typo
bkayser authored
97 See [the support site](http://support.newrelic.com/faqs) for additional tips and documentation.
873b2a3 @bkayser First pass at new instrumentation
bkayser authored
98
99 Contact support@newrelic.com for help.
100
cac8f9b @bkayser Updated docs
bkayser authored
101 ### Copyright
873b2a3 @bkayser First pass at new instrumentation
bkayser authored
102
103 Copyright (c) 2010 New Relic. See LICENSE for details.
Something went wrong with that request. Please try again.