Backtrace error reporting tool for Node.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.
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.
Required.
Example: https://backtrace.example.com:6098
.
Sets the HTTP/HTTPS endpoint that error reports will be sent to.
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.
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
.
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",
}
Defaults to 15000
. Maximum amount of milliseconds to wait for child process
to process error report and schedule sending the report to Backtrace.
Defaults to false
. Set to true
to cause process to wait for the report to
Backtrace to complete before exiting.
Defaults to false
. Set to true
to not crash when another uncaughtException
listener is detected.
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)
.
Defaults to 200
. When an error is reported, this many lines above and below
each stack function are included in the report.
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.
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.
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.
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.
Sends an error report to the endpoint specified in initialize
.
error
- optional. AnError
object created withnew Error("message")
. If this parameter is not an instance ofError
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:
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.
Same as bt.report
, but blocks until finished.
Calling this function is the same as doing:
var report = createReport();
report.setError(error);
report.addObjectAttributes(attributes);
report.sendSync();
This is a connect/express middleware function that will automatically send error reports. Use it like this:
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
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
.
Create a BacktraceReport
object with bt.createReport
.
Example:
http.createServer(function(request, response) {
var report = createReport();
report.addObjectAttributes(request);
// ...later...
report.setError(new Error("something broke"));
report.send();
});
Adds an attribute to a specific report. Valid types for value
are
string
, number
, and boolean
.
Attributes are indexed and searchable. See also addAnnotation
.
Adds all key-value pairs of object
into the report recursively. For example:
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 passtrue
forallowPrivateProps
then these keys are added.prefix
String. Defaults to""
. You might consider passing"foo."
to namespace the added attributes with"foo."
.
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
.
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.
[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.
[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
.
Sends the error report to the endpoint specified in initialize
.
callback(err)
- optional. Called when the report is finished sending.
Same as report.send
, but blocks until finished.