Merge pull request #1984 from cescoffier/guardrail-work

Refactor guardrail metrics

Author: cescoffier

.gitignore

@@ -34,6 +34,10 @@ bin/
 *.iml
 *.iws
 
+.idea/
+
+.claude/
+
 # NetBeans
 nb-configuration.xml
 

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,13 +38,72 @@
  * <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.
+     */
+    @Deprecated
     @BuildStep
     void transformWithMetrics(Optional<MetricsCapabilityBuildItem> metricsCapability,
             CombinedIndexBuildItem indexBuildItem,
@@ -48,11 +117,11 @@ void transformWithMetrics(Optional<MetricsCapabilityBuildItem> metricsCapability
                                     AnnotationInstance.builder(MICROMETER_COUNTED)
                                             .add("value", "guardrail.invoked")
                                             .add("description",
-                                                    "Measures the number of times this guardrail was invoked")
+                                                    "Measures the number of times this guardrail was invoked (deprecated)")
                                             .build(),
                                     AnnotationInstance.builder(MICROMETER_TIMED)
                                             .add("value", "guardrail.timed")
-                                            .add("description", "Measures the runtime of this guardrail")
+                                            .add("description", "Measures the runtime of this guardrail (deprecated)")
                                             .add("percentiles", new double[] { 0.75, 0.95, 0.99 })
                                             .add("histogram", true)
                                             .build()),