alec-gem 2.7.2

data/docs/context.rst

@@ -0,0 +1,141 @@
+Context
+=======
+
+Additional context can be passed to the capture methods.  This allows you
+to record extra information that could help you identify the root cause of
+the issue or who the error happened for.
+
+.. sourcecode:: ruby
+
+    Raven.capture_message 'My Event!',
+      logger: 'logger',
+      extra: {
+        my_custom_variable: 'value'
+      },
+      tags: {
+        foo: 'bar'
+      }
+
+The following attributes are available:
+
+* ``logger``: the logger name to record this event under
+* ``level``: a string representing the level of this event (fatal, error,
+  warning, info, debug)
+* ``server_name``: the hostname of the server
+* ``tags``: a mapping of tags describing this event
+* ``extra``: a mapping of arbitrary context
+* ``user``: a mapping of user context
+* ``transaction``: An array of strings. The final element in the array represents the current transaction, e.g. "HelloController#hello_world" for a Rails controller.
+
+Providing Request Context
+-------------------------
+
+Most of the time you're not actually calling out to Raven directly, but
+you still want to provide some additional context. This lifecycle
+generally constists of something like the following:
+
+*   Set some context via a middleware (e.g. the logged in user)
+*   Send all given context with any events during the request lifecycle
+*   Cleanup context
+
+There are three primary methods for providing request context.
+
+User Context
+~~~~~~~~~~~~
+
+User context describes the current actor.
+
+.. sourcecode:: ruby
+
+    # bind the logged in user
+    Raven.user_context(
+      # a unique ID which represents this user
+      id: current_user.id, # 1
+
+      # the actor's email address, if available
+      email: current_user.email, # "example@example.org"
+
+      # the actor's username, if available
+      username: current_user.username, # "foo"
+
+      # the actor's IP address, if available
+      ip_address: request.ip # '127.0.0.1'
+    )
+
+When dealing with anonymous users you will still want to send basic user context to ensure Sentry can count them against the unique users:
+
+.. sourcecode:: ruby
+
+    Raven.user_context(
+      # the actor's IP address, if available
+      ip_address: request.ip # '127.0.0.1'
+    )
+
+Tags
+~~~~
+
+You can provide a set of key/value pairs called tags which Sentry will index and aggregate. This will help you understand the distribution of issues, as well as enabling easy lookup via search.
+
+.. sourcecode:: ruby
+
+    # tag the request with something interesting
+    Raven.tags_context(
+      language: I18n.locale, # "en-us"
+      timezone: current_user.time_zone # "PST"
+    )
+
+
+Additional Context
+~~~~~~~~~~~~~~~~~~
+
+In addition to the supported structured data of Sentry, you can provide additional context. This is a key/value mapping, where the values must be JSON compatible, but can be of a rich datatype.
+
+.. sourcecode:: ruby
+
+    # provide a bit of additional context
+    Raven.extra_context(
+      happiness: 'very',
+      emoji: ['much']
+    )
+
+Rack (HTTP) Context
+~~~~~~~~~~~~~~~~~~~
+
+Additionally, if you're using Rack (without the middleware), you can
+easily provide context with the ``rack_context`` helper:
+
+.. sourcecode:: ruby
+
+    Raven.rack_context(env)
+
+If you're using the Rack middleware, we've already taken care of cleanup
+for you, otherwise you'll need to ensure you perform it manually:
+
+.. sourcecode:: ruby
+
+    Raven::Context.clear!
+
+Note: the rack and user context will perform a set operation, whereas tags
+and extra context will merge with any existing request context.
+
+Transactions
+~~~~~~~~~~~~
+
+The "transaction" is intended to represent the action the event occurred during.
+In Rack, this will be the request URL. In Rails, it's the controller name and
+action ("HelloController#hello_world").
+
+Transactions are modeled as a stack. The top item in the stack (i.e. the last
+element of the array) will be used as the ``transaction`` for any events:
+
+.. sourcecode:: ruby
+
+    Raven.context.transaction.push "User Import"
+    # import some users
+    Raven.context.transaction.pop
+
+Transactions may also be overridden/set explicitly during event creation:
+
+.. sourcecode:: ruby
+
+    Raven.capture_exception(exception, transaction: "User Import")

data/docs/index.rst

@@ -0,0 +1,113 @@
+.. sentry:edition:: self
+
+    Raven Ruby
+    ==========
+
+.. sentry:edition:: hosted, on-premise
+
+    .. class:: platform-ruby
+
+    Ruby
+    ====
+
+Raven for Ruby is a client and integration layer for the Sentry error
+reporting API.  It supports Ruby 1.9.3 and 2.x.
+JRuby support is provided but experimental.
+
+Installation
+------------
+
+Raven Ruby comes as a gem and is straightforward to install.  If you are
+using Bundler just add this to your ``Gemfile``:
+
+.. sourcecode:: ruby
+
+    gem "sentry-raven"
+
+For other means of installation see :doc:`install`.
+
+Configuration
+-------------
+
+To use Raven Ruby all you need is your DSN.  Like most Sentry libraries it
+will honor the ``SENTRY_DSN`` environment variable.  You can find it on
+the project settings page under API Keys.  You can either export it as
+environment variable or manually configure it with ``Raven.configure``:
+
+.. sourcecode:: ruby
+
+    Raven.configure do |config|
+      config.dsn = '___DSN___'
+    end
+
+Reporting Failures
+------------------
+
+If you use Rails, Rake, Sidekiq, etc, you're already done - no more
+configuration required! Check :doc:`integrations/index` for more details on
+other gems Sentry integrates with automatically.
+
+Rack requires a little more setup: :doc:`integrations/rack`
+
+Otherwise, Raven supports two methods of capturing exceptions:
+
+.. sourcecode:: ruby
+
+    Raven.capture do
+      # capture any exceptions which happen during execution of this block
+      1 / 0
+    end
+
+    begin
+      1 / 0
+    rescue ZeroDivisionError => exception
+      Raven.capture_exception(exception)
+    end
+
+Additional Context
+------------------
+
+Much of the usefulness of Sentry comes from additional context data with
+the events.  Raven Ruby makes this very convenient by providing
+methods to set thread local context data that is then submitted
+automatically with all events.
+
+There are three primary methods for providing request context:
+
+.. sourcecode:: ruby
+
+    # bind the logged in user
+    Raven.user_context email: 'foo@example.com'
+
+    # tag the request with something interesting
+    Raven.tags_context interesting: 'yes'
+
+    # provide a bit of additional context
+    Raven.extra_context happiness: 'very'
+
+For more information see :doc:`context`.
+
+Deep Dive
+---------
+
+Want to know more?  We have a detailed documentation about all parts of
+the library and the client integrations.
+
+
+.. toctree::
+   :maxdepth: 2
+   :titlesonly:
+
+   install
+   config
+   usage
+
+   breadcrumbs
+   context
+   processors
+   integrations/index
+
+Resources:
+
+* `Bug Tracker <http://github.com/getsentry/raven-ruby/issues>`_
+* `Github Project <http://github.com/getsentry/raven-ruby>`_

data/docs/install.rst

@@ -0,0 +1,40 @@
+Installation
+============
+
+Raven Ruby comes as a gem and is straightforward to install.  If you are
+using Bundler just add this to your ``Gemfile``:
+
+.. sourcecode:: ruby
+
+    gem "sentry-raven"
+
+Development Version
+-------------------
+
+If you want to install the development version from github:
+
+.. sourcecode:: ruby
+
+    gem "sentry-raven", :github => "getsentry/raven-ruby"
+
+Without Integrations
+--------------------
+
+If you wish to activate integrations manually (or don't want them
+activated by default), require "raven/base" instead of "raven" or
+"sentry-raven".  In that case disable the requiring in the ``Gemfile``:
+
+.. sourcecode:: ruby
+
+    gem "sentry-raven", :require => false
+
+And in your initialization code:
+
+.. sourcecode:: ruby
+
+    require "raven/base"
+    require "raven/integrations/rails"
+    require "raven/integrations/delayed_job"
+
+This stops you from calling ``Raven.inject``, which is where all this
+integration loading occurs.

data/docs/integrations/heroku.rst

@@ -0,0 +1,11 @@
+Heroku
+======
+
+Installation
+------------
+
+Enable the ``runtime-dyno-metadata`` Heroku Labs feature in order to enable automated release detection:
+
+::
+
+   heroku labs:enable runtime-dyno-metadata -a myapp

data/docs/integrations/index.rst

@@ -0,0 +1,59 @@
+Integrations
+============
+
+For common environments and frameworks like Rails, Rake, Rack and others
+Ruby Raven provides automatic integration for reporting.  Most of the time
+you don't need to change anything, although you can configure those
+features if you want.
+
+.. toctree::
+   :maxdepth: 1
+
+   rails
+   rack
+   puma
+   heroku
+
+The following integrations are available:
+
+*   Sidekiq (``:sidekiq``)
+*   ``Delayed::Job`` (``:delayed_job``)
+*   Rake (``:rake``)
+*   Rack (``:rack``)
+*   Rails (``:railties``)
+
+
+Manually using integrations
+---------------------------
+
+Integrations are automatically loaded by default. This can be problematic if
+the default integration behavior doesn't suit your projects' needs.
+
+To explicitly include integrations:
+
+.. sourcecode:: ruby
+
+   require 'sentry-raven-without-integrations'
+   Raven.inject_only(:railties, :rack, :rake)
+
+
+To blacklist integrations:
+
+.. sourcecode:: ruby
+
+   require 'sentry-raven-without-integrations'
+   Raven.inject_without(:sidekiq, :delayed_job)
+
+
+If you're using bundler, then in your gemfile:
+
+.. sourcecode:: ruby
+
+   gem 'sentry-raven', require: 'sentry-raven-without-integrations'
+
+
+And in some sort of initializer:
+
+.. sourcecode:: ruby
+
+   Raven.inject_without(:sidekiq)

data/docs/integrations/puma.rst

@@ -0,0 +1,30 @@
+Puma
+====
+
+Installation
+------------
+
+Install the SDK via Rubygems by adding it to your ``Gemfile``:
+
+.. sourcecode:: ruby
+
+    gem "sentry-raven"
+
+Configuration
+-------------
+
+Puma provides a config option for handling low level errors.
+
+.. sourcecode:: ruby
+
+    # in your puma.rb config
+    lowlevel_error_handler do |ex, env|
+      Raven.capture_exception(
+        ex,
+        :message => ex.message,
+        :extra => { :puma => env },
+        :transaction => "Puma"
+      )
+      # note the below is just a Rack response
+      [500, {}, ["An error has occurred, and engineers have been informed. Please reload the page. If you continue to have problems, contact support@example.com\n"]]
+    end

data/docs/integrations/rack.rst

@@ -0,0 +1,27 @@
+Rack (Sinatra etc.)
+===================
+
+Installation
+------------
+
+Install the SDK via Rubygems by adding it to your ``Gemfile``:
+
+.. sourcecode:: ruby
+
+    gem "sentry-raven"
+
+Configuration
+-------------
+
+Add ``use Raven::Rack`` to your ``config.ru`` or other rackup file (this is
+automatically inserted in Rails):
+
+.. sourcecode:: ruby
+
+    require 'raven'
+
+    Raven.configure do |config|
+      config.dsn = '___DSN___'
+    end
+
+    use Raven::Rack

data/docs/integrations/rails.rst

@@ -0,0 +1,62 @@
+Ruby on Rails
+=============
+
+In Rails, all uncaught exceptions will be automatically reported. 
+
+We support Rails 4 and newer.
+
+Installation
+------------
+
+Install the SDK via Rubygems by adding it to your ``Gemfile``:
+
+.. sourcecode:: ruby
+
+    gem "sentry-raven"
+
+Configuration
+-------------
+
+Open up ``config/application.rb`` and configure the DSN, and any other :doc:`settings <../config>`
+you need:
+
+.. sourcecode:: ruby
+
+    Raven.configure do |config|
+      config.dsn = '___DSN___'
+    end
+
+If you have added items to `Rails' log filtering
+<http://guides.rubyonrails.org/action_controller_overview.html#parameters-filtering>`_,
+you can also make sure that those items are not sent to Sentry:
+
+.. sourcecode:: ruby
+
+    # in your application.rb:
+    config.filter_parameters << :password
+
+    # in an initializer, like sentry.rb
+    Raven.configure do |config|
+      config.sanitize_fields = Rails.application.config.filter_parameters.map(&:to_s)
+    end
+
+Params and sessions
+-------------------
+
+.. sourcecode:: ruby
+
+  class ApplicationController < ActionController::Base
+    before_action :set_raven_context
+
+    private
+
+    def set_raven_context
+      Raven.user_context(id: session[:current_user_id]) # or anything else in session
+      Raven.extra_context(params: params.to_unsafe_h, url: request.url)
+    end
+  end
+
+Caveats
+-------
+
+Currently, custom exception applications (`config.exceptions_app`) are not supported. If you are using a custom exception app, you must manually integrate Raven yourself.