Per-instance logging context

[lmolkova]

While working on #25671 I found a few gaps not covered in structured logging yet:

• support for global context (i.e. ability to attach a few key-value-pairs to logger instance that will be populated on all log records produced with this logger). In case of AMQP it's always connectionId and sometimes entityPath or linkName.
• support for Object values (with deferred toString() call to serialize them)
• log(RuntimeException)
• log(Supplier<String> message, Throwable)

This PR fills these gaps.

I'm also entertaining the idea of separating context-aware logging to a new ContextualLogger class to reduce some noise and have clearer expectations for each logger. LMK what you think

• CHANGELOG is updated for new features, bug fixes or other significant changes.

[azure-sdk]

API changes have been detected in com.azure:azure-core. You can review API changes here

API changes

+         public ClientLogger(Class<?> clazz, Map<String, Object> context) 
+         public ClientLogger(String className, Map<String, Object> context) 
+         public LoggingEventBuilder addKeyValue(String key, Object value) 
+         public RuntimeException log(RuntimeException runtimeException) 
+         public void log(Supplier<String> messageSupplier, Throwable throwable) 

[srnagar]

Do we throw any other RuntimeException apart from NullPointerException? We should declare the specific exception types in the @throws clause.

[lmolkova]

we are throwing something in DefaultLogger impl, but realistically we can't document closed set of exceptions here because they depend on SLF4J implementation used in the app.

[srnagar]

Do we need this overload since we already have log(Throwable throwable) method?

[lmolkova]

yes, we need it for similar reasons we have one on ClientLogger: when we do throw log(RuntimeException) we don't have to add checked exception or cast the exception type.

[srnagar]

We initially only supported primitive types. With Object, using toString may not always log a human-friendly message which then requires supporting serializers. Should we add this overload only when required? If something like that is required, the caller can always call toString() themselves.
Thoughts?

[lmolkova]

good point. What I found while adopting amqp-core is that I have to repeatedly write something like

  logger.canLogAtLevel(level) {
      builder.addKeyValue("foo", value == null ? null : value.toString());
 }

and even then it won't compile becasue of ambiguity of overload matching for value == null ? null : value.toString()

So based on this, I realized this overload is essential. I tried to document that we only call toString everywhere. SLF4J does the same with {} anchor, i.e. users would have done the same with the old API.

Also, if someone would pass something that doesn't override toString, they would see an unreadable log message and fix it, but it doesn't lead to errors (while explicit toString() might unless it's guarded with all above checks)

[lmolkova]

@JonathanGiles @srnagar can you please take another look?

[srnagar]

LGTM!