Logging foundation: structured LogEvent, JUL handler, Log API enhancements

apache-maven/pom.xml

@@ -78,13 +78,6 @@ under the License.
       <version>${slf4jVersion}</version>
       <scope>runtime</scope>
     </dependency>
-    <!-- bridge from java.util.logging (JUL) to SLF4J -->
-    <dependency>
-      <groupId>org.slf4j</groupId>
-      <artifactId>jul-to-slf4j</artifactId>
-      <version>${slf4jVersion}</version>
-      <scope>runtime</scope>
-    </dependency>
     <dependency>
       <groupId>org.apache.maven.resolver</groupId>
       <artifactId>maven-resolver-connector-basic</artifactId>

api/maven-api-core/src/main/java/org/apache/maven/api/build/report/LogEvent.java

@@ -0,0 +1,150 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+package org.apache.maven.api.build.report;
+
+import java.time.Instant;
+
+import org.apache.maven.api.annotations.Experimental;
+import org.apache.maven.api.annotations.Nonnull;
+import org.apache.maven.api.annotations.Nullable;
+
+/**
+ * A structured log event captured during the build.
+ * <p>
+ * Each event carries the log level, timestamp, message, and optionally
+ * the logger name and a stack trace. This replaces raw log line strings
+ * in the build report, enabling programmatic filtering by level and
+ * correlation by timestamp.
+ * <p>
+ * Events originating from JUL ({@code java.util.logging}) may carry
+ * additional metadata that is normally lost when routed through the
+ * SLF4J bridge: the source class name, source method name, and thread
+ * identifier.  These fields are populated by Maven's custom JUL
+ * {@link java.util.logging.Handler} and are {@code null} for events
+ * from other logging paths (Log API, SLF4J direct).
+ *
+ * @since 4.1.0
+ */
+@Experimental
+public interface LogEvent {
+
+    /**
+     * When this log event was produced (wall-clock time).
+     *
+     * @return the event instant, never {@code null}
+     */
+    @Nonnull
+    Instant timestamp();
+
+    /**
+     * The severity level of this log event.
+     *
+     * @return the log level, never {@code null}
+     */
+    @Nonnull
+    LogLevel level();
+
+    /**
+     * The log message, without level prefix or timestamp formatting.
+     *
+     * @return the formatted message, never {@code null}
+     */
+    @Nonnull
+    String message();
+
+    /**
+     * The name of the logger that produced this event
+     * (e.g. {@code "org.apache.maven.plugins.compiler.CompilerMojo"}).
+     *
+     * @return the logger name, or {@code null} if unavailable
+     */
+    @Nullable
+    String loggerName();
+
+    /**
+     * The stack trace associated with this event, if an exception was logged.
+     * <p>
+     * The trace is formatted as a multi-line string and may be truncated
+     * for very deep stack traces.
+     *
+     * @return the stack trace string, or {@code null} if no exception was logged
+     */
+    @Nullable
+    String stackTrace();
+
+    /**
+     * The fully formatted log line as rendered for console output, including
+     * the level prefix, timestamp, and any ANSI styling applied by the logger.
+     * <p>
+     * This is the string that would be printed to the terminal in verbose mode.
+     * Console renderers that just need pass-through output can use this directly,
+     * while renderers that apply custom formatting (e.g. rich mode) can use the
+     * structured fields ({@link #level()}, {@link #message()}) instead.
+     * <p>
+     * May be {@code null} if the event was created outside the SLF4J pipeline
+     * (e.g. in tests or by programmatic construction).
+     *
+     * @return the formatted log line, or {@code null}
+     */
+    @Nullable
+    String formattedMessage();
+
+    // ---- JUL metadata (populated only for events from java.util.logging) ----
+
+    /**
+     * The fully qualified class name of the source that issued the log call,
+     * as reported by JUL's {@code LogRecord.getSourceClassName()}.
+     * <p>
+     * This field is only populated for events originating from JUL.  For
+     * events from the Maven Log API or SLF4J, it is {@code null}.
+     *
+     * @return the source class name, or {@code null}
+     * @since 4.1.0
+     */
+    @Nullable
+    default String sourceClassName() {
+        return null;
+    }
+
+    /**
+     * The method name of the source that issued the log call,
+     * as reported by JUL's {@code LogRecord.getSourceMethodName()}.
+     *
+     * @return the source method name, or {@code null}
+     * @since 4.1.0
+     */
+    @Nullable
+    default String sourceMethodName() {
+        return null;
+    }
+
+    /**
+     * The thread identifier from which this log event originated,
+     * as reported by JUL's {@code LogRecord.getLongThreadID()}.
+     * <p>
+     * Returns {@code -1} if the thread ID is not available (i.e. for
+     * non-JUL events).
+     *
+     * @return the thread ID, or {@code -1} if unavailable
+     * @since 4.1.0
+     */
+    default long threadId() {
+        return -1;
+    }
+}

impl/maven-cli/src/main/java/org/apache/maven/cling/logging/impl/Log4j2Configuration.java → api/maven-api-core/src/main/java/org/apache/maven/api/build/report/LogLevel.java

@@ -16,29 +16,21 @@
  * specific language governing permissions and limitations
  * under the License.
  */
-package org.apache.maven.cling.logging.impl;
+package org.apache.maven.api.build.report;
 
-import org.apache.maven.cling.logging.BaseSlf4jConfiguration;
+import org.apache.maven.api.annotations.Experimental;
 
 /**
- * Configuration for slf4j-log4j2.
+ * Log severity levels, mirroring the standard SLF4J levels.
  *
- * @since 3.1.0
+ * @since 4.1.0
+ * @see LogEvent#level()
  */
-public class Log4j2Configuration extends BaseSlf4jConfiguration {
-    @Override
-    public void setRootLoggerLevel(Level level) {
-        String value =
-                switch (level) {
-                    case DEBUG -> "debug";
-                    case INFO -> "info";
-                    default -> "error";
-                };
-        System.setProperty("maven.logging.root.level", value);
-    }
-
-    @Override
-    public void activate() {
-        // no op
-    }
+@Experimental
+public enum LogLevel {
+    TRACE,
+    DEBUG,
+    INFO,
+    WARN,
+    ERROR
 }

api/maven-api-core/src/main/java/org/apache/maven/api/build/report/package-info.java

@@ -0,0 +1,33 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+
+/**
+ * Structured build report data model.
+ * <p>
+ * This package provides structured representations of build execution
+ * data, including log events and (in future) full build reports.
+ * {@link org.apache.maven.api.build.report.LogEvent} is the foundational
+ * type representing a single structured log entry captured during the build.
+ *
+ * @since 4.1.0
+ */
+@Experimental
+package org.apache.maven.api.build.report;
+
+import org.apache.maven.api.annotations.Experimental;

api/maven-api-core/src/main/java/org/apache/maven/api/plugin/Log.java

@@ -36,13 +36,62 @@
 @Experimental
 @Provider
 public interface Log {
+    /**
+     * {@return true if the <b>trace</b> error level is enabled}
+     * @since 4.1.0
+     */
+    boolean isTraceEnabled();
+
+    /**
+     * Sends a message to the user in the <b>trace</b> error level.
+     * <p>
+     * Trace is intended for Maven core internals and low-level framework
+     * diagnostics.  Plugin authors should normally use {@link #debug} for
+     * developer-facing diagnostic output.
+     *
+     * @param content the message to log
+     * @since 4.1.0
+     */
+    void trace(CharSequence content);
+
+    /**
+     * Sends a message (and accompanying exception) to the user at the <b>trace</b> error level.
+     *
+     * @param content the message to log
+     * @param error the error that caused this log
+     * @since 4.1.0
+     */
+    void trace(CharSequence content, Throwable error);
+
+    /**
+     * Sends an exception to the user in the <b>trace</b> error level.
+     *
+     * @param error the error that caused this log
+     * @since 4.1.0
+     */
+    void trace(Throwable error);
+
+    /**
+     * @since 4.1.0
+     */
+    void trace(Supplier<String> content);
+
+    /**
+     * @since 4.1.0
+     */
+    void trace(Supplier<String> content, Throwable error);
+
     /**
      * {@return true if the <b>debug</b> error level is enabled}
      */
     boolean isDebugEnabled();
 
     /**
      * Sends a message to the user in the <b>debug</b> error level.
+     * <p>
+     * Debug is the recommended level for diagnostic output that helps
+     * plugin users troubleshoot build problems (e.g. resolved paths,
+     * computed values).  For Maven core internals, prefer {@link #trace}.
      *
      * @param content the message to log
      */
@@ -167,4 +216,21 @@ public interface Log {
     void error(Supplier<String> content);
 
     void error(Supplier<String> content, Throwable error);
+
+    /**
+     * Returns a child logger whose name is derived from this logger's name
+     * by appending {@code "." + name}.  This allows plugins to create
+     * sub-loggers for different concerns while keeping hierarchical level
+     * control (e.g. setting the level for the parent silences the children).
+     * <p>
+     * The default implementation returns {@code this} so that existing
+     * implementations continue to work without changes.
+     *
+     * @param name the child logger name segment (must not be {@code null})
+     * @return a child {@code Log}, never {@code null}
+     * @since 4.1.0
+     */
+    default Log child(String name) {
+        return this;
+    }
 }

compat/maven-embedder/pom.xml

@@ -163,11 +163,6 @@ under the License.
       <artifactId>commons-cli</artifactId>
     </dependency>
 
-    <dependency>
-      <groupId>ch.qos.logback</groupId>
-      <artifactId>logback-classic</artifactId>
-      <optional>true</optional>
-    </dependency>
     <dependency>
       <groupId>org.jline</groupId>
       <artifactId>jansi-core</artifactId>

impl/maven-cli/pom.xml

@@ -195,19 +195,10 @@ under the License.
       <groupId>org.slf4j</groupId>
       <artifactId>slf4j-api</artifactId>
     </dependency>
-    <dependency>
-      <groupId>org.slf4j</groupId>
-      <artifactId>jul-to-slf4j</artifactId>
-    </dependency>
     <dependency>
       <groupId>commons-cli</groupId>
       <artifactId>commons-cli</artifactId>
     </dependency>
-    <dependency>
-      <groupId>ch.qos.logback</groupId>
-      <artifactId>logback-classic</artifactId>
-      <optional>true</optional>
-    </dependency>
 
     <dependency>
       <groupId>org.junit.jupiter</groupId>

impl/maven-cli/src/main/java/org/apache/maven/cling/invoker/LookupInvoker.java

@@ -83,6 +83,7 @@
 import org.apache.maven.logging.ProjectBuildLogAppender;
 import org.apache.maven.logging.SimpleBuildEventListener;
 import org.apache.maven.logging.api.LogLevelRecorder;
+import org.apache.maven.slf4j.MavenJulHandler;
 import org.apache.maven.slf4j.MavenSimpleLogger;
 import org.codehaus.plexus.PlexusContainer;
 import org.jline.terminal.Terminal;
@@ -91,7 +92,6 @@
 import org.jline.terminal.spi.TerminalExt;
 import org.jline.utils.OSUtils;
 import org.slf4j.LoggerFactory;
-import org.slf4j.bridge.SLF4JBridgeHandler;
 import org.slf4j.spi.LocationAwareLogger;
 
 import static java.util.Objects.requireNonNull;
@@ -436,9 +436,8 @@ protected Consumer<String> doDetermineWriter(C context) {
     }
 
     protected void activateLogging(C context) throws Exception {
-        if (!SLF4JBridgeHandler.isInstalled()) {
-            SLF4JBridgeHandler.removeHandlersForRootLogger();
-            SLF4JBridgeHandler.install();
+        if (!MavenJulHandler.isInstalled()) {
+            MavenJulHandler.install();
         }
 
         context.slf4jConfiguration.activate();