Langfuseエクスポーター

Koogは、AIアプリケーションの可観測性と分析のためのプラットフォームであるLangfuseへのエージェントのトレースのエクスポートを組み込みでサポートしています。 Langfuse連携により、KoogエージェントがLLM、API、その他のコンポーネントとどのように連携するかを可視化、分析、デバッグできます。

KoogのOpenTelemetryサポートに関する背景情報については、OpenTelemetryサポートを参照してください。

---

セットアップ手順

1. Langfuseプロジェクトを作成します。Create new project in Langfuseのセットアップガイドに従ってください。
2. API認証情報を取得します。Where are Langfuse API keys?で説明されているように、Langfuseのpublic keyとsecret keyを取得します。
3. Langfuseホスト、公開キー、シークレットキーをLangfuseエクスポーターに渡します。 これらはaddLangfuseExporter()関数のパラメーターとして渡すか、または以下に示すように環境変数を設定することで行えます。

   export LANGFUSE_HOST="https://cloud.langfuse.com"
   export LANGFUSE_PUBLIC_KEY="<your-public-key>"
   export LANGFUSE_SECRET_KEY="<your-secret-key>"

設定

Langfuseエクスポートを有効にするには、OpenTelemetry機能をインストールし、LangfuseExporterを追加します。 エクスポーターは内部でOtlpHttpSpanExporterを使用して、LangfuseのOpenTelemetryエンドポイントにトレースを送信します。

例: Langfuseトレースを持つエージェント

fun main() = runBlocking {
    val apiKey = "api-key"
    
    val agent = AIAgent(
        promptExecutor = simpleOpenAIExecutor(apiKey),
        llmModel = OpenAIModels.CostOptimized.GPT4oMini,
        systemPrompt = "You are a code assistant. Provide concise code examples."
    ) {
        install(OpenTelemetry) {
            addLangfuseExporter()
        }
    }

    println("Running agent with Langfuse tracing")

    val result = agent.run("Tell me a joke about programming")

    println("Result: $result
See traces on the Langfuse instance")
}

何がトレースされるか

有効にすると、Langfuseエクスポーターは、Koogの一般的なOpenTelemetry連携と同じスパンをキャプチャします。以下を含みます:

• エージェントのライフサイクルイベント: エージェントの開始、停止、エラー
• LLMインタラクション: プロンプト、レスポンス、トークン使用量、レイテンシー
• ツール呼び出し: ツール呼び出しの実行トレース
• システムコンテキスト: モデル名、環境、Koogバージョンなどのメタデータ

Koogは、Langfuseがエージェントグラフを表示するのに必要なスパン属性もキャプチャします。

Langfuseで視覚化されると、トレースは次のようになります:

Langfuse OpenTelemetryトレースの詳細については、以下を参照してください: Langfuse OpenTelemetry Docs.

---

トラブルシューティング

Langfuseにトレースが表示されない

• LANGFUSE_HOST、LANGFUSE_PUBLIC_KEY、およびLANGFUSE_SECRET_KEYが環境に設定されていることを再確認してください。
• セルフホスト型Langfuseで実行している場合は、LANGFUSE_HOSTがアプリケーション環境から到達可能であることを確認してください。
• 公開/シークレットキーペアが正しいプロジェクトに属していることを確認してください。