Format option should affect the output formatting of exceptions on STDERR for the CLI #323
Description
Specification
Now that we centralised all of our error functionality into https://github.com/MatrixAI/js-errors, we have a more structured way of creating and propagating way. Due to this, we need our output for these errors to become more formalised as well in order to display this information. We need to be able to communicate the information from our errors to both humans and machines, so we need to modify the --format option to apply to the STDERR as well as the STDOUT.
Readable details included in both styles of output would need to include:
- Structured error information coming from Integrate Structured Logging js-logger#3
- Chained error information coming from Integrate Error Chaining in a js-errors or @matrixai/errors package #304
- Extra data that is put into the
dataproperty - Whether the exception came from local or from a remote PK node Integrate Error Chaining in a js-errors or @matrixai/errors package #304 (comment)
- Contextual information about parsing/validation errors
The json output is the most simple to achieve, since we now have toJSON and fromJSON methods for our errors that allow them to be serialised and deserialised easily. toJSON is called automatically whenever JSON.stringify() is called, so nothing needs to change about how we already handle the output of json data (except for handling non-polykey errors, which have no toJSON method).
A bit more thought needs to go into the human-readable output style, for example:
- Indentation: we want to indent every error in the cause chain, and we want to indent error properties underneath the name of the error
- Formatting: we want to use tabs between keys and values for readability, and keys should be displayed in camelCase
- Data: we want to include important information without crowding the output - we want to minimise repetition (e.g. don't print the exitCode for remote errors since these are inherited from the cause, and don't print the stack for any errors)
There is one point of ambiguity, which is that of logging for the PK agent. When starting the PK agent, we can use the --format option, but this would affect the output of the starting command and the output of logs going to STDERR for the agent process. Should this be 2 separate options? I believe this has been discussed here MatrixAI/js-logger#3 (comment) and the conclusion was that no, it should be 1 option, and it affects STDOUT, STDERR of the CLI command as well as the STDERR logging of the agent process if any.
This means that the format option needs to be propagated to the exit handlers, as well as the error loggers in polykey-agent.ts. This requires dynamic setting of the format property after it has been passed in as an option.
Additional context
- Integrate Structured Logging js-logger#3 - We need structured logging in order to completely address this issue
- Integrate Error Chaining in a js-errors or @matrixai/errors package #304 - Issue for error chaining including implementation details
Tasks
- Modify the output formatter to display more detailed error information (including the error chain)
- Propagate the
--formatoption toCommandPolykey(and all subcommands), the exit handlers, andpolykey-agent