Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/nodejs/node-report
Delivers a human-readable diagnostic summary, written to file.
https://github.com/nodejs/node-report
node nodejs
Last synced: about 1 month ago
JSON representation
Delivers a human-readable diagnostic summary, written to file.
- Host: GitHub
- URL: https://github.com/nodejs/node-report
- Owner: nodejs
- License: other
- Archived: true
- Created: 2016-08-09T13:25:33.000Z (about 8 years ago)
- Default Branch: main
- Last Pushed: 2021-06-17T19:56:46.000Z (over 3 years ago)
- Last Synced: 2024-04-14T00:38:26.591Z (7 months ago)
- Topics: node, nodejs
- Language: C++
- Homepage: https://www.npmjs.com/package/node-report
- Size: 226 KB
- Stars: 327
- Watchers: 24
- Forks: 45
- Open Issues: 6
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGES.md
- Contributing: CONTRIBUTING.md
- License: LICENSE.md
Awesome Lists containing this project
- awesome - nodejs/node-report - Delivers a human-readable diagnostic summary, written to file. (C++)
README
THIS PROJECT HAS BEEN ARCHIVED.
Node-report is now supported as part of Node.js itself.
# node-report
Delivers a human-readable diagnostic summary, written to file.
The report is intended for development, test and production
use, to capture and preserve information for problem determination.
It includes JavaScript and native stack traces, heap statistics,
platform information and resource usage etc. With the report enabled,
reports can be triggered on unhandled exceptions, fatal errors, signals
and calls to a JavaScript API.Supports Node.js versions 8, 10 and 12 on AIX, Linux, macOS, SmartOS and
Windows. Node.js 12 and later contain similar functionality in the built-in
[Diagnostic Report][] feature.NOTE: This repo will be archived and the npm package will be sunset
in lieu of [Diagnostic Report][], when Node.js 10 enters End-of-Life.## Usage
```bash
npm install node-report
node -r node-report app.js
```
A report will be triggered automatically on unhandled exceptions and fatal
error events (for example out of memory errors), and can also be triggered
by sending a USR2 signal to a Node.js process (not supported on Windows).A report can also be triggered via an API call from a JavaScript
application.```js
var nodereport = require('node-report');
nodereport.triggerReport();
```
The content of a report can also be returned as a JavaScript string via an
API call from a JavaScript application.```js
var nodereport = require('node-report');
var report_str = nodereport.getReport();
console.log(report_str);
```
The API can be used without adding the automatic exception and fatal error
hooks and the signal handler, as follows:```js
var nodereport = require('node-report/api');
nodereport.triggerReport();
```Content of the report consists of a header section containing the event
type, date, time, PID and Node version, sections containing JavaScript and
native stack traces, a section containing V8 heap information, a section
containing libuv handle information and an OS platform information section
showing CPU and memory usage and system limits. An example report can be
triggered using the Node.js REPL:```
$ node
> nodereport = require('node-report')
> nodereport.triggerReport()
Writing Node.js report to file: node-report.20161020.091102.8480.001.txt
Node.js report completed
>
```When a report is triggered, start and end messages are issued to stderr
and the filename of the report is returned to the caller. The default filename
includes the date, time, PID and a sequence number. Alternatively, a filename
can be specified as a parameter on the `triggerReport()` call.```js
nodereport.triggerReport("myReportName");
```Both `triggerReport()` and `getReport()` can take an optional `Error` object
as a parameter. If an `Error` object is provided, the message and stack trace
from the object will be included in the report in the `JavaScript Exception
Details` section.
When using node-report to handle errors in a callback or an exception handler
this allows the report to include the location of the original error as well
as where it was handled.
If both a filename and `Error` object are passed to `triggerReport()` the
`Error` object should be the second parameter.```js
try {
process.chdir('/foo/foo');
} catch (err) {
nodereport.triggerReport(err);
}
...
});
```## Configuration
Additional configuration is available using the following APIs:
```js
var nodereport = require('node-report/api');
nodereport.setEvents("exception+fatalerror+signal+apicall");
nodereport.setSignal("SIGUSR2|SIGQUIT");
nodereport.setFileName("stdout|stderr|");
nodereport.setDirectory("");
nodereport.setVerbose("yes|no");
```Configuration on module initialization is also available via environment variables:
```bash
export NODEREPORT_EVENTS=exception+fatalerror+signal+apicall
export NODEREPORT_SIGNAL=SIGUSR2|SIGQUIT
export NODEREPORT_FILENAME=stdout|stderr|
export NODEREPORT_DIRECTORY=
export NODEREPORT_VERBOSE=yes|no
```## Examples
To see examples of reports generated from these events you can run the
demonstration applications provided in the node-report github repository. These are
Node.js applications which will prompt you to trigger the required event.1. `api.js` - report triggered by JavaScript API call.
2. `exception.js` - report triggered by unhandled exception.
3. `fatalerror.js` - report triggered by fatal error on JavaScript heap out of memory.
4. `loop.js` - looping application, report triggered using kill `-USR2 `.## License
[Licensed under the MIT License.](LICENSE.md)
[Diagnostic Report]: https://nodejs.org/dist/latest-v12.x/docs/api/report.html