Skip to main content
W&B Weave 에이전트 관측성은 OpenTelemetry (OTel)을 기반으로 합니다. Weave는 span을 Agents 뷰로 수집하는 전용 OTLP 엔드포인트를 제공합니다. 에이전트가 이미 OTel span을 내보내고 있다면 Weave SDK를 설치하지 않아도 기존 OTel 파이프라인이 해당 엔드포인트를 가리키도록 설정해 Weave로 보낼 수 있습니다. 이 페이지에서는 엔드포인트에 인증하고 span을 보내는 방법을 설명합니다.

인증

다음 엔드포인트로 spans를 전송할 수 있습니다:
  • 경로: /agents/otel/v1/traces
  • 방법: POST
  • 콘텐츠 유형: application/x-protobuf
  • 기본 URL: Multi-tenant Cloud의 경우 https://trace.wandb.ai
이 엔드포인트는 OTLP protobuf payload만 허용합니다. opentelemetry-exporter-otlp-proto-http (Python) 또는 @opentelemetry/exporter-trace-otlp-proto (TypeScript)와 같은 protobuf HTTP 익스포터를 사용하세요. 이 엔드포인트는 gzipdeflate 콘텐츠 인코딩도 허용합니다. 엔드포인트에 인증하려면 다음 값 중 하나를 사용해 OTLPSpanExporter 설정에 W&B API 키를 설정하세요:
  • wandb-api-key: 값으로 W&B API 키를 지정합니다.
  • Authorization: 사용자 이름으로 api를, 비밀번호로 W&B API 키를 사용하는 HTTP Basic 인증입니다. 이 형식은 익스포터 또는 collector가 표준 authorization 헤더만 지원하는 경우에 유용합니다.

프로젝트 라우팅

Weave는 OTel 리소스 속성 또는 요청 헤더를 사용해 span을 프로젝트로 라우팅합니다.
  • 리소스 속성(권장): TracerProvider 리소스에서 wandb.entity는 담당 W&B 팀 또는 사용자 이름으로, wandb.project는 프로젝트 이름으로 설정하세요.
  • project_id 헤더: 값을 [YOUR-TEAM]/[YOUR-PROJECT]로 설정하세요.
둘 다 있으면 리소스 속성이 우선합니다. entity와 프로젝트 없이 들어오는 span은 무시됩니다.

Agents 뷰용 span 구성하기

Weave는 모든 OTel span을 허용하고 해당 span의 모든 속성을 저장하지만, Agents 뷰에서는 OTel GenAI semantic conventions을 따르는 span을 렌더링합니다. 각 span에 gen_ai.operation.name을 설정하여 Weave에 해당 span이 무엇을 나타내는지 알려 주세요. 그룹화는 다음 두 속성으로 제어됩니다.
  • gen_ai.conversation.id: 여러 턴을 하나의 대화로 그룹화합니다. 대화가 유지되는 동안에는 안정적인 ID를 사용하세요.
  • gen_ai.agent.name: Agents 탭에서 대화를 이름 있는 에이전트 아래로 그룹화합니다.
gen_ai.request.model, gen_ai.usage.input_tokens, gen_ai.usage.output_tokens와 같은 다른 GenAI semantic-convention 속성은 모델 이름과 token 수를 표시해 렌더링 정보를 더 풍부하게 해 주지만, 선택 사항입니다. 이러한 span이 매핑되는 에이전트 데이터 모델은 Trace your agents에서 확인하세요.

환경 변수만 사용해 구성하기

애플리케이션 또는 collector가 표준 OTel 익스포터 환경 변수를 읽는 경우, 코드를 전혀 변경하지 않고도 다음 변수를 설정해 spans를 Weave로 라우팅할 수 있습니다:

예시: Weave SDK 없이 에이전트 spans 내보내기

다음 예시는 OTel 패키지만 사용해 최소한의 에이전트 턴을 계측합니다. 턴용 invoke_agent span, LLM Call용 chat span, 도구 Call용 execute_tool span을 내보낸 다음, 이를 Weave Agents 엔드포인트로 익스포트합니다. 먼저, 필요한 의존성을 설치하세요:
그런 다음 아래 코드에서 WANDB_API_KEY, ENTITY, PROJECT 값을 설정한 후 실행하세요:
같은 대화에 턴을 더 추가하려면 동일한 gen_ai.conversation.id를 사용해 invoke_agent span을 더 emit하세요. 각 턴은 자체 트레이스의 루트 span이므로 턴끼리 부모 span을 공유할 필요가 없습니다. 애플리케이션이 span을 내보낸 후 Weave 프로젝트의 Agents 탭을 여세요.