add APIs for llm obs

Author: gary-huang

Diff for: dd-trace-api/src/main/java/datadog/trace/api/llmobs/LLMObs.java

@@ -0,0 +1,60 @@
+package datadog.trace.api.llmobs;
+
+import datadog.trace.api.llmobs.noop.NoOpLLMObsSpanFactory;
+import javax.annotation.Nullable;
+
+public class LLMObs {
+  private static LLMObsSpanFactory SPAN_FACTORY = NoOpLLMObsSpanFactory.INSTANCE;
+
+  public static LLMObsSpan startLLMSpan(
+      String spanName,
+      String modelName,
+      String modelProvider,
+      @Nullable String mlApp,
+      @Nullable String sessionID) {
+
+    return SPAN_FACTORY.startLLMSpan(spanName, modelName, modelProvider, sessionID, mlApp);
+  }
+
+  public static LLMObsSpan startAgentSpan(
+      String spanName, @Nullable String mlApp, @Nullable String sessionID) {
+
+    return SPAN_FACTORY.startAgentSpan(spanName, sessionID, mlApp);
+  }
+
+  public static LLMObsSpan startToolSpan(
+      String spanName, @Nullable String mlApp, @Nullable String sessionID) {
+
+    return SPAN_FACTORY.startToolSpan(spanName, sessionID, mlApp);
+  }
+
+  public static LLMObsSpan startTaskSpan(
+      String spanName, @Nullable String mlApp, @Nullable String sessionID) {
+
+    return SPAN_FACTORY.startTaskSpan(spanName, sessionID, mlApp);
+  }
+
+  public static LLMObsSpan startWorkflowSpan(
+      String spanName, @Nullable String mlApp, @Nullable String sessionID) {
+
+    return SPAN_FACTORY.startWorkflowSpan(spanName, sessionID, mlApp);
+  }
+
+  public interface LLMObsSpanFactory {
+    LLMObsSpan startLLMSpan(
+        String spanName,
+        String modelName,
+        String modelProvider,
+        @Nullable String mlApp,
+        @Nullable String sessionID);
+
+    LLMObsSpan startAgentSpan(String spanName, @Nullable String mlApp, @Nullable String sessionID);
+
+    LLMObsSpan startToolSpan(String spanName, @Nullable String mlApp, @Nullable String sessionID);
+
+    LLMObsSpan startTaskSpan(String spanName, @Nullable String mlApp, @Nullable String sessionID);
+
+    LLMObsSpan startWorkflowSpan(
+        String spanName, @Nullable String mlApp, @Nullable String sessionID);
+  }
+}

Diff for: dd-trace-api/src/main/java/datadog/trace/api/llmobs/LLMObsSpan.java

@@ -0,0 +1,51 @@
+package datadog.trace.api.llmobs;
+
+import java.util.List;
+import java.util.Map;
+import javax.annotation.Nullable;
+
+/** This interface represent an individual LLM Obs span. */
+public interface LLMObsSpan {
+
+  /**
+   * Annotate spans with inputs, outputs, metadata, metrics, and tags.
+   *
+   * @param inputData The input data of the span in the form of a list, for example a list of input
+   *     messages
+   * @param outputData The output data of the span in the form of a list, for example a list of
+   *     output messages
+   * @param metadata A map of JSON serializable key-value pairs that contains metadata information
+   *     relevant to the input or output operation described by the span
+   * @param metrics A map of JSON serializable keys and numeric values that users can add as metrics
+   *     relevant to the operation described by the span (input_tokens, output_tokens, total_tokens,
+   *     etc.).
+   * @param tags An map of JSON serializable key-value pairs that users can add as tags regarding
+   *     the span’s context (session, environment, system, versioning, etc.).
+   */
+  void annotate(
+      @Nullable List<Map<String, Object>> inputData,
+      @Nullable List<Map<String, Object>> outputData,
+      @Nullable Map<String, Object> metadata,
+      @Nullable Map<String, Number> metrics,
+      @Nullable Map<String, Object> tags);
+
+  /**
+   * Annotate spans with inputs, outputs, metadata, metrics, and tags.
+   *
+   * @param inputData The input data of the span in the form of a string
+   * @param outputData The output data of the span in the form of a string
+   * @param metadata A map of JSON serializable key-value pairs that contains metadata information
+   *     relevant to the input or output operation described by the span
+   * @param metrics A map of JSON serializable keys and numeric values that users can add as metrics
+   *     relevant to the operation described by the span (input_tokens, output_tokens, total_tokens,
+   *     etc.).
+   * @param tags An map of JSON serializable key-value pairs that users can add as tags regarding
+   *     the span’s context (session, environment, system, versioning, etc.).
+   */
+  void annotate(
+      @Nullable String inputData,
+      @Nullable String outputData,
+      @Nullable Map<String, Object> metadata,
+      @Nullable Map<String, Number> metrics,
+      @Nullable Map<String, Object> tags);
+}

Diff for: dd-trace-api/src/main/java/datadog/trace/api/llmobs/noop/NoOpLLMObsSpan.java

@@ -0,0 +1,26 @@
+package datadog.trace.api.llmobs.noop;
+
+import datadog.trace.api.llmobs.LLMObsSpan;
+import java.util.List;
+import java.util.Map;
+import javax.annotation.Nullable;
+
+public class NoOpLLMObsSpan implements LLMObsSpan {
+  public static final LLMObsSpan INSTANCE = new NoOpLLMObsSpan();
+
+  @Override
+  public void annotate(
+      @Nullable List<Map<String, Object>> inputData,
+      @Nullable List<Map<String, Object>> outputData,
+      @Nullable Map<String, Object> metadata,
+      @Nullable Map<String, Number> metrics,
+      @Nullable Map<String, Object> tags) {}
+
+  @Override
+  public void annotate(
+      @Nullable String inputData,
+      @Nullable String outputData,
+      @Nullable Map<String, Object> metadata,
+      @Nullable Map<String, Number> metrics,
+      @Nullable Map<String, Object> tags) {}
+}

Diff for: dd-trace-api/src/main/java/datadog/trace/api/llmobs/noop/NoOpLLMObsSpanFactory.java

@@ -0,0 +1,38 @@
+package datadog.trace.api.llmobs.noop;
+
+import datadog.trace.api.llmobs.LLMObs;
+import datadog.trace.api.llmobs.LLMObsSpan;
+import javax.annotation.Nullable;
+
+public class NoOpLLMObsSpanFactory implements LLMObs.LLMObsSpanFactory {
+  public static final NoOpLLMObsSpanFactory INSTANCE = new NoOpLLMObsSpanFactory();
+
+  public LLMObsSpan startLLMSpan(
+      String spanName,
+      String modelName,
+      String modelProvider,
+      @Nullable String mlApp,
+      @Nullable String sessionID) {
+    return NoOpLLMObsSpan.INSTANCE;
+  }
+
+  public LLMObsSpan startAgentSpan(
+      String spanName, @Nullable String mlApp, @Nullable String sessionID) {
+    return NoOpLLMObsSpan.INSTANCE;
+  }
+
+  public LLMObsSpan startToolSpan(
+      String spanName, @Nullable String mlApp, @Nullable String sessionID) {
+    return NoOpLLMObsSpan.INSTANCE;
+  }
+
+  public LLMObsSpan startTaskSpan(
+      String spanName, @Nullable String mlApp, @Nullable String sessionID) {
+    return NoOpLLMObsSpan.INSTANCE;
+  }
+
+  public LLMObsSpan startWorkflowSpan(
+      String spanName, @Nullable String mlApp, @Nullable String sessionID) {
+    return NoOpLLMObsSpan.INSTANCE;
+  }
+}