Skip to content
Permalink
Browse files

Merge pull request #2684 from Piankero/error-message-format

error: splitted error_message document, added error message format
  • Loading branch information...
markus2330 committed May 13, 2019
2 parents 1389668 + 9ac5fcd commit 24f3278b2dd8989e50ce12042d00b6d79e1d199f
@@ -29,6 +29,7 @@ section here.
- [Definition of Bool](bool.md)
- [Plugin Variants](plugin_variants.md)
- [Ingroup Removal](ingroup_removal.md)
- [Error Message Format](error_message_format.md)

## In Discussion

@@ -38,7 +39,7 @@ section here.
- [Array](array.md)
- [Vendor Spec](vendor_spec.md)
- [Deferred Plugin Calls](deferred_plugin_calls.md)
- [Error concept](error_message.md)
- [Error codes](error_codes.md)

## Drafts

@@ -1,12 +1,9 @@
#Error message & handling concept
# Error codes

## Problem

The current error concept has disadvantages in following regards:

- Too verbose error message
Currently for every error, 9 lines are shown in which most of them are not relevant to end users/administrators. One goal
is to reduce the verbosity of such messages and let users/administrators see only information they need.
- A lot of redundant errors
At the moment, each new plugin introduces new error codes which led to about 210+ error codes. Many of those errors
are duplicated because developers did not know or search for a similar error which is already present. This concept should
@@ -24,18 +21,15 @@ The current error concept has disadvantages in following regards:

## Constraints

- Error numbers must stay because they are more reliable to check against than strings
- Error codes/numbers must stay but can be changed to another format (eg. Strings)
- Supporting multiple programming languages
- Plugin System
- Supporting Elektra's Plugin System

## Assumptions

## Considered Alternatives

- Removing the specification file without requiring error numbers
- Possible variations on what message should be displayed,
eg. to keep the mountpoint information or on how wordings should be (with or without
"Sorry, ...", coloring of certain parts of a message, etc.)
- Adding the key of the occurred error to the API which permits reading information from
additional metadata such as an error message provided by a specification author.
Reason against: The description of the key should already provide such information.
@@ -80,106 +74,40 @@ Various projects and standards:

## Decision

The error message has the current format:
All "fatal" errors will be converted to "errors" as the distinction is not relevant.

```
The command kdb set failed while accessing the key database with the info:
Sorry, the error (#121) occurred ;(
Description: validation failed
Reason: Validation of key "<key>" with string "<value>" failed.
Ingroup: plugin
Module: enum
At: ....../src/plugins/enum/enum.c:218
Mountpoint: <parentKey>
Configfile: ...../<file>.25676:1549919217.284067.tmp
```
Unused errors will be removed from the specification.

The new default message will look like this:

```
Sorry, plugin <PLUGIN> issued [error|warning] code <NR>:
Validation of key "<key>" with string "<value>" failed.
```

The <NR> will be the color red in case of an error or yellow in case of a warning
while <PLUGIN> will be the color blue.

Optionally a third line indicating a solution can be added. Eg. for a permission related error there would be a third line:

```
Possible Solution: Retry the command as sudo (sudo !!)
```

To avoid losing information, the user can use the command line argument `-v` (verbose) to show
`Mountpoint`, `Configfile` in addition to the current error message.
Furthermore a developer can use the command line argument `-d` (debug)
to show `At` for debugging purposes.

All "fatal" errors will be converted to "errors" as the distinguishment is not relevant.

Unused marked errors will be removed from the specification.

Errors will be categorizes into logical groups with subgroups.
Errors will be categorized into logical groups with subgroups.
Each error will be made up of 5 characters, where the first 2 character indicate the highest level
and character 3 to 5 will be used for subgrouping.

- Permanent errors ("01000")
- Resource ("01100")
- Parsing ("01200")
- Installation ("01300")
- Logical ("01400")
- Conflict ("02000")
- Timeout ("03000")
- Validation ("04000")
- Syntactic ("04100")
- Semantic ("04200")
and character 3 to 5 will be used for subgrouping. Errors are prepended with the letter `C` which
is the abbreviation for "Code".

- Permanent errors C01000
- Resource C01100
- Memory Allocation C01110
- General Resource C01120
- Installation C01200
- Logical C01310
- Assertion C01310
- Interface C01320
- Plugin is Broken C01330
- Conflicting State C02000
- Timeout C03000
- Validation C04000
- Syntactic C04100
- Semantic C04200
- Out-Of-Range C05000

## Rationale

The new error message is much more succinct which gives end users more relevant information.
Furthermore the solution approach still holds all necessary information if requested by users.

`Ingroup`, `Description` and `Module` will be removed from the error message as they provide no useful
information at all.

The grouping of errors will allow developers to filter for specific as well as more general errors to correctly
react to them programmatically.
The new concept will permit additional subgrouping of errors in case it might be needed in the future. Imagine the case where
"Resource" errors is too general because developers saw a need for splitting the errors in "permission" and "existence" errors.
They can simply take the current subclass 01100 and make "permission" be 01110 and "existence" be 01120. This will also allow
backwards compatibility by applications just checking for resource errors in general.
The new concept will permit additional subgrouping of errors in case it might be needed in the future.

Splitting/merging/rearranging any category should only be done by a decision (such as this file here) because elektra developers
should not be able to generate a new category as they wish because it would lead to the same proliferation of errors as we have now.

The classification as of now is done with the following concept in mind:

- Permanent errors
Generally errors which require changes by a user which are not getting fixed by eg. retrying.
- Resource
The class of errors which require certain permissions (opening a file) or where some directory/file is missing.
One possible reaction to these kind of errors is to try a different directory/file or create a missing resource.
- Parsing
Errors while parsing files such as ini/yaml/etc.
Reactions could be to trim line endings/ try different encodings or even try another input at all.
- Installation
Errors in the installation process such as missing plugins or more generic errors in beneath
the plugins/core which cannot be fixed programmatically but needs further investigation.
- Logical
These errors indicate a bug in beneath elektra and should never have happened.
- Conflict
Conflicts indicate temporary problems but also could be harmful such as overwriting a file after a merge conflict.
- Timeout
These errors indicate temporary failures such as connection timeouts or not enough space available. Retrying at a later point in time (or
immediately) will most likely fix the problem.
- Validation
These errors usually indicate wrong values for certain keys such as an invalid port number or wrong types. Such errors require user action and
retry with a different value.
- Syntactic
Syntactic failures indicate a wrong notation or missing characters for example. They require a certain form which was not given by the user.
- Semantic
Semantic errors are failures which indicate a different expectation of the program than from the user concerning the meaning of a value.
One example would be a wrong type or out-of-range errors.

These categories are chosen because they can help developers to react programmatically and cover the majority of use cases to our present knowledge.
If there is ever the need for another reaction based category, it can be extended very easily.

@@ -192,4 +120,7 @@ Current errors will be migrated.

## Related Decisions

- [Error Message Format](error_message_format.md)
Shows the new format of the error message

## Notes
@@ -0,0 +1,91 @@
# Error message format

## Problem

Too verbose error message
Currently for every error, 9 lines are shown in which most of them are not relevant to end users/administrators. One goal
is to reduce the verbosity of such messages and let users/administrators see only information they need.

## Constraints

- Supporting multiple programming languages
- Plugin System
- Error Code should be preserved

## Assumptions

## Considered Alternatives

Possible variations on what message should be displayed,
e.g., to keep the mountpoint information or on how wordings should be (with or without
"Sorry, ...", coloring of certain parts of a message, etc.)

Examples would be to

- Leave out the "Sorry" in the error message or leave the introduction sentence completely
- Drop `At`, `Mountpoint`, `Configfile`, `Module`. This information though yields useful information
or was even added as a request
- Show mountpoint, configfile, module, etc in beneath the general introduction message. Eg.
`The command kdb set failed while accessing the key database on mountpoint (...) with the info`
- Incorporating the description in another ways:
`Reason: Validation of key "<key>" with string "<value>" failed. (validation failed)`
- Use one command line option to show all additional info which gets hidden per default from now on instead of two
- Color the main message differently compared to the general introduction message
- Do not color messages as it might confuse users with overwhelming many colors
- Do not print out the error code. It is useful though for googling

## Decision

The error message has the current format:

```
The command kdb set failed while accessing the key database with the info:
Sorry, the error (#121) occurred ;(
Description: validation failed
Reason: Validation of key "<key>" with string "<value>" failed.
Ingroup: plugin
Module: enum
At: ....../src/plugins/enum/enum.c:218
Mountpoint: <parentKey>
Configfile: ...../<file>.25676:1549919217.284067.tmp
```

The new default message will look like this:

```
Sorry, plugin <MODULE> issued [error|warning] code <NR>:
<ERROR_CODE_DESCRIPTION>: Validation of key "<key>" with string "<value>" failed.
```

The <NR> will be the color red in case of an error or yellow in case of a warning
while <PLUGIN> will be the color blue.

Optionally a third line indicating a solution can be added. Eg. for a permission related error there would be a third line:

```
Possible Solution: Retry the command as sudo (sudo !!)
```

To avoid losing information, the user can use the command line argument `-v` (verbose) to show
`Mountpoint`, `Configfile` in addition to the current error message.
Furthermore a developer can use the command line argument `-d` (debug)
to show `At` for debugging purposes.

## Rationale

The new error message is much more succinct which gives end users more relevant information.
Furthermore the solution approach still holds all necessary information if requested by users.

## Implications

`Description` will be incorporated into `Reason` whereas the `Module` will be incorporated into
the general sentence starting the error message.

## Related Decisions

- [Error Codes](error_codes.md)
Shows how the new error codes are meant to be
- [Ingroup Removal](ingroup_removal.md)
Shows the decision of why the `ingoup` field has been removed

## Notes
@@ -30,6 +30,6 @@ The `ingroup` will be removed from all implementations, metakeys and tests.

## Related Decisions

See [Error concept](error_message.md)
See [Error concept](error_codes.md)

## Notes
@@ -510,6 +510,7 @@ mounted, use `kdb gen -F <plugin>:<file> elektra <parentKey> <outputName>` to lo
- Added [LCDproc](../../examples/spec/lcdproc) and [Cassandra](../../examples/spec/cassandra.ini) specification examples. These examples
provide a good guideline for writing specifications for configurations. _(Michael Zronek)_
- Added a new error concept to be implemented soon. _(Michael Zronek)_
- Added a new error message format concept to be implemented soon. _(Michael Zronek)_
- We fixed the format specifiers in the [“Hello, Elektra” example](https://master.libelektra.org/examples/helloElektra.c). _(René Schwaiger)_
- Expanded the Python Tutorial to cover installation under Alpine Linux. _(Philipp Gackstatter)_

0 comments on commit 24f3278

Please sign in to comment.
You can’t perform that action at this time.