This product is not supported for your selected
Datadog site. (
).
概要
このページでは、Datadog の Agent Observability Trace Explorer を使用して、LLM アプリケーションのスパンとトレースをクエリする方法について説明します。
スパンとトレースにまたがるクエリ
Agent Observability において、_スパン_は、LLM アプリケーション内の単一の操作を表す作業単位です。_トレース_は、LLM アプリケーションでのリクエスト処理に関与するエンドツーエンドの操作を表し、多くの場合、1 つ以上のネストされたスパンで構成されます。この用語の詳細については、Agent Observability の用語と概念を参照してください。
Agent Observability Trace Explorer で、トレースとスパンのどちらを検索するかを選択します。
- Traces を選択すると、ルートスパンがクエリと一致するトレースを検索できます。
- Spans を選択すると、ネストされた子スパンを含むすべてのスパンを検索できます。
一部の検索語句はトレースにのみ適用されます。例については、トレースレベルのクエリを参照してください。
属性によるクエリ
_スパン属性_は、各スパンに直接付加されるキーと値のペアです。属性は、パフォーマンスメトリクス、リソース識別子、パラメーター値など、スパンの実行に関する詳細を取得します。
属性クエリは @key:value の形式を取ります。すべての属性キーには @ が先頭に付加されます。
| クエリ | 一致 |
|---|
@duration:>5s | 完了までに 5 秒以上かかったスパン |
タグによるクエリ
_スパンタグ_は、スパン、サービス、または環境全体でテレメトリデータをグループ化、セグメント化、および相関付けるために使用されるキーと値のペアです。タグは多くの場合、アプリケーション名、環境、デプロイメントリージョンなどのより広範なコンテキストを示し、効率的な検索と集計を容易にするためにスパンに付加されます。
タグクエリは key:value の形式を取ります。属性キーとは対照的に、タグキーの先頭には @ は付きません。
| クエリ | 一致 |
|---|
ml_app:my_llm_app | アプリケーション名が my_llm_app |
フリーテキストクエリを使用して、入力または出力のペアを持つ任意のスパンで、特定のキーワード、フレーズ、または文字列を検索することもできます。フリーテキスト検索を使用するには、クエリを " で囲みます。
| クエリ | 一致 |
|---|
"what's the weather" | 入力または出力に文字列 what's the weather を含む Agent、ワークフロー、または LLM スパン |
フリーテキストクエリは、スパンの入力または出力の最初の 20,500 文字に制限されています。
演算子
ブール演算子の AND (積集合)、OR (和集合)、および - (差集合) を使用して、複数の検索語を組み合わせることができます。
| クエリ | 一致 |
|---|
@duration:>5s AND -"foo" | 完了までに 5 秒以上かかり、入力または出力に文字列 foo を含まないスパン |
クエリ構文
Agent Observability Trace Explorer は、Datadog の APM Trace Explorer と同じクエリ構文を使用します。ワイルドカード検索、数値の処理、特殊文字のエスケープなど、クエリ構文の詳細については、Trace Explorer のクエリ構文を参照してください。
クエリの例
| クエリ | 一致 |
|---|
@status:error | ステータスが error |
@meta.error.type:"Max turns exceeded" | エラータイプが Max turns exceeded |
@duration:>5s | 完了までに 5 秒以上かかったスパンまたはトレース |
@trace.total_tokens:>=1000 | 合計 1000 トークン以上を消費したトレース |
ml_app:my_llm_app | アプリケーション名が my_llm_app |
"what's the weather" | 入力または出力に文字列 what's the weather を含む Agent、ワークフロー、または LLM スパン |
評価クエリ
@evaluation 属性を使用して、評価の結果でスパンまたはトレースを検索します。
評価
評価の結果によってスパンを検索できます。たとえば、user_mood という名前の評価があり、そのカテゴリ値が happy、sad、tired である場合、次のようなクエリを使用できます: @evaluation.user_mood.value:happy。
| クエリ | 一致 |
|---|
@evaluation.user_satisfaction.value:>5 | user_satisfaction |
@evaluation.user_mood.value:happy | user_mood という評価で happy と評価されたスパンまたはトレース (カテゴリ値は happy、sad、tired |
フィードバッククエリ
@feedback 属性を使用して、エンドユーザーのフィードバックの送信内容に基づいてスパンまたはトレースを検索します。たとえば、ユーザーが user_satisfaction というラベルの下で thumbs_up または thumbs_down というカテゴリ値を使用してフィードバックを送信している場合、次のようなクエリを使用できます: @feedback.user_satisfaction.value:thumbs_down。
| クエリ | 一致 |
|---|
@feedback.user_satisfaction.value:thumbs_down | user_satisfaction |
@feedback.user_comment.assessment:fail | user_comment |
@feedback.user_score.value:<2 | user_score |
@meta 属性を使用して、メタデータ情報によってスパンを検索します。
| クエリ | 一致 |
|---|
@meta.span.kind:llm | スパン llmスパンの種類 |
@meta.model_provider:openai | モデルプロバイダーが OpenAI であるスパンまたはトレース |
@meta.model_name:gpt-4.1 | モデルが GPT-4.1 であるスパンまたはトレース |
インスツルメンテーション中に付加されたカスタムメタデータフィールドによってスパンやトレースをクエリできます。カスタムメタデータフィールドには @meta.metadata.<key> からアクセスできます。
| クエリ | 一致 |
|---|
@meta.metadata.config.debug_mode:false | カスタムメタデータフィールド config.debug_mode が false |
@meta.metadata.job_id:job_14fb81c3 | カスタムメタデータフィールド job_id が job_14fb81c3 |
トレースレベルのクエリ
ネストされたスパンの属性に基づいてトレースを検索するには、@child 属性を使用します。
| クエリ | 一致 |
|---|
@child.@evaluation.hallucination.value:"hallucination found" | ハルシネーションが発生しているサブスパンを持つトレース |
@child.@meta.span.kind:retrieval AND @meta.span.kind:workflow | 検索スパンを含むワークフロートレース |
推定総コスト、LLM 呼び出し数、ツール数などのトレースレベルの情報にアクセスするには、@trace 属性を使用します。
| クエリ | 一致 |
|---|
@trace.llm_calls:>3 | LLM 呼び出しが 3 回を超えるトレース |
@trace.tool_calls:>=4 | ツール呼び出しが 4 回以上のトレース |
@trace.number_of_tools:<5 | 異なるツールを 5 種類未満呼び出すトレース |
参考資料
