kaeruera

kaeruera copied to clipboard

= KaeruEra

KaeruEra is a bare-bones error tracking application for ruby, tracking errors that occur in other ruby applications.

It is similar to Errbit[1] but with a much smaller feature set. The only advantages that KaeruEra has over Errbit are more advanced search features, fewer dependencies, and a smaller footprint. There are no notification features, source control integration, issue tracker integration, user information tracking, deploy tracking, or GitHub/LDAP authentication. You are responsible for manually integrating the error reporter into the applications that will be reporting errors.

As another example of the simplicity, KaeruEra does not do error aggregation. Instead, for each error, it offers the ability to easily search for errors with the same class, message, backtrace line, etc.. Any results of that search can be manipulated as a unit.

KaeruEra is not designed to replace an existing error tracking application. It's designed to supplement an email notification about the error.

1. (https://github.com/errbit/errbit)

== Demo

• URL: http://kaeruera-demo.jeremyevans.net
• Login Email: demo
• Login Password: demo

== Source Control/Issue Tracker

https://github.com/jeremyevans/kaeruera

== License

KaeruEra is licensed under the MIT License.

== Design

The KaeruEra database and web server have a fairly simple design. There are only three tables in the database, users, applications, and errors. Each user can have multiple applications, and each application multiple errors.

In the database, each error is stored is a single row, document style. This uses PostgreSQL's advanced types, storing the backtrace for the error as an array of text fields (text[]), the environment, params, session information as jsonb (since they contain nested data). All of the error columns are indexed for easy searching.

The web site has a very basic bootstrap design, with only 4 main pages:

• Front page (choose an application)
• Search page (options for each search field)
• Error List page (see open errors for applications/search results)
• Error page (see all information about a particular error, with links to perform searches for similar errors)

=== Error Information Tracked

• Exception Class
• Exception Message
• Exception Backtrace
• Params
• Environment Variables
• Session Variables

The exception class, message, and backtrace are required and are taken from the underlying ruby exception.

The params, environment, and session information are optional, and you have to configure the reporting code to include the information.

=== Updating Errors

Most information for errors is immutable. The two exceptions are that each error has a notes field and an open/closed flag. As long as the error is open, the notes flag can be updated and it can be closed. Once it is closed, the error is completely immutable.

== Reporting Errors

KaeruEra is not airbrake compatible. Instead, it offers separate libraries for reporting errors. All libraries are shipped in the kaeruera gem, installable via:

gem install kaeruera

=== KaeruEra::DatabaseReporter

This library assumes you can have a direct connection to the database, and inserts the error directly into the database.

require 'kaeruera/database_reporter' REPORTER = KaeruEra::DatabaseReporter.new('postgres://db_user:pass@host:port/database', '[email protected]', 'app_name')

Here db_user is the PostgreSQL user name for the connection, email is the email address for the user account in the KaeruEra application, and app_name is the application name in KaeruEra.

=== KaeruEra::Reporter

This library uploads the error information to a server running the web application, via json.

require 'kaeruera/reporter' REPORTER = KaeruEra::Reporter.new('http://host:port/report_error', application_id, 'application_token')

You can use the "Reporter Info" page in the web application to get a line that will work for the given application.

=== KaeruEra::AsyncReporter

This library is the same as the KaeruEra::Reporter library, except it runs asynchronously, useful if the application does not have a fast connection to the KaeruEra server. The downside is you don't get the id of the error, and are not notified if there was a problem reporting the error.

require 'kaeruera/async_reporter' REPORTER = KaeruEra::AsyncReporter.new('http://host:port/report_error', application_id, 'application_token')

=== Usage

All three libraries for reporting errors have the same API:

REPORTER.report

If called without arguments, it assumes that $! is the error to report. This makes it easy to use in a rescue block:

begin #code rescue REPORTER.report end

If the error you want to report is not in $!, you can pass it via the :error option:

begin #code rescue => e begin #more code rescue REPORTER.report(:error => e) end end

The params, session, and environment variables are all passed as options :params, :session, and :env. In each case the values for those options should be hashes.

As reporters are designed to be used in rescue blocks, they swallow any errors raised internally, since the assumption is that it is better to raise the original error in that case.

The return value of the reporting methods is one of the following:

Integer :: The id of the error, indicating the error was successfully reported. false :: There was no error detected (:error option was not set and $! did not indicate an active error) true :: The async reporter received a valid error (it cannot tell whether the error was successfully reported). StandardError :: an exception occurred when trying to report the error, the return value is the exception.

=== Sinatra

If the application reporting errors is running Sinatra, you can probably put this in your error block to report errors to KaeruEra:

REPORTER.report(:params=>params, :env=>env, :session=>session, :error=>env['sinatra.error'])

=== Roda

If the application reporting errors is running Roda, you can probably use an error plugin block similar to this to report errors to KaeruEra:

plugin :error do |e| REPORTER.report(:params=>request.params, :env=>env, :session=>session, :error=>e) end

== Runtime Dependencies

=== KaeruEra::App (web server)

• PostgreSQL 9.4+
• pg
• roda
• sequel
• bcrypt
• forme
• json
• rack-compatible web server

=== KaeruEra::DatabaseReporter

• pg
• sequel

=== KaeruEra::Reporter / KaeruEra::AsyncReporter

• uri
• net/http
• json

== Heroku Setup

heroku create heroku addons:add heroku-postgresql:dev heroku pg:promote HEROKU_POSTGRESQL_COLOR_URL git push heroku master heroku run rake production_up heroku config:set
KAERUERA_SESSION_SECRET=ruby -rsecurerandom -e 'print SecureRandom.random_bytes(64).gsub("\x00"){((rand*255).to_i+1).chr}' heroku run irb -r ./models irb> KaeruEra::User.create(:email=>'foo', :password=>'bar')

== Manual Setup

=== Environment Setup

First, create an .env.rb setting the KAERUERA_SESSION_SECRET (>=64 bytes of random data) and KAERUERA_DATABASE_URL (database connection URL) environment variables.

The rest of the instructions assume you are not modifying the default database configuration, and that the database super user for your PostgreSQL database cluster is postgres. If those assumptions are inaccurate, you should substitute the appropriate values. Also, the examples below do not use a password for the accounts, so they will only work if localhost is trusted in PostgreSQL.

Create a user for the application:

createuser -U postgres kaeruera

Then, create databases for the application with that user:

createdb -U postgres -O kaeruera kaeruera_development createdb -U postgres -O kaeruera kaeruera_test createdb -U postgres -O kaeruera kaeruera_production

You could use the following .env.rb file:

ENV['KAERUERA_SESSION_SECRET'] ||= '...' ENV['KAERUERA_DATABASE_URL'] ||= case ENV['RACK_ENV'] when 'test' "postgres:///kaeruera_test?user=kaeruera&password=..." when 'production' "postgres:///kaeruera_production?user=kaeruera&password=..." else "postgres:///kaeruera_development?user=kaeruera&password=..." end

Then, you can migrate the database:

rake dev_up rake test_up rake production_up

=== User Account Setup

In development mode, the first time the server is started, if you haven't set up any users manually, a kaeruera user account (login/password kaeruera) and application named KaeruEraApp will automatically be created for you. It's recommended that you change the password for this user after logging in for the first time in development mode.

In all other cases, you have to setup your user accounts manually:

$ irb -r ./models KaeruEra::User.create(:email=>'foo', :password=>'bar')

It's recommended that you have a kaeruera user and KaeruEraApp application for that user, as that is where the web application will log any internal errors.

== Testing

To run all tests, use rake's default task:

rake

This assumes you have already created the test database and migrated the test database to the latest version. The following are additional requirements when running tests:

• minitest
• minitest-hooks
• unicorn
• capybara

== Naming

KaeruEra is a transliteration of the Japanese words for frog (kaeru) and error (era). One of the first popular error reporting apps for ruby was named Hoptoad (later renamed to Airbrake), and Errbit I'm guessing was chosen for its similarity to ribbit (the sound a frog makes) so this is in keeping with the frog theme.

== Author

Jeremy Evans [email protected]