Langfuse 익스포터

Koog는 AI 애플리케이션의 관측 가능성 및 분석 플랫폼인 Langfuse로 에이전트 트레이스를 내보내는 내장 지원을 제공합니다.
Langfuse 통합을 통해 Koog 에이전트가 LLM, API 및 기타 구성 요소와 상호 작용하는 방식을 시각화하고, 분석하고, 디버그할 수 있습니다.

Koog의 OpenTelemetry 지원에 대한 배경 정보는 OpenTelemetry 지원 문서를 참조하세요.

---

설정 지침

1. Langfuse 프로젝트를 생성합니다. Langfuse에서 새 프로젝트 생성 설정 가이드를 따르세요.
2. API 자격 증명을 얻습니다. Langfuse API 키는 어디에 있나요?에 설명된 대로 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 문서.

---

문제 해결

Langfuse에 트레이스가 나타나지 않음

• LANGFUSE_HOST, LANGFUSE_PUBLIC_KEY, 및 LANGFUSE_SECRET_KEY가 환경에 설정되어 있는지 다시 확인하세요.
• 자체 호스팅 Langfuse에서 실행 중인 경우, LANGFUSE_HOST가 애플리케이션 환경에서 도달 가능한지 확인하세요.
• 공개/비밀 키 쌍이 올바른 프로젝트에 속하는지 확인하세요.