Track start/end template + before/after node resolve #48693

angelozerr · 2025-06-30T11:16:11Z

This PR provides the capability to track start/end template rendering and before/after node resolve (it follows the same idea than Saxon events used to implement a debugger). I need this support to provide the Qute debugger that I am implementing and integrating in IntelliJ (and it will be easy to integrate in vscode and even in Eclipse IDE):

Here a demo with breakpoint and steps:

Here a demo with expression eval:

Breakpoint with condition is supported:

Engine#addTraceListener(TraceListener listener)

The track can be done by adding a TraceListener registered with Engine#addTraceListener(TraceListener listener)

Here a sample how to use TraceListener:

import io.quarkus.qute.Engine;
import io.quarkus.qute.ReflectionValueResolver;
import io.quarkus.qute.Template;
import io.quarkus.qute.trace.ResolveEvent;
import io.quarkus.qute.trace.TemplateEvent;
import io.quarkus.qute.trace.TraceListener;

public class TraceSample {

    public static void main(String[] args) throws InterruptedException {

        Engine engine = Engine.builder()
                .addDefaults()
                .addValueResolver(new ReflectionValueResolver()).build();

        Template template = engine.parse("""
                <html>
                   Hello {name}!
                </html>
                """);

        engine.addTraceListener(new TraceListener() {
            @Override
            public void onStartTemplate(TemplateEvent event) {
                System.err.println("Starting template (id): " + event.getTemplateInstance().getTemplate().getId());
            }

            @Override
            public void onBeforeResolve(ResolveEvent event) {
                System.err.println("Before node resolve: " + event.getTemplateNode());
            }

            @Override
            public void onAfterResolve(ResolveEvent event) {
                System.err.println("After node resolve: " + event.getTemplateNode() + " in " + event.getEllapsedTime() + "ms");
            }

            @Override
            public void onEndTemplate(TemplateEvent event) {
                System.err.println("Rendering template (id): " + event.getTemplateInstance().getTemplate().getId() + " in " + event.getEllapsedTime() + "ms");
            }
        });


        String s = template.data("name", "Quarkus")
                .render();
        System.err.println(s);

    }
}

You will see in the console the following trace:

Starting template (id): 1
Before node resolve: TextNode [value=<html>
   Hello ]
After node resolve: TextNode [value=<html>
   Hello ] in 1ms
Before node resolve: ExpressionNode [expression=Expression [namespace=null, parts=[name], literal=null]]
After node resolve: ExpressionNode [expression=Expression [namespace=null, parts=[name], literal=null]] in 8ms
Before node resolve: TextNode [value=!
</html>
]
After node resolve: TextNode [value=!
</html>
] in 0ms
Rendering template (id): 1 in 23ms
<html>
   Hello Quarkus!
</html>

Register TraceListener with Java SPI

As you can see the PR have no dependencies to the Qute debugger. How Qute debugger can be registered?

The answer is that Qute debugger will track creation of Engine instance with the existing EngineListener API. Qute debugger need to register a custom EngineListener (RegisterDebugServerAdapter) to track Engine build. To do that the Qute debugger register this custom EngineListener with Java SPI with the following file stored in the Qute debugger artifact

src/main/resources/META-INF/services/io.quarkus.qute.EngineBuilder$EngineListener which contains io.quarkus.qute.debug.adapter.RegisterDebugServerAdapter

The Qute debugger adds a custom TraceListener to block the process (by using wait() in onAfterResolve if there is a breakpoint defined for the resolved node.

angelozerr · 2025-06-30T13:32:22Z

@mkouba @maxandersen @ia3andy please review this PR because I need it to provide Qute debugger which starts working.

angelozerr · 2025-06-30T13:35:09Z

@FroMage please also review this PR

ia3andy · 2025-06-30T13:35:18Z

That looks very cool, as this is based on the contract that will be hard to change, we need to make sure the api/contract is flexible and will not change in the future.

angelozerr · 2025-06-30T13:50:17Z

That looks very cool, as this is based on the contract that will be hard to change, we need to make sure the api/contract is flexible and will not change in the future.

Perhaps I will need more changes because for the moment my Qute debugger is just a POC and I have hard coded some things like src/main/resources/templates folder because I need to retrieve file path from a given template id since Qute works only with template id and not with file path.

But I think the API to track nodes is enough.

FroMage

LGTM, though I'm not a fan of the nested interface for the service file, we should probably move it out.
But I'll let @mkouba merge this.

FroMage · 2025-06-30T14:03:23Z

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

@@ -58,6 +59,11 @@ public final class EngineBuilder {
        this.timeout = 10_000;
        this.useAsyncTimeout = true;
        this.listeners = new ArrayList<>();
+        // Load EngineListener implementations via Java SPI and register them.
+        ServiceLoader<EngineListener> listenerExtensions = ServiceLoader.load(EngineListener.class);


Apparently this is an inner class, making it hard to add a services file for it, because EngineBuilder$EngineListener is often an annoying character to deal with from the command-line.

I know but I don't want to change the existing API.

Why do we use the service loader at all? I mean, we don't use service loaders for anything else. The EngineBuilder is intended to be used purely programmatically.

I need this service loader for the Qute debuger. The Qute debugger need to track all Engine which was built. If your Quarkus App uses for instance N EngineBuilder, the Qute debugger can track all engine created by the N EngineBuilder.

By using ServiceLoader, the Qute core have no dependencies to the Qute debugger.

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

FroMage · 2025-06-30T14:04:47Z

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

-    private static CompletionStage<ResultNode> resolveWith(TemplateNode templateNode, ResolutionContext context) {
+    private static CompletionStage<ResultNode> resolveWith(TemplateNode templateNode, ResolutionContext context,
+            Engine engine) {
+        if (!engine.hasTraceListeners()) {


Oh that's where it's used, OK.

angelozerr · 2025-06-30T14:13:49Z

LGTM, though I'm not a fan of the nested interface for the service file, we should probably move it out. But I'll let @mkouba merge this.

I agree with you but it is the existing API.

angelozerr · 2025-06-30T16:26:07Z

@mkouba I switched the PR to draft because I have some bugs with item inside #for while debugging.

I don't know if the problem comes from this PR.

angelozerr · 2025-07-01T09:28:39Z

@mkouba sorry for the noise, the bug was inside my current Qute debugger, this PR works perfectly for now.

mkouba · 2025-07-01T12:56:32Z

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

+    @Override
+    public TraceManager getTraceManager() {
+        if (traceManager == null) {
+            traceManager = new TraceManager();


Why the lazy loading here? Also you would need use the volatile modifier + synchronize, or the io.quarkus.qute.LazyValue abstraction to make it thread-safe.

I wanted to create a trace manager if nobody regsiters a listener, but I agree with you, I can create it every time and set it as final, since it exists hasTraceListeners.

mkouba · 2025-07-01T13:00:24Z

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

+ */
+public class TraceManager {
+
+    private List<TraceListener> listeners;


You should use a thread-safe List variant (such as CopyOnWriteArrayList). And ideally, the reference should be final.

Indeed it is very basic, I need to improve that but for the moment I have not seen some trouble.

Signed-off-by: azerr <azerr@redhat.com>

angelozerr force-pushed the qute_trace branch 6 times, most recently from cf41f2c to 1768462 Compare June 30, 2025 13:12

angelozerr marked this pull request as ready for review June 30, 2025 13:30

FroMage reviewed Jun 30, 2025

View reviewed changes

angelozerr force-pushed the qute_trace branch from 1768462 to 3b37388 Compare June 30, 2025 14:37

angelozerr marked this pull request as draft June 30, 2025 16:21

angelozerr force-pushed the qute_trace branch from 3b37388 to c5cd3f6 Compare June 30, 2025 16:29

angelozerr marked this pull request as ready for review July 1, 2025 09:28

mkouba reviewed Jul 1, 2025

View reviewed changes

Track start/end template + before/after node resolve

2d88b79

Signed-off-by: azerr <azerr@redhat.com>

angelozerr force-pushed the qute_trace branch from c5cd3f6 to 2d88b79 Compare July 1, 2025 15:45

Track start/end template + before/after node resolve #48693

Are you sure you want to change the base?

Track start/end template + before/after node resolve #48693

Uh oh!

Conversation

angelozerr commented Jun 30, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Engine#addTraceListener(TraceListener listener)

Register TraceListener with Java SPI

Uh oh!

angelozerr commented Jun 30, 2025

Uh oh!

angelozerr commented Jun 30, 2025

Uh oh!

ia3andy commented Jun 30, 2025

Uh oh!

angelozerr commented Jun 30, 2025

Uh oh!

FroMage left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

angelozerr commented Jun 30, 2025

Uh oh!

angelozerr commented Jun 30, 2025

Uh oh!

angelozerr commented Jul 1, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

angelozerr commented Jun 30, 2025 •

edited

Loading