report-toolkit Quick Start

Unsurprisingly, to use report-toolkit, you must install it.

For the purposes of this guide, you must be running Node.js version v11.8.0 or newer; the Diagnostic Reports API referenced in this guide will reflect its state at version v11.8.0.

Here are some options for installation:

To do much of anything with report-toolkit, you must generate a diagnostic report.

At the time of this writing (2019-09-23), the diagnostic report functionality is “hidden” behind a flag to the node executable; --experimental-report.

The quickest way to generate a report is to evaluate an inline script, like so:

You’ll see this:

Breaking down the arguments to node, we have:

Next, you'll see how report-toolkit enables safe storage and transmission of report files.

Open report.json in your favorite editor (or use cat or less or whathaveyou). Scroll down to—or search for—the environmentVariables property.

environmentVariables is a top-level property of a report file. It contains a complete dump of the environment at the time the report was created. You might notice API keys, cloud provider tokens, credentials, or other session identifiers; in other words, secrets.

Depending on your filesystem permissions, report.json might even be readable by other users who couldn’t otherwise see your environment. This is a potential leak, and we should plug it. report-toolkit to the rescue!

The report-toolkit package provides command-line utility, rtk.

Assuming report-toolkit is installed globally, run:

You should see:

We see rtk provides commands; the command we want is redact.

By default, the redact command will print its output to STDOUT (the terminal). Instead, let’s use the --output option to write to a new file (smarties may also ask their shell to redirect the output to a file):

If you wish, delete your original report.json; report-redacted.json is now safe to share or send across the wire.

A design goal of report-toolkit is strong security defaults. It will always automatically redact all reports which it ingests. You can disable this via a flag—see the detailed CLI Guide for more information.

Next, you’ll see how rtk can provide a quick comparison of two reports using its diff command.

If you’re having trouble tracking down the difference between two running node processes—say, on two machines that should have identical environments—diagnostic reports and report-toolkit can help.

As you may have deduced, we’ll need two (2) reports to proceed.

To create the first report, named report-1.json, execute:

You’ll see:

To create a second report, repeat the command with the filename changed to report-2.json:

And you will see:

With our two reports in-hand, we can use the diff command to see what’s changed between these two files.

A “diff” between two reports is not a POSIX diff like you’d see between two versions of the same file. If you want that, you can use the diff utility!

Instead, report-toolkit attempts to disregard typically-irrelevant information, and provide output tailored to the data structure of a report file, which is JSON.

To display a diff, execute:

You’ll get something like the below (but probably with fancy colors):

By default, rtk will display a diff in a tabular format, intended for human consumption.

In the table above, we have four (4) columns. Breaking them down:

Note the difference within the header.commandLine array. This reflects the different commands we used to generate each report. We could use that information to determine if the same application generated both reports. Likewise, by comparing header.processId, we could tell if the same process created both reports.

Next, we’ll see how report-toolkit can detect problems using its inspect command.

A diagnostic report is raw data about a node process. If you’re familiar with diagnostic reports—or happen to know precisely what you’re looking for—you can interpret that data yourself.

But much like a radiologist reading an X-ray, report-toolkit can interpret the raw data in a report and provide akin to a diagnosis—or warn about something you may have otherwise overlooked.

Given a diagnostic report, report-toolkit can run a set of rules (heuristics) against it, providing further information if a “check” fails. This is similar—and, in fact, patterned on—how ESLint runs rules against your codebase. Also akin to ESLint, report-toolkit ships with a set of built-in rules, which we’ll use next.

Let’s take one of the reports we’ve already created (it doesn’t matter which). Execute:

Most likely, this command will result in no output—in other words, success. rtk didn’t find anything worth your attention.

Each message emitted by a rule has an associated severity. These severities, from “most severe” to “least severe”, are:

The default behavior of rtk is to exclusively show messages with a severity of error.

But you, the user, can control this. Let’s change the severity threshold to info, and see what happens:

The output should now look something like this (and in color):

Above, we see that two rules (cpu-usage and memory-usage) each output a message. Reading the message, we see that the allowed CPU usage and memory usage, respectively, are within the default thresholds for each rule.

If, for example, the CPU usage was greater than 50%, then instead of a message with severity INFO, the severity would be displayed as ERROR.

Instead of printing a fibonacci sequence in another process, we can use an example “problem” report file to see what an actual error looks like. Download report-high-cpu-usage.example.json; we’ll hand this file to inspect:

Note that the above command does not include --severity info. Now, we should see an error:

In report-high-cpu-usage.example.json, the reported CPU usage (precisely, the mean across all CPUs) is greater than the default threshold of 50%.

You could use this information to verify that the process isn’t taking up too much CPU—or change the range (via a configuration file) to assert the process remains active—or even verify that utilization is high enough to justify paying for the compute!

Finally, let’s see how rtk’s transform command can help convert a report to a more useful format.

The transform command allows you to apply one or more “transformers” to a diagnostic report.

The list of built-in transformers is as follows:

Since this is supposed to be a quick-start guide, we’ll pick two of these as examples: filter and stack-hash.

The filter transformer allows you to essentially “whitelist” or “blacklist” some portion of a report (or both at once; the blacklist takes preference).

For example, if you’d like to retrieve only the version of node used to generate the report, you can use:

Which will result in something like this (depending on the version of node you used to generate the report):

Likewise, the --exclude argument would allow you to, say, omit the entirety the environmentVariables and sharedObjects properties:

As you can see from the above, --include and --exclude can be specified multiple times.

For something more practical, let’s try stack-hash.

The intent of this transformer is to facilitate the gathering of metrics around exceptions (or more specifically, the stack traces thereof).

node can be configured to automatically generate a diagnostic report when it encounters an uncaught exception or a user signal (e.g., SIGUSR1). We can then use the stack-hash transformer to associate the stack (present in all reports) with a reasonably unique SHA1 hash.

Here’s an example of configuring node to automatically output a report file upon an uncaught exception (and summarily throwing one via --eval):

We can then use the stack-hash transformer on report-3.json:

Which will result in something akin to:

If we repeat the command using a different filename (report-4.json):

And run the transformer:

We’ll get the same hash, even though the dumpEventTime (when the report file was created) and filepath differ:

But not if the message is different:

And:

Results in:

You can see that the sha1 property is different, because the exception thrown has a different message.

That wraps up the report-toolkit quick start guide! We’ve learned how to use report-toolkit to:

See below for links to detailed documentation on all of the above topics.