Geyser gRPC - 모범 사례

이 가이드는 Geyser gRPC로 견고한 프로덕션용 애플리케이션을 구축하기 위한 핵심 패턴을 다룹니다. Solana Stream SDK는 Geyser gRPC를 지원합니다.

시작하기

단순하게 시작하기: 복잡한 필터를 추가하기 전에 slot 구독부터 시작해 스트리밍에 익숙해지세요.
필터를 현명하게 사용하기: 대역폭/CPU를 줄이려면 필요한 데이터만 구독하세요.

rust

SubscribeRequestFilterTransactions {
    vote: Some(false),   // Exclude vote txs
    failed: Some(false), // Exclude failed txs
    ..Default::default()
}

SubscribeRequestFilterTransactions {
    vote: Some(false),   // Exclude vote txs
    failed: Some(false), // Exclude failed txs
    ..Default::default()
}

연결 관리

자동 재연결: 네트워크 문제는 일어난다고 가정하고, exponential backoff로 재연결하세요.
Ping/pong 처리: Yellowstone gRPC 서버는 ping을 보냅니다. 항상 pong으로 응답하세요. 그렇지 않으면 서버가 연결을 닫을 수 있습니다(약 30초 만에 연결이 끊기는 흔한 원인).

rust

if matches!(update.update_oneof, Some(UpdateOneof::Ping(_))) {
    subscribe_tx.send(SubscribeRequest {
        ping: Some(SubscribeRequestPing { id: 1 }),
        ..Default::default()
    }).await?;
}

if matches!(update.update_oneof, Some(UpdateOneof::Ping(_))) {
    subscribe_tx.send(SubscribeRequest {
        ping: Some(SubscribeRequestPing { id: 1 }),
        ..Default::default()
    }).await?;
}

Gap 복구: 재연결 후 from_slot을 사용해 데이터 손실을 방지하세요(중복은 허용됩니다).

rust

subscribe_request.from_slot = if tracked_slot > 0 {
    Some(tracked_slot) // Optionally subtract a small buffer to dodge reorgs
} else {
    None
};

subscribe_request.from_slot = if tracked_slot > 0 {
    Some(tracked_slot) // Optionally subtract a small buffer to dodge reorgs
} else {
    None
};

아키텍처 패턴

채널로 수신(ingress)과 처리를 분리해 네트워크 IO를 비즈니스 로직에서 떼어 내고 backpressure를 추가하세요.

rust

let (tx, rx) = mpsc::channel::<SubscribeUpdate>(10_000);
// ingress task reads stream and tx.send(...)
// processing task consumes rx and does business logic

let (tx, rx) = mpsc::channel::<SubscribeUpdate>(10_000);
// ingress task reads stream and tx.send(...)
// processing task consumes rx and does business logic

bounded 채널 사용: 처리 속도와 데이터 손실 허용 범위에 따라 용량을 정하세요(작을수록 메모리는 적게 쓰지만 드롭이 늘고, 클수록 메모리는 많이 쓰지만 드롭이 줄어듭니다).

성능과 복원력

처리 지연 시간을 모니터링하고 임계값을 넘으면 로그를 남기세요.
DB 쓰기는 배치로 묶고, 배치 크기나 시간 간격에 따라 flush하세요.
외부 호출에는 async IO를 사용하고, 무거운 연산은 worker 태스크/스레드로 넘기세요.
구독 요청을 재사용해 할당을 줄이세요.

오류 처리

오류 유형(스트림 대 처리 대 채널)을 구분하세요.
잘못된 요청은 재시도하기 전에 수정하고, 응답이 재시도를 요구할 때만 일시 정지를 고려한 exponential backoff를 사용하세요.
드롭된 업데이트를 로그/메트릭으로 기록해 느린 컨슈머 상태를 추적하세요.

재시도 전 수정과 일시 정지를 고려한 backoff

재연결 루프가 덮어쓰기 전에 첫 번째 gRPC 오류를 보존하세요. 그 오류의 status와 message, 그리고 존재하는 x-erpc-error-code, x-erpc-error-reason, x-erpc-doc-url, x-erpc-retry-after-seconds, x-erpc-retry-at metadata를 기록하세요. 연결이 일찍 닫히면 일반적인 transport 오류처럼 보일 수 있으므로 모든 trailer가 포함되지 않을 수 있습니다.

잘못된 요청, 거부된 필터 형태, IP 등록 불일치는 재시도하기 전에 수정하세요. ERPC 일시 정지가 반환되면 반환된 기한까지 기다리세요. 이 기한은 로컬 backoff보다 구체적입니다. 가용성 실패와 그 밖의 재시도 가능한 응답에는 상한이 있는 exponential backoff를 사용하세요. 0이 아닌 status가 반환되었다는 이유만으로 바꾸지 않은 요청을 반복해서 재시도하지 마세요.

리소스 사용과 처리 용량

Shared 보호 장치는 하나의 워크로드가 다른 ERPC 고객에게 필요한 전송 용량을 소비하지 않도록 합니다. 스트림은 실효 대역폭, CPU, 메모리, 컨슈머 큐, 데이터베이스 쓰기, 외부 호출 때문에 느려질 수 있습니다. 리소스는 워크로드에 맞게 충분해야 하며, 수신 측이 느리다는 사실만으로는 어느 부분이 병목인지 알 수 없습니다.

컨슈머에서 최대 데이터 전송률을 측정하세요. MB/s × 8로 MB/s를 Mbps로 변환한 뒤, 측정한 최댓값보다 여유를 두세요. 측정 없이 정할 수 있는 고정 최솟값은 없습니다. 수신 작업은 짧게 유지하고, 업데이트는 bounded 큐에 넘기며, 처리가 따라가지 못하면 처리를 확장하거나 구독을 줄이세요. bounded 큐는 메모리 사용량을 제한할 뿐, 계속 느린 컨슈머 문제를 해결하지는 못합니다.

데이터 관리

from_slot을 사용할 때는 중복을 처리하세요(시간 제한이 있는 캐시 또는 DB 제약 조건).
사용 사례에 맞게 commitment를 선택하세요:
- processed: 가장 빠른 대시보드용이며, 롤백될 수 있습니다
- confirmed: 대부분의 앱/인덱서에 적합한 기본값
- finalized: 절대적인 확실성이 필요할 때

동적 구독

양방향 스트림을 사용하면 재연결 없이 런타임에 구독을 업데이트할 수 있습니다(필터 hot-swap, 대상 범위 확대).

프로덕션 체크리스트

✅ exponential backoff를 사용한 자동 재연결
✅ from_slot을 사용한 gap 복구
✅ Ping/pong 처리(30초 연결 끊김 방지)
✅ bounded 채널/backpressure로 수신과 처리 분리
✅ 오류 로깅과 메트릭/알림
✅ 처리 지연 시간 추적
✅ 중복 처리와 필터 최적화
✅ 배치 쓰기(데이터를 저장하는 경우)
✅ 정상 종료(graceful shutdown)와 헬스 체크

추가 리소스

Solana Stream SDK(Geyser gRPC 지원): https://github.com/ValidatorsDAO/solana-stream