목록으로
기술

Koog를 사용한 OpenTelemetry: AI 에이전트 추적

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

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

Koog를 사용한 OpenTelemetry: AI 에이전트 추적

:material-github: Open on GitHub{ .md-button .md-button--기본 } :material-download: Download .ipynb{ .md-버튼 }

이 노트북은 Koog AI 에이전트에 OpenTelemetry 기반 추적을 추가하는 방법을 보여줍니다. 우리는:

  • 빠른 로컬 디버깅을 위해 콘솔에 범위를 내보냅니다.
  • 범위를 OpenTelemetry Collector로 내보내고 Jaeger에서 확인하세요.

전제 조건:

  • Docker/Docker Compose 설치됨
  • 환경 변수 OPENAI_API_KEY에서 사용 가능한 OpenAI API 키

노트북을 실행하기 전에 로컬 OpenTelemetry 스택(Collector + Jaeger)을 시작합니다.

1./docker-compose up -d

에이전트가 실행된 후 Jaeger UI를 엽니다.

나중에 서비스를 중지하려면 다음 안내를 따르세요.

1docker-compose down
1%useLatestDescriptors2// %use koog
1import ai.koog.agents.core.agent.AIAgent2import ai.koog.agents.features.opentelemetry.feature.OpenTelemetry3import ai.koog.prompt.executor.clients.openai.OpenAIModels4import ai.koog.prompt.executor.llms.all.simpleOpenAIExecutor5import io.opentelemetry.exporter.logging.LoggingSpanExporter6import io.opentelemetry.exporter.otlp.trace.OtlpGrpcSpanExporter7

OpenTelemetry 내보내기 구성

다음 셀에서는 다음을 수행합니다.

  • Koog AIAgent 생성
  • OpenTelemetry 기능 설치
  • 두 개의 범위 내보내기를 추가합니다.

이는 예제 설명(로컬 디버깅을 위한 콘솔 로그 및 Jaeger에서 추적을 보기 위한 OTLP)을 반영합니다.

1val agent = AIAgent(2    executor = simpleOpenAIExecutor(System.getenv("OPENAI_API_KEY")),3    llmModel = OpenAIModels.Chat.GPT4oMini,4    systemPrompt = "You are a code assistant. Provide concise code examples."5) {6    install(OpenTelemetry) {7        // Add a console logger for local debugging8        addSpanExporter(LoggingSpanExporter.create())910        // Send traces to OpenTelemetry collector11        addSpanExporter(12            OtlpGrpcSpanExporter.builder()13                .setEndpoint("http://localhost:4317")14                .build()15        )16    }17}

Jaeger에서 에이전트 실행 및 추적 보기

간단한 프롬프트를 트리거하려면 다음 셀을 실행하세요. 다음을 확인해야 합니다.

  • LoggingSpanExporter의 콘솔 범위 로그
  • 로컬 OpenTelemetry Collector로 내보낸 추적은 http://localhost:16686의 Jaeger에서 볼 수 있습니다.

팁: 셀을 실행한 후 Jaeger 검색을 사용하여 최근 추적을 찾으십시오.

1import ai.koog.agents.utils.use2import kotlinx.coroutines.runBlocking34runBlocking {5    agent.use { agent ->6        println("Running agent with OpenTelemetry tracing...")78        val result = agent.run("Tell me a joke about programming")910        "Agent run completed with result: '$result'.\nCheck Jaeger UI at http://localhost:16686 to view traces"11    }12}

정리 및 문제 해결

완료되면:

  • 서비스 중지:
1docker-compose down

  • Jaeger에 흔적이 표시되지 않는 경우:

    • 스택이 실행 중인지 확인하고(./docker-compose up -d) 시작하는 데 몇 초를 기다립니다.
    • 포트 확인:

  • 수집기(OTLP gRPC): http://localhost:4317

  • 예거 UI: http://localhost:16686

    • 컨테이너 로그 확인: docker-compose logs --tail=200
    • 노트북이 실행되는 환경에 OPENAI_API_KEY이 설정되어 있는지 확인하세요.
    • 내보내기의 엔드포인트가 수집기(http://localhost:4317)와 일치하는지 확인하세요.

  • 예상 범위:

    • Koog 에이전트 수명 주기
    • LLM 요청/응답 메타데이터
    • 모든 도구 실행 범위(도구를 추가하는 경우)

이제 에이전트를 반복하고 추적 파이프라인의 변경 사항을 관찰할 수 있습니다.

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