Docs 1.x overhaul (#249)

* Integration example docs

* working on context stuff

* WIP

* Added config stuff on breadcrumbs, cleaned up index overview

* Update usage docs with all the things

* Address Ben's feedback

Author: LewisJEllis

docs/config.rst

@@ -1,17 +1,28 @@
 Configuration
 =============
 
-Configuration is passed as the second argument of the ``raven.Client`` constructor:
+To get started, you need to configure Raven to use your Sentry DSN:
 
-.. code-block:: javascript
+.. sourcecode:: javascript
 
-    var raven = require("raven");
+    var Raven = require('raven');
+    Raven.config('___PUBLIC_DSN___').install()
 
-    new raven.Client(String dsn[, Object options])
+At this point, Raven is ready to capture any uncaught exceptions.
 
 Optional settings
 -----------------
 
+``Raven.config()`` can optionally be passed an additional argument for extra configuration:
+
+.. sourcecode:: javascript
+
+    Raven.config('___PUBLIC_DSN___', {
+        release: '1.3.0'
+    }).install()
+
+Those configuration options are documented below:
+
 .. describe:: logger
 
     The name of the logger used by Sentry. Default: ``''``
@@ -81,6 +92,47 @@ Optional settings
             }
         }
 
+.. describe:: shouldSendCallback
+
+    A callback function that allows you to apply your own filters to determine if the event should be sent to Sentry.
+
+    .. code-block:: javascript
+
+        {
+            shouldSendCallback: function (data) {
+                // randomly omit half of events
+                return Math.random() > 0.5;
+            }
+        }
+
+.. describe:: autoBreadcrumbs
+
+  Enables/disables automatic collection of breadcrumbs. Possible values are:
+
+  * `false` - all automatic breadcrumb collection disabled (default)
+  * `true` - all automatic breadcrumb collection enabled
+  * A dictionary of individual breadcrumb types that can be enabled/disabled:
+
+  .. code-block:: javascript
+
+      autoBreadcrumbs: {
+          'console': false,  // console logging
+          'http': true,     // http and https requests
+          'postgres': true,  // postgresql queries from pg module
+      }
+
+.. describe:: maxBreadcrumbs
+
+  Raven captures up to 30 breadcrumb entries by default. You can increase this to
+  be as high as 100, or reduce it if you find 30 is too noisy, by setting `maxBreadcrumbs`.
+
+  Note that in very high-concurrency situations where you might have a large number of
+  long-lived contexts each with a large number of associated breadcrumbs, there is potential
+  for significant memory usage. 10,000 contexts with 10kB of breadcrumb data each will use
+  around 120mB of memory. Most applications will be nowhere close to either of these numbers,
+  but if yours might be, you can use the `maxBreadcrumbs` parameter to limit the amount of
+  breadcrumb data each context will keep around.
+
 .. describe:: transport
 
     Override the default HTTP data transport handler.

docs/index.rst

@@ -10,7 +10,7 @@
     Node.js
     =======
 
-raven-node is a Sentry's officially supported Node.js SDK.
+raven-node is the official Node.js client for Sentry.
 
 **Note**: If you're using JavaScript in the browser, you'll need
 `raven-js <https://github.com/getsentry/raven-js>`_.
@@ -32,55 +32,91 @@ Next you need to initialize the Raven client and configure it to use your `Sentr
 
 .. code-block:: javascript
 
-    var raven = require('raven');
-    var client = new raven.Client('___DSN___');
+    var Raven = require('raven');
+    Raven.config('___DSN___').install();
 
-You can optionally pass an object of configuration options as the 2nd argument to `Client`. For
+At this point, Raven is set up to capture and report any uncaught exceptions.
+
+You can optionally pass an object of configuration options as the 2nd argument to `Raven.config`. For
 more information, see :doc:`config`.
 
 Reporting Errors
 ----------------
 
-To get started passing errors to Raven, it is recommended to initialize Raven's global error handler using
-``patchGlobal``. This will cause any uncaught exception which would bubble up to the Node runtime to be
-captured and processed by Raven.
+Raven's ``install`` method sets up a global handler to automatically capture any uncaught exceptions. You can also report errors manually with ``try...catch`` and
+a call to ``captureException``:
 
 .. code-block:: javascript
 
-  client.patchGlobal();
+    try {
+        doSomething(a[0]);
+    } catch (e) {
+        Raven.captureException(e);
+    }
 
-Additionally, you can manually capture and report potentially problematic code with ``try...catch`` and
- ``captureException``:
+You can also use ``wrap`` and ``context`` to have Raven wrap a function and automatically capture any exceptions it throws:
 
 .. code-block:: javascript
 
-    try {
-        doSomething(a[0])
-    } catch(e) {
-        client.captureException(e)
-    }
+  Raven.context(function () {
+    doSomething(a[0]);
+  });
 
-The ``captureException`` method optionally takes an object of configuration options as the 2nd argument. For more information, and to learn about other methods provided by the Raven API, see :doc:`usage`.
+For more information on reporting errors, see :doc:`usage`.
 
 Adding Context
 --------------
 
-While a user is logged in, you can tell Sentry to associate errors with
-user data.  This data is then submitted with each error which allows you
-to figure out which users are affected.
+Code run via ``wrap`` or ``context`` has an associated set of context data, and Raven provides methods for managing that data.
+
+You'll most commonly use this to associate the current user with an exception:
 
 .. code-block:: javascript
 
-    client.setUserContext({
+  Raven.context(function () {
+    Raven.setContext({
+      user: {
         email: '[email protected]',
         id: '123'
-    })
+      }
+    });
+    // errors thrown here will be associated with matt
+  });
+  // errors thrown here will not be associated with matt
+
+This can also be used to set ``tags`` and ``extra`` keys for associated tags and extra data.
+
+You can update the context data with ``mergeContext`` or retrieve it with ``getContext``. When an exception is captured by a wrapper, the current context state will be passed as options to ``captureException``.
+
+See :ref:`raven-node-additional-context` for more.
+
+Breadcrumbs
+-----------
+
+Breadcrumbs are records of server and application lifecycle events that can be helpful in understanding the state of the application leading up to a crash.
+
+We can capture breadcrumbs and associate them with a context, and then send them along with any errors captured from that context:
+
+.. code-block:: javascript
+
+  Raven.context(function () {
+    Raven.captureBreadcrumb({
+      message: 'Received payment confirmation',
+      category: 'payment',
+      data: {
+         amount: 312,
+      }
+    });
+    // errors thrown here will have breadcrumb attached
+  });
+
+Raven can be configured to automatically capture breadcrubs for certain events including:
 
-If at any point, the user becomes unauthenticated, you can call
-``client.setUserContext()`` with no arguments to remove their data.
+  * http/https requests
+  * console log statements
+  * postgres queries
 
-Other similar methods are ``client.setExtraContext`` and
-``client.setTagsContext``.  See :ref:`raven-node-additional-context` for more info.
+For more information, see :ref:`raven-recording-breadcrumbs`.
 
 Middleware and Integrations
 ---------------------------
@@ -91,7 +127,7 @@ to configure one of Raven's server middleware integrations. See doc:`integration
 Deep Dive
 ---------
 
-For more detailed information about how to get most out of Raven.js there
+For more detailed information about how to get most out of Raven there
 is additional documentation available that covers all the rest:
 
 .. toctree::

docs/integrations/connect.rst

@@ -4,7 +4,10 @@ Connect
 .. code-block:: javascript
 
   var connect = require('connect');
-  var raven = require('raven');
+  var Raven = require('raven');
+
+  // Must configure Raven before doing anything else with it
+  Raven.config('___DSN___').install();
 
   function mainHandler(req, res) {
       throw new Error('Broke!');
@@ -14,19 +17,19 @@ Connect
       // The error id is attached to `res.sentry` to be returned
       // and optionally displayed to the user for support.
       res.statusCode = 500;
-      res.end(res.sentry+'\n');
+      res.end(res.sentry + '\n');
   }
 
   connect(
       // The request handler be the first item
-      raven.middleware.connect.requestHandler('___DSN___'),
+      Raven.requestHandler(),
 
       connect.bodyParser(),
       connect.cookieParser(),
       mainHandler,
 
       // The error handler must be before any other error middleware
-      raven.middleware.connect.errorHandler('___DSN___'),
+      Raven.errorHandler(),
 
       // Optional fallthrough error handler
       onError,

docs/integrations/express.rst

@@ -4,26 +4,27 @@ Express
 .. code-block:: javascript
 
     var app = require('express')();
-    var raven = require('raven');
+    var Raven = require('raven');
 
-    function onError(err, req, res, next) {
-        // The error id is attached to `res.sentry` to be returned
-        // and optionally displayed to the user for support.
-        res.statusCode = 500;
-        res.end(res.sentry+'\n');
-    }
+    // Must configure Raven before doing anything else with it
+    Raven.config('__DSN__').install();
 
-    // The request handler must be the first item
-    app.use(raven.middleware.express.requestHandler('___DSN___'));
+    // The request handler must be the first middleware on the app
+    app.use(Raven.requestHandler());
 
     app.get('/', function mainHandler(req, res) {
         throw new Error('Broke!');
     });
 
     // The error handler must be before any other error middleware
-    app.use(raven.middleware.express.errorHandler('___DSN___'));
+    app.use(Raven.errorHandler());
 
     // Optional fallthrough error handler
-    app.use(onError);
+    app.use(function onError(err, req, res, next) {
+        // The error id is attached to `res.sentry` to be returned
+        // and optionally displayed to the user for support.
+        res.statusCode = 500;
+        res.end(res.sentry + '\n');
+    });
 
     app.listen(3000);

docs/integrations/koa.rst

@@ -4,13 +4,15 @@ Koa
 .. code-block:: javascript
 
     var koa = require('koa');
-    var raven = require('raven');
+    var Raven = require('raven');
 
     var app = koa();
-    var sentry = new raven.Client('___DSN___');
+    Raven.config('___DSN___').install();
 
-    app.on('error', function(err) {
-        sentry.captureException(err);
+    app.on('error', function (err) {
+        sentry.captureException(err, function (err, eventId) {
+            console.log('Reported error ' + eventId);
+        });
     });
 
     app.listen(3000);