slachiewicz commented on PR #14066:
URL: https://github.com/apache/maven/pull/14066#issuecomment-7040891401

   ## Comparison with SLF4J and the OpenTelemetry logs API
   
   Maven's new `org.apache.maven.api.logging` API is a **plugin-facing facade 
deliberately modelled on SLF4J's 2.x fluent API**, backed by SLF4J at runtime. 
OpenTelemetry's logs API sits at a different layer: it builds *telemetry 
records* for export, and its own Javadoc says it "should be used to write 
appenders to bridge logs from logging frameworks… **NOT** a replacement for an 
application logging framework."
   
   | Dimension | Maven 4 `api.logging` | SLF4J 2.x | OpenTelemetry Java logs 
API |
   |---|---|---|---|
   | Role | Stable Maven-owned SPI for plugins; implementation delegates to 
SLF4J | Logging facade; binds to Logback, Log4j, JUL, etc. | Telemetry API; SDK 
exports records via OTLP |
   | Obtaining it | `@Inject Logger`, seeded per mojo execution; also 
`child(String)` | `LoggerFactory.getLogger(Class)` static | 
`GlobalLoggerProvider.get().getLogger(name)` or injected `LoggerProvider` |
   | Levels | 5: `TRACE`, `DEBUG`, `INFO`, `WARN`, `ERROR` | Same 5 levels 
(plus custom via markers) | 24 numeric severities: `TRACE`–`TRACE4`, 
`DEBUG`–`DEBUG4`, `INFO`–`INFO4`, `WARN`–`WARN4`, `ERROR`–`ERROR4`, 
`FATAL`–`FATAL4`, `UNDEFINED` |
   | Enablement | `isEnabled(LogLevel)` + `isXxxEnabled()`; disabled `atXxx()` 
returns a shared NOP builder | `isXxxEnabled()`; disabled `atXxx()` returns 
SLF4J's NOP builder | `isEnabled(Severity[, Context])`, default `true`; 
emission is decided by the SDK/no-op provider |
   | Fluent builder | `atInfo().withKeyValue(...).log(...)` — must be one 
chained call | `atInfo().addKeyValue(...).setCause(...).log(...)` — 
`@CheckReturnValue` setters | 
`logRecordBuilder().setSeverity(...).setBody(...).setAttribute(...).setException(...).emit()`
 |
   | Structured fields | `withKeyValue(String, String/long/boolean)` only; no 
`Object` or supplier values | `addKeyValue(String, Object)`, 
`addKeyValue(String, Supplier<Object>)`, markers | Typed `AttributeKey<T>`, 
`Attributes`, `setAllAttributes`, `Value<?>` body — richest typing |
   | Message formatting | SLF4J-style `{}` with 1, 2 or varargs; plus 
`Supplier<String>` | Same `{}` style, plus `addArgument(Supplier)`, 
`setMessage(Supplier)`, `log()` | No template: you build the body string (or a 
`Value`) yourself; formatting is eager |
   | Throwable | `withThrowable(Throwable)` or `info(msg, t)`; no 
`info(Throwable)` | `setCause(t)` or `error(msg, t)` | `setException(t)`; OTel 
guidance explicitly says pass `Throwable` to preserve stack traces |
   | Context/correlation | `withProjectId`/`withMojoId` exist but are no-ops in 
this PR; no trace context | MDC + markers carry thread-local context | 
`setContext(Context)` attaches trace/span context — first-class trace 
correlation |
   | Maturity | `@Experimental @Provider`, brand new in 4.0; 
`LoggerManager`/`LogSink` deferred to 4.2 | Mature, ubiquitous | Logs API 
stable, but intended to be fed by bridges |
   
   Examples:
   
   ```java
   // Maven
   @Inject Logger log;
   log.atInfo().withKeyValue("artifact", id).log("Resolved {} files", count);
   
   // SLF4J
   LOG.atInfo().addKeyValue("artifact", id).log("Resolved {} files", count);
   
   // OpenTelemetry
   logger.logRecordBuilder()
       .setSeverity(Severity.INFO)
       .setBody("Resolved " + count + " files")
       .setAttribute(stringKey("artifact"), id)
       .setException(error)
       .emit();
   ```
   
   Implications for plugins migrating off `org.apache.maven.api.plugin.Log`:
   
   - Move to `api.logging.Logger`, not to SLF4J types. Key-values and `{}` 
messages reach whatever SLF4J backend the build uses, while plugins keep 
compiling against Maven's API only.
   - There is no reason to switch plugins to OTel. Maven has no `setContext`, 
no typed attributes and no SDK, and the two context methods are silent no-ops. 
If OTLP export is wanted later, an SLF4J/Logback bridge can ingest Maven's 
records; trace correlation would have to come from MDC or instrumentation.
   - Mechanical migration gotchas: old `Log.info(Throwable)` has no `Logger` 
equivalent (use `log.atInfo().withThrowable(t).log("")`); old `CharSequence` 
parameters become `String`; `withKeyValue` cannot take an `Object` or a lazy 
supplier; no markers or MDC; the builder must be consumed in one chain.
   
   Sources: [SLF4J fluent 
API](https://github.com/qos-ch/slf4j/blob/master/_autodocs/api-reference/spi.md),
 [OTel 
`Logger`](https://github.com/open-telemetry/opentelemetry-java/blob/main/api/all/src/main/java/io/opentelemetry/api/logs/Logger.java)
 and 
[`LogRecordBuilder`](https://github.com/open-telemetry/opentelemetry-java/blob/main/api/all/src/main/java/io/opentelemetry/api/logs/LogRecordBuilder.java).
   


-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: [email protected]

For queries about this service, please contact Infrastructure at:
[email protected]

Reply via email to