Langfuseセルフホストで遭遇した課題のまとめ

Langfuseセルフホストでハマったポイントをまとめてみる Advent Calendar こんにちは、AIチームの長澤 (@sp_1999N) です。 この記事はAI Shift Advent Calendar 2025の16日目の記事です。 弊社サービスのAI Worker PlatformではAIエージェントの監視基盤としてLangfuseを採用しています。 Langfuseをはじめとしたエージェント監視基盤については、こちらの記事でまとめておりますので、よければご覧ください。 さて、この記事ではLangfuseを (GKEでHelm dependencyを使って) セルフホストするときに、個人的にハマってしまったポイントを整理してご紹介します。 ドキュメントを詳しく読めばわかるものも含まれますが、何かの参考になれば幸いです！ ＊ 本記事はLangfuse v3を対象としています Langfuseをセルフホストする場合、ローカルであればDocker Composeを、クラウド (k8s) であればHelm chartを使ってデプロイします。 この時、設定すべき環境変数が多数あります。ドキュメントには丁寧にまとめられており、またGitHubリポジトリを参考にすれば、Docker Composeを使ってのローカル環境では比較的簡単に立ち上げられます。（実際に git clone docker compose up 必須なものが必ずしも必須とは限らない ただ少し注意が必要なのが「一見requiredとして紹介されているが、他の環境変数と組み合わせると必須でなくなる」ものが存在する点です。例えばドキュメントではREDIS_CONNECTION_STRING このように「組み合わせで代替できるもの」がいくつか存在します。ただ代替が可能なものは以下のように明記されているため、事前にドキュメントに目を通しておくことをお勧めします。 Connection string of your redis instance. Instead of REDIS_CONNECTION_STRING 一方でEnvironment Variablesに載っていない環境変数も設定できます。例えば、プロジェクトなどの初期セットアップを行うために必要なLANGFUSE_INIT_PROJECT_ID 従って、環境変数でハマらないようにするには、事前にドキュメントページを (Environment Variablesだけでなく、関連しそうなページを全体的に) 読んでおくことをおすすめします。 ハマりポイント：Helm values k8sを使ってセルフホストする場合、公式配布されているHelmチャートを使う形になります。ドキュメントを見ると、概ねアプリケーション設定ごとにどのようにvaluesファイルに変数を設定すべきかが分かります。 ただし、Composeファイルで設定した環境変数をvaluesファイルではどのように書けば良いかが明記されていないものもあります。 そんな時はlangfuse-k8sのリポジトリにあるREADMEを見ることをおすすめします。READMEには必要なvalueやその指定方法が網羅されています。例えばlangfuse.salt langfuse.additionalEnv ただ「何をadditionalEnv AUTH_GOOGLE_CLIENT_ID AUTH_DISABLE_SIGNUP AUTH_DISABLE_SIGNUP langfuse.features.signUpDisabled AUTH_DISABLE_SIGNUP このほかにも「additionalEnv このポイントにハマらないようにするにはREADMEと睨めっこしながらも「実際にレンダリングを行って、意図通りの環境変数が作成されているか」をチェックすることをオススメします。 ハマりポイント：ClickHouse Langfuseではトレース保存用データベースとしてClickHouseを内部利用します。ClickHouseに関して、ハマりポイントが2つあったのでご紹介します。 いつの間にかいるZooKeeper Langfuseのドキュメントではその存在を見かけないのですが、実際にk8sでデプロイするとZooKeeperというPodが立っていることに気が付きます。この正体は「ClickHouseが内部的に利用する分散コーディネータ」になります。ClickHouseを複数レプリカ立てる時に、分散クエリの調整やテーブルメタデータの管理などをしてくれます。 この時、nodeSelector 逆に単一レプリカのnon-HA構成ならZooKeeperがデプロイされないかというとそういうわけではなく、デフォルトでデプロイされるようになっています。単一レプリカ時は不要になるので、Helmチャートでデプロイされないように指定する必要があります。(e.g., clickhouse.zookeeper.enabled: false （一点余談としては、ClickHouseは分散コーディネーターとしてClickHouse Keeperを推奨しているようですので、将来的にはLangfuseでZooKeeperを意識することもなくなるのかなと感じています） PVC作成ゾーンに気をつけろ これはLangfuseに限った話ではないですが、ClickHouseのPodがうまく立たない時に遭遇したものになります。 ClickHouseには永続ボリュームが必要なため、PVC (PersistentVolumeClaim) が作成されます。この時、環境や設定によっては「PVCとClickHouse Pod (k8s node) が存在するゾーンが互いに異なる」ことがあります。このような状況が発生すると、ClickHouse Podが永続ボリュームをマウントすることができず、Podが立ち上がってくれない事態が発生します。 これを避けるにはclickhouse.persistence.storageClass volumeBindingMode WaitForFirstConsumer PodがスケジュールされるまでPVCのバインディングを遅延 Podがスケジュールされるノードのゾーンに合わせてPVが作成される 今回の記事では、弊社のAIエージェントサービスで利用しているLangfuseについて、個人的にハマってしまったポイントをご紹介しました。公式のHelmチャートをそのまま利用する場合は強く意識せずともうまく立ち上がる気もしますが、既存のクラスタに取り込むなど、LangfuseをHelm dependencyでサブチャート化しようとした時に自分は苦しんでしまいました。 この躓きが誰かの参考になれば幸いです。

Langfuseセルフホストで遭遇した課題のまとめ

背景や根拠まで確認しますか？

関連記事

調べる

選ぶ

サイト