Skip to content
A toolkit for consumers of Node.js diagnostic Reports
JavaScript CSS HTML
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
.github chore: deploy site on published releases only Feb 3, 2020
packages fix(core): default config loads correctly Feb 13, 2020
scripts chore: development package upgrades Jan 29, 2020
.editorconfig docs: initial commit for gatsby-based docs repo; closes #53 Oct 2, 2019
.eslintignore chore: ensure gatsby stuff is not linted Oct 25, 2019
.eslintrc.yml chore: development package upgrades Jan 29, 2020
.gitignore docs: initial commit for gatsby-based docs repo; closes #53 Oct 2, 2019
.markdownlint.yml chore(lint): update markdownlint cfg for generated CHANGELOG files Nov 7, 2019
.mocharc.js fix(cli): more timeout fixes Jan 29, 2020
.rtkrc.js fix(core): default config loads correctly Feb 13, 2020
CHANGELOG.md chore(release): v0.5.1 Feb 3, 2020
LICENSE.md lint the markdown Mar 27, 2019
README.md docs(readme): fix a couple errors Feb 11, 2020
babel.config.json chore: move to babel.config.json Jan 31, 2020
globals.d.ts chore: fix typing issues in globals.d.ts Aug 13, 2019
jsconfig.json chore: tweak jsconfig.json Jan 30, 2020
lerna.json chore(release): v0.5.1 Feb 3, 2020
lint-staged.config.js chore: fix sync of README.md Feb 3, 2020
netlify.toml chore: attempt to get netlify build to work via cache-busting (#77) Jan 31, 2020
package-lock.json chore(dev): use bleeding-edge prettier for MDX support Feb 6, 2020
package.json chore(dev): use bleeding-edge prettier for MDX support Feb 6, 2020
rollup.config.js chore: development package upgrades Jan 29, 2020
tsconfig.base.json docs: initial commit for gatsby-based docs repo; closes #53 Oct 2, 2019
tsconfig.declarations.json docs: initial commit for gatsby-based docs repo; closes #53 Oct 2, 2019
tsconfig.docs.json chore: development package upgrades Jan 29, 2020

README.md

report-toolkit

A toolkit for consumers of Node.js diagnostic Reports

Build Status Latest Version Licensed Apache-2.0

Features

  • Run heuristics ("Rules") against diagnostic reports to uncover issues needing attention
    • Comes with a set of built-in Rules and a "recommended" configuration
    • Custom, extendable, and shareable Rules
  • Purpose-built, "smart" diagnostic report diffing
    • "What has changed from last report?"
    • Ignores fields that don't matter
  • Automatically redacts sensitive information from report output
    • Redacts cloud provider tokens, session IDs, etc., from environment variables
    • Redaction available as a single operation--use this before sending the report somewhere else!
  • A friendly, colorful command-line interface
  • Two public APIs: Promise-based and Observable-based

Other Stuff Worth Mentioning

  • A choice of output formats:
    • Tabular, human-readable output
    • JSON
    • CSV
  • Handles one or more report files
  • Written using ES modules to facilitate bundling as library for the web

Installation & Usage

🚨 WARNING! 🚨

As per semantic versioning, report-toolkit should be considered experimental until it reaches v1.0.0. Until then, the command-line options, programmatic API or output could change at any time.

report-toolkit is unlikely to reach v1.0.0 until Diagnostic Reports become a stable Node.js API.

For CLI Usage

npx report-toolkit --help

or install globally:

npm install -g report-toolkit && \
report-toolkit --help

For Usage as a Library

npm install report-toolkit

and:

// my-app.js
const {inspect} = require('report-toolkit');

async function main() {
  const report = JSON.parse(process.report.getReport());
  // configuration automatically loaded from `.rtkrc.js` in CWD
  const results = await inspect(report);
  if (results.length) {
    results.forEach(result => {
      // log problem and associated rule ID
      console.log(`${result.message} (${result.id})`);
    });
  } else {
    console.log('no problems!');
  }
}

main();

About Diagnostic Reports

Diagnostic Reports landed as an experimental feature in Node.js v11.8.0.

The Node.js documentation describes reports:

"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, resource usage etc. With the report option enabled, diagnostic reports can be triggered on unhandled exceptions, fatal errors and user signals, in addition to triggering programmatically through API calls."

Contributing

Roadmap

Future Ideas, Extensions & Use Cases

  • report-toolkit-as-a-service: send reports to a service which returns inspection or diff results
  • Client-side ("in your app") wrapper for report transmission or direct invocation of report-toolkit
  • Use CLI or API to trigger report generation from a running node process & interpret results; could be real-time
  • Easy cloud deployment & integration
  • "Connectors" for logging, tracing & observability tools
  • Web or Electron-based GUI
  • Adapters for frameworks
  • IDE/editor integration: generate a report from running process, view results

See Also

Maintainer(s)

License

Copyright © 2019-2020, IBM. Licensed Apache-2.0

You can’t perform that action at this time.