トレース分析¶

ローカルエクスペリメントダッシュボードのトレースページでは、トレース分析コントロールがトレースをコーディングエージェントに渡します。コーディングエージェントはエージェントの動作を報告し、誤りを指摘して、エージェントのプロンプトやコードに対する修正案を提案またはテストできます。 これらのコントロールは、分析可能な各トレースのステータスバッジの横にある✨アイコン、開いているトレースの上部にあるトレースを分析ボタン、およびページ上の分析可能なすべてのトレースをまとめて分析するツールバー内のトレースを分析ボタンの3か所に表示されます。

トレースとは、エージェントが処理した1つのリクエストの記録であり、LLMの呼び出し、ツールの呼び出し、およびその他のステップのスパンで構成されています。 トレースページには、エージェントや実行を問わず、--entity-idを指定してdr xpに渡したユースケースまたはデプロイへエクスポートされたトレースが、1行に1件ずつ一覧表示されます。 実行軌跡とは、トレースのうちLLM呼び出しの部分を指し、Tensileによって完全に記録されるため、コーディングエージェントはすべてのプロンプトと回答を確認することができます。 ✨のないトレースは、LLMの呼び出しが記録されていない実行（Tensileを用いた計装が行われていないエージェント、サポートされていないLLMクライアント、またはLLMの呼び出しを一切行わなかったトレース）によって生成されたものです。

分析は、Tensileを用いて計装されたエージェントによって記録されたトレースを対象に行われます。エージェントが行うすべてのLLM呼び出しは、送受信されたままの状態でDataRobotのトレースに保存されます。 コントロールをクリックすると、その記録が実行軌跡として取得され、TensileエージェントスキルがインストールされたOpenCodeセッションが開始されます。そして、確認して送信できるように/tensileプロンプトが事前に入力されます。

For installation, GUI access, and port configuration, see the DataRobot experimentation plugin landing page. トレースページ自体については、ローカルトレースを参照してください。

仕組み¶

トレース分析は、以下の3つのコンポーネントを結びつけます。

トレース上の✨またはトレースを分析をクリックすると、dr xpは起動元のディレクトリで以下を実行します。

1. Tensileプロジェクトを準備します。 tensile checkを実行し、必要に応じてtensile init --refresh --agent opencodeを実行します。 これにより、.tensile/config.yamlが作成され、.opencode/skills/の下にTensileのエージェントスキルがインストールされて、両方が.gitignoreに追加されます。 最初にクリックされるまでは、何も書き込まれません。
2. 実行軌跡をプルします。 dr xpがすでに保持しているエンティティ、エンドポイント、およびトークンを使用して、トレースに対してtensile trace pullを実行します。 結果は.tensile/trajectories/trace-<トレースIDの先頭12文字>.jsonl.gzです。 そのファイルがすでに存在する場合は、再利用されます。 DataRobot上のスパン数がローカルコピーよりも多くなった場合、自動的に更新されます。
3. OpenCodeを開きます。 共有のdr opencode serveプロセスがまだ実行されていない場合はそれを起動し（アシストタブで使用されているものと同じプロセスです）、コンポーザーに/tensile trace-<prefix>が事前に入力された状態で分析ビューを開きます。 プロンプトは送信されないため、まずプロンプトを編集したり、モデルを切り替えたりすることができます。

トレース分析を有効にする¶

トレース分析は、--enable-trace-analysisフラグによって制御されます。 このフラグを指定しない場合、トレース分析コントロールがトレースページに一切表示されず、dr xpは記録された実行軌跡がないかDataRobotを確認せず、tensileを実行またはインストールせず、OpenCodeをオンデマンドで起動することもありません。

エージェントプロジェクトのディレクトリからダッシュボードを起動する際に、このフラグを指定します。

dr xp --enable-trace-analysis --entity-id <USE_CASE_ID> 

Alternatively, set the environment variable before launch:

export DR_EXPERIMENT_ENABLE_TRACE_ANALYSIS=true
dr xp --entity-id <USE_CASE_ID> 

For Agentic Starter projects that use dr run dev or task infra:dev, add the variable to the project root .env file instead. Taskfiles load .env automatically:

# .env (project root)
DR_EXPERIMENT_ENABLE_TRACE_ANALYSIS=true 

トレース分析が有効になっている場合、/api/infoのfeaturesに"trace_analysis"が含まれます。 無効になっている場合、/api/tensile/*のルートでは404が返され、分析ビューはトレースページにリダイレクトされます。

前提条件¶

エージェントの計装¶

トレース分析コントロールは、記録された実行軌跡（LLMの呼び出し1回につき1つのtensile.envelopeログレコード）を含むトレースにのみ表示されます。 これらを記録するには、エージェントがTensileのOpenTelemetryフックをインストールする必要があります。 これらの手順は、ダッシュボードの/tensile/setupでも利用可能です。このページには、トレースを分析のツールチップや、すべての分析エラー状態からリンクされています。

1. エージェントプロジェクトにパッケージを追加します。

   uv add "tensile>=0.12.0" opentelemetry-sdk opentelemetry-exporter-otlp-proto-http 
   

   Agentic Starterテンプレートから構築されたエージェントは、すでにDataRobotへトレースを送信するように設定されています。必要なのは、agent/pyproject.toml内のtensile依存関係のみです。

2. トレースをDataRobotにエクスポートします。 ヘッダーX-DataRobot-Api-Key（APIトークン）およびX-DataRobot-Entity-Id（トレースの送信先：experiment_container-<USE_CASE_ID>またはdeployment-<DEPLOYMENT_ID>）を指定して、トレーサープロバイダーの送信先をhttps://<your-datarobot-host>/otel/v1/tracesに設定します。 または、環境または.envでDATAROBOT_API_TOKEN、DATAROBOT_ENDPOINT、およびDATAROBOT_ENTITY_IDを設定すると、次の手順のフックによってプロバイダーがブートストラップされます。

3. プロバイダーの設定後、最初のLLMクライアントが作成される前に、フックを1回呼び出します。

   import tensile.otel
   
   tensile.otel.install() 
   

4. スパンを発行します。 エンベロープは、LLM呼び出しの実行時にアクティブなスパンに紐付けられます。そのため、各リクエストをルートスパンで囲むか、フレームワークのOpenTelemetry計装を有効にしてください（例：PydanticAIのAgent.instrument_all()）。 スパンがない場合、紐付ける対象がありません。

計装されたエージェントの最小構成は以下のとおりです。

load_dotenv()          # DATAROBOT_* variables
configure_otel()       # tracer provider aimed at DataRobot

import tensile.otel    # after the providers, before any LLM client

tensile.otel.install()

with tracer.start_as_current_span("my-agent.request"):
    client.chat.completions.create(model="azure/gpt-5-mini", messages=[...]) 

キャプチャ対象¶

Tensileのフックは、OpenAI Python SDK（1.x～3.x）またはLiteLLM（1.70～2.0）を介して、/chat/completions、/responses、または/llmgw/chatで終わるパスに対して行われた呼び出しを記録します。 これには、DataRobot LLM Gateway、OpenAI、OpenAI互換サーバー、およびそれらのクライアント上に構築されたフレームワーク（PydanticAI、LangChainのOpenAI統合、datarobot-genai）が含まれます。

キャプチャされないのは、Anthropic SDK、LiteLLM（/v1/messages）を介したAnthropic、およびネイティブのGemini、Bedrock、Vertex SDKです。 これらのトレースには、トレース分析コントロールはありません。 3MBを超えるエンベロープは破棄され、エージェントのログに警告が記録されます。

エンベロープはスパンの7～30秒後に到着するため、終了したばかりのトレースには約30秒以内に✨が表示されます。

トレースの分析¶

1. エージェントプロジェクトのルートから、トレース分析を有効にした状態でダッシュボードを起動し、トレースページを開きます。 トレース分析を有効にするを参照してください。

2. エージェントにリクエストを送信し、トレースが表示されるまで待機します。 実行軌跡が記録されたトレースには、ステータスバッジの横に✨アイコンが表示されます。 トレースを開くと、全画面表示アイコンおよび閉じるアイコンの隣（トレース上部）に、トレースを分析ボタンとして同じコントロールが表示されます。

   

3. ✨またはトレースを分析をクリックします。 ダッシュボードには、プロジェクトの準備、実行軌跡の取得、OpenCodeの起動が行われている間、Tensileの準備、DataRobotからの実行軌跡の取得、およびOpenCodeの起動を行っています…と表示されます。 dr xpの起動後の最初のクリックには数秒かかりますが、その後、安定したトレースをクリックした場合は約1秒で結果が表示されます。

4. OpenCodeコンポーザーに事前入力されているプロンプト（/tensile trace-<prefix>）を確認します。 これを編集してコンテキスト（エージェントが実行することになっていた内容など）を追加するか、そのままにします。

   

5. モデルピッカーに、DataRobot LLM Gatewayモデルではなく、無料プランのOpenCodeモデルが表示された場合は、一度Gatewayモデルを選択してください（Claude Sonnetまたはそれ以上の性能を持つモデルをお勧めします）。 OpenCodeは、後のセッションのために選択内容を記憶します。

6. プロンプトを送信します。 tensileスキルは、インストールを確認し、実行軌跡を一覧表示し、分析セッションを開始し、抽出された実行軌跡を読み取り、エージェントが成功したかどうか、どのツール呼び出しが適切だったか、および発見された誤りについて、ステップごとの評価結果を報告します。

   

7. 会話を続けます。 実行軌跡について追加の質問をしたり、エージェントに問題の是正を依頼したりします。 tensileスキルはtensile-remediateワークフローへとエスカレーションされ、そこでモチーフ（誤りに対するパターン検出器）が生成され、リプレイを用いてベースライン率を測定し、エージェントに適用する前にプロンプトやツールの変更をテストします。 Tensileのスキルと概念を参照してください。

ページ上のすべてのトレースを分析する¶

トレースページのツールバーにあるトレースを分析は、ページ全体を対象とするバージョンです。 この機能は、現在ページに表示されているすべてのキャプチャ済みトレースをプルし（並列処理を行い、既存のファイルを再利用します）、以下の内容で初期化されたOpenCodeセッションを1つ開きます。

/tensile Inspect my recent trajectories. How is the agent performing? 

dr xpではなく、コーディングエージェントが、どの実行軌跡をまとめて分析するかを選択します。 送信前にプロンプトを編集して、別の意図を指定してください（例：「最新の4つ」や「ツールXを呼び出したものすべて」など）。 日付、ステータス、または検索フィルターを使用して、プルするトレースを絞り込むことができます。

ページ上のどのトレースにも記録された実行軌跡がない場合、このボタンは無効になります。 その理由についてはツールチップに説明があり、セットアップガイドへのリンクも表示されます。 トレースが開かれている間は、ツールバーのボタンは非表示になるので、代わりに開いているトレースのトレースを分析ボタンを使用してください。

プルされたすべての実行軌跡ファイルは、最新のステップのタイムスタンプに遡って日付が設定されます。そのため、tensile lsコマンドは、ファイルがプルされた日時ではなく、エージェントが実行された日時を報告し、「最近」という表現は、期待どおりの意味となります。

セッションの再開または再起動¶

トレースの分析ビューに戻ると、最初からやり直すのではなく、そのOpenCodeセッションが再開されます。 実行軌跡とセッションの対応関係は、ブラウザーのローカルストレージに保存されます。 分析ヘッダーにある新しく開始をクリックすると、記憶されているセッションが破棄され、プロンプトが再設定された状態で新しいセッションが開かれます。

どのtensileが実行されるか¶

dr xpは、以下の順序でtensile CLIを検索します。

1. アクティブ化された仮想環境（$VIRTUAL_ENV）。
2. 起動ディレクトリから最大3階層下にある、tensileを含む.venvまたはvenv（例：agent/.venv）。階層が最も浅いものが優先。
3. PATH、次に~/.local/bin、~/.cargo/bin、そして$UV_TOOL_BIN_DIR。
4. dr xpが自身のためにインストールしたコピー。

エージェントプロジェクト独自のコピーが最優先されるため、トレースを取得するバージョンは、そのトレースを記録したバージョンとなります。 また、そのディレクトリはOpenCodeサブプロセスのPATHでも最優先されるため、コーディングエージェント自身のtensileコマンドでも同じバージョンが使用されます。

これらのいずれにもtensileが含まれていない場合、トレースを初めて分析する際に、dr xpはuv tool installを使用してtensile>=0.12.0を、dr xpが所有するディレクトリにインストールします。

インストールには初回で約20～60秒かかります。マシン上にuvがインストールされている必要があり、分析フレームの上部にある注記にその旨が記載されます。 このコピーは自動的にアップグレードされることはありません。再インストールするには、ディレクトリを削除してください。 プロジェクトの仮想環境は、常にこれよりも優先されます。

dr xpによるインストールを一切行わないようにするには、DR_EXPERIMENT_TENSILE_NO_INSTALL=trueを設定してください。 uvがない場合は、自身でtensileをインストールしてください（例：pipx install "tensile>=0.12.0"、またはdr xpを起動する前にアクティブ化した仮想環境内でpip install "tensile>=0.12.0"を実行するなど）。その後、トレースを再度分析してください。

Tensileのスキルと概念¶

tensile initを実行すると、Tensileエージェントのスキルが.opencode/skills/にインストールされます。 トレース分析では、そのうちの2つが使用されます。

分析レポートで使用される主要な概念：

• 実行軌跡。1回のエージェント実行中に発生したすべてのLLMとのやり取りを記録したログ。 各ステップには、LLMに送信されたメッセージとその応答（テキストおよびツール呼び出し）が含まれます。 実行軌跡は、.tensile/trajectories/の下に.jsonl.gzファイルとして保存されます。
• セッション。分析のために1つまたは複数の実行軌跡をグループ化します。 セッションを開始すると、システムプロンプト、ユーザープロンプト、ツール定義、および各実行軌跡の読みやすいサマリーが.tensile/extracted/に抽出され、既存のモチーフに対してスキャンされます。
• モチーフ。特定のクラスのエージェント動作（通常は繰り返し発生する誤り）に対する再利用可能なパターン検出器。 モチーフは注釈（パターンが観察された実行軌跡とステップのペア）を蓄積するので、誤りの発生頻度と修正が有効かどうかを測定できます。
• リプレイ。注釈が付けられたステップまで遡った会話履歴をLLMに再入力し、新たな回答を生成します。 変更を加えた場合と加えていない場合の多数のリプレイ間で検出率を比較することで、是正策を単なる事例報告ではなく、定量的に評価できるようになります。
• 是正。エージェントのシステムプロンプト、ツール定義、スキル、またはコードに対する変更で、実際のエージェントに適用する前にリプレイを用いてテストされたものです。

CLIとスキルの完全なリファレンスについては、PyPI上のTensileパッケージを参照してください。

トレース分析のトラブルシューティング¶

See also¶

• DataRobot experimentation plugin—install, configure, and open the GUI.
• ローカルトレース — トレースページでOpenTelemetryのスパンを確認します。
• Batch agent evaluation—score agent responses on a fixed dataset.
• DataRobot OpenCodeプラグイン — Tensileスキルを実行するコーディングエージェント。
• Implement tracing—add custom spans and attributes.
• PyPI上のTensile — パッケージ、CLIリファレンス、およびスキルの説明。