rpm_contrib 1.0.2 → 1.0.3

data/CHANGELOG

@@ -1,3 +1,7 @@
+* Version 1.0.3
+
+  MongoDB instrumentation contributed by John Nunemaker
+
 * Version 1.0.2
  
   Improved Camping support

data/README.md

@@ -4,11 +4,103 @@ The `rpm_contrib` gem contains instrumentation for the New Relic RPM agent
 contributed by the community of RPM users.  It requires the RPM Agent
 to run.
 
+To use the contrib gem, install the `rpm_contrib` gem off gemcutter.  It will
+also install the required version of the `newrelic_rpm` gem if it's not 
+already installed.
+
+For Rails 2.1 and later, add the dependency in your initializer:
+
+    config.gem 'rpm_contrib'
+
+For other frameworks, make sure you load rubygems if it isn't already, then
+just require the contrib gem:
+
+    require 'rubygems'
+    require 'rpm_contrib'
+
+When you load the rpm_contrib gem, the `newrelic_rpm` gem will also be initialized.
+No need for a separate require statement for `newrelic_rpm`.
+
+**It's important that you don't load the newrelic_rpm gem separately.** The 
+`rpm_contrib` gem must be loaded before the `newrelic_rpm` gem initializes.
+
+# How to Add Custom Instrumentation
+
 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](http://newrelic.github.com/rpm/classes/NewRelic/Agent.html)
+and contact support@newrelic.com with any questions.
+
+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](http://support.newrelic.com/faqs/general/manual-start).
+* 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 how to define custom tracers, refer to the [support documentation on adding
+custom tracers](http://support.newrelic.com/faqs/docs/custom-metric-collection).  You 
+can also get detailed information on the API from the 
+[Agent method tracing rdocs](http://newrelic.github.com/rpm/classes/NewRelic/Agent/MethodTracer.html),
+especially the [add_method_tracer](http://newrelic.github.com/rpm/classes/NewRelic/Agent/MethodTracer/ClassMethods.html)
+docs.
+
+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](http://support.newrelic.com/faqs/docs/custom-dashboard-specification).
+
+Samplers should extend the [`NewRelic::Agent::Sampler`](http://newrelic.github.com/rpm/classes/NewRelic/Agent/Sampler.html)
+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 support@newrelic.com and
+we'll be happy to help you work through it.
+
+# Note on Patches/Pull Requests
  
 * Fork the http://www.github.com/newrelic/rpm_contrib project.
 * Add instrumentation files to `lib/rpm_contrib/instrumentation`.  These
@@ -21,7 +113,7 @@ 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](http://newrelic.github.com/rpm).
 
@@ -29,6 +121,6 @@ See [the support site](http://support.newrelic.com/faqs) for additional tips and
 
 Contact support@newrelic.com for help.
 
-## Copyright
+### Copyright
 
 Copyright (c) 2010 New Relic. See LICENSE for details.

data/Rakefile

@@ -56,5 +56,7 @@ Rake::RDocTask.new do |rdoc|
   rdoc.rdoc_dir = 'rdoc'
   rdoc.title = "rpm_contrib #{version}"
   rdoc.rdoc_files.include('README*')
+  rdoc.rdoc_files.include('LICENSE')
+  rdoc.rdoc_files.include('CHANGELOG')
   rdoc.rdoc_files.include('lib/**/*.rb')
 end

data/lib/rpm_contrib/instrumentation/mongodb.rb

@@ -0,0 +1,40 @@
+# Just drop this little diddy in your app to get some (not perfect) information on query times and such
+# This will eventually become an official plugin but for those who can't wait, enjoy.
+
+if defined?(::MongoMapper)
+  module MMNewRelicTracing
+    def self.included(model)
+      model.metaclass.class_eval do
+        add_method_tracer :find,        'Database/#{self.name}/find'
+        add_method_tracer :find!,       'Database/#{self.name}/find!'
+        add_method_tracer :paginate,    'Database/#{self.name}/paginate'
+        add_method_tracer :first,       'Database/#{self.name}/first'
+        add_method_tracer :last,        'Database/#{self.name}/last'
+        add_method_tracer :all,         'Database/#{self.name}/all'
+        add_method_tracer :count,       'Database/#{self.name}/count'
+        add_method_tracer :create,      'Database/#{self.name}/create'
+        add_method_tracer :create!,     'Database/#{self.name}/create!'
+        add_method_tracer :update,      'Database/#{self.name}/update'
+        add_method_tracer :delete,      'Database/#{self.name}/delete'
+        add_method_tracer :delete_all,  'Database/#{self.name}/delete_all'
+        add_method_tracer :destroy,     'Database/#{self.name}/destroy'
+        add_method_tracer :destroy_all, 'Database/#{self.name}/destroy_all'
+        add_method_tracer :exists?,     'Database/#{self.name}/exists?'
+        add_method_tracer :find_by_id,  'Database/#{self.name}/find_by_id'
+        add_method_tracer :increment,   'Database/#{self.name}/increment'
+        add_method_tracer :decrement,   'Database/#{self.name}/decrement'
+        add_method_tracer :set,         'Database/#{self.name}/set'
+        add_method_tracer :push,        'Database/#{self.name}/push'
+        add_method_tracer :push_all,    'Database/#{self.name}/push_all'
+        add_method_tracer :push_uniq,   'Database/#{self.name}/push_uniq'
+        add_method_tracer :pull,        'Database/#{self.name}/pull'
+        add_method_tracer :pull_all,    'Database/#{self.name}/pull_all'
+      end
+      
+      model.class_eval do
+        add_method_tracer :save,        'Database/#{self.class.name}/save'
+      end
+    end
+  end
+  ::MongoMapper::Document.append_inclusions(MMNewRelicTracing)
+end

metadata

@@ -5,8 +5,8 @@ version: !ruby/object:Gem::Version
   segments: 
   - 1
   - 0
-  - 2
-  version: 1.0.2
+  - 3
+  version: 1.0.3
 platform: ruby
 authors: 
 - Bill Kayser
@@ -14,7 +14,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2010-03-05 00:00:00 -08:00
+date: 2010-03-11 00:00:00 -08:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
@@ -50,6 +50,7 @@ files:
 - lib/rpm_contrib/detection/camping.rb
 - lib/rpm_contrib/instrumentation/authlogic.rb
 - lib/rpm_contrib/instrumentation/camping.rb
+- lib/rpm_contrib/instrumentation/mongodb.rb
 - lib/rpm_contrib/instrumentation/paperclip.rb
 - test/helper.rb
 - test/schema.rb