Skip to content
This repository

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 122 lines (100 sloc) 3.721 kb
9c4c4972 »
2012-03-17 Travis CI build status badge
1 # Raven [![Build Status](https://secure.travis-ci.org/mattrobenolt/raven-node.png?branch=master)](http://travis-ci.org/mattrobenolt/raven-node)
b3323330 »
2012-03-17 Adding docs.
2 Log errors and stack traces in [Sentry](http://getsentry.com/) from within your Node.js applications. Includes middleware support for [Connect](http://www.senchalabs.org/connect/)/[Express](http://expressjs.com/).
3
4 All processing and sending happens asynchronously to not slow things down if/when Sentry is down or slow.
5
6 ## Installation
7 ```
8 $ npm install raven
9 ```
10
11 ## Basic Usage
12 ```javascript
13 var raven = require('raven');
14 var client = new raven.Client('{{ SENTRY_DSN }}');
15
a18fe17e »
2012-03-18 Removed the weird Pythonic aliases and updated to the newer "capture*…
16 client.captureMessage('Hello, world!');
b3323330 »
2012-03-17 Adding docs.
17 ```
18
dca508c8 »
2012-03-18 Adding environment variable support, docs, and tests
19 Run with:
20 ```
21 $ NODE_ENV=production node script.js
22 ```
23
b3323330 »
2012-03-17 Adding docs.
24 ## Logging an error
25 ```javascript
a18fe17e »
2012-03-18 Removed the weird Pythonic aliases and updated to the newer "capture*…
26 client.captureError(new Error('Broke!'));
b3323330 »
2012-03-17 Adding docs.
27 ```
28
58c14b0b »
2012-03-18 Added docs for createFromQuery
29 ## Logging a query
30 ```javascript
a18fe17e »
2012-03-18 Removed the weird Pythonic aliases and updated to the newer "capture*…
31 client.captureQuery('SELECT * FROM `awesome`', 'mysql');
58c14b0b »
2012-03-18 Added docs for createFromQuery
32 ```
33
b3323330 »
2012-03-17 Adding docs.
34 ## Sentry Identifier
35 ```javascript
a18fe17e »
2012-03-18 Removed the weird Pythonic aliases and updated to the newer "capture*…
36 client.captureMessage('Hello, world!', function(result) {
b3323330 »
2012-03-17 Adding docs.
37 console.log(client.getIdent(result));
38 });
39 ```
40
41 ```javascript
a18fe17e »
2012-03-18 Removed the weird Pythonic aliases and updated to the newer "capture*…
42 client.captureError(new Error('Broke!'), function(result) {
b3323330 »
2012-03-17 Adding docs.
43 console.log(client.getIdent(result));
44 });
45 ```
46
a18fe17e »
2012-03-18 Removed the weird Pythonic aliases and updated to the newer "capture*…
47 __Note__: `client.captureMessage` will also return the result directly without the need for a callback, such as: `var result = client.captureMessage('Hello, world!');`
b3323330 »
2012-03-17 Adding docs.
48
dca508c8 »
2012-03-18 Adding environment variable support, docs, and tests
49 ## Environment variables
50 ### NODE_ENV
51 `NODE_ENV` must be set to `production` for Sentry to actually work. Without being in production, a warning is issued and logging disabled.
52
53 ### SENTRY_DSN
54 Optionally declare the DSN to use for the client through the environment. Initializing the client in your app won't require setting the DSN.
55
56 ### SENTRY_NAME
57 Optionally set the name for the client to use. [What is name?](http://raven.readthedocs.org/en/latest/config/index.html#name)
58
59 ### SENTRY_SITE
60 Optionally set the site for the client to use. [What is site?](http://raven.readthedocs.org/en/latest/config/index.html#site)
61
b3323330 »
2012-03-17 Adding docs.
62 ## Catching global errors
63 For those times when you don't catch all errors in your application. ;)
64
65 ```javascript
6e0191e1 »
2012-03-18 patchGlobal, not patchGlobals
66 client.patchGlobal();
b3323330 »
2012-03-17 Adding docs.
67 // or
6e0191e1 »
2012-03-18 patchGlobal, not patchGlobals
68 raven.patchGlobal(client);
b3323330 »
2012-03-17 Adding docs.
69 // or
6e0191e1 »
2012-03-18 patchGlobal, not patchGlobals
70 raven.patchGlobal('{{ SENTRY_DSN }}');
b3323330 »
2012-03-17 Adding docs.
71 ```
72
73 ## Methods
74 ```javascript
75 new raven.Client(dsn[, options])
a18fe17e »
2012-03-18 Removed the weird Pythonic aliases and updated to the newer "capture*…
76 client.captureMessage(string[,callback])
77 client.captureError(Error[,callback])
78 client.captureQuery(string, string[,callback])
b3323330 »
2012-03-17 Adding docs.
79 ```
80
81 ## Integrations
82 ### Connect/Express middleware
83 The Raven middleware can be used as-is with either Connect or Express in the same way. Take note that in your middlewares, Raven must appear _after_ your main handler to pick up any errors that may result from handling a request.
84
85 #### Connect
86 ```javascript
87 var connect = require('connect');
88 function mainHandler(req, res) {
89 throw new Error('Broke!');
90 }
91 function onError(err, req, res, next) {
92 // The error id is attached to `res.sentry` to be returned
93 // and optionally displayed to the user for support.
94 res.statusCode = 500;
95 res.end(res.sentry+'\n');
96 }
97 connect(
98 connect.bodyParser(),
99 connect.cookieParser(),
100 mainHandler,
101 raven.middleware.connect('{{ SENTRY_DSN }}'),
102 onError, // optional error handler if you want to display the error id to a user
103 ).listen(3000);
104 ```
105
106 #### Express
107 ```javascript
108 var app = require('express').createServer();
109 app.error(raven.middleware.express('{{ SENTRY_DSN }}'));
110 app.error(onError); // optional error handler if you want to display the error id to a user
111 app.get('/', function mainHandler(req, res) {
112 throw new Error('Broke!');
113 });
114 app.listen(3000);
115 ```
116
117 ## Todo
118 * More complete test coverage
119 * More comments in code
120 * More third party integration
8485039a »
2012-03-22 Update README.md
121 * Client should extend EventEmitter and emit events when logs are sent instead of being 100% blind
Something went wrong with that request. Please try again.