Skip to main content
Koog는 single-run 및 복잡한 워크플로 에이전트를 구축하기 위한 Kotlin 기반 프레임워크입니다. Koog에는 OpenTelemetry(OTEL) 지원이 내장되어 있으며 트레이스를 Weave로 직접 내보낼 수 있어 프롬프트, 완료, 도구 Call 및 엔드투엔드 에이전트 실행에 대한 가시성을 제공합니다. 이 가이드에서는 Kotlin 에이전트가 OpenTelemetry span을 Weave 프로젝트로 전달하도록 Koog의 Weave 익스포터를 설정하는 방법을 설명합니다. 익스포터를 사용하면 run을 디버그하고, 성능을 분석하며, 더 빠르게 반복할 수 있습니다. 이 가이드는 이미 Koog로 에이전트를 구축하고 Weave 트레이싱을 추가하려는 Kotlin 개발자를 위한 것입니다.
Koog

사전 요구 사항

에이전트를 실행하기 전에 다음 환경 변수를 설정해야 Weave 익스포터가 트레이스를 인증하고 올바른 프로젝트로 라우팅할 수 있도록 합니다: [YOUR-API-KEY]를 CoreWeave Forge API 키로, [YOUR-ENTITY]를 CoreWeave Forge 팀 또는 entity 이름으로 바꾸세요. WEAVE_PROJECT_NAME 값은 임의의 프로젝트 이름일 수 있습니다. Weave는 처음 사용 시 프로젝트를 생성합니다.

Koog 설치 (Gradle)

환경 변수가 준비되면, Kotlin 프로젝트에 Koog를 추가하여 에이전트와 그 익스포터를 설정할 수 있습니다 (Kotlin DSL 예시):
Koog의 문서에서 추가 설치 정보를 참조하세요.

Weave 내보내기 활성화 (OpenTelemetry)

Koog를 설치한 후 Koog의 OpenTelemetry 기능을 설치하고 Weave 익스포터를 추가하세요. 이는 Weave의 OpenTelemetry 엔드포인트를 사용하여 Koog spans를 Weave 트레이스로 매핑합니다. 다음 예제는 addWeaveExporter를 사용하는 방법을 보여줍니다:
이 함수는 Weave 환경 변수를 자동으로 읽어 오지만, 다음 예시처럼 익스포터의 특정 매개변수를 직접 설정할 수도 있습니다.
이전 예제:
  • weaveEntity와 weaveProjectName을 사용하여 특정 팀과 프로젝트로 트레이스를 라우팅합니다.
  • weaveOtelBaseUrl을 트레이스 엔드포인트(예: https://[YOUR-SUBDOMAIN].wandb.io/[PATH])로 설정합니다. 전용 Weave 인스턴스에 이 매개변수를 사용하세요.
Koog를 Weave와 함께 처음 사용하는 경우 다음 문서를 검토하세요:

트레이스 대상

익스포터를 활성화한 상태로 에이전트를 실행하면 Koog가 트레이스를 Weave 프로젝트로 전달합니다. Koog의 Weave 익스포터는 Koog의 일반 OTEL 인테그레이션과 동일한 span을 캡처하며, 여기에는 다음 항목이 포함됩니다.
  • 에이전트 라이프사이클 이벤트(시작, 중지, 오류)
  • LLM 상호작용(프롬프트, 완료, 토큰 사용량, 지연 시간)
  • 도구 및 API 호출(함수 호출 및 외부 요청)
  • 시스템 컨텍스트(모델 이름, Koog 버전, 환경 메타데이터)
Weights & Biases UI에서 이러한 트레이스를 시각화하여 성능과 품질을 파악할 수 있습니다. Weave로 트레이스를 캡처하는 방법은 Weave 트레이싱 개요를 참조하세요.

예시 노트북

Weave로 트레이스를 스트리밍하는 실행 가능한 노트북에 대한 Koog의 문서를 참조하세요.

문제 해결

Koog 에이전트가 예상대로 트레이스를 내보내지 않는 경우 다음을 확인하세요:
  • 트레이스가 누락된 경우 먼저 WEAVE_API_KEY, WEAVE_ENTITY, WEAVE_PROJECT_NAME이 올바르게 설정되었는지 확인하세요.
  • 환경이 https://trace.wandb.ai에 도달할 수 있는지, 그리고 앞의 예시에서 보여준 대로 익스포터가 설정되었는지 확인하세요.
  • 추가 문제 해결 및 샘플링 지침은 Koog의 OpenTelemetry support를 참조하세요.
마지막 수정일 2026년 9월 30일