Here's what happens when we're doing something like

public static void main( String[] args ) {
    ClientLogger logger = new ClientLogger(App.class);
    throw logger.atInfo()
        .addKeyValue("hello", "world")
        .log(new RuntimeException("test exception"));
}

1. If user didn't configure any logging, the exception instance is printed to stderr

Exception in thread "main" java.lang.RuntimeException: test exception
	at com.test.App.main(App.java:40)

2. If user set LOG_LEVEL or configured logback/etc, we get a log in stdout and uncaught exception in stderr

2025-04-02 14:42:16.032 [main] [ERROR] com.test.App - {"exception.type":"java.lang.RuntimeException","exception.message":"test exception","hello":"world"}
Exception in thread "main" java.lang.RuntimeException: test exception
	at com.test.App.main(App.java:13)

Assuming user didn't enable our logging and sees unhandled exception or logs it on their own, they don't get any context provided to the log record.

With exceptions, we want to make sure we put all the important details into the exception instance (message), not just on the log record.

I.e. we should do something like

String errorMessage = String.format("Connection with id '%d' terminated, reason - '%s'", connectionId, reason);
throw logger.logThrowableAsError(new SomeException(errorMessage));

which in its turn becomes more friendly to users who don't use logging and less friendly to those who do (since we no longer provide structured context)).

To make it friendly to all users, we could do

String errorMessage = String.format("Connection with id '%d' terminated, reason - '%s'", connectionId, reason);
Throwable error = new SomeException(errorMessage);

logger.atError()
  .addKeyValue("connectionId", connectionId)
  .addKeyValue("reason", reason)
  .setThrowable(error)
  .log("Connection terminated")

throw error;

But then it's not friendly to anyone who needs to write it - it's also hard to keep exception message and log consistent.

We should consider providing a convenience for lib developers to simplify exception creation along with logging it.

We can consider producing an exception message like Connection terminated. {"connectionId": "...", "reason" : "..."} while the log record full be fully structured.