backtrace-node


Backtrace error reporting tool for Node.js.

Usage

``js
var bt = require('backtrace-node');
bt.initialize({
endpoint: "https://youruniverse.sp.backtrace.io:6098",
token: "abcdef123456",
});

// ...

bt.report(new Error("something broke"));
`

For more advanced usage, see BacktraceReport API below.

Documentation

$3

This is intended to be one of the first things your application does during
initialization. It registers a handler for uncaughtException which will
spawn a detached child process to perform the error report and then crash
in the same way that your application would have crashed without the handler.

#### Options

##### endpoint

Required.

Example: https://backtrace.example.com:6098.

Sets the HTTP/HTTPS endpoint that error reports will be sent to.

##### token

Required if you're not using integration via submit.backtrace.io.

Example: 51cc8e69c5b62fa8c72dc963e730f1e8eacbd243aeafc35d08d05ded9a024121.

Sets the token that will be used for authentication when sending an error
report.

##### handlePromises

Optional. Set to true to listen to the unhandledRejection global event and
report those errors in addition to uncaughtException events.

Defaults to false because an application can technically add a promise
rejection handler after an event loop iteration, which would cause the
unhandledRejection event to fire, followed by the rejectionHandled event
when the handler was added later. This would make the error report a false
positive. However, most applications will add rejection handlers before an
event loop iteration, in which case handlePromises should be set to true.

##### attributes

Optional. Object that contains additional attributes to be sent along with
every error report. These can be overridden on an individual report with
report.addAttribute.

Example:

`
{
application: "ApplicationName",
serverId: "foo",
}
`

##### timeout

Defaults to 15000. Maximum amount of milliseconds to wait for child process
to process error report and schedule sending the report to Backtrace.

##### debugBacktrace

Defaults to false. Set to true to cause process to wait for the report to
Backtrace to complete before exiting.

##### allowMultipleUncaughtExceptionListeners

Defaults to false. Set to true to not crash when another uncaughtException
listener is detected.

##### disableGlobalHandler

Defaults to false. If this is false, this module will attach an
uncaughtException handler and report those errors automatically before
re-throwing the exception.

Set to true to disable this. Note that in this case the only way errors
will be reported is if you call bt.report(error).

##### contextLineCount

Defaults to 200. When an error is reported, this many lines above and below
each stack function are included in the report.

##### tabWidth

Defaults to 8. If there are any hard tabs in the source code, it is unclear
how many spaces they should be indented to correctly display the source code.
Therefore the error report can override this number to specify how many spaces
a hard tab should be represented by when viewing source code.

#### sampling

Now, Backtrace-node supports sampling attribute. By using this argument, you can prevent sending reports to the server. You can define sampling value in the BacktraceClientOptions.Sampling option which accepts values from 0 to 1, where 1 means sampling algorithm will skill all reports. If you want to know when Backtrace-node skips a report, please check BacktraceResult object, or use 'sampling-hit' event.

#### rateLimit

Backtrace-node supports client rate limiting! You can define how many reports per one minute you want to send to Backtrace by adding the additional option to the BacktraceClientOptions object. Now, when you reach the defined limit, the client will skip the current report. You can still learn which report won’t be available on the server by using event-emitter and ‘rate-limit’ events or by checking BacktraceResult – object that will return the reportSync/reportAsync method.

$3

Returns a new BacktraceClient instance that you can use to send data to Backtrace. You can create new BacktraceClient manually and then replace existing default BacktraceClient with yours by using use method.

$3

Sends an error report to the endpoint specified in initialize.

* error - optional. An Error object created with new Error("message").
If this parameter is not an instance of Error then backtrace-node will
print a warning message to stderr.
* attributes - optional. An object which contains key-value pairs to add
to the report.
* callback(err) - optional. Called when the report is finished sending.
* attachments - optional. String array with paths to report attachments.

Calling this function is the same as doing:

`js
var report = createReport();
report.setError(error);
report.addObjectAttributes(attributes);
report.send(callback);
`

Though the callstack generation is synchronous, note that actually sending
the report is an asynchronous process. If you wish to synchronously generate
and send the error report, use reportSync as specified below. Note that
unlike report, the reportSync function is also safe to use for
uncaughtException handlers.

$3

Same as bt.report, but blocks until finished.

Calling this function is the same as doing:

`js
var report = createReport();
report.setError(error);
report.addObjectAttributes(attributes);
report.sendSync();
`

$3

This is a connect/express middleware function that will automatically send
error reports. Use it like this:

`js
app.use(bt.errorHandlerMiddleware);
`

This middleware is read-only; it kicks off an error report and then passes the
error down the middleware chain.

For more details see
Express error handling

$3

Create a report object that you can later choose whether or not to send.

This may be useful to track something like a request.

Returns a BacktraceReport.

$3

Create a BacktraceReport object with bt.createReport.

Example:

`js
http.createServer(function(request, response) {
var report = createReport();
report.addObjectAttributes(request);

// ...later...
report.setError(new Error("something broke"));
report.send();
});
`

#### report.addAttribute(key, value)

Adds an attribute to a specific report. Valid types for value are
string, number, and boolean.

Attributes are indexed and searchable. See also addAnnotation.

#### report.addObjectAttributes(object, [options])

Adds all key-value pairs of object into the report recursively. For example:

`js
http.createServer(function(request, response) {
report.addObjectAttributes(request);
});
`

In this example, the list of attributes added is:

`
readable = true
socket.readable = true
socket.writable = true
socket.allowHalfOpen = true
socket.destroyed = false
socket.bytesRead = 0
server.allowHalfOpen = true
server.pauseOnConnect = false
server.httpAllowHalfOpen = false
server.timeout = 120000
parser.maxHeaderPairs = 2000
socket.remoteAddress = "::ffff:127.0.0.1"
socket.remoteFamily = "IPv6"
socket.remotePort = 32958
socket.localAddress = "::ffff:127.0.0.1"
socket.localPort = 12345
socket.bytesWritten = 0
httpVersionMajor = 1
httpVersionMinor = 1
httpVersion = "1.1"
complete = false
headers.host = "localhost:12345"
headers.user-agent = "curl/7.47.0"
headers.accept = "/"
upgrade = false
url = "/"
method = "GET"
`

Available options:

* allowPrivateProps Boolean. By default, keys that start with an underscore
are ignored. If you pass true for allowPrivateProps then these keys are
added.
* prefix String. Defaults to "". You might consider passing "foo." to
namespace the added attributes with "foo.".

#### report.addAnnotation(key, value)

Adds an annotation to a specific report. Annotations, unlike attributes, are
not indexed and searchable. However, they are available for inspection when
you view a specific report.

* key - String which is the name of the annotation.
* value - Any type which is JSON-serializable.

See also addAttribute.

#### report.setError(error)

error is an Error object. Backtrace will extract information from this object
such as the error message and stack trace and send this information along with
the report.

#### report.trace()
[Deprecated]
This function captures a stack trace at the current location. Due to the event
loop, errors in Node.js sometimes are missing part of the stack trace.

Call this function before every asynchronous function call, and your stack
trace will be complete.

Note that it is safe to call trace multiple times; if you call trace
redundantly, backtrace-node will recognize that the second trace call supercedes
the first, and only the latter will be included in the report.

trace is automatically called when you call createReport and when you call
setError.

#### report.log(...)
[Deprecated]

Adds a timestamped log message to the report. Log output is available when you
view a report. The arguments to report.log are the same as the arguments to
console.log.

#### report.send([callback])

Sends the error report to the endpoint specified in initialize.

* callback(err) - optional. Called when the report is finished sending.

#### report.sendSync()

Same as report.send`, but blocks until finished.