add observation

Author: alexcheng1982

core/pom.xml

@@ -28,6 +28,10 @@
       <artifactId>jspecify</artifactId>
       <version>1.0.0</version>
     </dependency>
+    <dependency>
+      <groupId>io.micrometer</groupId>
+      <artifactId>micrometer-observation</artifactId>
+    </dependency>
   </dependencies>
 
 </project>

core/src/main/java/com/javaaidev/agenticpatterns/core/Agent.java

@@ -1,12 +1,26 @@
 package com.javaaidev.agenticpatterns.core;
 
+import io.micrometer.observation.ObservationRegistry;
+import org.jspecify.annotations.Nullable;
 import org.springframework.ai.chat.client.ChatClient;
 
 public abstract class Agent {
 
   protected final ChatClient chatClient;
+  @Nullable
+  protected final ObservationRegistry observationRegistry;
 
   protected Agent(ChatClient chatClient) {
     this.chatClient = chatClient;
+    this.observationRegistry = null;
+  }
+
+  protected Agent(ChatClient chatClient, @Nullable ObservationRegistry observationRegistry) {
+    this.chatClient = chatClient;
+    this.observationRegistry = observationRegistry;
+  }
+
+  protected String getName() {
+    return this.getClass().getSimpleName();
   }
 }

core/src/main/java/com/javaaidev/agenticpatterns/core/AgentUtils.java

@@ -1,5 +1,8 @@
 package com.javaaidev.agenticpatterns.core;
 
+import com.fasterxml.jackson.core.JsonProcessingException;
+import com.fasterxml.jackson.databind.ObjectMapper;
+import com.fasterxml.jackson.databind.SerializationFeature;
 import java.io.IOException;
 import java.nio.charset.StandardCharsets;
 import java.util.HashMap;
@@ -11,6 +14,9 @@
 
 public class AgentUtils {
 
+  private static final ObjectMapper objectMapper = new ObjectMapper().enable(
+      SerializationFeature.INDENT_OUTPUT);
+
   public static String loadPromptTemplateFromClasspath(String resource) {
     try {
       return new ClassPathResource(resource).getContentAsString(StandardCharsets.UTF_8);
@@ -34,4 +40,12 @@ public static Map<String, Object> mergeMap(@Nullable Map<String, Object> map1,
   public static <T, R> R safeGet(@Nullable T obj, Function<T, R> extractor, R defaultValue) {
     return Optional.ofNullable(obj).map(extractor).orElse(defaultValue);
   }
+
+  public static String toJson(Object input) {
+    try {
+      return objectMapper.writeValueAsString(input);
+    } catch (JsonProcessingException e) {
+      return "{}";
+    }
+  }
 }

core/src/main/java/com/javaaidev/agenticpatterns/core/observation/AgentExecutionObservationContext.java

@@ -0,0 +1,21 @@
+package com.javaaidev.agenticpatterns.core.observation;
+
+import io.micrometer.observation.transport.RequestReplySenderContext;
+
+public class AgentExecutionObservationContext extends RequestReplySenderContext<Object, Object> {
+
+  private final String agentName;
+
+  public AgentExecutionObservationContext(
+      String agentName, Object input) {
+    super((carrier, key, value) -> {
+
+    });
+    this.agentName = agentName;
+    setCarrier(input);
+  }
+
+  public String getAgentName() {
+    return agentName;
+  }
+}

core/src/main/java/com/javaaidev/agenticpatterns/core/observation/AgentExecutionObservationConvention.java

@@ -0,0 +1,13 @@
+package com.javaaidev.agenticpatterns.core.observation;
+
+import io.micrometer.observation.Observation.Context;
+import io.micrometer.observation.ObservationConvention;
+
+public interface AgentExecutionObservationConvention extends
+    ObservationConvention<AgentExecutionObservationContext> {
+
+  @Override
+  default boolean supportsContext(Context context) {
+    return context instanceof AgentExecutionObservationContext;
+  }
+}

core/src/main/java/com/javaaidev/agenticpatterns/core/observation/AgentExecutionObservationDocumentation.java

@@ -0,0 +1,50 @@
+package com.javaaidev.agenticpatterns.core.observation;
+
+import io.micrometer.common.docs.KeyName;
+import io.micrometer.observation.Observation.Context;
+import io.micrometer.observation.ObservationConvention;
+import io.micrometer.observation.docs.ObservationDocumentation;
+
+public enum AgentExecutionObservationDocumentation implements ObservationDocumentation {
+  AGENT_EXECUTION {
+    @Override
+    public Class<? extends ObservationConvention<? extends Context>> getDefaultConvention() {
+      return DefaultAgentExecutionObservationConvention.class;
+    }
+
+    @Override
+    public KeyName[] getLowCardinalityKeyNames() {
+      return LowCardinalityKeyNames.values();
+    }
+
+    @Override
+    public KeyName[] getHighCardinalityKeyNames() {
+      return HighCardinalityKeyNames.values();
+    }
+  };
+
+  public enum LowCardinalityKeyNames implements KeyName {
+    AGENT_NAME {
+      @Override
+      public String asString() {
+        return "agent.name";
+      }
+    }
+  }
+
+  public enum HighCardinalityKeyNames implements KeyName {
+    AGENT_EXECUTION_INPUT {
+      @Override
+      public String asString() {
+        return "agent.execution.input";
+      }
+    },
+
+    AGENT_EXECUTION_OUTPUT {
+      @Override
+      public String asString() {
+        return "agent.execution.output";
+      }
+    }
+  }
+}

core/src/main/java/com/javaaidev/agenticpatterns/core/observation/DefaultAgentExecutionObservationConvention.java

@@ -0,0 +1,54 @@
+package com.javaaidev.agenticpatterns.core.observation;
+
+import com.javaaidev.agenticpatterns.core.AgentUtils;
+import com.javaaidev.agenticpatterns.core.observation.AgentExecutionObservationDocumentation.HighCardinalityKeyNames;
+import com.javaaidev.agenticpatterns.core.observation.AgentExecutionObservationDocumentation.LowCardinalityKeyNames;
+import io.micrometer.common.KeyValue;
+import io.micrometer.common.KeyValues;
+
+public class DefaultAgentExecutionObservationConvention implements
+    AgentExecutionObservationConvention {
+
+  private String defaultName = "agent.execute";
+
+
+  @Override
+  public String getName() {
+    return defaultName;
+  }
+
+  @Override
+  public KeyValues getLowCardinalityKeyValues(AgentExecutionObservationContext context) {
+    return KeyValues.of(agentName(context));
+  }
+
+  @Override
+  public KeyValues getHighCardinalityKeyValues(AgentExecutionObservationContext context) {
+    return KeyValues.of(
+        agentExecutionInput(context),
+        agentExecutionOutput(context)
+    );
+  }
+
+  private KeyValue agentName(AgentExecutionObservationContext context) {
+    return KeyValue.of(
+        LowCardinalityKeyNames.AGENT_NAME, context.getAgentName()
+    );
+  }
+
+  private KeyValue agentExecutionInput(AgentExecutionObservationContext context) {
+    return KeyValue.of(
+        HighCardinalityKeyNames.AGENT_EXECUTION_INPUT,
+        context.getCarrier() != null ? AgentUtils.toJson(context.getCarrier()) : KeyValue.NONE_VALUE
+    );
+  }
+
+  private KeyValue agentExecutionOutput(AgentExecutionObservationContext context) {
+    return KeyValue.of(
+        HighCardinalityKeyNames.AGENT_EXECUTION_OUTPUT,
+        context.getResponse() != null ? AgentUtils.toJson(context.getResponse())
+            : KeyValue.NONE_VALUE
+    );
+  }
+
+}

examples/observation-docker/.gitignore

@@ -0,0 +1 @@
+tempo-data/

examples/observation-docker/config/grafana-datasources.yaml

@@ -0,0 +1,30 @@
+apiVersion: 1
+
+datasources:
+  - name: Prometheus
+    type: prometheus
+    uid: prometheus
+    access: proxy
+    orgId: 1
+    url: http://prometheus:9090
+    basicAuth: false
+    isDefault: false
+    version: 1
+    editable: false
+    jsonData:
+      httpMethod: GET
+  - name: Tempo
+    type: tempo
+    access: proxy
+    orgId: 1
+    url: http://tempo:3200
+    basicAuth: false
+    isDefault: true
+    version: 1
+    editable: false
+    apiVersion: 1
+    uid: tempo
+    jsonData:
+      httpMethod: GET
+      serviceMap:
+        datasourceUid: prometheus

examples/observation-docker/config/otel-collector.yaml

@@ -0,0 +1,15 @@
+receivers:
+  otlp:
+    protocols:
+      grpc:
+      http:
+exporters:
+  otlp:
+    endpoint: tempo:4317
+    tls:
+      insecure: true
+service:
+  pipelines:
+    traces:
+      receivers: [ otlp ]
+      exporters: [ otlp ]