웹 콜아웃

웹 콜아웃 (Web Callouts)

Web Callout은 프로젝트 멤버가 Langfuse UI의 트레이스, observation, 또는 세션에서 설정된 백엔드 HTTP 요청을 트리거할 수 있게 해줘요. 디버깅 워크플로우를 내부 도구, 지원 시스템, 인시던트 워크플로우, 또는 커스텀 조사 서비스에 연결하는 데 쓰죠.

출처: 문서

본문

프롬프트 웹훅과 달리, Web Callout은 UI에서 수동으로 트리거돼요. 사용자가 액션을 클릭하면 Langfuse가 백엔드에서 요청을 동기적으로 보내요.

Web Callout은 식별자만 보내요: 트레이스/observation/세션 ID와 프로젝트 ID. 워크플로우에서 더 많은 데이터가 필요하면 당신의 백엔드에서 Langfuse API로 추가 데이터를 가져와야 해요.

Web Callout 구성하기

프로젝트 설정(Project Settings) > 통합(Integrations) > Web Callouts를 열고 콜아웃 엔드포인트를 만들어요. 새 콜아웃을 구성하려면 Admin/Owner(integrations:CRUD) 권한이 필요해요. 콜아웃은 프로젝트별로 구성되며 프로젝트의 모든 사용자가 호출할 수 있어요.

다음을 구성하세요:

  • Name: 액션 메뉴에 표시되는 이름. 예: Add to Support Tool.
  • URL: POST 요청을 받는 HTTP 또는 HTTPS 엔드포인트. 커스텀 포트도 지원돼요.
  • Success toast message: 엔드포인트가 성공 응답을 반환한 후 표시되는 메시지.
  • Enabled: 비활성화된 콜아웃은 액션 메뉴에서 숨겨져요.
  • Request headers: 선택적인 정적 헤더. 예: Authorization: Bearer ***

Web Callout 트리거하기

설정이 끝나면 프로젝트 읽기 권한이 있는 사용자가 다음 위치에서 콜아웃을 트리거할 수 있어요:

  • 트레이스 상세의 액션 메뉴
  • observation 상세의 액션 메뉴
  • 세션 상세 헤더

사용자가 액션을 클릭하면 Langfuse가 즉시 요청을 보내요. 엔드포인트가 2xx 응답을 반환한 후에만 UI에 성공 토스트가 표시돼요. 요청은 5초 후 타임아웃돼요. 호출은 재시도되지 않으며 rate limit이 적용돼요.

요청 페이로드

Langfuse는 다음 구조의 JSON POST 요청을 보내요:

web-callout-payload.json

{
  "version": 1,
  "items": [
    {
      "projectId": "project-id",
      "traceId": "trace-id",
      "observationId": null,
      "sessionId": "session-id"
    }
  ]
}

참고: projectId를 제외한 모든 ID 필드는 null일 수 있어요. Langfuse는 요청을 보내기 전에 트레이스, observation, 세션이 해당 프로젝트에 속하는지 검증해요.

엔드포인트 요구사항

엔드포인트는 다음을 충족해야 해요:

  • Content-Type: application/json POST 요청을 수락해야 함
  • 5초 안에 HTTP 2xx 상태를 반환해야 함

Langfuse는 2xx가 아닌 응답, 네트워크 오류, 잘못된 URL, 타임아웃을 실패한 콜아웃으로 처리하고 오류 토스트를 표시해요.

Web Callout은 재시도되지 않으며 Langfuse는 전달 로그(delivery log)를 보관하지 않아요.

인증 및 헤더

인증을 위해 정적 요청 헤더를 구성할 수 있어요. 예: Authorization 또는 X-API-Key. 헤더 값은 저장 시 암호화되며 Langfuse 백엔드에서 전송돼요. 이름을 바꾸지 않고 기존 헤더를 편집할 때, 값을 비워두면 저장된 암호화된 값을 유지해요.

Langfuse는 Content-Type: application/json과 User-Agent: Langfuse/1.0을 자동으로 설정해요. 구성할 수 없는 헤더 이름: content-length, content-type, cookie, host.

더 알아보기 (Learn more)