
사전 요구 사항
Weave 익스포터가 인증을 수행하고 트레이스를 올바른 프로젝트로 라우팅할 수 있도록, 에이전트를 실행하기 전에 다음 환경 변수를 설정해야 합니다.[YOUR-API-KEY]를 Weave API 키로, [YOUR-ENTITY]를 W&B 팀 또는 entity 이름으로 바꾸세요. WEAVE_PROJECT_NAME 값에는 원하는 프로젝트 이름을 사용할 수 있습니다. Weave는 처음 사용할 때 해당 프로젝트를 생성합니다.
Koog 설치 (Gradle)
환경 변수를 설정했다면, 에이전트와 해당 익스포터를 구성할 수 있도록 Kotlin 프로젝트에 Koog를 추가하세요(Kotlin DSL 기준):Weave 내보내기 활성화(OpenTelemetry)
Koog를 설치한 후 Koog의 OpenTelemetry 기능을 설치하고 Weave 익스포터를 추가하세요. 그러면 Koog 스팬이 Weave의 OpenTelemetry 엔드포인트를 사용해 Weave 트레이스로 매핑됩니다. 다음 예제는addWeaveExporter를 사용하는 방법을 보여줍니다:
weaveEntity와weaveProjectName을 사용해 트레이스를 특정 팀과 프로젝트로 라우팅합니다.weaveOtelBaseUrl을 트레이스 엔드포인트(예:https://[YOUR-SUBDOMAIN].wandb.io/[PATH])로 설정합니다. 전용 Weave 인스턴스를 사용하는 경우 이 파라미터를 사용하세요.
- 익스포터에 대한 추가 정보는 Koog’s Weave exporter guide를 참조하세요.
- OpenTelemetry가 Koog와 함께 작동하는 방식의 핵심 개념은 Koog’s OpenTelemetry support guide를 참조하세요.
- Weave가 OTLP 데이터를 수집하는 방식에 대한 정보는 Weave OTEL docs를 참조하세요.
트레이스되는 항목
익스포터를 활성화한 상태로 에이전트를 실행하면 Koog가 트레이스를 사용자의 Weave 프로젝트로 전달합니다. Koog의 Weave 익스포터는 Koog의 일반 OTEL 인테그레이션과 동일한 스팬을 캡처하며, 여기에는 다음이 포함됩니다.- 에이전트 수명 주기 이벤트(시작, 중지, 오류)
- LLM 상호작용(프롬프트, completion, 토큰 사용량, 지연 시간)
- 도구 및 API 호출(함수 호출 및 외부 요청)
- 시스템 컨텍스트(모델 이름, Koog 버전, 환경 메타데이터)
예시 노트북
트레이스를 Weave로 스트리밍하는 실행 가능한 노트북은 Koog 문서를 참조하세요.문제 해결
Koog 에이전트가 예상대로 트레이스를 익스포트하지 않는다면 다음을 확인하세요.- 트레이스가 보이지 않으면 먼저
WEAVE_API_KEY,WEAVE_ENTITY,WEAVE_PROJECT_NAME이 올바르게 설정되어 있는지 확인하세요. - 사용 중인 환경에서
https://trace.wandb.ai에 연결할 수 있는지, 그리고 익스포터가 앞선 예시에 나온 대로 설정되어 있는지 확인하세요. - 추가 문제 해결 방법과 샘플링 지침은 Koog의 OpenTelemetry 지원을 참조하세요.