Stats

**Stats**
종류	서버 활동 통계
개발	PLAYCITY
최신 개발 버전	0.3.1
지원 플랫폼	Paper 26.2 build 111 이상
필요 Java	Java 25
서버 API	Paper API 26.2
의존성	없음
데이터 저장	SQLite·PostgreSQL·MySQL·MariaDB
Folia	지원 선언 없음
상태	개발 중
라이선스	명시되지 않음

Stats는 플레이시티 블록의 서버 활동을 세션·시간·일 단위로 집계하여 저장하는 자체 개발 마인크래프트 플러그인이다. 명령어 사용, 접속 활동, 블록 작업, 이동·전투 지표 등을 일정한 기준으로 남겨 서버 운영 상태와 활동 추이를 분석하는 데 활용한다. 좌표나 채팅 본문 같은 원시 이벤트를 저장하는 플러그인이 아니라, 서버 성능과 개인정보를 고려해 선별한 카운터를 수집하는 방식이다.

주요 기능

Stats의 주요 기능은 서버 운영에 필요한 활동 데이터를 저비용 집계 형태로 정리하는 것이다.

접속 세션, 플레이 시간, AFK 시간, 활동한 분 수집
채팅 횟수와 문자 수 집계
명령어 별칭 정규화와 시간·일 단위 사용 횟수 집계
시간 단위 블록 설치·파괴 총량과 소재 그룹별 일 단위 집계
사망 원인, 플레이어·비플레이어 처치 수 집계
일반 이동거리와 텔레포트 횟수·거리 집계
데이터베이스 비동기 배치 저장
관리자용 상태 확인, 수동 저장, 설정 재불러오기

명령어는 원문 전체를 저장하지 않고 동일 기능의 별칭을 대표 키로 통합한다. 게임 모드나 월드 편집 재료처럼 사전에 허용한 저카디널리티 값만 제한적으로 구분하며, 대상 플레이어명·메시지 본문·좌표 등의 인자는 저장하지 않는다.

Stats 자체에는 실시간 위험 감지나 자동 경보 기능이 없다. 월드 편집 명령 사용량과 블록 그룹별 작업량 등 저장된 집계는 별도 분석·대시보드 계층에서 이상 행동을 판단하는 보조 자료로 사용할 수 있다.

명령어

관리자가 사용할 수 있는 기본 명령어는 다음과 같다. 모든 명령은 stats.admin 권한 또는 OP 권한이 필요하다.

/stats reload
/stats status
/stats db ping
/stats db health
/stats flush

명령어	용도
`/stats reload`	설정과 명령어 별칭 규칙을 비동기로 다시 불러온다. 새 설정 초기화에 실패하면 기존 동작 상태를 유지한다.
`/stats status`	활성화·초기화 상태, 데이터베이스 종류, 보류 중인 배치와 최근 플러시 결과를 확인한다.
`/stats db ping`	비동기로 데이터베이스에 `SELECT 1`을 실행하여 연결과 지연 시간을 확인한다.
`/stats db health`	SQL을 실행하지 않고 데이터베이스 연결 풀의 활성·유휴·대기 상태를 확인한다.
`/stats flush`	대기 중인 통계 데이터를 즉시 비동기로 저장한다. 저장할 데이터가 없으면 데이터베이스 연결을 요청하지 않는다.

수집 범위와 개인정보

Stats는 플레이어 UUID와 마지막으로 확인한 이름, 세션 시작·종료 월드명, 시간·일 단위 활동 카운터를 저장한다. 다음 정보는 수집하지 않는다.

정확한 좌표와 이동 경로 이력
채팅 본문
원시 명령줄과 전체 명령 인자
IP 주소와 클라이언트 식별 정보
인벤토리 스냅샷
개별 블록 이벤트의 좌표와 시각

블록 작업은 개별 원본 행 대신 container, redstone, ore, stone 같은 제한된 소재 그룹으로 합산한다. 이동거리는 기본 주기의 위치 차이를 합산한 근사치이며 좌표 자체는 저장하지 않는다.

운영 참고

Stats 0.3.1은 Java 25로 실행하는 Paper 26.2 build 111 이상을 대상으로 하며 SQLite, PostgreSQL, MySQL·MariaDB를 지원한다. 최초 실행에서는 setup.enabled: false인 안전 모드로 설정 파일만 생성하고, 데이터베이스 연결과 수집을 시작하지 않는다. 운영자가 설정을 확인한 뒤 값을 true로 변경하고 서버를 재시작하거나 /stats reload를 실행해야 한다. 0.3.1에서는 Paper 환경의 PostgreSQL 연결 초기화 과정에서 발생하던 JDBC 드라이버 등록 경고를 해소했으며, 기존 데이터베이스 설정과 저장 데이터는 그대로 호환된다.

기본 배치 주기는 300초이다. 접속자와 이벤트가 모두 없어 메모리 버퍼가 비어 있으면 타이머와 로컬 작업만 실행된다. 현재 원격 데이터베이스 풀 기본값인 minimumIdle: 0에서는 이때 새 연결을 요청하지 않으므로 원격 통신도 발생하지 않는다. 기존 설정에서 최소 유휴 연결 수를 1 이상으로 지정했다면 연결 풀이 유휴 연결을 유지할 수 있다. 온라인 플레이어가 있으면 명시적 입력이 없어도 플레이 시간과 AFK 시간이 누적되므로 저장 대상이 생긴다.

비어 있지 않은 배치는 데이터베이스 전송 전에 체크섬이 포함된 로컬 내구 저장소에 기록하고, 데이터베이스 반영이 확인된 뒤에만 삭제한다. 데이터베이스 장애가 발생하면 같은 배치를 메모리와 로컬 저장소에 보존하여 다음 플러시 또는 다음 기동에서 중복 합산 없이 재시도한다. 다만 주기 플러시 전에 아직 내구 저장소로 옮겨지지 않은 활성 메모리 버퍼는 프로세스가 강제 종료되면 유실될 수 있다. 로컬 저장소에도 좌표·채팅 본문·원시 명령줄은 기록하지 않고 기존의 선별된 집계 스냅샷만 보관한다.

Stats는 서버 내부 운영 데이터를 다루므로, 공개 문서에는 기능과 목적을 중심으로 기록하고 실제 데이터베이스 접속 정보나 내부 테이블 구조는 공개하지 않는다. 운영 중에는 다음 항목을 확인하는 것이 좋다.

데이터가 정상적으로 저장되는지
배치 저장 중 오류가 없는지
명령어 정규화와 블록 그룹 집계가 과도하게 누락되지 않는지
통계 수집이 서버 성능에 영향을 주지 않는지
개인정보나 민감한 운영 정보가 외부에 노출되지 않는지

플레이시티 블록에서의 활용

플레이시티 블록은 도시건축 서버이기 때문에 일반 생존 서버보다 건축 활동과 명령어 사용량이 운영 판단에 더 큰 의미를 가진다. Stats는 월드 편집 명령 사용량과 블록 그룹별 작업량 등을 장기적으로 확인할 수 있게 하며, 서버 설정 변경이나 플러그인 업데이트 이후 활동 패턴이 달라졌는지도 비교할 수 있다.

같이 보기

라이선스

현재 프로젝트에는 자체 코드의 이용·수정·재배포 조건을 정한 라이선스가 명시되어 있지 않다. 공개 배포 전에는 프로젝트 라이선스와 번들된 데이터베이스 드라이버의 제3자 고지를 함께 정리해야 한다.