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は、セッション、環境、タグ、その他のメタデータなどの機能で可観測性を向上させるために、トレースレベルの属性を使用します。 addLangfuseExporter関数は、CustomAttributeオブジェクトのリストを受け入れるtraceAttributesパラメーターをサポートしています。

これらの属性は、各トレースのルートInvokeAgentSpanスパンに追加され、Langfuseの高度な機能を有効にします。Langfuseがサポートする任意の属性を渡すことができます。詳細については、LangfuseのOpenTelemetryドキュメントで完全なリストを参照してください。

一般的な属性:

• セッション (langfuse.session.id): 関連するトレースをグループ化して、集計メトリクス、コスト分析、スコアリングを行います
• 環境: 本番トレースを開発およびステージングから分離し、よりクリーンな分析を行います
• タグ (langfuse.trace.tags): トレースに機能名、実験ID、または顧客セグメントをラベル付けします（文字列の配列）

セッションとタグの例

fun main() = runBlocking {
    val apiKey = "api-key"
    val sessionId = UUID.randomUUID().toString()

    val agent = AIAgent(
        promptExecutor = simpleOpenAIExecutor(apiKey),
        llmModel = OpenAIModels.CostOptimized.GPT4oMini,
        systemPrompt = "You are a helpful assistant."
    ) {
        install(OpenTelemetry) {
            addLangfuseExporter(
                traceAttributes = listOf(
                    CustomAttribute("langfuse.session.id", sessionId),
                    CustomAttribute("langfuse.trace.tags", listOf("chat", "kotlin", "production"))
                )
            )
        }
    }

    // Multiple runs with the same session ID will be grouped in Langfuse
    agent.run("What is Kotlin?")
    agent.run("Show me a coroutine example")
}

何がトレースされるか

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

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

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

セキュリティ上の理由により、OpenTelemetryスパンの一部コンテンツはデフォルトでマスクされています。 Langfuseでコンテンツを利用可能にするには、OpenTelemetry構成でsetVerboseメソッドを使用し、そのverbose引数を以下のようにtrueに設定します。

install(OpenTelemetry) {
    addLangfuseExporter()
    setVerbose(true)
}

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

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

---

トラブルシューティング

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

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