rails-dtrace 0.0.1 → 0.0.2

data/.gitignore

@@ -15,3 +15,4 @@ spec/reports
 test/tmp
 test/version_tmp
 tmp
+.DS_Store

data/LICENSE

@@ -1,22 +1,13 @@
 Copyright (c) 2012 Eric Saxby
 
-MIT License
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
 
-Permission is hereby granted, free of charge, to any person obtaining
-a copy of this software and associated documentation files (the
-"Software"), to deal in the Software without restriction, including
-without limitation the rights to use, copy, modify, merge, publish,
-distribute, sublicense, and/or sell copies of the Software, and to
-permit persons to whom the Software is furnished to do so, subject to
-the following conditions:
+   http://www.apache.org/licenses/LICENSE-2.0
 
-The above copyright notice and this permission notice shall be
-included in all copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
-EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
-MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
-NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
-LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
-OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
-WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.

data/README.md

@@ -5,11 +5,15 @@ instruments in Rails, turning them into DTrace probes.
 
 ## Requirements
 
+Rails > 3.0
+
 An OS that supports DTrace. For example:
 * MacOS X
 * Illumos
 * SmartOS
 * Solaris
+* BSD
+* Oracle Linux ?
 
 ## Installation
 
@@ -27,6 +31,17 @@ And then execute:
 $ bundle
 ```
 
+If you are using edge Rails (master/4.0), the notification syntax has
+changed in an awesome way. In this case, you'll want the `rails_4`
+branch.
+
+```ruby
+gem 'ruby-usdt', :git => 'git://github.com/chrisa/ruby-usdt.git',
+        :submodules => true, :branch => 'disable_provider'
+gem 'rails-dtrace', :git => 'git://github.com/sax/rails-dtrace.git',
+        :branch => 'rails_4'
+```
+
 ## Warning
 
 This gem in an experiment in progress. The code does not have automated
@@ -42,26 +57,77 @@ tests around this gem) these warnings will disappear.
 ## Usage
 
 Once you add the gem to your Rails application, it will automatically
-subscribe to all notifications, turning them into DTrace probes. The
-arguments to the probes will be:
+subscribe to all notifications, turning them into DTrace probes. 
+
+Note that notifications are lazy-loaded, so even though rails-dtrace subscribes to all available instruments, they will only be converted to probes as they fire in Rails code. For this reason, in order to get a full picture of what is happening in a Rails process, enough load should be generated to ensure that all important probes are registered before tracing.
+
+### Rails 3
 
-* `arg0` - Start time of notification - Integer
-* `arg1` - End time of notification - Integer
-* `arg2` - Unique identifier of notification - String
-* `arg3` - Stringified hash of notification payload - String
+Arguments to probes are:
+
+* `arg0` - Unique identifier of notification - String
+* `arg1` - Stringified hash of notification payload - String
+* `arg2` - Nanoseconds between start and finish of event - Integer
+
+The notification name is turned into the probe function, and the probe name is defined as 'event'. For instance, `sql.active_record` becomes `ruby*:rails:sql.active_record:event`. This is to make events somewhat compatible with the edge Rails method of firing events, described below.
+
+Some operating systems (MacOS X, I'm looking at you) don't give you nanosecond time resolution. In this case you get microseconds multipled by 1000.
 
 The following dtrace command can be used, as an example:
 
 ```bash
-sudo dtrace -n 'ruby*:rails:: { printf("%d %d %s %s", arg0, arg1,
-  copyinstr(arg2), copyinstr(arg3)) }'
+sudo dtrace -n 'ruby*:rails:sql.active_record: { 
+  printf(
+    "%s \n\t %s \n\t %d", 
+    copyinstr(arg0), copyinstr(arg1),
+    arg2
+  )
+}'
+```
+
+Example output:
+
+```
+  1  15407  sql.active_record:event 4595e4d30b17bdb96fe9 
+	 {:sql=>"SELECT \"things\".* FROM \"things\" ", :name=>"Thing Load", :connection_id=>70184895988280, :binds=>[]} 
+	 238000
+```
+
+
+### Rails 4 / Edge Rails
+
+Note that you need to use the `rails_4` branch in order for this to work. In newer Rails, notifications become more dtrace-like. Rather than a notification sending a message to `#call` (which gets start time and end time), they can send two messages, `#start` and `#finish`. This way, you can do your own math on the notifications.
+
+In *rails-dtrace*, the notification name becomes the probe function, and we map `start -> entry` and `finish -> exit`.
+
+If a notification subscriber responds to #call, ActiveSupport::Notifications will send methods in the Rails 3 way. For this reason the rails-dtrace code is incompatible at this time. It could conceivably be done with some metaprogramming to trick the Rails framework, but I'd prefer to keep the rails-dtrace code small and readable.
+
+Arguments to probes are:
+
+* `arg0` - Unique identifier of notification - String
+* `arg1` - Stringified hash of notification payload - String
+
+The following dtrace command can be used, as an example:
+
+```bash
+sudo dtrace -n 'ruby*:rails:sql.active_record: { 
+  printf(
+    "%s \n\t %s", 
+    copyinstr(arg0),
+    copyinstr(arg1)
+  )
+}'
+```
+
+Example output:
+
+```
+3  52609  sql.active_record:entry a392841cfd75a132432e 
+	 {:sql=>"SELECT \"things\".* FROM \"things\" ", :name=>"Thing Load", :connection_id=>70362294355260, :binds=>[]}
+3  52610  sql.active_record:exit a392841cfd75a132432e 
+	 {:sql=>"SELECT \"things\".* FROM \"things\" ", :name=>"Thing Load", :connection_id=>70362294355260, :binds=>[]}
 ```
 
-Notifications are lazy-loaded, so even though rails-dtrace subscribes to
-all available instruments, they will only be converted to probes as
-they fire in Rails code. For this reason, in order to get a full picture
-of what is happening in a Rails process, enough load should be generated
-to ensure that all important probes are registered before tracing.
 
 ## Contributing
 
@@ -74,17 +140,13 @@ to ensure that all important probes are registered before tracing.
 ## Suggestions for Contributions
 
 * How the F do you test this thing?
-* Can Rails instruments be detected at initialization time?
-* Notifications do start/end in one instrument. DTrace probes tend to
-  fire multiple probes, on entry and exit. This lets you write scripts
-  to do neat analytics on event timing. Can Notifications be hacked to
-  do this?
-* The Responder turns the Notification payload (a hash) into a string.
+* Can Rails instruments be detected at initialization time to register all probes at once?
+* The Subscriber turns the Notification payload (a hash) into a string.
   This can surely be better.
 
 ## License
 
-Copyright 2012 Eric Saxby
+Copyright (c) 2012 Eric Saxby
 
 Licensed under the Apache License, Version 2.0 (the "License");
 you may not use this file except in compliance with the License.

data/lib/rails-dtrace/railtie.rb

@@ -2,8 +2,7 @@ module DTrace
   class Railtie < Rails::Railtie
 
     initializer 'railtie.configure_rails.initialization' do
-      DTrace::Responder.logger = Rails.logger
-      ActiveSupport::Notifications.subscribe(/.*/, DTrace::Responder)
+      ActiveSupport::Notifications.subscribe(/.*/, DTrace::Subscriber)
     end
   end
 end

data/lib/rails-dtrace/subscriber.rb

@@ -0,0 +1,71 @@
+require 'usdt'
+
+module DTrace
+  class Subscriber
+    cattr_reader :probes, :provider
+
+    @@provider = USDT::Provider.create :ruby, :rails
+    @@probes = {}
+    @@enabled = false
+
+    class << self
+      def logger
+        @logger ||= Rails.logger if defined?(Rails)
+      end
+
+      attr_writer :logger
+
+      # Rails 3.x define instruments as blocks that wrap code. When the code
+      # finishes executing, subscribers are called with the start and end time.
+
+      def call(notification, start_time, end_time, id, payload)
+        fire_probe(notification, id, payload, 'event', start_time, end_time)
+      end
+
+      # Rails 4.x defines instruments in a different way, where #start is called
+      # when the block begins and #finish is called when the block ends.
+
+      def start(notification, id, payload)
+        fire_probe(notification, id, payload, 'entry')
+      end
+
+      def finish(notification, id, payload)
+        fire_probe(notification, id, payload, 'exit')
+      end
+
+      protected
+
+      def find_or_create_probe(probe_func, probe_name)
+        probe_id = "#{probe_func}::#{probe_name}"
+
+        unless probes.keys.include?(probe_id)
+          probe = provider.probe(probe_func, probe_name, :string, :string, :integer)
+          probes[probe_id] = probe
+
+          logger.debug "Adding DTrace probe: #{probe_id}"
+
+          provider.disable if @@enabled
+          provider.enable
+          @@enabled = true
+        end
+
+        probes[probe_id]
+      end
+
+      private
+
+      def fire_probe(notification, id, payload, type, start_time = nil, end_time = nil)
+        probe = find_or_create_probe(notification, type)
+
+        if probe.enabled?
+          probe.fire id, payload.inspect, nsec_time_diff(start_time, end_time)
+        end
+      end
+
+      def nsec_time_diff(start_time, end_time)
+        return 0 unless start_time and end_time
+        ((end_time - start_time) * 1000000000).to_i
+      end
+    end
+  end
+end

data/lib/rails-dtrace/version.rb

@@ -1,3 +1,3 @@
 module Dtrace
-  VERSION = "0.0.1"
+  VERSION = "0.0.2"
 end

data/lib/rails-dtrace.rb

@@ -1,4 +1,4 @@
 require "rails-dtrace/version"
-require "rails-dtrace/responder"
+require "rails-dtrace/subscriber"
 
 require 'rails-dtrace/railtie' if defined?(Rails)

data/rails-dtrace.gemspec

@@ -6,7 +6,7 @@ Gem::Specification.new do |gem|
   gem.email         = ["sax@livinginthepast.org"]
   gem.description   = %q{Turn ActiveSupport::Notification instruments into DTrace probes. This allows you to trace Rails apps.}
   gem.summary       = %q{Add DTrace probes to Rails}
-  gem.homepage      = ""
+  gem.homepage      = "https://github.com/sax/dtrace-rails"
 
   gem.files         = `git ls-files`.split($\)
   gem.executables   = gem.files.grep(%r{^bin/}).map{ |f| ::File.basename(f) }

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: rails-dtrace
 version: !ruby/object:Gem::Version
-  version: 0.0.1
+  version: 0.0.2
   prerelease: 
 platform: ruby
 authors:
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2012-08-09 00:00:00.000000000 Z
+date: 2012-08-12 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: ruby-usdt
@@ -59,11 +59,11 @@ files:
 - Rakefile
 - lib/rails-dtrace.rb
 - lib/rails-dtrace/railtie.rb
-- lib/rails-dtrace/responder.rb
+- lib/rails-dtrace/subscriber.rb
 - lib/rails-dtrace/version.rb
 - rails-dtrace.gemspec
 - spec/spec_helper.rb
-homepage: ''
+homepage: https://github.com/sax/dtrace-rails
 licenses: []
 post_install_message: 
 rdoc_options: []
@@ -75,23 +75,18 @@ required_ruby_version: !ruby/object:Gem::Requirement
   - - ! '>='
     - !ruby/object:Gem::Version
       version: '0'
-      segments:
-      - 0
-      hash: 1821254754778372356
 required_rubygems_version: !ruby/object:Gem::Requirement
   none: false
   requirements:
   - - ! '>='
     - !ruby/object:Gem::Version
       version: '0'
-      segments:
-      - 0
-      hash: 1821254754778372356
 requirements: []
 rubyforge_project: 
-rubygems_version: 1.8.23
+rubygems_version: 1.8.24
 signing_key: 
 specification_version: 3
 summary: Add DTrace probes to Rails
 test_files:
 - spec/spec_helper.rb
+has_rdoc: 

data/lib/rails-dtrace/responder.rb

@@ -1,41 +0,0 @@
-require 'usdt'
-
-=begin
-
-Problems:
-* How do you dynamically enable/disable probes?
-* Split name on '.' sucks
-* Notifications include entry AND exit. Can we fire our own entry/exit probes?
-
-=end
-
-module DTrace
-  class Responder
-    cattr_reader :probes, :provider
-    cattr_writer :logger
-
-    @@provider = USDT::Provider.create :ruby, :rails
-    @@probes = {}
-    @@enabled = false
-
-    def self.logger
-      @@logger || Logger.new
-    end
-
-    def self.call(name, started, finished, unique_id, payload)
-      unless probes.keys.include?(name)
-        func_name, probe_name = name.split('.')
-        p = @@provider.probe(func_name, probe_name, :integer, :integer, :string, :string)
-        probes[name] = p
-        logger.debug "Adding dtrace probe: #{name}"
-        @@provider.disable if @@enabled
-        @@provider.enable
-        @@enabled = true
-      end
-
-      if probes[name].enabled?
-        probes[name].fire(started.to_i, finished.to_i, unique_id, payload.inspect)
-      end
-    end
-  end
-end