Geyser gRPC - Praktik Terbaik

Panduan ini membahas pola-pola penting untuk membangun aplikasi yang tangguh dan siap produksi dengan Geyser gRPC. Solana Stream SDK mendukung Geyser gRPC.

Memulai

Mulai dari yang sederhana: gunakan subscription slot terlebih dahulu untuk mengenal streaming sebelum menambahkan filter yang kompleks.
Gunakan filter dengan bijak: subscribe hanya ke data yang Anda butuhkan untuk mengurangi bandwidth/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()
}

Manajemen koneksi

Reconnect otomatis: masalah jaringan pasti terjadi; sambungkan ulang dengan exponential backoff.
Penanganan ping/pong: server Yellowstone gRPC mengirim ping. Selalu balas dengan pong, atau server dapat menutup koneksi (penyebab umum terputusnya koneksi setelah ~30 detik).

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?;
}

Pemulihan gap: gunakan from_slot setelah tersambung ulang untuk menghindari kehilangan data (duplikat dapat diterima).

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
};

Pola arsitektur

Pisahkan ingress dan pemrosesan dengan channel untuk memisahkan IO jaringan dari logika bisnis dan menambahkan 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

Gunakan bounded channel: pilih kapasitas berdasarkan kecepatan pemrosesan dan toleransi kehilangan data (lebih kecil = memori lebih sedikit, lebih banyak drop; lebih besar = memori lebih banyak, lebih sedikit drop).

Performa dan ketahanan

Pantau latensi pemrosesan dan catat log saat ambang batas terlampaui.
Lakukan penulisan DB secara batch; flush berdasarkan ukuran batch atau interval.
Gunakan async IO untuk panggilan eksternal; alihkan komputasi berat ke task/thread worker.
Gunakan ulang request subscription untuk mengurangi alokasi.

Penanganan error

Bedakan jenis error (stream vs pemrosesan vs channel).
Perbaiki request yang tidak valid sebelum mencobanya lagi; gunakan exponential backoff yang memperhitungkan jeda hanya ketika respons meminta retry.
Catat log/metrik update yang di-drop untuk memantau kondisi consumer yang lambat.

Perbaiki sebelum retry dan backoff yang memperhitungkan jeda

Simpan error gRPC pertama sebelum loop reconnect menggantikannya. Catat status dan pesannya, serta metadata x-erpc-error-code, x-erpc-error-reason, x-erpc-doc-url, x-erpc-retry-after-seconds, dan x-erpc-retry-at yang ada. Koneksi yang ditutup lebih awal dapat terlihat seperti transport error biasa, sehingga mungkin tidak menyertakan setiap trailer.

Perbaiki request yang tidak valid, bentuk filter yang ditolak, atau ketidakcocokan registrasi IP sebelum mencoba lagi. Untuk jeda (pause) ERPC, tunggu hingga batas waktu yang dikembalikan; batas itu lebih spesifik daripada backoff lokal. Gunakan exponential backoff yang dibatasi untuk kegagalan ketersediaan dan respons lain yang dapat di-retry. Jangan berulang kali me-retry request yang tidak diubah hanya karena request itu mengembalikan status bukan nol.

Penggunaan resource dan kapasitas pemrosesan

Perlindungan Shared mencegah satu workload menghabiskan kapasitas pengiriman yang dibutuhkan pelanggan ERPC lain. Stream dapat melambat karena bandwidth efektif, CPU, memori, antrean consumer, penulisan database, atau panggilan eksternal. Resource harus cukup untuk workload tersebut; receiver yang lambat tidak dengan sendirinya menunjukkan bagian mana yang terbatas.

Ukur laju data puncak di sisi consumer. Ubah MB/s ke Mbps dengan MB/s × 8, lalu sisakan headroom di atas puncak yang terukur. Tidak ada angka minimum tetap tanpa pengukuran. Jaga pekerjaan penerimaan tetap singkat, serahkan update ke bounded queue, lalu scale atau kurangi subscription jika pemrosesan tidak dapat mengimbangi. Bounded queue membatasi penggunaan memori, tetapi tidak dapat mengatasi consumer yang terus-menerus lambat.

Manajemen data

Tangani duplikat saat menggunakan from_slot (cache dengan batas waktu atau constraint DB).
Pilih commitment sesuai kasus penggunaan:
- processed: dashboard tercepat, dapat di-rollback
- confirmed: default yang baik untuk sebagian besar aplikasi/indexer
- finalized: ketika kepastian mutlak diperlukan

Subscription dinamis

Gunakan stream dua arah untuk memperbarui subscription saat runtime (hot-swap filter, memperluas cakupan) tanpa reconnect.

Checklist produksi

✅ Reconnect otomatis dengan exponential backoff
✅ Pemulihan gap dengan from_slot
✅ Penanganan ping/pong (hindari terputus setelah 30 detik)
✅ Ingress dan pemrosesan dipisahkan dengan bounded channel/backpressure
✅ Logging error dan metrik/alerting
✅ Pemantauan latensi pemrosesan
✅ Penanganan duplikat dan optimasi filter
✅ Penulisan batch (jika menyimpan data)
✅ Graceful shutdown dan health check

Sumber daya tambahan

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