Red Artisan - Blog

Sprinkle Some Powder!

2008-05-27T07:21:00Z

Provisioning a brand new server or VPS slice can be quite tricky, tedious and time consuming, particularly if done manually with changing software versions and configurations.

In the Rails world, most of us are using virtual private servers which are instantiated from base operating system images, it takes only a few minutes to create a slice, however installing the rest of your server's stack, be it Rails, Merb or another framework is where the work begins. Provisioning in this sense, is installing all software required post operating system install.

Sprinkle is a new prototype tool that you can use to provision your servers/slices. Its declarative policy/state based approach for specifying how a remote system should be provisioned with intelligent logic to support dependencies, multiple installer types and remote installation is really compelling.

Several free and commercially available tools already exist to help automate the installation of software however most fall into two styles of design:

1 - Task based, where the tool issues a list of commands to run on the remote system, either remotely via a network connection or smart client.
2 - Policy/state based, where the tool determines what needs to be run on the remote system by examining its current and final state.

Task based solutions are usually quite easy and fast to get up and running, but can be problematic as the user has to define all of the commands manually (not to mention get them right with testing). Policy/state based solutions have much more intelligence about how to modify and adapt the remote system, but often require specialized software to run remotely.

Sprinkle is a prototype tool I've been working on recently in this space that merges both concepts together, using a Ruby domain specific language to declaratively describe the state of the remote system. Using Sprinkle, provisioning your brand new remote server or slice can be automated using pre-defined and/or customized scripts from a single machine at your fingertips.

Sprinkle reads a script that defines a set of packages, a set of policies that define what packages should be installed on what roles of target machines, and a deployment section that defines the delivery mechanism for communicating with remote machines, and any default settings.

Packages can have relationships between each other to support dependencies. Virtual packages are also supported allowing you to define a role that a package (or multiple) fulfills, with the user or Sprinkle selecting which concrete package should be used at runtime.

Packages can also support arbitrary installer types, allowing you to install packages from source, gems, apt, or any other installer you'd like to employ. Installer types know what commands need to be issued to install packages, so all that needs to be specified in a script is the installer type and metadata about the package itself.

In essence, Sprinkle is about defining a domain specific meta-language for describing and processing the installation of software.

Example Sprinkle Script

Here's an example Sprinkle deployment script, annotated to explain each section:

# Annotated Example Sprinkle Rails deployment script
#
# This is an example Sprinkle script configured to install Rails from Gems, Apache, Ruby and
# Sphinx from source, and MySQL from APT on an Ubuntu system.
#
# Installation is configured to run via capistrano (and an accompanying deploy.rb recipe script).
# Source based packages are downloaded and built into /usr/local on the remote system.
#
# A sprinkle script is separated into 3 different sections. Packages, policies and deployment:


# Packages (separate files for brevity)
#
#  Defines the world of packages as we know it. Each package has a name and
#  set of metadata including its installer type (eg. apt, source, gem, etc). Packages can have
#  relationships to each other via dependencies.

require 'packages/essential'
require 'packages/rails'
require 'packages/database'
require 'packages/server'
require 'packages/search'


# Policies
#
#  Names a group of packages (optionally with versions) that apply to a particular set of roles:
#
#   Associates the rails policy to the application servers. Contains rails, and surrounding
#   packages. Note, appserver, database, webserver and search are all virtual packages defined above.
#   If there's only one implementation of a virtual package, it's selected automatically, otherwise
#   the user is requested to select which one to use.

policy :rails, :roles => :app do
  requires :rails, :version => '2.0.2'
  requires :appserver
  requires :database
  requires :webserver
  requires :search
end


# Deployment
#
#  Defines script wide settings such as a delivery mechanism for executing commands on the target
#  system (eg. capistrano), and installer defaults (eg. build locations, etc):
#
#   Configures sprinkle to use capistrano for delivery of commands to the remote machines (via
#   the named 'deploy' recipe). Also configures 'source' installer defaults to put package gear
#   in /usr/local

deployment do

  # mechanism for deployment
  delivery :capistrano do
    recipes 'deploy'
  end

  # source based package installer defaults
  source do
    prefix   '/usr/local'
    archives '/usr/local/sources'
    builds   '/usr/local/build'
  end

end

# End of script, given the above information, Spinkle will apply the defined policy on all roles using the
# deployment settings specified.

Given such a script, Sprinkle will apply the defined policy rails on the target machines identified by the role app, where the policy rails is composed of packages for the rails gem itself, an application server, webserver, search daemon, and the ruby runtime.

Currently, Sprinkle uses Capistrano internally for communicating with remote systems, however this is pluggable as well, allowing for just about any concievable delivery mechanism in the future. The deployment section above identifies Capistrano as the delivery mechanism, specifying a local deploy.rb script that defines what roles are available, and what machines are defined within those roles.

This particular script breaks the package section up into multiple files, here are some of the actual package definitions (complete example available here):

package :ruby do
  description 'Ruby Virtual Machine'
  version '1.8.6'
  source "ftp://ftp.ruby-lang.org/pub/ruby/1.8/ruby-#{version}-p111.tar.gz" # implicit :style => :gnu
  requires :ruby_dependencies
end

package :rubygems do
  description 'Ruby Gems Package Management System'
  version '1.0.1'
  source "http://rubyforge.org/frs/download.php/29548/rubygems-#{version}.tgz" do
    custom_install 'ruby setup.rb'
  end
  requires :ruby
end

package :rails do
  description 'Ruby on Rails'
  gem 'rails'
  version '2.0.2'
end

package :sphinx, :provides => :search do
  description 'MySQL full text search engine'
  version '0.9.8-rc2'
  source "http://www.sphinxsearch.com/downloads/sphinx-#{version}.tar.gz"
  requires :mysql_dev
end

package :apache, :provides => :webserver do
  description 'Apache 2 HTTP Server'
  version '2.2.6'
  source "http://apache.wildit.net.au/httpd/httpd-#{version}.tar.bz2" do
    enable %w( mods-shared=all proxy proxy-balancer proxy-http rewrite cache headers ssl deflate so )
    prefix "/opt/local/apache2-#{version}"
    post :install, 'install -m 755 support/apachectl /etc/init.d/apache2', 'update-rc.d -f apache2 defaults'
  end
  requires :apache_dependencies
end

Each package includes a description, optional version, optional list of dependencies and an installer type (also optional allowing for meta-packages).

Source installers are particularly intelligent and will download, configure and install source archives from a remote location directly on the target machine. They assume GNU style source archives by default (ie. tar.gz/tar.bz2 compressed archives, configure script and make, make install style semantics), however are completely customziable to support any arbitrary build style (rubygems for example does this above), with pre and post commands.

The Apache installer for example, specifies a few extra source installer options such as a set of --enable options, an alternate installation prefix and a series of post installation commands to be executed.

With this example configuration, lets take a look at actually using Sprinkle to provision a remote server.

Usage

Sprinkle supports several command line options:

Usage
=====

$> sprinkle [options]

Options are:

  -s, --script=PATH                Path to a sprinkle script to run
  -t, --test                       Process but don't perform any actions
  -v, --verbose                    Verbose output
  -c, --cloud                      Show powder cloud, ie. package hierarchy and installation order
  -h, --help                       Show this help message.

where you can name the script to be procesed, enable testing mode or verbose output, and/or examine the cloud of packages and operations that will be performed.

Viewing the powder cloud!

Sprinkle calculates all operations to be performed on remote servers upfront which is nice, as it allows you to inspect what modifications will be made to the system before any are actually performed. Lets inspect the powder (ie. package) cloud for the above script:

$> sprinkle -c -t -s rails.rb
--> Cloud hierarchy for policy rails

Policy rails requires package rails
        Package rails requires rubygems
                Package rubygems requires build_essential
                Package rubygems requires ruby
                        Package ruby requires build_essential
                        Package ruby requires ruby_dependencies

Policy rails requires package appserver
Selecting mongrel_cluster for virtual package appserver
        Package mongrel_cluster requires rubygems
                Package rubygems requires build_essential
                Package rubygems requires ruby
                        Package ruby requires build_essential
                        Package ruby requires ruby_dependencies
        Package mongrel_cluster requires mongrel
                Package mongrel requires rubygems
                        Package rubygems requires build_essential
                        Package rubygems requires ruby
                                Package ruby requires build_essential
                                Package ruby requires ruby_dependencies

Policy rails requires package database
Selecting mysql for virtual package database

Policy rails requires package webserver
Selecting apache for virtual package webserver
        Package apache requires build_essential
        Package apache requires apache_dependencies

Policy rails requires package search
Selecting sphinx for virtual package search
        Package sphinx requires build_essential
        Package sphinx requires mysql_dev

--> Normalized installation order for all packages: build_essential, ruby_dependencies, ruby, rubygems, rails, mongrel, mongrel_cluster, mysql, apache_dependencies, apache, mysql_dev, sphinx

-c indicates that Sprinkle should print the powder cloud (ie. the output above)
-t indicates that we're operating in test mode, so we won't actually perform any remote commands
-s identifies the Sprinkle script that should be processed

Above we can see that the policy rails required packages rails, appserver, database, webserver and search.

Note that all of these packages bar rails are actually virtual packages, so Sprinkle has selected an appropriate implementation of each virtual package automatically based on the supplied package definitions. If more than one package provided an implementation of a virtual package, then the user would be given the opportunity to select which one they prefer.

Under each package is a textual representation of that package's dependency tree, including all sub-dependencies, etc. Dependencies are packages that need to be installed first before a higher level package can be installed.

You'll notice that several packages have the same dependencies, eg. both rails and mongrel require ruby, which has its own dependencies as well. Sprinkle will install all packages in reverse dependency order so that lower level dependencies are installed before higher level packages, and it will also normalize the final package list to remove duplicates so that packages aren't installed multiple times unnecessarily. This is the final line in the output above which lists the actual packages to be installed and order of installation.

Provisioning a remote system

To actually provision a remote server we simply remove the testing (and if desired cloud) flags from the command issued above and Sprinkle will process the configuration and provision the remote system. Note for the moment, you'll need to ensure that your SSH keys are appropriately installed on the remote server under a user that has enough privileges to install software (generally the root user):

$> sprinkle -s rails.rb
--> Installing build_essential for roles: app
--> Installing ruby_dependencies for roles: app
--> Installing ruby for roles: app
--> Installing rubygems for roles: app
--> Installing rails for roles: app
--> Installing mongrel for roles: app
--> Installing mongrel_cluster for roles: app
--> Installing mysql for roles: app
--> Installing apache_dependencies for roles: app
--> Installing apache for roles: app
--> Installing mysql_dev for roles: app
--> Installing sphinx for roles: app

(its also possible to put the #!/usr/bin/env sprinkle -c line at the top of a sprinkle script and make it executable).

After the command is finished, all of the requested software will have been applied on your target system.

If you'd like to see more action printed as commands are run, specify the --verbose (-v) flag. Internally, Capistrano tasks are dynamically defined and executed at runtime for each package's installation, using a Capistrano configuration file to identify the actual roles and hostnames associated with those roles to communicate with. The verbose option will display Capistrano activity in addition to the usual Sprinkle output.

An extra benefit of leveraging Capistrano is that you can actually provision multiple servers/slices simultaneously and in parallel if desired.

I want!

If you're interested in downloading and experimenting with Sprinkle, you can clone and/or watch the project at GitHub, or download it from GitHub's gem server using:

$> sudo gem install crafterm-sprinkle --source http://gems.github.com/

The official Rubyforge gem server will also be updated over the coming days as well. If you download the source, you can create a gem package for installation by:

$> rake package
$> sudo gem install -l pkg/sprinkle-0.1.0

There are also specs with a decent amount of coverage over the code base that you can run as well:

$> rake spec

Prerequsites

Installing the Sprinkle gem will also install all pre-requsite gems such as activesupport, highline and capistrano. The only other pre-requisite is that you have SSH connectivity to the remote system you wish to provision, preferably with SSH keys in place to prevent passwords being asked for.

Finally

Sprinkle is a young project and while operational still in development, with several limitations. Currently, only Ubuntu/Debian has been tested as a target deployment platform, operating system abstraction and other platforms will be tested and supported in the future, along with several new features that are in the pipeline.

I'm most certainly open to ideas, suggestions and thoughts about how Sprinkle can be improved and generally made better for the community, and I really welcome any bug reports, patches and suggestions. Please feel free to contact me with any comments at all.

Special Thanks!

Several people have been really helpful during the development of Sprinkle. In particular I'd like to thank Ben Schwarz and Pete Yandell for their initial feedback and help after my first demos. I'd also really like to thank Matthew and Jared from Slicehost for their help and support as well.

Twilight Theme for Emacs!

2008-05-27T00:24:00Z

Recently I’ve been returning to my Unix heritage and using Emacs as my day to day editor. Its been quite an enlightening journey returning to such a powerful editor with its limitless customization and features (probably worthy of a whole separate post), although one things I do miss from TextMate are the colour themes used for syntax highlighting.

Emacs has a package called color-theme which can be used to customize font faces/colours however in comparison to the styled themes TextMate offers, most of default ones available don’t quite compare.

In TextMate I used the Twilight theme quite often, so, after examining the color-theme package format, I’ve ported across the Twilight theme to Emacs, and have released it as a small project on GitHub.

Its definitely a work in progress, most of the colours within Ruby mode are working as expected, but please feel free to improve anything that needs some fine tuning (eg. Rails keywords, and particularly non-Ruby modes such as dired, ERB, SCM, etc). Patches are most certainly welcome.

Ruby && DTrace!

2008-05-18T12:11:00Z

Performance, memory and runtime analysis of software has always been a tricky subject, often requiring special debug versions of code or application specific parameters to determine what's going on. Additionally, developer debugging information can often clutter source code making it harder to see the intent and design of source.

D-Trace offers an interesting solution to this problem, by dynamically instrumenting your application at runtime to enable probes to report various pieces of information as to how your application is running. DTrace is a part of Solaris, but is now also available under Mac OS X Leopard. A typical installation of DTrace can offer 20,000 different types of probes (or more depending on what applications are running), from kernel level information, all the way to application specific data.

Applications, such as the Ruby interpreter can also define their own domain specific probes, last year Joyent added support for D-Trace probes to MRI (Matz-Ruby), allowing developers to analyze runtime behaviour of their Ruby based applications. Starting with this particular commit, compatible D-Trace probes for Rubinius have been developed as well.

What can you do with DTrace?

The list of uses for DTrace are endless, as it provides the means to gain answers to many questions about how your application is behaving. Some practical questions DTrace can answer include:

Tracing execution flow through your application as it steps through each method/class
Determining runtime performance analysis, working out what methods are the most expensive (excellent for 80/20 performance analysis)
Heap analysis, determining what objects are consuming the most memory
Garbage collection impact, determining how often the garbage collector is running an impacting your applications performance
and much more...

Getting started with DTrace and Ruby

To get started with Ruby and DTrace, you'll need a compatible operating system, eg. Mac OS X Leopard, and you'll need to get the Ruby source to build MRI with Joyent's DTrace patches. Luckily, if you're using Mac OS X Leopard, Apple has already appropriately patched their bundled version of Ruby to include DTrace patches for you, and no extra compilation is necessary. DTrace itself is also included by default under all Mac OS X Leopard operating system installs.

DTrace primer

There is a wealth of information available on the internet that I'd certainly recommend taking a look at to learn using DTrace in depth (in particular Sun's DTrace admin guides). Essentially to interact with DTrace, you write a script in a language called 'D', which defines what probes you're interested in, and what to do with the data when the probe fires. This script is then read and bytecode compiled by DTrace's command line and user land libraries, and then passed to the DTrace virtual machine running inside of the kernel to be interpreted. Probes are enabled, and appropriately fired, with data being collected according to your scripts for analysis.

Anatomy of a DTrace script

provider : module : function : name
/ predicate /
{
  action
}

Above is generic breakdown of a DTrace script (somewhat bearing similarity to an awk script). Most parts of the script are optional as you'll see further, such as the module or function name, or even the action.

Probes are grouped by providers, of which there are many (io, pid, objc, profile, to name a few). module and function's meaning are somewhat dependant on the provider being used. The name parameter identifies the actual name of the probe that is to be fired.

The predicate identifies a clause that must evaluate to true for the probe to fire and allows for conditional firing of probes.

The action contains arbitrary instructions to be performed when the probe fires.

To probe your application you also need root privileges on the machine you'll be running DTrace on, this is due to kernel level interaction of DTrace.

Usually you'll run DTrace and pass it the name of a D script (or include the script on the command line if it's brief), either with a command to run, or a process ID of an application that's already running that should be attached to. For example:

$> sudo dtrace -s profile.d -c 'ruby script.rb'

or:

$> ps aux|grep ruby
crafterm 29877   0.0  0.0   590472    188 s001  R+    5:04pm   0:00.00 grep ruby
crafterm 29875   0.0  1.2   622564  25016 s001  S     5:04pm   0:00.85 ruby
$> sudo dtrace -s profile.d 29875

Ruby Provider Probes

To see how many probes are available, and those that are Ruby related, we can ask DTrace to print their specifics to the console, eg:

$> sudo dtrace -l | wc -l
31569

indicating I currently have 31569 probes available to query, this number will change depending on what applications are running at the time of running the dtrace command.

Ruby specific probes can be found by:

$> sudo dtrace -l | grep ruby
21427  ruby53816   libruby.1.dylib                          rb_call0 function-entry
21428  ruby53816   libruby.1.dylib                          rb_call0 function-return
21429  ruby53816   libruby.1.dylib                   garbage_collect gc-begin
21430  ruby53816   libruby.1.dylib                   garbage_collect gc-end
21431  ruby53816   libruby.1.dylib                           rb_eval line
21432  ruby53816   libruby.1.dylib                      rb_obj_alloc object-create-done
21433  ruby53816   libruby.1.dylib                      rb_obj_alloc object-create-start
21434  ruby53816   libruby.1.dylib                   garbage_collect object-free
21435  ruby53816   libruby.1.dylib                        rb_longjmp raise
21436  ruby53816   libruby.1.dylib                           rb_eval rescue
21437  ruby53816   libruby.1.dylib                 ruby_dtrace_probe ruby-probe

As you can see from the list in the last column of the output, probes are available between method invocations, runs of the garbage collector, creation and destruction of objects and exceptions. The last probe actually allows the application writer to fire an arbitrary ruby probe containing application specific data from ruby code.

A full list of probes and arguments supplied to them is available at Joyent's Ruby provider wiki page.

Example 1: Tracing execution flow through your application

Lets start by tracing the execution flow through a small Ruby program.

Simple Ruby Program

class World
  def say(message)
    puts message
  end
end

world = World.new
world.say('hello')

This small Ruby program creates an instance of the World class, sends it the say message with hello as a String parameter which is printed to the console.

execution-flow.d

ruby$target:::function-entry
{
    printf("%s:%s\n", copyinstr(arg0), copyinstr(arg1));
}

ruby$target:::function-return
{
   printf("%s:%s\n", copyinstr(arg0), copyinstr(arg1));
}

This particular script enables the function-entry probe on the Ruby provider, and prints the first and second arguments passed to the probe in a C-style printf command.

The first and second arguments passed are provider specific, but in the Ruby provider's case for these probes they are always the class/module and method names being executed.

The $target variable enables the probe on the PID of the command specified via the -c parameter to DTrace itself.

Results

$> sudo dtrace -q -F -s execution-flow.d -c "ruby hello.rb"
CPU FUNCTION
1  -> rb_call0                              Class:inherited
1  <- rb_call0                              Class:inherited
1  -> rb_call0                              Module:method_added
1  <- rb_call0                              Module:method_added
1  -> rb_call0                              Class:new
1    -> rb_call0                            Object:initialize
1    <- rb_call0                            Object:initialize
1  <- rb_call0                              Class:new
1  -> rb_call0                              World:say
1    -> rb_call0                            Object:puts
1      -> rb_call0                          IO:write
1      <- rb_call0                          IO:write
1      -> rb_call0                          IO:write
1      <- rb_call0                          IO:write
1    <- rb_call0                            Object:puts
1  <- rb_call0                              World:say

Taking a look at the results we can almost visually 'see' how the script was parsed and executed. First Class was 'inherited', this is part of the creation of our 'World' class, then we defined World#say (invoking the Module:method_added method) to contain some operations. We then created a new instance of our class (Class:new and Object:initialize to create and construct our object), and then invoked World#say which we can see calls Object:puts and IO:write.

(In this particular case, the program is small and the instructions simple, however just add "require 'rubygems'" to the top of the source and re-run the DTrace script again and you'll quickly be overwhelmed with too much information - writing effective DTrace scripts is an art, but it's well worth learning to ensure you get the answers you're looking for)

Example 2: Individual Method Performance

Lets use DTrace to take another look at our application from a different perspective and see what methods are most expensive. To do this we'll use the function entry and return probes to capture a time stamp interval for each method call.

We'll also use an aggregate DTrace variable to store a running average of how long each method takes so that multiple method calls are recorded together and averaged across the count of method invocations, and we'll print the results according to most expensive method execution time.

Method Performance DTrace script

timestamps.d

ruby$target:::function-entry
{
  self->start = timestamp;
}

ruby$target:::function-return
/self->start/
{
  @[copyinstr(arg0), copyinstr(arg1)] = avg(timestamp - self->start);
  self->start = 0;
}

This script introduces a few more DTrace constructs, associative arrays and aggregate functions.

We enable two probes, function entry and function return on our Ruby program. When any method is entered, we capture a timestamp and store it in the 'start' variable. When any method is exited, we gather another timestamp, subtract it from the entry, and pass it to the avg DTrace aggregate function to be averaged.

The average execution time is then stored in an associative array, indexed by the module/class and method name (arg0 and arg1 respectively). Finally, we reset 'start' to zero once its no longer required.

A predicate is also set on the function return probe to fire only if we have a 'start' timestamp value, which prevents us from seeing any errors or miscalculations if we attach our DTrace script to an application that is already running (since after attaching, a return probe could fire for which we have no start timestamp).

Results

$> sudo dtrace -s timestamps.d -c "ruby hello.rb"
Object                   initialize                     9185
Module                   method_added                   10021
Class                    inherited                      25323
IO                       write                          98956

DTrace automatically prints data collected unless you supply a custom output format (eg. by using the C-style printf DTrace function as in the method flow example above) which in this case is the associative array, indexed by class/module and method name.

From these results we can see that IO#write was the slowest of the methods called, taking an average of 98956 nanaseconds to run, most likely due to its interation with the rest of the system and IO nature.

Example 3: Quantized Method Performance

Average values can often be affected by a few large values during program startup, so lets take a closer look and see what values consititue the calculation the averages above. To do this we'll use the DTrace quantize aggregate function, which will provide us with a distribution breakdown of each individual component within the average. We'll also specifically target the IO#write method, and update our Ruby program to print 'hello' 10 times to collect some more data over a period of invocations.

timestamps-q.d

ruby$target:::function-entry
/copyinstr(arg0) == "IO" && copyinstr(arg1) == "write"/
{
  self->start = timestamp;
}

ruby$target:::function-return
/copyinstr(arg0) == "IO" && copyinstr(arg1) == "write" && self->start/
{
  @[copyinstr(arg0), copyinstr(arg1)] = quantize(timestamp - self->start);
  self->start = 0;
}

Results

$> sudo dtrace -s timestamps-q.d -c "ruby hello.rb"

  IO                                                  write
           value  ------------- Distribution ------------- count
            4096 |                                         0
            8192 |@@@@@@@@@@@@@@@@@@@@                     10
           16384 |@@@@@@@@@@@@@@@@                         8
           32768 |@@                                       1
           65536 |                                         0
          131072 |@@                                       1
          262144 |                                         0

Here we see the distribution of how long each invocation of IO#write took. There was one invocation that particuarly long, over 131k nanoseconds, with most landing between 8k and 16k nanoseconds.

From here we could step further into the runtime and determine which particular IO#write call was slower than the others by inspecting the user stack inside the virtual machine, and/or by enabling probes in lower level providers.

Example 4: Memory allocation

To profile memory allocation we need to enable the object-create-start, object-create-done, and object-free probes. Creation of objects is separated into two probes to allow you to determine exactly how long it takes to construct an object.

First, lets create a simple balance script to check that objects are being allocated and deallocated correctly within the Ruby runtime. The script we'll use will create an associative array and index a counter by object type. Each time an object is created we'll increment the counter, conversely each time an object is freed we'll decrement the counter.

object-balance.d

ruby$target:::object-create-done { @[copyinstr(arg0)] = sum(1); }
ruby$target:::object-free        { @[copyinstr(arg0)] = sum(-1); }

Results

$> sudo dtrace -s object-balance.d -c "ruby hello.rb"

  NoMemoryError                                                     1
  SystemStackError                                                  1
  ThreadGroup                                                       1
  World                                                             1
  fatal                                                             1
  Object                                                            3

Glancing over the results we can see that Ruby is creating an instance of several error classes and a thread group during the run of our application (perhaps during startup), we can also see a single instance of our World class, and three other Objects that have also been allocated.

Our particular hello.rb script is quite small, and probably finishes executing before the garbage collector has had a change to reclaim any unused objects. If you run this script over a large application though, you'll see a line for each Object type in the application, and essentially a reference count of how many have been created and free'd.

In an ideal application, after garbarge collector has finished, all object types (except those required to keep the application running) will be listed with the value '0' alongside it indicating a corresponding deallocation for each allocation.

Example 5: Inspecting memory allocation points

The object-create-start/done probes also provide the source file and line number of where the allocation was made in Ruby script which we can use. For example if our World class came from another developer's library and we wanted to find out where it was allocated we could use the following script:

object-world-location.d

ruby$target:::object-create-start
/copyinstr(arg0) == "World"/
{
  printf("%s was allocated in file %s, line number %d\n", copyinstr(arg0), copyinstr(arg1), arg2);
}

Results

$> sudo dtrace -s object-world-location.d -c "ruby hello.rb"

  World was allocated in file hello.rb, line number 7

which matches our source file.

Example 6: Inspecting stack traces

We also saw above that several other 'Object's are created within the C portion of the Ruby interpreter upon startup. We can also inspect where these objects were created by saving the user C stack inside the virtual machine at the point of allocation.

object-user-stack.d

ruby$target:::object-create-start
/copyinstr(arg0) == "Object"/
{
  @[ustack(4)] = count();
}

This particular script uses the DTrace ustack function to access the actual runtime stack of the Ruby interpreter in userland at the point in time when the probe fired, to a depth of 4 method calls.

We then use the stack as an index into an associative array and store the number of times an Object type was created at the same point in the interpreter. This example really shows how flexible associative arrays can be in DTrace, by using a full stack trace as an index.

Results

$> sudo dtrace -s object-user-stack.d -c "ruby hello.rb"

          libruby.1.dylib`rb_obj_alloc+0x90
          libruby.1.dylib`Init_Object+0x130b
          libruby.1.dylib`rb_call_inits+0x15
          libruby.1.dylib`ruby_init+0x14f
            1

          libruby.1.dylib`rb_obj_alloc+0x90
          libruby.1.dylib`Init_IO+0x1059
          libruby.1.dylib`rb_call_inits+0x6a
          libruby.1.dylib`ruby_init+0x14f
            1

          libruby.1.dylib`rb_obj_alloc+0x90
          libruby.1.dylib`Init_Hash+0x903
          libruby.1.dylib`rb_call_inits+0x51
          libruby.1.dylib`ruby_init+0x14f
            1

Here we can see three separate stack traces indicating a Hash, IO and Object being created as part of the ruby_init method inside the Ruby interpreter.

Summary

DTrace is a very powerful framework, allowing you to really hypothesise and ask arbitrary questions about the behaviour of your system and applications. Often, the answer to one question will lead to another, and this is very much in the sprit of DTrace. The ability to script questions and format results allows you to slice behavioural data from any perspective and depth from your application, all the way to the operating system kernel.

DTrace scripts are the key to reducing complexity and understanding the true behaviour of your application at runtime, and I certainly recommend learning as much about the D script format and language as you can. Fine tuning your script to return the exact data you're after can be an art, but its well worth learning so that you can specify exactly what data you are after, and not be cluttered with too much information obscuring the information you are searching for.

Collections of commonly used DTrace scripts are available as part of the DTraceToolkit, in particular several very useful and high quality Ruby DTrace scripts. I'd recommend taking a look at them to see how probes can be used in combination with each other, also in multi-threaded environments.

In future articles I'll step further into using DTrace via Instruments, and also look at instrumenting your Rails or Merb application to collect runtime data about the performance of your web applications.

DTrace at Cocoaheads

2008-05-09T00:10:00Z

Last night we had our monthly Melbourne Cocoaheads meetup which was great. There were several talks given including one about the AUC, and I also gave a talk about DTrace, the popular dynamic tracing framework for Mac OS X Leopard and OpenSolaris.

I’ve uploaded the slides from my talk to slideshare for those interested - since most of the talk was a demo there are only a few slides included, however the links towards the end of the presentation provide some good references to more information about DTrace, the D language and using DTrace on your system. Happy DTracing! :)

Ruby Cocoa & Core Image at Cocoaheads

2008-04-11T01:00:00Z

Last night saw our first Melbourne Cocoaheads meet up for the year. An awesome night was had by all, there were several talks given by various people including myself about RubyCocoa & Core Image, XCode Organiser, Python, and the iPhone.

I gave a presentation about Ruby Cocoa and some of the Core Image related research I had been working on to integrate it into Attachment Fu for processing file uploads in Rails applications. I’ve uploaded the slides from my talk if anyone is interested in them.

.au Rubinius Sprint roundup!

2008-03-21T10:04:00Z

March 8/9th saw the first Australian Rubinius Sprint held in Sydney, at the Shangri-La Hotel, in Sydney’s famous Rocks district!

The sprint went really well, in total we had 22 attendees, including some international visitors such as including Evan Phoenix, the founder of the project and Eric Hodel from the United States.

The sprint started off with a comprehensive introduction to Rubinius by Evan, stepping through the project’s source layout and navigation, the architecture of the virtual machine, standard library and language.

From there everyone selected a spec test that was failing either due to error or non-implementation and started developing patches that were submitted to Rubinius’ lighthouse bug/patch tracker.

There were many highlights over the weekend, one in particular included seeing Rubygems working inside of Rubinius and being merged into the main Rubinius git repository which is a great milestone to have been achieved.

A total of ~60 patches were submitted to Lighthouse, which was an outstanding effort made by all, not to mention the fantastic ‘spinner’ spec progress indicator :)

We also made several visits to some of the great local restaurants and pubs nearby, such as Red Oak, The Australian, The Glenmore, and the Lord Nelson, not to mention the world speedboat championships that were on in the background of the conference hotel.

For me it was also great seeing the local community all come together to participate in such an awesome project. Great work guys! :)

I’d really like to thank Dylan for helping me organise the event, and many thanks to Evan and Eric for traveling out to Australia for the sprint.

A big kudos to Engine Yard for sponsoring the venue over the weekend, and to Glenn also took many more photos over the weekend which are available on Flickr.

Looking forward to the next sprint!

git bisect to the rescue!

2008-03-20T23:55:00Z

An interesting feature in Git I came across the other day is the bisect command.

”Find the change that introduced a bug by binary search”

Certainly sounds intriguing, turns out it can be quite useful.

The motivation behind bisect is to help you find out when a bug was introduced into the source base, by marking a known good and bad point within the source, and examining commits in between those points following a binary search algorithm (ie. eliminating half of the possible commits each successive iteration).

Linux developers use it to track down issues in the kernel spread across hundreds if not thousands of commits.

Lets see an example, suppose we have a project with the following (annotated) log:

commit bdf6fe9cd7c929487ffb6830b01a105836807f50
Author: Marcus Crafter <crafterm@redartisan.com>
Date:   Fri Mar 21 00:29:38 2008 +1100

    Added change 10       (version 2.0 aka HEAD)

commit af4331699b1ecfc39f077149801d80e5d83ab5fe
Author: Marcus Crafter <crafterm@redartisan.com>
Date:   Fri Mar 21 00:29:38 2008 +1100

    Added change 9

commit 9235af336946661c9c935c6f00a0b8590447dd6e
Author: Marcus Crafter <crafterm@redartisan.com>
Date:   Fri Mar 21 00:29:38 2008 +1100

    Added change 8  

commit 25718d202ee9b16a3d661d46a9d4dac5ff80ab52
Author: Marcus Crafter <crafterm@redartisan.com>
Date:   Fri Mar 21 00:29:38 2008 +1100

    Added change 7

commit af4932de08721a333a1c0c51d130c9d006f0bf61
Author: Marcus Crafter <crafterm@redartisan.com>
Date:   Fri Mar 21 00:29:38 2008 +1100

    Added change 6      (change introduced here)

..  ..  ..  ..

commit 463a5d5bd180e6b2d0eedaeb5227aeb357ca7827
Author: Marcus Crafter <crafterm@redartisan.com>
Date:   Fri Mar 21 00:29:38 2008 +1100

    Added change 1                 (version 1.0)

The history indicates 2 releases of the software package annotated via parenthesis.

Post release 2.0 lets say a defect is reported (for the reader we’ve flagged change 6 as the culprit, but lets pretend we don’t know this for the moment). The information reported is that the feature used to work in version 1.0, but it’s broken in version 2.0, but no one has any idea where.

So how can git help us track down what happened?

Using git bisect, we can do the following:

$> git bisect start
$> git bisect good version_1_0
$> git bisect bad
Bisecting: 4 revisions left to test after this
[388ec2c43dcccb710fd9e636c3ecf28ca2b42709] Added change 5

We’ve told git that the tag version_1_0 (ie. change 1) was the last known point when the issue didn’t occur, and that HEAD (ie. version_2_0) still has the issue. Given this information git takes these two known boundaries, and has chosen a midway point for us to inspect - change 5, which is half way between changes 1 and 10.

If the defect is present in this revision, it was introduced in this commit or beforehand (eliminating the need to check commits 6-10 to see when the issue first appeared), if the defect isn’t present, then it was introduced after (eliminating the need to check commits 1-5). Either way, we eliminate the need to check half the field of commits.

We test the software at change 5 and discover that the issue isn’t present, so we tell git this particular change is good:

$> git bisect good
Bisecting: 2 revisions left to test after this
[25718d202ee9b16a3d661d46a9d4dac5ff80ab52] Added change 7

git now fast forwards to change 7, which is midway between 5 and 10. We repeat the process again. Here things become interesting, after testing the software we find the defect has appeared - somewhere between 5 and 7, in this case a range of only 3 commits. We inform git that this point in the history is broken:

$> git bisect bad
Bisecting: 0 revisions left to test after this
[af4932de08721a333a1c0c51d130c9d006f0bf61] Added change 6

Now the result is obvious. If change 6 is broken then change 6 has introduced the issue (we found out above that change 5 was good). If change 6 is good, then change 7 must have introduced the issue. Testing finds out that 6 is bad, yielding it as the commit that first exhibited the issue:

$ git bisect bad
af4932de08721a333a1c0c51d130c9d006f0bf61 is first bad commit
commit af4932de08721a333a1c0c51d130c9d006f0bf61
Author: Marcus Crafter <crafterm@redartisan.com>
Date:   Fri Mar 21 00:29:38 2008 +1100

    Added change 6

:100644 100644 bb009e53210caf5bd64c46c9299a1c315e393c59 17d7ba157d12c79dd6337f091491e542f49b2c14 M  README

and git tells us some more information about it. Now we can take a closer look at the commit details and see what happened to correct it.

Once we’re done we can:

$> git bisect reset && git checkout master

to continue development since the bisect takes place on a separate branch not to interfere with any other work you were previously doing.

Due to the nature of bisecting the commit space by binary search, effectively searching across large ranges of commits can really be eased.

Rubinius Sprint in Sydney, Australia

2008-01-31T05:36:00Z

Dylan and I would like to announce that we’ll be running a Rubinius Sprint in Sydney, Australia, on the 8th/9th March 2008!

The Rubinius Sprint/Workshop is a weekend dedicated to learning and developing Rubinius, the next generation Ruby virtual machine. The spring is aimed at developers of all levels, the only requirement is that you have a keen interest to be involved with Rubinius and want to learn more. No particular experience with Rubinius is necessary however it would be beneficial if you’ve spent a bit of time prior to the sprint familiarizing yourself with the basics of Rubinius itself.

Everyone is invited to attend, registration details, etc, are all available at:

http://engineyard.eventwax.com/rubinius-sprint

Thanks to our awesome sponsor EngineYard, attending the event will be free (you’ll need to cover your own accommodation and food).

Places are limited to please register quick if you’d like to come.

Looking forward to seeing you all there!

Screen Capture via Ruby Cocoa!

2008-01-12T12:55:00Z

During the week a good friend of mine laid down the challenge to work out how to programatically create a screenshot of your Mac OSX desktop. The following article steps through the process of performing this, adding some charm to the operation to create a full desktop snapshot tool using Ruby Cocoa.

Before stepping into the code, I’ll first present a small extension module that all code snippets rely upon. It’s essentially a small extension to the OSX::CIImage class to simplify loading and saving of image files, and conversions between Core Image and Quartz Image objects (which we’ll need later).

extensions.rb

module OSX
  class CIImage      
    def save(target, format = OSX::NSJPEGFileType, properties = nil)
      bitmapRep = OSX::NSBitmapImageRep.alloc.initWithCIImage(self)
      blob = bitmapRep.representationUsingType_properties(format, properties)
      blob.writeToFile_atomically(target, false)
    end

    def cgimage
      OSX::NSBitmapImageRep.alloc.initWithCIImage(self).CGImage()
    end

    def self.from(filepath)
      raise Errno::ENOENT, "No such file or directory - #{filepath}" unless File.exists?(filepath)
      OSX::CIImage.imageWithContentsOfURL(OSX::NSURL.fileURLWithPath(filepath))
    end
  end
end

Capturing the Desktop

With our extensions code in place, we can use the new CGWindow API, recently added to Mac OSX 10.5, to snapshot our desktop:

capture-plain.rb

require 'osx/cocoa'
require 'extensions'

class Screen
  def self.capture
    screenshot = OSX::CGWindowListCreateImage(OSX::CGRectInfinite, OSX::KCGWindowListOptionOnScreenOnly, OSX::KCGNullWindowID, OSX::KCGWindowImageDefault)
    OSX::CIImage.imageWithCGImage(screenshot)
  end
end

Screen.capture.save('desktop.jpg')

An example screen capture is at the top of this article.

This works really well and is only a few lines of code. It’s quite fast, in fact the Apple documentation mentions ”For capturing pixels, the CGWindow API should demonstrate performance that is equal or better than the techniques used by the OpenGLScreenSnapshot and OpenGLScreenCapture samples”.

The only thing is that the user has no feedback that an actual screenshot was taken, other than the creation of the target image file.

So, lets build upon this and add some feedback.

Capturing the Desktop with a Fade operation

What we’ll do to make it obvious that a screenshot is being taken, is fade the desktop out to a black colour, take the screenshot of the original desktop content, and fade the desktop back to it’s original state.

The effect is similar to what OSX does while changing screen resolutions when you attach an external display or a projector to your Mac.

Implementation wise, we’ll add a fade operation to our Screen class, that will accept a block of code to perform in between fading the display out and back in again. The relevant Cocoa operations are documented in the Quartz Display Services guide.

Essentially we need to invoke CGAcquireDisplayFadeReservation() to obtain a fade reservation token, after which we can invoke CGDisplayFade() to fade the display to a solid colour and back. Once we’re done fading, we can release the fade reservation token with CGReleaseDisplayFadeReservation() (or allow it to time out).

capture-with-fade.rb

require 'osx/cocoa'
require 'extensions'

class Screen

  def self.capture
    fade do
      screenshot = OSX::CGWindowListCreateImage(OSX::CGRectInfinite, OSX::KCGWindowListOptionOnScreenOnly, OSX::KCGNullWindowID, OSX::KCGWindowImageDefault)
      OSX::CIImage.imageWithCGImage(screenshot)
    end
  end

  private

    def self.fade
      err, token = OSX::CGAcquireDisplayFadeReservation(OSX::KCGMaxDisplayReservationInterval)

      if err == OSX::KCGErrorSuccess
        begin
          OSX::CGDisplayFade(token, 0.3, OSX::KCGDisplayBlendNormal, OSX::KCGDisplayBlendSolidColor, 0, 0, 0, true)
          return yield if block_given?
        ensure
          OSX::CGDisplayFade(token, 0.3, OSX::KCGDisplayBlendSolidColor, OSX::KCGDisplayBlendNormal, 0, 0, 0, false)
          OSX::CGReleaseDisplayFadeReservation(token)
        end
      end
    end
end

Screen.capture.save('desktop.jpg')

Capturing the Desktop with a Fade and Snap Graphic

The fade looks really nice, but since other applications can also perform the same effect, lets embed a small graphic in between the fade of a camera to really show that we’re taking a picture of the desktop.

To do this, we need to capture the desktop in between the fade operation, and draw directly onto the display, without creating a window or any other graphical decorations. Capturing and drawing directly onto a display are also discussed in the Quartz documentation online.

Essentially, we need to use CGDisplayCapture(display) to capture a specified display. While it’s captured we have exclusive access to the display, and no other application will interfere with it. Then, we can use CGDisplayGetDrawingContext(display) to obtain a drawing context, and CGContextDrawImage() to draw an image directly to the display. Once we’re done showing our picture, we can then release our capture of the display using CGDisplayRelease(display).

The image we’ll use is above (or grab another one you’d like to use), save is as nikon.jpg alongside the following script.

capture-with-fade-and-graphic.rb

require 'osx/cocoa'
require 'extensions'

class Screen

  def self.capture
    fade do
      screenshot = OSX::CGWindowListCreateImage(OSX::CGRectInfinite, OSX::KCGWindowListOptionOnScreenOnly, OSX::KCGNullWindowID, OSX::KCGWindowImageDefault)
      OSX::CIImage.imageWithCGImage(screenshot)
    end
  end

  private

    def self.fade
      err, token = OSX::CGAcquireDisplayFadeReservation(OSX::KCGMaxDisplayReservationInterval)

      if err == OSX::KCGErrorSuccess
        begin
          OSX::CGDisplayFade(token, 0.3, OSX::KCGDisplayBlendNormal, OSX::KCGDisplayBlendSolidColor, 0, 0, 0, true)

          snap(token)

          return yield if block_given?
        ensure
          OSX::CGDisplayFade(token, 0.3, OSX::KCGDisplayBlendSolidColor, OSX::KCGDisplayBlendNormal, 0, 0, 0, false)
          OSX::CGReleaseDisplayFadeReservation(token)
        end
      end
    end

    def self.snap(token)
      display = OSX::CGMainDisplayID()

      if OSX::CGDisplayCapture(display) == OSX::KCGErrorSuccess
        begin
          ctx = OSX::CGDisplayGetDrawingContext(display)
          if ctx
            pic = OSX::CIImage.from('nikon.jpg')

            OSX::CGDisplayFade(token, 0.0, OSX::KCGDisplayBlendSolidColor, OSX::KCGDisplayBlendNormal, 0, 0, 0, true)

            # calculate middle of the screen for the images location
            display_width, display_height = OSX::CGDisplayPixelsWide(display), OSX::CGDisplayPixelsHigh(display)
            pic_width, pic_height = pic.extent.size.width, pic.extent.size.height
            position_x, position_y = (display_width - pic_width) / 2.0, (display_height - pic_height) / 2.0

            OSX::CGContextDrawImage(ctx, OSX::NSRectFromString("#{position_x} #{position_y} #{pic_width} #{pic_height}"), pic.cgimage)

            sleep(0.7)

            OSX::CGDisplayFade(token, 0.0, OSX::KCGDisplayBlendNormal, OSX::KCGDisplayBlendSolidColor, 0, 0, 0, true)
          end
        ensure
          OSX::CGDisplayRelease(display)
        end
      end
    end
end

Screen.capture.save('desktop.jpg')

Summary

First we created a simple capture class that used the new CGWindow API in Mac OSX 10.5, then we built upon that adding a fade effect around the actual screen capture. Next we drew an image directly on the display in between the fade, to make it even more obvious that we were taking a screenshot.

There we have it, a really useful tool for capturing screenshots of your desktop programatically.

Special Thanks!

Thanks to Lachlan for the challenge mate! :)
Thanks to Pete for your help with the Cocoa desktop fade semantics.
Thanks to DSevilla for the camera image used above.

Cool Effects with Core Image!

2007-12-31T02:29:00Z

In a previous article I described how to use Core Image as the backend image processor for Attachment Fu in your Rails applications. In that particular article we looked at supporting image scaling and thumbnails to be compatible with the other Attachment Fu backends such as RMagick and ImageScience.

With Core Image available however, we have an entire range of post processing filters available to use at our fingertips. In this article we’ll step through a few of these additional filter options that you can use to post process your images with.

Here’s a few examples of what we can do with Core Image post file upload. All of the following examples use the following input image taken in Berlin while at RailsConf EU (also used in the performance measurements article):

Greyscale or Sepia

A scaled version of the source image is cool, but how about an automatic greyscale or sepia version of the image:

Greyscale

Sepia

Code Fragment

module RedArtisan
  module CoreImage
    module Filters
      module Color

        def greyscale(color = nil, intensity = 1.00)
          create_core_image_context(@original.extent.size.width, @original.extent.size.height)

          color = OSX::CIColor.colorWithString("1.0 1.0 1.0 1.0") unless color

          @original.color_monochrome :inputColor => color, :inputIntensity => intensity do |greyscale|
            @target = greyscale
          end
        end

        def sepia(intensity = 1.00)
          create_core_image_context(@original.extent.size.width, @original.extent.size.height)

          @original.sepia_tone :inputIntensity => intensity do |sepia|
            @target = sepia
          end
        end

      end
    end
  end
end

Exposure and Noise Control

Another option for us is to automatically adjust exposure and noise parameters upon upload to brighten images up, or remove unwanted noise from lower quality images:

1 F-Stop

2 F-Stops

Noise Removal

Code Fragment

module RedArtisan
  module CoreImage
    module Filters
      module Quality

        def reduce_noise(level = 0.02, sharpness = 0.4)
          create_core_image_context(@original.extent.size.width, @original.extent.size.height)

          @original.noise_reduction :inputNoiseLevel => level, :inputSharpness => sharpness do |noise_reduced|
            @target = noise_reduced
          end
        end

        def adjust_exposure(input_ev = 0.5)
          create_core_image_context(@original.extent.size.width, @original.extent.size.height)

          @original.exposure_adjust :inputEV => input_ev do |adjusted|
            @target = adjusted
          end          
        end

      end
    end
  end
end

Watermarking

Sometimes we’d like to automatically add a watermark to our images, either with a single watermark image, or as a tiled watermark image:

Single Watermark

Tiled Watermark

Code Fragment

module RedArtisan
  module CoreImage
    module Filters
      module Watermark

        def watermark(watermark_image, tile = false, strength = 0.1)
          create_core_image_context(@original.extent.size.width, @original.extent.size.height)

          if watermark_image.respond_to? :to_str
            watermark_image = OSX::CIImage.from(watermark_image.to_str)
          end

          if tile
            tile_transform = OSX::NSAffineTransform.transform
            tile_transform.scaleXBy_yBy 1.0, 1.0

            watermark_image.affine_tile :inputTransform => tile_transform do |tiled|
              tiled.crop :inputRectangle => vector(0, 0, @original.extent.size.width, @original.extent.size.height) do |tiled_watermark|
                watermark_image = tiled_watermark
              end
            end
          end

          @original.dissolve_transition :inputTargetImage => watermark_image, :inputTime => strength do |watermarked|
            @target = watermarked
          end
        end

      end
    end
  end
end

Funky Effects

We can also use cool and funky effects used in applications like Photobooth, here’s an example using the edge colouring algorithm:

Edges

Core Fragment

module RedArtisan
  module CoreImage
    module Filters
      module Effects

        def edges(intensity = 1.00)
          create_core_image_context(@original.extent.size.width, @original.extent.size.height)

          @original.edges :inputIntensity => intensity do |edged|
            @target = edged
          end
        end

      end
    end
  end
end

The sign artwork works particularly well with this algorithm.

Core Image Processor

All of the code above is also available as a usable image processor via git.

Some examples of using the processor:

require 'red_artisan/core_image/processor'

# generate some test output images for various effects

processor = RedArtisan::CoreImage::Processor.new('berlin.jpg')

grey = processor.greyscale
grey.save 'results/berlin-grey.jpg'

sepia = processor.sepia
sepia.save 'results/berlin-sepia.jpg'

watermarked = processor.watermark('watermark_image.png')
watermarked.save 'results/berlin-watermarked.jpg'

watermarked = processor.watermark('watermark_image.png', true)
watermarked.save 'results/berlin-watermarked-tiled.jpg'

noise_reduced = processor.reduce_noise
noise_reduced.save 'results/berlin-noise-reduced.jpg'

exposure_adjusted = processor.adjust_exposure
exposure_adjusted.save 'results/berlin-exposure-adjusted-half-stop.jpg'

exposure_adjusted = processor.adjust_exposure(2.0)
exposure_adjusted.save 'results/berlin-exposure-adjusted-two-stops.jpg'

edge = processor.edges
edge.save 'results/berlin-edge.jpg'

Summary

The above shows us only a fraction of what can be done with the 100+ filters Core Image provides by default. There’s many other filters that let you create all sorts of effects with single and multiple images combined. Enjoy!

Core Image Performance

2007-12-16T11:42:00Z

Following my previous post, a few people have asked me how well Core Image performs in comparison to RMagick and ImageScience when used as part of Attachment Fu. To answer these questions, I’ve spent a bit of time collecting some performance results.

Please note that as with all performance testing, results will vary according to many parameters such as hardware, processing power, and even the input image content itself, as you’ll see below.

Naturally Core Image should be faster since it will run hardware accelerated on my MacBook Pro, so please take these results more as an indication of library characteristics rather than final timings. The tests I performed also mirrored how each library was being invoked by Attachment Fu, and beyond performance there’s also several other tangible benefits to Core Image such as deployment and access via RubyCocoa to keep in mind as well.

The first test performs 5 successive resizes of a 1mb image under each library (from 1250x833 to 640x480). The input image is a complex photo (smaller version above) taken in Berlin of parts of the Berlin Wall, including a high colour range and lots of shapes and sizes:

Both RMagick and ImageScience yield consistent results as expected. Core Image’s resize values are interesting as successive resizes are twice as fast than the first, which I speculate would include an initial Core Image to OpenGL compilation phase of the resize operation being performed.

Similar characteristics can be observed with a slightly larger image size of around 2.5mb (2200x1467 to 640x480):

In both cases, Core Image performs really well, particularly on consecutive runs.

The actual image content being resized also affects results as well - the following test uses a blank image of identical dimensions to the 1mb Berlin image (1250x833 to 640x480):

Finally, the following graph shows the results of resizing 6 versions of the Berlin image with each library, at increasing size & dimensions to half their original size. The results plotted for each measurement are calculated over the average of 5 resizes of each image.

At small image sizes, we can see the difference in resize time to be essentially negligible, however as image size increase up to 500kb, the hardware acceleration of Core Image starts to shine, particularly around the 2.5mb - 5mb range and beyond where it screams along.

There does seem to be a limit to performance gains, on Friday Ben and I also made a few experiments with really large image sizes (TIFF files around 90mb, resizing from 5436x4080 to 640x480), and noticed that Core Image can be slower than Image Science under these conditions:

At this stage I can only speculate as to why this occurs, and it deserves further inspection.

Another interesting aspect to look at is the actual on disk size of the resized images. The following is a directory listing of the results after the 2.5mb image (2200x1467 resize to 640x480):

crafterm  staff  153492 16 Dec 22:30 core_image-complex_resized.jpg
crafterm  staff  288455 16 Dec 22:30 image_science-complex_resized.jpg
crafterm  staff  356827 16 Dec 22:30 rmagick-complex_resized.jpg

Core Image’s default compression range is quite impressive, and while I’m sure the other libraries compression factors can be fine tuned I suspect it would also affect their relative performance measurements.

All measurements shown in the graphs are in seconds, and the test machine was my MacBook Pro, 15” Intel Core 2 Duo, 2.16 Ghz with an ATI Radeon X1600 video card with 128mb vram. I’d certainly be keen to see how other types of hardware perform, so please feel free to run the test code on your system and send me the resultant graphs, and I’ll add them to the project.

All test code and input images (except for the 90mb example due to copyright) are available in a git repository online.

Attachment_fu magic with Core Image and Ruby Cocoa!

2007-12-12T23:42:00Z

Like many of us in the Rails world, I use attachment_fu to handle file uploads in my Rails applications. Attachment_fu does a great job, in particular with it’s ability to scale and generate multiple sized copies of images with various processing back ends including ImageScience, RMagick and MiniMagic, not to mention it’s flexible storage options, all from the comfort of a DSL:

has_attachment :content_type => :image, 
               :resize_to    => '640x400',
               :storage      => :file_system, 
               :size         => 1.kilobyte .. 3.megabytes,
               :thumbnails   => { :small => '50x50', :medium => '320x200' }

Working on under Mac OS X though, it’s often been a challenge to get these underlying libraries installed. General community consensus is that RMagick leaks memory, and ImageScience is built upon FreeImage and RubyInline which requires a development environment to compile, install and run.

As developers MacPorts lets us all build and install these libraries comfortably, however the biggest beef I’ve had is that under the hood of every recent Mac OS X installation, there’s actually a great image processing library already available to us - Core Image.

Core Image

Core Image has been a part of Mac OS X since Tiger and is part of the QuartzCore framework, offering a flexible filter/pipeline based approach to manipulating images via transforms. Once of the most exciting things about Core Image though, is that it processes images using a subset of the OpenGL Shading Language, and when available will use the GPU to render, all in accelerated hardware near or in real time! In environments where the available GPU is not supported, Core Image automatically falls back to the CPU for processing seamlessly giving us the best of both worlds.

Until recently, access to Core Image has only been available via languages such as Objective-C. However with the release of Leopard, Ruby has become an officially supported language within XCode, and in particular RubyCocoa is available by default under every Leopard Mac OS X installation (in Tiger it can be installed separately).

So now it’s even easier for us to take full advantage of the underlying power of these Cocoa API’s, directly from Ruby itself.

Let’s get started!

In this article, I’ll describe how to add support for using Core Image as the image processing library within attachment_fu.

Once we’re finished, attachment_fu will handle all your uploads using Core Image for resizing and thumbnail generation (most likely hardware accelerated inside your Mac’s GPU), if you have Leopard it won’t require any 3rd party library to be installed to work, and it will handle any Mac OS X supported image format, which as of 10.5, includes RAW.

It’s even more particularly enticing if you deploy your Rails application to an XServe which includes a Core Image supported GPU.

To do this, we’ll need to perform the following steps:

Create an image manipulation class that uses Core Image
Integrate this new class into attachment_fu, by writing a new attachment_fu processor module
Optionally, update attachment_fu’s automatic image processing list, or rely on using the :processor directive in our has_attachment model definitions.

Create an image manipulation class that uses Core Image

Our first step is to create a new class that uses Core Image to resize and/or thumbnail a given image. To do this, we’ll need to define an API to accept the source image, some new dimensions and specify where the resized version should be rendered to.

Inside of the class, we’ll use Core Image Filters to perform the actual work.

Core Image Filters allow you to create a ‘pipeline’ of transforms that’s performed on a given image. Mac OS X includes many filters by default, allowing you to perform all sorts of effects on your image, but the one we’re interested in at the moment is the Lanczos Scale Transform filter.

The Lanczos Scale Transform produces a high quality, scaled version of the source image using a well defined algorithm.

In addition to this, we’ll pre-process the image with an Affine Clamp filter which will make the image infinitely big by clamping the image’s edges outwards. We do this so that there’s no edge imperfections introduced due to rounding/ceiling of dimensions when scaling. After the Lanczos scaling has done it’s trick, we then crop the image to our target dimensions for rendering.

Here’s an example of how we’ll use the classes API:

p = Processor.new OSX::CIImage.from(path_to_image)
p.resize(640, 480)
p.render do |result|
  result.save('resized.jpg', OSX::NSJPEGFileType)
end

Processor.resize(width, height) will perform a hard resize to the given dimensions, where as Processor.fit(size) will resize the image to a scale that fits its aspect ratio. These two methods are provided as attachment_fu includes some extra geometry processing code that lets us use RMagick style geometry stings to specify dimensions as fixed values, percentages, scales, or relative aspect ratio sizes that we’ll leverage off.

Here’s the actual classes implementation

vendor/core_image/processor.rb

require 'rubygems'
require 'osx/cocoa'
require 'active_support'

# Copyright (c) Marcus Crafter <crafterm@redartisan.com>
#
class Processor

  def initialize(original)
    @original = original
  end

  def resize(width, height)
    create_core_image_context(width, height)

    scale_x, scale_y = scale(width, height)

    @original.affine_clamp :inputTransform => OSX::NSAffineTransform.transform do |clamped|
      clamped.lanczos_scale_transform :inputScale => scale_x > scale_y ? scale_x : scale_y, :inputAspectRatio => scale_x / scale_y do |scaled|
        scaled.crop :inputRectangle => vector(0, 0, width, height) do |cropped|
          @target = cropped
        end
      end
    end
  end

  def fit(size)
    original_size = @original.extent.size
    scale = size.to_f / (original_size.width > original_size.height ? original_size.width : original_size.height)
    resize (original_size.width * scale).to_i, (original_size.height * scale).to_i
  end

  def render(&block)
    raise "unprocessed image: #{@original}" unless @target
    block.call @target
  end

  private

    def create_core_image_context(width, height)
        output = OSX::NSBitmapImageRep.alloc.initWithBitmapDataPlanes_pixelsWide_pixelsHigh_bitsPerSample_samplesPerPixel_hasAlpha_isPlanar_colorSpaceName_bytesPerRow_bitsPerPixel(nil, width, height, 8, 4, true, false, OSX::NSDeviceRGBColorSpace, 0, 0)
        context = OSX::NSGraphicsContext.graphicsContextWithBitmapImageRep(output)
        OSX::NSGraphicsContext.setCurrentContext(context)
        @ci_context = context.CIContext
    end

    def vector(x, y, w, h)
      OSX::CIVector.vectorWithX_Y_Z_W(x, y, w, h)
    end

    def scale(width, height)
      original_size = @original.extent.size
      return width.to_f / original_size.width.to_f, height.to_f / original_size.height.to_f
    end

end

module OSX
  class CIImage
    include OCObjWrapper

    def method_missing_with_filter_processing(sym, *args, &block)
      f = OSX::CIFilter.filterWithName("CI#{sym.to_s.camelize}")
      return method_missing_without_filter_processing(sym, *args, &block) unless f

      f.setDefaults if f.respond_to? :setDefaults
      f.setValue_forKey(self, 'inputImage')
      options = args.last.is_a?(Hash) ? args.last : {}
      options.each { |k, v| f.setValue_forKey(v, k.to_s) }

      block.call f.valueForKey('outputImage')
    end

    alias_method_chain :method_missing, :filter_processing

    def save(target, format, properties = nil)
      bitmapRep = OSX::NSBitmapImageRep.alloc.initWithCIImage(self)
      blob = bitmapRep.representationUsingType_properties(format, properties)
      blob.writeToFile_atomically(target, false)
    end

    def self.from(filepath)
      OSX::CIImage.imageWithContentsOfURL(OSX::NSURL.fileURLWithPath(filepath))
    end
  end
end

The processor class uses a few Ruby idioms, in particular with the filter processing and rendering code. The filtering code leverages blocks and method_missing to provide a declarative approach to defining filters and their parameters:

@original.affine_clamp :inputTransform => OSX::NSAffineTransform.transform do |clamped|
  clamped.lanczos_scale_transform :inputScale => inputScale, :inputAspectRatio => ratio do |scaled|
    scaled.crop :inputRectangle => vector do |cropped|
      @target = cropped
    end
  end
end

(note that the methods affine_clamp, lanczos_scale_transform and crop don’t actually exist on OSX::CIImage, they’re applied dynamically)

A few helper methods have also been added to OSX::CoreImage to ease construction and serialization. Rendered output file types can be NSBMPFileType, NSGIFFileType, NSJPEGFileType, NSPNGFileType, or NSTIFFFileType. See the XCode API documentation for an NSBitmapImageRep class for more information about the various properties for each type.

Integrating our core image processor into attachment_fu

Now that we have a class that can resize images using Core Image, we just need to integrate it with attachment_fu.

Attachment_fu’s design is quite modular, allowing us to add a new image processor via writing a module that’s mixed in at runtime. Essentially we need to define a module within the Technoweenie::AttachmentFu::Processors namespace, that will extend the functionality of the ‘process_attachment’ method.

The common approach is to do this via alias_method_chain, which decorates the existing process_attachment method with new functionality.

Here’s the new module:

technoweenie/attachment_fu/processors/core_image_processor.rb

require 'core_image/processor'

module Technoweenie # :nodoc:
  module AttachmentFu # :nodoc:
    module Processors
      module CoreImageProcessor
        def self.included(base)
          base.send :extend, ClassMethods
          base.alias_method_chain :process_attachment, :processing
        end

        module ClassMethods
          def with_image(file, &block)
            block.call OSX::CIImage.from(file)
          end
        end

        protected
          def process_attachment_with_processing
            return unless process_attachment_without_processing
            with_image do |img|
              self.width  = img.extent.size.width  if respond_to?(:width)
              self.height = img.extent.size.height if respond_to?(:height)
              resize_image_or_thumbnail! img
              callback_with_args :after_resize, img
            end if image?
          end

          # Performs the actual resizing operation for a thumbnail
          def resize_image(img, size)
            processor = Processor.new(img)
            size = size.first if size.is_a?(Array) && size.length == 1
            if size.is_a?(Fixnum) || (size.is_a?(Array) && size.first.is_a?(Fixnum))
              if size.is_a?(Fixnum)
                processor.fit(size)
              else
                processor.resize(size[0], size[1])
              end
            else
              new_size = [img.extent.size.width, img.extent.size.height] / size.to_s
              processor.resize(new_size[0], new_size[1])
            end

            processor.render do |result|
              self.width  = result.extent.size.width  if respond_to?(:width)
              self.height = result.extent.size.height if respond_to?(:height)
              result.save self.temp_path, OSX::NSJPEGFileType
              self.size = File.size(self.temp_path)
            end
          end          
      end
    end
  end
end

The module brings the core image based processing class we’ve written above into scope, and then proceeds to define a CoreImageProcessor module within the Technoweenie::AttachmentFu::Processors namespace. When this module is included, it then aliases process_attachment to add some new functionality, essentially the process_attachment_with_processing and resize_image methods.

Most of the code in this module surrounds calling the processor class’ API with the correct resize values based on the range of possible geometry values attachment_fu allows. The ImageScience and RMagick processors look quite similar.

Update attachment_fu’s automatic image processing list

Attachment_fu includes several processors which are tried in order at startup to work out which image processing engine to use, based on what underlying libraries, etc, are available on your machine.

This step is optional because we can either update this list so that our Core Image processor is part of this selection, or we can specify the processor directly when defining a has_attachment on a model:

has_attachment :content_type => :image, 
               :processor    => :core_image,
               :resize_to    => '640x400',
               :storage      => :file_system, 
               :size         => 1.kilobyte .. 3.megabytes,
               :thumbnails   => { :small => '50x50', :medium => '320x200' }

To update the default list, open up the attachment_fu.rb source file, and update the @@default_processors class variable from:

module Technoweenie
  module AttachmentFu
    @@default_processors = %w(ImageScience Rmagick MiniMagick)

to:

module Technoweenie
  module AttachmentFu
    @@default_processors = %w(CoreImage ImageScience Rmagick MiniMagick)

which will register the Core Image processor module for inclusion when attachment_fu searches for image processors.

Summary

We’ve created a class that uses Core Image to resize an image to given dimensions, using a high quality Lanczos Scale transform, via RubyCocoa. We’ve integrated it into attachment_fu by creating a new processor module that can be specified in the default image processing search list, or directly in a has_attachment definition.

I want it!

To make things easy, I’ve created a git repository that includes all of the above files so you can keep up to date, and the project format is in a structure you can export directly into your attachment_fu installation. To access the source, use the following command:

$> git clone git://git.redartisan.com/af_ci.git

This will check out the attachment_fu core image project that you can copy across into your attachment_fu installation (or perform a nice git export of the source directly).

Once you’ve installed the source files in your attachment_fu plugin, apply the supplied patch to update attachment_fu’s list of supported image processors. You’ll need to restart your Rails application to reload the plugin, after which you’ll be using Core Image to process attachments!

Future

I have several further enhancements and ideas surrounding the core image processor which I’ll talk about in further articles - if you have any improvements to the code, patches are also more than welcome. Enjoy!

[Update]

To facilitate updates to the code, I’ve imported the source into a git repository rather than distribute via the tar/gz the original post referenced.

[Update II]

Now that Technoweenie has imported his sources into github, I’ve created a child attachment_fu repository that includes all of the above updates to use Core Image with Attachment Fu.

Extracting database content as bootstrap or fixture data

2007-11-28T00:15:00Z

Recently I’ve been doing lots of work with databases full of existing data and often have needed to extract data out to into YAML files to use either as bootstrap data (particularly images coming from attachment_fu that need to be preloaded after deployment) or as fixtures (yep, sometimes the data is just too complex to mock).

To ease the process I’ve created a script that I use inside of TextMate, which lets me convert a CSV exported file from CocoaMySQL to a YAML file, suitable for the db:bootstrap rake task or fixture data, all at the close distance of a keyboard shortcut.

First, to get the data out of the database, open up CocoaMySQL, select your table and view its content, and go to ‘File -> Export -> Table Content Result -> Text File’.

Save the exported contents.

Then you’ll need the following script:

#!/usr/bin/env ruby
#
# Format CSV output of cocoamysql into a fixture file
#
# "id","name","mime_type","extensions","icon_url"
# "1","unknown","unknown/unknown","||","/images/icon/file_unknown.gif"
# "2","image/tiff","image/tiff","|tiff|tif|","/images/icon/blank.png"

require 'csv'

class String
  def unquote
    self.gsub(/^"|"$/, '')
  end
end

# first line contains the field names
line = gets
fields = line.split('","').collect {|f| f.unquote.chomp}

CSV::Reader.parse(STDIN) do |row|
  fixture = "#{row[1].downcase}_#{row[0]}:\n"
  fields.each_with_index do |field, i|
    fixture += "  #{field}: #{row[i]}\n"
  end

  puts fixture; puts
end

Which we’ll add as a new ‘Command’ inside of a TextMate bundle.

To do this, open up TextMate, and select the ‘Edit Commands’ menu item

Then, in a custom bundle add a new command (+ button along the bottom of the dialog) and paste the contents of the script above.

Select ‘Entire Document’ as the input source, and ‘New Document’ as the output, this will ensure that you don’t overwrite your CSV file incase you require it later.

Then we need to reload the bundles so that TextMate knows about your new command. To do this, select the ‘Reload Bundles’ menu item

And we’re all set to go. Open up your CSV file, and convert it to a YAML file either via the keyboard shortcut defined in your Command (mine was ctrl-shift-cmd-F) or the menu item from your custom bundle and voila, a converted YAML document will appear which you can save directly to db/bootstrap or your fixtures directory. Enjoy.

RailsConf Overview Slides

2007-11-04T11:26:00Z

Arriving back in Melbourne, after having such a fantastic trip through Europe to attend RailsConf, visit clients and travel, it was great to see everyone at our local user group again at the end of last month.

I gave a quick presentation covering all the fun we all had at RailsConf while away.

It was particularly cool being able to talk about the excitement and atmosphere at the conference, and also at RejectConf which was once again a highlight of the trip.

In just under three weeks we’ll be hosting RailsCamp in Melbourne, which I’m also looking forward to. The previous camp held in Gosford was a blast, and I’m excited to see it happening again!