add APIs for llm obs

dd-trace-api/build.gradle

@@ -31,6 +31,10 @@ excludedClassesCoverage += [
   'datadog.trace.api.profiling.ProfilingScope',
   'datadog.trace.api.profiling.ProfilingContext',
   'datadog.trace.api.profiling.ProfilingContextAttribute.NoOp',
+  'datadog.trace.api.llmobs.LLMObs',
+  'datadog.trace.api.llmobs.LLMObsSpan',
+  'datadog.trace.api.llmobs.noop.NoOpLLMObsSpan',
+  'datadog.trace.api.llmobs.noop.NoOpLLMObsSpanFactory',
   'datadog.trace.api.experimental.DataStreamsCheckpointer',
   'datadog.trace.api.experimental.DataStreamsCheckpointer.NoOp',
   'datadog.trace.api.experimental.DataStreamsContextCarrier',

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, mlApp, sessionID);
+  }
+
+  public static LLMObsSpan startAgentSpan(
+      String spanName, @Nullable String mlApp, @Nullable String sessionID) {
+
+    return SPAN_FACTORY.startAgentSpan(spanName, mlApp, sessionID);
+  }
+
+  public static LLMObsSpan startToolSpan(
+      String spanName, @Nullable String mlApp, @Nullable String sessionID) {
+
+    return SPAN_FACTORY.startToolSpan(spanName, mlApp, sessionID);
+  }
+
+  public static LLMObsSpan startTaskSpan(
+      String spanName, @Nullable String mlApp, @Nullable String sessionID) {
+
+    return SPAN_FACTORY.startTaskSpan(spanName, mlApp, sessionID);
+  }
+
+  public static LLMObsSpan startWorkflowSpan(
+      String spanName, @Nullable String mlApp, @Nullable String sessionID) {
+
+    return SPAN_FACTORY.startWorkflowSpan(spanName, mlApp, sessionID);
+  }
+
+  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);
+  }
+}

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

@@ -0,0 +1,147 @@
+package datadog.trace.api.llmobs;
+
+import java.util.List;
+import java.util.Map;
+
+/** This interface represent an individual LLM Obs span. */
+public interface LLMObsSpan {
+
+  /**
+   * Annotate the span with inputs and outputs
+   *
+   * @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
+   */
+  void annotateIO(List<Map<String, Object>> inputData, List<Map<String, Object>> outputData);
+
+  /**
+   * Annotate the span with inputs and outputs
+   *
+   * @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
+   */
+  void annotateIO(String inputData, String outputData);
+
+  /**
+   * Annotate the span with metadata
+   *
+   * @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
+   */
+  void setMetadata(Map<String, Object> metadata);
+
+  /**
+   * Annotate the span with metrics
+   *
+   * @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.).
+   */
+  void setMetrics(Map<String, Number> metrics);
+
+  /**
+   * Annotate the span with a single metric key value pair for the span’s context (number of tokens
+   * document length, etc).
+   *
+   * @param key the name of the metric
+   * @param value the value of the metric
+   */
+  void setMetric(CharSequence key, int value);
+
+  /**
+   * Annotate the span with a single metric key value pair for the span’s context (number of tokens
+   * document length, etc).
+   *
+   * @param key the name of the metric
+   * @param value the value of the metric
+   */
+  void setMetric(CharSequence key, long value);
+
+  /**
+   * Annotate the span with a single metric key value pair for the span’s context (number of tokens
+   * document length, etc).
+   *
+   * @param key the name of the metric
+   * @param value the value of the metric
+   */
+  void setMetric(CharSequence key, double value);
+
+  /**
+   * Annotate the span with tags
+   *
+   * @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 setTags(Map<String, Object> tags);
+
+  /**
+   * Annotate the span with a single tag key value pair as a tag regarding the span’s context
+   * (session, environment, system, versioning, etc.).
+   *
+   * @param key the key of the tag
+   * @param value the value of the tag
+   */
+  void setTag(String key, String value);
+
+  /**
+   * Annotate the span with a single tag key value pair as a tag regarding the span’s context
+   * (session, environment, system, versioning, etc.).
+   *
+   * @param key the key of the tag
+   * @param value the value of the tag
+   */
+  void setTag(String key, boolean value);
+
+  /**
+   * Annotate the span with a single tag key value pair as a tag regarding the span’s context
+   * (session, environment, system, versioning, etc.).
+   *
+   * @param key the key of the tag
+   * @param value the value of the tag
+   */
+  void setTag(String key, int value);
+
+  /**
+   * Annotate the span with a single tag key value pair as a tag regarding the span’s context
+   * (session, environment, system, versioning, etc.).
+   *
+   * @param key the key of the tag
+   * @param value the value of the tag
+   */
+  void setTag(String key, long value);
+
+  /**
+   * Annotate the span with a single tag key value pair as a tag regarding the span’s context
+   * (session, environment, system, versioning, etc.).
+   *
+   * @param key the key of the tag
+   * @param value the value of the tag
+   */
+  void setTag(String key, double value);
+
+  /**
+   * Annotate the span to indicate that an error occurred
+   *
+   * @param error whether an error occurred
+   */
+  void setError(boolean error);
+
+  /**
+   * Annotate the span with an error message
+   *
+   * @param errorMessage the message of the error
+   */
+  void setErrorMessage(String errorMessage);
+
+  /**
+   * Annotate the span with a throwable
+   *
+   * @param throwable the errored throwable
+   */
+  void addThrowable(Throwable throwable);
+
+  /** Finishes (closes) a span */
+  void finish();
+}

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

@@ -0,0 +1,61 @@
+package datadog.trace.api.llmobs.noop;
+
+import datadog.trace.api.llmobs.LLMObsSpan;
+import java.util.List;
+import java.util.Map;
+
+public class NoOpLLMObsSpan implements LLMObsSpan {
+  public static final LLMObsSpan INSTANCE = new NoOpLLMObsSpan();
+
+  @Override
+  public void annotateIO(
+      List<Map<String, Object>> inputData, List<Map<String, Object>> outputData) {}
+
+  @Override
+  public void annotateIO(String inputData, String outputData) {}
+
+  @Override
+  public void setMetadata(Map<String, Object> metadata) {}
+
+  @Override
+  public void setMetrics(Map<String, Number> metrics) {}
+
+  @Override
+  public void setMetric(CharSequence key, int value) {}
+
+  @Override
+  public void setMetric(CharSequence key, long value) {}
+
+  @Override
+  public void setMetric(CharSequence key, double value) {}
+
+  @Override
+  public void setTags(Map<String, Object> tags) {}
+
+  @Override
+  public void setTag(String key, String value) {}
+
+  @Override
+  public void setTag(String key, boolean value) {}
+
+  @Override
+  public void setTag(String key, int value) {}
+
+  @Override
+  public void setTag(String key, long value) {}
+
+  @Override
+  public void setTag(String key, double value) {}
+
+  @Override
+  public void setError(boolean error) {}
+
+  @Override
+  public void setErrorMessage(String errorMessage) {}
+
+  @Override
+  public void addThrowable(Throwable throwable) {}
+
+  @Override
+  public void finish() {}
+}

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;
+  }
+}