LibreChatに統合されたLangfuseトレース送信機能を試す

はじめに
#

この記事では、オープンソースのチャットUI「LibreChat」をDocker Composeでセットアップし、既存のLangfuseへトレースを送信する機能を試します。

LibreChatでLangfuseにトレースを送信するには
#

LibreChatでLangfuseにトレースを送信するには、これまでLiteLLMをプロキシとして挟む構成が必要でした。

LibreChat → LiteLLM (プロキシ) → LLM Provider
                ↓
            Langfuse

LiteLLMはLangfuse連携をサポートしており、LLM呼び出しをトレースできますが、LibreChatとは別にLiteLLMの構築・管理が必要になるため、セットアップの複雑さが増すという課題がありました。

LibreChat v0.8.1（2025年12月11日リリース）では、PR #10292 により、LiteLLMなしでLibreChatから直接Langfuseにトレースを送信できるようになりました。

LibreChat → LLM Provider
    ↓
 Langfuse（直接送信）

これにより、LibreChatとLangfuseだけのシンプルな構成でオブザーバビリティを実現できます。

この記事で実現すること
#

この記事では、以下の内容を実践します。

Docker ComposeでLibreChatを構築し、OpenAI APIとLangfuseに接続
基本的なトレースの確認
LibreChatでMCP Server利用時のトレースを確認

注意：この記事では、Langfuseは既に用意されている前提で進めます。Langfuseをセルフホストする方法については、Langfuse公式ドキュメントを参照してください。Langfuse Cloudを利用する場合は、https://cloud.langfuse.com でアカウントを作成してください。

それでは、環境構築から始めます。

環境構築編
#

LibreChatをDocker Composeでローカル環境に構築し、既存のLangfuseに接続します。

前提条件
#

以下がインストールされていることを前提とします。

Docker Desktopなど、Docker Composeが使える環境
以下何れかのLangfuseとAPIキー
- Langfuse Cloud
- セルフホストしたLangfuse
LLMプロバイダーのAPIキー（OpenAI、Anthropic、Google Vertex AIなど）

アーキテクチャ概要
#

今回構築する環境の構成は以下の通りです。

各コンポーネントの役割

LibreChat: チャットUIおよびLLM統合層
MongoDB: LibreChatのデータベース（ユーザー情報、会話履歴など）
外部Langfuse: トレース収集・可視化（Cloudまたはセルフホスト）
LLM Provider API: OpenAI、Vertex AI、Anthropicなどのモデルプロバイダー

セットアップ手順
#

1. ディレクトリ構成
#

以下のようなディレクトリ構成で環境構築します。

librechat-langfuse-integrate/
├── .env                 # 環境変数
├── docker-compose.yml   # コンテナ構成定義
└── librechat.yaml       # LibreChatの設定ファイル

任意のディレクトリを作成し、以降の手順で各ファイルを配置していきます。

2. 環境変数ファイル (.env)
#

.env ファイルを作成し、Langfuse接続情報とLLMプロバイダーのAPIキーを設定します。

.env

# ============================================
# LibreChat Server Settings
# ============================================
PORT=3080
ALLOW_REGISTRATION=true

# ============================================
# LLM Provider Settings
# ============================================
# OpenAI API Key
OPENAI_API_KEY=sk-proj-xxxxxxxxxxxxxxxxxxxxxxxx

# ============================================
# Langfuse Settings (External Server)
# ============================================
# Get these values from your Langfuse project settings
LANGFUSE_SECRET_KEY=sk-lf-xxxxxxxxxxxxxxxxxxxxxxxx
LANGFUSE_PUBLIC_KEY=pk-lf-xxxxxxxxxxxxxxxxxxxxxxxx
# Langfuse Cloud の場合は https://cloud.langfuse.com
# セルフホストの場合は https://your-langfuse-server.com
LANGFUSE_BASE_URL=https://cloud.langfuse.com

# ============================================
# LibreChat Auth Secrets
# ============================================
# セキュリティ上、必ず変更してください
# 生成: openssl rand -hex 16
CREDS_KEY=your-creds-key-change-this
# 生成: openssl rand -hex 8
CREDS_IV=your-creds-iv-change-this
# 生成: openssl rand -hex 32
JWT_SECRET=your-jwt-secret-change-this
# 生成: openssl rand -hex 32
JWT_REFRESH_SECRET=your-jwt-refresh-secret-change-this

補足

Langfuseとの接続に必要なのは LANGFUSE_SECRET_KEY、LANGFUSE_PUBLIC_KEY、LANGFUSE_BASE_URL の3つです。これらの値はLangfuseプロジェクトの Settings → API Keys から取得できます。
Auth Secrets（CREDS_KEY、CREDS_IV、JWT_SECRET、JWT_REFRESH_SECRET）は、各項目のコメントに記載した openssl rand コマンドで生成した値に置き換えてください。

3. Docker Compose設定ファイル (docker-compose.yml)
#

LibreChatとMongoDBのみを起動し、OpenAI APIを利用したシンプルな構成です。

フル機能を含む公式のDocker Compose設定は以下公式GitHubリポジトリの設定ファイルを参照して下さい。

https://github.com/danny-avila/LibreChat/blob/main/docker-compose.yml

docker-compose.yml

services:
  # ===========================================
  # LibreChat Application Server
  # ===========================================
  api:
    container_name: LibreChat
    image: ghcr.io/danny-avila/librechat:v0.8.1
    ports:
      - "${PORT}:${PORT}"
    depends_on:
      - mongodb
    restart: always
    extra_hosts:
      - "host.docker.internal:host-gateway"
    env_file:
      - .env
    environment:
      - HOST=0.0.0.0
      - MONGO_URI=mongodb://mongodb:27017/LibreChat
    volumes:
      - ./librechat.yaml:/app/librechat.yaml:ro

  # ===========================================
  # MongoDB - LibreChatのデータストア
  # ===========================================
  mongodb:
    container_name: chat-mongodb
    image: mongo:8.0.17
    restart: always
    volumes:
      - mongodb-data:/data/db
    command: mongod --noauth

volumes:
  mongodb-data:

4. LibreChat設定ファイル (librechat.yaml)
#

LibreChatの動作をカスタマイズする設定ファイルです。以下の例はOpenAIモデルとエージェント機能を使用する設定です。

librechat.yaml

# Configuration version (required)
version: 1.3.5

# Cache settings: Set to true to enable caching
cache: true

# Endpoints Configuration
endpoints:
  # OpenAI Configuration
  openAI:
    apiKey: "${OPENAI_API_KEY}"
    models:
      default:
        - "gpt-5"
        - "gpt-5-mini"
        - "gpt-5-nano"
    titleConvo: true
    summarize: false
    titleModel: "gpt-5-nano"

  # Agents Configuration
  # Langfuse tracing is enabled for Agents
  agents:
    disableBuilder: false # Enable Agent Builder UI
    recursionLimit: 25 # Default steps an agent can take
    maxRecursionLimit: 50 # Maximum steps limit

# MCP Server Configuration（後ほど検証編2で使用）
mcpServers: {}

registration:
  socialLogins: []

補足

mcpServers は後ほどMCP Server機能を検証する際に設定を追加します。

5. Docker ComposeでLibreChatを起動・動作確認
#

以下のコマンドでLibreChatを起動します。

# LibreChatとMongoDBを起動
docker compose up -d

# 起動状態を確認
docker compose ps

初回起動時は、イメージのダウンロードやデータベースの初期化が行われるため、数分かかる場合があります。

サービスが正常に起動しているか、ログを確認します。

# LibreChatコンテナのログを確認
docker compose logs -f api

# 正常に起動していれば、以下のようなログが表示されます
# LibreChat v0.8.1
# Server listening on port 3080
# Connected to MongoDB

起動を確認したら、以下の手順でLibreChatにアクセスします。

http://localhost:3080 にアクセス
新規登録からアカウントを作成

3. ログイン後、設定したLLM（OpenAI）を選択し、LLMに挨拶をし、LibreChatで正しくLLMが動作することを確認します。

6. Langfuse接続の確認
#

LibreChatで簡単な会話を実行した後、Langfuse UIにアクセスしてトレースが記録されているか確認します。

Langfuse UI アクセス先
#

Langfuse Cloud : https://cloud.langfuse.com
セルフホスト : セルフホストのLangfuseURL

Tracing ページに移動し、LibreChatからのトレースが表示されていれば成功です。

これで、LibreChatと外部Langfuseの統合環境が完成しました。次は、実際にトレースの詳細を確認します。

検証編1 - 基本的なトレース確認
#

環境構築が完了したので、トレースが正しく送信されているか確認します。

「5. Docker ComposeでLibreChatを起動・動作確認」での会話のトレース詳細を確認しましょう。

トレースの確認
#

上記で実行した会話の内容についてトレースを深堀りしてみます。

Langfuse UIの Tracing ページに移動します。

確認できる情報
#

主に以下のような内容がトレースから確認できます。

Trace ID（各会話に一意のIDが付与されています）
Timestamp（トレースが記録された日時）
User ID（LibreChat MongoDBのObjectIDと紐づく）
Session ID （LibreChatのスレッドID : ConversationIDと紐づく）
Input/Output（プロンプトとLLMの応答）
Latency（リクエストにかかった時間）
Tokens（入力トークン数と出力トークン数）
Cost（トークン使用量から計算されたコスト）

トレースの詳細を確認
#

特定のトレースをクリックすると、詳細情報が表示されます。

1. 実行フロー
#

トレースは階層構造で表示され、以下のような流れと各処理にかかったコストが確認できます。

また、自動的にエージェントの処理フローがグラフとしても表示されます。

2. プロンプト詳細
#

Input、Output セクションには、実際にLLMに送信されたプロンプトとLLMからの応答が表示されます。

3. パフォーマンスメトリクス
#

パフォーマンス関連のメトリクスとしては以下のようなものが確認できます。

Latency（リクエストの開始から完了までの時間）
Time to First Token (TTFT)（最初のトークンが生成されるまでの時間）

これらの指標により、モデルのパフォーマンスを定量的に評価できます。

複数の会話スレッドを確認
#

LibreChatで新規チャットを開始すると、新しい Conversation ID が付与されます。Langfuse UIの Sessions ページで、Conversation ID ごとにグループ化された会話を確認できます。

これにより、ユーザーがどのような会話の流れを持っているかを追跡できます。

コスト分析
#

デフォルトで用意されている Langfuse Cost Dashboard ページにより、

以下のようなコスト分析が可能です。

総コスト（トークン使用量から計算された総コスト）
モデル別コスト（どのモデルがどれだけコストを使っているか）
ユーザー別コスト（どのユーザーがどれだけコストを使っているか）

検証1のまとめ
#

基本的なトレース送信機能の検証により、以下のことが確認できました。

LibreChatからLangfuseへのトレース送信が正常に動作
会話内容、パフォーマンスメトリクスが正確に記録される
Sessions から ConversationIDごとの、会話を追跡できる
トークン使用量とコストを可視化できる

次は、MCP Server機能を使用した場合のトレースを確認します。

検証編2 - MCP Server利用時のトレース
#

LibreChatはMCP (Model Context Protocol) Serverをサポートしており、LLMにツール実行機能を追加できます。ここでは、MCP Serverを設定し、ツール呼び出し時のトレースがどのように記録されるかを確認します。

MCP Serverの設定
#

Langfuse Docs MCP Serverを設定する例を示します。

librechat.yamlの更新
#

librechat.yaml を編集し、mcpServers セクションに以下の設定を追加します。

mcpServers:
  langfuse-docs:
    command: npx
    args:
      - "-y"
      - "mcp-remote"
      - "https://langfuse.com/api/mcp"
    metadata:
      name: "Langfuse Documentation"
      description: "Access to Langfuse official documentation via MCP"

追記後の librechat.yaml は下記セクションを参照ください。

librechat.yaml

# Configuration version (required)
version: 1.3.5

# Cache settings: Set to true to enable caching
cache: true

# Endpoints Configuration
endpoints:
  # OpenAI Configuration
  openAI:
    apiKey: "${OPENAI_API_KEY}"
    models:
      default:
        - "gpt-5"
        - "gpt-5-mini"
        - "gpt-5-nano"
    titleConvo: true
    summarize: false
    titleModel: "gpt-5-nano"

  # Agents Configuration
  # Langfuse tracing is enabled for Agents
  agents:
    disableBuilder: false # Enable Agent Builder UI
    recursionLimit: 25 # Default steps an agent can take
    maxRecursionLimit: 50 # Maximum steps limit

# MCP Server Configuration
mcpServers:
  langfuse-docs:
    command: npx
    args:
      - "-y"
      - "mcp-remote"
      - "https://langfuse.com/api/mcp"
    metadata:
      name: "Langfuse Documentation"
      description: "Access to Langfuse official documentation via MCP"

registration:
  socialLogins: []

設定の反映
#

# LibreChatコンテナを再起動
docker compose restart api

# ログを確認
docker compose logs -f api

起動ログに以下のようなメッセージが表示されれば、MCP Serverが正常に起動しています。

info: MCP servers initialized successfully. Added 3 MCP tools.

MCP Serverを使った会話
#

LibreChat UIに戻り、新しい会話を開始します。MCP Serverが有効化されている場合、チャット欄に「MCP サーバー」という欄が表示され、「MCP サーバー」を押下すると langfuse-docs が選択できます。

langfuse-docs にチェックを入れた後、以下のような指示をLLMに依頼しましょう。

すると、LLMは langfuse-docs の Tool : searchLangfuseDocs を利用して調査しその内容を下に回答を生成してくれます。（生成された回答は長いので一部省略）

Langfuse UIでMCP Serverトレースを確認
#

MCP Serverを使用した会話のトレースを確認します。

Toolの利用
#

LLMがToolを利用した記録を確認できます。

また、Tool の Input、Output から、呼び出し（クエリ内容）とそれに対する戻り値（クエリ結果）を確認できます。

（Outputは階層が深いので一部省略。）

検証2のまとめ
#

MCP Server利用時のトレース検証により、以下のことが確認できました。

MCP Serverのツール呼び出しが正確にトレースされる
ツール呼び出しのパラメータと戻り値が記録される

まとめ
#

LibreChat v0.8.1で追加されたLangfuse統合機能を、外部Langfuse接続で検証しました。

良かった点
#

セットアップが簡単（Langfuseの環境変数を3つ追加するだけで動作）
コード変更なしで会話が自動的にトレースされる
User ID、Conversation IDなどのメタデータが自動記録されLangfuse上でトレースがグルーピングされる
MCP Serverのツール呼び出しも含めてトレースされる

こんな人におすすめ
#

既にLangfuseを使っていて、LibreChatの会話も一元管理したい方
企業内でLLMチャットUIを提供し、利用状況を可視化したい方
MCP Serverやエージェント機能のデバッグに詳細なトレース情報が必要な方

今後の期待
#

今回の検証では、トレースに記録されるObservation Typeが主に generation（LLM呼び出し）に限られていることも確認できました。

Langfuseは generation 以外にも、agent、tool、など多彩なObservation Type をサポートしています。

例えば、MCP Serverのツール呼び出しが tool 型として記録されるようになれば、Langfuse UI上でのフィルタリングや分析がより直感的になるはずです。

LibreChatのLangfuse統合はv0.8.1で初めて導入された機能です。今後のバージョンアップでこれらのObservation Typeへの対応が進むことで、トレースの表現力がさらに向上し、より実践的なオブザーバビリティが実現できるのではないかと期待しています。

参考リンク
#

LibreChat公式ドキュメント: https://www.librechat.ai/docs
Langfuse公式ドキュメント: https://langfuse.com/docs
Langfuse LibreChat統合ガイド: https://langfuse.com/integrations/other/librechat
LibreChat PR #10292（Langfuse統合）: https://github.com/danny-avila/LibreChat/pull/10292

はじめに#

LibreChatでLangfuseにトレースを送信するには#

この記事で実現すること#

環境構築編#

前提条件#

アーキテクチャ概要#

セットアップ手順#

1. ディレクトリ構成#

2. 環境変数ファイル (.env)#

3. Docker Compose設定ファイル (docker-compose.yml)#

4. LibreChat設定ファイル (librechat.yaml)#

5. Docker ComposeでLibreChatを起動・動作確認#

6. Langfuse接続の確認#

Langfuse UI アクセス先#

検証編1 - 基本的なトレース確認#

トレースの確認#

確認できる情報#

トレースの詳細を確認#

1. 実行フロー#

2. プロンプト詳細#

3. パフォーマンスメトリクス#

複数の会話スレッドを確認#

コスト分析#

検証1のまとめ#

検証編2 - MCP Server利用時のトレース#

MCP Serverの設定#

librechat.yamlの更新#

設定の反映#

MCP Serverを使った会話#

Langfuse UIでMCP Serverトレースを確認#

Toolの利用#

検証2のまとめ#

まとめ#

良かった点#

こんな人におすすめ#

今後の期待#

参考リンク#