apache / apache/polaris

`PolarisDiagnostics` issues

Open
#759 3 comments 0 reactions 0 assignees View on GitHub
bug
Dominant language
Java
Stars
2.1k
Forks
522
Avg merge
1d 17h
Merged PRs (30d)
137

Description

### Describe the bug

The only implementation of `PolarisDiagnostics` (`PolarisDefaultDiagServiceImpl`) has various issues:

* All functions that take `extraInfoFormat` and `extraInfoArgs` seem to accept a SLF4J-style formatting using `{}`, but the actual formatting relies on Guava's `Preconditions`, which only accepts `%s`. The formatted messages then read awkward: `something_went_wrong: id={} fileName={} ["a", java.lang.Object@deadbeef]` due to the implementation
* The generated exception messages contain rather cryptic information (e.g. `unexpected_not_found_entity`) instead of a description that users can act on.
* Some functions say: "Create a fatal incident if expression is false" - but all the implementation does is calling `Preconditions.checkState()`
* Nit-ish maybe: some functions unnecessarily have a `throw new RuntimeException` after a `Preconditions.checkState(false, ...`

The current implementation is not really useful and emits no information/instructions that a user could act on (other than raising questions on a chat or open a GH issue).

These are some options:
1. replace all usages of `PolarisDiagnostics` with direct use of `Preconditions` / `Objects.requireNonNull` and eventually remove `PolarisDiagnostics` and its implementation
2. refactor `PolarisDiagnostics` and implement a proper mapping of error-codes to user consumable and act-able messages

Generally speaking (IMHO), the use of `PolarisDiagnostics` adds a lot of boilerplate code that makes it harder than necessary to read the code.

Contributor guide

Open the contributing guide

Research direction

Start by auditing PolarisDiagnostics and its only named implementation, PolarisDefaultDiagServiceImpl, along with their usages. Compare the extraInfoFormat handling and exception messages with Preconditions and Objects.requireNonNull, then determine whether removal or error-code mapping is the intended direction. Done means the chosen design is implemented consistently and the emitted diagnostics are actionable.

Written by the indexing model from the issue text.

Assessment

Tech stack
java
Domain
backend
Issue type
Refactor
Difficulty
5/5
Estimated time
Over a week
Activity status
Stale
Clarity
Needs clarification
Newbie friendliness
25/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.