스레드 풀 사용률 관측 결손 — Tomcat(기본값 그대로, 지표 없음) + Python DetectorPool(사용률·대기 지표 전무)

[Khyojae]

배경

USE method Saturation 축 점검 중 발견. gRPC 서버 스레드풀은 이미 #598이 추적 중이라 그건 제외하고, 나머지 두 스레드/워커 풀의 관측 결손을 묶어 등록한다.

1. Tomcat 스레드풀

• backend/src/main/resources/application.yml:290이 management.endpoint.prometheus를 include해 tomcat_threads_*가 /actuator/prometheus로 노출은 된다.
• 그런데 monitoring/grafana/dashboards/shadowfit-backend.json엔 이 지표를 보여주는 패널이 없다.
• docs/decisions/production-signal-checklist.md:338 — "Tomcat 스레드 풀 크기도 application.yml에 별도 설정 없이 기본값(200) 그대로 — 튜닝한 적 없음." 즉 사용률을 볼 수단도, 튜닝 근거도 둘 다 없는 상태.

2. Python DetectorPool (POSE_DETECTOR_POOL_SIZE)

• ai-server/app/core/mediapipe_detector.py:322-361에 lease 기반 DetectorPool이 있다.
• ai-server/app/observability/metrics.py:48-59에 정의된 지표는 spring_callback_total·active_sessions 둘뿐이고, 풀 사용률·대기(leases-in-use, wait count) 게이지는 전무하다(grep 전수 확인).
• AI detector pool: POSE_DETECTOR_POOL_SIZE=160 인데 160 동시세션에서 nolease 98% #617("POSE_DETECTOR_POOL_SIZE=160인데 160 동시세션에서 nolease 98%")이 이 풀의 고갈 증상을 이미 잡았지만, 그건 일회성 부하테스트로 발견한 것이지 상시 계측이 아니다 — 같은 문제가 운영 중 다시 생겨도 대시보드로는 못 본다.

참고

• backend/src/main/resources/application.yml:290
• docs/decisions/production-signal-checklist.md:336-358
• ai-server/app/core/mediapipe_detector.py:322-361
• ai-server/app/observability/metrics.py:48-59
• Spring gRPC 서버 스레드풀 — 설정 자체가 없다, 동시 유입량부터 재야 한다 #598 (gRPC 서버 스레드풀 — 별도 추적 중, 이 이슈 범위 아님)
• AI detector pool: POSE_DETECTOR_POOL_SIZE=160 인데 160 동시세션에서 nolease 98% #617 (DetectorPool 고갈 증상 — 상시 계측 부재의 결과로 참고)

[Khyojae]

설계 정리 (대화 기반)

Tomcat

코드 변경 없음. tomcat_threads_busy_threads/current_threads/config_max_threads가 Micrometer 기본으로 이미 /actuator/prometheus에 나오고 있다(application.yml:290이 prometheus를 include). 패널만 추가하면 된다.

Python DetectorPool — 신규 메트릭 4개 (ai-server/app/observability/metrics.py)

기존 shadowfit_ai_* 네이밍 컨벤션을 따르고, worker 라벨은 넣지 않는다(monitoring/prometheus.yml의 job target이 이미 worker="0/1/2"로 스크레이프 대상을 나눔).

• shadowfit_ai_detector_pool_in_use (Gauge) — DetectorPool.status()(mediapipe_detector.py:311-313)를 set_function()으로 스크레이프 시점에 읽음. active_sessions(metrics.py:52-59)와 동일 패턴, 새 갱신 지점 불필요
• shadowfit_ai_detector_pool_capacity (Gauge) — 위와 동일 패턴
• shadowfit_ai_detector_pool_rejected_total (Counter) — 훅 지점: acquire()의 return False(mediapipe_detector.py:260, capacity 초과로 거절되는 지점). self._guard 락 밖에서 증가시켜야 함 — 이 클래스가 이미 "락 안에서는 예약만, 비싼 작업은 락 밖" 원칙을 지키고 있음(acquire() 독스트링 참고)
• shadowfit_ai_detector_pool_build_wait_seconds (Histogram) — 훅 지점: event.wait()(mediapipe_detector.py:266-271, #599가 만든 대기 경로 — 동시 재시도가 같은 session_id의 PoseDetector() 생성 완료를 기다리는 구간). time.monotonic()으로 전후 측정

계측 함수는 record_callback()(metrics.py:54-59) 패턴대로 try/except로 감싸 계측이 본 경로를 절대 안 깨뜨리게 한다.

대시보드 — 보류 (블로커: #677, #680)

Tomcat 패널을 넣을 shadowfit-backend.json은 있지만, DetectorPool 패널을 넣을 AI 쪽 대시보드는 아직 없다(#677과 동일 사유로 막힘). 또한 트래픽/포화도/에러 신호가 대시보드 3곳에 흩어진 문제(#680)를 먼저 정리해야 이 이슈의 패널이 또 다른 파편 파일이 되는 걸 피할 수 있다. 결정: 코드 계측(위 4개 메트릭)은 #680과 무관하게 지금 진행 가능 — Prometheus는 대시보드 유무와 무관하게 수집한다. 패널 작업만 #677·#680 설계 확정 후로 미룬다.

---

정정: NO_LEASE는 실제 응답 경로에서 안 쓰인다

이 이슈를 설계하면서 PoseSkipReason.NO_LEASE(ai-server/app/models/pose.py:27)를 "풀 상한으로 거절된 경우"의 지표 근거로 쓰려다가 코드를 다시 보고 정정한다.

ai-server/app/api/endpoints/pose.py:178-195에서 lease_detector()가 None을 반환하면(세션 미시작이든 풀 상한이든) 응답은 NO_LEASE가 아니라 SESSION_NOT_FOUND로 통일해서 나간다:

lease = lease_detector(req.session_id)
if lease is None:
    return PoseResponse(
        success=False,
        skip_reason=PoseSkipReason.SESSION_NOT_FOUND,
        message=f"세션 {req.session_id}가 시작되지 않았습니다 (StartAnalysis 먼저 호출 필요)",
    )

이건 버그가 아니라 #605·#187 안 (d)가 정한 의도적 보안 설계다 — "풀 상한 걸림"과 "세션이 진짜 없음"을 다른 응답으로 구분해주면, session_id를 훑어 "지금 배정된 분석기가 있는 세션(≈ 진행 중)"을 열거할 수 있게 된다. test_pose_response_contract.py:115-129(test_배정_없음도_세션_없음과_구분되면_안_된다)가 이 계약을 테스트로 박아뒀다.

결론: 위 shadowfit_ai_detector_pool_rejected_total 카운터는 클라이언트 응답(skip_reason)과 무관하게 서버 내부(acquire() 반환값)에서만 세는 것이라 이 보안 설계와 충돌하지 않는다. 다만 구현 시 "NO_LEASE 응답을 늘려서 원인을 구분하자"는 방향으로는 가면 안 된다는 점을 여기 명시해둔다 — #617("160세션에서 nolease 98%")도 실은 이 통일된 SESSION_NOT_FOUND 집계였을 가능성이 있어, 그 이슈를 다시 볼 때도 같은 함정을 주의할 것.

---

🤖 Generated with Claude Code