Langfuse 匯出器

Koog 內建支援將代理程式追蹤匯出到 Langfuse，這是一個用於 AI 應用程式可觀察性與分析的平台。 透過 Langfuse 整合，您可以視覺化、分析和除錯您的 Koog 代理程式如何與 LLM、API 和其他元件互動。

有關 Koog 的 OpenTelemetry 支援背景資訊，請參閱 OpenTelemetry support。

---

設定說明

1. 建立一個 Langfuse 專案。請遵循 在 Langfuse 中建立新專案 的設定指南。
2. 取得 API 憑證。請按照 Langfuse API 金鑰在哪裡？ 所述，擷取您的 Langfuse public key 和 secret key。
3. 將 Langfuse 主機、public key 和 secret key 傳遞給 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 函式支援 traceAttributes 參數，它接受 CustomAttribute 物件的列表。

這些屬性會被新增到每個追蹤的根 InvokeAgentSpan span 中，並啟用 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"))
                )
            )
        }
    }

    // 使用相同工作階段 ID 的多次執行將會在 Langfuse 中被分組。
    agent.run("What is Kotlin?")
    agent.run("Show me a coroutine example")
}

追蹤的內容

啟用後，Langfuse 匯出器會擷取與 Koog 一般 OpenTelemetry 整合相同的 span，包括：

• 代理程式生命週期事件：代理程式啟動、停止、錯誤
• LLM 互動：提示、回應、令牌使用量、延遲
• 工具呼叫：工具調用的執行追蹤
• 系統上下文：中繼資料，例如模型名稱、環境、Koog 版本

Koog 也會擷取 Langfuse 顯示 Agent Graphs 所需的 span 屬性。

出於安全考量，某些 OpenTelemetry span 的內容預設會被遮罩。若要使內容在 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 可從您的應用程式環境存取。
• 驗證 public/secret key 對屬於正確的專案。