Skip to content
Browse files

Updated docs

  • Loading branch information...
1 parent 648a2f7 commit cac8f9b245099347c3f1d64895ddc878a28898e2 @bkayser bkayser committed Mar 5, 2010
Showing with 74 additions and 3 deletions.
  1. +72 −3
  2. +2 −0 Rakefile
@@ -8,7 +8,76 @@ We encourage contributions to this project and will provide whatever
assistance we can to those wishing to develop instrumentation for
other open source Ruby libraries.
-## Note on Patches/Pull Requests
+When adding instrumentation to this gem, be sure and get familiar with the
+[RPM Agent API](
+and contact with any questions.
+# How to Add Custom Instrumentation
+There are several extension points in the agent you can take advantage of
+with this gem.
+* Custom tracers which measure methods and give visibility to
+ otherwise unmeasured libraries.
+* Samplers which sample some value about once a minute.
+* Dispatcher support for web request handlers which would otherwise be undetected.
+ In order for the agent to turn on in 'auto' mode it needs to discover a
+ web dispatcher, or be [started manually](
+* Framework support, for alternatives to Rails like Camping or Ramaze
+## Custom Tracers
+Custom tracers for frameworks should be added to the `lib/rpm_contrib/instrumentation`
+directory. These files are loaded at the time the Agent starts. **They will not
+be loaded if the Agent does not start up.**
+It is important that you wrap any instrumentation with the checks necessary
+to determine if the code being instrumented is loaded. You can't add code to the
+contrib gem that will break when run in any other context besides yours.
+For details on the instrumentation API, refer to the
+[Agent method tracing rdocs](
+especially the [add_method_tracer](
+A good example can be found in `lib/rpm_contrib/instrumentation/paperclip.rb`.
+## Samplers
+You can add samplers which will record metrics approximately once a minute. Samplers
+are useful for capturing generic instrumentation for display in
+[custom views](
+Samplers should extend the [`NewRelic::Agent::Sampler`](
+class. They should be placed in the `samplers` directory.
+Refer to examples in the RPM agent to see how to get started.
+## Supporting New Dispatchers
+If you want to add support for a new dispatcher which is not being recognized by default
+by the RPM agent, add code to the `rpm_contrib/detection` directory. This code needs
+to define a module in the `NewRelic::LocalEnvironment` class. This module will be
+accessed at the time environment detection takes place, when the agent is initialized.
+This module should define the method `discover_dispatcher` and return the name of the
+dispatcher if detected, or defer to super. See `rpm_contrib/detection/camping.rb`
+for a good example.
+## Supporting New Frameworks
+Supporting new frameworks can be pretty involved and generally involves both
+adding custom instrumentation as well as framework and dispatcher detection.
+In addition it will be necessary to define a new control class with the same
+name as the framework. This control class must go in `new_relic/control`.
+Refer to the camping example in this gem to see how this is done in general.
+If you decide to tackle any new frameworks, contact and
+we'll be happy to help you work through it.
+# Note on Patches/Pull Requests
* Fork the project.
* Add instrumentation files to `lib/rpm_contrib/instrumentation`. These
@@ -21,14 +90,14 @@ other open source Ruby libraries.
commit by itself I can ignore when I pull)
* Send me a pull request. Bonus points for topic branches.
-## Further Information
+# Further Information
Refer to the [Agent API Documentation](
See [the support site]( for additional tips and documentation.
Contact for help.
-## Copyright
+### Copyright
Copyright (c) 2010 New Relic. See LICENSE for details.
2 Rakefile
@@ -56,5 +56,7 @@ do |rdoc|
rdoc.rdoc_dir = 'rdoc'
rdoc.title = "rpm_contrib #{version}"
+ rdoc.rdoc_files.include('LICENSE')
+ rdoc.rdoc_files.include('CHANGELOG')

0 comments on commit cac8f9b

Please sign in to comment.
Something went wrong with that request. Please try again.