report-toolkit

A toolkit for consumers of Node.js diagnostic Reports

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

:rotating_light: WARNING! :rotating_light:

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

Please see the list of issues labeled help wanted.
report-toolkit wants your ideas for new rules! Please create an issue.

Roadmap

[ ] Documentation
- [x] Real website (https://ibm.github.io/report-toolkit)
- [ ] API docs (incomplete: https://ibm.github.io/report-toolkit/api)
- [ ] Tutorials
- [x] Quick start guide (https://ibm.github.io/report-toolkit/quick-start)
- [x] CLI usage guide (https://ibm.github.io/report-toolkit/cli)
- [ ] Programmatic usage guide
- [ ] Configuration guide
- [ ] Plugin authoring guide
- [ ] Contribution guidelines
- [x] CoC (https://github.com/IBM/report-toolkit/blob/master/.github/CODE_OF_CONDUCT.md)
- [ ] Design docs & developer documentation
[ ] "Interactive" mode -- a "wizard" to help you solve problems (this needs more fleshing out, but the idea is to help developers that may not know "where to start" with diagnostic reports)

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

Maintainer(s)

boneskull

IBM / report-toolkit

readme