MeX - Merb eXception tracking
==============

Version 0.2.0

==============

MeX is a flat Merb app that provides a web service for logging exceptions
raised by other web apps.

MeX can be run in two different ways: as a stand alone web service or as
a Merb plugin.

== Running MeX as a stand-alone web service

Start from the command line with:

  mex

The mex command takes the same arguments as merb does on the command line.

By default, this will start the MeX Merb app running on port 4911.  It will
also by default use a sqlite database located in the directory from which you
run the app.  To setup the database, do the following:

  $ mex -i
  $ >> Mex.auto_migrate!

If you already have a database, you can put your configuration into a YAML
file.

  mex --config path/to/config

The config file is a YAML file that can look something like this:

---
:merb:
  :port: 4911
:development:
  :adapter: sqlite3
  :database: mex.sqlite3

Under the :merb key, you can use any of the configuration settings that map
to the arguments that merb accepts on the command line.

As for the database, there are two options: either the different environments
can be specified, as above, or a different database configuration can be
provided.  Providing a different database.yml file is done this way:

:database
  :config_file: path/to/file.yml

For this to work, the merb_database gem must be patched:

http://merb.lighthouseapp.com/projects/7588/tickets/92-extend-merb-datamapper-for-custom-configuration

Once up and running, from within any Merb app, you can log an exception from
within the exceptions.rb controller like this:

class Exceptions < Application
    def internal_server_error
      exception   = self.params[:exception]
      request     = self.request
      orig_params = self.params[:original_params]

      params = {}
      params['mex[app_name]']        = 'myApp'
      params['mex[exception_class]'] = exception.name
      params['mex[controller_name]'] = orig_params[:controller]
      params['mex[action_name]']     = orig_params[:action]
      params['mex[message]']         = exception.message
      params['mex[backtrace]']       = exception.backtrace.to_yaml
      params['mex[params]']          = orig_params.to_yaml
      params['mex[environment]']     = request.env.merge( 'process' => $$ ).to_yaml
      params['mex[url]']             = "#{request.protocol}#{request.env["HTTP_HOST"]}#{request.uri}"

      Net::HTTP.post_form( URI.parse('http://localhost:4911/mexes'), params ).body
    end
end

You can then view the exceptions here:

http://localhost:4911

== Running MeX as a Merb Plugin

After installing the MeX gem, require the gem in init.rb:

dependency "mex"

Then, from the exceptions.rb controller, do the following:

def internal_server_error
  Mex.create_from_controller( self )
  'there was an error'
end

Exceptions can then be viewed here:

http://yourAppName.com/mex

== Building the gem

  $ sudo rake gem install

CREDITS

MeX is heavily inspired by exception_logger - http://github.com/defunkt/exception_logger

Jamis Buck  - original exception_notification plugin
Rick Olson  - original model/controller code
Josh Goebel - design