dt-obs-genai

AI オブザーバビリティ（GenAI）スキル

DQL を使用して、顧客の GenAI アプリケーションからの AI オブザーバビリティシグナルを分析します。ゴールデンシグナル、LLM シグナル、トークンとコストの分析（使用状況の帰属とプロンプトキャッシュの経済性を含む）、エージェントシグナル（ループや暴走の検出、Smartscape トポロジーを含む）、会話／セッションレベルの分析、ガードレール、評価品質を扱います。

使用する場合

顧客の GenAI アプリケーションに関するオブザーバビリティの質問に、このスキルを使用します。OpenTelemetry GenAI スパン（gen_ai.*）または LLM 評価のビジネスイベントを読み取るものが対象です。トリガーの例：

• 「LLM のレイテンシ」、「モデル別エラー率」
• 「モデル別のトークン使用量」、「トークン処理率／TPM」、「レート制限に達していますか」、「プロバイダーによるスロットリングや 429」
• 「モデルとプロバイダー別のコスト」、「トークン消費を押し上げているのは誰ですか」、「プロンプトキャッシュを利用していますか」
• 「会話あたりのコスト」、「最も高額なセッション」
• 「失敗しているエージェントのツール呼び出し」、「暴走しているエージェントを見つける」
• 「応答の切り詰めやブロック」、「終了理由」
• 「失敗した評価」、「品質スコア」

使用しない場合

Davis CoPilot／MCP テレメトリー（dt-platform）、汎用サービスメトリクス（dt-obs-services）、ログ（dt-obs-logs）、または GenAI 以外の分散トレーシング（dt-obs-tracing）。

質問の例

フォローアップの質問を提案する場合（例：「トピックごとに質問例を 1 つ挙げて」）、すぐに使える以下の標準的な表現を、機能ごとに 1 つ使用してください。提案は単一節にし、「content filter」という表現はそのまま使わず、「ブロックまたは安全フィルターで除外」としてください。長すぎる複文の質問は拒否されることがあります。

• トラフィック、エラー、レイテンシ： 過去 24 時間のモデル別 LLM エラー率と p95 レイテンシを教えてください。
• トークン使用量とコスト： 過去 24 時間のモデルとプロバイダー別に、トークン使用量とコストを内訳表示してください。
• エージェントとツールのアクティビティ： 過去 24 時間に失敗したエージェントのツール呼び出しを表示してください。
• 会話分析： 過去 24 時間の合計トークン使用量が最も多い会話を、上位 10 件表示してください。
• ガードレール： 過去 7 日間にブロックまたは切り詰められた応答はいくつあり、最も影響を受けたモデルはどれですか？
• 評価品質： 過去 24 時間に失敗した評価について、判定者の説明と質問・回答のペアを表示してください。

---

主な機能

ゴールデンシグナル

オブザーバビリティの古典的な 4 つのシグナル、すなわちトラフィック、エラー、レイテンシ、飽和度は、GenAI アプリケーションにも直接適用できます。トラフィックは時間経過に伴うリクエスト処理量です。エラーは span.status_code == "error" となるスパンです。レイテンシは duration フィールド（Grail の duration 値です。数値のミリ秒値にするには、1ms リテラルで割り、duration / 1ms とします）です。飽和度は、1 分あたりの合計トークン処理量（入力トークンと出力トークンの合計）で近似します。

fetch spans, from: now()-24h
| filter isNotNull(gen_ai.request.model)
| summarize total = count(), errors = countIf(span.status_code == "error"), by: {gen_ai.request.model}
| fieldsAdd error_rate_pct = if(total > 0, errors * 100.0 / total, else: 0.0)
| sort error_rate_pct desc

→ トラフィック、レイテンシ、飽和度のクエリ全般： references/golden-signals.md を参照してください。

LLM シグナル

LLM シグナルは、各リクエストを処理したモデルとプロバイダー、呼び出された操作タイプ（chat、execute_tool、invoke_agent、create_agent）、およびトークンの消費方法を示します。これらを使用して、プロバイダーのレイテンシを比較評価し、モデルのパフォーマンスを比較し、モデルとプロバイダーの組み合わせごとのトークン分布を把握できます。

fetch spans, from: now()-24h
| filter isNotNull(gen_ai.request.model)
| summarize p95_ms = percentile(duration, 95) / 1ms, requests = count(), by: {gen_ai.provider.name}
| sort p95_ms desc

→ 最も遅いモデル、モデル別トークン使用量： references/llm-signals.md を参照してください。

コストとトークン

トークンの消費が主なコスト要因です。Dynatrace はすべてのスパンに gen_ai.usage.input_tokens と gen_ai.usage.output_tokens を保存します。保存済みのコストフィールドはありません。推定コストは、トークンの合計に指定したモデルごとの価格を掛けて算出する必要があります。以下のクエリを使用して、支出が最も多いモデルとプロバイダーの組み合わせを特定し、トークン消費の急増を検出します。

fetch spans, from: now()-24h
| filter isNotNull(gen_ai.usage.input_tokens) or isNotNull(gen_ai.usage.output_tokens)
| summarize input_tokens = sum(gen_ai.usage.input_tokens), output_tokens = sum(gen_ai.usage.output_tokens), total_tokens = sum(gen_ai.usage.input_tokens) + sum(gen_ai.usage.output_tokens), by: {gen_ai.provider.name, gen_ai.request.model}
| sort total_tokens desc

→ トークンの急増、コストの推定、最も高額なプロンプト、使用状況の帰属、プロンプトキャッシュの経済性： references/cost-and-tokens.md を参照してください。

エージェントシグナル

GenAI エージェントは、各ツール呼び出し（execute_tool）、エージェントのステップ（invoke_agent）、エージェントの作成（create_agent）ごとにスパンを出力します。エージェントシグナルを使用して、最も頻繁に呼び出されるツールや、失敗しているエージェントを特定できます。どのエージェント、モデル、プロバイダーが存在し、それらがどのようにつながっているかといった構造に関する質問には、スパンをスキャンする代わりに GenAI Smartscape エンティティ（GENAI_AGENT、GENAI_MODEL、GENAI_PROVIDER、GENAI_SERVICE）をクエリしてください。これは機能フラグで制御されるプレビュー機能です。

fetch spans, from: now()-24h
| filter isNotNull(gen_ai.agent.name)
| summarize total = count(), errors = countIf(span.status_code == "error"), by: {gen_ai.agent.name}
| fieldsAdd error_rate_pct = if(total > 0, errors * 100.0 / total, else: 0.0)
| sort errors desc

→ ツールの使用状況、失敗しているエージェント、エージェントステップのレイテンシー、ループ／暴走の検出、Smartscape トポロジー： references/agent-signals.md を参照してください

会話分析

スパン単位およびトレース単位のシグナルは、1 つのリクエストまたは 1 つのターンを測定します。アプリケーションが gen_ai.conversation.id を伝播する場合、スパンをセッション単位に集約できます。会話あたりのコスト、会話の深さ、コストが異常に高い、またはエラーが発生しやすいセッションを把握できます。これは、チャージバックとユーザーが実感する信頼性にとって重要な単位です。

fetch spans, from: now()-24h
| filter isNotNull(gen_ai.conversation.id)
| summarize turns = countDistinct(trace.id), total_tokens = sum(gen_ai.usage.input_tokens) + sum(gen_ai.usage.output_tokens), errors = countIf(span.status_code == "error"), by: {gen_ai.conversation.id}
| sort total_tokens desc

→ 会話あたりのコスト／深さ、セッションのエラー率： references/conversation-analytics.md を参照してください

ガードレール

ガードレールは、スパン上の gen_ai.response.finish_reasons として現れます。content_filter は安全フィルターが出力をブロックまたは編集したことを示し、length はトークン上限で応答が切り詰められたことを示します。また、評価 bizevents 内のプロアクティブな安全性評価器（prompt-injection、pii-leakage、toxicity、bias）としても現れます。これらを使用して、ブロックされた応答や切り詰められた応答を定量化し、LLM 判定による安全性の判定結果と関連付けられます。

fetch spans, from: now()-24h
| filter isNotNull(gen_ai.response.finish_reasons)
| fieldsAdd finish_reason = gen_ai.response.finish_reasons
| expand finish_reason
| summarize calls = count(), by: {finish_reason, gen_ai.request.model}
| sort calls desc

→ ブロック（安全フィルターによる除外）、切り詰め（長さ）、終了理由の内訳： references/guardrails.md を参照してください

評価品質

評価結果は、スパンではなく bizevents として、event.type == "gen_ai.evaluation.result" で記録されます。各評価器は応答ごとに 1 つの bizevent を出力し、スコア、合否ラベル、説明、正確な Q&A の組み合わせを含みます。評価クエリを使用して品質の各側面を監視し、LLM 判定者の推論とともに失敗した応答を明らかにできます。各 bizevent には、評価対象の応答を生成した実行の trace.id も含まれるため、品質上の問題から、その原因となったスパンへと切り替えて調査できます。

fetch bizevents, from: now()-24h
| filter event.type == "gen_ai.evaluation.result"
| filter gen_ai.evaluation.score.label == "fail"
| fields timestamp, gen_ai.evaluation.name, gen_ai.evaluation.score.value, gen_ai.evaluation.explanation, gen_ai.evaluation.input.question, gen_ai.evaluation.input.answer
| sort timestamp desc

→ 品質スコア、失敗した評価、失敗率： references/evaluations.md を参照してください

データがない場合の確認

シグナルクエリが行を返さない場合、「データが見つかりません」と報告してはいけません。まず、アプリケーションが GenAI テレメトリーを送信しているかどうかを確認してください。次の 2 つの存在確認クエリで、どのシグナルファミリーが存在するかを確認できます。

fetch spans, from: now()-24h
| summarize 
    has_genai = countIf(isNotNull(gen_ai.request.model)), 
    has_tokens = countIf(isNotNull(gen_ai.usage.input_tokens) or isNotNull(gen_ai.usage.output_tokens)), 
    has_agents = countIf(isNotNull(gen_ai.agent.name)), 
    has_tools = countIf(gen_ai.operation.name == "execute_tool"), 
    has_conversation = countIf(isNotNull(gen_ai.conversation.id)), 
    has_finish_reason = countIf(isNotNull(gen_ai.response.finish_reasons)), 
    has_cached_tokens = countIf(isNotNull(gen_ai.usage.cache_read.input_tokens) or isNotNull(gen_ai.usage.cache_creation.input_tokens)),
    total = count()
    

fetch bizevents, from: now()-24h
| filter event.type == "gen_ai.evaluation.result"
| summarize evals = count()

has_genai がゼロの場合は、「データが見つかりません」ではなく、アプリケーションではまだ AI Observability の計装が行われていないようだと報告してください。has_genai がゼロ以外で、特定のファミリー（has_tokens、has_agents、has_tools、has_conversation、has_finish_reason、has_cached_tokens、evals）がゼロの場合は、そのシグナルタイプのみが欠落しています。たとえば、has_conversation == 0 は、アプリが会話 ID を伝播していないためセッション単位の分析を利用できないことを意味し、has_cached_tokens == 0 はプロンプトキャッシュのテレメトリーが報告されていないことを意味します。これらのオプションのファミリーでは、プロバイダー／SDK によって属性名が異なる場合があります。欠落していると報告する前に確認してください。

---

エージェントへの指示

まず実行し、後から調整する

ユーザーが分析を依頼した場合は、妥当なデフォルト値を用いてすぐに進めます。合理的に仮定できるパラメーター値は、ユーザーに尋ねないでください。

指定がない場合のデフォルト値：

パラメーター	デフォルト値	理由
期間	過去 24 時間（from: now()-24h）	狭すぎず、運用上の丸一日をカバーできます
モデルの範囲	すべてのモデル（モデルフィルターなし）	全体像を示し、結果を見てからユーザーが範囲を絞り込めます
プロバイダーの範囲	すべてのプロバイダー	モデルの範囲と同じ理由です
トークンのしきい値	なし	すべてを表示し、データから外れ値を見つけられるようにします

例外 — コスト価格。 モデルごとの価格は、デフォルト値を設定できない唯一の入力です（データにコストフィールドがありません）。USD の推定前にユーザーに価格を尋ねてください。記憶にある価格を使用してはいけません。cost-and-tokens.md を参照してください。

空の結果に関するルール

シグナルクエリの結果が 0 行の場合は、応答する前に上記の 空の結果の確認 機能にある 2 つの有無確認を実行してください。「データが見つかりませんでした」と返してはいけません。 has_genai が 0 の場合は、アプリケーションが AI Observability 向けにまだ計装されていないようだと報告してください。特定のファミリーだけが 0 の場合は、どのシグナルタイプが欠けているかを伝えてください。

対象範囲の境界

このスキルの対象は、顧客向け GenAI アプリケーションの AI Observability シグナルのみです。 製品ドキュメントや設定方法に関する質問（例：「Dynatrace OTLP エンドポイントを設定するにはどうすればよいですか？」）は ask-dynatrace-docs に回してください。このスキルには、製品の設定方法に関する説明は含まれていません。

ユーザーの意図を理解する

ユーザーのリクエストやプロンプトスターターの表現を、機能に対応付けます：

ユーザーのリクエスト／プロンプトスターター	機能	参照ファイル
「AI オブザーバビリティのシグナルを理解する」	すべてのシグナルカテゴリの概要	この SKILL.md
「LLM のレイテンシとエラーを分析する」、「LLM のエラー」、「モデル別のエラー率」	ゴールデンシグナル	golden-signals.md
「現在、最も遅いモデルは？」、「プロバイダー間のレイテンシを比較する」	LLM シグナル	llm-signals.md
「モデル別のトークン使用量を表示する」、「トークン使用量の急増」	コストとトークン	cost-and-tokens.md
「モデルとプロバイダー別にコストを内訳表示する」、「最もコストが高いプロンプトは？」	コストとトークン	cost-and-tokens.md
「失敗したエージェントの実行をトレースする」、「失敗したツール呼び出しを表示する」	エージェントシグナル	agent-signals.md
「レイテンシ別にエージェントのステップを内訳表示する」	エージェントシグナル	agent-signals.md
「エージェントのトポロジーをマッピングする」、「このエージェントが使用するモデルは？」、「GenAI エージェント／モデル／プロバイダーを一覧表示する」	エージェントシグナル（Smartscape）	agent-signals.md
「エージェントがループにはまっていますか？」、「暴走しているエージェントを見つける」、「トークン急増の原因は？」	エージェントシグナル（ループ）	agent-signals.md
「会話あたりのコスト」、「最もコストが高いセッション」、「会話はどのくらい深く続いていますか？」	会話分析	conversation-analytics.md
「エージェントの軌跡をつなぎ合わせる」、「セッション ID でフィルタリングする」、「セッション全体のトレースを関連付ける」	会話分析	conversation-analytics.md
「応答がブロック／フィルタリングされる頻度は？」、「応答が途中で切り詰められていますか？」、「終了理由」	ガードレール	guardrails.md
「アプリケーション／ユーザー／テナント別のコスト」、「トークン支出を増やしているのは誰ですか？」	コストとトークン（アトリビューション）	cost-and-tokens.md
「プロンプトキャッシュは利用されていますか？」、「キャッシュヒット率」、「キャッシュによる節約」	コストとトークン（キャッシュ）	cost-and-tokens.md
「評価品質スコアを要約する」、「スコアの低い応答を表示する」、「失敗した評価を表示する」	評価品質	evaluations.md
「不足しているシグナルは？」、「データがないのはなぜですか？」	空状態の確認	この SKILL.md

---

一般的なワークフロー

ワークフロー：コスト調査

1. Run token usage by model and provider (cost-and-tokens.md → "Token usage by model and provider")
2. Identify the top model-provider combinations by total_tokens
3. For the top offenders, run token usage spikes to check for abnormal time windows
4. Use the cost-estimation template in "Most expensive prompts and models" to estimate USD spend — ask the user for per-model prices first (see "Exception — cost prices" under Agent Instructions)
5. Check for prompt-size outliers: high input_tokens / output_tokens ratio indicates large context windows
6. Attribute spend to a consumer (cost-and-tokens.md → "Usage attribution") and check whether prompt caching is enabled and effective (cost-and-tokens.md → "Prompt caching economics")

ワークフロー：トークン急増／暴走の調査

1. Run token usage spikes (cost-and-tokens.md → "Token usage spikes") to find the abnormal time window
2. Within that window, run repeated-tool-calls and runaway-turn queries (agent-signals.md → "Agent loops and runaway detection")
3. For a flagged trace.id, open the trace to see what the agent looped on
4. If conversation ids are present, re-run the loop query grouped by gen_ai.conversation.id to catch cross-turn loops (conversation-analytics.md)

ワークフロー：失敗したエージェントの実行

1. Run failing agent activity query (agent-signals.md → "Failing agent activity")
2. Sort by errors desc to find the most error-prone agent
3. Take the trace.id from a failing span and open in Dynatrace distributed-tracing view
4. Check agent steps by latency (agent-signals.md) to see which operation type is slowest

ワークフロー：ガードレールと安全性のレビュー

1. Run the guardrails presence check (guardrails.md) to confirm finish reasons are recorded
2. Run the finish-reason breakdown, then the blocked (content_filter) and truncated (length) queries
3. Correlate safety-filter spikes with the prompt-injection evaluator and truncation with answer-completeness failures (evaluations.md)
4. For a specific block or failure, take the trace.id and pivot to the originating spans (evaluations.md → "Correlating evaluations to traces")

ワークフロー：評価のレビュー

1. Run evaluation quality scores (evaluations.md → "Evaluation quality scores") to rank evaluators by avg_score asc
2. Focus on the lowest-scoring evaluator
3. Run failed evaluations (evaluations.md → "Failed evaluations") to surface the exact Q&A pairs and LLM judge explanations
4. Use the "Fail rate by evaluator" query to see how many responses fail each evaluator and the share of total evaluations
5. To root-cause a specific failure, take its trace.id and pivot to the originating spans (evaluations.md → "Correlating evaluations to traces")

---

参照資料

• references/golden-signals.md — トラフィック、エラー、レイテンシ、飽和度
• references/llm-signals.md — 最も遅いモデル、プロバイダーのレイテンシ、モデル別のトークン使用量
• references/cost-and-tokens.md — トークン使用量、急増、コスト見積もりテンプレート、使用量のアトリビューション、プロンプトキャッシュの経済性
• references/agent-signals.md — ツールの使用状況、失敗したエージェント、ステップのレイテンシ、ループ／暴走の検出、Smartscape のエージェントトポロジー（プレビュー）
• references/conversation-analytics.md — セッション単位のコスト、深さ、エラー率（gen_ai.conversation.id）
• references/guardrails.md — 終了理由による、ブロックされた（安全フィルター適用済み）応答と切り詰められた（長さによる）応答の確認
• references/evaluations.md — 品質スコア、失敗した評価、失敗率、トレース相関（bizevents）