Merge pull request #48693 from angelozerr/qute_trace

Track start/end template + before/after node resolve

Author: mkouba

independent-projects/qute/core/src/main/java/io/quarkus/qute/Engine.java

@@ -6,6 +6,7 @@
 import java.util.function.Predicate;
 
 import io.quarkus.qute.TemplateLocator.TemplateLocation;
+import io.quarkus.qute.trace.TraceListener;
 
 /**
  * Represents a central point for template management.
@@ -182,6 +183,45 @@ default Template parse(String content, Variant variant) {
      */
     boolean removeStandaloneLines();
 
+    /**
+     * Returns the {@link TraceManager} responsible for managing trace listeners and
+     * firing trace events during template rendering.
+     *
+     * @return the trace manager instance or {@code null} if tracing is disabled
+     * @see EngineBuilder#enableTracing(boolean)
+     */
+    TraceManager getTraceManager();
+
+    /**
+     * Registers a new {@link TraceListener} to receive trace events.
+     * <p>
+     * The listener will be notified of template rendering and resolution events.
+     *
+     * @param listener the trace listener to add; must not be {@code null}
+     */
+    default void addTraceListener(TraceListener listener) {
+        TraceManager manager = getTraceManager();
+        if (manager == null) {
+            throw new IllegalStateException("Tracing not enabled");
+        }
+        manager.addTraceListener(listener);
+    }
+
+    /**
+     * Unregisters a previously registered {@link TraceListener}.
+     * <p>
+     * After removal, the listener will no longer receive trace events.
+     *
+     * @param listener the trace listener to remove; must not be {@code null}
+     */
+    default void removeTraceListener(TraceListener listener) {
+        TraceManager manager = getTraceManager();
+        if (manager == null) {
+            throw new IllegalStateException("Tracing not enabled");
+        }
+        manager.removeTraceListener(listener);
+    }
+
     /**
      * Initializes a new {@link EngineBuilder} instance from this engine.
      * <p>
@@ -191,4 +231,5 @@ default Template parse(String content, Variant variant) {
      * @return a new builder instance initialized from this engine
      */
     EngineBuilder newBuilder();
+
 }

independent-projects/qute/core/src/main/java/io/quarkus/qute/EngineBuilder.java

@@ -43,6 +43,7 @@ public final class EngineBuilder {
     long timeout;
     boolean useAsyncTimeout;
     final List<EngineListener> listeners;
+    boolean enableTracing;
 
     EngineBuilder() {
         this.sectionHelperFactories = new HashMap<>();
@@ -336,6 +337,19 @@ public EngineBuilder addEngineListener(EngineListener listener) {
         return this;
     }
 
+    /**
+     * If set to {@code true} then trace listeners that enable logging, profiling, or building interactive debugging tools, can
+     * be registered with the {@link TraceManager}.
+     *
+     * @param value
+     * @return self
+     * @see Engine#getTraceManager()
+     */
+    public EngineBuilder enableTracing(boolean value) {
+        this.enableTracing = value;
+        return this;
+    }
+
     /**
      *
      * @return a new engine instance

independent-projects/qute/core/src/main/java/io/quarkus/qute/EngineImpl.java

@@ -39,6 +39,7 @@ class EngineImpl implements Engine {
     final boolean removeStandaloneLines;
     private final long timeout;
     private final boolean useAsyncTimeout;
+    final TraceManagerImpl traceManager;
 
     EngineImpl(EngineBuilder builder) {
         this.sectionHelperFactories = Map.copyOf(builder.sectionHelperFactories);
@@ -55,6 +56,7 @@ class EngineImpl implements Engine {
         this.initializers = ImmutableList.copyOf(builder.initializers);
         this.timeout = builder.timeout;
         this.useAsyncTimeout = builder.useAsyncTimeout;
+        this.traceManager = builder.enableTracing ? new TraceManagerImpl() : null;
     }
 
     @Override
@@ -236,4 +238,9 @@ private Reader ensureBufferedReader(Reader reader) {
                         reader);
     }
 
+    @Override
+    public TraceManagerImpl getTraceManager() {
+        return traceManager;
+    }
+
 }

independent-projects/qute/core/src/main/java/io/quarkus/qute/Results.java

@@ -13,6 +13,8 @@
 import java.util.function.Supplier;
 import java.util.stream.Collectors;
 
+import io.quarkus.qute.trace.ResolveEvent;
+
 public final class Results {
 
     public static final CompletedStage<Object> FALSE = CompletedStage.of(false);
@@ -43,18 +45,19 @@ public static CompletionStage<Object> notFound() {
         return CompletedStage.of(NotFound.EMPTY);
     }
 
-    static CompletionStage<ResultNode> resolveAndProcess(List<TemplateNode> nodes, ResolutionContext context) {
+    static CompletionStage<ResultNode> resolveAndProcess(List<TemplateNode> nodes, ResolutionContext context,
+            EngineImpl engine) {
         int nodesCount = nodes.size();
         if (nodesCount == 1) {
             // Single node in the block
-            return resolveWith(nodes.get(0), context);
+            return resolveWith(nodes.get(0), context, engine);
         }
         @SuppressWarnings("unchecked")
         Supplier<ResultNode>[] allResults = new Supplier[nodesCount];
         List<CompletableFuture<ResultNode>> asyncResults = null;
         int idx = 0;
         for (TemplateNode templateNode : nodes) {
-            final CompletionStage<ResultNode> result = resolveWith(templateNode, context);
+            final CompletionStage<ResultNode> result = resolveWith(templateNode, context, engine);
             if (result instanceof CompletedStage) {
                 // No async computation needed
                 allResults[idx++] = (CompletedStage<ResultNode>) result;
@@ -99,7 +102,29 @@ private static CompletionStage<ResultNode> toCompletionStage(Supplier<ResultNode
      * This method is trying to speed-up the resolve method which could become a virtual dispatch, harming
      * the performance of trivial implementations like TextNode::resolve, which is as simple as a field access.
      */
-    private static CompletionStage<ResultNode> resolveWith(TemplateNode templateNode, ResolutionContext context) {
+    private static CompletionStage<ResultNode> resolveWith(TemplateNode templateNode, ResolutionContext context,
+            EngineImpl engine) {
+        TraceManagerImpl traceManager = engine.traceManager;
+        if (traceManager == null) {
+            return doResolveWith(templateNode, context);
+        }
+
+        // Notify trace listeners before resolving the template node.
+        final ResolveEvent event = new ResolveEvent(templateNode, context, engine);
+        traceManager.fireBeforeResolveEvent(event);
+
+        return doResolveWith(templateNode, context).whenComplete((result, error) -> {
+            // Notify trace listeners after resolving the template node.
+            event.resolve(result, error);
+            traceManager.fireAfterResolveEvent(event);
+        });
+    }
+
+    /**
+     * This method is trying to speed-up the resolve method which could become a virtual dispatch, harming
+     * the performance of trivial implementations like TextNode::resolve, which is as simple as a field access.
+     */
+    private static CompletionStage<ResultNode> doResolveWith(TemplateNode templateNode, ResolutionContext context) {
         if (templateNode instanceof TextNode textNode) {
             return textNode.resolve(context);
         }

independent-projects/qute/core/src/main/java/io/quarkus/qute/SectionNode.java

@@ -31,13 +31,15 @@ static Builder builder(String helperName, Origin origin, Parser parser,
     final SectionHelper helper;
     private final Origin origin;
     private final boolean traceLevel;
+    private final EngineImpl engine;
 
-    SectionNode(String name, List<SectionBlock> blocks, SectionHelper helper, Origin origin) {
+    SectionNode(String name, List<SectionBlock> blocks, SectionHelper helper, Origin origin, EngineImpl engine) {
         this.name = name;
         this.blocks = blocks;
         this.helper = helper;
         this.origin = origin;
         this.traceLevel = LOG.isTraceEnabled();
+        this.engine = engine;
     }
 
     public CompletionStage<ResultNode> resolve(ResolutionContext context, Map<String, Object> params) {
@@ -46,19 +48,20 @@ public CompletionStage<ResultNode> resolve(ResolutionContext context, Map<String
         }
         if (traceLevel && !Parser.ROOT_HELPER_NAME.equals(name)) {
             LOG.tracef("Resolve {#%s} started:%s", name, origin);
-            return helper.resolve(new SectionResolutionContextImpl(context, params)).thenApply(r -> {
+            return helper.resolve(new SectionResolutionContextImpl(context, params, engine)).thenApply(r -> {
                 LOG.tracef("Resolve {#%s} completed:%s", name, origin);
                 return r;
             });
         }
-        return helper.resolve(new SectionResolutionContextImpl(context, params));
+        return helper.resolve(new SectionResolutionContextImpl(context, params, engine));
     }
 
     @Override
     public CompletionStage<ResultNode> resolve(ResolutionContext context) {
         return resolve(context, null);
     }
 
+    @Override
     public Origin getOrigin() {
         return origin;
     }
@@ -212,7 +215,7 @@ SectionNode build(Supplier<Template> currentTemlate) {
             return new SectionNode(helperName, blocks,
                     factory.initialize(
                             new SectionInitContextImpl(engine, blocks, errorInitializer, currentTemlate, helperName)),
-                    origin);
+                    origin, engine);
         }
 
     }
@@ -221,10 +224,13 @@ class SectionResolutionContextImpl implements SectionResolutionContext {
 
         private final Map<String, Object> params;
         private final ResolutionContext resolutionContext;
+        private final EngineImpl engine;
 
-        public SectionResolutionContextImpl(ResolutionContext resolutionContext, Map<String, Object> params) {
+        public SectionResolutionContextImpl(ResolutionContext resolutionContext, Map<String, Object> params,
+                EngineImpl engine) {
             this.resolutionContext = resolutionContext;
             this.params = params;
+            this.engine = engine;
         }
 
         @Override
@@ -238,7 +244,7 @@ public CompletionStage<ResultNode> execute(SectionBlock block, ResolutionContext
                 // Use the main block
                 block = blocks.get(0);
             }
-            return Results.resolveAndProcess(block.nodes, context);
+            return Results.resolveAndProcess(block.nodes, context, engine);
         }
 
         @Override

independent-projects/qute/core/src/main/java/io/quarkus/qute/TemplateImpl.java

@@ -22,6 +22,7 @@
 
 import org.jboss.logging.Logger;
 
+import io.quarkus.qute.trace.TemplateEvent;
 import io.smallrye.mutiny.Multi;
 import io.smallrye.mutiny.Uni;
 
@@ -273,6 +274,11 @@ private CompletionStage<Void> renderData(Object data, Consumer<String> consumer)
             ResolutionContext rootContext = new ResolutionContextImpl(data,
                     engine.getEvaluator(), null, this);
             setAttribute(DataNamespaceResolver.ROOT_CONTEXT, rootContext);
+            TemplateEvent event = engine.traceManager != null ? new TemplateEvent(this, engine) : null;
+            if (event != null) {
+                // Notify trace listeners that template rendering has started.
+                engine.getTraceManager().fireStartTemplate(event);
+            }
             // Async resolution
             root.resolve(rootContext).whenComplete((r, t) -> {
                 if (t != null) {
@@ -297,6 +303,11 @@ private CompletionStage<Void> renderData(Object data, Consumer<String> consumer)
 
                     }
                 }
+                if (event != null) {
+                    // Notify trace listeners that template rendering has ended.
+                    event.done();
+                    engine.getTraceManager().fireEndTemplate(event);
+                }
             });
             return result;
         }

independent-projects/qute/core/src/main/java/io/quarkus/qute/TraceManager.java

@@ -0,0 +1,42 @@
+package io.quarkus.qute;
+
+import io.quarkus.qute.trace.TraceListener;
+
+/**
+ * Manager that holds and dispatches events to registered
+ * {@link TraceListener}s.
+ * <p>
+ * Each {@link Engine} instance has its own {@code TraceManager} to coordinate
+ * tracing callbacks during template rendering.
+ */
+public interface TraceManager {
+
+    /**
+     * Registers a new {@link TraceListener} to receive trace events.
+     * <p>
+     * The listener will be notified of template rendering and resolution events.
+     *
+     * @param listener the trace listener to add; must not be {@code null}
+     */
+    void addTraceListener(TraceListener listener);
+
+    /**
+     * Unregisters a previously registered {@link TraceListener}.
+     * <p>
+     * After removal, the listener will no longer receive trace events.
+     *
+     * @param listener the trace listener to remove; must not be {@code null}
+     */
+    void removeTraceListener(TraceListener listener);
+
+    /**
+     * Returns {@code true} if there are any trace listeners currently registered,
+     * {@code false} otherwise.
+     * <p>
+     * Trace listeners monitor and react to template rendering events.
+     *
+     * @return {@code true} if at least one trace listener is registered, {@code false} otherwise
+     */
+    boolean hasTraceListeners();
+
+}