README.md in zenbox-0.0.5 vs README.md in zenbox-0.0.6

- old
+ new

@@ -1,22 +1,24 @@ -Zenbox +Zenbox Gem ======== -This is the notifier gem for integrating apps with [Zenbox](http://zenbox.io). +An implementation of the Zenbox integration API for Ruby. It's super +simple and lets your sync your custom models with your gmail interface +in minutes -When an uncaught exception occurs, Zenbox will POST the relevant data -to the Zenbox server specified in your environment. Help ---- -For help with using Zenbox and this notifier visit [our support site](http://help.zenbox.io). +For help with using Zenbox and this notifier [email us](mailto://support@zenboxapp.com). -For discussion of Zenbox development check out the [mailing list](http://groups.google.com/group/hoptoad-notifier-dev). +Extension Installation +---------------------- -For SSL verification see the [Resources](https://github.com/zenbox/zenbox/blob/master/resources/README.md). +Visit [zenboxapp.com](http://getzenboxapp.com), click on "Install Zenbox Extension", and follow the instructions. + Rails Installation ------------------ ### Rails 3.x @@ -31,434 +33,43 @@ That's it! The generator creates a file under `config/initializers/zenbox.rb` configuring Zenbox with your API key. This file should be checked into your version control system so that it is deployed to your staging and production environments. -### Rails 2.x +Configuration +------------- -Add the zenbox gem to your app. In config/environment.rb: +Any ActiveRecord model that responds to `#email` can be easily integrated with two lines: - config.gem 'zenbox' - -or if you are using bundler: + include Zenbox::ModelHelper + zenbox_model methods - gem 'zenbox', :require => 'zenbox/rails' +where fields is just a list of methods your model responds to that you want synced with your backend, for example `zenbox_model :first_name, :last_name, :paying_customer?, :current_plan, :widgets_bought, :created_at` -Then from your project's RAILS_ROOT, and in your development environment, run: +That's it! If you have additional models, that will also work fine, all the data will be merged, with the latest values replacing previous ones. - rake gems:install - rake gems:unpack GEM=zenbox - script/generate zenbox --api-key your_key_here +You can sync all your data in one-go with the `zenbox:sync` rake task: -As always, if you choose not to vendor the zenbox gem, make sure -every server you deploy to has the gem installed or your application won't start. + rake zenbox:sync -The generator creates a file under `config/initializers/zenbox.rb` configuring Zenbox with your API key. This file should be checked into your version control system so that it is deployed to your staging and production environments. - -### Upgrading From Earlier Versions of Zenbox - -If you're currently using the plugin version (if you have a -vendor/plugins/hoptoad_notifier directory, you are), you'll need to perform a -few extra steps when upgrading to the gem version. - -Add the zenbox gem to your app. In config/environment.rb: - - config.gem 'zenbox' - -Remove the plugin: - - rm -rf vendor/plugins/hoptoad_notifier - -Make sure the following line DOES NOT appear in your ApplicationController file: - - include HoptoadNotifier::Catcher - -If it does, remove it. The new catcher is automatically included by the gem -version of Zenbox. - -Before running the zenbox generator, you need to find your project's API key. -Log in to your account at zenbox.io, and click on the "Projects" button. -Then, find your project in the list, and click on its name. In the left-hand -column, you'll see an "Edit this project" button. Click on that to get your -project's API key. If you accidentally use your personal API api_key, -you will get API key not found errors, and exceptions will not be stored -by the Zenbox service. - -Then from your project's RAILS_ROOT, run: - - rake gems:install - script/generate zenbox --api-key your_key_here - -Once installed, you should vendor the zenbox gem. - - rake gems:unpack GEM=zenbox - -As always, if you choose not to vendor the zenbox gem, make sure -every server you deploy to has the gem installed or your application won't -start. - -### Upgrading from Earlier Versions of the Hoptoad Gem (with config.gem) - -If you're currently using the gem version of the hoptoad_notifier and have -a version of Rails that uses config.gem (in the 2.x series), there is -a step or two that you need to do to upgrade. First, you need to remove -the old version of the gem from vendor/gems: - - rm -rf vendor/gems/hoptoad_notifier-X.X.X - -Then you must remove the hoptoad_notifier_tasks.rake file from lib: - - rm lib/tasks/hoptoad_notifier_tasks.rake - -You can then continue to install normally. If you don't remove the rake file, -you will be unable to unpack this gem (Rails will think it's part of the -framework). - - - -You can test that Zenbox is working in your production environment by using -this rake task (from RAILS_ROOT): - - rake zenbox:test - -If everything is configured properly, that task will send a notice to Zenbox -which will be visible immediately. - -### Removing hoptoad_notifier - -in your ApplicationController, REMOVE this line: - - include HoptoadNotifiable - -In your config/environment* files, remove all references to HoptoadNotifier - -Remove the vendor/plugins/hoptoad_notifier directory. - -### Remove hoptoad_notifier plugin - -Remove the vendor/plugins/hoptoad_notifier directory before installing the gem, or run: - - script/plugin remove hoptoad_notifier - -Non-rails apps using Bundler ----------------------------- -There is an undocumented dependency in `activesupport` where the `i18n` gem is -required only if the core classes extensions are used (`active_support/core_ext`). -This can lead to a confusing `LoadError` exception when using Zenbox. Until -this is fixed in `activesupport` the workaround is to add `i18n` to the Gemfile -for your Sinatra/Rack/pure ruby application: - - gem 'i18n' - gem 'zenbox' - -Rack ----- - -In order to use zenbox in a non-Rails rack app, just load -zenbox, configure your API key, and use the Zenbox::Rack -middleware: - - require 'rack' - require 'zenbox' - - Zenbox.configure do |config| - config.api_key = 'my_api_key' - end - - app = Rack::Builder.app do - run lambda { |env| raise "Rack down" } - end - - use Zenbox::Rack - run app - -Sinatra -------- - -Using zenbox in a Sinatra app is just like a Rack app: - - require 'sinatra' - require 'zenbox' - - Zenbox.configure do |config| - config.api_key = 'my API key' - end - - use Zenbox::Rack - - get '/' do - raise "Sinatra has left the building" - end - -Usage ------ - -For the most part, Zenbox works for itself. - -It intercepts the exception middleware calls, sends notifications and continues the middleware call chain. - -If you want to log arbitrary things which you've rescued yourself from a -controller, you can do something like this: - - ... - rescue => ex - notify_zenbox(ex) - flash[:failure] = 'Encryptions could not be rerouted, try again.' - end - ... - -The `#notify_zenbox` call will send the notice over to Zenbox for later -analysis. While in your controllers you use the `notify_zenbox` method, anywhere -else in your code, use `Zenbox.notify`. - -To perform custom error processing after Zenbox has been notified, define the -instance method `#rescue_action_in_public_without_zenbox(exception)` in your -controller. - -Informing the User +Ruby Installation ------------------ +After adding the `zenbox` gem to your Gemfile, you can simple use: `Zenbox.post(email, profile_data)`, where `profile_data` is a hash. That's it! -The zenbox gem is capable of telling the user information about the error that just happened -via the user_information option. They can give this error number in bug reports, for example. -By default, if your 500.html contains the text +HTTP API +-------- +You can also simply post to the endpoint using any http library from any language your prefer. Here's and example: - <!-- AIRBRAKE ERROR --> +`curl -X POST 'http://zenboxapp.com/customers?api_key=<your_api_key&email=support@zenboxapp.com&title=Support People&widgets_consumed=4000'` -then that comment will be replaced with the text "Zenbox Error [errnum]". You can modify the text -of the informer by setting `config.user_information`. Zenbox will replace "{{ error_id }}" with the -ID of the error that is returned from Zenbox. +Now go check out your email from support@zenboxapp.com. If you've installed the Zenbox extension, you should see your custom fields rendered alongside! - Zenbox.configure do |config| - ... - config.user_information = "<p>Tell the devs that it was <strong>{{ error_id }}</strong>'s fault.</p>" - end - -You can also turn the middleware that handles this completely off by setting `config.user_information` to false. - -Note that this feature is reading the error id from `env['zenbox.error_id']`. When the exception is caught -automatically in a controller, Zenbox sets that value. If you're, however, calling the Zenbox methods like -`Zenbox#notify` or `Zenbox#notify_or_ignore`, please make sure you set that value. So the proper way of calling the -"manual" methods would be `env['zenbox.error_id'] = Zenbox.notify_or_ignore(...)`. - -Tracking deployments in Zenbox --------------------------------- - -Paying Zenbox plans support the ability to track deployments of your application in Zenbox. -By notifying Zenbox of your application deployments, all errors are resolved when a deploy occurs, -so that you'll be notified again about any errors that reoccur after a deployment. - -Additionally, it's possible to review the errors in Zenbox that occurred before and after a deploy. - -When Zenbox is installed as a gem, you need to add - - require 'zenbox/capistrano' - -to your deploy.rb - -If you don't use Capistrano, then you can use the following rake task from your -deployment process to notify Zenbox: - - rake zenbox:deploy TO=#{rails_env} REVISION=#{current_revision} REPO=#{repository} USER=#{local_user} - -Going beyond exceptions ------------------------ - -You can also pass a hash to `Zenbox.notify` method and store whatever you want, -not just an exception. And you can also use it anywhere, not just in -controllers: - - begin - params = { - # params that you pass to a method that can throw an exception - } - my_unpredicable_method(params) - rescue => e - Zenbox.notify( - :error_class => "Special Error", - :error_message => "Special Error: #{e.message}", - :parameters => params - ) - end - -While in your controllers you use the `notify_zenbox` method, anywhere else in -your code, use `Zenbox.notify`. Zenbox will get all the information -about the error itself. As for a hash, these are the keys you should pass: - -* `:error_class` - Use this to group similar errors together. When Zenbox catches an exception it sends the class name of that exception object. -* `:error_message` - This is the title of the error you see in the errors list. For exceptions it is "#{exception.class.name}: #{exception.message}" -* `:parameters` - While there are several ways to send additional data to Zenbox, passing a Hash as :parameters as in the example above is the most common use case. When Zenbox catches an exception in a controller, the actual HTTP client request parameters are sent using this key. - -Zenbox merges the hash you pass with these default options: - - { - :api_key => Zenbox.api_key, - :error_message => 'Notification', - :backtrace => caller, - :parameters => {}, - :session => {} - } - -You can override any of those parameters. - -### Sending shell environment variables when "Going beyond exceptions" - -One common request we see is to send shell environment variables along with -manual exception notification. We recommend sending them along with CGI data -or Rack environment (:cgi_data or :rack_env keys, respectively.) - -See Zenbox::Notice#initialize in lib/zenbox/notice.rb for -more details. - -Filtering ---------- - -You can specify a whitelist of errors that Zenbox will not report on. Use -this feature when you are so apathetic to certain errors that you don't want -them even logged. - -This filter will only be applied to automatic notifications, not manual -notifications (when #notify is called directly). - -Zenbox ignores the following exceptions by default: - - ActiveRecord::RecordNotFound - ActionController::RoutingError - ActionController::InvalidAuthenticityToken - CGI::Session::CookieStore::TamperedWithCookie - ActionController::UnknownAction - AbstractController::ActionNotFound - Mongoid::Errors::DocumentNotFound - - -To ignore errors in addition to those, specify their names in your Zenbox -configuration block. - - Zenbox.configure do |config| - config.api_key = '1234567890abcdef' - config.ignore << "ActiveRecord::IgnoreThisError" - end - -To ignore *only* certain errors (and override the defaults), use the #ignore_only attribute. - - Zenbox.configure do |config| - config.api_key = '1234567890abcdef' - config.ignore_only = ["ActiveRecord::IgnoreThisError"] # or [] to ignore no exceptions. - end - -To ignore certain user agents, add in the #ignore_user_agent attribute as a -string or regexp: - - Zenbox.configure do |config| - config.api_key = '1234567890abcdef' - config.ignore_user_agent << /Ignored/ - config.ignore_user_agent << 'IgnoredUserAgent' - end - -To ignore exceptions based on other conditions, use #ignore_by_filter: - - Zenbox.configure do |config| - config.api_key = '1234567890abcdef' - config.ignore_by_filter do |exception_data| - true if exception_data[:error_class] == "RuntimeError" - end - end - -To replace sensitive information sent to the Zenbox service with [FILTERED] use #params_filters: - - Zenbox.configure do |config| - config.api_key = '1234567890abcdef' - config.params_filters << "credit_card_number" - end - -Note that, when rescuing exceptions within an ActionController method, -zenbox will reuse filters specified by #filter_parameter_logging. - -Testing -------- - -When you run your tests, you might notice that the Zenbox service is recording -notices generated using #notify when you don't expect it to. You can -use code like this in your test_helper.rb or spec_helper.rb files to redefine -that method so those errors are not reported while running tests. - - module Zenbox - def self.notify(exception, opts = {}) - # do nothing. - end - end - -Proxy Support -------------- - -The notifier supports using a proxy, if your server is not able to directly reach the Zenbox servers. To configure the proxy settings, added the following information to your Zenbox configuration block. - - Zenbox.configure do |config| - config.proxy_host = proxy.host.com - config.proxy_port = 4038 - config.proxy_user = foo # optional - config.proxy_pass = bar # optional - -Supported Rails versions ------------------------- - -See SUPPORTED_RAILS_VERSIONS for a list of official supported versions of -Rails. - -Please open up a support ticket ( http://help.zenbox.io ) or submit a new github issue -if you're using a version of Rails that is listed above and the notifier is -not working properly. - -Javascript Notifer ------------------- - -To automatically include the Javascript node on every page, use this helper method from your layouts: - - <%= zenbox_javascript_notifier %> - -It's important to insert this very high in the markup, above all other javascript. Example: - - <!DOCTYPE html> - <html> - <head> - <meta charset="utf8"> - <%= zenbox_javascript_notifier %> - <!-- more javascript --> - </head> - <body> - ... - </body> - </html> - -This helper will automatically use the API key, host, and port specified in the configuration. - -The Javascript notifier tends to send much more notifications than the base Rails project. -If you want to receive them into a separate Zenbox project, specify its -API key in the `js_api_key` option. - - config.js_api_key = 'another-projects-api-key' - -To test the Javascript notifier in development environment, overwrite (temporarily) the development_environments option: - - Zenbox.configure do |config| - # ... - config.development_environments = [] - end - -Development ------------ - -See TESTING.md for instructions on how to run the tests. - Credits ------- -![thoughtbot](http://thoughtbot.com/images/tm/logo.png) +![Cloudfuji](http://zenbox.com/images/tm/logo.png) -Zenbox is maintained and funded by [zenbox.io](http://zenbox.io) - -Thank you to all [the contributors](https://github.com/zenbox/zenbox/contributors)! - -The names and logos for Zenbox, thoughtbot are trademarks of their respective holders. +The Zenbox gem was forked from [Airbrake](http://airbrake.io), which is a totally amazing company run by people you should support. License ------- Zenbox is Copyright © 2008-2012 Zenbox. It is free software, and may be redistributed under the terms specified in the MIT-LICENSE file.