Skip to main content
このガイドでは、Langfuse Cloud の LLM トレースデータを ClickHouse Cloud に取り込み、リアルタイム分析に活用するまでの手順を説明します。

Langfuse Cloud からのエクスポート

このガイドに従って、Langfuse Cloud で定期エクスポート用の Blob Storage インテグレーションを設定します。トレースデータのオブジェクトストレージへのエクスポートは、最短 20 minutes 間隔のほか、hourly、daily、weekly のスケジュールでも設定できます。デフォルトでは、各エクスポートに observations (トレース属性で拡充済み) と scores が含まれます。

エクスポートされるファイルの構成

Langfuse Cloud の Blob Storage インテグレーションは、以下のディレクトリ構造で、出力先のバケットまたはストレージコンテナーにデータを書き込みます。

ClickHouse Cloud へのインポート

Langfuse Cloud で Blob Storage インテグレーションを設定すると、トレースデータが定期的に対象のバケットまたはストレージコンテナーへエクスポートされます。このデータを ClickHouse Cloud にインポートするには、ClickPipes が提供するマネージドなオブジェクトストレージコネクタを利用できます。

ClickPipe を作成する

この例では、S3 ClickPipe を使用して、Langfuse Cloud から定期的にエクスポートされたデータを受け取る S3 バケットからデータをインポートします。この手順は、あらゆるオブジェクトストレージのエクスポート先に共通するひな形としても利用できます。データソースごとの詳細な手順については、ClickPipes ドキュメントを参照してください。
1

データソースを選択する

1. ClickHouse Cloud のメインナビゲーションメニューで Data sources を選択し、Create ClickPipe をクリックします。
ClickPipe の作成
2. Amazon S3 タイルをクリックします。ClickPipes UI に表示されていないその他の S3 互換サービスに接続する場合も、このタイルを使用できます。
Amazon S3 データソースを選択
2

接続を設定する

1. Langfuse Cloud のエクスポートを受け取るバケットに ClickPipes が接続・認証するために必要な情報を入力します。
  • Authentication method: S3 ClickPipe は IAM 認証情報 (Credentials) と IAM role ベースの認証 (IAM role) をサポートしています。ClickPipes に必要なのは、バケットへの読み取りアクセス権のみです。認証とアクセス許可の詳細については、リファレンスドキュメントを参照してください。
  • S3 file path: ClickPipe の参照先としてサブディレクトリを指定し、* ワイルドカードを使用してエクスポートされたすべてのファイルにマッチさせます。サブディレクトリごとにエクスポートファイルのスキーマが異なるため、サブディレクトリごとに ClickPipe を 1 つずつ作成する必要があります。 ネストされたプレフィックスをまたいでファイルをマッチさせる方法など、サポートされているパターンの詳細については、リファレンスドキュメントを参照してください。
2. Continuous ingestion を選択します。これにより、Langfuse がターゲットバケットに新しいファイルを書き込むたびに、自動的に取り込まれるようになります。
継続的インジェストを有効にした Langfuse エクスポートの接続情報。
3. Incoming data をクリックします。ClickPipes がバケットからメタデータをフェッチし、次のステップでターゲットテーブルのスキーマを推論します。
3

取り込むデータを検証する

1. ClickPipes がバケットに接続し、指定したパス内のファイルを一覧表示して、ファイルフォーマットを推論します。この例では、Langfuse Cloud のデフォルトのエクスポートファイルフォーマット (Parquet) を使用しています。
Langfuse のエクスポートパスに一致するファイル(ファイルタイプは Parquet に設定)
2. Parse information をクリックします。ClickPipes はサンプルファイルを使ってエクスポートされたデータのスキーマを推論し、ソースのフィールドを ClickHouse のターゲットテーブルに自動的にマッピングします。
4

取り込み先を設定する

1. このステップでは、推定したスキーマを確認し、ターゲットテーブルの設定をカスタマイズできます。具体的には、データ型マッピングの調整、sorting key の定義、テーブルエンジン の選択などを行います。
専用の langfuse データベースに書き込む scores エクスポート。sorting key は environment、name、timestamp、trace_id、observation_id、id に設定されている
Upload data to では New table を選択したままにし、以下を設定します。
  • Database と Name: Langfuse データ用の専用データベース (例: langfuse) と、宛先テーブルのわかりやすい名前 (例: scores) を指定します。ClickPipes では、名前の衝突を避けるため、デフォルトで default.s3-<uuid> が使用されます。
  • Sorting key: 宛先テーブルのソートキーです。ClickHouse がディスク上にデータをどのように格納するかを決定します。最適なパフォーマンスを得るには、sorting key をデータのアクセスパターンに合わせ、クエリがデータの読み取りをできるだけスキップできるようにする必要があります。 このキーは ReplacingMergeTree テーブルでの重複排除にも使用されるため、カラムの組み合わせでレコードを一意に識別できる必要があります。複数の Langfuse プロジェクトを 1 つのテーブルに読み込む場合は、sorting key の先頭に project_id を追加してください。sorting key の選び方についてはリファレンスドキュメントを参照してください。
  • Partition by: 古いトレースを期限切れにする予定がなければ、空欄のままにします。ClickHouse におけるパーティション化はクエリ最適化ではなくデータ管理のための機能であり、時間範囲のクエリは推奨の sorting key によってすでに絞り込まれます。保持期間の管理が必要な場合は、時間カラム (toYYYYMM(start_time)、scores の場合は toYYYYMM(timestamp)) でパーティション化してください。こうすることで、1 か月分のトレースを 1 回の DROP PARTITION 操作で削除できます。
2. 次に、Advanced settings を展開し、重複排除を確実に行うため Engine を ReplacingMergeTree に設定して、Version カラムに updated_at を指定します。
ReplacingMergeTree エンジンと、バージョンカラムとして updated_at が設定された Advanced settings
Langfuse Cloud の Blob Storage 連携では、エクスポート期間の開始・終了の両端が含まれるため、同じレコードが複数のエクスポートファイルに含まれることがあります。分析クエリのパターンが冪等 (例: uniq()、max()、min()) でない限り、ターゲットエンジンに ReplacingMergeTree を使用し、下流のデータモデルで重複排除を必ず行ってください。
ReplacingMergeTree による重複排除このテーブルエンジンは、バックグラウンドマージによって重複を統合します。読み取り時に完全な重複排除 (すなわち merge-on-read のセマンティクス) を行うには、クエリ実行時に FINAL 修飾子 (または argMax() 形式の集計) を必ず使用してください。
5

アクセス許可を設定する

ClickPipes は、宛先テーブルへのデータ書き込み用に専用ユーザーを作成します。この内部ユーザーには、カスタムロールまたは事前定義済みロールのいずれかを選択して割り当てます。
  • Full access: クラスターへのフルアクセス権を持ちます。宛先テーブルで materialized view または Dictionary を使用する場合は、このロールが必要です。
  • Only destination table: 宛先テーブルに対する INSERT アクセス許可のみを持ちます。
アクセス許可
Complete setup をクリックすると、ClickPipe が作成されます。
6

設定を完了する

これで設定は完了です。ClickPipes はまず、指定したパス内のすべてのファイルを対象に過去データのバックフィルを実行し、その後はバケットに新しいファイルが到着するたびに取り込みを開始します。
Data sources の下で実行中の observations および scores の ClickPipes
ClickHouse Cloud にインポートしたいサブディレクトリごとに、このガイドの手順を繰り返してください。

トレースデータのクエリ

ClickPipes が稼働したら、Langfuse Cloud のトレースデータを ClickHouse Cloud 上で直接クエリできます。以下では、コストとレイテンシのロールアップ、単一トレースの再構築、スコアとモデルやプロンプトとの相関分析など、代表的なクエリパターンの例を紹介します。

時間バケット単位のメトリクスロールアップ

usage_details や cost_details などの一部のフィールドは、Map 型のカラムとしてエクスポートされます。個々の値を取得するには、キーによるルックアップを使用します (例: sum(cost_details['total'])) 。

トレースの再構築

品質分析

関連項目

最終更新日 2026年9月26日