From 46b89a03770c3542fd5050c89f1e0dc02f1c1233 Mon Sep 17 00:00:00 2001 From: Richard Chamberlain Date: Mon, 31 Oct 2016 14:01:10 +0000 Subject: [PATCH 1/7] README documentation improvements 1. Add platform and node version support statement 2. Update usage - now installable from npmjs 3. Separate example install command line from example code 4. Add REPL example 5. Highlight setEvents() API 6. Demo applications are now in github, not npm --- README.md | 61 +++++++++++++++++++++++++++++++------------------------ 1 file changed, 35 insertions(+), 26 deletions(-) diff --git a/README.md b/README.md index 9728867..a3878e2 100644 --- a/README.md +++ b/README.md @@ -7,40 +7,48 @@ 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. +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 From 289b9db3b58ae27bbd952c70b8b8b8ee23288bfb Mon Sep 17 00:00:00 2001 From: Richard Chamberlain Date: Mon, 31 Oct 2016 15:06:24 +0000 Subject: [PATCH 2/7] Set/correct package metadata in package.json 1. nodereport module is copied to top level directory as part of build, so 'main' property should reference that 2. Direct homepage property URL to start of README text 3. Add contributors 4. Add bugs property, referencing nodereport github URL --- package.json | 10 ++++++++-- 1 file changed, 8 insertions(+), 2 deletions(-) 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" } } From e60b4f73bf1bfb083e5f6af20277df799b5461f0 Mon Sep 17 00:00:00 2001 From: Richard Chamberlain Date: Mon, 31 Oct 2016 16:03:23 +0000 Subject: [PATCH 3/7] Add MAINTAINER.md file to document NPM release procedure --- MAINTAINER.md | 15 +++++++++++++++ 1 file changed, 15 insertions(+) create mode 100644 MAINTAINER.md diff --git a/MAINTAINER.md b/MAINTAINER.md new file mode 100644 index 0000000..8da50f7 --- /dev/null +++ b/MAINTAINER.md @@ -0,0 +1,15 @@ +# Instructions for maintainers of the nodereport project + +## Releasing to www.npmjs.com + +The nodereport project is published as an NPM native module here: https://www.npmjs.com/package/nodereport + +On each release to www.npmjs.com + + - 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 From 39e029fb216896c2f672be208aaa32c5cefb944e Mon Sep 17 00:00:00 2001 From: Richard Chamberlain Date: Tue, 1 Nov 2016 14:00:08 +0000 Subject: [PATCH 4/7] Remove specific URLs for NPM --- MAINTAINER.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/MAINTAINER.md b/MAINTAINER.md index 8da50f7..27f8c01 100644 --- a/MAINTAINER.md +++ b/MAINTAINER.md @@ -1,10 +1,10 @@ # Instructions for maintainers of the nodereport project -## Releasing to www.npmjs.com +## Publishing to the NPM registry -The nodereport project is published as an NPM native module here: https://www.npmjs.com/package/nodereport +The nodereport project is published as an NPM native module -On each release to www.npmjs.com +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 From 515c9f1abb02fe15ecb7b4e0cfa05a3766707364 Mon Sep 17 00:00:00 2001 From: Richard Chamberlain Date: Tue, 1 Nov 2016 17:00:42 +0000 Subject: [PATCH 5/7] Correct upper-case NPM, should be lower-case --- MAINTAINER.md | 6 +++--- README.md | 2 +- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/MAINTAINER.md b/MAINTAINER.md index 27f8c01..eba3eb6 100644 --- a/MAINTAINER.md +++ b/MAINTAINER.md @@ -1,10 +1,10 @@ # Instructions for maintainers of the nodereport project -## Publishing to the NPM registry +## Publishing to the npm registry -The nodereport project is published as an NPM native module +The nodereport project is published as an npm native module -For each publish to NPM: +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 diff --git a/README.md b/README.md index a3878e2..94a5b08 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ # 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. From a84f1f0ab1dbea4b366e81e62ccf163758ab30af Mon Sep 17 00:00:00 2001 From: Richard Chamberlain Date: Tue, 1 Nov 2016 17:33:01 +0000 Subject: [PATCH 6/7] Correct Javascript to JavaScript in README.md --- README.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/README.md b/README.md index 94a5b08..eb990d4 100644 --- a/README.md +++ b/README.md @@ -4,10 +4,10 @@ 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. The module supports Node.js v4, v6 and v7 +and calls to a JavaScript API. The module supports Node.js v4, v6 and v7 on Linux, MacOS and Windows. Usage: @@ -21,7 +21,7 @@ call from a JavaScript application. 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 +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 @@ -68,7 +68,7 @@ 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 +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 +3. fatalerror.js - NodeReport triggered by fatal error on JavaScript heap out of memory 4. loop.js - looping application, NodeReport triggered using kill -USR2 From 830ccd9d00e3be41525b68808c9b6f1de336d846 Mon Sep 17 00:00:00 2001 From: Richard Chamberlain Date: Wed, 2 Nov 2016 11:11:24 +0000 Subject: [PATCH 7/7] Deleting AUTHORS file. Contributors are listed in package.json. This change saves having them listed in two places, and is consistent with other nodejs projects such as nan and node-gyp. --- AUTHORS | 1 - 1 file changed, 1 deletion(-) delete mode 100644 AUTHORS 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.