Exasol's error reporting libraries and catalog - open source software that you can use too

General
1

Error Catalog and Reporting Libraries

Exasol maintains a central catalog for a growing number of our extensions. Each error there has a unique identifier, level, message and often also an associated mitigation.

You can find the catalog here:

The catalog is automatically generated from the sources of all projects that use our error reporting libraries which we have for a variety of different programming languages:

The Benefits of Uniform Error Reporting

A good user-facing error message must fulfill a whole list of criteria, some of which are in the way they are written, others can be automated by using the right library.

Here’s what Exasol’s error reporting libraries can do for you:

  1. Make sure each error has a unique identifier. This is crucial for making reporting errors easy for the users.
  2. Encourage developers to add mitigation information.
  3. Lay the foundation of collecting the errors in a central error catalog

The central catalog makes it easy for users to get an overview and also help search engines direct searches to the authoritative source.

A Useful Error Message

The way we structure our errors messages also helps with debugging and thus makes error resolution faster.

Let’s look at a typical example: Exasol Error Catalog – E-VSEXA-5

E-VSEXA-5

Message

Attention! Using literals and constant expressions with datatype `TIMESTAMP WITH LOCAL TIME ZONE` in Virtual Schemas can produce incorrect results.

Mitigation

We recommend using ‘TIMESTAMP’ instead. If you are willing to take the risk and want to use `TIMESTAMP WITH LOCAL TIME ZONE` anyway, please, create a Virtual Schema with the following additional property IGNORE_ERRORS = {{switchParameter}}. We also recommend to set Exasol system `time_zone` to UTC while working with `TIMESTAMP WITH LOCAL TIME ZONE`.

Source

src/main/java/com/exasol/adapter/dialects/exasol/ExasolSqlGenerationVisitor.java:38

As you can see the error has a unique identifier that hints at the project it comes from. That’s the first thing that helps with debugging. When you are a supporter or developer you instantly know which project to look in and you can search for the occurrence of the ID in documents and code.

Then there is the message that explains the issue and equally important, a clear suggestion of what to do better.

Last, there is a direct link to the source code where that message originates. This is especially helpful debugging obscure failure scenarios in open source software.

You can use the Libraries too

If you would also like the error messages in your products to be structured uniformly, we would like to encourage you to try out our libraries. They are easy-to-use and well-documented.

Here is a Python example that shows how simple it is to use the error module in your code:


from exasol import error

error1 = error.ExaError(
    "E-TEST-1", "A trivial error", "No mitigation available", {}
)


error2 = error.ExaError(
    "E-TEST-2",
    message="Fire in the server room",
    mitigations=[
        "Use the fire extinguisher",
        "Flood the room with halon gas (Attention: make sure no humans are in the room!)"
    ],
    parameters={}
)

Similarly in Java:

ExaError.messageBuilder(“E-TEST-2”)
        .message(“Unknown input: {{input}}.”)
        .parameter(“input”, “unknown”, “The illegal user input.”).toString();

So, give it a try and let us know how you like it!