Sketch out ergonomic log event API

[jack-berg]

Related to open-telemetry/opentelemetry-specification#4741

OTEP#265 lays out OpenTelemetry's vision for events, which includes a user facing logging API to emit events.

A key pre-requisite of this is that logs recorded via this API should be interoperable with other logging libraries. I've proposed how that works in open-telemetry/opentelemetry-java-instrumentation#15572, and here I propose a set of principles for what an ergonomic, user-facing log API could look like in OpenTelemetry Java.

Design philosophy

• Should only support emitting opentelemetry events. I.e. no support for emitting the types of logs OpenTelemetry wants to be interoperable with, but discourage (structured logs without an event name, or unstructured string logs).
• Should have fluid API (i.e. builder style) and non-fluent low-allocation API
  • Fluent API has convenience methods for incrementally adding fields and attributes.
  • Low-allocation API accepts overloads of the arguments exposed via the builder, allowing for skipping the builder allocation.
• Should be structured to require severity and event name, and optionally accept other event fields:
  • body
  • attributes
• Should be structured to optionally accept an exception, since recording exceptions is a common use case
• Should be structured to allow for explicit or implicit context propagation
• Should be structured to not accept the low-level fields required for appender use cases, but which clutter a user-facing log API:
  • timestamp: (set to clock time when emitted)
  • observed timestamp: (set to clock time when emitted)
  • severity text: irrelevant
• Should deprecate or otherwise discourage use of low-level logRecordBuilder(), calling out that use is only for appenders

Usage examples

To assist with evaluation, I've started pulling together some usage examples and patterns in ErgonomicLogApiUsageTest. In these, I compare what usage looks like in the proposed OpenTelemetry log API to log4j2, slf4j, and JUL.

[codecov]

Codecov Report

❌ Patch coverage is 20.20202% with 79 lines in your changes missing coverage. Please review.
✅ Project coverage is 89.78%. Comparing base (9d47ea2) to head (6657383).
⚠️ Report is 1 commits behind head on main.

Files with missing lines	Patch %	Lines
.../io/opentelemetry/sdk/logs/SdkLogEventBuilder.java	0.00%	26 Missing ⚠️
...entelemetry/api/incubator/logs/ExtendedLogger.java	41.17%	20 Missing ⚠️
...a/io/opentelemetry/sdk/logs/ExtendedSdkLogger.java	0.00%	20 Missing ⚠️
...ntelemetry/api/incubator/logs/LogEventBuilder.java	0.00%	10 Missing ⚠️
...etry/api/incubator/logs/ExtendedDefaultLogger.java	66.66%	3 Missing ⚠️

❌ Your patch check has failed because the patch coverage (20.20%) is below the target coverage (80.00%). You can increase the patch coverage or adjust the target coverage.

Additional details and impacted files

@@             Coverage Diff              @@
##               main    #7907      +/-   ##
============================================
- Coverage     90.04%   89.78%   -0.27%     
- Complexity     7320     7334      +14     
============================================
  Files           825      827       +2     
  Lines         22051    22150      +99     
  Branches       2179     2181       +2     
============================================
+ Hits          19856    19887      +31     
- Misses         1515     1583      +68     
  Partials        680      680              

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[zeitlinger]

lots of overloads - but I think it's warranted in this case

[zeitlinger]

Suggested change

	LogEventBuilder setContext(Context context);
	LogEventBuilder context(Context context);

[zeitlinger]

callback methods are popular to short circuit if the severity is not reached, e.g. https://logging.apache.org/log4j/2.x/javadoc/log4j-api/org/apache/logging/log4j/Logger.html#info(java.lang.String,org.apache.logging.log4j.util.Supplier...)

we could add

void log(Severity severity, Consumer<LogEventBuilder> consumer);