CAUSEWAY-3975: Open Telemetry Integration

api/applib/src/main/java/module-info.java

@@ -146,6 +146,7 @@
     requires transitive spring.web;
     requires spring.tx;
     requires org.slf4j;
+	requires micrometer.observation;
 
     // JAXB viewmodels
     opens org.apache.causeway.applib.annotation;

api/applib/src/main/java/org/apache/causeway/applib/services/iactnlayer/InteractionLayer.java

@@ -18,36 +18,71 @@
  */
 package org.apache.causeway.applib.services.iactnlayer;
 
+import org.jspecify.annotations.Nullable;
+
 import org.apache.causeway.applib.services.iactn.Interaction;
+import org.apache.causeway.commons.functional.Try;
 
 /**
  * Binds an {@link Interaction} ("what" is being executed) with
  * an {@link InteractionContext} ("who" is executing, "when" and "where").
  *
- * <p>
- * {@link InteractionLayer}s are so called because they may be nested (held in a stack).  For example the
+ * <p> {@link InteractionLayer}s are so called because they may be nested (held in a stack).  For example the
  * {@link org.apache.causeway.applib.services.sudo.SudoService} creates a new temporary layer with a different
  * {@link InteractionContext#getUser() user}, while fixtures that mock the clock switch out the
  * {@link InteractionContext#getClock() clock}.
- * </p>
  *
- * <p>
- * The stack of layers is per-thread, managed by {@link InteractionService} as a thread-local).
- * </p>
+ * <p> The stack of layers is per-thread, managed by {@link InteractionService} as a thread-local).
  *
  * @since 2.0 {@index}
  */
 public record InteractionLayer(
+        @Nullable InteractionLayer parent,
         /**
-         * Current thread's {@link Interaction} : &quot;what&quot; is being executed
+         * Current thread's {@link Interaction} : WHAT is being executed
          */
         Interaction interaction,
 
         /**
-         * &quot;who&quot; is performing this {@link #getInteraction()}, also
-         * &quot;when&quot; and &quot;where&quot;.
+         * WHO is performing this {@link #getInteraction()}, also
+         * WHEN and WHERE.
+         */
+        InteractionContext interactionContext,
+        /**
+         * @since 4.0
          */
-        InteractionContext interactionContext
-        ) {
+        Runnable onCloseCallback) implements AutoCloseable {
+
+    public boolean isRoot() {
+        return parent==null;
+    }
+
+    public int parentCount() {
+        return parent!=null
+            ? 1 + parent.parentCount()
+            : 0;
+    }
+
+    public int totalLayerCount() {
+        return 1 + parentCount();
+    }
+
+    public InteractionLayer rootLayer() {
+        return parent!=null
+            ? parent.rootLayer()
+            : this;
+    }
+
+    @Override
+    public void close() {
+    	Try.run(onCloseCallback::run); // ignores exceptions
+    }
+
+    public void closeAll() {
+        close();
+        if(parent!=null) {
+            parent.closeAll();
+        }
+    }
 
 }

api/applib/src/main/java/org/apache/causeway/applib/services/iactnlayer/InteractionLayerStack.java

@@ -0,0 +1,103 @@
+/*
+ *  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.causeway.applib.services.iactnlayer;
+
+import java.util.Optional;
+import java.util.function.Predicate;
+
+import org.jspecify.annotations.Nullable;
+
+import org.apache.causeway.applib.services.iactn.Interaction;
+import org.apache.causeway.commons.internal.observation.ObservationClosure;
+
+import io.micrometer.observation.Observation;
+
+public final class InteractionLayerStack {
+
+    // TODO: reading the javadoc for TransactionSynchronizationManager and looking at the implementations
+    //  of TransactionSynchronization (in particular SpringSessionSynchronization), I suspect that this
+    //  ThreadLocal would be considered bad practice and instead should be managed using the TransactionSynchronization mechanism.
+    private final ThreadLocal<InteractionLayer> threadLocalLayer = new ThreadLocal<>();
+
+    public Optional<InteractionLayer> currentLayer() {
+        return Optional.ofNullable(threadLocalLayer.get());
+    }
+
+    public InteractionLayer push(
+            final Interaction interaction,
+            final InteractionContext interactionContext,
+            final Observation observation) {
+        var parent = currentLayer().orElse(null);
+        @SuppressWarnings("resource")
+        var newLayer = new InteractionLayer(parent, interaction, interactionContext,
+        		// on-close callback
+        		new ObservationClosure().startAndOpenScope(observation)::close);
+        threadLocalLayer.set(newLayer);
+        return newLayer;
+    }
+
+    public void clear() {
+        currentLayer().ifPresent(InteractionLayer::closeAll);
+        threadLocalLayer.remove();
+    }
+
+    public boolean isEmpty() {
+        return threadLocalLayer.get()==null;
+    }
+
+    public int size() {
+        return currentLayer()
+                .map(InteractionLayer::totalLayerCount)
+                .orElse(0);
+    }
+
+    @Nullable
+    public InteractionLayer peek() {
+        return threadLocalLayer.get();
+    }
+
+    @Nullable
+    public InteractionLayer pop() {
+        var current = threadLocalLayer.get();
+        if(current==null) return null;
+
+        var newTop = current.parent();
+        current.close();
+        return set(newTop);
+    }
+
+    public void popWhile(final Predicate<InteractionLayer> condition) {
+        while(!isEmpty()) {
+            if(!condition.test(peek())) return;
+            pop();
+        }
+    }
+
+    // -- HELPER
+
+    private InteractionLayer set(@Nullable final InteractionLayer layer) {
+        if(layer != null) {
+            threadLocalLayer.set(layer);
+        } else {
+            threadLocalLayer.remove();
+        }
+        return layer;
+    }
+
+}

api/applib/src/main/java/org/apache/causeway/applib/services/iactnlayer/InteractionService.java

@@ -20,11 +20,11 @@
 
 import java.util.concurrent.Callable;
 
+import org.jspecify.annotations.NonNull;
+
 import org.apache.causeway.commons.functional.ThrowingRunnable;
 import org.apache.causeway.commons.functional.Try;
 
-import org.jspecify.annotations.NonNull;
-
 /**
  * A low-level service to programmatically create a short-lived interaction or session.
  *

bom/pom.xml

@@ -1803,6 +1803,18 @@ identified
                 <version>${jdom.version}</version>
             </dependency>
 
+            <dependency>
+                <groupId>org.springframework.boot</groupId>
+                <artifactId>spring-boot-starter-opentelemetry</artifactId>
+                <version>${spring-boot.version}</version>
+                <exclusions>
+                    <exclusion>
+                        <groupId>org.jetbrains</groupId>
+                        <artifactId>annotations</artifactId>
+                    </exclusion>
+                </exclusions>
+            </dependency>
+
             <dependency>
                 <groupId>org.springframework.boot</groupId>
                 <artifactId>spring-boot-starter-quartz</artifactId>

commons/src/main/java/module-info.java

@@ -50,6 +50,7 @@
     exports org.apache.causeway.commons.internal.html;
     exports org.apache.causeway.commons.internal.image;
     exports org.apache.causeway.commons.internal.ioc;
+    exports org.apache.causeway.commons.internal.observation;
     exports org.apache.causeway.commons.internal.os;
     exports org.apache.causeway.commons.internal.primitives;
     exports org.apache.causeway.commons.internal.proxy;
@@ -67,6 +68,8 @@
     requires transitive tools.jackson.core;
     requires transitive tools.jackson.databind;
     requires transitive tools.jackson.module.jakarta.xmlbind;
+    requires transitive micrometer.commons;
+    requires transitive micrometer.observation;
     requires transitive org.jdom2;
     requires transitive org.jspecify;
     requires transitive org.jsoup;

commons/src/main/java/org/apache/causeway/commons/having/HasTypeSpecificAttributes.java

@@ -18,6 +18,7 @@
  */
 package org.apache.causeway.commons.having;
 
+import java.util.Optional;
 import java.util.function.Function;
 
 public interface HasTypeSpecificAttributes {
@@ -31,6 +32,10 @@ public interface HasTypeSpecificAttributes {
     /** get type specific attribute */
     <T> T getAttribute(Class<T> type);
 
+    default <T> Optional<T> lookupAttribute(final Class<T> type) {
+        return Optional.ofNullable(getAttribute(type));
+    }
+
     /** remove type specific attribute */
     void removeAttribute(Class<?> type);
 

commons/src/main/java/org/apache/causeway/commons/internal/observation/ObservationClosure.java

@@ -0,0 +1,96 @@
+/*
+ *  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.causeway.commons.internal.observation;
+
+import java.util.function.Supplier;
+
+import org.jspecify.annotations.Nullable;
+
+import lombok.Getter;
+import lombok.experimental.Accessors;
+
+import io.micrometer.common.KeyValue;
+import io.micrometer.observation.Observation;
+import io.micrometer.observation.Observation.Scope;
+
+/**
+ * Helps if start and stop of an {@link Observation} happen in different code locations.
+ */
+@Getter @Accessors(fluent = true)
+public final class ObservationClosure implements AutoCloseable {
+
+	public static final KeyValue DISCARD_KEY = KeyValue.of("causeway.discard", "");
+
+    private Observation observation;
+    private Scope scope;
+
+    public ObservationClosure startAndOpenScope(final Observation observation) {
+        if(observation==null) return this;
+        this.observation = observation.start();
+        this.scope = observation.openScope();
+        return this;
+    }
+
+    @Override
+    public void close() {
+        if(observation==null) return;
+        if(scope!=null) {
+            this.scope.close();
+            this.scope = null;
+        }
+        observation.stop();
+    }
+
+    public void onError(final Exception ex) {
+        if(observation==null) return;
+        // scope lifecycle terminates before exception handling
+        if(scope!=null) {
+            this.scope.close();
+            this.scope = null;
+        }
+        observation.error(ex);
+    }
+
+    public ObservationClosure tag(final String key, @Nullable final Supplier<? extends Object> valueSupplier) {
+        if(observation==null || valueSupplier == null) return this;
+        try {
+            observation.highCardinalityKeyValue(key, "" + valueSupplier.get());
+        } catch (Exception e) {
+            observation.highCardinalityKeyValue(key, "EXCEPTION: " + e.getMessage());
+        }
+        return this;
+    }
+
+    public void discard() {
+        discard(this.observation);
+        close();
+    }
+
+    // -- UTILITY
+
+    /**
+     * Denies span export, in collaboration with a Spring registered {@link DiscardedSpanExportingPredicate}.
+     */
+    public static void discard(@Nullable final Observation obs) {
+        if(obs == null)
+            return;
+        obs.lowCardinalityKeyValue(DISCARD_KEY);
+    }
+
+}

core/config/pom.xml

@@ -91,6 +91,11 @@
             <groupId>org.hibernate.validator</groupId>
             <artifactId>hibernate-validator</artifactId>
         </dependency>
+
+        <dependency>
+            <groupId>io.micrometer</groupId>
+            <artifactId>micrometer-tracing</artifactId>
+        </dependency>
 
         <!--
         as per https://github.com/spring-projects/spring-boot/issues/30986, must be

core/config/src/main/java/module-info.java

@@ -27,6 +27,7 @@
     exports org.apache.causeway.core.config.metamodel.facets;
     exports org.apache.causeway.core.config.metamodel.services;
     exports org.apache.causeway.core.config.metamodel.specloader;
+    exports org.apache.causeway.core.config.observation;
     exports org.apache.causeway.core.config.presets;
     exports org.apache.causeway.core.config.progmodel;
     exports org.apache.causeway.core.config.util;
@@ -44,12 +45,16 @@
     requires jakarta.validation;
     requires jakarta.inject;
     requires org.hibernate.validator;
+    requires transitive micrometer.commons;
+    requires transitive micrometer.observation;
+    requires transitive micrometer.tracing;
+    requires transitive spring.boot;
     requires spring.aop;
     requires spring.beans;
-    requires transitive spring.boot;
     requires spring.context;
     requires spring.core;
     requires spring.tx;
+    requires spring.boot.autoconfigure;
     requires org.slf4j;
 
     opens org.apache.causeway.core.config to spring.core, org.hibernate.validator;