Self-hosted を選ぶ理由

LangfuseはSaaS（Cloud）とSelf-hostedの両方を公式提供しています。 Self-hostedが選ばれる主な理由は4つです。

  • データレジデンシー: GDPR/HIPAA/国内法でLLMの入出力を第三者サービスに送れない
  • コスト: 月数十M events を超えるとCloudより自社運用のほうが安くなる
  • 社内LLM連携: プライベートVPC内のモデル/DBにアクセスする必要
  • カスタマイズ: プラグイン的に社内認証・監査ログ・SSOを深く結合したい

4つのデプロイオプション

方式 向く規模 強み 弱み
Docker Compose 開発〜数チーム one-linerで立ち上がる。Simplify for Scale以降はAll-in-one HA性なし。プロダクションは非推奨（検証用）
Helm Chart 中規模〜大規模 K8sネイティブ。Web/Worker分離、HPAで水平スケール K8s運用知識が必要
Terraform IaC前提の組織 AWS/GCP公式モジュール。VPC・RDS・EKSまで一括 クラウドベンダー固有のアップデート追随
Railway / その他PaaS スタートアップ GitHub連携で即デプロイ。運用自動化 カスタマイズ幅は狭い

本番リファレンス構成

graph TB
  LB[Load Balancer<br/>TLS終端]
  LB --> W1[Web Pod 1]
  LB --> W2[Web Pod 2]
  LB --> W3[Web Pod 3]
  W1 --> PG[(Postgres HA)]
  W1 --> REDIS[(Redis Sentinel)]
  W1 --> S3[(S3 / MinIO)]
  W1 --> CH[(ClickHouse Keeper<br/>3 shard × 2 replica)]
  WK1[Worker Pod 1]
  WK2[Worker Pod 2]
  REDIS --> WK1
  REDIS --> WK2
  WK1 --> CH
  WK1 --> S3
  PROM[Prometheus] -.scrape.-> W1
  PROM -.scrape.-> WK1
  GRAF[Grafana] --> PROM
本番リファレンス構成: TLS終端LBの後ろにWeb 3Pod、Worker 2Pod、ClickHouseは3shard×2replica、Redis Sentinel、Postgres HA、S3(MinIO可)。Prometheus/Grafanaで監視

Headless Initialization

Self-hostedの初期セットアップは従来 UI での手動登録が必要でしたが、 Headless Initialization を使えば環境変数だけで組織・プロジェクト・APIキーを事前作成できます。 

# Web Container env
LANGFUSE_INIT_ORG_ID=my-org
LANGFUSE_INIT_ORG_NAME="My Org"
LANGFUSE_INIT_PROJECT_ID=default
LANGFUSE_INIT_PROJECT_NAME="Default Project"
LANGFUSE_INIT_PROJECT_PUBLIC_KEY=pk-lf-xxxxxxxx
LANGFUSE_INIT_PROJECT_SECRET_KEY=sk-lf-yyyyyyyy
LANGFUSE_INIT_USER_EMAIL=admin@example.com
LANGFUSE_INIT_USER_NAME=Admin
LANGFUSE_INIT_USER_PASSWORD=<strong>

水平スケールの指標

シグナル 意味 HPAルール例
Web CPU % UI/API負荷 CPU 60%超でPod増
Worker Lag (Redis XLEN) Ingestion未処理数 Lag > 10,000 でWorker増
ClickHouse insert queue CH書き込み遅延 shard追加 or batch size増
Redis memory % キュー+キャッシュ 75%超で容量up
Postgres connections 接続プール枯渇 PgBouncer導入 / レプリカ追加

運用の落とし穴 Top 8

  1. タイムゾーン: サーバ・DB・ClickHouseすべて UTC で揃える。JSTなどにするとダッシュボード集計がズレる
  2. ClickHouseバージョン: 24.3+ 推奨。古いとReplacingMergeTreeの挙動が異なりクエリ互換性に影響
  3. Redis永続化: AOF有効化 + persistent volume。キュー消失はingestion欠損に直結
  4. S3バケット権限: Web/Workerで同一バケットに書き/読みできる必要。lifecycleルールで古いpayload削除
  5. TLS終端: Ingress / ALB / Cloudflare などで行う。自己署名は避ける（SDKで証明書エラー）
  6. NEXTAUTH_URL: 外部公開URLと正確に一致させる。OAuthリダイレクト失敗の典型原因
  7. 秘密鍵の長さ: NEXTAUTH_SECRET / SALT は32文字以上のランダム値。短いと認証事故
  8. バックアップ: Postgres（メタデータ）+ ClickHouse（Trace本体）+ S3（原本）の3系統をすべて。S3だけあれば再構築可能なのでここが最後の砦

シークレット管理

# 必須シークレット
NEXTAUTH_SECRET=$(openssl rand -base64 32)        # セッション暗号化
SALT=$(openssl rand -base64 32)                   # APIキーハッシュ
ENCRYPTION_KEY=$(openssl rand -hex 32)            # DBフィールド暗号化

# DB
DATABASE_URL=postgresql://user:pass@pg:5432/langfuse
CLICKHOUSE_URL=http://clickhouse:8123
CLICKHOUSE_MIGRATION_URL=clickhouse://clickhouse:9000

# Redis
REDIS_CONNECTION_STRING=redis://redis:6379

# S3
LANGFUSE_S3_EVENT_UPLOAD_BUCKET=langfuse-events
LANGFUSE_S3_EVENT_UPLOAD_ACCESS_KEY_ID=<aws-key>
LANGFUSE_S3_EVENT_UPLOAD_SECRET_ACCESS_KEY=<aws-secret>
LANGFUSE_S3_EVENT_UPLOAD_REGION=ap-northeast-1

# OAuth (任意)
AUTH_GOOGLE_CLIENT_ID=...
AUTH_GOOGLE_CLIENT_SECRET=...

監視・アラート

メトリック 警告しきい値 対応
ingestion_queue_lag > 10,000 events が 5分以上 Worker Pod追加 / ClickHouse負荷確認
web_5xx_rate > 1% ログ確認・DB接続確認
clickhouse_insert_error > 0 ClickHouse Keeper/shard 健康確認
postgres_connection_exhaustion > 80% PgBouncer / プール拡張
redis_memory_usage > 80% TTL短縮 / メモリ追加
s3_4xx/5xx_rate > 0.1% バケット権限・quota確認
openai_llm_eval_fail_rate > 5% Managed Evaluator モデルのフェイルオーバー設定確認

バックアップ戦略

graph LR
  PG[(Postgres)] -->|pg_basebackup<br/>日次| PGBK[Postgres Snapshot]
  CH[(ClickHouse)] -->|BACKUP TO S3<br/>日次| CHBK[ClickHouse Snapshot]
  S3PRIMARY[(S3 Primary)] -->|Cross-Region Replication| S3DR[(S3 DR)]
  PGBK --> S3BK[(S3 Backup Bucket)]
  CHBK --> S3BK
3系統バックアップ: Postgres日次 / ClickHouse日次 / S3 Cross-Region Replication。S3原本があれば最終的にTrace再構築が可能

v2 → v3 マイグレーション

既存のv2（Postgres単一）からv3（Postgres + ClickHouse + Redis + S3）へのアップグレードは公式スクリプトで支援されますが、 大規模データではダウンタイム最小化のための 段階的移行 が推奨です。

  1. 事前準備: ClickHouse / Redis / S3を別途構築。v2は稼働継続
  2. Dual-write期間: v3 Webを並列起動し、新規TraceはPostgres + ClickHouseの両方に書く（SDKはどちらに送ってもOK）
  3. バックフィル: v2 Postgresの過去Traceを公式スクリプトでClickHouseへ移送。数TB規模なら数日〜数週間見る
  4. 読み取り切替: UIのデータ読み取りをClickHouseに切替。レポートの数字が一致することを確認
  5. v2停止: Postgres側のtrace/observation/scoreテーブル書き込みを停止（ただしテーブルは残す）
  6. v3化完了: 一定期間後にテーブル削除

規模別コストの目安

規模 構成 月額インフラ費の目安（AWS東京）
〜1M events/月 Single-container (Docker Compose) 約 $50〜100 (t3.large + EBS)
〜10M events/月 EKS Web 2 + Worker 1 + RDS + OpenSearch不要 約 $500〜800
〜100M events/月 EKS Web 3 + Worker 3 + RDS HA + CH 3node + ElastiCache + S3 約 $2,500〜4,000
〜1B events/月 CH 6 shard × 2 replica + Operator + multi-AZ 約 $10,000〜20,000

まとめ

最終章では、こうして運用された事例としてMerck myGPT・LayerX・ZOZO・Seven-Eleven・Canva・Khan Academy・Samsaraの採用と、ClickHouse合流後の展望、学習ロードマップを見ていきます。

理解度チェック

問題 0 / 50%
Q1

Langfuse Self-hosted の本番運用で 必須 に近い要件として正しいものはどれか？

キーボード: 1〜4 で選択、Enter で回答