diff --git a/AUTHORS b/AUTHORS deleted file mode 100644 index 5d72b8d..0000000 --- a/AUTHORS +++ /dev/null @@ -1 +0,0 @@ -# Authors ordered by first contribution. diff --git a/MAINTAINER.md b/MAINTAINER.md new file mode 100644 index 0000000..eba3eb6 --- /dev/null +++ b/MAINTAINER.md @@ -0,0 +1,15 @@ +# Instructions for maintainers of the nodereport project + +## Publishing to the npm registry + +The nodereport project is published as an npm native module + +For each publish to npm: + + - update the version property in the package.json file, incrementing the major, minor and patch level as appropriate + - update the CHANGES.md file with a list of commits since last release + - commit CHANGES.md and package.json to nodereport master branch + - tag commit with an annotated tag + - git checkout and npm publish the nodereport package + +Suggested tooling is the slt-release script documented here: https://github.com/strongloop/strong-tools diff --git a/README.md b/README.md index 9728867..eb990d4 100644 --- a/README.md +++ b/README.md @@ -1,46 +1,54 @@ # nodereport -nodereport is an add-on for Node.js, delivered as an NPM native module, +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 use, to capture and preserve information for problem determination. -It includes Javascript and native stack traces, heap statistics, +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. +and calls to a JavaScript API. The module supports Node.js v4, v6 and v7 +on Linux, MacOS and Windows. Usage: - npm install nodejs/nodereport - - var nodereport = require('nodereport'); + npm install nodereport By default, this will allow a NodeReport to be triggered via an API -call from a JavaScript application. The filename of the NodeReport is -returned. The default filename includes the date, time, PID and a -sequence number. Alternatively a filename can be specified on the API call. +call from a JavaScript application. + var nodereport = require('nodereport'); nodereport.triggerReport(); - var filename = 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 +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 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 + > + +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. nodereport.triggerReport("myReportName"); -Content of the NodeReport in the initial implementation 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. -The following messages are issued to stderr when a NodeReport is triggered: +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: - Writing Node.js error report to file: NodeReport.201605113.145311.26249.001.txt - Node.js error report completed + nodereport.setEvents("exception+fatalerror+signal+apicall"); -A NodeReport can also be triggered on unhandled exception and fatal error -events, and/or signals (Linux/OSX only). These and other options can be -enabled or disabled using the following APIs: +Additional configuration is available using the following APIs: - nodereport.setEvents("exception+fatalerror+signal+apicall"); nodereport.setSignal("SIGUSR2|SIGQUIT"); nodereport.setFileName("stdout|stderr|"); nodereport.setDirectory(""); @@ -56,10 +64,11 @@ Configuration on module initialisation is also available via environment variabl export NODEREPORT_COREDUMP=yes|no export NODEREPORT_VERBOSE=yes|no -Sample programs for triggering NodeReports are provided in the -node_modules/nodereport/demo directory: +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. - api.js - NodeReport triggered by Javascript API call - exception.js - NodeReport triggered by unhandled exception - fatalerror.js - NodeReport triggered by fatal error on Javascript heap out of memory - 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 diff --git a/package.json b/package.json index 2b7e926..9621052 100644 --- a/package.json +++ b/package.json @@ -1,9 +1,9 @@ { "name": "nodereport", - "main": "build/Release/nodereport.node", + "main": "nodereport.node", "version": "1.0.4", "description": "Diagnostic NodeReport", - "homepage": "https://github.com/nodejs/nodereport", + "homepage": "https://github.com/nodejs/nodereport#readme", "repository": { "type": "git", "url": "https://github.com/nodejs/nodereport.git" @@ -15,7 +15,13 @@ "nan": "^2.3.5" }, "license": "MIT", + "contributors": [ + "Richard Chamberlain (https://github.com/rnchamberlain)" + ], "scripts": { "test": "node test/autorun.js" + }, + "bugs": { + "url": "https://github.com/nodejs/nodereport/issues" } }