Geyser gRPC - Best practices

Deze handleiding behandelt essentiële patronen voor het bouwen van robuuste, productieklare applicaties met Geyser gRPC. Solana Stream SDK ondersteunt Geyser gRPC.

Aan de slag

Begin eenvoudig: start met slot-abonnementen om vertrouwd te raken met streaming voordat u complexe filters toevoegt.
Gebruik filters verstandig: abonneer u alleen op wat u nodig heeft om bandbreedte/CPU te verminderen.

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()
}

Verbindingsbeheer

Automatische herverbinding: verwacht netwerkproblemen; maak opnieuw verbinding met exponentiële backoff.
Ping/pong-afhandeling: Yellowstone gRPC-servers sturen een ping. Reageer altijd met pong, anders kan de server de verbinding sluiten (veelvoorkomende oorzaak van verbroken verbindingen na ~30s).

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 recovery: gebruik from_slot na herverbinding om gegevensverlies te voorkomen (duplicaten zijn acceptabel).

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

Architectuurpatronen

Scheid inkomend verkeer en verwerking met channels om netwerk-IO los te koppelen van bedrijfslogica en backpressure toe te voegen.

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

Gebruik bounded channels: kies de capaciteit op basis van verwerkingssnelheid en tolerantie voor gegevensverlies (kleiner = minder geheugen, meer weggevallen updates; groter = meer geheugen, minder weggevallen updates).

Prestaties en veerkracht

Monitor verwerkingslatentie en log wanneer drempelwaarden worden overschreden.
Bundel DB-schrijfacties; flush bij een bepaalde batchgrootte of na een interval.
Gebruik async IO voor externe aanroepen; verplaats zware berekeningen naar worker-taken/threads.
Hergebruik abonnementsverzoeken om allocaties te verminderen.

Foutafhandeling

Onderscheid fouttypen (stream vs verwerking vs channel).
Herstel een ongeldige aanvraag voordat u opnieuw probeert; gebruik pauzebewuste exponentiële backoff alleen wanneer een antwoord om een herhaling vraagt.
Log en meet weggevallen updates om situaties met een trage consument te volgen.

Herstel vóór opnieuw proberen en pauzebewuste backoff

Bewaar de eerste gRPC-fout voordat een herverbindingslus deze vervangt. Leg status en bericht vast, plus aanwezige metadata x-erpc-error-code, x-erpc-error-reason, x-erpc-doc-url, x-erpc-retry-after-seconds en x-erpc-retry-at. Een vroege sluiting kan op een algemene transportfout lijken en bevat mogelijk niet elke trailer.

Herstel een ongeldige aanvraag, afgewezen filtervorm of afwijkende IP-registratie voordat u opnieuw probeert. Wacht bij een ERPC-pauze tot de teruggegeven deadline; die is specifieker dan lokale backoff. Gebruik begrensde exponentiële backoff voor beschikbaarheidsfouten en andere herhaalbare antwoorden. Herhaal een ongewijzigde aanvraag niet alleen omdat die een niet-nulstatus gaf.

Resourcegebruik en verwerkingscapaciteit

Shared-bescherming voorkomt dat één workload aflevercapaciteit verbruikt die andere ERPC-klanten nodig hebben. Een stream kan traag worden door effectieve bandbreedte, CPU, geheugen, de consumentwachtrij, schrijfacties naar de database of externe aanroepen. Resources moeten bij de workload passen; een trage ontvanger wijst niet zelfstandig de beperking aan.

Meet de piekdatasnelheid bij de consument. Zet MB/s met MB/s × 8 om naar Mbps en houd ruimte boven de gemeten piek. Er is geen vaste ongemeten ondergrens. Houd ontvangstwerk kort, geef updates door aan een begrensde wachtrij en schaal het abonnement op of beperk het als de verwerking het niet kan bijhouden. Een begrensde wachtrij beperkt geheugen; zij lost een blijvend trage consument niet op.

Gegevensbeheer

Behandel duplicaten bij gebruik van from_slot (tijdgebonden cache of DB-constraints).
Kies commitment per use case:
- processed: snelste dashboards, kan worden teruggedraaid
- confirmed: goede standaard voor de meeste apps/indexers
- finalized: wanneer absolute zekerheid vereist is

Dynamische abonnementen

Gebruik de bidirectionele stream om abonnementen tijdens runtime bij te werken (hot-swap filters, dekking uitbreiden) zonder opnieuw te verbinden.

Productiechecklist

✅ Automatische herverbinding met exponentiële backoff
✅ Gap recovery met from_slot
✅ Ping/pong-afhandeling (voorkom verbroken verbindingen na 30s)
✅ Gescheiden inkomend verkeer en verwerking met bounded channels/backpressure
✅ Foutlogging en metrics/alerting
✅ Bijhouden van verwerkingslatentie
✅ Duplicaatafhandeling en filteroptimalisatie
✅ Gebundelde schrijfacties (bij opslag van gegevens)
✅ Graceful shutdown en health checks

Aanvullende bronnen

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