메인 콘텐츠로 건너뛰기
이 문서는 메트릭 수집, 로깅, 디스크 공간 관리, 데이터베이스 유지보수 및 일반적인 문제 해결을 포함하여 StableNet 노드를 운영하기 위한 실무 가이드를 제공합니다.
본 문서에서 다루는 도구와 절차는 노드 안정성을 유지하고 프로덕션 환경에서 발생하는 문제를 진단하는 데 목적이 있습니다. 검증자 노드 운영에 대한 내용은 검증자 작업을 참고하세요. 네트워크 초기 배포 및 구성에 대한 내용은 네트워크 배포을 참고하세요.

​
메트릭 수집

StableNet 노드는 성능 및 운영 상태를 관찰할 수 있도록 다양한 내부 메트릭을 노출합니다.
메트릭 시스템은 go-metrics 라이브러리를 기반으로 구현되어 있으며, 노드의 합의 처리, 트랜잭션 처리, 네트워크 상태 및 데이터베이스 동작에 대한 실시간 지표를 제공합니다. 운영 환경에서는 메트릭 수집을 통해 다음을 확인할 수 있습니다.
  • 블록 생성 및 합의 처리 지연 여부
  • 트랜잭션 풀 적체 상태
  • 피어 연결 안정성
  • 데이터베이스 및 상태 처리 성능
  • 리소스 병목(CPU, 메모리, 디스크 I/O)

​
메트릭 활성화

메트릭 수집은 명령줄 플래그를 통해 제어됩니다.
FlagDescriptionDefault
--metrics메트릭 수집 및 노출 활성화비활성화
--metrics.expensive비용이 큰 메트릭 활성화(운영 환경 비권장)비활성화
--metrics.addr메트릭 HTTP 서버 바인드 주소없음
--metrics.port메트릭 HTTP 서버 포트6060
기본 메트릭 서버 실행 예시: 
gstable --metrics --metrics.addr 0.0.0.0 --metrics.port 6060
메트릭 HTTP 엔드포인트는
http://<addr>:<port>/debug/metrics 경로에서 Prometheus 호환 형식으로 데이터를 노출합니다. 운영 환경에서는 메트릭 서버를 외부에 직접 노출하지 않고, 내부 네트워크 또는 프록시를 통해 접근하는 구성을 권장합니다.

​
InfluxDB 내보내기

메트릭을 장기 저장하거나 시계열 분석을 수행하기 위해 InfluxDB로 메트릭을 내보낼 수 있습니다.
StableNet은 InfluxDB v1과 v2를 모두 지원합니다.

​
InfluxDB v1 구성

FlagDescription
--metrics.influxdbInfluxDB v1 내보내기 활성화
--metrics.influxdb.endpointInfluxDB API 엔드포인트
--metrics.influxdb.database데이터베이스 이름
--metrics.influxdb.username인증 사용자 이름
--metrics.influxdb.password인증 비밀번호
--metrics.influxdb.tags쉼표로 구분된 키/값 태그

​
InfluxDB v2 구성

FlagDescription
--metrics.influxdbv2InfluxDB v2 내보내기 활성화
--metrics.influxdb.token인증 토큰
--metrics.influxdb.bucket버킷 이름
--metrics.influxdb.organization조직 이름
예제: 
# InfluxDB v1
gstable --metrics --metrics.influxdb \
  --metrics.influxdb.endpoint "http://localhost:8086" \
  --metrics.influxdb.database "gstable_metrics" \
  --metrics.influxdb.username "admin" \
  --metrics.influxdb.password "secret" \
  --metrics.influxdb.tags "host=node01,network=mainnet"

# InfluxDB v2
gstable --metrics --metrics.influxdbv2 \
  --metrics.influxdb.endpoint "http://localhost:8086" \
  --metrics.influxdb.token "my-token" \
  --metrics.influxdb.bucket "gstable" \
  --metrics.influxdb.organization "my-org"

​
사용 가능한 메트릭

​
카테고리별 주요 메트릭

CategoryMetric NameTypeDescriptionSource
WBFT Consensusconsensus/wbft/core/commitworkTimer블록 커밋 처리 시간miner/worker.go
Workerminer.newTxsCounter새 트랜잭션 유입 수miner/worker.go
Workerminer.runningBool블록 생성 워커 활성 여부miner/worker.go
Workerminer.syncingBool동기화 중 여부miner/worker.go
ChainBlock insertion rateMeter블록 삽입 처리율core/blockchain.go
ChainReorg depthCounter체인 재구성 깊이core/blockchain.go
TxPoolPending transactionsGauge실행 가능한 트랜잭션 수core/txpool/legacypool
TxPoolQueued transactionsGauge대기 중 트랜잭션 수core/txpool/legacypool
P2PPeer countGauge연결된 피어 수p2p/server.go
P2PIngress / EgressMeter네트워크 트래픽p2p/server.go
StateTrie cache hitsCounter상태 캐시 적중 횟수core/state/statedb.go
StateCommit timeTimer상태 커밋 소요 시간core/state/statedb.go

​
StableNet / Anzeon 특화 메트릭

Anzeon(WBFT) 기반 네트워크에서는 다음과 같은 합의 특화 메트릭을 추가로 확인할 수 있습니다.
  • 거버넌스를 통한 가스 팁 변경 이벤트
  • 에포크 단위 검증자 세트 변경
  • BLS 서명 검증 처리 시간
  • 라운드 변경 및 타임아웃 발생 횟수

​
워커 상태 모니터링

worker 구조체는 블록 생성 및 합의 처리 상태를 나타내는 여러 원자 변수들을 노출합니다.
이는 검증자 노드에서 블록 생성 중단 원인을 분석하는 데 중요합니다.

​
로깅

StableNet은 구조화된 로그 시스템을 사용하며, 로그 레벨을 통해 출력 상세도를 제어할 수 있습니다.

​
로그 레벨

LevelValueDescription
Critical1즉각적인 조치가 필요한 치명적 오류
Error2기능 장애를 유발할 수 있는 오류
Warn3주의가 필요한 상태
Info4일반 운영 정보(기본값)
Debug5디버깅용 상세 로그
Trace6매우 상세한 추적 로그

​
로그 출력 예시

노드 시작 로그: 
INFO Starting Gstable on StableNet
INFO Maximum peer count total=50
INFO Set global gas cap cap=50,000,000
디스크 공간 경고 로그: 
WARN Disk space is running low available=50GiB
ERROR Low disk space. Shutting down to prevent database corruption

​
디스크 공간 관리

StableNet은 디스크 공간 부족으로 인한 데이터베이스 손상을 방지하기 위해 자동 디스크 공간 모니터링 기능을 포함합니다.

​
디스크 공간 임계값

임계값은 다음 중 하나로 결정됩니다.
  • 기본값: 2 * TrieDirtyCache
  • 캐시 설정 기반: 2 * --cache * --cache.gc / 100
  • 명시적 설정: --datadir.minfreedisk

​
동작 방식

  1. 여유 공간 ≥ 2x 임계값: 정상 동작
  2. 1x ~ 2x: 주기적 경고 로그 출력
  3. < 1x: 노드 종료 트리거

​
플랫폼별 구현

PlatformImplementationSystem Call
Linux / Unixcmd/utils/diskusage.gosyscall.Statfs()
Windowscmd/utils/diskusage_windows.goGetDiskFreeSpaceEx()
OpenBSDcmd/utils/diskusage_openbsd.gosyscall.Statfs()

​
데이터베이스 유지보수

​
데이터베이스 백엔드

StableNet은 다음 데이터베이스 백엔드를 지원합니다.
  • LevelDB
  • Pebble

​
압축(Compaction)

  • 자동 압축은 정상 운영 중 백그라운드에서 수행됩니다.
  • 압축 완료 시 로그를 통해 확인할 수 있습니다.
INFO Database compaction finished elapsed=5m30s

​
상태 정리(Pruning)

  • 해시 상태 스키마에서만 오프라인 정리 지원
  • 정리 중 노드 중지 필요
  • 중단 시 다음 실행 시 자동 복구 시도

​
고대 데이터(Freezer)

  • 일정 블록 이후 데이터는 고대 저장소로 이동
  • 읽기 전용, 높은 압축 효율
  • 체인 성장에 따라 지속 증가

​
노드 상태 모니터링

StableNet은 비정상 종료 여부를 추적합니다.
  • 정상 종료 시 클린 마커 기록
  • 비정상 종료 후 재시작 시 경고 로그 출력

​
모니터링 체크리스트

일일
  • 동기화 완료 여부
  • 피어 수 ≥ 10
  • 디스크 여유 공간 확인
주간
  • DB 크기 증가 추세
  • 비정상 종료 발생 여부
월간
  • 로그 정책 점검
  • 고대 데이터 관리
  • 버전 업데이트 검토

​
문제 해결

​
노드 동기화 실패

  • 피어 연결 여부 확인
  • 방화벽 설정 점검
  • 네트워크 ID 및 bootnode 확인

​
높은 메모리 사용량

  • 캐시 설정 점검
  • 아카이브 모드 여부 확인
  • 시스템 OOM 로그 확인

​
느린 블록 처리

  • 디스크 I/O 병목 확인
  • commitwork 메트릭 확인
  • 캐시 설정 및 CPU 코어 수 점검

​
데이터베이스 손상

  • 즉시 노드 중지
  • 백업 복원 또는 재동기화
  • 장기적으로 Pebble 백엔드 고려
이러한 모니터링 및 유지보수 절차를 통해 StableNet 노드를 안정적으로 운영하고 장애 발생 시 신속하게 대응할 수 있습니다.