Rbkit
============================================
## [WARNING]
This project is not maintained at the moment. We have plans to work on a universal profiling protocol after which we intend to rewrite major parts of Rbkit.
[](https://gitter.im/code-mancers/rbkit?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge)
[](http://badge.fury.io/rb/rbkit)
[](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)
as packed messages.
## Usage
#### Install prerequisites
Rbkit requires the following executables to be present :
* libtool
* autoconf
* automake
Install these with your operating system's package manager before proceeding
to install Rbkit gem.
#### Add `rbkit` to Gemfile
Add the following to the project's Gemfiles
```
gem '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
```
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
Without any arguments, it's same as :
```ruby
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 an instance of
`Rbkit::Server` if server was started successfully, else returns false.
|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
Without any arguments, it's same as :
```ruby
Rbkit.start_profiling(
pub_port: nil,
request_port: nil,
enable_object_trace: true,
enable_gc_stats: true,
enable_cpu_profiling: true,
clock_type: :wall,
cpu_profiling_mode: :sampling,
cpu_sampling_interval_usec: 1000
)
```
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 an instance of `Rbkit::Server`
if server was started successfully, else returns false.
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 |
|enable_cpu_profiling | true/false | true | Enables CPU profiling |
|clock_type | :wall/:cpu | :wall | Specifies clock type to use in CPU profiling |
|cpu_profiling_mode | :sampling | :sampling | CPU profiling mode - currently only sampling |
|cpu_sampling_interval_usec | Fixnums | 1000 | CPU Sampling interval un usec, if sampling mode |
## 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:
```
~> brew install zeromq
~> brew install msgpack
```
On Linux - we recommend to download these libraries
from their respective home pages and manually compiling
and installing.
Recommended versions are:
Zeromq: 4.0.5_2
Msgpack: 0.5.9
#### Clone the repo
`git clone git@github.com:code-mancers/rbkit.git`
We'll call this ``.
#### Set RBKIT_DEV environment flag
Set the environment variable `RBKIT_DEV` to true.
If using bash, put `export RBKIT_DEV=true` in your `~/.bashrc`.
This compiles the C extension with debug flag and also sets a macro named
`RBKIT_DEV` inside the C extension.
#### Compile the C extension
Two ways to do this :
##### Using rake
```
cd
bundle install
bundle exec rake compile
```
##### Or do it manually
```
cd
ruby extconf.rb
make
# Create a symlink at `lib/rbkit_server.bundle` (or .so if on linux)
# that points to `ext/rbkit_server.bundle`
# (in order to use `rbkit` gem in Gemfiles using `path` option)
```
#### Run the tests
```
bundle exec rake
```
## TODO
TODOs are tracked as github issues.