> ## Documentation Index
> Fetch the complete documentation index at: https://docs.stablenet.network/llms.txt
> Use this file to discover all available pages before exploring further.

# 노드 모니터링 및 유지보수

이 문서는 메트릭 수집, 로깅, 디스크 공간 관리, 데이터베이스 유지보수 및 일반적인 문제 해결을 포함하여 StableNet 노드를 운영하기 위한 실무 가이드를 제공합니다.\
본 문서에서 다루는 도구와 절차는 노드 안정성을 유지하고 프로덕션 환경에서 발생하는 문제를 진단하는 데 목적이 있습니다.

검증자 노드 운영에 대한 내용은 [검증자 작업](/ko/operations-guide/11.2-validator-operations)을 참고하세요.

네트워크 초기 배포 및 구성에 대한 내용은 [네트워크 배포](/ko/operations-guide/11.1-network-deployment)을 참고하세요.

## 메트릭 수집

StableNet 노드는 성능 및 운영 상태를 관찰할 수 있도록 다양한 내부 메트릭을 노출합니다.\
메트릭 시스템은 `go-metrics` 라이브러리를 기반으로 구현되어 있으며, 노드의 합의 처리, 트랜잭션 처리, 네트워크 상태 및 데이터베이스 동작에 대한 실시간 지표를 제공합니다.

운영 환경에서는 메트릭 수집을 통해 다음을 확인할 수 있습니다.

* 블록 생성 및 합의 처리 지연 여부
* 트랜잭션 풀 적체 상태
* 피어 연결 안정성
* 데이터베이스 및 상태 처리 성능
* 리소스 병목(CPU, 메모리, 디스크 I/O)

### 메트릭 활성화

메트릭 수집은 명령줄 플래그를 통해 제어됩니다.

| Flag                  | Description              | Default |
| --------------------- | ------------------------ | ------- |
| `--metrics`           | 메트릭 수집 및 노출 활성화          | 비활성화    |
| `--metrics.expensive` | 비용이 큰 메트릭 활성화(운영 환경 비권장) | 비활성화    |
| `--metrics.addr`      | 메트릭 HTTP 서버 바인드 주소       | 없음      |
| `--metrics.port`      | 메트릭 HTTP 서버 포트           | 6060    |

**기본 메트릭 서버 실행 예시:**

```bash theme={null}
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 구성

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

#### InfluxDB v2 구성

| Flag                              | Description          |
| --------------------------------- | -------------------- |
| `--metrics.influxdbv2`            | InfluxDB v2 내보내기 활성화 |
| `--metrics.influxdb.token`        | 인증 토큰                |
| `--metrics.influxdb.bucket`       | 버킷 이름                |
| `--metrics.influxdb.organization` | 조직 이름                |

**예제:**

```bash theme={null}
# 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"
```

### 사용 가능한 메트릭

#### 카테고리별 주요 메트릭

| Category       | Metric Name                      | Type    | Description    | Source                 |
| -------------- | -------------------------------- | ------- | -------------- | ---------------------- |
| WBFT Consensus | `consensus/wbft/core/commitwork` | Timer   | 블록 커밋 처리 시간    | miner/worker.go        |
| Worker         | `miner.newTxs`                   | Counter | 새 트랜잭션 유입 수    | miner/worker.go        |
| Worker         | `miner.running`                  | Bool    | 블록 생성 워커 활성 여부 | miner/worker.go        |
| Worker         | `miner.syncing`                  | Bool    | 동기화 중 여부       | miner/worker.go        |
| Chain          | Block insertion rate             | Meter   | 블록 삽입 처리율      | core/blockchain.go     |
| Chain          | Reorg depth                      | Counter | 체인 재구성 깊이      | core/blockchain.go     |
| TxPool         | Pending transactions             | Gauge   | 실행 가능한 트랜잭션 수  | core/txpool/legacypool |
| TxPool         | Queued transactions              | Gauge   | 대기 중 트랜잭션 수    | core/txpool/legacypool |
| P2P            | Peer count                       | Gauge   | 연결된 피어 수       | p2p/server.go          |
| P2P            | Ingress / Egress                 | Meter   | 네트워크 트래픽       | p2p/server.go          |
| State          | Trie cache hits                  | Counter | 상태 캐시 적중 횟수    | core/state/statedb.go  |
| State          | Commit time                      | Timer   | 상태 커밋 소요 시간    | core/state/statedb.go  |

#### StableNet / Anzeon 특화 메트릭

Anzeon(WBFT) 기반 네트워크에서는 다음과 같은 합의 특화 메트릭을 추가로 확인할 수 있습니다.

* 거버넌스를 통한 가스 팁 변경 이벤트
* 에포크 단위 검증자 세트 변경
* BLS 서명 검증 처리 시간
* 라운드 변경 및 타임아웃 발생 횟수

#### 워커 상태 모니터링

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

## 로깅

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

### 로그 레벨

| Level    | Value | Description         |
| -------- | ----- | ------------------- |
| Critical | 1     | 즉각적인 조치가 필요한 치명적 오류 |
| Error    | 2     | 기능 장애를 유발할 수 있는 오류  |
| Warn     | 3     | 주의가 필요한 상태          |
| Info     | 4     | 일반 운영 정보(기본값)       |
| Debug    | 5     | 디버깅용 상세 로그          |
| Trace    | 6     | 매우 상세한 추적 로그        |

### 로그 출력 예시

**노드 시작 로그:**

```text theme={null}
INFO Starting Gstable on StableNet
INFO Maximum peer count total=50
INFO Set global gas cap cap=50,000,000
```

**디스크 공간 경고 로그:**

```text theme={null}
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: 노드 종료 트리거

### 플랫폼별 구현

| Platform     | Implementation                   | System Call            |
| ------------ | -------------------------------- | ---------------------- |
| Linux / Unix | `cmd/utils/diskusage.go`         | `syscall.Statfs()`     |
| Windows      | `cmd/utils/diskusage_windows.go` | `GetDiskFreeSpaceEx()` |
| OpenBSD      | `cmd/utils/diskusage_openbsd.go` | `syscall.Statfs()`     |

## 데이터베이스 유지보수

### 데이터베이스 백엔드

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

* LevelDB
* Pebble

### 압축(Compaction)

* 자동 압축은 정상 운영 중 백그라운드에서 수행됩니다.
* 압축 완료 시 로그를 통해 확인할 수 있습니다.

```text theme={null}
INFO Database compaction finished elapsed=5m30s
```

### 상태 정리(Pruning)

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

### 고대 데이터(Freezer)

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

## 노드 상태 모니터링

StableNet은 비정상 종료 여부를 추적합니다.

* 정상 종료 시 클린 마커 기록
* 비정상 종료 후 재시작 시 경고 로그 출력

### 모니터링 체크리스트

**일일**

* 동기화 완료 여부
* 피어 수 ≥ 10
* 디스크 여유 공간 확인

**주간**

* DB 크기 증가 추세
* 비정상 종료 발생 여부

**월간**

* 로그 정책 점검
* 고대 데이터 관리
* 버전 업데이트 검토

## 문제 해결

### 노드 동기화 실패

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

### 높은 메모리 사용량

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

### 느린 블록 처리

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

### 데이터베이스 손상

* 즉시 노드 중지
* 백업 복원 또는 재동기화
* 장기적으로 Pebble 백엔드 고려

이러한 모니터링 및 유지보수 절차를 통해 StableNet 노드를 안정적으로 운영하고 장애 발생 시 신속하게 대응할 수 있습니다.