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]