ガイド

著者 Matt Connor 2026-08-03 ・更新日 2026-08-27

Langfuseをセルフホストする方法と必要なVPS構成

Q: データ保持期間を設定した後も ClickHouse のディスク使用量が増え続けるのはなぜですか？

保持期間の設定が対象にするのは、Langfuse 自身のデータだけです。ClickHouse は診断用テーブル trace_log、text_log、opentelemetry_span_log、metric_log、asynchronous_metric_log も個別に書き込みます。これらには TTL が設定されていません。テーブル別に system.parts をグループ化して実行し、最も容量を使用しているテーブルを確認してください。その後、/etc/clickhouse-server/config.d/ 配下のファイルに remove="1" エントリを追加して未使用のテーブルを無効にし、ClickHouse を再起動します。すでに使用されている領域を解放するには、既存のテーブルも削除します。

Langfuse v4をVPSで運用する手順です。実際のリソース下限、固定するイメージタグ、TLS、ディスクを圧迫する前のClickHouse保持期間、復元できるバックアップを確認します。

AI エージェントを追跡する理由

Langfuse をセルフホストすると、エージェントが実行時に実際に何をしたかを確認できます。Langfuse は、オープンソースの LLM（大規模言語モデル）可観測性ツールです。すべてのプロンプト、モデルの応答、ツール呼び出し、トークンを記録し、それらを 1 つのトレースにまとめて開いて確認できるようにします。自分で管理する VPS で実行すれば、これらのプロンプトが自分の管理下にあるサーバーの外部へ送信されることはありません。

手間をかける理由は明確です。確認できないコストの問題や品質の問題は修正できません。プロバイダーの請求書からは、火曜日のコストが月曜日の 4 倍だったことは分かります。トレースからは、どのエージェント実行が原因だったか、どのプロンプトが 40,000 トークンまで増えたか、どの再試行ループが 9 回実行されてから失敗したかが分かります。請求書が示すのは数値です。トレースが示すのは、その数値を生み出したコードです。

このガイドでは、3 つの用語を使用します。トレースは、エージェントの最初から最後までの 1 回の実行です。オブザベーションは、その実行内の 1 つのステップです。通常のコードには span、モデルの呼び出しには generation を使用します。スコアは、人によるレビューまたは自動評価によってトレースに付与される数値です。Langfuse は、分散トレーシング向けのベンダー中立な標準である OpenTelemetry（OTel）に対応しているため、すでに導入している計装から Langfuse に送信できます。

セルフホストする Langfuse の実際の構成

Langfuse v4 は単一のコンテナではありません。2 つのアプリケーションコンテナと 4 つのストレージサービスで構成され、単一の VPS では 6 つすべてがサーバー上で動作します。

langfuse-web は Web インターフェースと取り込み API を提供します。
langfuse-worker はバックグラウンドでキューを処理します。取り込みバッチを解析し、コストを計算し、夜間の保持ジョブを実行します。
Postgres は、ユーザー、組織、プロジェクト、API キー、プロンプトなどのトランザクションデータを保持します。
ClickHouse は、オブザベーションやスコアなどのトレースデータ自体を保持します。分析クエリ向けに設計されたカラム型ストアであるため、1 億行を超えるデータに対するダッシュボードの応答も高速です。
Redis は、Web とワーカーの間に配置されるキューおよびキャッシュです。
MinIO は、サーバー上で S3 互換のオブジェクトストレージを提供します。すべての未加工の受信イベントと、添付したメディアを保持します。

Langfuse は、実際に処理を行う 3 つのコンポーネントについて最低限必要なリソースを公開しています。

ChartLangfuse published minimum resources per component

label

cpu_cores

memory_gib

ClickHouse

Langfuse web

Langfuse worker

The data behind this chart

[
  {
    "label": "ClickHouse",
    "cpu_cores": 2,
    "memory_gib": 8
  },
  {
    "label": "Langfuse web",
    "cpu_cores": 2,
    "memory_gib": 4
  },
  {
    "label": "Langfuse worker",
    "cpu_cores": 2,
    "memory_gib": 4
  }
]

ClickHouse だけで 8 GiB のメモリを必要とします。Web コンテナとワーカーは、それぞれ 4 GiB を必要とします。これは Langfuse がリソース要件を示している 3 個のコンポーネントに対する公開済みの最低値であり、Postgres、Redis、MinIO にも追加のメモリが必要です。プロジェクト独自の Docker Compose ガイドが 4 コア、16 GiB のメモリ、約 100 GiB のストレージを備えたマシンを推奨しているのは、この計算結果に沿ったものであり、余裕を過剰に見積もったものではありません。

2 GiB のプランで実行しようとしてはいけません。ClickHouse は起動してしばらく書き込みを受け付けますが、バックグラウンドマージ中に停止します。マージではテーブルの大きなパーツをメモリに読み込むためです。docker compose ps が clickhouse コンテナを restarting と報告し、dmesg に Out of memory: Killed process 1234 (clickhouse-serv) のような行が表示され、Langfuse のすべてのダッシュボードが 500 を返す状態になります。負荷が軽い場合、ClickHouse は代わりにクエリを拒否し、DB::Exception: Memory limit (total) exceeded をログに記録します。1 日に数千件のトレースを送信する 1 人の開発者であれば、8 GiB でも運用できます。計画時には 16 GiB を基準にしてください。同じ VPS で別の用途も実行する場合は、その分を別途見積もります。セルフホストの AFFiNE ワークスペースのように比較的軽いスタックでも、独自に数 GiB を必要とし、ClickHouse がメモリを返してくれることはないためです。

Docker Compose で Langfuse をデプロイする

リポジトリをクローンします。スタック、各サービスの接続設定、デフォルト環境はすべて docker-compose.yml に定義されています。

git clone https://github.com/langfuse/langfuse.git
cd langfuse

変更が必要な値には、すべてそのファイル内で # CHANGEME の印が付いています。最初に、3 つのアプリケーション Secret を生成します。

openssl rand -base64 32   # NEXTAUTH_SECRET
openssl rand -base64 32   # SALT
openssl rand -hex 32      # ENCRYPTION_KEY

ENCRYPTION_KEY は 64 個の 16 進文字で記述した 256 ビット値である必要があります。これは openssl rand -hex 32 がそのまま出力します。この値は、インスタンスに保存する LLM プロバイダーのキーなど、機密情報を保存時に暗号化します。データが存在する状態で変更すると、該当する行を復号できなくなります。そのため、初回起動時から永続的な値として扱ってください。SALT は Langfuse API キーのハッシュ化に使用されるため、変更するとエージェントが現在使用しているすべてのキーが無効になります。

次に POSTGRES_PASSWORD、CLICKHOUSE_PASSWORD、REDIS_AUTH、MINIO_ROOT_PASSWORD を設定します。MinIO のパスワードは 4 か所に記述されています。最初は MINIO_ROOT_PASSWORD として記述され、続いて LANGFUSE_S3_EVENT_UPLOAD_SECRET_ACCESS_KEY、LANGFUSE_S3_MEDIA_UPLOAD_SECRET_ACCESS_KEY、LANGFUSE_S3_BATCH_EXPORT_SECRET_ACCESS_KEY にも記述されます。1 か所でも漏れると、MinIO はそのクライアントを SignatureDoesNotMatch として拒否します。このエラーは worker のログに記録されますが、Web インターフェイスは正常に見えます。これらの値を追跡対象の compose ファイルではなく env ファイルに保持する方法については、Docker Compose の env ファイルと Secret で説明しています。

開始前にイメージタグを固定する

配布されているファイルでは langfuse/langfuse:4 と langfuse/langfuse-worker:4 が使用されています。これらのタグは更新されます。Langfuse は起動時に Postgres と ClickHouse のマイグレーションを自動実行します。そのため、数か月後の通常の docker compose pull が、その日の朝にバックアップしていなかったデータベースに対する、予定外のスキーママイグレーションになる可能性があります。両方を 1 つのリリースに固定し、docker-compose.override.yml に記述してください。Compose はこれを配布ファイルに重ねて適用するため、後の git pull によって編集内容が上書きされることはありません。

services:
  langfuse-web:
    image: docker.io/langfuse/langfuse:4.3.1
  langfuse-worker:
    image: docker.io/langfuse/langfuse-worker:4.3.1

2026 年 8 月時点では、4.3 リリースの最新版は 4.3.1 でした（その後 4.4.0 がリリースされています）。プロジェクトの GitHub リリースページを確認し、デプロイ当日に最新版の番号を固定してください。その後は、意図的に番号を更新します。配布ファイル内のストレージイメージはすでにメジャーバージョンとして、postgres:17、clickhouse-server:25.12、redis:7 に固定されています。これらも同じように扱ってください。このルールは Langfuse 固有のものではありません。自己ホスト型の openGym ワークアウトトラッカーはこのスタックの一部だけを使用しますが、それでも名前付きの git タグを必要とします。起動時にデータベースを自動マイグレーションするソフトウェアでは、通常の pull がスキーマ変更になる可能性があるためです。

起動します。

docker compose up -d
docker compose ps
docker compose logs -f langfuse-worker

初回起動ではマイグレーションが実行されるため、応答が始まるまで 1、2 分待ってください。docker compose ps では、状態 running のサービスが 6 つ表示されるはずです。worker がループして再起動する場合は、ログに原因が記録されています。CLICKHOUSE_MIGRATION_URL はポート 9000 の ClickHouse ネイティブプロトコルを使用します。HTTP ポートの 8123 を指定すると worker は失敗しますが、Web コンテナは正常に見えます。

サーバー自身からヘルス状態を確認します。

curl -s "http://localhost:3000/api/public/health?failIfDatabaseUnavailable=true"
curl -s -o /dev/null -w '%{http_code}\n' http://localhost:3000/api/public/ready

通常の /api/public/health リクエストで確認できるのは、API プロセスが稼働していることだけです。これは、データベースを意図的に確認対象から外しているためです。Postgres が一時的に停止しても、サービスは処理を継続できます。監視対象にするなら failIfDatabaseUnavailable=true 形式を使用してください。データベースに到達できない場合は 503 を返します。マイグレーションが完了してコンテナがトラフィックを受け付けると、/api/public/ready は 200 を返します。どちらも通常の HTTP チェックです。そのため、Uptime Kuma のステータスページで監視し、エージェントが異常を検知する前にスタックの停止を把握できます。

TLS を前段に置き、不要なポートを閉じる

付属の Compose ファイルは、Web コンテナ用に 3000:3000、MinIO 用に 9090:9000 を公開します。どちらもすべてのインターフェースで待ち受けます。パブリック IP で運用すると、ポート 3000 をスキャンした誰もがサインアップページに到達でき、ポート 9090 をスキャンした誰もが raw prompt を格納するバケットに接続できます。

ファイアウォールルールだけでは、これらのポートは閉じません。Docker は nat テーブルに独自の DNAT ルールを書き込みます。パケットは ufw の filter ルールで処理される前に DNAT ルールで評価されるため、ufw deny 3000 だけでは公開ポートが開いたままになります。この問題は多くの利用者が遭遇するため、専用のガイドがあります: Docker の公開ポートが ufw を迂回する理由。代わりに、override ファイルで loopback にバインドします。

services:
  langfuse-web:
    ports:
      - "127.0.0.1:3000:3000"
    environment:
      NEXTAUTH_URL: https://langfuse.example.com
  minio:
    ports:
      - "127.0.0.1:9090:9000"
      - "127.0.0.1:9091:9001"

NEXTAUTH_URL には、スキームを含む正確な公開アドレスを指定する必要があります。ログインフローは、この値からコールバック URL を構築するためです。HTTPS プロキシの背後で http://localhost:3000 のままにすると、サインインの往復処理でブラウザーが到達できない場所へ転送されます。

次に、リバースプロキシから 127.0.0.1:3000 に転送し、証明書をリバースプロキシで管理します。同じ Compose プロジェクト内の Traefik が通常の選択肢です。ルーティングラベルについては、1 台の Traefik リバースプロキシで複数のアプリを運用するで説明しています。Langfuse だけをそのホストで運用するなら、Caddy でも 2 行で同じことができます。curl -sI https://langfuse.example.com/api/public/ready で確認し、別のマシンから curl http://YOUR_IP:3000 がタイムアウトすることを確認します。

MinIO には注意点があります。Langfuse は、S3 エンドポイントを指す presigned URL を使って、添付メディアをブラウザーに配信します。そのため、画像や音声を含むマルチモーダルな trace を使う場合、MinIO を loopback のみにすると添付ファイルを読み込めません。MinIO をプロキシの背後に置く前に、blob storage の設定ページを確認してください。presigned URL に書き込まれるエンドポイントは、公開するエンドポイントと一致している必要があります。プレーンテキストの trace には影響しません。

初回アクセス時に自分のアカウントを作成し、そのインスタンスを自分で管理します。LANGFUSE_ALLOWED_ORGANIZATION_CREATORS には自分のメールアドレスを設定してください。これにより、ページに到達した第三者がサーバー上に組織を作成できなくなります。すでに自分の identity provider として Authentik を運用している場合、Langfuse は標準の OIDC 接続を利用できます。アカウントを、このホストだけが把握するパスワード一覧ではなく、ほかのアプリと同じ identity provider で管理できます。

最初のトレースを送信する

Web インターフェースでプロジェクトを作成し、プロジェクト設定から公開キーとシークレットキーをコピーします。Python SDK は3つの環境変数を読み取ります。

export LANGFUSE_PUBLIC_KEY="pk-lf-..."
export LANGFUSE_SECRET_KEY="sk-lf-..."
export LANGFUSE_BASE_URL="https://langfuse.example.com"

LANGFUSE_BASE_URLは SDK v4 での変数名です。SDK v4 は2026年3月にリリースされました。古いコードや古いガイドでは LANGFUSE_HOST が使われています。トレースがサーバーではなく Langfuse Cloud に送られる場合、原因は base URL が未設定であることです。未設定の場合、デフォルトでホスト版インスタンスが指定されます。

pip install langfuse opentelemetry-instrumentation-anthropic anthropic

import os
from anthropic import Anthropic
from langfuse import get_client, observe
from opentelemetry.instrumentation.anthropic import AnthropicInstrumentor

AnthropicInstrumentor().instrument()
langfuse = get_client()
client = Anthropic(api_key=os.environ["ANTHROPIC_API_KEY"])

@observe(as_type="tool")
def lookup_order(order_id: str) -> str:
    return f"order {order_id}: shipped"

@observe()
def handle_request(question: str) -> str:
    context = lookup_order("A-1042")
    message = client.messages.create(
        model="claude-haiku-4-5",
        max_tokens=512,
        messages=[{"role": "user", "content": f"{context}\n\n{question}"}],
    )
    return message.content[0].text

if __name__ == "__main__":
    assert langfuse.auth_check()
    print(handle_request("Where is my order?"))
    langfuse.flush()

@observe デコレーターは関数の周囲に observation を作成し、引数と戻り値を取得します。すでに有効な observation がある場合は、その配下にネストします。AnthropicInstrumentor は Anthropic クライアント用の OpenTelemetry 計装です。各 messages.create 呼び出しを、モデル名、トークン使用量、レイテンシを含む generation に変換します。呼び出し側のコードを変更する必要はありません。

2 つの呼び出しで確認を自動化できます。langfuse.auth_check() はキーが不正な場合やベース URL が誤っている場合に False を返すため、ダッシュボードが空の理由を調べ続けるよりも迅速です。langfuse.flush() はキューに入った span が送信されるまでブロックします。SDK はバックグラウンドでバッチ処理するため、短時間で終了するプロセスではこれが必要です。スクリプトが直ちに終了すると、未送信のバッチも失われます。1 つのスクリプトではなくチーム全体で trace を送信する場合は、これら 3 つの変数を各自の shell ではなく、全員の agent がすでに経由している gateway で一度だけ設定します。これにより、自己ホスト型 OneCLI ハーネスで各メンバーの実行を常に計測対象にしながら、キーを 1 か所で管理できます。

ClickHouse のデータが増え続けるのはなぜですか？

トレースは、多くの人が自己ホストするデータの中で最も速く増加します。エージェントを 1 回実行するたびにステップごとに 1 行が書き込まれ、入力と出力も完全な形で保存されます。そのため、プロンプトが長く、ログ出力の多いエージェントは、監視対象のアプリケーションよりも 1 日あたりのデータ量がはるかに多くなります。放置すると ClickHouse がディスクを使い切り、ディスクが満杯になると取り込みは遅くなるのではなく停止します。

ここでは別々の 2 つが増加するため、それぞれに別の対策が必要です。

1 つ目は独自のトレースデータです。対策は保持期間の設定です。Web インターフェースでプロジェクト設定を開き、データ保持期間を日数で設定します。Langfuse では最小 3 日を指定できます。夜間ジョブがその期間より古いトレース、オブザベーション、スコア、メディアアセットを選択し、ClickHouse と blob storage から削除します。このジョブにはバケットへの DeleteObject 権限が必要です。デフォルトの compose ファイルにある MinIO の root 認証情報には、すでにこの権限があります。削除したデータは復元できないため、長期的な履歴が必要な場合は、先に blob storage へエクスポートを設定してください。Langfuse 自身のテーブルに TTL 句を手動で記述しないでください。ClickHouse とバケットの状態を一致させるのは保持ジョブであり、手動の TTL では片方だけが削除されます。

実際の利用状況に基づいて保持期間を選びます。コストや品質の確認に使うのは、数か月前のデータではなく数日前のデータです。小規模なチームなら 30 日から始めるのが妥当です。問題が発生したときだけトレースを確認するなら、14 日で十分です。

2 つ目は ClickHouse 自身のシステムログテーブルです。保持期間を設定した後もディスク使用量が増え続けるため、ここが原因だと気付きにくいことがあります。ClickHouse は診断情報用に trace_log、text_log、opentelemetry_span_log、metric_log、asynchronous_metric_log を書き込みます。これらには TTL が設定されておらず、Langfuse が読み取ることもありません。まず、実際にどこでディスクを使用しているかを確認します。

SELECT table, formatReadableSize(size) AS size, rows FROM (
    SELECT table, database, sum(bytes) AS size, sum(rows) AS rows
    FROM system.parts
    WHERE active
    GROUP BY table, database
    ORDER BY size DESC
)

docker compose exec clickhouse clickhouse-client --password "$CLICKHOUSE_PASSWORD" を指定して実行します。システムテーブルが上位にある場合は、設定オーバーレイで無効にします。ClickHouse は起動時に /etc/clickhouse-server/config.d/ 内のすべてのファイルをメイン設定に統合するためです。

<clickhouse>
    <trace_log remove="1"/>
    <text_log remove="1"/>
    <opentelemetry_span_log remove="1"/>
    <asynchronous_metric_log remove="1"/>
    <metric_log remove="1"/>
</clickhouse>

これをマウントして ClickHouse を再起動します。

services:
  clickhouse:
    volumes:
      - ./clickhouse-config.d/system-logs.xml:/etc/clickhouse-server/config.d/system-logs.xml:ro

これで新しい書き込みは停止します。ただし、すでにディスク上にある行は残るため、DROP TABLE IF EXISTS system.trace_log を明示的に実行して容量を回収し、削除した各テーブルでも同じ操作を行います。診断情報を残す場合は、remove="1" の代わりに各テーブルへ積極的な TTL を設定する方法もあります。詳しくは Langfuse のスケーリングに関するドキュメントで説明されています。

もう 1 つ、把握しておく価値のあるテーブルがあります。blob_storage_file_log は、バケットにアップロードされたイベントファイルを追跡します。バケットにもライフサイクルポリシーを設定する場合は、テーブルにも対応する TTL を設定し、両者の状態がずれないようにします。

ALTER TABLE blob_storage_file_log MODIFY TTL created_at + INTERVAL 30 DAY DELETE;

データディスクには、単純な df -h アラートも設定してください。トレースは一定のペースでは増えません。新しいエージェントをリリースした日に増加します。その最初の兆候が、取り込みの失敗にならないようにしてください。

Postgres と ClickHouse をバックアップする

Langfuse のバックアップは 3 つの部分で構成されます。Postgres にはユーザー、組織、プロジェクト、API キーが保存されます。ClickHouse にはトレースが保存されます。MinIO には未加工のイベントが保存されます。Postgres だけを復元すると、ログインはできても履歴がない状態になります。ClickHouse だけを復元すると、履歴はあっても誰もログインして確認できません。この分離構成は Langfuse 固有のものではありません。自己ホスト型 Chatwoot のサポートデスクでも同様で、uploads ディレクトリなしで取得した Postgres ダンプを復元すると、添付ファイルがすべて失われた会話だけが復元されます。

Postgres は単純な pg_dump であり、Langfuse のバックアップドキュメントでもこの方法が推奨されています。

docker compose exec -T postgres pg_dump -U postgres postgres \
  | gzip > langfuse-pg-$(date +%F).sql.gz

ClickHouse では、マージの実行中にライブのデータディレクトリをコピーすると、一貫性のあるバックアップにならないため、より注意が必要です。1 台のサーバーで行う簡単な方法は、コンテナを停止してボリュームをアーカイブすることです。

docker compose stop clickhouse
docker volume ls | grep clickhouse
docker run --rm -v langfuse_langfuse_clickhouse_data:/data -v "$PWD":/backup alpine \
  tar czf /backup/langfuse-ch-$(date +%F).tar.gz -C /data .
docker compose start clickhouse

YAML に記載された名前ではなく、docker volume ls が表示するボリューム名を使用します。ファイルでは langfuse_clickhouse_data と宣言されていますが、Compose はプロジェクト名を前置します。そのため、langfuse というディレクトリでクローンすると langfuse_langfuse_clickhouse_data になります。名前を間違えると、docker run はエラーを出さずに新しい空のボリュームを作成するため、アーカイブには何も含まれません。

Web コンテナは受信した各イベントをワーカーが処理する前にバケットへ書き込みます。そのため、ClickHouse を短時間停止しても、主にワーカーが後で再試行するだけです。利用の少ない時間帯に実施し、停止時間を短くしてください。負荷の高いインスタンスでは、ClickHouse 独自の BACKUP DATABASE default TO S3(...) 文を使用すると、サーバーを停止せずに一貫性のあるバックアップを書き出せます。MinIO が 3 つ目の要素であり、mc mirror または MinIO からサーバー外のバケットへのレプリケーションで対応できます。作成したバックアップは必ずサーバー外へ移してください。VPS 上の暗号化された restic バックアップはそのために使用します。

Redis はバックアップ不要です。キューとキャッシュを保持しているため、失うのは現在処理中のイベントだけで、過去のデータは失われません。

一貫性に関する注意点は実際に存在するため、明確にしておく必要があります。Postgres と ClickHouse は異なる時点でダンプされるため、復元後にトレースのないプロジェクト行が残ったり、存在しなくなったプロジェクトに属するトレースが残ったりする可能性があります。Langfuse はこの状態を許容しますが、2 つのダンプは近い時間に、トラフィックの少ない時間帯に取得してください。イベントバケットが実質的な安全網です。Langfuse は受信した各イベントを処理前にそこへ保存するためです。

少なくとも 1 回はスクラッチ環境へ復元してください。これにより、障害発生中ではなく、今の段階でボリューム名の誤りを確認できます。

最初に確認すること

最初の 1 週間で確認する価値があるのは、次の 4 つです。

トレースあたりのコスト。 Langfuse はモデル名とトークン使用量からコストを計算します。トレースをコスト順に並べ、最も高額なものを最初から最後まで読みます。原因は通常、肥大化したプロンプトです。文書全体をコンテキストに貼り付けている場合や、誰も整理していない会話履歴が含まれている場合があります。原因を確認できれば、AI エージェントのコストを制御する方法は推測ではなく、エンジニアリング上の作業になります。
入力と出力に分けたトークン使用量。 入力トークンは数が多く、単価が低い一方、出力トークンは数が少なく、単価が高くなります。キャッシュされた入力はさらに安価です。同じ計算方法を Claude Code のトークン使用量の数え方で詳しく説明しています。この考え方は、自作するエージェントにも適用できます。
レイテンシのパーセンタイル。 中央値では問題が隠れます。タイムアウトは p95 と p99 に現れます。エージェントループ内では、p95 の遅いツール呼び出しが反復回数分だけ増幅されます。
失敗したツール呼び出し。 レベル ERROR で観測結果を絞り込みます。5% の確率で失敗するツールは、全体の成功率では見えません。しかしトレースでは明確に確認できます。モデルが再試行し、その問題を回避するためにトークンを消費する様子を監視できます。

保持期間を設定し、毎週同じ曜日に確認するダッシュボードを、デプロイする日に決めます。誰も開かない可観測性ツールは、ディスクを埋めるだけのデータベースです。

FAQ

自己ホスト型の Langfuse にはどの程度のメモリが必要ですか？

4 CPU コア、16 GiB のメモリ、約 100 GiB のストレージを確保してください。これは、1 台の仮想マシンで運用する場合に Langfuse の Docker Compose ガイドが推奨する構成です。公開されているコンポーネントの最小値は、ClickHouse が 8 GiB、web コンテナと worker コンテナがそれぞれ 4 GiB です。これらに加えて、Postgres、Redis、MinIO にもメモリが必要です。8 GiB なら 1 人の開発者が使うインスタンスを実行できます。2 GiB では不足します。バックグラウンドマージ中に ClickHouse がカーネルによって強制終了され、dmesg に Out of memory: Killed process が表示されます。

データ保持期間を設定した後も ClickHouse のディスク使用量が増え続けるのはなぜですか？

保持期間の設定が対象にするのは、Langfuse 自身のデータだけです。ClickHouse は診断用テーブル trace_log、text_log、opentelemetry_span_log、metric_log、asynchronous_metric_log も個別に書き込みます。これらには TTL が設定されていません。テーブル別に system.parts をグループ化して実行し、最も容量を使用しているテーブルを確認してください。その後、/etc/clickhouse-server/config.d/ 配下のファイルに remove="1" エントリを追加して未使用のテーブルを無効にし、ClickHouse を再起動します。すでに使用されている領域を解放するには、既存のテーブルも削除します。

Langfuse の最小データ保持期間はどのくらいですか？

3 日間です。保持期間はプロジェクト設定でプロジェクトごとに設定するか、projects API で設定します。夜間ジョブにより、保持期間より古い traces、observations、scores、media assets が ClickHouse と blob storage の両方から削除されます。削除したデータは元に戻せません。この期間を超える履歴が必要な場合は、先に blob storage へのエクスポートを設定してください。

Postgres と ClickHouse の両方をバックアップする必要がありますか？

はい。両者が異なるデータを保持しているためです。Postgres には users、organisations、projects、API keys が保存され、ClickHouse には trace データ自体が保存されます。Postgres だけを復元すると、ログインはできますがデータのないインスタンスになります。MinIO バケットもバックアップしてください。到着時に Langfuse が永続化する raw events が保存されており、このスタックでは source of truth に最も近いデータだからです。

既存の OpenTelemetry 構成を self-hosted Langfuse に接続できますか？

はい。Langfuse v4 とその v4 SDK は OpenTelemetry を基盤としており、Anthropic と OpenAI の OTel instrumentation は Langfuse へ直接 export できます。Python では pip install langfuse opentelemetry-instrumentation-anthropic を実行し、起動時に AnthropicInstrumentor().instrument() を 1 回呼び出します。LANGFUSE_PUBLIC_KEY、LANGFUSE_SECRET_KEY、LANGFUSE_BASE_URL には自分のホストを設定してください。見つからない dashboard を調べる前に、langfuse.auth_check() で確認します。

#langfuse#observability #llm #docker-compose #self-hosting