From a86158a60696366fd515e7e70b3f0b77b845b8f5 Mon Sep 17 00:00:00 2001 From: Jeremiah Senkpiel Date: Tue, 15 Nov 2016 13:08:26 -0500 Subject: [PATCH] Improve README.md Better code blocks, clarity, markdown formatting. PR-URL: https://github.com/nodejs/nodereport/pull/23/ --- README.md | 93 ++++++++++++++++++++++++++++++++++--------------------- 1 file changed, 58 insertions(+), 35 deletions(-) diff --git a/README.md b/README.md index d54e587..8865428 100644 --- a/README.md +++ b/README.md @@ -1,24 +1,29 @@ # nodereport -nodereport is an add-on for Node.js, delivered as an npm native module, -which provides a human-readable diagnostic summary report, written -to file. The report is intended for development, test and production +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. The module supports Node.js v4, v6 and v7 -on Linux, MacOS, Windows and AIX. +and calls to a JavaScript API. + +Supports Node.js v4, v6 and v7 on Linux, MacOS, Windows and AIX. -Usage: +## Usage - npm install nodereport +```bash +npm install nodereport +``` -By default, this will allow a NodeReport to be triggered via an API +This will allow a NodeReport to be triggered via an API call from a JavaScript application. - var nodereport = require('nodereport'); - nodereport.triggerReport(); +```js +var nodereport = require('nodereport'); +nodereport.triggerReport(); +``` Content of the NodeReport consists of a header section containing the event type, date, time, PID and Node version, sections containing JavaScript and @@ -27,48 +32,66 @@ containing libuv handle information and an OS platform information section showing CPU and memory usage and system limits. An example NodeReport can be triggered using the Node.js REPL: - C:\test>node - > nodereport = require('nodereport') - > nodereport.triggerReport() - Writing Node.js report to file: NodeReport.20161020.091102.8480.001.txt - Node.js report completed - > +``` +$ node +> nodereport = require('nodereport') +> nodereport.triggerReport() +Writing Node.js report to file: NodeReport.20161020.091102.8480.001.txt +Node.js report completed +> +``` When a NodeReport 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. +can be specified as a parameter on the `triggerReport()` call. - nodereport.triggerReport("myReportName"); +```js +nodereport.triggerReport("myReportName"); +``` A NodeReport can also be triggered automatically on unhandled exceptions, fatal error events (for example out of memory errors), and signals (Linux/MacOS only). Triggering on these events can be enabled using the following API call: - nodereport.setEvents("exception+fatalerror+signal+apicall"); +```js +nodereport.setEvents("exception+fatalerror+signal+apicall"); +``` + +## Configuration Additional configuration is available using the following APIs: - nodereport.setSignal("SIGUSR2|SIGQUIT"); - nodereport.setFileName("stdout|stderr|"); - nodereport.setDirectory(""); - nodereport.setCoreDump("yes|no"); - nodereport.setVerbose("yes|no"); +```js +nodereport.setSignal("SIGUSR2|SIGQUIT"); +nodereport.setFileName("stdout|stderr|"); +nodereport.setDirectory(""); +nodereport.setCoreDump("yes|no"); +nodereport.setVerbose("yes|no"); +``` -Configuration on module initialisation is also available via environment variables: +Configuration on module Initialization is also available via environment variables: - export NODEREPORT_EVENTS=exception+fatalerror+signal+apicall - export NODEREPORT_SIGNAL=SIGUSR2|SIGQUIT - export NODEREPORT_FILENAME=stdout|stderr| - export NODEREPORT_DIRECTORY= - export NODEREPORT_COREDUMP=yes|no - export NODEREPORT_VERBOSE=yes|no +```bash +export NODEREPORT_EVENTS=exception+fatalerror+signal+apicall +export NODEREPORT_SIGNAL=SIGUSR2|SIGQUIT +export NODEREPORT_FILENAME=stdout|stderr| +export NODEREPORT_DIRECTORY= +export NODEREPORT_COREDUMP=yes|no +export NODEREPORT_VERBOSE=yes|no +``` + +## Examples To see examples of NodeReports generated from these events you can run the demonstration applications provided in the nodereport github repository. These are Node.js applications which will prompt you to trigger the required event. -1. api.js - NodeReport triggered by JavaScript API call -2. exception.js - NodeReport triggered by unhandled exception -3. fatalerror.js - NodeReport triggered by fatal error on JavaScript heap out of memory -4. loop.js - looping application, NodeReport triggered using kill -USR2 +1. `api.js` - NodeReport triggered by JavaScript API call. +2. `exception.js` - NodeReport triggered by unhandled exception. +3. `fatalerror.js` - NodeReport triggered by fatal error on JavaScript heap out of memory. +4. `loop.js` - looping application, NodeReport triggered using kill `-USR2 `. + +## License + +[Licensed under the MIT License.](LICENSE.md)