Control the error reporting verbosity with --verbosity flags
#17
Comments
|
Default verbosity should show us at least 2 things:
It is essential that the metadata should be mostly optional. That is, we should endeavour to describe what the error is in the message with all the relevant properties embedded in the message. The exact output can be something like: Ideally in most cases the I think having the error class name up front might be bad UX for non-technical users. Most examples I see in the wild has the "code" later. Note sure yet. It's probably a good idea to have a short version of the node id too. Commands will need to interpret why it is failing, and provide a custom message (think of this like "localisation") for that specific problem, and then a default message in case it's not one of the expected errors. I believe we deal with this just by creating another exception, and then rethrow it with exception override pattern. |
|
Structured logging is available now, we can make use of it to achieve this. As well as potentially incorporating https://github.com/davidmarkclements/fast-redact for redacting structured information. |
|
JSON structured logging is now being integrated with MatrixAI/Polykey#421. Atm, still no verbosity control is applied to exception/error reporting. At the same time, the reporting of errors is different from the logger. The logger isn't used for reporting exception error information to STDERR. We may look into standardising the reporting of both errors and logs, so that reporting of At the same time, I want to investigate tracing MatrixAI/js-logger#15, if tracing wraps around logger, then our child loggers are replaced with "child spans". These spans then may add additional context around exceptions that get reported. So while exceptions themselves have a low-level stack trace regarding the function call graph, our tracing spans provides a more "global" overview from object contexts to distributed system RPC. So any unification of error logging and structured logging and human readable logging should be designed together. |
|
Moving to Polykey-CLI. |
|
The Add a new command line option to the PK CLI so that one can provide a filter expression (regexp) that will be set to the root logger to control it. Note that this can affect 2 things:
If you want to dynamically control the filter on the agent program - that can be done, but it requires a client service handler that has access to |
Specification
The
--format=humanor--format=jsonnow controls the STDERR reporting of exceptions. See: MatrixAI/Polykey#323.However the verbosity of the report should be controlled with our
--verbosityflag.For
--format=jsonbecause we expect this to be processed by machines, we can say that--verbosedoesn't affect it, and instead all information is produced.However for
--format=humanwe can progressively show more information.Right now without a verbosity flag, our logging level is set to show warnings and up. With the
-vwe get info logs, and-vvwe get debug logs. This means we can think of having 3 levels of error reporting.The default level without a
-vshould be assumed to be used by an end-user of the CLI program, who will probably never look at the source code of PK. Which means, any error we report should only really have the error description and error message. The error name can be useful, if they want to report the error to the dev who can identify the exception.With
-v, extra information about the error should be shown, this should probably mean all the properties except thestackproperty and this applies recursively to the cause chain.Finally with
-vvwe should show the stack property as well.This should apply to exceptions reported on the
src/bin/polykey.tsandsrc/bin/polykey-agent.ts. In the case ofPolykeyAgent, this depends onpk agent start -vv, verbosity flags passed frompk agent startsubcommand.Additional context
Tasks
outputFormatter. Use the verbosity level. It should be a number.pk agent start-vmeans and-vvmeans.The text was updated successfully, but these errors were encountered: