Skip to content
This repository has been archived by the owner on Oct 23, 2023. It is now read-only.

Commit

Permalink
Initial doc commit
Browse files Browse the repository at this point in the history
  • Loading branch information
@dcramer
dcramer committed Sep 1, 2015
1 parent fd99c57 commit 4b52da6
Show file tree
Hide file tree
Showing 16 changed files with 1,029 additions and 245 deletions.
3 changes: 3 additions & 0 deletions .gitignore
View file
Expand Up @@ -11,6 +11,9 @@ pids
logs
results

docs/_build
docs/doctrees

node_modules
npm-debug.log

Expand Down
3 changes: 3 additions & 0 deletions .gitmodules
View file
@@ -0,0 +1,3 @@
[submodule "docs/_sentryext"]
path = docs/_sentryext
url = https://github.com/getsentry/sentry-doc-support
20 changes: 20 additions & 0 deletions Makefile
View file
@@ -0,0 +1,20 @@
develop: update-submodules
npm install .

update-submodules:
git submodule init
git submodule update

docs:
cd docs; $(MAKE) html

docs-live:
while true; do \
sleep 2; \
$(MAKE) docs; \
done

clean:
rm -rf docs/html

.PHONY: develop update-submodules docs docs-live clean
251 changes: 6 additions & 245 deletions README.md
View file
@@ -1,248 +1,9 @@
# Raven [![Build Status](https://secure.travis-ci.org/getsentry/raven-node.png?branch=master)](http://travis-ci.org/getsentry/raven-node)
**Node v0.12/iojs compatible**
# raven-node [![Build Status](https://travis-ci.org/getsentry/raven-node.svg?branch=master)](https://travis-ci.org/getsentry/raven-node)

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/).
raven-node is a Node.js client for [Sentry](https://www.getsentry.com/).

All processing and sending happens asynchronously to not slow things down if/when Sentry is down or slow.
## Resources

## Compatibility
* 0.8.x
* 0.10.x
* 0.12.x
* iojs

Raven 0.7+ requires Sentry 6.4+

## Installation
```
$ npm install raven
```

## Methods
```javascript
new raven.Client(String dsn[, Object options])
client.captureMessage(String message[[, Object options], Function callback])
client.captureError(Error error[[, Object options], Function callback])
client.captureQuery(String query[[, String type], Function callback])
```

## Basic Usage
```javascript
var raven = require('raven');
var client = new raven.Client('{{ SENTRY_DSN }}');

client.captureMessage('Hello, world!');
```
You can specify a level in the second optional parameter. Default level is `error`


**Sentry is aware of five different levels:**
* debug (the least serious)
* info
* warning
* error
* fatal (the most serious)

```javascript
var raven = require('raven');
var client = new raven.Client('{{ SENTRY_DSN }}', {level: 'warning'});

client.captureMessage('Another message')
```

**Passing extra HTTP transport options**
```javascript
var raven = require('raven');
var client = new raven.Client('{{ SENTRY_DSN }}', {transport: new raven.transports.HTTPSTransport({rejectUnauthorized: false})});
```

**Adding extra info to an event**
```javascript
var raven = require('raven');

var client = new raven.Client('{{ SENTRY_DSN }}');

client.captureMessage("Another message", {extra: {'key': 'value'}})
```

**Adding tags to an event**
```javascript
var raven = require('raven');

var client = new raven.Client('{{ SENTRY_DSN }}');

client.captureMessage("Another message", {tags: {'key': 'value'}})
```

## Logging an error
```javascript
client.captureError(new Error('Broke!'));
```

## Logging a query
```javascript
client.captureQuery('SELECT * FROM `awesome`', 'mysql');
```

## Sentry Identifier
```javascript
client.captureMessage('Hello, world!', function(result) {
console.log(client.getIdent(result));
});
```

```javascript
client.captureError(new Error('Broke!'), function(result) {
console.log(client.getIdent(result));
});
```

__Note__: `client.captureMessage` will also return the result directly without the need for a callback, such as: `var result = client.captureMessage('Hello, world!');`

## Events
If you really care if the event was logged or errored out, Client emits two events, `logged` and `error`:

```javascript
client.on('logged', function(){
console.log('Yay, it worked!');
});
client.on('error', function(e){
console.log('oh well, Sentry is broke.');
})
client.captureMessage('Boom');
```

### Error Event
The event error is augmented with the original Sentry response object as well as the response body and statusCode for easier debugging.

```javascript
client.on('error', function(e){
console.log(e.reason); // raw response body, usually contains a message explaining the failure
console.log(e.statusCode); // status code of the http request
console.log(e.response); // entire raw http response object
});
```

## Environment variables
### SENTRY_DSN
Optionally declare the DSN to use for the client through the environment. Initializing the client in your app won't require setting the DSN.

### SENTRY_NAME
Optionally set the name for the client to use. [What is name?](http://raven.readthedocs.org/en/latest/config/index.html#name)

### SENTRY_RELEASE
Optionally set the application release version for the client to use, this is usually a Git SHA hash.

## Catching global errors
For those times when you don't catch all errors in your application. ;)

```javascript
client.patchGlobal();
// or
raven.patchGlobal(client);
// or
raven.patchGlobal('{{ SENTRY_DSN }}');
```

It is recommended that you don't leave the process running after receiving an `uncaughtException` (http://nodejs.org/api/process.html#process_event_uncaughtexception), so an optional callback is provided to allow you to hook in something like:

```javascript
client.patchGlobal(function() {
console.log('Bye, bye, world.');
process.exit(1);
});
```

The callback is called **after** the event has been sent to the Sentry server.

## Integrations
### Connect/Express middleware
The Raven middleware can be used as-is with either Connect or Express in the same way.

#### Connect and Express
```javascript
var connect = require('connect');
function mainHandler(req, res) {
throw new Error('Broke!');
}
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');
}
connect(
// Should be the first item listed
raven.middleware.connect.requestHandler('{{ SENTRY_DSN }}'),

connect.bodyParser(),
connect.cookieParser(),
mainHandler,

// Should come before any other error middleware
raven.middleware.connect.errorHandler('{{ SENTRY_DSN }}'),
onError, // optional error handler if you want to display the error id to a user
).listen(3000);
```

#### Express
```javascript
var app = require('express')();

app.get('/', function mainHandler(req, res) {
throw new Error('Broke!');
});

// Should be the first item listed
app.use(raven.middleware.express.requestHandler('{{ SENTRY_DSN }}'));

// Should come before any other error middleware
app.use(raven.middleware.express.errorHandler('{{ SENTRY_DSN }}'));
app.use(onError); // optional error handler if you want to display the error id to a user

app.listen(3000);
```

__Note__: `raven.middleware.express` or `raven.middleware.connect` *must* be added to the middleware stack *before* any other error handling middlewares or there's a chance that the error will never get to Sentry.

## Coffeescript
In order to use raven-node with coffee-script or another library which overwrites
Error.prepareStackTrace you might run into the exception "Traceback does not support Error.prepareStackTrace being defined already."

In order to not have raven-node (and the underlying raw-stacktrace library) require
Traceback you can pass your own stackFunction in the options. For example:

```coffeescript
client = new raven.Client('{{ SENTRY_DSN }}', { stackFunction: {{ Your stack function }}});
```

So for example:
```coffeescript
client = new raven.Client('{{ SENTRY_DSN }}', {
stackFunction: Error.prepareStackTrace
});
```

## Pre-processing data
Pass the `dataCallback` configuration value:

```javascript
client = new raven.Client('{{ SENTRY_DSN }}', {
dataCallback: function(data) {
delete data.request.env;
return data;
}
});
```

## Disable Raven
Pass `false` as the DSN (or any falsey value).

```javascript
client = new raven.Client(process.env.NODE_ENV === 'production' && '{{ SENTRY_DSN }}')
```

__Note__: We don't infer this from `NODE_ENV` automatically anymore. It's up to you to implement whatever logic you'd like.

## Support
You can find me on IRC. I troll in `#sentry` on `freenode`.
* [Documentation](https://docs.getsentry.com/hosted/clients/node/)
* [Bug Tracker](https://github.com/getsentry/raven-node/issues)
* [IRC](irc://chat.freenode.net/sentry) (chat.freenode.net, #sentry)

0 comments on commit 4b52da6

Please sign in to comment.