요청하신 "간혹

add_shutdown_callback

이벤트가 발생하지 않는 이유"에 대해 답변드립니다. 아래에서는 어떤 상황에서 콜백이 누락되는지, 각각의 원인과 바로 적용할 수 있는 해결책을 함께 정리했습니다. 먼저 어떤 부분에 답변드리는지: "add_shutdown_callback이 간헐적으로 호출되지 않는 원인"과 이를 안정화하기 위한 권장 조치에 대해 설명합니다. 주요 원인 및 해결책 1) 종료 타임아웃 초과 • 원인: 에이전트가 셧다운 절차에서 콜백의 작업이 완료되기를 기다리지만, 기본 종료 대기 시간이 짧아(기본값 10초) 콜백이 끝나기 전에 프로세스가 강제 종료될 수 있습니다. 오래 걸리는 I/O(DB 저장, 외부 API 호출 등)가 콜백 안에 있으면 타임아웃이 발생하기 쉽습니다. • 해결책: 콜백 내부 작업을 가능한 가볍게 유지하고, 긴 작업은 별도의 비동기 백그라운드 태스크로 분리하세요. 필요하면

shutdown_process_timeout

설정을 늘려주세요. 2) 비정상적 프로세스 종료 (예: SIGKILL, 크래시) • 원인: 프로세스가 OOM(메모리 부족)이나 예외로 인해 강제 종료되면 정상적인 종료 흐름이 실행되지 않아 콜백이 호출되지 않습니다. `SIGTERM`은 정상 종료 처리로 콜백을 트리거하지만 `SIGKILL`은 호출하지 못합니다. • 해결책: 종료 시 로그(스택 트레이스, OOM 이벤트 등)를 확인해 비정상 종료 원인을 파악하고, 예외 처리를 강화하거나 리소스 사용을 최적화하세요. 3)

aclose()

등 즉시 연결 종료 사용 • 원인:

session.aclose()

또는 `ctx.aclose()`처럼 즉시/비동기적으로 닫는 호출을 사용하면 정상적인 셧다운 절차(콜백 실행 포함)가 실행되지 않습니다. • 해결책: 정상적인 종료를 위해

session.shutdown()

또는

ctx.shutdown()

같은 셧다운 API를 사용하세요.

shutdown(drain=True)

형태로 드레이닝을 보장하면 더 안전합니다. 4) 콜백 등록 시점/범위 문제 • 원인: 콜백이 올바른 컨텍스트(

JobContext

또는 entrypoint 내)에서 등록되지 않거나, 예외로 인해 등록 코드가 실행되지 않을 수 있습니다. • 해결책: 콜백 등록이 항상 실행되는 코드 경로(예: entrypoint의 초기화 단계)에 있는지 확인하세요.

prewarm()

같은 시점에는 `ctx`가 없을 수 있으므로 주의하세요. 권장 점검 항목 (우선 순위 제안) 1. 종료 로그 확인: 종료 시점 로그, 신호 종류(SIGTERM vs SIGKILL), 예외/오류 메시지 수집 2. 콜백 작업 분리: 긴 작업은 별도 태스크(큐/워크플로우)로 옮김 3. 종료 API 일관성:

shutdown()

사용을 강제하고

aclose()

사용을 피함 4. 타임아웃 조정:

shutdown_process_timeout

값을 현재 환경에 맞게 늘림 5. 콜백 등록 검증: entrypoint/JobContext 내에서 항상 등록되는지 코드 검토 추가로 도와드릴 수 있는 것 • 현재 콜백에 어떤 작업이 들어있는지(예: DB 쓰기, 외부 호출, 파일 I/O 등)를 알려주시면, 어떤 부분을 비동기로 옮기거나 경량화할지 구체적으로 제안드릴게요. • 셧다운 시 로그(종료 신호, 에러 스택, 타임스탬프)가 있으면 공유해 주세요. 어떤 신호로 종료되는지와 타임아웃 여부를 함께 확인해드릴 수 있습니다. 원하시면 먼저 콜백 코드와 종료 로그 일부를 공유해 주세요. 그러면 더 구체적으로 원인 분석 및 개선안을 드리겠습니다. Sources: Job lifecycle | LiveKit Documentation

이게 뭘 의미해?