ClickHouse を活用した Langfuse による Cursor エージェントのトレースと評価

コードの diff は何が変更されたかを示します。エージェントを改善するには、どのモデル呼び出しやツールがそれを生成したのか、どこに時間がかかったのか、そしてその実行コストがいくらだったのかを把握することも重要です。

エージェントのオブザーバビリティと評価のためのオープンソースプラットフォームである Langfuse は、そうした作業の検証と改善に役立ちます。Langfuse Observability プラグイン は、Cursor のモデル呼び出し、ツール実行、トークン使用量をトレースとして収集します。それらのトレースの背後にある分析基盤を支えるのが ClickHouse であり、個々の実行の調査やチーム全体でのパターンの比較が可能になります。

本ガイドでは、Cursor を Langfuse に接続し、コストの高いターンを調査して、変更によって結果が改善されたかどうかを評価機能で確認します。

ClickHouse が Langfuse の分析を支える仕組み #

エージェントのオブザーバビリティからは、モデル呼び出し、ツール実行、トークン使用量、レイテンシ、評価スコアといった分析用データが生成されます。ClickHouse は Langfuse の背後にある分析データベースであり、個々の実行の調査とチーム全体にわたる分析の両方をサポートしています。

Langfuse v4 では、ClickHouse のワイドな observations テーブルが各 observation とともにユーザー、セッション、タグ、環境を保持します。Langfuse ダッシュボードと Metrics API v2 は、これらの observation を使用して記録された使用量、コスト、レイテンシを集計します。各 observation にトレースコンテキストを持たせることで、これらのクエリにおいて別々の trace テーブルと observation テーブルを結合する手間を省けます。

Cursor を利用するチームにとっては、コストの傾向から調査を開始し、その背景にあるターンを特定して、対応が必要なモデルやツールの動きを詳しく調べられることを意味します。

Cursor での Langfuse プラグインのセットアップ #

1. Langfuse Cloud または自社のセルフホスト環境でプロジェクトを作成し、その API キーをコピーします。
2. Cursor Marketplace から Langfuse Observability をインストールします。Customize を開き、Plugins に移動して Browse Marketplace を選択し、検索します。
3. ~/.cursor/langfuse.json にキーを配置します。

1{
2  "publicKey": "pk-lf-...",
3  "secretKey": "sk-lf-...",
4  "baseUrl": "https://cloud.langfuse.com"
5}

この例では EU リージョンを使用しています。その他のリージョンやセルフホスト環境の場合は、統合ドキュメント に記載されている対応するベース URL を使用してください。

4. Cursor を再起動し、エージェントにプロンプトを送信します。

このプラグインは MIT ライセンスに基づくオープンソースです。プロンプト、アシスタントメッセージ、ツールの入力と出力、トークン使用量、その他のトレースメタデータを Langfuse プロジェクトに送信します。ファイル読み取り内容の収集はデフォルトでオフになっており、有効にするには captureFileContent と captureToolOutput の両方が必要です。プラグインは Langfuse キーをマスクし、デフォルトでは Cursor の動作を維持したままアップロードの失敗をログに記録します。無効化するには、設定で enabled を false に設定します。統合ドキュメント では、すべてのオプション、Cursor CLI、および Cloud Agents を網羅しています。

Langfuse における Cursor のターンの見え方 #

プラグインは Cursor のフック上で動作し、プロンプトごとに Cursor Turn という名前のトレースを 1 つ作成します。その内部には以下が含まれます。

• アシスタントメッセージごとの LLM observation(会話履歴を入力とし、テキスト、思考プロセス、要求されたツール呼び出しを出力とする)。
• エージェントが実行する各ツール(Shell、Read、StrReplace、MCP ツールなど)のツール observation(入力、出力、実行時間、エラーステータスを含む)。
• サブエージェント用のネストされた Cursor Subagent observation、および Cursor がコンテキストを圧縮した際のイベント。

1 つの会話のすべてのターンは セッション にグループ化され、ユーザーはオーバーライドしない限り、サインインしている Cursor アカウントのメールアドレスがデフォルトになります。

Cursor はモデル呼び出しごとではなく、1 ターンに 1 回トークン使用量を報告します。プラグインはこれをそのターンの最後の LLM observation に記録するため、コストはトレースの合計値から確認してください。

チーム全体でのコストと使用量の追跡 #

すべてのトレースには Cursor ユーザー、タグ、環境ラベルが付与されるため、コーディングエージェントのトレースを本番環境のトレースと分けて管理できます。カスタムダッシュボード では、ユーザー、モデル、時間ごとにコストと使用量をグラフ化でき、同じフィルターをトレーステーブルにも適用できます。価格定義のないモデルはトークン数を表示しますがコストは表示されません。これらには カスタムモデル定義 を追加できます。これをチーム全体に展開する方法については、コーディングエージェントの使用量の追跡と最適化 を参照してください。

コストの高いターンの特定と修正の確認 #

Cursor をすべてのエンジニアに展開したチームを例にとってみましょう。1 週間トレースを収集した後のコストダッシュボードには、開発者やモデル別の支出が表示され、いくつかのターンが高コストとして目立っています。

1. チームはそれらのターンを開きます。いくつかには共通のパターンが見られます。エージェントが同じファイルを繰り返し読み取っており、シェルコマンドが失敗して成功するまで再試行されています。

2. チームは、関連するコードの場所や実行すべきビルドコマンドを指定したプロジェクトルールを作成し、この反復されるコンテキストをルール化します。

3. ルールが有効に機能しているか確認するため、チームはそれらの実際のセッションのプロンプトから データセット を構築します。エバリュエーターが各タスクが完了したかどうかを評価し、比較ビュー にはそれらのスコアと並んでコストとレイテンシが表示されます。コストが低下し、タスク完了率が維持されていれば、そのルールを本番に反映します。

Cursor 自体に検索を任せることもできます。Langfuse プラグイン を追加すると Langfuse スキルが導入され、エージェントは Langfuse CLI を通じてトレース、プロンプト、データセット、スコアにアクセスできるようになります。これを Langfuse Observability と並んでインストールし、次のように質問してください。「今週最もコストの高かった Cursor のターンと、それらに共通している点をリストアップして。」

展開後は、最初のステップのダッシュボードによって、ターンあたりのコストが低下したかどうかを確認できます。

Cursor で構築する AI アプリケーションへの同じループの適用 #

Cursor はアプリケーションのプロンプト、モデル、ツールも編集するため、各変更を実験として扱えます。実際のケースをデータセットとして保存し、LLM-as-a-judge、コードエバリュエーター、または人間によるレビューで スコア を定義し、データセット上でアプリケーションを実行して、マージ前に現在のバージョンとその実行を比較します。CI では、langfuse/experiment-action GitHub Action を使用して、スコアがしきい値に達しない場合にジョブを失敗させます。

デプロイ後は、オンライン評価 が同じエバリュエーターを用いて本番トレースのサンプルをスコアリングします。スコアの低かったトレースはデータセットに戻され、次の実験でカバーされるようになります。Langfuse Academy の AI エンジニアリングループ では、この完全なサイクルについて説明しています。

Cursor にこのセットアップを任せることも可能です。Langfuse スキルをインストールした状態で、エージェントに次のようにプロンプトを出してください。

1Set up offline evaluation for this application with Langfuse.

まとめ #

Langfuse Cloud プロジェクト を作成するか、自社のセルフホスト環境を使用して、上記のセットアップに従って最初の Cursor セッションを収集してみましょう。コストの高いターンを調査し、関連する指示を更新して、展開する前にその結果を評価してください。

お使いのアプリケーションで ClickHouse を使用している場合、Cursor 向け ClickHouse プラグイン を利用すると、エージェントからスキーマ設計、クエリ最適化、データ取り込みに関するガイダンスを得られます。テーブルスキーマのレビューや、ClickHouse のベストプラクティスに沿った SQL のチェックを Cursor に依頼してみてください。