Langfuse に機能を追加してマージされるまで：日本語コントリビュートガイド

LLM オブザーバビリティプラットフォーム「Langfuse」に機能を追加して、PR がマージされるまでの過程を紹介します。環境構築でハマったポイントや解決方法もまとめているので、日本語でのコントリビュートガイドとしてもお使いください。

この記事で得られること

#

• Langfuse 開発環境のセットアップ手順
• 実際に遭遇したエラーと解決法
• セルフホスト/クラウドモードの違いと切り替え方
• PR 作成時のベストプラクティス

コントリビュートの背景

#

セルフホスト環境で Langfuse を使っていて、Vertex AI の認証に Application Default Credentials（ADC） を使いたかったのですが、その機能がありませんでした。AWS Bedrock には既に ADC 対応があったので、Vertex AI にも同様の機能を実装することにしました。

成果: PR #11039 がv3.140.0でマージされました 🎉 （私の PR #10915 が取り込まれたもの）

まずは公式ドキュメントを読もう

#

Langfuse には充実したコントリビュートガイド があります。必要なツール、セットアップ手順、コミット規約、テスト方法まで丁寧に書かれているので、まずはこれを一読することを強くおすすめします。

この記事は公式ドキュメントを補足するもので、「読んだけどハマった」ポイントを中心に書いています。

必要なツール一覧

#

公式ドキュメントの内容を日本語で整理します。

インストール方法は環境によって異なるので、各ツールの公式ドキュメントを参照してください。

Docker で起動するコンテナ

#

pnpm run dx を実行すると、以下の 4 つのコンテナが起動します。

環境構築でハマったこと

#

1. pnpm not found

#

zsh: command not found: pnpm

原因: corepack が有効化されていない、または pnpm がインストールされていない

解決方法:

# 方法1: corepack を有効化
corepack enable

# 方法2: npm でグローバルインストール
npm install -g pnpm

2. golang-migrate がない

#

Error: migrate: command not found

原因: 公式ガイドに書いてあるが見落としがち

解決方法:

brew install golang-migrate

📝 補足: golang-migrate は ClickHouse のマイグレーションに使われます。PostgreSQL は Prisma を使いますが、ClickHouse は Prisma がサポートしていないため、別のツールが必要です。

3. ~/package-lock.json の罠

#

Error: Cannot find module '@langfuse/shared'

原因: ホームディレクトリ（~）に古い package-lock.json があると、Node.js のモジュール解決がおかしくなることがある

解決方法:

# ホームディレクトリの package-lock.json を削除
rm ~/package-lock.json

# node_modules もクリーン
cd ~/langfuse
pnpm run nuke  # 全ての node_modules と build ファイルを削除
pnpm install

4. ポート 5432 競合

#

Error: listen EADDRINUSE: address already in use :::5432

原因: 他のアプリケーション（Docker環境であるRancher Desktop）の PostgreSQL コンテナがポート 5432 を使用していた

解決方法: .env ファイルでポートを変更

# ポート番号を変更
POSTGRES_HOST_PORT=5433

# データベース URL も同じポートに
DATABASE_URL="postgresql://postgres:postgres@localhost:5433/postgres"
DIRECT_URL="postgresql://postgres:postgres@localhost:5433/postgres"

5. セルフホストとクラウドモード設定

#

これが一番のハマりポイントでした！

機能を実装したのに、UI に ADC のオプションが表示されない…

原因

#

環境変数 NEXT_PUBLIC_LANGFUSE_CLOUD_REGION でアプリの動作モードが決まります。.env.dev.example には以下の設定があります。

NEXT_PUBLIC_LANGFUSE_CLOUD_REGION="DEV"

この値が設定されていると、Boolean(“DEV”) は true になるため、クラウドモードとして動作します。

// 判定ロジック（fetchLLMCompletion.ts）
const isLangfuseCloud = Boolean(env.NEXT_PUBLIC_LANGFUSE_CLOUD_REGION);
const isSelfHosted = !isLangfuseCloud;

クラウドモードでは、セルフホスト専用機能（ADC など）が UI に表示されません。

解決方法

#

.env でこの行をコメントアウトします。

# コメントアウトする
# NEXT_PUBLIC_LANGFUSE_CLOUD_REGION="DEV"

サーバーを再起動すると、ADC オプションが表示されるようになります。

モードの違い

#

見分け方

#

ログイン画面を見れば、どちらのモードで動いているかすぐわかります。

• クラウドモード: 「Data Region」セレクターが表示される

• セルフホストモード: シンプルなログインフォームのみ

開発の始め方

#

1. Fork & Clone

#

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

2. 依存関係のインストール

#

pnpm install

3. 環境変数の設定

#

cp .env.dev.example .env

.env を編集します。

1. NEXT_PUBLIC_LANGFUSE_CLOUD_REGION をコメントアウト（セルフホスト機能をテストする場合）
2. 必要ならポート番号を変更

4. 開発サーバーの起動

#

# 初回（DB リセットあり、時間がかかる）
pnpm run dx

# 2回目以降
pnpm run dev

5. 動作確認

#

http://localhost:3000 を開き、テストユーザーでログインします。

• Email: demo@langfuse.com
• Password: password

プロジェクト構造

#

Langfuse は pnpm + Turborepo のモノレポ構成です。

langfuse/
├── web/              # Next.js フロントエンド + API
├── worker/           # 非同期処理ワーカー
├── packages/
│   └── shared/       # 共有コード（スキーマ、ユーティリティ）
├── ee/               # Enterprise 機能
└── fern/             # OpenAPI 仕様

技術スタック

#

PR 作成時に気をつけること

#

Conventional Commits を使う

#

feat(llm): add ADC support for Vertex AI
fix(security): prevent projectId specification
refactor(llm): rename useADC to shouldUseDefaultCredentials

提出前チェックリスト

#

# コード整形
pnpm format

# Lint チェック
pnpm run lint

CI について

#

PR を作成すると、以下のチェックが自動実行されます。

• CLA assistant: 初回は Contributor License Agreement への署名が必要
• depthfirst-app bot: AI による自動コードレビュー
• dosubot: 自動ラベル付け

全てパスすると、メンテナーによるレビューに進みます。

PR の流れ（実体験）

#

私の PR は以下の流れで進みました。

1. PR 作成 → 3 つの自動チェックが走る
2. CLA 署名 → CLA assistant が署名を要求
3. AI レビュー → depthfirst-app bot がレビュー（ここで弾かれた場合は修正 or コメントを残す）
4. 人間レビュー → メンテナーから changes requested
5. 修正 → フィードバック対応

——–ここからはメンテナーが対応——- 6. マージ → 作業ブランチへマージ 7. 本番マージ → メンテナーが main へマージする PR を作成

まずは3.のAI レビューのCIが通るまでが我々が行う作業です。

ここまで行けたら、メンテナーに知らせたりすると良いと思います！

その他知っておくと良いこと

#

今回の PR では使わなかったものもありますが、参考までに。

1. 大きな変更は Issue を先に立てる: 公式ガイドにも記載されています
2. Discord で質問できる: 困ったことがあれば Discord で質問可能
3. good first issue から始める: 初コントリビュートなら good first issue ラベルがおすすめ

まとめ

#

Langfuse へのコントリビュートは、充実した公式ドキュメントのおかげでスムーズに進められました。環境構築では特に NEXT_PUBLIC_LANGFUSE_CLOUD_REGION の設定に注意が必要です。

レビューはとても丁寧で、変数名の改善やセキュリティの考慮点など建設的なフィードバックがもらえます。厳しく詰められるようなことはないので、安心して PR を出してみてください。

日本からも OSS にどんどん貢献していきましょう！

参考リンク

#

• Langfuse GitHub
• Langfuse 公式ドキュメント
• コントリビュートガイド
• Discord
• PR #11039