dm-cutie 0.3.16

data/LICENSE

@@ -0,0 +1,19 @@
+Copyright (C) 2009, Cory ODaniel 
+
+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: 
+
+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.

data/README.markdown

@@ -0,0 +1,352 @@
+Project Description
+===================
+dm-cutie - The 'cutie' stands for Query Tracking.  She is super thorough and easy as hell, just the way you like it.
+
+Tracks queries that are executed by DataMapper.  Models can be optionally excluded from tracking. Cutie currently only supports DataObjects Adapters.
+
+
+
+Quickstart- The whole caboodle.
+===============================
+There are two major pieces to the Cutie Project. 
+
+  * dm-cutie - the query tracking portion - this gets installed 'in your app'
+  * dm-cutie-ui - A sinatra app that can connect to your dm-cutie repo and provide statisics.
+  
+Installing the query tracker (dm-cutie)
+    $ gem sources -a http://gemcutter.org # Add gem cutter to your gem sources
+    $ gem install dm-cutie
+    $ gem install dm-cutie-extras # This is a plugin pack for dm-cutie
+    $ gem install dm-cutie-ui     # this is the front-end to dm-cutie
+
+
+Adding it to your projects
+    # Somewhere after your DataMapper repositories are setup
+    require 'dm-cutie'
+    DataMapper::Cutie.enable_adapter :data_objects
+
+    # If you want some extras, sorry its Mysql centric, its what Im primarily familiar with
+    # require 'dm-cutie-extras'
+    #
+    # # Query Plan for Sqlite3
+    # DataMapper::Cutie::Extras.load :sqlite3_execution_step
+    #
+    # # Query Plan for Mysql
+    # DataMapper::Cutie::Extras.load :mysql_execution_step
+    #
+    # # Mysql Index information
+    # DataMapper::Cutie::Extras.load :mysql_index
+    #
+    # # Mysql warnings & errors
+    # DataMapper::Cutie::Extras.load :mysql_warning
+    #
+
+    DataMapper::Cutie.setup do |c|
+      # The name of the datamapper repository to store dm cutie tracked data in.
+      #   If you are using something like mysql make sure that you created the schema
+      #   
+      c[:repo_name]       = :dm_cutie 
+  
+      # List of any models in YOUR application that you want dm-cutie to ignore
+      c[:exclude_models]  = false #[:person, :car]
+  
+      # List of models you want dm-cutie to specifically track
+      c[:only_models]     = false #[:article, :address]
+  
+      # What you consider a slow query
+      c[:slow_query_length] = 2
+    end
+
+    # passing true will tell dm-cutie to force a migration of all of HER models.
+    #   she will always do a migration if she can't find her tables. In a development
+    #   environment it is recommended to pass 'true' as your DataMapper models are probably
+    #   changing often and there for should be re-profiled.
+    DataMapper::Cutie.start(true)
+
+    # If you are doing long term tracking in a production environment you will want to pass
+    #   'false'  DM cutie will still migrate her tables the first time to make sure everything
+    #   is set up correctly. PS, dm-cutie causes TONS of queries to be executed to adequatly track
+    #   what is going on in your application.  It would be recommended to only use her in development
+    #   and staging environments.
+    # DataMapper::Cutie.start(false)
+
+Starting the dm-cutie-ui sinatra app
+    # A bin file should have been included with the gem
+    #
+    # Want to see options? 
+    #   dm-cutie-ui --help
+    #
+    # The default port is 4567
+    $ dm-cutie-ui
+
+Log into dm-cutie-ui
+  
+  * Go to http://localhost:4567 #or whatever port you used
+  * Enter the path to your dm-cutie repo # mysql://root@localhost/dm-cutie
+  * Click 'connect' or enter a password if the account you are connecting with needs a password
+  * Learn?
+
+
+How It Works
+============
+DM Cutie overrides DataObjectsAdapters and puts in some hooks to track queries. Cutie uses four models to store information about queries
+  
+  * GeneralizedQuery - This is a query without variables bound to it
+    * Example: Person.first(:email => "user@example.com") would be stored as "SELECT * FROM `people` WHERE `email` = ?"
+    * This query will be unique to this table.
+    * Useful for determine how many generic queries are being generated by your application
+  * ExecutedQuery - This is a query WITH variables bound to it
+    * Example: Person.first(:email => "user@example.com") would be stored as "SELECT * FROM `people` WHERE `email` = 'user@example.com'"
+    * EVERY executed statement is stored in this table, executed statements do not have a unique constraint.
+    * This table has a foreign Key to GeneralizedQuery, so you can determine which ExecutedQuery objects are related
+      * Example: Person.first(:email => "user@example.com") and Person.first(:email => "person@example.com")
+      * Both ExecutedQuery objects would relate back to the GeneralizedQuery, Person.first(:email => ?) ("SELECT * FROM `people` WHERE `email` = ?")
+    * This also stores the line number and file name of the caller.
+  * RepositoryStorage - This keeps track of all storages (tables) across repositories.
+    * UnboundQueries 'belong' to RepositoryStorages through QueryStorageLink
+    * Example:
+      * if you have a Person model that is stored in a YAML repository that would be one RepositoryStorage
+      * if you have a Person model that is stored in a MySQL repostiroy that would be an additional RepositoryStorage
+      * UnboundQueries directed at MySQL for the Person model would be related to the MySQL Person RepositoryStorage object
+  * QueryStorageLink - ties a RepositoryStorage
+    * Denotes whether a RepositoryStorage was the 'primary storage' for a query
+    * The primary storage is determine by the Repository#name and Repository#adapter of the query object
+    * Other QueryStorageLinks on an GeneralizedQuery are a result of relationships that are stored in the Query#links
+
+    
+Important
+=========
+DM Cutie generates a ton of queries itself to track what is going on in DataMapper.  It would be wise to use it to only to track your queries in a Staging or Development environment or temporarily in production.
+
+DM Cutie essentially records a 'snapshot' of everything that happened in your applications repository.
+
+
+Usage
+=======
+    require 'dm-cutie' 
+    
+    # Load the hook for the adapter you want to track
+    DataMapper::Cutie.enable_adapter :data_objects
+
+    #note, these haven't been written yet
+    # DataMapper::Cutie.enable_adapter :yaml 
+    # DataMapper::Cutie.enable_adapter :in_memory
+    
+    # Optional
+    DataMapper::Cutie.setup do |c|
+      # The repo to use to store Cutie's data in
+      c[:repo_name]                  = :dm_cutie
+      
+      # Models to always exclude from tracking
+      c[:exclude_models]            = false #[:person, :car]
+      
+      # Models to only tracker
+      c[:only_models]               = false #[:article, :address]
+      
+      # Time in seconds you consider a query to be slow
+      c[:slow_query_length]         = 2
+    end
+
+    DataMapper::Cutie.start
+    
+    
+Adapter Trackers vs Tracker Hooks
+====================================
+    
+  * Adapter Trackers are the basic trackers for a specific adapter (DataObjectsAdapter, MySQLAdapter, etc)
+    * Provide the basic functionality to 'capture' a query in progress and the basic storage of details in ExecutedQuery, GeneralizedQuery, RepositoryStorage, and QueryStorageLink
+    * Currently this is NOT DRY and is a bit hostile, as it literally reimplements the CRUD layer methods in DO
+  * Tracker Hooks allow you to create additional storages for details that are outside the basic 4 models included in Cutie
+    * Example: All SQL queries have a RepositoryStorage (the tables in the FROM statement), but only a MySQL query would have a MySQL execution plan, so you can have a Tracker Hook that will only store MySQL Execution plans if its the mysql adapter
+    * Allow you to perform logic on an 'executed query'
+
+
+Enabling Tracker Hooks
+=========================
+
+A project of tracker hooks exists called dm-cutie-extras.
+
+    require 'dm-cutie'
+    DataMapper::Cutie.enable_adapter :data_objects
+    
+    # Simply require the additional trackers
+    require 'dm-cutie-extras'
+    DataMapper::Cutie::Extras.load :mysql_execution_step
+    DataMapper::Cutie::Extras.load :sqlite3_execution_step
+
+    DataMapper::Cutie.start(true)
+    
+    
+Currently included are:
+
+  * MySQL Execution Step - Runs a query plan for MySQL queries
+  * Sqlite3 Execution Step - Runs a query plan for Sqlite3 queries
+
+
+Writing Tracker Hooks
+=========================
+To write a tracker simply include DataMapper::Cutie::Tracker::Hook::Abstract into a class and define a few methods
+    class MyTrackerHook
+      include DataMapper::Cutie::Tracker::Hook::Abstract
+      
+      # The name of your hook
+      def self.hook_name
+        "Really cool hook"
+      end
+      
+      # the statements this tracker applies to
+      def self.supported_statements
+        [:select]
+      end
+      
+      # The adapters this tracker applies to
+      def self.suppored_adapters
+        [:mysql]
+      end
+      
+      # This is a factory method that will run your tracking logic
+      # this method will receive the current ExecutedQuery
+      #
+      def self.track( executed_query )
+        # Your tracking logic goes here
+      end
+    end
+
+Then let Cutie know she has a new hook to work with
+    DataMapper::Cutie.add_tracker_hook :my_tracker_hook #Symbol representation of your class name
+    
+Example "Hi Mom! Tracker Hook" - Sends mom an email telling her what SELECT statements where ran
+  
+    class HiMomTrackerHook
+      include DataMapper::Cutie::Tracker::Hook::Abstract
+  
+      # The name of your hook
+      def self.hook_name
+        "Hi Mom! Tracker hook"
+      end
+  
+      # the statements this tracker applies to
+      def self.supported_statements
+        [:select]
+      end
+  
+      # The adapters this tracker applies to
+      def self.suppored_adapters
+        [:mysql]
+      end
+  
+      def self.track( executed_query )
+        # This is an absolutely awesome tracker, because my mom can optimize the heck out of a query.
+      
+        my_cool_mail_method(
+          :to => "mom@example.com",
+          :from => "yourlovingchild@example.com",
+          :subject => "my friends are reading my data",
+          :body => "My friend just executed this query: #{executed_query.generalized_query.statement}"
+        )
+      end
+    end
+
+    # Of course tell cutie she has a new hook
+    DataMapper::Cutie.add_tracker_hook :hi_mom_tracker_hook
+    
+  
+Example "Which Server Executed What" - Keeps track of what Application server sent the query
+    # Create a model to store server names in    
+    class QueryingServer    
+      require 'socket'
+      include DataMapper::Cutie::Tracker::Hook::Abstract
+            
+      include DataMapper::Resource
+      has n, :executed_queries
+      
+      property :id, Serial
+      property :name, String, :unique_index => true
+          
+      def self.hook_name
+        "Which Server Executed A Query Hook"
+      end
+  
+      def self.supported_statements
+        [:select, :insert, :update, :delete]
+      end
+  
+      def self.suppored_adapters
+        [:mysql]
+      end
+  
+      def self.track( executed_query )
+        DataMapper::Cutie.repo do #get access to the Cutie's repo (you can store this wherever, probably makes sense here though)
+      
+          trans = DataMapper::Transaction.new #start a transaction (optional)
+      
+          trans.link do 
+            querying_server = QueryingServer.first_or_create(:name => Socket.gethostname)
+            querying_server.executed_queries << executed_query
+            querying_server.save
+          end
+        
+        end
+      end
+      
+    end
+    
+    # Let ExecutedQuery know its getting a new column :P
+    ExecutedQuery.send :belongs_to, :querying_server
+    
+    # Of course let cutie know she has a new hook
+    DataMapper::Cutie.add_tracker_hook :querying_server
+      
+    # Here we have one other concern, we've created a new model: QueryingServer.  We want Cutie to treat this model as an internal model, so she doesn't track it (which would cause an infinite loop)
+    DataMapper::Cutie.add_internal_model :querying_server    
+
+
+Tracker hooks don't have to be a model, but they can be.
+    
+The #track method receives a ExecutedQuery object.  Here are some methods available on that object
+  
+    executed_query.generalized_query  #The GeneralizedQuery object
+    executed_query.statement      #The bound SQL Statement
+    executed_query.generalized_query.statement #The generalized SQL Statement
+    executed_query.bind_values    #The bind values for the SQL Statement
+    # etc... Everything that is available on a DataMapper::Query object
+  
+
+Writing an Adapter Tracker
+==================
+
+Trackers should 'hook' around the method that is to be tracked.  In the DataObjectsTracker example
+the methods being tracked are
+
+  * select_statement
+  * insert_statement
+  * update_statement
+  * delete_statement
+  
+A model that is performing a crud action will only be tracked if the adapter of the repository that the action
+is happening in is based on the DO Adapter.
+
+
+TODOS
+=====
+  * Model.all => Doesnt track -> Probably need to add an override to Collection class
+  * Rspecs, convert test_script.rb to specs
+  
+  * Format documentation for rdoc/yard whatever.
+  * is there an easier way to 'hi jack' something at the DO Adapter level other than making the code unDRY in /tracker/data_objects/overrides
+    * Tried using extlib hooks, but needed access to local variables in the DO CRUD methods
+      
+  * Namespace the Models so they dont interfere with anyones code if they have the same model names.
+  * Tracker hooks trackers should automatically be stored in DataMapper::Cutie.repo instead of having to explicitly call it
+  * Spot Tracking => Cutie.track{...statements...}  #So you can track a specific area, rather than the whole system
+
+CONSIDERATIONS
+===============
+
+ * Should this be pushed back to the DO level?  
+  * I like using DM to access data... also the potential to track DM Sphinx, etc
+  * Its highly geared toward SQL, can it be abstracted
+  * use CRUD operations instead of :select, :insert, :update, :delete
+ * Get self.default_respository_name to work so all CUTIE queries dont have to be done in Cutie.repo block
+  * class_eval def self.default_repository_name; #{THE_NAME}; end;
+ * Add ability to exclude/include repositories.  You might have 3 MySQL repos, and are tracking the DO adapter, but are only interested in a particular database

data/Rakefile

@@ -0,0 +1,103 @@
+require 'rubygems'
+require 'rake/gempackagetask'
+require 'rubygems/specification'
+require 'date'
+require "extlib"
+
+require 'rake'
+require 'rake/clean'
+require 'spec/rake/spectask'
+require "spec"
+require 'rake/rdoctask'
+require 'rake/gempackagetask'
+
+ROOT    = Pathname(__FILE__).dirname.expand_path
+require ROOT + 'lib/dm-cutie/version'
+
+@spec = Gem::Specification.new do |s|
+  s.name = %q{dm-cutie}
+  s.version = DataMapper::Cutie::VERSION
+
+  s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
+  s.authors     = ["Cory ODaniel"]
+  s.date        = %q{2009-10-15}
+  s.summary     = %q{DataMapper's Original Query Tracker'}
+  s.description = %q{DataMapper's Query Tracker; She is super thorough and easy as hell, just the way you like it.}
+
+  s.email = %q{cutie@coryodaniel.com}
+
+  s.extra_rdoc_files = ["README.markdown", "LICENSE", "History.txt"]
+  s.files = ["LICENSE", "README.markdown", "Rakefile",  
+    "lib/dm-cutie.rb",
+    "lib/dm-cutie/cutie.rb",
+    "lib/dm-cutie/version.rb",    
+    
+    "lib/dm-cutie/models/executed_query.rb",
+    "lib/dm-cutie/models/query_storage_link.rb",
+    "lib/dm-cutie/models/repository_storage.rb",
+    "lib/dm-cutie/models/generalized_query.rb",
+    
+    "lib/dm-cutie/tracker/data_objects.rb",
+    "lib/dm-cutie/tracker/data_objects/helper.rb",
+    "lib/dm-cutie/tracker/data_objects/overrides.rb",
+
+    "lib/dm-cutie/tracker/hook/abstract.rb"
+      
+    ]
+  s.add_dependency "extlib",">=0.9.12"   
+  s.add_dependency "dm-core",  '>=0.10.0'
+  s.add_dependency "dm-types",  '>=0.10.0'
+  s.has_rdoc = true
+  s.homepage = "http://github.com/coryodaniel/dm-cutie"
+  s.require_paths = ["lib"]
+  s.rubygems_version = %q{1.2.0}
+end
+
+[ ROOT, ROOT.parent ].each do |dir|
+  Pathname.glob(dir.join('tasks/**/*.rb').to_s).each { |f| require f }
+end
+
+NAME = @spec.name
+GEM_VERSION = DataMapper::Cutie::VERSION
+
+Rake::GemPackageTask.new(@spec) do |pkg|
+  pkg.gem_spec = @spec
+end
+
+desc "install the plugin locally"
+task :install => [:package] do
+  sh %{sudo gem install #{install_home} pkg/#{NAME}-#{GEM_VERSION} --no-update-sources}
+end
+
+desc "create a gemspec file"
+task :make_spec do
+  File.open("#{NAME}.gemspec", "w") do |file|
+    file.puts @spec.to_ruby
+  end
+end
+
+Rake::RDocTask.new do |rdoc|
+  files = ["README.markdown", "History.txt", "LICENSE", "lib/**/*.rb"]
+  rdoc.rdoc_files.add(files)
+  rdoc.main = "README.markdown"
+  rdoc.title = "DM Cutie"
+
+  rdoc.rdoc_dir = "doc/rdoc"
+  rdoc.options << "--line-numbers" << "--inline-source"
+end
+
+Spec::Rake::SpecTask.new do |t|
+  t.spec_files = Dir["./spec/**/*_spec.rb"]
+  t.spec_files.unshift './spec/spec_helper.rb'
+  
+  t.libs = ['lib']
+  t.spec_opts << "--color" << "--format" << "specdoc" #"progress"
+  
+  if ENV['RCOV']
+    t.rcov = true
+    t.rcov_opts << '--exclude' << 'pkg,spec,interactive.rb,install_test_suite.rb,lib/gems,' + Gem.path.join(',')
+    t.rcov_opts << '--text-summary'
+    t.rcov_opts << '--sort' << 'coverage' << '--sort-reverse'
+    t.rcov_opts << '--only-uncovered'
+  end
+end