SDK には、入力、出力、メトリクス、メタデータを使用してスパンにアノテーションを付けるためのいくつかのメソッドが用意されています。
入力と出力のアノテーション付け
LLMObsSpan インターフェイスの annotateIO() メンバーメソッドを使用して、LLMObsSpan に構造化された入力および出力データを追加します。ここにはオプションの引数と LLM メッセージオブジェクトが含まれます。
引数
引数が null または空の場合、処理は何も行われません。たとえば、inputData が空でない文字列で、outputData が null の場合、inputData のみが記録されます。
inputData
オプション - 文字列 または リスト<LLMObs.LLMMessage>
文字列 (非 LLM スパン用)、または LLM スパン用の LLMObs.LLMMessage のリスト。
outputData
オプション - 文字列 または リスト<LLMObs.LLMMessage>
文字列 (非 LLM スパン用)、または LLM スパン用の LLMObs.LLMMessage のリスト。
LLM メッセージ
LLM スパンは、LLMObs.LLMMessage オブジェクトを使用して LLM メッセージでアノテーションを付ける必要があります。
LLMObs.LLMMessage オブジェクトは、次の引数を指定して LLMObs.LLMMessage.from() を呼び出すことでインスタンス化できます。
role
必須 - 文字列
メッセージの作成者の役割を記述する文字列。
content
必須 - 文字列
メッセージの内容を含む文字列。
例
import datadog.trace.api.llmobs.LLMObs;
public class MyJavaClass {
public String invokeChat(String userInput) {
LLMObsSpan llmSpan = LLMObs.startLLMSpan("my-llm-span-name", "my-llm-model", "my-company", "maybe-ml-app-override", "session-141");
String systemMessage = "You are a helpful assistant";
Response chatResponse = ... // user application logic to invoke LLM
llmSpan.annotateIO(
Arrays.asList(
LLMObs.LLMMessage.from("user", userInput),
LLMObs.LLMMessage.from("system", systemMessage)
),
Arrays.asList(
LLMObs.LLMMessage.from(chatResponse.role, chatResponse.content)
)
);
llmSpan.finish();
return chatResponse;
}
}
メトリクスの追加
メトリクスの一括追加
LLMObsSpan インターフェイスの setMetrics() メンバーメソッドは、複数のメトリクスを一括でアタッチするための次の引数を受け付けます。
引数
metrics
必須 - Map<string, number>
スパンで記述された操作に関連するメトリクスを記録するためにユーザーが追加できる JSON のシリアライズ可能なキーと数値のマップ (たとえば、input_tokens、output_tokens、total_tokens)。
単一のメトリクスを追加
LLMObsSpan インターフェイスの setMetric() メンバーメソッドは、単一のメトリクスをアタッチするための次の引数を受け付けます。
引数
key
必須 - CharSequence
メトリクスの名前。
value
必須 - int、 long、または double
メトリクスの値。
例
import datadog.trace.api.llmobs.LLMObs;
public class MyJavaClass {
public String invokeChat(String userInput) {
LLMObsSpan llmSpan = LLMObs.startLLMSpan("my-llm-span-name", "my-llm-model", "my-company", "maybe-ml-app-override", "session-141");
String chatResponse = ... // user application logic to invoke LLM
llmSpan.setMetrics(Map.of(
"input_tokens", 617,
"output_tokens", 338,
"time_per_output_token", 0.1773
));
llmSpan.setMetric("total_tokens", 955);
llmSpan.setMetric("time_to_first_token", 0.23);
llmSpan.finish();
return chatResponse;
}
}
タグの追加
タグの詳細については、タグの概要 を参照してください。
タグの一括追加
LLMObsSpan インターフェイスの setTags() メンバーメソッドは、複数のタグを一括でアタッチするための次の引数を受け付けます。
引数
notification
必須 - Map<string, object>
スパンのコンテキストを説明するためにユーザーがタグとして追加できる JSON のシリアライズ可能なキーと値のペアのマップ (たとえば、session、environment、system、またはversion)。
単一のタグを追加
LLMObsSpan インターフェイスの setTag() メンバーメソッドは、単一のタグをアタッチするための次の引数を受け付けます。
引数
key
必須 - 文字列
タグのキー。
value
必須 - int、long、double、boolean、または_String_
タグの値。
例
import datadog.trace.api.llmobs.LLMObs;
public class MyJavaClass {
public String invokeChat(String userInput) {
LLMObsSpan llmSpan = LLMObs.startLLMSpan("my-llm-span-name", "my-llm-model", "my-company", "maybe-ml-app-override", "session-141");
String chatResponse = ... // user application logic to invoke LLM
llmSpan.setTags(Map.of(
"chat_source", "web",
"users_in_chat", 3
));
llmSpan.setTag("is_premium_user", true);
llmSpan.finish();
return chatResponse;
}
}
エラーのアノテーション付け
Throwable の追加 (推奨)
LLMObsSpan インターフェイスの addThrowable() メンバーメソッドは、スタックトレースを持つ Throwable をアタッチするための次の引数を受け付けます。
引数
throwable
必須 - Throwable
発生した Throwable/Exception。
エラーメッセージの追加
LLMObsSpan インターフェイスの setErrorMessage() メンバーメソッドは、エラー文字列をアタッチするための次の引数を受け付けます。
引数
errorMessage
必須 - 文字列
エラーメッセージ。
エラーフラグの設定
LLMObsSpan インターフェイスの setError() メンバーメソッドは、操作にエラーがあることを示すための次の引数を受け付けます。
引数
error
必須 - boolean
true の場合、スパンでエラーが発生しています。
例
import datadog.trace.api.llmobs.LLMObs;
public class MyJavaClass {
public String invokeChat(String userInput) {
LLMObsSpan llmSpan = LLMObs.startLLMSpan("my-llm-span-name", "my-llm-model", "my-company", "maybe-ml-app-override", "session-141");
String chatResponse = "N/A";
try {
chatResponse = ... // user application logic to invoke LLM
} catch (Exception e) {
llmSpan.addThrowable(e);
throw new RuntimeException(e);
} finally {
llmSpan.finish();
}
return chatResponse;
}
}
メタデータのアノテーション付け
LLMObsSpan インターフェイスの setMetadata() メンバーメソッドは、次の引数を受け付けます。
metadata
必須 - Map<string, object>
スパンによって記述された入力または出力操作に関連するメタデータを含む、JSON のシリアライズ可能なキーと値のペアのマップです。
例
import datadog.trace.api.llmobs.LLMObs;
public class MyJavaClass {
public String invokeChat(String userInput) {
LLMObsSpan llmSpan = LLMObs.startLLMSpan("my-llm-span-name", "my-llm-model", "my-company", "maybe-ml-app-override", "session-141");
llmSpan.setMetadata(
Map.of(
"temperature", 0.5,
"is_premium_member", true,
"class", "e1"
)
);
String chatResponse = ... // user application logic to invoke LLM
return chatResponse;
}
}
