Langfuse経由でwatsonx OrchestrateのAIエージェントをIBM Instanaで監視する

はじめに

IBM watsonx Orchestrate（WXO） は、LLMベースのAIエージェントを構築・実行するためのプラットフォームです。WXOのADK（Developer Edition）では、Langfuse というLLMオブザーバビリティツールがバンドルされており、エージェントの会話トレースやLLMの呼び出しログを自動収集します。

しかし、企業の監視基盤として IBM Instana を利用しているケースでは、LangfuseのデータをそのままInstanaに連携したいというニーズがあります。本記事では、OSSツール Langfuse2Instana を使って、LangfuseからInstanaへOTLPでトレース・メトリクスを転送する方法を解説します。

WXO ADK の SaaS版（IBM Cloud上のインスタンス）と OnPrem版 両方に対応しています。

---

アーキテクチャ概要

┌─────────────────────────────────────────────────────────────────┐
│  Windows Server 2022 (WXO ADK ホスト)                           │
│                                                                 │
│  ┌──────────────────────────┐                                   │
│  │  WXO ADK Server          │  orchestrate server start -l      │
│  │  （AIエージェント実行）    │  --with-langfuse                  │
│  └──────────┬───────────────┘                                   │
│             │ トレース自動送信                                    │
│             ▼                                                   │
│  ┌──────────────────────────┐                                   │
│  │  Langfuse (localhost:3010)│  SaaS: cloud.langfuse.com        │
│  │  LLMトレース収集          │  OnPrem: 社内URLも可              │
│  └──────────┬───────────────┘                                   │
│             │ REST API ポーリング（15秒毎）                       │
│             ▼                                                   │
│  ┌──────────────────────────┐                                   │
│  │  Langfuse2Instana        │  ← 本記事のツール                  │
│  │  Fetcher→Converter→      │                                   │
│  │  OTLP Exporter           │                                   │
│  └──────────┬───────────────┘                                   │
│             │ OTLP/HTTPS (protobuf)                             │
└─────────────┼───────────────────────────────────────────────────┘
              ▼
  ┌─────────────────────────────┐
  │  IBM Instana                │
  │  otlp-XXXX-saas.instana.io│
  │  トレース・メトリクス表示    │
  └─────────────────────────────┘

データフローのポイント

• WXO ADKを --with-langfuse オプションで起動すると、エージェントのトレースはローカルLangfuseに送られる（クラウドのWXOトレースストアには書かれない）
• Langfuse2InstanaはLangfuseのREST APIを観測（observation）の開始時刻でポーリングし、新規・追記された観測を含むトレースをOTLP形式に変換してInstanaへ転送する（既存の長寿命トレースに後から追記された観測も取りこぼさない）
• SQLiteで観測ID単位の重複排除を行い、再起動後も二重送信せず、メトリクスの二重計上も防ぐ

---

前提条件

コンポーネント	バージョン/要件
OS	Windows Server 2022（Linux/macOSも動作可）
Python	3.10以上（3.12推奨）
WXO ADK	Developer Edition（--with-langfuseで起動）
Langfuse	v3.x（SaaS / OnPrem / ADK同梱版）
IBM Instana	SaaS または OnPrem（OTLPインジェスション有効）
Instana Agent Key	OTLP送信用のインジェストキー

---

LangfuseのAPI Keyを取得する

Langfuseの管理画面からAPIキーを取得します。WXO ADKのローカルLangfuseの場合は http://localhost:3010 にアクセスします。

1. Langfuse UI にログイン
2. 左メニュー → Settings → API Keys
3. Create new API keys をクリック
4. Secret Key と Public Key をコピーして保存する

Langfuse API Keys画面の例

▲ Langfuse Project Settings → API Keys 画面。Secret Key と Public Key をここで取得する。

Secret Key は作成時にしか表示されません。必ず安全な場所に保存してください。
.env 欄に表示される LANGFUSE_BASE_URL もメモしておきましょう（OnPremの場合は社内URLになります）。

---

インストール手順（Windows Server 2022）

Step 1 — Pythonのインストール

Python公式サイトからインストーラーをダウンロード。インストール時に 「Add python.exe to PATH」 にチェックを入れること。

python --version
# Python 3.12.x が表示されれば OK

Step 2 — プロジェクトの取得

git clone https://github.com/GSSJacky/Langfuse2Instana.git C:\langfuse2instana
cd C:\langfuse2instana

Step 3 — 仮想環境の作成とインストール

cd C:\langfuse2instana
python -m venv venv
.\venv\Scripts\Activate.ps1   # PowerShellの場合
# または: venv\Scripts\activate.bat  (cmd.exeの場合)

pip install .

# インストール確認
.\venv\Scripts\langfuse2instana.exe --help

⚠️ 必ずプロジェクトディレクトリで python -m venv venv を実行してから pip install . してください。
別の場所から venv をコピーすると、.exe 内に古いPythonパスが埋め込まれ、以下のエラーが発生します：

Fatal error in launcher: Unable to create process using '...\python.exe'

この場合は venv フォルダを削除して最初からやり直してください。

Activate.ps1 が実行ポリシーでブロックされる場合：
Set-ExecutionPolicy -Scope CurrentUser RemoteSigned

---

設定ファイルの作成

⚠️ Windows エンコーディングの注意： メモ帳で config.yaml を保存すると cp1252 エンコーディングになり、YAML解析エラーが発生します。必ず以下のPowerShell方式でUTF-8として書き込んでください。

WXO ADK（ローカルLangfuse）の場合

$config = @"
sources:
  - name: "wxo-adk"
    langfuse_host: "http://localhost:3010"
    public_key: "pk-lf-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
    secret_key: "sk-lf-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
    poll_interval_seconds: 15
    lookback_minutes: 60
    service_name: "wxo-adk-test"
    environment: "production"
    max_traces_per_poll: 1000
    include_io: false

export:
  endpoint: "https://otlp-orange-saas.instana.io"
  protocol: "http/protobuf"
  headers:
    x-instana-key: "your-instana-agent-key"
  insecure: false
  timeout_seconds: 30
  max_retries: 3

state:
  db_path: "C:\\langfuse2instana\\state.db"
  retention_days: 7

metrics:
  enabled: true

log_level: "INFO"
"@
[System.IO.File]::WriteAllText(
    "C:\langfuse2instana\config.yaml",
    $config,
    [System.Text.Encoding]::UTF8
)

Langfuse SaaS（cloud.langfuse.com）の場合

sources:
  - name: "saas-langfuse"
    langfuse_host: "https://cloud.langfuse.com"
    public_key: "${LANGFUSE_PUBLIC_KEY}"    # 環境変数参照も可能
    secret_key: "${LANGFUSE_SECRET_KEY}"
    poll_interval_seconds: 60
    lookback_minutes: 5
    service_name: "wxo-saas-app"
    environment: "production"

OnPrem Langfuse（社内URL）の場合

sources:
  - name: "onprem-langfuse"
    langfuse_host: "https://langfuse.internal.company.com"
    public_key: "pk-lf-xxx"
    secret_key: "sk-lf-xxx"
    poll_interval_seconds: 30
    service_name: "wxo-onprem-app"

上記の SaaS / OnPrem の例は sources: 部分のみの抜粋です。export: / state: / metrics: ブロックは「WXO ADK（ローカルLangfuse）の場合」と同じものを付けてください。

複数ソースを同時監視

sources:
  - name: "wxo-local"
    langfuse_host: "http://localhost:3010"
    public_key: "pk-lf-..."
    secret_key: "sk-lf-..."
    service_name: "wxo-adk"

  - name: "wxo-saas"
    langfuse_host: "https://cloud.langfuse.com"
    public_key: "${LANGFUSE_SAAS_PUBLIC_KEY}"
    secret_key: "${LANGFUSE_SAAS_SECRET_KEY}"
    service_name: "wxo-cloud"

export:
  endpoint: "https://otlp-orange-saas.instana.io"
  headers:
    x-instana-key: "your-instana-agent-key"

---

実行と動作確認

フォアグラウンドで実行（テスト用）

cd C:\langfuse2instana
.\venv\Scripts\langfuse2instana.exe -c C:\langfuse2instana\config.yaml

正常起動時のログ例：

============================================================
Langfuse → OTLP/Instana Conversion Service
============================================================
Sources: 1
  - wxo-adk: http://localhost:3010 (every 30s)
Export: https://otlp-orange-saas.instana.io (http/protobuf)
Metrics: enabled
Webhook: disabled
============================================================
2026-06-29 07:00:00 INFO [langfuse2instana.main] [wxo-adk] Polling observations from 2026-06-29T12:00:00.000Z to 2026-06-29T13:00:00.000Z
2026-06-29 07:00:01 INFO [langfuse2instana.langfuse_client] [wxo-adk] Fetched 5 observations from 2026-06-29T12:00:00.000Z to 2026-06-29T13:00:00.000Z
2026-06-29 07:00:01 INFO [langfuse2instana.main] [wxo-adk] Found 5 new observations across 1 traces to export
2026-06-29 07:00:01 INFO [langfuse2instana.main] [wxo-adk] Exported trace f7c1bd874da5e709d... (5 new obs)
2026-06-29 07:00:01 INFO [langfuse2instana.main] [wxo-adk] Exported metrics for trace f7c1bd874da5e709d...
2026-06-29 07:00:01 INFO [langfuse2instana.main] [wxo-adk] Poll complete: 1/1 traces (re-)exported

WXOでエージェントを動かしてトレースを生成する

WXO ADKのChat画面（http://localhost:4321）を開き、エージェントに質問を投げかけます。

▲ WXO ADK の Chat 画面。ユーザーが「Summarize the capabilities of watsonx Orchestrate」と入力し、AskOrchestrate エージェントが回答。この会話が Langfuse にトレースとして記録される。

LangfuseでTraceが記録されているか確認

Langfuse UI（http://localhost:3010）→ Tracing → Traces タブに POST /orchestrate/runs が表示されます。

▲ Langfuse Tracing → Traces タブ。POST /orchestrate/runs が複数記録されている。

langfuse_observations.png

▲ Langfuse Tracing → Observations タブ。answer, WatsonxChatModel.chat, agent, LangGraph など WXO 内部の span ツリーが可視化されている。

Instana UIでトレース・メトリクスを確認する

トレースの確認

1. Instana UI → 分析（Analytics）→ 呼び出し（Calls）
2. フィルター: 宛先 service.name = wxo-adk-test
3. ⚠️ 「内部呼び出しの表示」にチェック を入れると、LangGraph・agent・answer などの子 span も表示される

▲ Instana 分析 → アプリケーション → 呼び出し画面。wxo-adk-test サービスの POST /orchestrate/runs が一覧表示されている。

▲ Instana 分析 → 呼び出し画面。POST /orchestrate/runs のトレースが表示され、LangGraph（5808ms）、agent（5743ms）、WatsonxChatModel.chat（5707ms）のスパンツリーが可視化されている。右パネルには langfuse.session.id, agent.id などのカスタム属性も確認できる。

サービスサマリーの確認

Instana UI → アプリケーション（Applications） → wxo-adk-test-app を選択すると、サービス全体の呼び出し数・エラー率・待ち時間が可視化されます。

▲ Instana Application サマリー画面。wxo-adk-test サービスの呼び出し（合計15件）、エラー率 0.00%、平均待ち時間 70ms が表示されている。

カスタムメトリクスの確認

LLMのトークン使用量やコストなどのメトリクスは、Custom Dashboards で確認します。

メトリクス名	種別	説明
gen_ai.client.token.usage	Counter（Delta Sum）	モデル別・トークン種別（input/output）の使用量
gen_ai.client.cost	Counter（Delta Sum）	モデル別コスト（USD）
gen_ai.client.operation.duration	Gauge	生成（GENERATION）ごとのレイテンシ（ms）

これらのOTLPメトリクスはServiceサマリー画面には表示されません。Custom Dashboard での確認が必要です。

SpanKindとInstanaサービス認識の仕組み

Instanaの Applications / Services は、entry span（SERVER または CONSUMER） を基点にサービスを構築します。OpenTelemetryのスパンが全て INTERNAL の場合、Instanaはentry callとして認識できず、Serviceダッシュボードが作成されません。

Langfuse2Instanaでは以下のSpanKindマッピングを実装しています：

Observation種別	SpanKind	Instanaでの扱い
単一の自然ルートspan	SERVER ✅	entry call → Serviceダッシュボード作成
複数のトップレベルspanがある場合	合成ルート SERVER + 子は INTERNAL	合成ルートがentry call
GENERATION（LLM呼び出し）	CLIENT	exit/remote call（LLMプロバイダーへ）
その他のSPAN/EVENT	INTERNAL	内部処理（「内部呼び出しの表示」で確認）

「内部呼び出しの表示」が必要な理由：
LangGraph・agent・answer などの内部処理 span は INTERNAL です。これは OpenTelemetry の正しいセマンティクスです。Instanaのデフォルトビューはentry spanのみ表示するため、内部spanを見るには「内部呼び出しの表示」チェックボックスをオンにする必要があります。

SaaS版とOnPrem版の違い

項目	SaaS版	OnPrem版（CPD/Zen）	ADK開発者版
LangfuseのURL	https://cloud.langfuse.com	社内URL	http://localhost:3010
API Key取得	cloud.langfuse.com → Settings	社内Langfuse → Settings	localhost:3010 → Settings
TLS検証	insecure: false	自己署名証明書の場合 insecure: true	insecure: false

Windowsサービスとして常駐させる（NSSM）

本番環境では、Langfuse2InstanaをWindowsサービスとして登録することで、ログオフ後も動作し続け、障害時に自動再起動されます。

NSSMのインストール

winget install NSSM.NSSM

Machine スコープで環境変数を設定

# Windowsサービスはユーザー環境変数を継承しないためMachineスコープで設定
[Environment]::SetEnvironmentVariable("LANGFUSE_PUBLIC_KEY", "pk-lf-...", "Machine")
[Environment]::SetEnvironmentVariable("LANGFUSE_SECRET_KEY", "sk-lf-...", "Machine")
[Environment]::SetEnvironmentVariable("INSTANA_KEY", "your-instana-key", "Machine")

サービス登録

New-Item -ItemType Directory -Force -Path C:\langfuse2instana\logs | Out-Null

nssm install langfuse2instana `
    "C:\langfuse2instana\venv\Scripts\langfuse2instana.exe" `
    "-c C:\langfuse2instana\config.yaml"
nssm set langfuse2instana AppDirectory C:\langfuse2instana
nssm set langfuse2instana Start SERVICE_AUTO_START
nssm set langfuse2instana AppStopMethodConsole 1500
nssm set langfuse2instana AppStdout C:\langfuse2instana\logs\out.log
nssm set langfuse2instana AppStderr C:\langfuse2instana\logs\err.log
nssm set langfuse2instana AppRotateFiles 1
nssm start langfuse2instana

# 状態確認
nssm status langfuse2instana
Get-Content C:\langfuse2instana\logs\out.log -Tail 20 -Wait

---

トラブルシューティング

症状	原因	対処法
UnicodeDecodeError: 'charmap'	config.yaml が cp1252 エンコーディング	PowerShellの WriteAllText(..., UTF8) で書き直す
Fatal error in launcher: Unable to create process	.exe が古い venv パスを参照	venv を削除し python -m venv venv && pip install . を再実行
yaml.scanner.ScannerError: mapping values not allowed	PowerShell -replace で YAML が破損	PowerShell heredoc で config.yaml を書き直す
All N traces already exported（state.db削除後も）	複数箇所に state.db が存在	Get-ChildItem -Path C:\ -Recurse -Filter state.db で全て削除
200 OK で送信されるがInstana UIに表示されない	見ている場所が違う	分析（Analytics）→ 呼び出し（Calls）（Applicationサマリービューではない）+ 「内部呼び出しの表示」をオン
Service画面のメトリクスが空	OTLP メトリクスはServiceサマリーに出ない	Custom Dashboard で gen_ai.client.* メトリクスを追加
新しい会話がLangfuseのObservationsタブにしか出ず、Tracesタブに新規行が増えない	WXOが既存の長寿命セッションtraceに各ターンをobservationとして追記するため	自動対処済み：観測の開始時刻でポーリングし親traceを冪等に再エクスポートするため、追記分もInstanaに反映される（新しいチャットセッションを開始すれば新規trace IDにもなる）
Serviceが作成されない・トレースがINTERNALのみ	旧バージョンの問題	本バージョンで修正済み：root spanは自動的にSERVERに昇格

---

まとめ

本記事では、Langfuse2Instana を使って IBM watsonx Orchestrate のAIエージェントのトレースをIBM Instanaで監視する方法を解説しました。

ポイントのまとめ

• ✅ WXO ADKを --with-langfuse で起動した場合、Langfuse2Instanaを使ってInstanaへ転送する
• ✅ Langfuse SaaS・OnPrem・ADK同梱版のいずれにも対応。複数ソースの同時監視も可能
• ✅ root span を SERVER に自動昇格することで、Instanaのサービス認識が正常に機能する
• ✅ 観測の開始時刻でポーリングするため、長寿命セッショントレースに追記された会話ターンも取りこぼさない
• ✅ 観測ID単位の重複排除（SQLite）で、再起動後も二重送信せず、メトリクスの二重計上も防ぐ
• ✅ WindowsサービスとしてNSSMで登録することで常時監視が可能
• ✅ LLMのトークン使用量・コスト・レイテンシはCustom Dashboardで可視化する

関連リソース

• 📦 GitHub: https://github.com/GSSJacky/Langfuse2Instana
• 📖 Langfuse公式ドキュメント: https://langfuse.com/docs
• 📖 IBM Instana OTelドキュメント: https://www.ibm.com/docs/en/instana-observability/current?topic=opentelemetry-overview