この記事は freee Developers Advent Calendar 2025 の15日目になります。

昨日はけむりだまさんが「freee技術の日」に関する記事を投稿してくれました！技術カンファレンスの裏側で運営を円滑にするために使われた技術について解説してくれています、ぜひ見てみてくださいね！

はじめに

フリーで DBRE として働いている pon です。 24 卒として入社し、今年の 7 月から DBRE (Database Reliability Engineer) に配属となり、ほぼ未経験のデータベース領域で勉強の日々を過ごしています。

私は社内で Langfuse v2 から v3 へのバージョンアッププロジェクトに参加していました。フリーではこの Langfuse を「まほう経費精算」というプロダクトで使用しています。

Langfuse v3 からバックエンド DB として ClickHouse が推奨構成となりました。社内で初の ClickHouse 使用例となるため、DBRE としてその調査検証に関わることになりました。

本記事では、Langfuse バージョンアッププロジェクトで得た ClickHouse 周りの知見について話したいと思います。

Langfuse について

Langfuse とはどんなツールなのか

Langfuse は LLM アプリケーション専用の観測・評価プラットフォームです。 LLM の振る舞いを計測・記録し、品質を評価することで、開発者が「良いプロンプト」や「良いモデル」を見つける手助けをします。

Langfuse が扱うデータの特性

Langfuse が扱うデータには以下のような特性があります。

データ量が非常に多い

LLM アプリケーションでは、1 回の呼び出しで数百〜数千 token のデータが生成されます。これが 1 日数万回単位で繰り返され、データがどんどん蓄積していきます。

トレース、観測ログ、スコアといった様々なデータが日々積み重なり、運用が長期化するほどデータ量は膨大になっていきます。

追記型ワークロード

Langfuse へのデータ書き込みは、SDK から送信されるトレーシングデータの継続的な INSERT が中心です。

ユーザーの LLM 利用に応じてリアルタイムでデータが追記されていくため、書き込み頻度は非常に高くなります。一方で既存データの更新や削除を頻繁に行うことはないため、追記型のワークロードと言えるでしょう。

複雑な集計

Langfuse のダッシュボードでは、時系列でのパフォーマンス推移、モデル別・機能別のクロス分析、トークン消費量の合計といった複雑な集計処理が求められます。また、数億件に達するトレーシングデータに対してフィルタリングや並び替えを行う必要もあります。

これらの分析クエリをリアルタイムで処理するには、単純なトランザクション処理向けのデータベースでは処理効率に課題があります。

Langfuse v2 から v3 への移行に伴う構成の変更

フリーでは Langfuse をセルフホストして運用しています。セルフホストにおける Langfuse では、 v2 から v3 にかけてアーキテクチャが大きく変更されています。以下に Migrate Langfuse v2 to v3 にある構成図を示します。

Langfuse 2 の構成図。Langfuseを動かすWebサーバーと、データベースとしてPostgreSQLが用いられている。 — Langfuse v2 の構成図

Langfuse v3 の構成図。Langfuse v3 の構成図。v2 との違いとしてLangfuseを動かすWebサーバーと、データベースとしてPostgreSQLに加えて、ワーカー、ClickHouse、S3、Redisが追加されている。 — Langfuse v3 の構成図

Langfuse v3 において追加された要素は以下になります。

Redis
- イベントキューとキャッシュによる非同期処理の実現
Worker
- バックグラウンドでのデータ処理を担当
S3
- メディアファイルやバックアップの保存先
ClickHouse
- 大量のトレースデータの高速な集計・分析を担当

なお、PostgreSQLは引き続きユーザー管理や設定情報などのトランザクション処理を担当し、ClickHouse はトレースデータの集計・分析を担当するという役割分担になっています。

これらの追加により、書き込み処理の非同期化によるパフォーマンス向上と、データ保存先の分離によるセキュリティ強化が図られています。また、この他にも organization 単位での権限制御が可能になるなどのバージョンアップによるメリットが存在します。

フリーでは従来 Langfuse v2 を使用しており、これらのメリットを享受するため v3 への移行プロジェクトを開始しました。ここからは v3 で新たに導入された ClickHouse について詳しく見ていきます。

ClickHouse について

ClickHouseの強み

列指向ストレージ

ClickHouse は列指向のデータベースです。一般的によく知られているRDBMS である MySQL や PostgreSQL が行単位でデータを保存するのに対し、ClickHouse は列単位でデータを保存します。この構造は分析・集計処理に大きなメリットをもたらします。

例えば「過去 1 ヶ月のトークン消費量の合計」を求める場合、行指向データベースでは全行のデータを読み込む必要がありますが、列指向では必要な列だけを読み込めば済みます。結果として、大量のデータに対する集計クエリの効率が上がります。

行指向と列指向の場合のデータ取得方法の違い。行指向データベースでは行単位でデータを読み込み、tokenの要素を抽出している。列指向データベースでは、tokenの列のデータを読み込んでいる。 — データ取得のイメージ図

大規模データの高速処理

ClickHouse は OLAP（Online Analytical Processing）に特化して設計されており、数億〜数兆行のデータを秒単位で処理できます。Langfuse のように日々膨大なトレースデータが蓄積される環境では、この処理性能が重要になります。

また、Table Engine (MergeTree など)、Materialized View、多様なインデックスタイプなど、高速化のための機能が豊富に用意されています。

トレードオフ

先ほどは強みについて紹介しましたが、もちろん ClickHouse には上記の強みと引き換えに不得手なところも存在します。

OLTPワークロードには不向き

ClickHouse は OLAP に特化しており、OLTP (Online Transactional Processing) には向いていません。

複数テーブルにまたがるトランザクションの原子性が保証されないため、テーブル間の整合性を厳密に保つ必要がある処理には不向きです。トランザクション外のクライアントは Read Uncommitted の分離レベルとなることから、他のセッションのコミット前の変更が見える可能性があります。

分散構成においては、各シャードへの書き込みは個別にトランザクショナルですが、全体としての原子性は保証されません。このような分散環境でのレプリケーション調整には ClickHouse Keeper（または ZooKeeper）が使用されます。

また、1件ずつのレコード取得や、細かい単位でのデータ操作が頻繁に発生するアプリケーションでは行指向のデータベースの方が適しているでしょう。

MergeTree による更新・削除の制約

ClickHouse は Table Engine に MergeTree を採用しており、データの更新や削除は通常の RDBMS とは異なる挙動をします。

ClickHouse には従来の DELETE とLightweight Delete の 2 種類の削除が存在します。ClickHouse で推奨される Lightweight Delete では、削除対象の行に内部的なフラグを立てることで、後続のクエリからは即座に除外されます。ただし、物理的な削除はバックグラウンドのマージ処理時に行われます。この間、削除済みデータのフィルタリングが必要となるため、大量のデータを削除した場合は SELECTのパフォーマンスに影響を与える可能性があります。 UPDATE についても同様に非同期で処理されるため、変更が即座に反映されるわけではありません。

MergeTree の非同期マージは、マージ処理を後回しにすることで書き込みのブロックを防ぎ、大量の INSERT を高スループットで処理できるようにする設計です。しかし、頻繁にデータを更新・削除するワークロードにとってはデメリットとなるでしょう。

Langfuse における ClickHouse の役割

Langfuse が扱うデータの特性を振り返ると、ClickHouse との相性の良さが見えてきます。

Langfuse v3 のリリースノートでもPostgres の行ベースストレージでは数十億行のトレースデータを扱う際にクエリ時間が遅くなる課題があったことが述べられており、ClickHouseの採用によってこれを解決しています。

集計の高速化

ダッシュボードで求められるリアルタイム集計は、列指向ストレージにより高速に処理できます。

書き込み性能

Langfuse のデータは SDK からの継続的な INSERT が中心であり、更新・削除は稀です。これは MergeTree の設計思想と合致しており、高い書き込みスループットを最大限に活かせます。

整合性要件

トレーシングデータは独立したイベントの記録であるため、厳密な ACID トランザクションが不要です。

ClickHouse OSS版 VS ClickHouse SaaS版

Langfuse v3 では ClickHouse が推奨構成となっていますが、セルフホスト (OSS) とマネージドサービスである ClickHouse Cloud (SaaS) の選択肢があります

フリーでは、技術面・コスト面・セキュリティ面・運用面の 4軸で比較検討を行いました。

観点	セルフホスト（ EKS ）	SaaS（ ClickHouse Cloud ）
可用性（技術面）	冗長化・フェイルオーバーの実装が必要	デフォルトで高可用性構成、複数 AZ 対応
拡張性（技術面）	手動でのスケーリング設定が必要	自動垂直スケーリング、ストレージ無制限
インフラ費用（コスト面）	低い	高い( 試算時にはセルフホストの約1.8倍程度 )
人的コスト（コスト面）	高い（構築・監視・アップグレード・障害対応）	低い（マネージド）
データ保護・アクセス制御（セキュリティ面）	自社で全て管理	SSO 対応、AWS PrivateLink 、監査ログ標準提供
障害対応（運用面）	コミュニティサポートに依存	Enterprise プランで 30 分以内の応答