Conditionally generate a bean receiving CDI event to report the guardrail metrics.

Author: cescoffier

core/deployment/src/main/java/io/quarkiverse/langchain4j/deployment/GuardrailObservabilityProcessor.java

@@ -5,20 +5,30 @@
 import java.util.Optional;
 import java.util.function.Consumer;
 
+import jakarta.enterprise.event.Observes;
+import jakarta.inject.Singleton;
+
 import org.jboss.jandex.AnnotationInstance;
 import org.jboss.jandex.AnnotationTransformation;
 import org.jboss.jandex.AnnotationTransformation.TransformationContext;
 import org.jboss.jandex.IndexView;
 import org.jboss.logging.Logger;
 
-import io.quarkiverse.langchain4j.deployment.GuardrailObservabilityProcessorSupport.TransformType;
+import dev.langchain4j.observability.api.event.InputGuardrailExecutedEvent;
+import dev.langchain4j.observability.api.event.OutputGuardrailExecutedEvent;
 import io.quarkus.arc.deployment.AnnotationsTransformerBuildItem;
+import io.quarkus.arc.deployment.GeneratedBeanBuildItem;
+import io.quarkus.arc.deployment.GeneratedBeanGizmoAdaptor;
 import io.quarkus.deployment.Capabilities;
 import io.quarkus.deployment.Capability;
 import io.quarkus.deployment.annotations.BuildProducer;
 import io.quarkus.deployment.annotations.BuildStep;
 import io.quarkus.deployment.builditem.CombinedIndexBuildItem;
 import io.quarkus.deployment.metrics.MetricsCapabilityBuildItem;
+import io.quarkus.gizmo.ClassCreator;
+import io.quarkus.gizmo.ClassOutput;
+import io.quarkus.gizmo.MethodCreator;
+import io.quarkus.gizmo.MethodDescriptor;
 import io.quarkus.runtime.metrics.MetricsFactory;
 
 /**
@@ -28,12 +38,67 @@
  * <p>
  * The main capabilities include:
  * <ul>
- * <li>Applying Micrometer's `@Timed` and `@Counted` annotations to monitor method execution.</li>
+ * <li>Registering the guardrail metric observer that collect metrics about guardrail execution</li>
+ * <li>Applying Micrometer's `@Timed` and `@Counted` annotations to monitor method execution. (deprecated)</li>
  * <li>Adding OpenTelemetry's `@WithSpan` annotation for distributed tracing.</li>
  * </ul>
  */
+@SuppressWarnings("OptionalUsedAsFieldOrParameterType")
 public class GuardrailObservabilityProcessor {
     private static final Logger LOG = Logger.getLogger(GuardrailObservabilityProcessor.class);
+    public static final String GUARDRAIL_METRICS_OBSERVER_SUPPORT_CLASS = "io.quarkiverse.langchain4j.runtime.observability.GuardrailMetricsObserverSupport";
+
+    /**
+     * Metrics collection must only be enabled when Micrometer is available.
+     * In practice, however, Arc always registers observers, regardless of whether
+     * Micrometer is on the classpath or whether an observer bean is actually
+     * registered. As a result, an observer may attempt to record metrics when
+     * Micrometer is missing, which can trigger runtime errors and even break
+     * native image compilation.
+     * <p>
+     * To prevent such failures, this method conditionally generates a bean when
+     * Micrometer support is detected.
+     * The generation logic depends on: {@code io.quarkiverse.langchain4j.runtime.observability.GuardrailMetricsObserverSupport}
+     * *
+     * </p>
+     *
+     * @param metricsCapability the metrics capability build item
+     * @param generatedBean the generated bean build item producer
+     */
+    @BuildStep
+    void addMetricObserver(
+            Optional<MetricsCapabilityBuildItem> metricsCapability,
+            BuildProducer<GeneratedBeanBuildItem> generatedBean) {
+
+        if (metricsCapability.isPresent() && metricsCapability.get().metricsSupported(MetricsFactory.MICROMETER)) {
+            LOG.debug("Generating GuardrailMetricsObserver bean for guardrail metrics collection");
+            ClassOutput output = new GeneratedBeanGizmoAdaptor(generatedBean);
+            ClassCreator.Builder classCreatorBuilder = ClassCreator.builder()
+                    .classOutput(output)
+                    .className("io.quarkiverse.langchain4j.runtime.observability.GuardrailMetricsObserver");
+            try (ClassCreator classCreator = classCreatorBuilder.build()) {
+                classCreator.addAnnotation(Singleton.class);
+                MethodCreator onInputGuardrailExecuted = classCreator.getMethodCreator("onInputGuardrailExecuted", "V",
+                        InputGuardrailExecutedEvent.class);
+                onInputGuardrailExecuted.getParameterAnnotations(0).addAnnotation(Observes.class);
+                var support1 = MethodDescriptor.ofMethod(
+                        GUARDRAIL_METRICS_OBSERVER_SUPPORT_CLASS,
+                        "onInputGuardrailExecuted", "V", InputGuardrailExecutedEvent.class);
+                onInputGuardrailExecuted.invokeStaticMethod(support1, onInputGuardrailExecuted.getMethodParam(0));
+                onInputGuardrailExecuted.returnVoid();
+
+                MethodCreator onOutputGuardrailExecuted = classCreator.getMethodCreator("onOutputGuardrailExecuted", "V",
+                        OutputGuardrailExecutedEvent.class);
+                onOutputGuardrailExecuted.getParameterAnnotations(0).addAnnotation(Observes.class);
+                var support2 = MethodDescriptor.ofMethod(
+                        GUARDRAIL_METRICS_OBSERVER_SUPPORT_CLASS,
+                        "onOutputGuardrailExecuted", "V", OutputGuardrailExecutedEvent.class);
+                onOutputGuardrailExecuted.invokeStaticMethod(support2, onOutputGuardrailExecuted.getMethodParam(0));
+                onOutputGuardrailExecuted.returnVoid();
+            }
+        }
+
+    }
 
     /**
      * @deprecated These metrics are now collected via the GuardrailMetricsObserver bean.

core/runtime/src/main/java/io/quarkiverse/langchain4j/runtime/observability/GuardrailMetricsObserver.java renamed to core/runtime/src/main/java/io/quarkiverse/langchain4j/runtime/observability/GuardrailMetricsObserverSupport.java

@@ -2,20 +2,14 @@
 
 import java.util.concurrent.TimeUnit;
 
-import jakarta.enterprise.context.ApplicationScoped;
-import jakarta.enterprise.event.Observes;
-import jakarta.enterprise.inject.Instance;
-import jakarta.inject.Inject;
-
 import dev.langchain4j.observability.api.event.InputGuardrailExecutedEvent;
 import dev.langchain4j.observability.api.event.OutputGuardrailExecutedEvent;
 import io.micrometer.core.instrument.Counter;
-import io.micrometer.core.instrument.MeterRegistry;
+import io.micrometer.core.instrument.Metrics;
 import io.micrometer.core.instrument.Timer;
-import io.quarkus.arc.Unremovable;
 
 /**
- * Observes guardrail execution events and records metrics with detailed tags.
+ * Support class to observes guardrail execution events and records metrics with detailed tags.
  * <p>
  * This observer listens to {@link InputGuardrailExecutedEvent} and {@link OutputGuardrailExecutedEvent}
  * and records both counter and timer metrics with the following tags:
@@ -27,25 +21,28 @@
  * <li><strong>outcome</strong>: The result of the guardrail execution ({@link GuardrailOutcome})</li>
  * </ul>
  * <p>
- * This observer is only active when Micrometer is available in the application.
+ * Metrics collection must only be enabled when Micrometer is available.
+ * In practice, however, Arc always registers observers, regardless of whether
+ * Micrometer is on the classpath or whether an observer bean is actually
+ * registered. As a result, an observer may attempt to record metrics when
+ * Micrometer is missing, which can trigger runtime errors and even break
+ * native image compilation.
+ * </p>
+ *
+ * <p>
+ * To prevent such failures, this class is only referenced by a bean that is
+ * conditionally generated when Micrometer support is detected.
+ * This class is only providing static methods, so simplify the generation logic.
+ * </p>
  */
-@ApplicationScoped
-@Unremovable
-public class GuardrailMetricsObserver {
-
-    @Inject
-    Instance<MeterRegistry> registry;
+public class GuardrailMetricsObserverSupport {
 
     /**
      * Observes input guardrail execution events and records metrics.
      *
      * @param event the input guardrail executed event
      */
-    public void onInputGuardrailExecuted(@Observes InputGuardrailExecutedEvent event) {
-        if (registry.isUnsatisfied()) {
-            return;
-        }
-
+    public static void onInputGuardrailExecuted(InputGuardrailExecutedEvent event) {
         String aiServiceName = event.invocationContext().interfaceName();
         String methodName = event.invocationContext().methodName();
         String guardrailName = sanitize(event.guardrailClass().getName());
@@ -60,11 +57,7 @@ public void onInputGuardrailExecuted(@Observes InputGuardrailExecutedEvent event
      *
      * @param event the output guardrail executed event
      */
-    public void onOutputGuardrailExecuted(@Observes OutputGuardrailExecutedEvent event) {
-        if (registry.isUnsatisfied()) {
-            return;
-        }
-
+    public static void onOutputGuardrailExecuted(OutputGuardrailExecutedEvent event) {
         String aiServiceName = event.invocationContext().interfaceName();
         String methodName = event.invocationContext().methodName();
         String guardrailName = sanitize(event.guardrailClass().getName());
@@ -74,7 +67,7 @@ public void onOutputGuardrailExecuted(@Observes OutputGuardrailExecutedEvent eve
         recordMetrics(GuardrailType.OUTPUT, aiServiceName, methodName, guardrailName, outcome, durationNanos);
     }
 
-    private String sanitize(String simpleName) {
+    private static String sanitize(String simpleName) {
         if (simpleName == null) {
             return null;
         }
@@ -84,11 +77,9 @@ private String sanitize(String simpleName) {
         return simpleName;
     }
 
-    private void recordMetrics(GuardrailType guardrailType, String aiServiceName, String methodName,
+    private static void recordMetrics(GuardrailType guardrailType, String aiServiceName, String methodName,
             String guardrailName, GuardrailOutcome outcome, long durationNanos) {
 
-        MeterRegistry meterRegistry = registry.get();
-
         Counter.builder("guardrail.invoked")
                 .description("Number of guardrail invocations")
                 .tags(
@@ -97,7 +88,7 @@ private void recordMetrics(GuardrailType guardrailType, String aiServiceName, St
                         "guardrail", guardrailName,
                         "guardrail.type", guardrailType.getValue(),
                         "outcome", outcome.getValue())
-                .register(meterRegistry)
+                .register(Metrics.globalRegistry)
                 .increment();
 
         Timer.builder("guardrail.timed")
@@ -109,11 +100,11 @@ private void recordMetrics(GuardrailType guardrailType, String aiServiceName, St
                         "outcome", outcome.getValue())
                 .publishPercentiles(new double[] { 0.75, 0.95, 0.99 })
                 .publishPercentileHistogram(true)
-                .register(meterRegistry)
+                .register(Metrics.globalRegistry)
                 .record(durationNanos, TimeUnit.NANOSECONDS);
     }
 
-    private GuardrailOutcome determineInputGuardrailOutcome(InputGuardrailExecutedEvent event) {
+    private static GuardrailOutcome determineInputGuardrailOutcome(InputGuardrailExecutedEvent event) {
         // Check if the guardrail execution was successful
         if (event.result().isSuccess()) {
             return GuardrailOutcome.SUCCESS;
@@ -122,7 +113,7 @@ private GuardrailOutcome determineInputGuardrailOutcome(InputGuardrailExecutedEv
         }
     }
 
-    private GuardrailOutcome determineOutputGuardrailOutcome(OutputGuardrailExecutedEvent event) {
+    private static GuardrailOutcome determineOutputGuardrailOutcome(OutputGuardrailExecutedEvent event) {
         // Check the result type to determine the outcome
         if (event.result().isSuccess()) {
             return GuardrailOutcome.SUCCESS;