로그 및 모니터링
로그 확인
로그는 도커가 갖고 있습니다. 호스트에 쌓이는 로그 파일을 따로 지울 일이 없습니다 — 회전은 compose 에 설정돼 있습니다.
cd /opt/kopens/plantpulse-ai-docker/bin
./logs.sh # 스택 전체를 따라 본다
./logs.sh plantpulse-copilot-web # 서비스 하나 — compose 서비스 이름 그대로 (여러 개 나열 가능)
./logs.sh --tail 50 # 기본보다 «적게» 보고 싶을 때
-f 를 붙일 필요가 없습니다logs.sh 는 이미 따라가기(-f)로 돕니다. 뒤에 준 --tail 값이 기본값을 이깁니다.
compose 를 직접 불러도 됩니다.
cd /opt/kopens/plantpulse-ai-docker
docker compose logs -f --tail=200 plantpulse-rag-api
docker compose logs -f plantpulse-litellm
어느 컨테이너를 보면 되나
| 증상 | 볼 컨테이너 |
|---|---|
| 화면이 안 뜬다 | plantpulse-proxy · plantpulse-copilot-web |
| 답이 안 나온다 | plantpulse-litellm · plantpulse-llm |
| 문서를 못 찾는다 | plantpulse-rag-api · plantpulse-lightrag |
| 문서를 못 읽어들인다 | plantpulse-docling-serve · plantpulse-document-understanding-api |
| 시계열 분석이 안 된다 | plantpulse-timeseries-insight-api · -server |
| 관리 콘솔이 이상하다 | plantpulse-admin-api · plantpulse-admin-web |
| 커넥터 · 그래프 거울 · 설비 타임라인이 이상하다 | plantpulse-digital-thread-api · plantpulse-digital-thread-neo4j |
| 영상이 색인되지 않는다 · 음성으로 묻기가 안 된다 (영상 · 음성을 켠 설치) | plantpulse-asr · plantpulse-asr-audio · plantpulse-document-understanding-api · plantpulse-rag-api |
컨테이너 전체 목록과 역할은 설치 개요 에 있습니다.
AI 도구 호출 관찰 — 묻기의 도구 줄과 Phoenix
AI 가 답을 만들며 무엇을 했는지 보는 자리는 둘입니다.
| 자리 | 무엇 | 여는 법 |
|---|---|---|
| 묻기 답 위의 도구 줄(「도구 N개 사용 · N초」) | 그 답이 부른 도구와 물은 값, 실패한 도구 | 묻기(/chat)에서 바로 |
Arize Phoenix (plantpulse-phoenix) | LLM 호출 트레이스 — 프롬프트 · 응답 본문까지 | 호스트에 열려 있지 않습니다 — 진단할 때만 PP_DEBUG_PORTS=1 로 엽니다 → 서비스 포트 맵 |
Phoenix 는 기본 스택에 포함되어 트레이스를 계속 모읍니다. 2026.09 부터 6006 을 호스트에 발행하지 않을 뿐입니다 — 인증이 없는데 담는 것이 질문과 답의 본문이기 때문입니다. 관리 콘솔 LLM 의 로그 화면에는 모델 · 토큰 · 지연만 있고, 본문은 Phoenix 에만 있습니다.
묻기 답마다 붙는 도구 줄을 펴면 어떤 도구가 어떤 값으로 불렸는지, 실패한 것이 있는지 볼 수 있습니다. 자동화가 돈 회차는 자동화의 실행 기록에 「근거 — 도구 호출 N번」 으로 남습니다.
서비스 상태 모니터링
cd /opt/kopens/plantpulse-ai-docker/bin
./status.sh # compose ps + 외부 노출 지점(copliot-web :80) 응답 확인
./health.sh # 위에 더해 호스트 디스크 · 컨테이너 자원 · 서비스별 최근 로그
./doctor.sh # 무엇이 잘못됐는지 진찰 — 아무것도 바꾸지 않습니다
빠르게 보려면 status.sh, 장애 중이면 health.sh 로 넓게 본 뒤 doctor.sh 로 좁힙니다.
헬스 체크 엔드포인트
| 서비스 | 헬스 체크 URL | 비고 |
|---|---|---|
| AI Chat Web | http://127.0.0.1/actuator/health | 프록시를 지나 들어갑니다 |
| RAG | http://127.0.0.1:7115/health | rag-api. 키 없이 됩니다(면제 경로) |
| 시계열 인사이트 | http://127.0.0.1:8970/health | 키 없이 됩니다(면제 경로) |
| LiteLLM | http://127.0.0.1:4000/health/liveliness | /health 는 마스터 키를 요구할 수 있습니다 |
| 관리 콘솔 | http://127.0.0.1:5959/health | 컨테이너 자체 헬스는 /ping. 포트는 PI_ADMIN_WEB_PORT(기본 5959) — 바꿨다면 그 값으로. 뒤의 서비스 상태 집계는 콘솔 화면에서 |
| 디지털 스레드 | 호스트에서 닿지 않음 — 관리 콘솔 홈의 디지털 스레드 API 카드 | 7140 은 발행하지 않습니다. 카드는 /health 를 읽고, 그래프 거울 투영이 failed 면 degraded(노란불)로 내려갑니다. 커넥터 주기 동기화의 상태(connector_sync)도 여기 실리지만 정보일 뿐이라 노란불을 만들지 않습니다 |
| 문서 이해 | 호스트에서 닿지 않음 — docker exec plantpulse-document-understanding-api python3 -c "import urllib.request;print(urllib.request.urlopen('http://localhost:7120/health').read().decode())" | 영상 · 음성을 켠 설치에서는 components.asr.status 가 up 이어야 합니다(꺼진 설치는 disabled — 정상). 녹취 서빙이 죽으면 degraded 입니다 |
예전에 LightRAG 를 7114 로 직접 열어 두었지만, 지금은 rag-api(7115) 가 유일한
관문이고 LightRAG 자체는 컨테이너 안에만 있습니다. 7114 를 찔러 「죽었다」고 판단하지
마십시오 — 애초에 그 자리에 없습니다.
Qdrant · vLLM · 임베딩 · 리랭커 · docling · 시계열 추론 · admin-api 는 호스트 포트를
발행하지 않습니다(2026-08-21). Phoenix 도 2026.09 부터, 디지털 스레드 API(7140)와 그 전용 Neo4j 도
2026.10 부터 같습니다. 컨테이너 안에서만 서로 부르기 때문에 127.0.0.1 로
찔러도 안 됩니다. 진단이 필요하면 디버그 오버레이로 되살립니다 →
서비스 포트 맵
플랫폼 server-web 이 내주므로 헬스 체크도 플랫폼 쪽을 봅니다.
지표 — /metrics
2026.10 재릴리즈부터 파이썬 뒷단 다섯(RAG · 시계열 인사이트 API · 문서 이해 · 비전 · 디지털 스레드)이 Prometheus
텍스트 형식의 지표를 GET /metrics 로 냅니다. 새 포트는 없고 각 서비스의 원래 포트에 붙은 경로입니다.
| 서비스 | 지표 주소 | 호스트에서 |
|---|---|---|
| RAG | http://127.0.0.1:7115/metrics | 닿습니다 |
| 시계열 인사이트 API | http://127.0.0.1:8970/metrics | 닿습니다 |
| 문서 이해 · 비전 · 디지털 스레드 | plantpulse-document-understanding-api:7120 · plantpulse-vision-api:7130 · plantpulse-digital-thread-api:7140 의 /metrics | 닿지 않습니다 — 같은 compose 네트워크 안에서 긁습니다 |
curl -s -H "X-API-Key: <PI_INBOUND_API_KEY>" http://127.0.0.1:7115/metrics | grep '^http_requests_total' | head
/metrics 는 키가 필요합니다헬스 경로(/ping · /health)와 달리 인바운드 키 뒤에 있습니다. Prometheus 로 긁을 때는 X-API-Key 헤더나
authorization:(Bearer) 설정으로 PI_INBOUND_API_KEY 를 줍니다. 키 없이 부르면 401 입니다.
| 지표 | 뜻 |
|---|---|
http_requests_total | 처리한 요청 수 — 메서드 · 경로 템플릿 · 상태 계열(2xx 등)별 |
http_request_duration_seconds | 요청 지연 히스토그램 — 같은 라벨 |
http_requests_in_flight | 지금 처리 중인 요청 수 |
app_build_info | 서비스 이름 · 버전 · 릴리즈(release 라벨, 예 2026.10). 값은 늘 1 |
경로 라벨은 실제 경로가 아니라 경로 템플릿이고, 어느 라우트에도 맞지 않는 요청은 <unmatched> 하나로 접힙니다 —
ID 가 들어간 경로마다 시계열이 생기지 않습니다. 프로세스 · GC 같은 기본 지표도 함께 나옵니다.
요청 하나를 로그에서 잇기 — X-Request-ID
같은 다섯 서비스는 요청마다 id 를 붙여 응답 헤더 X-Request-ID 로 돌려주고, 그 요청이 도는 동안의 모든 로그 줄에
request_id 로 싣습니다. 부르는 쪽이 X-Request-ID(1~128자, 영문 · 숫자 · . _ -)를 실어 보내면 그 값을 그대로
씁니다. 화면에 뜬 오류를 로그와 맞출 때 이 값 하나로 찾습니다.
docker compose logs plantpulse-rag-api 2>&1 | grep '<request_id 값>'
디스크가 찰 때
로그 파일을 손으로 지울 필요가 없습니다 — 컨테이너 로그는 도커가 회전시킵니다. 디스크를 먹는 것은 대개 이미지와 볼륨입니다.
docker system df # 무엇이 얼마나 쓰고 있나
docker image prune -f # 태그 없는 옛 이미지 정리
docker volume prune 을 함부로 돌리지 마십시오Neo4j 두 인스턴스 · Qdrant · LightRAG 저장소 · 설치별로 학습한 시계열 모델(pi-ttm-tuned-models)과
TLS 인증서가 볼륨에 있습니다. 컨테이너가 내려간 사이에 돌리면 지식 그래프와 벡터 색인, 현장에서 학습한
모델이 사라집니다.
health.sh 가 호스트 디스크와 컨테이너 자원을 함께 보여 주므로, 정리 전에 그것부터 보십시오.