Enhancement Request:

The message field produced by --log-json should be broken down into components to give the program that reads the log messages more granularity and more control on how it presents them to the end user. I propose replacing the message field, which is currently a string, with the following:

    "message": {
        "severity": "error",
        "message", "argument must match precisely one archive, but matched 0.",
        "culprit": ["cd682ef4"],
        "codicil": null,
        "trace": null,
        "id": "B207"
    }

These components include:

• severity
  How serious is the condition being reported on by the message. Possible choices include warning, error, fatal, panic, .... This is not needed if it replicates levelname.

• message
  A short (single line) message describing the issue. It should be unadorned (no severity, no culprit, no codicil, no stack trace)

• culprit
  The source of the problem. Could be a simple string or a list. A list would be used to give the components of a hierarchical path (may not be needed for Borg).

• codicil
  Extra information that can be used to understand and resolve the issue. Perhaps including suggestions on what the user might do. Typically a sentence or short paragraph. Might make sense to allow multiple codicils.

• trace
  A stack trace, if one is produced.

• id
  A unique code for each message. This allows the receiving program to change the wording of messages or translate them into different languages without fear that minor adjustments to the message produced by Borg would confound their mappings.

For example, a receiving program may want to present the above message as follows:

    borg error: cd682ef4: archive does not exist.
        If specifying the archive using its ID, add ‘aid:’ prefix (ex.  
        aid:cd682ef4).

In this message 'error' is the severity, 'cd682ef4' is the culprit, 'archive does not exist' is the message, and 'If specifying ...' is the codicil. The id is used to convert the borg supplied message to one that is more oriented to the end user. This is an error message in the traditional Unix style.

Background:

I am developing a wrapper program for Borg Backup v2 called Assimilate. It's goal is to provide a command-line interface to Borg that can accomplish common tasks without the need for shell scripts. This program will be the next generation of Emborg, which performs this same function for Borg Backup v1.

Emborgs's reporting of Borg errors is currently unsatisfactory, and I would like to resolve this in Assimilate. Emborg has one style of reporting errors, but Borg has another, and it can make Emborg look schizophrenic. In addition, Borg itself is inconsistent in how it presents errors, which contributes to the problem.

Some times the error messages consist of a single line:
Command Error: ['cd682ef4'] needed to match precisely one archive, but matched 0.

That is a nice error message except for the syntatic clutter that surrounds the culprit (cd682ef40). It is directed to, and useful to, the end user. But then there are messages like this:

\nError:\n\nBackendAlreadyExists: posixfs storage ... None\n\n

This message spans 5 lines, and does not seem to useful to end users, and is formatted in a manner inconsistent other messages..

Finally, Borg has a habit of producing stack traces, which are jibberish to most end users and act to hide the small bit of relevant information among lots of irrelevant information. In my experience, programs produce a stack traces when they encounter an internal error, and so should be reported as a bug. But Borg seems to generate stack traces for normal occurrences. Regardless, with Assimilate I would like to be able to show just the error message and bury any stack traces in a log file. In addition, I would like to use one style for both Assimilate's and Borg's error messages.