https://github.com/clever/sentry-node
simple node wrapper around the Sentry API
https://github.com/clever/sentry-node
Last synced: over 1 year ago
JSON representation
simple node wrapper around the Sentry API
- Host: GitHub
- URL: https://github.com/clever/sentry-node
- Owner: Clever
- License: apache-2.0
- Created: 2013-11-22T01:35:19.000Z (over 12 years ago)
- Default Branch: master
- Last Pushed: 2024-09-23T15:44:42.000Z (almost 2 years ago)
- Last Synced: 2025-03-17T16:53:18.569Z (over 1 year ago)
- Language: CoffeeScript
- Size: 91.8 KB
- Stars: 6
- Watchers: 65
- Forks: 2
- Open Issues: 3
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
## Sentry-node
**Node v10 compatible**
[](https://travis-ci.org/Clever/sentry-node)
A simple Node wrapper around the [Sentry](http://getsentry.com/) API.
## Installation
```
$ npm install sentry-node
```
## Testing
```
$ npm test
```
## Usage
### Creating the Client
```javascript
var Sentry = require('sentry-node');
```
You can initialize `sentry-node` by passing in a Sentry DSN:
```javascript
var sentry = new Sentry('');
```
You can also pass in the individual parameters that make up the DSN as an object:
```javascript
var sentry = new Sentry({
key: '',
secret: '',
project_id: ''
});
```
**Note:** If the DSN passed to `Sentry` is invalid, the client will be disabled. You will still be able to call its methods, but no data will be sent to Sentry. This can be useful behavior for testing and development environments, where you may not want to be logging errors to Sentry.
### Error
```javascript
sentry.error(err, logger, culprit, extra);
```
#### sample
```javascript
sentry.error(
new Error("The error method expected an Error instance as first argument."),
'/sentry-node.coffee',
"Bad arguments to sentry-node:error method",
{
note: "to test sentry-node error method",
version: "0.1.0"
}
);
```
#### arguments
* **err:** the error object to log, must be an instance of `Error`. `err.message` will be used for the smaller text that appears right under `culprit`
* **logger:** the place where the error was detected
* **culprit:** the location of the code that caused the error. If not known, should be `null`. If included, is the big text at the top of the sentry error.
* **extra:** (optional) an object that gives more context about the error, it is augmented with `stacktrace` which contains `err.stack`
### Message
```javascript
sentry.message(message, logger, extra);
```
#### sample
```javascript
sentry.message(
"message",
"/trial.coffee",
{
note: "to test sentry-node api",
type: "message"
}
);
```
#### arguments
* **message:** text will be used for both the big text that appears at the top and the smaller text appears right under it
* **logger:** the place where the error was detected
* **extra:** (optional) an object that gives more context about the message
### Wrapper
Wrapper can be used to wrap an async function, which will attempt to log any error's passed to the async function's callback with sentry.
```javascript
sentry.wrapper(logger, timeout).wrap(some_async_func);
```
When using wrapper, in case of an error, it's possible to pass extra context parameters by assigning them to the `wrapper.globals` variable:
```
wrapper = sentry_wrapper(logger, timeout)
wrapper.wrap(function(cb) {
if (some_error_case) {
wrapper.globals.context = "some context information to be logged";
cb(new Error("error has occured"));
}
});
```
### sample
```javascript
wrapped = sentry.wrapper('logger', 1000).wrap(function(callback){
callback(new Error('error to be logged'));
});
wrapped();
```
### arguments
* **logger:** value used as the logger argument to sentry.error
* **timeout:** (optional) the timeout (in ms) to wait for sentry to log error. If timeout is exceeded, wrapped async function's callback will return a sentry timeout error.
## Events
The Sentry client emits three events that you can listen to:
- `'logged'`: emitted when an error or message is successfully logged to Sentry
- `'error'`: emitted when an error occurs within the Sentry client and an error or message fails to be logged to Sentry
- `'warning'`:
* emitted when a value of the incorrect type is passed as err or logger
* emitted when a HTTP 429 (burst rate limiting) is returned from Sentry API
```javascript
sentry.on('logged', function(){
console.log('Yay, it worked!');
});
sentry.on('error', function(e){
console.log('oh well, Sentry is broke.');
console.log(e);
})
sentry.on('warning', function(e){
console.log('You did something sentry didn't expect', e);
})
```
## Best Practices
The Sentry client expects an instance of `Error` - if it is given some other object, it will still send the error to Sentry, but much of the error content will be lost. This behavior is intended to align with the node.js best practice of always using `Error` instances. This means you should always take care to construct an `Error` object with an appropriate message before logging it to Sentry (really, you should always be using `Error` objects to represent error data throughout your codebase).
You should always give as much context as possible with your errors. Make liberal use of the `extra` parameter to send more information that may help someone (most likely your future self) diagnose the cause of the error.
If you attach other fields with important data to the `Error` instance, they will not show up in Sentry automatically. You should make sure to include those fields on the `extra` object.
Sentry asks for three main fields:
* `message`: what was the exception? Always the message from the passed in error.
* `logger`: what piece of code generated the message to Sentry? Usually just whatever application actually holds the Sentry client.
* `extra`: what other information is needed to determine the cause of the error