rbkit 0.0.1 → 0.1.6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 9c98d007ffcab15624f4463ba9220cfe0b02635f
-  data.tar.gz: 4de1af44a5313d96dc359dac2e5929616c8362af
+  metadata.gz: 739b3af12258b89ecfdae05d06c03889329d496d
+  data.tar.gz: c7144822b77d0173352ef6c184c7c8ddaa046311
 SHA512:
-  metadata.gz: 3b867812d99bcc5b41da934789e26f0053419757928db46d9f23f0faaac30757ef1eec6083d3b28e21277d99f5b8d4cf0e566fffc89c80b790005916492689f4
-  data.tar.gz: 001c0549d008515fc411499c94b4fe72768d801e1040ff44ab39e1ee0e79f7830de0aa3816be738a90a66aff728b2c34c9630a3e27231a163aee06af8200a09f
+  metadata.gz: b46dc7d9c12bd100c59177e0afc0d0021ede93328d4e5444f4cbefac70bfd960046f88e20ebd4aa2cdde458a9a9caa01f5e9697a4a8e542e43df7840476f7889
+  data.tar.gz: d8e462c46b173086ce21f04d1350ebdaae5023a6da9407c50841a2dfb8755d2b281908450136db079570a3ab3ea6f53789039e5391ad3bf30cf51406407f51fa

data/.gitignore

@@ -14,3 +14,8 @@ Gemfile.lock
 /mkmf.log
 /coverage
 *.xcodeproj
+/ext/libzmq.a
+/ext/zeromq*
+/ext/libmsgpack.a
+/ext/msgpack*
+/ext/TAGS

data/.rspec

@@ -0,0 +1,2 @@
+--color
+--format progress

data/.travis.yml

@@ -0,0 +1,17 @@
+language: ruby
+bundler_args: "--without exclude_in_travis"
+rvm:
+- 2.1.3
+- 2.2.0
+- ruby-head
+os:
+- linux
+- osx
+script: bundle exec rake run_spec
+notifications:
+  hipchat:
+    rooms:
+      secure: KdhzB9VueLEJp9p/ZUFaXAMO0u1CEbT0sjdRt10jqseAJCld9CAK1KAb1f/mNO/+cbVd+7W9UdHA0cEGUZ9dLP9Mcpmy31QxOJSITUCrRiLOF1ti13Lq4WHpMM46Tz6p7vVYd4zpPj9Mup+lCTGOeCovReX+neIoZw0UjDg9oGs=
+    template:
+      - '%{result}: %{repository_slug}#%{branch} - <a href="%{compare_url}">%{commit}</a>(%{commit_message}) by %{author} (<a href="%{build_url}">Details</a>)'
+    format: html

data/CHANGELOG.md

@@ -0,0 +1,5 @@
+v0.1.6
+======
+
+* First final public release
+* CHANGELOG.md created

data/Gemfile

@@ -1,7 +1,11 @@
 source "https://rubygems.org"
 
-gem "rbczmq"
 gem "msgpack"
-gem "rake-compiler"
+
+group :exclude_in_travis do
+  gem 'pry-byebug'
+  gem 'rbczmq'
+end
+
 
 gemspec

data/LICENSE.txt

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2014 Emil Soman, Hemant Kumar
+
+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.md

@@ -1,5 +1,8 @@
-Rbkit
-=====
+<img src="./logo.png" height="30px" /> Rbkit
+============================================
+
+[![Gem Version](https://badge.fury.io/rb/rbkit.svg)](http://badge.fury.io/rb/rbkit)
+[![Build Status](https://travis-ci.org/code-mancers/rbkit.svg?branch=tests)](https://travis-ci.org/code-mancers/rbkit)
 
 `rbkit` is a Ruby gem that plugs into your ruby process, taps profiling data
 in realtime and sends it across the wire to the [rbkit-client](https://github.com/code-mancers/rbkit-client)
@@ -16,24 +19,87 @@ then follow these steps :
 Add the following to the project's Gemfiles
 
 ```
-gem 'rbkit', path: <RBKIT_PATH>`
+gem 'rbkit', path: <RBKIT_PATH>
 ```
+
+
 and run `bundle install`
 
+#### Installation without Rubygems
+
+You can also install `rbkit` without bundler/rubygems. This can
+be useful, if you are profiling a Ruby app where you want to measure
+overhead of Rubygems/Bundler.
+
+Just clone the repository or download from a release tag and run:
+
+```
+# Run from root of rbkit directory.
+~> ruby setup.rb
+```
+
+This should install `rbkit`
+in ruby's `site_dir` and then you don't need `rbkit` added to your
+`Gemfile` for requiring `rbkit`.
+
 #### Inject `rbkit` into code
 
 Wherever you want to start profiling, add the following :
+
+```ruby
+require 'rbkit' # Not needed in Rails
+Rbkit.start_server
 ```
-require 'rbkit'
-Rbkit.start_profiling
-```
+
 If using Rails, and you want to measure everything from the boot process,
 a good place to put this would be at the end of `config/boot.rb`.
 
+## Rbkit API
+
+### Rbkit.start_server(pub_port: nil, request_port: nil)
+
+Starts the Rbkit server and waits for a client to connect and issue
+commands to the request_port, until then there's zero performance overhead.
+Profiling data is sent asynchronously over pub_port.
+This method can be called early in a ruby application so that
+whenever profiling needs to be done, the client can attach itself to the
+inactive server, do the profiling and leave. Returns true if server was
+started successfully.
+
+
+|argument      | valid values | default value | description                                       |
+|--------------|--------------|---------------|---------------------------------------------------|
+|pub_port      | nil, fixnum  | nil           | Override default message publishing port of 5555  |
+|request_port  | nil, fixnum  | nil           | Override default command listener port of 5556    |
+
+
+### Rbkit.start_profiling(pub_port: nil, request_port: nil, enable_object_trace: true, enable_gc_stats: true)
+
+Starts the server with all tracepoints enabled by default. User can
+optionally disable tracepoints using the optional arguments.
+This method can be used to profile the startup process of a ruby
+application where sending commands from the client to enable
+profiling is not feasible. Returns true if server was started successfully.
+
+Arguments:
+
+|argument             | valid values | default value | description                                      |
+|---------------------|--------------|---------------|--------------------------------------------------|
+|pub_port             | nil, fixnum  | nil           | Override default message publishing port of 5555 |
+|request_port         | nil, fixnum  | nil           | Override default command listener port of 5556   |
+|enable_object_trace  | true/false   | true          | Enables object creation/deletion events          |
+|enable_gc_stats      | true/false   | true          | Enables GC stats which is sent every 5 seconds   |
+
+
 ## Development
 
 #### Install zmq and msgpack
 
+If zmq and msgpack are not installed, Rbkit automatically downloads
+and installs the two libraries from source during gem installation.
+But if you are developing Rbkit, it makes sense to have these
+preinstalled:
+
 On OSX - Using `homebrew` following command should suffice:
 
 ```
@@ -45,9 +111,6 @@ On Linux - we recommend to download these libraries
 from their respective home pages and manually compiling
 and installing.
 
-At some point, we will bundle these two C libraries during gem installations
-but for now, this has to suffice.
-
 #### Clone the repo
 
 `git clone git@github.com:code-mancers/rbkit.git`
@@ -66,7 +129,7 @@ This compiles the C extension with debug flag and also sets a macro named
 
 Two ways to do this :
 
-##### Using rake-compiler
+##### Using rake
 
 ```
 cd <RBKIT_PATH>
@@ -81,7 +144,7 @@ bundle exec rake compile
 cd <RBKIT_PATH/ext>
 ruby extconf.rb
 make
-# Create a symlink at `lib/rbkit_tracer.bundle`
+# Create a symlink at `lib/rbkit_tracer.bundle` (or .so if on linux)
 # that points to `ext/rbkit_tracer.bundle`
 # (in order to use `rbkit` gem in Gemfiles using `path` option)
 ```

data/Rakefile

@@ -1,7 +1,31 @@
 require "bundler/gem_tasks"
+require "rspec/core/rake_task"
 
-require 'rake/extensiontask'
+RSpec::Core::RakeTask.new
 
-Rake::ExtensionTask.new('rbkit_tracer') do |ext|
-  ext.ext_dir = 'ext'
+task :compile do
+  symlink_bundle_path = File.absolute_path "lib/rbkit_tracer.#{RbConfig::MAKEFILE_CONFIG['DLEXT']}"
+  original_bundle_path = File.absolute_path "ext/rbkit_tracer.#{RbConfig::MAKEFILE_CONFIG['DLEXT']}"
+  Dir.chdir 'ext' do
+    system("#{Gem.ruby} extconf.rb")
+    system("make")
+    File.delete(symlink_bundle_path) if File.symlink? symlink_bundle_path
+    File.symlink(original_bundle_path, symlink_bundle_path)
+  end
 end
+
+desc "Run each spec in isolated process"
+task :run_spec => [:compile] do
+  command_output = []
+  Dir["spec/*_spec.rb"].each do |file|
+    puts "Running #{file}.."
+    command_output << system("bundle exec rspec #{file}")
+  end
+  if command_output.all?
+    exit(0)
+  else
+    exit(-1)
+  end
+end
+
+task :default => [:compile, :spec]

data/docs/EVENT_FORMAT.md

@@ -0,0 +1,195 @@
+Refer [issue #11](https://github.com/code-mancers/rbkit/issues/11) for some history.
+
+## Event types
+
+EventType is an integer value indicating the type of event
+contained in the message. It's basically the following enum : 
+
+```c
+enum EventType {
+  obj_created,
+  obj_destroyed,
+  gc_start,
+  gc_end_m,
+  gc_end_s,
+  object_space_dump,
+  gc_stats,
+  event_collection,
+  handshake
+}
+```
+
+ie, 
+
+```ruby
+# Rbkit::EVENT_TYPES
+{
+  "obj_created"       => 0,
+  "obj_destroyed"     => 1,
+  "gc_start"          => 2,
+  "gc_end_m"          => 3,
+  "gc_end_s"          => 4,
+  "object_space_dump" => 5,
+  "gc_stats"          => 6,
+  "event_collection"  => 7,
+  "handshake"         => 8
+}
+```
+
+The keys of all event message hashes are integer values whose enum names
+are used below. `Rbkit::MESSAGE_FIELDS` gives you the exhaustive list of
+enums used. 
+
+```ruby
+# Rbkit::MESSAGE_FIELDS
+{
+  'event_type'      =>  0,
+  'timestamp'       =>  1,
+  'payload'         =>  2,
+  'object_id'       =>  3,
+  'class_name'      =>  4,
+  'references'      =>  5,
+  'file'            =>  6,
+  'line'            =>  7,
+  'size'            =>  8,
+  'message_counter' =>  9
+}
+```
+
+## Message frames
+
+Generic message frame is of the format :
+
+```yaml
+{
+  event_type: <EventType>,
+  timestamp: <timestamp in milliseconds>,
+  payload: <PAYLOAD> # Optional
+}
+```
+
+### Message frame for event_collection :
+
+All events are aggregated in the server and sent as the payload of a special
+type of event named `event_collection`. The payload will be an array containing
+other event messages.
+
+```yaml
+{
+  event_type: "event_collection",
+  message_counter: <incrementing counter>,
+  timestamp: <timestamp in milliseconds>,
+  payload: [
+    {event_type: <EVENT_TYPE>, timestamp: <TIMESTAMP>, payload: <PAYLOAD>},
+    {event_type: <EVENT_TYPE>, timestamp: <TIMESTAMP>, payload: <PAYLOAD>}
+  ]
+}
+```
+
+### Message frame for HANDSHAKE :
+
+Handshake is a special message which is sent synchronously over the REQ-REP
+socket pair and not on the PUB socket. When a "handshake" command is send by
+the client, the server responses with the Rbkit status. The handshake reply
+is of the following format :
+
+```yaml
+{
+  event_type: "handshake",
+  timestamp: <timestamp in milliseconds>,
+  payload: {
+    "process_name" => <Name of the process>,
+    "pwd" => <working directory of the app>,
+    "pid" => <PID of the ruby process>,
+    "object_trace_enabled" => <0 or 1>
+  }
+}
+```
+
+### Message frame for NEW_OBJECT :
+
+When the NEW_OBJECT event is triggered, the object id and the class name
+are sent as the payload.
+
+```yaml
+{
+  event_type: obj_created,
+  timestamp: <timestamp in milliseconds>,
+  payload: {
+    object_id: <OBJECT_ID>,
+    class_name: <CLASS_NAME>
+  }
+}
+```
+
+### Message frame for FREE_OBJECT :
+
+```yaml
+{
+  event_type: obj_destroyed,
+  timestamp: <timestamp in milliseconds>,
+  payload: {
+    object_id: <OBJECT_ID>
+  }
+}
+```
+
+### Message frame for GC_START :
+
+When the GC_START event is triggered, no payload is sent.
+
+```yaml
+{
+  event_type: gc_start,
+  timestamp: <timestamp in milliseconds>,
+}
+```
+
+### Message frame for GC_END_SWEEP :
+
+When the GC_END_SWEEP event is triggered, no payload is sent.
+
+```yaml
+{
+  event_type: gc_end_s,
+  timestamp: <timestamp in milliseconds>,
+}
+```
+
+### Message frame for OBJECT_SPACE_DUMP :
+
+```yaml
+{
+  event_type: object_space_dump
+  timestamp: <timestamp in milliseconds>,
+  payload: [
+    {
+      object_id: <OBJECT_ID>,
+      snapshot_no: <SNAPSHOT_COUNT>,
+      class_name: <CLASS_NAME>,
+      references: [<OBJECT_ID>, <OBJECT_ID>, ... ],
+      file: <FILE_PATH>,
+      line: <LINE_NUMBER>,
+      size: <SIZE>
+    },
+    ...
+  ]
+}
+```
+
+### Message from GC stats:
+**Note: GC stat payload uses strings for keys**
+
+```yaml
+{
+  event_type: "gc_stats",
+  timestamp: <timestamp in milliseconds>,
+  payload: {
+     count:
+     heap_user:
+     heap_length:
+     heap_increment:
+     ...
+  }
+}
+```