목록으로
기술

Langfuse Exporter

·3분 읽기
#Koog#JetBrains#AI Agent#Kotlin#Java#JVM

원문: Koog Documentation — opentelemetry-langfuse-exporter 이 글은 Koog 공식 문서의 opentelemetry-langfuse-exporter 페이지를 한국어로 옮긴 번역본입니다. 문서 구조와 링크 의미를 유지하되, MkDocs 전용 UI 문법은 블로그에서 읽기 좋도록 정리했습니다.

Langfuse Exporter

Koog는 관측 가능성 데이터에 대한 공개 표준인 OpenTelemetry을 사용하여 에이전트 추적을 내보냅니다. 이러한 추적을 Langfuse로 보내기 위해 Koog에는 내장된 OpenTelemetry 내보내기 기능이 포함되어 있습니다. 수동 계측이 필요하지 않습니다.

일단 연결되면 Langfuse의 OpenTelemetry support을 통해 시각화할 수 있습니다. 에이전트가 LLM, 도구 및 외부 API와 상호 작용하는 방식을 분석하고 디버깅합니다.

설정 지침

  1. setup guide을 사용하여 Langfuse 프로젝트를 생성합니다.
  2. Organization Settings > API Keys에서 public key 및 secret key를 가져옵니다.
  3. addLangfuseExporter()에 대한 매개변수로 또는 환경 변수를 통해 호스트, 공개 키 및 비밀 키를 제공합니다.
1export LANGFUSE_HOST="https://cloud.langfuse.com"2export LANGFUSE_PUBLIC_KEY="<your-public-key>"3export LANGFUSE_SECRET_KEY="<your-secret-key>"

구성

OpenTelemetry 기능을 설치하고 addLangfuseExporter()을 호출하여 Langfuse 내보내기를 활성화합니다.

기본 예

코틀린

1fun main() = runBlocking {2    val agent = AIAgent(3        promptExecutor = promptExecutor,4        llmModel = OpenAIModels.Chat.GPT4oMini,5        systemPrompt = "You are a code assistant. Provide concise code examples."6    ) {7        install(OpenTelemetry) {8            addLangfuseExporter()9        }10    }1112    println("Running agent with Langfuse tracing")1314    val result = agent.run("Tell me a joke about programming")15    println("Result: $result\nSee traces on the Langfuse instance")16}

자바

1public static void main(String[] args) {2    var agent = AIAgent.builder()3        .promptExecutor(promptExecutor)4        .llmModel(OpenAIModels.Chat.GPT4oMini)5        .systemPrompt("You are a code assistant. Provide concise code examples.")6        .install(OpenTelemetry.Feature, config ->7            config.addLangfuseExporter()8        )9        .build();1011    System.out.println("Running agent with Langfuse tracing");1213    var result = agent.run("Tell me a joke about programming");14    System.out.println("Result: " + result + "\nSee traces on the Langfuse instance");15}

추적 속성

Koog가 Langfuse에 에이전트 활동을 보낼 때 일련의 범위(예: 다음과 같은 개별 작업 기록)로 전송합니다. LLM 호출 또는 도구 실행. 관련 범위는 전체 에이전트 실행을 나타내는 trace로 그룹화됩니다. 처음부터 끝까지.

addLangfuseExporter()은 traceAttributes 매개변수(에 연결된 키-값 쌍 목록)를 허용합니다. 각 추적의 루트. 이를 통해 세션, 환경, 태그 등 Langfuse 관련 기능을 활성화할 수 있습니다. Langfuse UI에서 추적을 쉽게 필터링하고 그룹화할 수 있습니다.

지원되는 속성의 전체 목록은 Langfuse OpenTelemetry docs을 참조하세요.

포함할 공통 속성은 다음과 같습니다.

  • 세션 ID(langfuse.session.id): 집계된 측정항목, 비용 분석 및 점수 매기기에 대한 그룹 관련 추적
  • 환경(langfuse.environment): 개발 및 준비에서 프로덕션 추적을 격리합니다.
  • 태그(langfuse.trace.tags): 기능 이름, 실험 ID 또는 고객 세그먼트(문자열 배열)로 추적에 레이블을 지정합니다.

세션 및 태그의 예

코틀린

1fun main() = runBlocking {2    val sessionId = UUID.randomUUID().toString()34    val agent = AIAgent(5        promptExecutor = promptExecutor,6        llmModel = OpenAIModels.Chat.GPT4oMini,7        systemPrompt = "You are a helpful assistant."8    ) {9        install(OpenTelemetry) {10            addLangfuseExporter(11                traceAttributes = listOf(12                    CustomAttribute("langfuse.session.id", sessionId),13                    CustomAttribute("langfuse.trace.tags", listOf("chat", "kotlin", "production"))14                )15            )16        }17    }1819    println("Running agent with Langfuse tracing")2021    // Multiple runs with the same session ID will be grouped in Langfuse22    agent.run("What is Kotlin?")23    agent.run("Show me a coroutine example")24}

자바

1public static void main(String[] args) {2    var sessionId = UUID.randomUUID().toString();34    var agent = AIAgent.builder()5        .promptExecutor(promptExecutor)6        .systemPrompt("You are a helpful assistant.")7        .llmModel(OpenAIModels.Chat.GPT4oMini)8        .install(OpenTelemetry.Feature, config ->9            config.addLangfuseExporter(10                null,           // Langfuse host (falls back to LANGFUSE_HOST)11                null,           // Public key (falls back to LANGFUSE_PUBLIC_KEY)12                null,           // Secret key (falls back to LANGFUSE_SECRET_KEY)13                null,           // Timeout (uses default)14                List.of(15                    new CustomAttribute("langfuse.session.id", sessionId),16                    new CustomAttribute("langfuse.trace.tags", List.of("chat", "java", "production"))17                )18            ))19        .build();2021    System.out.println("Running agent with Langfuse tracing");2223    // Multiple runs with the same session ID will be grouped in Langfuse24    agent.run("How to setup Langfuse integration in Koog agent?");25    agent.run("Show me a Java API example");26}

추적되는 내용

Langfuse 내보내기는 Koog의 일반 OpenTelemetry 통합과 동일한 활동을 캡처합니다. 또한 Agent Graphs을 표시하기 위해 Langfuse에 필요한 범위 속성을 캡처합니다.

캡처된 범위의 전체 목록과 LLM 프롬프트 및 응답 콘텐츠를 포함하는 방법은 What gets traced을 참조하세요.

Langfuse에서 시각화하면 추적은 다음과 같이 나타납니다. Langfuse traces Langfuse traces

Langfuse OpenTelemetry 추적에 대한 자세한 내용은 다음을 참조하세요.
Langfuse OpenTelemetry Docs.

문제 해결

  • 추적 없음: LANGFUSE_HOST, LANGFUSE_PUBLIC_KEY 및 LANGFUSE_SECRET_KEY가 설정되어 있고 키 쌍이 올바른 프로젝트에 속해 있는지 확인하세요.
  • 연결 문제: 자체 호스팅 Langfuse를 실행하는 경우 환경에서 LANGFUSE_HOST에 연결할 수 있는지 확인하세요.

일반적인 문제 해결은 Troubleshooting을 참조하세요.

#Koog#JetBrains#AI Agent#Kotlin#Java#JVM