chrome_debugger 0.0.1

data/CHANGELOG

@@ -0,0 +1,2 @@
+v0.0.1 (XXX)
+- initial release

data/README.md

@@ -0,0 +1,59 @@
+# Chrome Debugger
+
+Ever wanted to capture stats (#requests, onload time, etc.) about the state of your frontend? Us too!
+Chrome Debugger uses the remote debugging protocol in Chrome to do just that!
+
+Intended to be a used in a post-deploy or CI step.
+
+Yay-hooray!
+
+## Installation
+
+    gem install chrome_debugger
+
+## Extra Requirements
+
+Chrome 18 or higher must be installed and available on the path.
+
+## Usage
+
+    require 'chrome_debugger'
+
+    ChromeDebugger::Client.open do |chrome|
+      document = chrome.load_url("https://theconversation.edu.au/")
+
+      puts "requests:          #{document.request_count}"
+      puts "onload_event:      #{document.onload_event}"
+      puts "dom_content_event: #{document.dom_content_event}"
+      puts "document_payload:  #{document.encoded_bytes("Document")}"
+      puts "script_payload:    #{document.encoded_bytes("Script")}"
+      puts "image_payload:     #{document.encoded_bytes("Image")}"
+    end
+
+Refer to the ChromeDebugger::Client and ChromeDebugger::Document classes for
+detailed docs.
+
+ChromeDebugger::Client starts and manages a new chrome session.
+
+ChromeDebugger::Document provides an entry point for querying the results of
+a page load.
+
+## Authors
+
+Justin Morris
+  justin.morris@theconversation.edu.au
+
+James Healy
+  james.healy@theconversation.edu.au
+
+## Further Reading
+
+* https://developers.google.com/chrome-developer-tools/docs/remote-debugging
+* http://www.igvita.com/2012/04/09/driving-google-chrome-via-websocket-api/
+
+## TODO
+
+Possible further work.
+
+* make the chrome path configurable
+* make headless mode configurable

data/examples/basic.rb

@@ -0,0 +1,34 @@
+# coding: utf-8
+
+# A basic example that prints stats on a website to STDOUT.
+#
+# Usage:
+#
+#   ruby basic.rb
+
+$:.unshift File.expand_path('../../lib/',  __FILE__)
+require 'chrome_debugger'
+
+ChromeDebugger::Client.open do |chrome|
+  document = chrome.load_url("https://theconversation.edu.au/")
+  {
+    requests:                        document.request_count,
+    onload_event:                    document.onload_event,
+    dom_content_event:               document.dom_content_event,
+    document_payload:                document.encoded_bytes("Document"),
+    script_payload:                  document.encoded_bytes("Script"),
+    image_payload:                   document.encoded_bytes("Image"),
+    stylesheet_payload:              document.encoded_bytes("Stylesheet"),
+    other_payload:                   document.encoded_bytes("Other"),
+    document_uncompressed_payload:   document.bytes("Document"),
+    script_uncompressed_payload:     document.bytes("Script"),
+    image_uncompressed_payload:      document.bytes("Image"),
+    stylesheet_uncompressed_payload: document.bytes("Stylesheet"),
+    other_uncompressed_payload:      document.bytes("Other"),
+    script_count:                    document.request_count_by_resource("Script"),
+    image_count:                     document.request_count_by_resource("Image"),
+    stylesheet_count:                document.request_count_by_resource("Stylesheet")
+  }.each {|key, value|
+    puts "#{key}: #{value}"
+  }
+end

data/examples/theconversation.rb

@@ -0,0 +1,57 @@
+# coding: utf-8
+
+# Demonstrates how we use ChromeDebugger at @ConversationEdu. We track various
+# performance metrics on key pages and send the results to Librato Metrics, a
+# hosted metrics platform.
+#
+# Usage:
+#
+#   LIBRATO_USER=someone@example.com LIBRATO_KEY=SECRET ruby theconversation.rb
+
+require 'chrome_debugger'
+require 'librato/metrics'
+
+# Config
+
+LIBRATO_PREFIX = "tc.frontend"
+LIBRATO_USER   = ENV["LIBRATO_USER"]
+LIBRATO_KEY    = ENV["LIBRATO_KEY"]
+PAGES          = {
+  homepage: 'https://theconversation.edu.au/',
+  articlepage: 'https://theconversation.edu.au/bike-lanes-economic-benefits-go-beyond-jobs-6081/'
+}
+
+# ACTION
+
+Librato::Metrics.authenticate(LIBRATO_USER, LIBRATO_KEY)
+librato_queue = Librato::Metrics::Queue.new
+
+PAGES.each do |name, url|
+  ChromeDebugger::Client.open do |chrome|
+    document = chrome.load_url(url)
+    {
+      requests:             document.request_count,
+      onload_event:         document.onload_event,
+      dom_content_event:    document.dom_content_event,
+      document_payload:     document.encoded_bytes("Document"),
+      script_payload:       document.encoded_bytes("Script"),
+      image_payload:        document.encoded_bytes("Image"),
+      stylesheet_payload:   document.encoded_bytes("Stylesheet"),
+      other_payload:        document.encoded_bytes("Other"),
+      document_uncompressed_payload:   document.bytes("Document"),
+      script_uncompressed_payload:     document.bytes("Script"),
+      image_uncompressed_payload:      document.bytes("Image"),
+      stylesheet_uncompressed_payload: document.bytes("Stylesheet"),
+      other_uncompressed_payload:      document.bytes("Other"),
+      script_count:         document.request_count_by_resource("Script"),
+      image_count:          document.request_count_by_resource("Image"),
+      stylesheet_count:     document.request_count_by_resource("Stylesheet")
+    }.each {|key, value|
+      puts "#{LIBRATO_PREFIX}.#{name}.#{key}: #{value}"
+    }.each { |key, value|
+      librato_queue.add("#{LIBRATO_PREFIX}.#{name}.#{key}" => value)
+    }
+  end
+end
+
+librato_queue.submit

data/lib/chrome_debugger.rb

@@ -0,0 +1 @@
+require 'chrome_debugger/client'

data/lib/chrome_debugger/client.rb

@@ -0,0 +1,136 @@
+require 'em-http'
+require 'faye/websocket'
+require 'headless'
+require 'json'
+
+require 'securerandom'
+
+require 'chrome_debugger/document'
+require 'chrome_debugger/notification'
+require 'chrome_debugger/data_received'
+require 'chrome_debugger/dom_content_event_fired'
+require 'chrome_debugger/load_event_fired'
+require 'chrome_debugger/request_will_be_sent'
+require 'chrome_debugger/response_received'
+
+module ChromeDebugger
+  class Client
+
+    PAGE_LOAD_WAIT = 16
+    REMOTE_DEBUGGING_PORT = 9222
+
+    def initialize(opts = {})
+      @chrome_path = find_chrome_binary
+    end
+
+    def self.open(&block)
+      headless = Headless.new
+      headless.start
+      chrome = ChromeDebugger::Client.new
+      chrome.start_chrome
+      yield chrome
+    ensure
+      chrome.cleanup
+      headless.destroy
+    end
+
+    def start_chrome
+      @profile_dir = File.join(Dir.tmpdir, SecureRandom.hex(10))
+      @chrome_cmd  = "'#{@chrome_path}' --user-data-dir=#{@profile_dir} -remote-debugging-port=#{REMOTE_DEBUGGING_PORT} --no-first-run"
+      @chrome_pid  = Process.spawn(@chrome_cmd, :pgroup => true)
+
+      until debug_port_listening?
+        sleep 0.1
+      end
+    end
+
+    def load_url(url)
+      raise "call the start_chrome() method first" unless @chrome_pid
+      document = ChromeDebugger::Document.new(url)
+      load(document)
+      document
+    end
+
+    def cleanup
+      if @chrome_pid
+        Process.kill('-TERM', Process.getpgid(@chrome_pid))
+        sleep 3
+        FileUtils.rm_rf(@profile_dir) if @profile_dir && File.directory?(@profile_dir)
+        @chrome_pid = nil
+      end
+    end
+
+    private
+
+    def find_chrome_binary
+      path = [
+        "/usr/bin/google-chrome",
+        "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome"
+      ].detect { |path|
+        File.file?(path)
+      }
+      raise "No Chrome binary found" if path.nil?
+      path
+    end
+
+    def handle_data(document, data)
+      unless data['result']
+        case data['method']
+        when "Network.requestWillBeSent" then
+          # The browser is initiating a new HTTP request
+          document.events << ChromeDebugger::RequestWillBeSent.new(data)
+        when "Page.domContentEventFired" then
+          document.events << ChromeDebugger::DomContentEventFired.new(data)
+        when "Page.loadEventFired" then
+          document.events << ChromeDebugger::LoadEventFired.new(data)
+        when "Network.responseReceived" then
+          document.events << ChromeDebugger::ResponseReceived.new(data)
+        when "Network.dataReceived" then
+          document.events << ChromeDebugger::DataReceived.new(data)
+        else
+          document.events << ChromeDebugger::Notification.new(data)
+        end
+      end
+    end
+
+    def load(document)
+      EM.run do
+        EM::add_periodic_timer(0.5) do
+          EM.stop_event_loop if document.onload_event
+        end
+
+        conn = EM::HttpRequest.new("http://localhost:#{REMOTE_DEBUGGING_PORT}/json").get
+        conn.callback do
+          response = JSON.parse(conn.response)
+
+          ws = Faye::WebSocket::Client.new response.first['webSocketDebuggerUrl']
+
+          ws.onmessage = lambda do |message|
+            data = JSON.parse(message.data)
+            handle_data(document, data)
+          end
+
+          ws.onopen = lambda do |event|
+            ws.send JSON.dump({id: 1, method: 'Page.enable'})
+            ws.send JSON.dump({id: 2, method: 'Network.enable'})
+            ws.send JSON.dump({id: 3, method: 'Network.setCacheDisabled', params: {cacheDisabled: true}})
+            ws.send JSON.dump({id: 4, method: 'Network.clearBrowserCache'})
+            ws.send JSON.dump({
+              id: 5,
+              method: 'Page.navigate',
+              params: {url: document.url}
+            })
+          end
+        end
+      end
+    end
+
+    def debug_port_listening?
+      TCPSocket.new('localhost', REMOTE_DEBUGGING_PORT).close
+      true
+    rescue Errno::ECONNREFUSED
+      false
+    end
+
+  end
+end

data/lib/chrome_debugger/data_received.rb

@@ -0,0 +1,19 @@
+require 'chrome_debugger/notification'
+
+module ChromeDebugger
+  class DataReceived < Notification
+
+    # uncompressed bytes in the HTTP content. Excludes HTTP headers
+    #
+    def data_length
+      @params['dataLength'].to_i
+    end
+
+    # bytes received over the wire. Includes HTTP headers
+    # and HTTP content. The HTTP content may be compressed.
+    #
+    def encoded_data_length
+      @params['encodedDataLength'].to_i
+    end
+  end
+end

data/lib/chrome_debugger/document.rb

@@ -0,0 +1,119 @@
+require 'chrome_debugger/dom_content_event_fired'
+require 'chrome_debugger/load_event_fired'
+require 'chrome_debugger/notification'
+require 'chrome_debugger/response_received'
+require 'chrome_debugger/request_will_be_sent'
+
+module ChromeDebugger
+  class Document
+
+    attr_reader :url, :events
+
+    def initialize(url)
+      @url       = url
+      @timestamp = 0
+      @events    = []
+    end
+
+    # The seconds since epoch that the request for this document started
+    #
+    def start_time
+      @start_time ||= @events.select { |event|
+        event.is_a?(RequestWillBeSent)
+      }.select { |event|
+        event.request['url'] == @url
+      }.map { |event|
+        event.timestamp
+      }.first
+    end
+
+    # The number of seconds *after* start_time that the OnLoad event fired
+    #
+    def onload_event
+      @onload_event ||= begin
+                          ts = @events.select { |event|
+                            event.is_a?(LoadEventFired)
+                          }.slice(0,1).map(&:timestamp).first
+                          ts ? (ts - start_time).round(3) : nil
+                        end
+    end
+
+    # The number of seconds *after* start_time the the DomReady event fired
+    #
+    def dom_content_event
+      @dom_content_event ||= begin
+                               ts = @events.select { |event|
+                                 event.is_a?(DomContentEventFired)
+                               }.slice(0,1).map(&:timestamp).first
+                               ts ? (ts - start_time).round(3) : nil
+                             end
+    end
+
+    # The number of bytes downloaded for a particular resource type. If the
+    # resource was gzipped during transfer then the gzipped size is reported.
+    #
+    # The HTTP headers for the response are included in the byte count.
+    #
+    # Possible resource types: 'Document','Script', 'Image', 'Stylesheet',
+    # 'Other'.
+    #
+    def encoded_bytes(resource_type)
+      @events.select {|e|
+        e.is_a?(ResponseReceived) && e.resource_type == resource_type
+      }.map { |e|
+        e.request_id
+      }.map { |request_id|
+        data_received_for_request(request_id)
+      }.flatten.inject(0) { |bytes_sum, n| bytes_sum + n.encoded_data_length }
+    end
+
+    # The number of bytes downloaded for a particular resource type. If the
+    # resource was gzipped during transfer then the uncompressed size is
+    # reported.
+    #
+    # The HTTP headers for the response are NOT included in the byte count.
+    #
+    # Possible resource types: 'Document','Script', 'Image', 'Stylesheet',
+    # 'Other'.
+    #
+    def bytes(resource_type)
+      @events.select {|e|
+        e.is_a?(ResponseReceived) && e.resource_type == resource_type
+      }.map { |e|
+        e.request_id
+      }.map { |request_id|
+        data_received_for_request(request_id)
+      }.flatten.inject(0) { |bytes_sum, n| bytes_sum + n.data_length }
+    end
+
+    # The number of network requests required to load this document
+    #
+    def request_count
+      @events.select {|n|
+        n.is_a?(ResponseReceived)
+      }.size
+    end
+
+    # the number of network requests of a particular resource
+    # type that were required to load this document
+    #
+    # Possible resource types: 'Document', 'Script', 'Image', 'Stylesheet',
+    # 'Other'.
+    #
+    def request_count_by_resource(resource_type)
+      @events.select {|n|
+        n.is_a?(ResponseReceived) && n.resource_type == resource_type
+      }.size
+    end
+
+    private
+
+    def data_received_for_request(id)
+      @events.select { |e|
+        e.is_a?(DataReceived) && e.request_id == id
+      }
+    end
+
+
+  end
+end

data/lib/chrome_debugger/dom_content_event_fired.rb

@@ -0,0 +1,10 @@
+require 'chrome_debugger/notification'
+
+module ChromeDebugger
+  class DomContentEventFired < Notification
+
+    def timestamp
+      @params['timestamp'].to_f
+    end
+  end
+end

data/lib/chrome_debugger/load_event_fired.rb

@@ -0,0 +1,11 @@
+require 'chrome_debugger/notification'
+
+module ChromeDebugger
+  class LoadEventFired < Notification
+
+
+    def timestamp
+      @params['timestamp'].to_f
+    end
+  end
+end

data/lib/chrome_debugger/notification.rb

@@ -0,0 +1,20 @@
+module ChromeDebugger
+  class Notification
+
+    attr_reader :method
+
+    def initialize(point)
+      @params = point['params'] || {}
+      @method = point['method']
+    end
+
+    def resource_type
+      @params['type']
+    end
+
+    def request_id
+      @params['requestId']
+    end
+
+  end
+end

data/lib/chrome_debugger/request_will_be_sent.rb

@@ -0,0 +1,14 @@
+require 'chrome_debugger/notification'
+
+module ChromeDebugger
+  class RequestWillBeSent < Notification
+
+    def request
+      @params['request']
+    end
+
+    def timestamp
+      @params['timestamp'].to_f
+    end
+  end
+end

data/lib/chrome_debugger/response_received.rb

@@ -0,0 +1,11 @@
+require 'chrome_debugger/notification'
+
+module ChromeDebugger
+  class ResponseReceived < Notification
+
+    def bytes
+      @params['response']['headers']['Content-Length'].to_i
+    end
+
+  end
+end

metadata

@@ -0,0 +1,63 @@
+--- !ruby/object:Gem::Specification
+name: chrome_debugger
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+  prerelease: 
+platform: ruby
+authors:
+- Justin Morris
+- James Healy
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2012-08-27 00:00:00.000000000 Z
+dependencies: []
+description: Starts a Google Chrome session. Load pages and examine the results.
+email:
+- justin.morris@theconversation.edu.au
+- james.healy@theconversation.edu.au
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- examples/basic.rb
+- examples/theconversation.rb
+- lib/chrome_debugger/client.rb
+- lib/chrome_debugger/data_received.rb
+- lib/chrome_debugger/document.rb
+- lib/chrome_debugger/dom_content_event_fired.rb
+- lib/chrome_debugger/load_event_fired.rb
+- lib/chrome_debugger/notification.rb
+- lib/chrome_debugger/request_will_be_sent.rb
+- lib/chrome_debugger/response_received.rb
+- lib/chrome_debugger.rb
+- README.md
+- CHANGELOG
+homepage: http://github.com/conversation/chrome_debugger
+licenses: []
+post_install_message: 
+rdoc_options:
+- --title
+- Chrome Debugger
+- --line-numbers
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: 1.9.2
+required_rubygems_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: 1.3.2
+requirements: []
+rubyforge_project: 
+rubygems_version: 1.8.24
+signing_key: 
+specification_version: 3
+summary: Remotely control Google Chrome and extract stats
+test_files: []