traceview 3.0.0

data/CONFIG.md

@@ -0,0 +1,16 @@
+# TraceView Gem Configuration
+
+## Environment Variables
+
+The following environment variables are detected by the traceview gem:
+
+* `IGNORE_TRACEVIEW_WARNING` - tells the traceview gem to __not__ output the _missing TraceView libraries_ message on stack initialization
+
+* `TRACEVIEW_GEM_VERBOSE` - sets the verbose flag (`TraceView::Config[:verbose]`) early in the gem loading process which may output valuable information
+
+## TraceView::Config
+
+`TraceView::Config` is a nested hash used by the traceview gem to store preferences and switches.
+
+See [this Rails generator template file](https://github.com/appneta/oboe-ruby/blob/master/lib/rails/generators/traceview/templates/traceview_initializer.rb) for documentation on all of the supported values.
+

data/Gemfile

@@ -0,0 +1,95 @@
+source 'https://rubygems.org'
+
+group :development, :test do
+  gem 'minitest', "5.5.1"
+  gem 'minitest-reporters'
+  gem 'minitest-debugger', :require => false
+  gem 'rack-test'
+  gem 'puma'
+  if RUBY_VERSION < '1.9.3'
+    # i18n 0.7.0 dropped support for Ruby 1.9.2 and older.  ActiveSupport
+    # depends on i18n 0.7.0 since v 4.0.5.  For < 1.9.2 Ruby support, lock
+    # down to these versions to maintain functionality.
+    gem 'i18n', '< 0.7.0'
+    gem 'activesupport', '< 4.0.5'
+    gem 'appraisal'
+  else
+    gem 'appraisal'
+  end
+end
+
+group :development do
+  gem 'ruby-debug',   :platforms => [ :mri_18, :jruby ]
+  gem 'debugger',     :platform  =>   :mri_19
+  gem 'byebug',       :platforms => [ :mri_20, :mri_21, :mri_22 ]
+#  gem 'perftools.rb', :platforms => [ :mri_20, :mri_21 ], :require => 'perftools'
+  if RUBY_VERSION > '1.8.7'
+    gem 'pry'
+    gem 'pry-byebug', :platforms => [ :mri_20, :mri_21, :mri_22 ]
+  else
+    gem 'pry', '0.9.12.4'
+  end
+end
+
+# Instrumented gems
+gem 'dalli'
+gem 'memcache-client'
+gem 'cassandra'
+gem 'mongo'
+gem 'resque'
+gem 'redis'
+gem 'faraday'
+gem 'httpclient'
+gem 'excon'
+gem 'typhoeus'
+gem 'sequel'
+if RUBY_VERSION >= '1.9.3'
+  # rest-client depends on mime-types gem which only supports
+  # ruby 1.9.3 and up
+  gem 'rest-client'
+end
+
+# Database adapter gems needed by sequel
+if defined?(JRUBY_VERSION)
+  gem 'jdbc-postgresql'
+  gem 'jdbc-mysql'
+else
+  gem 'mysql'
+  gem 'mysql2'
+  if RUBY_VERSION < '1.9.3'
+    gem 'pg', '0.17.1'
+  else
+    gem 'pg'
+  end
+end
+
+if RUBY_VERSION >= '1.9'
+  gem 'moped'
+  gem 'eventmachine'
+  gem 'em-synchrony'
+  gem 'em-http-request'
+end
+
+unless defined?(JRUBY_VERSION)
+  gem 'memcached', '1.7.2' if RUBY_VERSION < '2.0.0'
+  gem 'bson_ext' # For Mongo, Yours Truly
+end
+
+# Instrumented Frameworks
+
+if defined?(JRUBY_VERSION)
+  gem 'sinatra', :require => false
+else
+  gem 'sinatra'
+end
+
+if RUBY_VERSION >= '1.9.3'
+  gem 'padrino', '0.12.0'
+  gem 'grape'
+  gem 'bson'
+else
+  gem 'bson', '1.10.2'
+end
+
+gemspec
+

data/LICENSE

@@ -0,0 +1,199 @@
+AppNeta Open License, Version 1.0
+
+AppNeta Open License
+Version 1.0, April, 2013
+
+http://www.appneta.com/appneta-license
+
+TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+1. Definitions.
+
+"License" shall mean the terms and conditions for use, reproduction, and 
+distribution as defined by Sections 1 through 11 of this document.
+
+"Licensor" shall mean the copyright owner or entity authorized by the copyright 
+owner that is granting the License.  Licensor can include AppNeta as an 
+original contributor to the Work as defined below.
+
+"Legal Entity" shall mean the union of the acting entity and all other entities 
+that control, are controlled by, or are under common control with that entity. 
+For the purposes of this definition, "control" means (i) the power, direct or 
+indirect, to cause the direction or management of such entity, whether by 
+contract or otherwise, or (ii) ownership of fifty percent (50%) or more of the 
+outstanding shares, or (iii) beneficial ownership of such entity.
+
+"You" (or "Your") shall mean an individual or Legal Entity exercising 
+permissions granted by this License.
+
+"Source" form shall mean the preferred form for making modifications, including 
+but not limited to software source code, documentation source, and 
+configuration files.
+
+"Object" form shall mean any form resulting from mechanical transformation or 
+translation of a Source form, including but not limited to compiled object 
+code, generated documentation, and conversions to other media types.
+
+"Work" shall mean the work of authorship, whether in Source or Object form, 
+made available under the License, as indicated by a copyright notice that is 
+included in or attached to the work (an example is provided in the Appendix 
+below).
+
+"Derivative Works" shall mean any work, whether in Source or Object form, that 
+is based on (or derived from) the Work and for which the editorial revisions, 
+annotations, elaborations, or other modifications represent, as a whole, an 
+original work of authorship. For the purposes of this License, Derivative Works 
+shall not include works that remain separable from, or merely link (or bind by 
+name) to the interfaces of, the Work and Derivative Works thereof.
+
+"Contribution" shall mean any work of authorship, including the original 
+version of the Work and any modifications or additions to that Work or 
+Derivative Works thereof, that is intentionally submitted to Licensor for 
+inclusion in the Work by the copyright owner or by an individual or Legal 
+Entity authorized to submit on behalf of the copyright owner. For the purposes 
+of this definition, "submitted" means any form of electronic, verbal, or 
+written communication sent to the Licensor or its representatives, including 
+but not limited to communication on electronic mailing lists, source code 
+control systems, and issue tracking systems that are managed by, or on behalf 
+of, the Licensor for the purpose of discussing and improving the Work, but 
+excluding communication that is conspicuously marked or otherwise designated in 
+writing by the copyright owner as "Not a Contribution."
+
+"Contributor" shall mean Licensor and any individual or Legal Entity on behalf 
+of whom a Contribution has been received by Licensor and subsequently 
+incorporated within the Work.
+
+2. Grant of Copyright License.
+
+Subject to the terms and conditions of this License, each Contributor hereby 
+grants to You a perpetual, worldwide, non-exclusive, no-charge, royalty-free, 
+irrevocable copyright license to reproduce, prepare Derivative Works of, 
+publicly display, publicly perform, sublicense, and distribute the Work and 
+such Derivative Works in Source or Object form.
+
+3. Grant of Patent License.
+
+Subject to the terms and conditions of this License, each Contributor hereby 
+grants to You a perpetual, worldwide, non-exclusive, no-charge, royalty-free, 
+irrevocable (except as stated in this section) patent license to make, have 
+made, use, offer to sell, sell, import, and otherwise transfer the Work, where 
+such license applies only to those patent claims licensable by such Contributor 
+that are necessarily infringed by their Contribution(s) alone or by combination 
+of their Contribution(s) with the Work to which such Contribution(s) was 
+submitted. If You institute patent litigation against any entity (including a 
+cross-claim or counterclaim in a lawsuit) alleging that the Work or a 
+Contribution incorporated within the Work constitutes direct or contributory 
+patent infringement, then any patent licenses granted to You under this License 
+for that Work shall terminate as of the date such litigation is filed.
+
+Each time You convey a covered Work, the recipient automatically receives a 
+license from the original Licensor(s), to run, modify and propagate that work, 
+subject to this License. You are not responsible for enforcing compliance by 
+third parties with this License.
+
+You may not impose any further restrictions on the exercise of the rights 
+granted or affirmed under this License. For example, you may not impose a 
+license fee, royalty, or other charge for exercise of rights granted under this 
+License, and you may not initiate litigation (including a cross-claim or 
+counterclaim in a lawsuit) alleging that any patent claim is infringed by 
+making, using, selling, offering for sale, or importing the Work or any portion 
+of it.
+
+4. Redistribution.
+
+You may reproduce and distribute copies of the Work or Derivative Works thereof 
+in any medium, with or without modifications, and in Source or Object form, 
+provided that You meet the following conditions:
+
+  1. You must give any other recipients of the Work or Derivative Works a copy 
+of this License; and
+  2. You must cause any modified files to carry prominent notices stating that 
+You changed the files; and
+  3. You must retain, in the Source form of any Derivative Works that You 
+distribute, all copyright, patent, trademark, and attribution notices from the 
+Source form of the Work, excluding those notices that do not pertain to any 
+part of the Derivative Works; and
+  4. If the Work includes a "NOTICE" text file as part of its distribution, 
+then any Derivative Works that You distribute must include a readable copy of 
+the attribution notices contained within such NOTICE file, excluding those 
+notices that do not pertain to any part of the Derivative Works, in at least 
+one of the following places: within a NOTICE text file distributed as part of 
+the Derivative Works; within the Source form or documentation, if provided 
+along with the Derivative Works; or, within a display generated by the 
+Derivative Works, if and wherever such third-party notices normally appear. The 
+contents of the NOTICE file are for informational purposes only and do not 
+modify the License. You may add Your own attribution notices within Derivative 
+Works that You distribute, alongside or as an addendum to the NOTICE text from 
+the Work, provided that such additional attribution notices cannot be construed 
+as modifying the License.
+
+You may add Your own copyright statement to Your modifications and may provide 
+additional or different license terms and conditions for use, reproduction, or 
+distribution of Your modifications, or for any such Derivative Works as a 
+whole, provided Your use, reproduction, and distribution of the Work otherwise 
+complies with the conditions stated in this License.
+
+5. Submission of Contributions.
+
+Unless You explicitly state otherwise, any Contribution intentionally submitted 
+for inclusion in the Work by You to the Licensor shall be under the terms and 
+conditions of this License, without any additional terms or conditions. 
+Notwithstanding the above, nothing herein shall supersede or modify the terms 
+of any separate license agreement you may have executed with Licensor regarding 
+such Contributions.
+
+6. Trademarks.
+
+This License does not grant permission to use the trade names, trademarks, 
+service marks, or product names of the Licensor, except as required for 
+reasonable and customary use in describing the origin of the Work and 
+reproducing the content of the NOTICE file.
+
+7. Disclaimer of Warranty.
+
+Unless required by applicable law or agreed to in writing, Licensor provides 
+the Work (and each Contributor provides its Contributions) on an "AS IS" BASIS, 
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied, 
+including, without limitation, any warranties or conditions of TITLE, 
+NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A PARTICULAR PURPOSE. You are 
+solely responsible for determining the appropriateness of using or 
+redistributing the Work and assume any risks associated with Your exercise of 
+permissions under this License.
+
+8. Limitation of Liability.
+
+In no event and under no legal theory, whether in tort (including negligence), 
+contract, or otherwise, unless required by applicable law (such as deliberate 
+and grossly negligent acts) or agreed to in writing, shall any Contributor be 
+liable to You for damages, including any direct, indirect, special, incidental, 
+or consequential damages of any character arising as a result of this License 
+or out of the use or inability to use the Work (including but not limited to 
+damages for loss of goodwill, work stoppage, computer failure or malfunction, 
+or any and all other commercial damages or losses), even if such Contributor 
+has been advised of the possibility of such damages.
+
+9. Accepting Warranty or Additional Liability.
+
+While redistributing the Work or Derivative Works thereof, You may choose to 
+offer, and charge a fee for, acceptance of support, warranty, indemnity, or 
+other liability obligations and/or rights consistent with this License. 
+However, in accepting such obligations, You may act only on Your own behalf and 
+on Your sole responsibility, not on behalf of any other Contributor, and only 
+if You agree to indemnify, defend, and hold each Contributor harmless for any 
+liability incurred by, or claims asserted against, such Contributor by reason 
+of your accepting any such warranty or additional liability.
+
+10. Noncompetition
+
+You may install and execute the Work only in conjunction with the direct use of 
+AppNeta software.  This Work, any file or any derivative thereof shall not be 
+used in conjunction with any product that competes with any AppNeta software.
+
+11. Termination
+
+The License stated above is automatically terminated and revoked if you exceed 
+its scope or violate any of the terms of this License or any related License or 
+notice.
+
+END OF TERMS AND CONDITIONS
+

data/README.md

@@ -0,0 +1,380 @@
+# Welcome to the TraceView Ruby Gem
+
+The traceview gem provides AppNeta [TraceView](http://www.appneta.com/application-performance-management/) performance instrumentation for Ruby.
+
+![Ruby TraceView](https://s3.amazonaws.com/pglombardo/oboe-ruby-header.png)
+
+It has the ability to report performance metrics on an array of libraries, databases and frameworks such as Rails, Mongo, Memcache, ActiveRecord, Cassandra, Rack, Resque [and more](https://docs.appneta.com/ruby-instrumentation-supported-components)
+
+It requires a [TraceView](http://www.appneta.com/products/traceview/) account to view metrics.  Get yours, [it's free](http://www.appneta.com/products/traceview-free-account/).
+
+[![Oboe API Documentation](https://www.omniref.com/ruby/gems/oboe.png)](https://www.omniref.com/ruby/gems/oboe)
+[![Gem Version](https://badge.fury.io/rb/oboe.png)](http://badge.fury.io/rb/oboe)
+[![Build Status](https://travis-ci.org/appneta/oboe-ruby.png?branch=master)](https://travis-ci.org/appneta/oboe-ruby)
+[![Code Climate](https://codeclimate.com/github/appneta/oboe-ruby.png)](https://codeclimate.com/github/appneta/oboe-ruby)
+
+# Installation
+
+The traceview gem is [available on Rubygems](https://rubygems.org/gems/traceview) and can be installed with:
+
+```bash
+gem install traceview
+```
+
+or added to _the end_ of your bundle Gemfile and running `bundle install`:
+
+```ruby
+gem 'traceview'
+```
+
+On Heroku?  Use the `oboe-heroku` gem instead.  It wraps some additional functionality specialized for Heroku.
+
+# Running
+
+## Rails
+
+No special steps are needed to instrument Ruby on Rails.  Once part of the bundle, the traceview gem will automatically detect Rails and instrument on stack initialization.
+
+*Note: Unless you are Heroku, you will still need to decide on your `tracing_mode` depending on whether you are running with an instrumented Apache or nginx in front of your Rails stack.  See below for more details.*
+
+### The Install Generator
+
+The traceview gem provides a Rails generator used to seed an initializer where you can configure and control `tracing_mode` and [other options](https://docs.appneta.com/configuring-ruby-instrumentation)
+
+To run the install generator run:
+
+```bash
+bundle exec rails generate traceview:install
+```
+
+After the prompts, this will create an initializer: `config/initializers/traceview.rb`.
+
+## Sinatra
+
+You can instrument your Sinatra application by adding the following code to your `config.ru` Rackup file:
+
+```ruby
+# If you're not using Bundler.require.  Make sure this is done
+# after the Sinatra require directive.
+require 'traceview'
+
+# When traces should be initiated for incoming requests. Valid options are
+# "always", "through" (when the request is initiated with a tracing header
+# from upstream) and "never". You must set this directive to "always" in
+# order to initiate tracing.
+TraceView::Config[:tracing_mode] = 'through'
+
+# You may want to replace the TraceView.logger with whichever logger you are using
+# TraceView.logger = Sinatra.logger
+```
+
+Note: If you're on Heroku, you don't need to set `tracing_mode` - it will be automatically configured.
+
+Make sure that the traceview gem is loaded _after_ Sinatra either by listing `gem 'traceview'` after Sinatra in your Gemfile or calling the `require 'traceview'` directive after Sinatra is loaded.
+
+With this, the traceview gem will automatically detect Sinatra on boot and instrument key components.
+
+## Padrino
+
+As long as the traceview gem is in your `Gemfile` (inserted after the `gem 'padrino'` directive) and you are calling `Bundler.require`, the traceview gem will automatically instrument Padrino applications.
+
+If you need to set `TraceView::Config` values on stack boot, you can do so by adding the following
+to your `config/boot.rb` file:
+
+```ruby
+Padrino.before_load do
+  # When traces should be initiated for incoming requests. Valid options are
+  # "always", "through" (when the request is initiated with a tracing header
+  # from upstream) and "never". You must set this directive to "always" in
+  # order to initiate tracing.
+  TraceView::Config[:tracing_mode] = 'always'
+end
+```
+
+Note: If you're on Heroku, you don't need to set `tracing_mode` - it will be automatically configured.
+
+## Grape
+
+You can instrument your Grape application by adding the following code to your `config.ru` Rackup file:
+
+```ruby
+    # If you're not using Bundler.require.  Make sure this is done
+    # after the Grape require directive.
+    require 'traceview'
+    
+    # When traces should be initiated for incoming requests. Valid options are
+    # "always", "through" (when the request is initiated with a tracing header
+    # from upstream) and "never". You must set this directive to "always" in
+    # order to initiate tracing.
+    TraceView::Config[:tracing_mode] = 'through'
+    
+    ...
+
+    class App < Grape::API
+      use TraceView::Rack
+    end
+```
+
+Note: If you're on Heroku, you don't need to set `tracing_mode` - it will be automatically configured.
+
+Make sure that the traceview gem is loaded _after_ Grape either by listing `gem 'traceview'` after Grape in your Gemfile or calling the `require 'traceview'` directive after Grape is loaded.
+
+You must explicitly tell your Grape application to use TraceView::Rack for tracing to occur.
+
+## Custom Ruby Scripts & Applications
+
+The traceview gem has the ability to instrument any arbitrary Ruby application or script.  Only the `tracing_mode` needs to be set to tell the traceview gem to initiate performance metric collection.
+
+```ruby
+require 'rubygems'
+require 'bundler'
+
+Bundler.require
+
+require 'traceview'
+
+# Tracing mode can be 'never', 'through' (to follow upstream) or 'always'
+TraceView::Config[:tracing_mode] = 'always'
+```
+
+From here, you can use the Tracing API to instrument areas of code using `TraceView::API.start_trace` (see below).  If you prefer to instead dive directly into code, take a look at [this example](https://gist.github.com/pglombardo/8550713) of an instrumented Ruby script.
+
+Once inside of the `TraceView::API.start_trace` block, performance metrics will be automatically collected for all supported libraries and gems (Redis, Mongo, ActiveRecord etc..).
+
+## Other
+
+You can send deploy notifications to TraceView and have the events show up on your dashboard.  See: [Capistrano Deploy Notifications with tlog](https://docs.appneta.com/capistrano-deploy-notifications-tlog)
+
+# Custom Tracing
+
+## The Tracing API
+
+You can instrument any arbitrary block of code using `TraceView::API.trace`:
+
+```ruby
+# layer_name will show up in the TraceView app dashboard
+layer_name = 'subsystemX'
+
+# report_kvs are a set of information Key/Value pairs that are sent to
+# TraceView dashboard along with the performance metrics.  These KV
+# pairs are used to report request, environment and/or client specific
+# information.
+
+report_kvs = {}
+report_kvs[:mykey] = @client.id
+
+TraceView::API.trace(layer_name, report_kvs) do
+  # the block of code to be traced
+end
+```
+
+`TraceView::API.trace` is used within the context of a request.  It will follow the upstream state of the request being traced.  i.e. the block of code will only be traced when the parent request is being traced.
+
+This tracing state of a request can also be queried by using `TraceView.tracing?`.
+
+If you need to instrument code outside the context of a request (such as a cron job, background job or an arbitrary ruby script), use `TraceView::API.start_trace` instead which will initiate new traces based on configuration and probability (based on the sample rate).
+
+Find more details in the [RubyDoc page](http://rdoc.info/gems/oboe/TraceView/API/Tracing) or in [this example](https://gist.github.com/pglombardo/8550713) on how to use the Tracing API in an independent Ruby script.
+
+## Tracing Methods
+
+By using class level declarations, it's possible to automatically have certain methods on that class instrumented and reported to your TraceView dashboard automatically.
+
+The pattern for Method Profiling is as follows:
+
+```ruby
+# 'profile_name' is similar to a layer name.
+# It identifies this custom trace in your dashboard.
+#
+class Engine
+    include TraceViewMethodProfiling
+
+    def processor()
+        # body of method
+    end
+
+    # call syntax: profile_method <method>, <profile_name>
+    profile_method :processor, 'processor'
+end
+```
+
+This example demonstrates method profiling of instance methods.  Class methods are profiled slightly differently.  See the TraceView [documentation portal](https://docs.appneta.com/custom-ruby-instrumentation) for full details.
+
+# Support
+
+If you find a bug or would like to request an enhancement, feel free to file an issue.  For all other support requests, see our [support portal](https://tickets.appneta.com) or on IRC @ #appneta on [Freenode](http://freenode.net/).
+
+# Contributing
+
+You are obviously a person of great sense and intelligence.  We happily appreciate all contributions to the traceview gem whether it is documentation, a bug fix, new instrumentation for a library or framework or anything else we haven't thought of.
+
+We welcome you to send us PRs.  We also humbly request that any new instrumentation submissions have corresponding tests that accompany them.  This way we don't break any of your additions when we (and others) make changes after the fact.
+
+## Developer Resources
+
+We at AppNeta have made a large effort to expose as much technical information as possible to assist developers wishing to contribute to the traceview gem.  Below are the three major sources for information and help for developers:
+
+* The [TraceView blog](http://www.appneta.com/blog) has a constant stream of great technical articles.  (See [A Gentle X-Trace Introduction](http://www.appneta.com/blog/x-trace-introduction/) for details on the basic methodology that TraceView uses to gather structured performance data across hosts and stacks.)
+
+* The [TraceView Documentation Portal](https://docs.appneta.com/ruby) has a large collection of technical articles or, if needed, you can [submit a support request](https://tickets.appneta.com) directly to the team.
+
+* You can also reach the TraceView team on our IRC channel #appneta on freenode.
+
+If you have any questions or ideas, don't hesitate to contact us anytime.
+
+## Layout of the Gem
+
+The traceview gem uses a standard gem layout.  Here are the notable directories.
+
+    lib/traceview/inst               # Auto load directory for various instrumented libraries
+    lib/traceview/frameworks         # Framework instrumentation directory
+    lib/traceview/frameworks/rails   # Files specific to Rails instrumentation
+    lib/rails                        # A Rails required directory for the Rails install generator
+    lib/api                          # The TraceView Tracing API: layers, logging, profiling and tracing
+    ext/oboe_metal                   # The Ruby c extension that links against the system liboboe library
+
+## Building the Gem
+
+The traceview gem is built with the standard `gem build` command passing in the gemspec:
+
+```bash
+gem build traceview.gemspec
+```
+
+## Writing Custom Instrumentation
+
+Custom instrumentation for a library, database or other service can be authored fairly easily.  Generally, instrumentation of a library is done by wrapping select operations of that library and timing their execution using the TraceView Tracing API which then reports the metrics to the users' TraceView dashboard.
+
+Here, I'll use a stripped down version of the Dalli instrumentation (`lib/traceview/inst/dalli.rb`) as a quick example of how to instrument a client library (the dalli gem).
+
+The Dalli gem nicely routes all memcache operations through a single `perform` operation.  Wrapping this method allows us to capture all Dalli operations called by an application.
+
+First, we define a module (TraceView::Inst::Dalli) and our own custom `perform_with_traceview` method that we will use as a wrapper around Dalli's `perform` method.  We also declare an `included` method which automatically gets called when this module is included by another.  See ['included' Ruby reference documentation](https://www.omniref.com/ruby/2.2.1/symbols/Module/included).
+
+```ruby
+module TraceView
+  module Inst
+    module Dalli
+      include TraceView::API::Memcache
+
+      def self.included(cls)
+        cls.class_eval do
+          if ::Dalli::Client.private_method_defined? :perform
+            alias perform_without_traceview perform
+            alias perform perform_with_traceview
+          end
+        end
+      end
+
+      def perform_with_traceview(*all_args, &blk)
+        op, key, *args = *all_args
+
+        if TraceView.tracing?
+          opts = {}
+          opts[:KVOp] = op
+          opts[:KVKey] = key
+
+          TraceView::API.trace('memcache', opts || {}) do
+            result = perform_without_traceview(*all_args, &blk)
+            if op == :get and key.class == String
+                TraceView::API.log('memcache', 'info', { :KVHit => memcache_hit?(result) })
+            end
+            result
+          end
+        else
+          perform_without_traceview(*all_args, &blk)
+        end
+      end
+    end
+  end
+end
+```
+
+Second, we tail onto the end of the instrumentation file a simple `::Dalli::Client.module_eval` call to tell the Dalli module to include our newly defined instrumentation module.  Doing this will invoke our previously defined `included` method.
+
+```ruby
+if defined?(Dalli) and TraceView::Config[:dalli][:enabled]
+  ::Dalli::Client.module_eval do
+    include TraceView::Inst::Dalli
+  end
+end
+```
+
+Third, in our wrapper method, we capture the arguments passed in, collect the operation and key information into a local hash and then invoke the `TraceView::API.trace` method to time the execution of the original operation.
+
+The `TraceView::API.trace` method calls Dalli's native operation and reports the timing metrics and your custom `report_kvs` up to TraceView servers to be shown on the user's dashboard.
+
+That is a very quick example of a simple instrumentation implementation.  If you have any questions, visit us on IRC in #appneta on Freenode.
+
+Some other tips and guidelines:
+
+* You can point your Gemfile directly at your cloned traceview gem source by using `gem 'traceview', :path => '/path/to/oboe-ruby'`
+
+* If instrumenting a library, database or service, place your new instrumentation file into the `lib/traceview/inst/` directory.  From there, the traceview gem will detect it and automatically load the instrumentation file.
+
+* If instrumenting a new framework, place your instrumentation file in `lib/traceview/frameworks`.  Refer to the Rails instrumentation for on ideas on how to load the traceview gem correctly in your framework.
+
+* Review other existing instrumentation similar to the one you wish to author.  `lib/traceview/inst/` is a great place to start.
+
+* Depending on the configured `:sample_rate`, not all requests will be traced.  Use `TraceView.tracing?` to determine of this is a request that is being traced.
+
+* Performance is paramount.  Make sure that your wrapped methods don't slow down users applications.
+
+* Include tests with your instrumentation.  See `test/instrumentation/` for some examples of existing instrumentation tests.
+
+## Compiling the C extension
+
+The traceview gem utilizes a C extension to interface with the system `liboboe.so` library.  This system library is installed with the TraceView host packages (tracelyzer, liboboe0, liboboe-dev) and is used to report [host](http://www.appneta.com/blog/app-host-metrics/) and performance metrics from multiple sources (Ruby, Apache, Python etc.) back to TraceView servers.
+
+C extensions are usually built on `gem install` but when working out of a local git repository, it's required that you manually build this C extension for the gem to function.
+
+To make this simpler, we've included a few rake tasks to automate this process:
+
+```bash
+rake compile             # Build the gem's c extension
+rake distclean           # Remove all built files and extensions
+rake recompile           # Rebuild the gem's c extension
+```
+
+Note: Make sure you have the development package `liboboe0-dev` installed before attempting to compile the C extension.
+
+```bash
+>$ dpkg -l | grep liboboe
+ii  liboboe-dev    1.1.1-precise1    Tracelytics common library -- development files
+ii  liboboe0       1.1.1-precise1    Tracelytics common library
+```
+
+See [Installing Base Packages on Debian and Ubuntu](https://docs.appneta.com/installation-overview) in the Knowledge Base for details.  Our hacker extraordinaire [Rob Salmond](https://github.com/rsalmond) from the support team has even gotten these packages to [run on Gentoo](http://www.appneta.com/blog/unsupported-doesnt-work/)!
+
+To see the code related to the C extension, take a look at `ext/oboe_metal/extconf.rb` for details.
+
+You can read more about Ruby gems with C extensions in the [Rubygems Guides](http://guides.rubygems.org/gems-with-extensions/).
+
+## Running the Tests
+
+The tests bundled with the gem are implemented using [Minitest](https://github.com/seattlerb/minitest).  The tests are currently used to validate the sanity of the traces generated and basic gem functionality.
+
+After a bundle install, the tests can be run as:
+
+```bash
+bundle exec rake test
+```
+
+This will run a full end-to-end test suite that covers all supported libraries and databases.  Note that this requires all of the supported software (Cassandra, Memcache, Mongo etc.) to be installed, configured and available.
+
+Since this is overly burdensome for casual users, you can run just the tests that you're interested in.
+
+To run just the tests for the dalli gem trace validation:
+
+```bash
+bundle exec rake test TEST=test/instrumentation/dalli_test.rb
+```
+
+We humbly request that any submitted instrumentation is delivered with corresponding test coverage.
+
+# License
+
+Copyright (c) 2014 Appneta
+
+Released under the [AppNeta Open License](http://www.appneta.com/appneta-license), Version 1.0
+