HWSS 백엔드 가이드

1스택 띄우기

docker compose -f infra/observability/docker-compose.yml up -d

내릴 때는 같은 명령의 down, 쌓인 데이터까지 지우려면 down -v. 백엔드(bootRun)가 떠 있으면 Prometheus 가 15초마다 /actuator/prometheus 를 당겨가고, 1분 안에 Grafana → HWSS → “HWSS API Overview” 에 HTTP 처리율 · p95 지연 · 5xx 비율 · JVM 힙 · Hikari 풀 · 외부 연동 실패율/지연이 그려집니다.

2Loki 로 로그 보기

Grafana → Explore → 왼쪽 위 데이터소스 드롭다운을 Loki 로 바꾸고, Label browser 에서 container 라벨을 고르면 됩니다. 질의는 LogQL 입니다.

# 컨테이너 하나의 로그
{container="hwss-loki"}

# 문자열 필터 — 라벨로 범위를 좁힌 뒤 그 안에서 찾는다
{container="hwss-api"} |= "ERROR"

# JSON 로그일 때, 한 요청이 남긴 줄만
{container="hwss-api"} | json | mdc_requestId="응답 헤더 X-Request-Id 값"

주의 bootRun 으로 띄운 백엔드의 로그는 그냥은 Loki 에 들어오지 않습니다. Alloy 의 도커 수집은 컨테이너 로그만 보는데 bootRun 은 호스트 JVM 프로세스이기 때문입니다. 그래서 파일 수집 갈래를 하나 더 두었습니다 — compose 가 hwss-investigation-agent-backend/runtime/logs 를 컨테이너의 /var/log/hwss 로 마운트하고, Alloy 가 그 폴더의 *.log 를 따라 읽어 같은 container="hwss-api" 라벨로 보냅니다. 아래처럼 출력을 그 폴더로 흘리기만 하면 됩니다.

# 최초 1회
mkdir -p hwss-investigation-agent-backend/runtime/logs

# 기동 — hwss-investigation-agent-backend/ 에서
LOG_FORMAT=json DB_PASSWORD=hwss AUTH_JWT_SECRET=local-dev-only-secret-key-32bytes-min AUTH_LOCAL_PASSWORD=devpass SPRING_PROFILES_ACTIVE=local ./gradlew -q :hwss-api:bootRun | tee runtime/logs/app.log

LOG_FORMAT=json 이라야 | json 필드 질의가 됩니다. -q 는 Gradle 자신의 진행 줄을 빼서 파일이 JSON 줄로만 차게 합니다. 수집까지 10초쯤 걸리고, {container="hwss-api"} 가 잡히면 된 것입니다. 다른 경로에 남기려면 HWSS_LOG_DIR 에 절대 경로를 주고 스택을 다시 올립니다. 라벨 이름을 서버(컨테이너 수집) 쪽과 같게 맞춰 두었으므로 hwss-api 질의는 로컬과 개발 서버가 동일합니다.

기본 로그는 사람이 읽는 콘솔 형식이라 | json 필드 질의가 되지 않습니다. LOG_FORMAT=json(또는 json 프로필)을 주면 한 줄 JSON 이 되고, 요청마다 붙는 X-Request-Id(응답 헤더로도 돌아옵니다)가 mdc.requestId 로 나갑니다. 사번 등 개인정보는 로그에 싣지 않습니다 — 누가 무엇을 했는지는 감사 원장(audit_logs)의 몫입니다.

막힐 때

구성 파일과 개발 서버 반입 방식은 infra/observability/README.md, 스택을 이렇게 나눈 근거는 docs/decisions/20260828-observability-stack.md, 프론트·이미지시스템 데모까지 함께 띄우는 절차는 docs/guides/local-dev-run-guide.md 에 있습니다.