Skip to content

README.md

Latest commit

 

History

History
191 lines (138 loc) · 6.07 KB

README.md

File metadata and controls

191 lines (138 loc) · 6.07 KB

Scouter Server (Go)

Scouter APM의 경량 백엔드 서버입니다. 기존 Java 서버를 Go로 재작성하여 메모리·CPU 효율을 대폭 개선하면서 동일한 APM 데이터 수집 기능을 제공합니다. 단일 바이너리로 배포되며, JVM 없이 즉시 실행할 수 있습니다.

Java 대비 효율 비교

항목 Java (Scouter 2.21.2) Go 비고
런타임 메모리 400~800 MB (JVM 힙 + Metaspace) 50~150 MB (GOMEMLIMIT=1GiB) 70~80% 절감
배포 크기 ~34 MB (server/lib/ JAR 전체) + JRE 7.4 MB (단일 바이너리, stripped) JRE 불필요
시작 시간 수 초 (JVM 클래스 로딩) ~50ms 즉시 시작
GC 정지 Stop-the-World (G1GC 수십~수백 ms) 동시 수집 GC (sub-ms STW) 지연 스파이크 감소
XLog 수집 처리량 - ~27 ns/op (단일), ~11 ns/op (병렬) 0~1 alloc/op
디스크 I/O (쓰기) - 768 MB/s (1KB 레코드, 0 alloc/op) buffered + pwrite
인메모리 해시 조회 - 14 ns/op (0 alloc/op) MemHashBlock

메모리 최적화 기법

  • Zero-allocation 직렬화: DataOutputX의 WriteInt16/32/64 등이 buffer 모드에서 heap 할당 없이 동작 (escape analysis 검증 완료)
  • sync.Pool 기반 버퍼 재사용: zstd 디코드 버퍼, XLogPack 직렬화 버퍼 등을 풀링하여 GC 부담 최소화
  • Zero-copy 역직렬화: ReadBlobRef로 내부 버퍼를 복사 없이 참조
  • RWMutex 기반 읽기 최적화: MemHashBlock/MemTimeBlock의 읽기 경로에서 lock 경합 최소화
  • GOMEMLIMIT: 런타임 메모리 상한 1GiB 설정으로 OOM 방지 및 GC 효율 최적화

Features

  • 경량 실행 환경: JVM 불필요, 단일 바이너리 배포, 낮은 메모리 사용량 (Java 서버 대비 ~70% 절감)
  • TCP/UDP 기반 에이전트 데이터 수집 (기본 포트: 6100)
  • XLog, Counter, Profile, Alert, Summary 등 APM 데이터 처리
  • 인메모리 캐시 및 디스크 기반 스토리지
  • REST API 서버 (기본 포트: 6180, 설정으로 활성화)
  • 설정 파일 핫 리로드 지원
  • 일 단위 데이터 보관 및 자동 삭제

Installation

Release 바이너리 (권장)

GitHub Releases에서 플랫폼에 맞는 패키지를 다운로드합니다.

파일 플랫폼
scouter-server-linux-amd64.tar.gz Linux x86_64
scouter-server-linux-arm64.tar.gz Linux ARM64
scouter-server-darwin-amd64.tar.gz macOS x86_64
scouter-server-darwin-arm64.tar.gz macOS ARM64 (Apple Silicon)
scouter-server-windows-amd64.zip Windows x86_64

Linux / macOS

# 다운로드 및 압축 해제 (예: linux-amd64)
tar xzf scouter-server-linux-amd64.tar.gz
cd scouter-server-linux-amd64

# 설정 파일 편집
vi conf/scouter.conf

# 실행
./start.sh

배포 패키지 구조:

scouter-server-linux-amd64/
├── scouter-server          # 실행 바이너리
├── conf/
│   └── scouter.conf        # 설정 파일
├── start.sh                # 시작 스크립트
├── stop.sh                 # 종료 스크립트
└── scouter-server.service  # systemd 유닛 파일 (Linux)

Windows

# 압축 해제 후
cd scouter-server-windows-amd64

# 설정 파일 편집
notepad conf\scouter.conf

# 실행
start.bat

systemd 서비스 등록 (Linux)

# 바이너리를 /opt에 배치
sudo cp -r scouter-server-linux-amd64 /opt/scouter-server

# scouter 사용자 생성
sudo useradd -r -s /sbin/nologin scouter
sudo chown -R scouter:scouter /opt/scouter-server

# 서비스 등록 및 시작
sudo cp /opt/scouter-server/scouter-server.service /etc/systemd/system/
sudo systemctl daemon-reload
sudo systemctl enable scouter-server
sudo systemctl start scouter-server

# 상태 확인
sudo systemctl status scouter-server

소스에서 빌드

Go 1.26+ 필요

git clone https://github.com/scouter-project/scouter-server-go.git
cd scouter-server-go

# 빌드
make build

# 크로스 컴파일 (linux, darwin, windows)
make build-all

# 배포 패키지 생성 (바이너리 + 설정 + 스크립트)
make dist-all

# 테스트
make test

# 전체 명령어 확인
make help

빌드 결과물은 dist/ 디렉토리에 생성됩니다.

Configuration

설정 파일 경로: ./conf/scouter.conf (환경변수 SCOUTER_CONF로 변경 가능)

설정 기본값 설명
net_udp_listen_port 6100 UDP 에이전트 데이터 수신 포트
net_tcp_listen_port 6100 TCP 에이전트/클라이언트 연결 포트
net_http_port 6180 REST API 포트
net_http_enabled false HTTP API 활성화 여부
db_dir ./database 데이터 저장소 경로
db_keep_days 30 데이터 보관 일수
log_dir ./logs 로그 디렉토리

메모리 설정

GOMEMLIMIT 환경변수로 런타임 메모리 상한을 설정합니다. start.sh의 기본값은 1GiB입니다.

export GOMEMLIMIT=2GiB    # 2GB로 변경
./start.sh

Run

# make로 빌드 후 실행
make run

# 또는 직접 실행
./dist/scouter-server

# 버전 확인
./dist/scouter-server version

종료

PID 파일({PID}.scouter)을 삭제하면 서버가 graceful shutdown됩니다.

# start.sh로 실행한 경우
./stop.sh

# 또는 SIGTERM/SIGINT
kill <PID>

Documentation

  • 통신 프로토콜 개요 — 바이너리 직렬화, UDP/TCP 패킷 구조, Pack/Value 타입 체계
  • TCP 에이전트 프로토콜 상세 — 에이전트 연결 수립, 커넥션 풀, Keepalive, RPC 호출 패턴
  • Text Cache Database — 해시 기반 텍스트 저장소, 3계층 캐시 구조, 디스크 파일 포맷, 일별 로테이션
  • XLog Pipeline — XLog 수신/처리/저장/조회 파이프라인, 링 버퍼 실시간 스트리밍, 3중 인덱스, 서비스 그룹 집계

License

Apache-2.0