셀프 호스팅 배포 문제 해결

지원팀에 문의하기 전에 셀프 호스팅 LangSmith Deployment 문제를 해결하기 위한 진단 단계예요.

이 페이지는 지원팀에 연락하기 전에 셀프 호스팅 LangSmith Deployment 문제를 해결하는 데 도움이 되는 진단 단계를 제공해요. 일반적인 배포 문제를 식별하고 해결하려면 다음 단계를 체계적으로 따르세요.

이러한 진단 단계를 완료해도 여전히 도움이 필요하다면, 이 가이드 끝의 지원을 참고해 연락하기 전에 무엇을 모아야 하는지 확인하세요.

출처: 문서

본문

사전 요구 사항

진단 단계를 시작하기 전에 다음이 있는지 확인하세요:

Kubernetes 클러스터에 대한 kubectl 접근.
팟, 배포, 서비스 등을 볼 수 있는 적절한 권한.
Helm 차트 구성에 대한 이해.

1단계: 배포 이해하기

무엇이 배포되었는지 확인하고 시스템의 기본 상태를 이해하세요. 이는 정상 운영이 어떤 모습인지 인식하고 문제 발생 시 편차를 식별하는 데 도움이 돼요.

다음 명령을 실행해 배포된 모든 Kubernetes 리소스를 보세요.

이 섹션의 명령을 실행할 때 올바른 네임스페이스에 있는지 확인하세요. 또는 -n 플래그로 네임스페이스를 명시적으로 지정하세요. 예: kubectl get deployments -n langsmith.

모든 배포 나열:

kubectl get deployments

모든 팟 나열:

kubectl get pods

모든 서비스 나열:

kubectl get services

모든 lgps 리소스 나열 (Agent Server를 만든 후에만 존재):

kubectl get lgps

핵심 배포 구성 요소

배포에는 다음과 같은 핵심 구성 요소가 포함돼요:

langsmith-frontend: Agent Server 배포를 만드는 LangSmith 프론트엔드 UI. 이 앱은 langsmith-host-backend에 API 호출을 해요. 컨트롤 플레인의 일부.
langsmith-host-backend: langsmith-frontend에서 요청을 받고 배포 요청을 컨트롤 플레인 Postgres 데이터베이스에 영구화하는 LangSmith Deployment 컨트롤 플레인.
langsmith-listener: LangSmith Deployment 데이터 플레인의 일부. 만들거나, 업데이트하거나, 삭제할 배포를 위해 HTTP API로 langsmith-host-backend를 폴링해요. 워커 프로세스가 처리할 작업을 대기열에 넣어요.
langsmith-redis: langsmith-listener의 작업 큐 역할을 하는 Redis 인스턴스. 리스너가 여기에 작업을 대기열에 넣고 워커가 이 큐에서 작업을 가져와요.
langsmith-operator: lgps 리소스에 대한 기본 Kubernetes 리소스를 조정하는 lgps Kubernetes 오퍼레이터. 데이터 플레인 인프라의 일부.

구성에 따라 배포에 추가 구성 요소가 있을 수 있어요. 개요는 LangSmith Deployment 구성 요소를 참고하세요.

2단계: 디버그 로깅 활성화하기

문제를 해결할 때 첫 단계는 일반적으로 디버그 수준 로깅을 활성화해 시스템에서 실제로 무슨 일이 일어나는지에 대한 더 상세한 정보를 수집하는 것이에요.

컨트롤 플레인 또는 데이터 플레인 배포의 경우

컨트롤 플레인 배포(예: langsmith-host-backend) 또는 데이터 플레인 배포(예: langsmith-listener)에서 문제가 발생한다면, LOG_LEVEL=DEBUG 환경 변수로 Helm 차트를 다시 설치하세요. values.yaml 파일에 다음을 추가하세요:

extraEnv:
  - name: LOG_LEVEL
    value: DEBUG

Agent Server 배포의 경우

문제가 개별 Agent Server 배포에 있다면:

LangSmith UI의 Deployments 탭으로 이동하세요.
배포 보기에서 + New Revision을 선택하세요.
새 환경 변수 LOG_LEVEL을 추가하고 DEBUG로 설정하세요.

배포 보기의 UI에서도 디버그 로그를 찾을 수 있어요. Server Logs를 클릭하고 Log level: Info 드롭다운에서 Debug를 선택하세요.

광범위한 문제의 경우

문제가 어디서 발생하는지 확실하지 않다면 모든 곳(컨트롤 플레인, 데이터 플레인 및 모든 Agent Server 배포)에서 DEBUG 로깅을 활성화하세요.

애플리케이션 로그 검토하기

각 팟의 로그를 테일해서 기본 동작을 이해하세요:

kubectl logs -f <pod_name>

그런 다음 다음 로그 라인을 찾아보세요:

langsmith-listener: Reconciling projects... (10초마다 나타남)
langsmith-operator: Starting reconciliation (주기적으로 나타남)

건강한 배포에서는 오류가 보이지 않아야 해요. 모든 로그가 정상적이고 일상적으로 보여야 해요.

디버그 로그 해석하기

다음 문제 표시를 찾아보세요:

예외 또는 스택 트레이스.
오류 메시지 ("ERROR"라는 단어).
정상 운영과 다른 비정상적인 패턴.

발견한 오류에 따라:

구성 문제: 구성 문제가 의심된다면 helm install을 실행한 사람에게 문제를 제기하세요.
사용자 코드 버그: 사용자 코드(예: LangGraph OSS 그래프 구현)의 버그가 의심된다면 langgraph.json 파일을 만든 Agent Server 애플리케이션 소유자에게 문제를 제기하세요.

3단계: 배포 및 팟 설명하기

Kubernetes 리소스를 설명하면 애플리케이션 로그에 나타나지 않을 수 있는 오류 이벤트와 상태가 드러나요. 이러한 오류는 일반적으로 애플리케이션 코드 버그보다는 구성 또는 인프라 문제로 발생해요. 리소스를 설명하면 환경 변수 같은 구성도 보여주므로 디버깅에 유용해요.

리소스를 설명하려면 다음 명령을 실행하세요.

Kubernetes 배포 설명:

kubectl describe deployment <deployment_name>

Kubernetes 팟 설명:

kubectl describe pod <pod_name>

lgps 리소스 설명 (Agent Server를 만든 후에만 관련):

kubectl describe lgps <lgps_name>

결과 해석하기

출력의 Events: 섹션을 검토하고 모든 것이 정상인지 확인하세요. 나타나는 일반적인 문제는 다음과 같아요:

실패한 liveness 또는 readiness 프로브
이미지 풀 오류
리소스 제약 (CPU, 메모리)
볼륨 마운트 문제
구성 오류

오류 이벤트가 없고 모든 이벤트가 정상적인 운영을 나타내는지 확인하세요.

추가 리소스

자세한 문제 해결 정보는 다음을 참고하세요:

문제 해결: 일반적인 문제에 대한 해결책이 있는 일반 문제 해결 가이드.
셀프 호스팅 개요: 시스템 아키텍처 및 구성 요소 상호작용에 대한 세부 사항.

지원

이 진단 단계를 따라도 여전히 도움이 필요하다면 다음 정보를 수집해 기술 지원에 문의하세요:

진단 번들 캡처.
문제가 발생했을 때 무엇을 하려고 했는지에 대한 설명.

이 정보를 티켓에 포함하면 지원 팀이 문제를 더 빠르게 진단하고 해결하는 데 도움이 돼요.

셀프 호스팅 배포 문제 해결