자체 호스팅 러너 지표 — 훅과 카운터가 같은 일을 다르게 셉니다

사내 서버에서 AI 세션을 굴리기 시작하면 대시보드부터 만들고 싶어집니다. 몇 개나 돌았고, 몇 개가 실패했고, 지금 몇 개가 도는지. 그런데 공식 참조 문서를 읽어보니 같은 사건을 훅과 지표가 서로 다르게 세고 있었습니다. 둘을 맞춰보면 숫자가 안 맞는 게 정상이라는 뜻이죠. 게다가 건강 확인 주소는 멈춰 있어도 정상을 돌려줍니다. 대시보드를 잘못 만들기 딱 좋은 지점들만 정리했습니다.

📌 30초 요약

• ★★훅은 중단, 카운터는 완료로 셉니다 — 같은 사건인데요.
• ★맞춰보면 완료 수가 모자랍니다 — 쓰는 목적이 다릅니다.
• ★한 세션만 받으면 끝 카운터가 안 잡힙니다.
• ⚠️ 건강 확인은 멈춰 있어도 정상을 줍니다.
• 지표 라벨에 계정 이메일이 실려 나갑니다.
• 스폰 전 실패는 실패 수에 안 잡힙니다.

같은 일을 훅과 지표가 다르게 셉니다

세션이 끝나는 방식은 크게 셋으로 분류됩니다 — 정상 완료, 실패, 중단. 시작할 때 하나 올라가고 끝날 때 셋 중 하나가 올라가니, 시작 수에서 나머지 셋을 빼면 지금 돌고 있는 수가 나옵니다. 여기까진 깔끔하죠.

문제는 경계에 있는 사건들입니다. 쉬는 시간이 길어 자리를 놓아준 경우, 시작을 기다리다 시간이 넘은 경우, 서버가 배정을 거둬간 경우 — 이 셋을 지표는 "정상 완료"로 셉니다. 아무 문제 없이 자리를 깨끗하게 돌려준 거니까요. 그런데 세션 끝에 도는 훅은 같은 사건을 "중단됨"으로 알려줍니다. 훅 입장에선 러너가 자식을 죽인 것이거든요.

⚠️ 둘을 맞춰보면 완료 수가 모자랍니다

그래서 훅이 남긴 기록을 완료 카운터와 대조하면 완료가 적게 세어집니다. 버그가 아니라 설계예요. 문서의 처방이 명확합니다 — 훅은 세션 하나하나를 확실히 챙길 때, 카운터는 전체 비율을 볼 때 쓰라는 것. 둘을 같은 눈금으로 놓고 비교하면 안 됩니다. "왜 숫자가 안 맞지"로 며칠 날리기 좋은 자리라 미리 알아두면 좋습니다.

한 세션만 받으면 끝 카운터가 안 잡힙니다

보안을 위해 한 대가 세션 하나만 받고 통째로 버려지는 구성을 권한다고 앞서 정리했었죠. 그 구성에는 지표 쪽 부작용이 하나 있습니다. 세션이 끝나자마자 러너가 종료되는데, 끝을 세는 카운터 셋은 바로 그 직전에 올라갑니다. 수집기가 보통 십몇 초에서 1분 간격으로 긁어가니 증가한 순간을 거의 못 잡아요. 러너의 계열 자체가 사라져 버리거든요.

시작 카운터는 세션이 사는 동안 계속 보여서 잘 잡히는데, 이 구성에선 "누적 횟수"가 아니라 "지금 돌고 있는 수"에 가깝게 읽힙니다. 그래서 문서가 목적별로 대체 계열을 표로 제시합니다.

보고 싶은 것	대신 볼 것
처리량	기계를 띄운 호출 성공 수 — 단, 세션 수와는 어긋납니다
이용률	도는 세션 수 대 정원 — 언제 긁어도 유효
적체	대기 중인 세션 수 + 차단된 세션은 0 초과면 경보
실패	실패 카운터는 최선 노력 — 보이면 무조건 조사

첫째 줄에 함정이 하나 더 있습니다. 처리량 대용으로 쓰는 그 계열은 세션이 아니라 "기계를 띄우라는 요청을 처리한 횟수"를 셉니다. 미리 데워두는 요청이나 같은 세션에 대한 재요청이 섞이니 세션 수와는 벌어져요. 그리고 넷째 줄 — 세션이 뜨기 전에 난 실패는 실패 카운터에 안 잡힙니다. 소스를 내려받는 훅이 실패했거나 준비 단계나 표 발급에서 막힌 경우는 별도의 초기화 오류 계열에만 남아요. 대기 열 깊이는 아예 계열이 없어서 관리 화면에서 봐야 합니다. 배포까지는 명령 몇 줄로 끝나던 흐름과 달리, 여기선 배포 후에 뭘 보느냐가 훨씬 어렵습니다.

건강 확인이 항상 정상을 돌려줍니다

여기가 가장 위험한 오해입니다. 러너에는 상태를 알려주는 주소가 하나 있는데, 프로세스가 살아 있기만 하면 무조건 정상을 돌려줍니다. 서버와 대화하는 반복 동작이 완전히 멎어 있어도요. 그러니까 이 주소에 대고 거는 단순 확인은 "프로세스가 죽었는지"만 잡습니다.

진짜 신호는 응답 본문 안에 있어요. "마지막으로 서버와 대화한 뒤 얼마나 지났나"가 담겨 오는데, 이 값이 계속 커지면 반복 동작이 멈춘 것입니다. 확인 장치를 직접 짤 때는 이 값을 봐야 해요. 다만 첫 대화가 끝나기 전에는 이 값이 비어 있으니 그 경우를 따로 처리해야 합니다. 기계를 띄우는 쪽 프로그램도 마찬가지라, 본문의 "연결됨" 표시로 판단하고 응답 코드로는 판단하지 말라고 문서가 못을 박습니다.

지표에 이메일이 실려 나갑니다

프라이버시 쪽에서 놓치기 쉬운 대목. 러너가 한 사람에게 묶이면 그 계정의 이메일이 지표 라벨로 붙어 나갑니다. 지표 저장소를 사내 누구나 볼 수 있게 열어뒀다면 그대로 노출되는 거죠. 문서는 긁어올 때 그 라벨을 빼거나 해시하라고 안내합니다. 참고로 채널 쪽 신원에 묶인 러너는 그 계열이 아예 안 나옵니다 — 이메일이 없으니까요.

✅ 세션 쪽 지표를 끌어올 때의 규칙

한 대가 세션을 여럿 받는 구성이면, 각 세션이 따로 내보내던 지표를 러너 쪽 한 주소로 모아 다시 내보내게 할 수 있습니다. 세션 번호와 접속 경로가 라벨로 붙고, 세션이 끝나면 그 계열은 지워져요. 다만 규칙이 둘 있습니다 — 분포를 재는 종류는 안 넘어오고, 이름이 러너 쪽 것과 부딪히면 그냥 버려집니다. 그리고 한 대가 하나만 받는 기본 구성에서는 이 재작성이 아예 적용되지 않아, 세션이 자기 주소를 따로 엽니다. 이름과 표기가 바뀔 수 있다는 전제도 그대로 적용돼요 — 문서 자체가 "설치된 판에서 도움말로 직접 확인하라"고 적어둡니다.

자주 묻는 질문 (FAQ)

Q. 그럼 세션별 결과는 뭘로 남기나요?

세션 끝에 도는 훅이 정답입니다. 자식이 떠 있던 모든 종료에서 도니까요. 기계가 갑자기 회수되는 경우만 예외입니다. 반대로 총량 비율은 지표로 보세요.

Q. 경보는 어디에 걸어야 하나요?

문서가 두 가지를 콕 집습니다 — 마지막 대화 후 경과가 일정 시간을 넘으면, 그리고 대화 실패가 조금이라도 발생하면. 실패는 종류별로 계열이 나뉘어 있고 프로그램이 시작될 때부터 전부 존재해서, 값이 없어 경보가 안 뜨는 일은 없습니다.

Q. 버전이 섞여 있는지 알 수 있나요?

항상 값이 1인 정보용 계열이 하나 있는데, 여기에 기계 번호와 판, 그리고 붙여둔 이름표가 라벨로 달려 옵니다. 대수를 세는 용도가 아니라 목록을 뽑고 판이 어긋난 기계를 찾는 용도예요.

Q. 문서에 나온 이름과 실제가 다른데요?

문서가 스스로 밝힙니다 — 지표 계열과 일부 항목은 아직 옛 이름을 쓰고 있고, 설정 쪽은 새 이름을 씁니다. 둘은 같은 것을 가리켜요. 그리고 권위 있는 목록은 설치된 판의 도움말이라고 안내합니다.

✨ 정리하면

대시보드를 만들기 전에 "이 숫자가 무엇을 세는가"부터 확인하세요. 훅과 카운터는 같은 사건을 다르게 세고, 한 세션짜리 구성에서는 끝 카운터가 거의 안 잡히며, 건강 확인은 멈춰 있어도 정상을 돌려줍니다. 세션별 보증은 훅으로, 총량은 게이지로, 살아 있는지는 본문의 경과 시간으로. 그리고 이메일 라벨은 긁어올 때 지우세요. 비용과 권한을 함께 설계하는 흐름은 AI 지출 관리 허브에, 만든 서비스를 계속 굴릴 때의 기본기는 직접 만든 챗봇 편에 정리해 두었습니다.

출처: Claude Code 공식 문서 「자체 호스팅 환경 참조」 (2026-09-01 열람). 자체 호스팅 환경은 공개 베타 단계이며 팀·기업 요금제에서 관리자가 켜야 씁니다. 계열 이름과 기본값은 설치된 판에 따라 다르므로 도움말로 확인하세요.