W&B Weave 익스포터

Koog는 에이전트 트레이스(trace)를 AI 애플리케이션의 옵저버빌리티(observability) 및 분석을 위한 Weights & Biases의 개발자 도구인 W&B Weave로 내보낼 수 있는 내장 지원을 제공합니다.
Weave 통합을 통해 프롬프트, 완성(completion), 시스템 컨텍스트 및 실행 트레이스를 캡처하고 W&B 워크스페이스에서 직접 시각화할 수 있습니다.

Koog의 OpenTelemetry 지원에 대한 배경 지식은 OpenTelemetry 지원을 참조하세요.

---

설정 방법

1. https://wandb.ai에서 W&B 계정을 생성합니다.
2. https://wandb.ai/authorize에서 API 키를 가져옵니다.
3. https://wandb.ai/home의 W&B 대시보드에서 엔티티(entity) 이름을 확인합니다. 엔티티는 보통 개인 계정의 경우 사용자 이름이며, 팀/조직 이름일 수도 있습니다.
4. 프로젝트 이름을 정의합니다. 미리 프로젝트를 생성할 필요는 없으며, 첫 번째 트레이스가 전송될 때 자동으로 생성됩니다.
5. Weave 엔티티, 프로젝트 이름 및 API 키를 Weave 익스포터에 전달합니다. 이는 addWeaveExporter() 함수의 파라미터로 제공하거나, 아래와 같이 환경 변수를 설정하여 수행할 수 있습니다.

export WEAVE_API_KEY="<your-api-key>"
export WEAVE_ENTITY="<your-entity>"
export WEAVE_PROJECT_NAME="koog-tracing"

구성

Weave 내보내기를 활성화하려면 OpenTelemetry 기능을 설치하고 WeaveExporter를 추가하세요.
익스포터는 OtlpHttpSpanExporter를 통해 Weave의 OpenTelemetry 엔드포인트를 사용합니다.

예제: Weave 트레이싱이 적용된 에이전트

fun main() = runBlocking {
    val apiKey = "api-key"
    val entity = System.getenv()["WEAVE_ENTITY"] ?: throw IllegalArgumentException("WEAVE_ENTITY is not set")
    val projectName = System.getenv()["WEAVE_PROJECT_NAME"] ?: "koog-tracing"
    
    val agent = AIAgent(
        promptExecutor = simpleOpenAIExecutor(apiKey),
        llmModel = OpenAIModels.Chat.GPT4oMini,
        systemPrompt = "You are a code assistant. Provide concise code examples."
    ) {
        install(OpenTelemetry) {
            addWeaveExporter()
        }
    }

    println("Weave 트레이싱과 함께 에이전트 실행 중")

    val result = agent.run("Tell me a joke about programming")

    println("결과: $result
다음에서 트레이스를 확인하세요: https://wandb.ai/$entity/$projectName/weave/traces")
}

트레이스 대상

활성화되면 Weave 익스포터는 다음을 포함하여 Koog의 일반 OpenTelemetry 통합과 동일한 스팬(span)을 캡처합니다.

• 에이전트 수명 주기 이벤트: 에이전트 시작, 중지, 오류
• LLM 상호작용: 프롬프트, 완성, 지연 시간(latency)
• 도구 호출: 도구 호출에 대한 실행 트레이스
• 시스템 컨텍스트: 모델 이름, 환경, Koog 버전과 같은 메타데이터

보안상의 이유로 OpenTelemetry 스팬의 일부 콘텐츠는 기본적으로 마스킹(masking)됩니다. Weave에서 콘텐츠를 확인할 수 있게 하려면 OpenTelemetry 구성에서 setVerbose 메서드를 사용하고 다음과 같이 verbose 인자를 true로 설정하세요.

install(OpenTelemetry) {
    addWeaveExporter()
    setVerbose(true)
}

W&B Weave에서 시각화하면 트레이스는 다음과 같이 표시됩니다.

더 자세한 내용은 공식 Weave OpenTelemetry 문서를 참조하세요.

---

문제 해결

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

• 환경 변수에 WEAVE_API_KEY, WEAVE_ENTITY, WEAVE_PROJECT_NAME이 설정되어 있는지 확인하세요.
• W&B 계정이 지정된 엔티티 및 프로젝트에 액세스할 수 있는지 확인하세요.

인증 오류

• WEAVE_API_KEY가 유효한지 확인하세요.
• API 키는 선택한 엔티티에 트레이스를 쓸 수 있는 권한이 있어야 합니다.

연결 문제

• 사용자 환경에서 W&B의 OpenTelemetry 수집 엔드포인트에 대한 네트워크 액세스가 가능한지 확인하세요.