대시보드
~
사용자별 업로드 카운트
사용자별 삭제 카운트
사용자별 업로드양
기간 내 업로드 없음
사용자별 삭제량
기간 내 삭제 없음
장비 상태 현재 기준
전송/로그인 실패 건수
최근 이상 알림
시각(KST)장비지표심각도값평소내용
-
로그 조회
~
고객사:
기본 조회 3개월, 이상 조회 시 날짜 지정 후 진행 · CWD 실패 중 직후 그 경로가 생성된 건(존재 확인)은 실패가 아니라 목록에서 제외
시간업로드 장비사용자사용자 IP작업 파일 경로크기전송시간상태
검색 조건을 입력하고 조회하세요.
장비 관리
호스트명IP장비상태데몬상태 CPU / MEM / Disk버퍼 마지막 연결그룹
로딩 중...
그룹 관리
로딩 중...
API 가이드
인증

모든 요청에 API 키가 필요합니다. 키는 관리자가 설정 > 고객 계정 > API 키에서 발급합니다.

방법 1 — X-API-Key 헤더 (권장)
방법 2 — Authorization 헤더
  • 조회 전용입니다. GET 외의 요청은 403으로 거부됩니다.
  • 권한 범위는 키를 발급한 계정과 같습니다. 고객 계정 키는 해당 고객사의 장비 데이터만 조회됩니다.
  • 키는 발급 시 한 번만 표시됩니다. 분실하면 재발급해야 합니다.
  • 요청 한도는 분당 60회이며, 초과하면 503이 반환됩니다.
엔드포인트
경로설명
로그 조회 파라미터
이름예시설명
오류 응답
코드의미
사용 예시
구성도
수집 → 저장 → 판정 → 알림·조회 · 인수인계 문서
시스템 구성
장비의 데몬과 WAS 의 쓰기 버퍼가 각각 버퍼를 들고 있어 한쪽이 멈춰도 로그를 버리지 않는다 — WAS 가 내려가면 데몬이 buffer.jsonl 에 쌓아 두고, DB 가 내려가면 쓰기 버퍼가 재시도 큐에 들고 있다가 다시 쓴다.
FTP 장비 N대 · proftpd
xferlog · proftpd.log
전송 · 로그인 · CWD 550
soltrace_daemon.py
10초 폴링 · 200건 배치
60초 하트비트
buffer.jsonl
WAS 장애 시 보관 · 최대 5만 줄
복구되면 자동 재전송
soltrace_bulk.py
과거 로그 일괄 전송 (수동)
WAS 서버 · Rocky Linux 8
Nginx 80/443
TLS · gzip · 레이트리밋
수집 300r/m · 조회 60r/m · 로그인 10r/m
FastAPI + Gunicorn 2 worker
JWT · API 키 · 고객사 데이터 격리
write_buffer
3초 flush · 최대 2000건
실패 배치는 재시도 큐로
service_monitor
5분 주기 — 롤업 · 이상 판정 · 발송
디스크 자동 정리
PostgreSQL 16
ftp_logs
월별 파티션 · 기본 보존 36개월
service_metrics
장비 × 10분 버킷 롤업
최근 2시간은 매 주기 재집계
service_alerts · episodes
이상 버킷과 진행 중인 장애 상태
cron · 자동 정리
월 파티션 생성 · DB 백업(3년)
디스크 임계 초과 시 오래된 월 삭제
알림 · 조회
웹훅 · Slack
감지 / 복구 알림 · 음소거 가능
HMS 메일
같은 내용을 메일로
웹 대시보드 (SPA)
대시보드 · 로그 조회 · CSV/XLSX
외부 시스템
X-API-Key 조회 전용 토큰
이상 감지 · 알림 흐름
판정은 10분 버킷마다 하지만, 발송은 에피소드(장비 × 지표)당 한 번이다. 짧은 흔들림으로 메시지가 쏟아지지 않게 발송 앞단에 지속 조건을 둔다.
1 · 롤업
10분 버킷 집계
전송 실패율 · 전송 속도
로그인 실패율 · CWD 실패
2 · 판정
baseline 이탈
최근 7일 median + k·MAD
절대 하한과 최소 표본으로 오탐 차단
3 · 적재 (화면)
service_alerts
이상 버킷은 모두 남는다
발송 여부와 무관하게 대시보드에 표시
4 · 발송 게이트
보냄
지속 버킷 수 충족(기본 2 = 20분)
심각 등급은 즉시
주의 → 심각 승격 1회
보내지 않음
1버킷 반짝 · 같은 장애의 반복
이상 알림이 없었으면 복구도 없음
5 · 복구
30분(3버킷) 조용
에피소드 종료 → 복구 알림
지속 시간과 이상 건수를 함께 보낸다
지속 버킷 수 · 임계값은 설정 > 알림 설정 > 이상 감지 임계값에서 바꾼다 (저장하면 다음 판정 주기에 반영).
인수인계 문서 운영을 넘겨받는 사람이 먼저 읽는 문서
위 구성도가 무엇이 어떻게 연결돼 있는지라면, 아래는 무엇을 해야 하는지다. 비밀값(비밀번호·토큰·웹훅 URL)은 여기에 적지 않는다 — 있는 위치만 적고 값은 서버의 .env 와 설정 화면에서 확인한다.
1 · 한 장 요약
FTP 장비(proftpd)의 로그를 데몬이 파싱해 WAS 로 보내고, WAS 가 저장·분석해 대시보드와 알림으로 보여준다. 서비스 트래픽 경로가 아니라 관측 경로라 이 시스템이 멈춰도 FTP 전송 자체는 계속된다 — 다만 그동안의 기록과 알림이 비고, 장비 쪽 버퍼(최대 5만 줄)를 넘기면 그만큼은 복구되지 않는다.
하루 한 번 볼 것 — 대시보드 장비 상태(현재 기준)에 주의·심각이 있는지, 최근 이상 알림에 새 항목이 있는지, 설정 > DB 저장소의 디스크 사용률.
2 · 서버 · 경로 (WAS)
코드/opt/soltrace (git 저장소)
설정 · 비밀값/opt/soltrace/.env (DB 접속, SECRET_KEY, 관리자 초기 비밀번호)
서비스soltrace-was · nginx · postgresql-16
앱 로그/var/log/soltrace/error.log (트레이스백)
access.log · selfupdate.log — 저널이 아니라 파일
DBPostgreSQL 16 · DB soltrace
백업/var/backups/soltrace (매일 03:00, 3년 보관)
장비 데몬/opt/soltrace-daemon · config.ini
서비스 soltrace-daemon · 로그 /var/log/soltrace-daemon/daemon.log
3 · 자주 하는 작업
WAS 업데이트설정 > 시스템 업데이트 버튼
또는 서버에서 sudo bash scripts/update_rocky8.sh main
새 장비 붙이기장비에 데몬 설치 → 장비 관리에서 확인(Confirm) → 그룹 배정
데몬 업데이트장비 관리 > 해당 장비 > 원격 업데이트
고객사 계정 · API 키설정 > 고객 계정 — FTP 계정 매핑을 반드시 등록한다(그룹 + FTP 아이디). 없으면 그 계정은 아무것도 보지 못한다
알림 채널설정 > 알림 설정 (웹훅 · HMS) · 테스트 발송 버튼
알림이 잦을 때설정 > 이상 감지 임계값 — 먼저 발송 전 지속 버킷 수를 올리고, 그래도 잦으면 해당 지표의 하한을 올린다
작업 중 알림 끄기설정 > 알림 설정 > 음소거 — 다시 켜는 것을 잊지 않는다
보존 기간설정 > DB 저장소 (기본 36개월)
4 · 이럴 때 이렇게
화면이 안 뜨거나 500systemctl status soltrace-was → /var/log/soltrace/error.log 마지막 트레이스백. 배포 직후면 selfupdate.log
로그가 안 들어옴장비 관리에서 데몬 상태 확인(하트비트 120초) → 장비에서 systemctl status soltrace-daemon, daemon.log. WAS 가 살아나면 장비 버퍼가 자동 재전송한다
알림이 쏟아짐같은 장비·지표면 대개 임계가 그 장비에 안 맞는 것 — 위 '알림이 잦을 때'. 작업 중이면 음소거
디스크 부족설정 > DB 저장소에서 사용률·파티션 확인. 자동 정리가 켜져 있으면 오래된 월부터 되돌릴 수 없이 지운다 — 필요한 달은 먼저 백업 확인. DB 데이터 디렉토리를 다른 볼륨으로 옮겼다면 같은 화면의 디스크 감시 경로도 그 마운트로 바꿔야 한다(README '디스크 확장 · DB 위치 이동')
배포가 오래 걸림스키마 단계에서 락 대기일 수 있다(lock_timeout=5s·3회 재시도). 로그를 보고 기다리되, 반복 실패면 한산한 시간에 다시 시도
CWD 실패 급증대시보드 > CWD 실패 분석 — 한 경로에 몰려 있으면 침입 탐색이 아니라 홈·업로드 경로 설정 오류다. 원인 확인 후 그 경로를 알림에서 제외
5 · 자동으로 도는 것 (건드리지 않아도 됨)
5분마다롤업 · 이상 판정 · 알림 발송 · 디스크 점검 (WAS 내부 스레드)
매일 03:00DB 증분 백업 → /var/backups/soltrace (/etc/cron.d/soltrace-backup)
매월 1일 00:30월별 파티션 생성 (/etc/cron.d/soltrace-partitions)
인증서Let's Encrypt 자동 갱신 (설치 시 등록) — 만료 알림이 오면 갱신 동작부터 확인
백업·파티션 cron 이 살아 있는지는 ls /etc/cron.d/soltrace-* 와 /var/log/soltrace/backup.log 로 확인한다.
6 · 넘겨받을 때 확인할 것
☐ WAS 서버 SSH 접근(sudo) · 장비 서버 접근
☐ 관리자 계정 인계 후 비밀번호 변경, 퇴사자 계정 비활성화
☐ 저장소(GitHub) 접근 권한 — 배포가 git pull 기반이다
☐ 알림 채널(웹훅 · HMS) 수신처가 지금 팀인지 · 테스트 발송
☐ 도메인 · 인증서 갱신 주체
☐ 백업 위치와 복구를 실제로 해봤는지
☐ 고객사 계정 · API 키 목록과 용도
☐ 이상 감지 임계값을 손댔다면 왜 그렇게 뒀는지
더 자세한 설치·배포·SQL 은 저장소 README.md, 변경 내역은 왼쪽 변경 이력 탭, API 사용법은 API 가이드 탭.
변경 이력
불러오는 중…
설정
통신사 목록
  • 불러오는 중…
비밀번호 변경
접속 허용 IP
현재 접속 IP: -
한 줄에 하나씩. CIDR 대역 가능. 비워두면 모든 IP 허용.
예: 192.168.1.0/24, 10.0.0.5
저장 전 현재 IP 포함 여부를 확인하세요.
로그인 화면
로그인 창 상단에 표시됩니다. 비우면 SolTrace.
최대 2000자. 줄바꿈이 그대로 보입니다. 비우면 표시하지 않습니다.
배경 이미지를 등록하면 이미지가 우선합니다. 비우면 기본(어두운 반투명) 배경.
jpg · png · gif · webp · 최대 2MB. 화면을 꽉 채우도록 잘려서 표시됩니다.
jpg · png · gif · webp · 최대 512KB. 제목 왼쪽에 높이 32px로 표시됩니다. 비우면 기본 아이콘.
이미지는 고른 즉시 저장됩니다. 문구·색상은 저장을 눌러야 반영됩니다.
시스템 업데이트 (git)
브랜치
-
현재 커밋
-
커밋 일시
-
메시지
-
상태
-
업데이트 시 origin/main을 받아 재배포하며, 서비스가 1~2분간 재시작됩니다.
DB 저장소 현황
데이터베이스 전체
-
ftp_logs (전체 파티션)
-
데이터 보유 기간
-
디스크
-
default 파티션
-
보존 기간 개월 초과 파티션은 야간 백업 후 삭제됩니다. 기간을 줄여도 즉시 지워지지는 않습니다.
디스크 감시 경로 위 사용률과 아래 자동 정리가 함께 보는 경로(WAS 서버 기준). DB 데이터 디렉토리를 별도 볼륨으로 옮겼다면 그 마운트로 바꾸세요 — 그러지 않으면 여유가 남은 / 를 계속 보게 됩니다.
디스크 자동 정리
% 초과 시 백업 여부와 관계없이 가장 오래된 월 파티션부터 삭제합니다. 되돌릴 수 없습니다.
행 수는 통계 추정치입니다. 월별 파티션은 보존 기간만큼 미리 만들어 두므로, 목록에 있는 과거 월이라도 '데이터 기간'이 비어 있으면 실제 로그는 없습니다. default 파티션에 행이 남아 있으면 해당 월 파티션이 만들어지지 않고 보존기간 정리에서도 제외되므로 scripts/rebalance_default_partition.sql 로 재배치하세요.
월별 파티션
파티션데이터 기간행 수(추정)테이블인덱스합계삭제
불러오는 중…
알림 설정
발송 중
웹훅
HMS 메일 게이트웨이
이상 감지 임계값
클수록 둔감해져 알림이 줄어듭니다.
이상이 이 버킷 수만큼 이어질 때만 알림을 보냅니다(2 = 20분). 한 버킷 반짝했다 스스로 돌아오는 흔들림은 화면에만 남고 감지·복구 메시지가 나가지 않습니다. 1 = 즉시 발송, '심각' 등급은 이 값과 무관하게 바로 나갑니다.
평소 대비 이 비율 이상 떨어지면 알림 (0.6 = 60%↓)
평소 속도의 하위 이 비율(0.05 = 하위 5%)보다 느릴 때만 알립니다. 업로드 사용자마다 회선이 달라 평소에도 느린 구간이 있으면 임계가 자동으로 내려갑니다. 낮출수록 둔감해집니다.
아래 기준 크기 이상 전송이 이 건수 미만이면 속도 판정을 건너뜁니다.
원인이 밝혀진 경로(홈·업로드 경로 설정 오류 등)를 CWD 실패 집계에서만 뺍니다. 로그 조회에는 그대로 남습니다. 최근 2시간 버킷은 다음 판정 주기에 다시 집계됩니다.
전송 속도 판정 기준 크기
-
집계 버킷 / baseline
-
작은 파일은 연결·인증 오버헤드가 전송시간의 대부분이라 실효속도가 낮게 나옵니다. 전송 속도 판정은 기준 크기 이상의 성공한 전송만 사용하므로, 소량 파일을 대량 업로드해도 속도 저하로 오인하지 않습니다. 이 두 값은 .env 에서만 변경합니다(재배포 필요).
관리자 계정 추가
관리자 계정에는 설정 > 계정 보안의 접속 허용 IP가 그대로 적용됩니다. 비밀번호를 5회 연속 틀리면 계정이 15분간 잠깁니다.
관리자 목록
아이디상태마지막 로그인작업
불러오는 중…
마지막 활성 관리자와 로그인 중인 본인 계정은 비활성화·삭제할 수 없습니다.
고객 계정 추가
이 계정이 볼 그룹과 FTP 아이디를 등록합니다. 그룹은 여러 개, 아이디도 그룹마다 여러 개 넣을 수 있습니다(쉼표 구분). 등록하지 않으면 로그인해도 아무 데이터가 보이지 않습니다. 고객사를 먼저 입력하면 그 고객사의 그룹만 목록에 나옵니다.
고객 계정 목록
아이디 · 비고고객사FTP 계정허용 IP등록상태작업
불러오는 중…
API 키 (조회 전용)
키가 발급되었습니다 — 지금 복사하세요. 이 화면을 벗어나면 다시 볼 수 없습니다.
키계정메모마지막 사용만료상태작업
불러오는 중…
키는 조회(GET)만 가능하며 권한 범위는 소유 계정과 같습니다 (고객 계정 키는 해당 고객사 데이터만 보입니다). 사용 예:
curl -H "X-API-Key: slt_..." https://<주소>/api/v1/logs?size=50