Een Discord-bot online houden bij crashes en deploys
Door Arthur De WitteGepubliceerd Bijgewerkt 14 min lezen
Op deze pagina
- Waarom sharding alleen niet volstaat
- Hoe sharding werkt
- Drie manieren om de shards te draaien
- De architectuur: een dunne gateway, een stream en workers
- Hoe dit er in productie uitziet
- De gateway op Kubernetes
- De bot op Docker Swarm
- De streams en consumers opzetten
- Wanneer er iets faalt
- Waar je op let
- Test hoe je leest
- Dit op A-Line.cloud
- Veelgestelde vragen
- Wat je als eerste verandert
Je bot werkt prima, tot je deployt. Slash-commando’s reageren een minuut lang niet, een paar berichten worden nooit gemodereerd, en iemand vraagt in het supportkanaal of de bot plat ligt. De meeste uitleg over het schalen van Discord-bots stopt bij sharding. Sharding verdeelt de last, maar houdt op zich niets online. Deze handleiding behandelt de andere delen: een gateway die events alleen doorgeeft, een duurzame wachtrij die ze bijhoudt, en workers die mogen crashen of herstarten zonder dat er iets verloren gaat.
Waarom sharding alleen niet volstaat
Discord verplicht sharding zodra een bot in 2.500 servers zit, die de API van Discord guilds noemt. Elke shard is een aparte verbinding met de gateway van Discord, en elke verbinding mag 120 events per 60 seconden sturen (Discord-documentatie). Sharding gaat dus over binnen de limieten van Discord blijven, en daar is het goed in.
Wat het niet doet, is de bot laten werken terwijl een proces herstart. Als de code die een event ontvangt ook de code is die het afhandelt, verliest elke deploy en elke crash alles wat tijdens de herstart binnenkomt. Een bot die online blijft, heeft drie dingen nodig die samenwerken: shards om de verbindingen te verdelen, een orchestrator om te herstarten wat faalt, en een duurzame wachtrij, zodat geen enkel event afhangt van één proces dat toevallig draait.
Hoe sharding werkt
Discord bepaalt met één formule welke shard de events van een guild krijgt (Discord-documentatie):
shard_id = (guild_id >> 22) % shard_count
Elke guild-ID bevat in de hoogste bits een tijdstempel. Door hem 22 bits naar rechts te schuiven en de rest te nemen, worden guilds gelijkmatig verdeeld, met hoogstens zo’n 2.500 per shard. Elke shard heeft zijn eigen WebSocket, zijn eigen heartbeat, zijn eigen sessie-ID en zijn eigen volgnummer. Eén shard kan dus wegvallen en opnieuw verbinden terwijl de andere gewoon doorwerken.
Je hoeft het aantal shards niet te raden. Het endpoint /gateway/bot geeft een aanbevolen aantal shards terug, samen met max_concurrency: hoeveel shards tegelijk mogen identificeren. Voor bijna elke bot is dat 1, wat neerkomt op één nieuwe verbinding per 5 seconden. Alleen bots in meer dan 250.000 guilds krijgen een hogere waarde.
Die 5 seconden tussenruimte spelen later nog een rol. Tien shards van nul opstarten duurt bijna een minuut, dus het deel van je bot dat deze verbindingen vasthoudt, herstart je beter zo zelden mogelijk.
Drie manieren om de shards te draaien
Libraries bieden drie manieren om shards over processen te verdelen. Ze verschillen in geheugen, in hoeveel er tegelijk kan uitvallen, en in hoe snel ze herstellen.
| Strategie | Hoe het draait | Complexiteit | Als één deel faalt |
|---|---|---|---|
| Intern | Eén proces houdt elke verbinding vast | Laag | Alles staat stil tot het herstart |
| Extern | Eén proces per shard | Gemiddeld | Eén shard valt weg, de rest werkt door |
| Hybride | Meerdere shards per proces, meerdere processen | Gemiddeld | Alleen de shards in dat proces vallen weg |
- Intern200 MB
- Hybride400 MB
- Extern800 MB
Toon de cijfers als tabel
| Strategie | Geheugen (ongeveer) |
|---|---|
| Intern | 200 MB |
| Hybride | 400 MB |
| Extern | 800 MB |
Interne sharding gebruikt het minste geheugen, maar de hele bot is één proces: één crash legt elke shard plat. Externe sharding isoleert fouten, maar laadt je code en caches één keer per shard. Hybride zit daartussen, en voor de meeste bots boven een paar duizend guilds is dat de verstandige keuze. Het project discord-hybrid-sharding meldt een daling van ongeveer 4 GB naar ongeveer 700 MB na de overstap, en is gebruikt met tot 600.000 guilds.
De architectuur: een dunne gateway, een stream en workers
De vorm die een bot beschikbaar houdt, heeft drie lagen, en elke laag heeft één taak.
De gateway houdt de verbindingen met Discord vast. Hij ontvangt events en publiceert ze één voor één naar de stream. Er zit geen bedrijfslogica in: geen databasecalls, geen moderatieregels, geen beeldverwerking. Omdat identificeren gelimiteerd is, is de gateway het traagste deel om te herstarten. Je wilt dus dat hij zelden verandert en nooit crasht. Weinig code betekent weinig dat fout kan gaan.
De stream zit in het midden. NATS JetStream bewaart elk event op schijf tot een worker bevestigt dat hij het heeft afgehandeld. Luistert er geen worker, dan wachten de events.
De workers doen het eigenlijke werk. Ze houden tussen events geen eigen toestand bij, dus je kunt er zoveel draaien als je nodig hebt, ze in elke volgorde herstarten en ze zo vaak deployen als je wilt.
Druk op de knop om de worker te herstarten terwijl er events blijven binnenkomen.
Waarom JetStream
De stream moet berichten bewaren als niemand luistert, en dat sluit de snelste opties uit. NATS Core en Redis Pub/Sub zijn fire-and-forget: een bericht dat binnenkomt terwijl er geen worker verbonden is, is weg. Van de brokers die berichten wel bewaren, heeft JetStream in een benchmark uit 2025 de laagste latency.
Bewaart berichten als er geen worker luistert
- JetStream3 ms
- RabbitMQ12,5 ms
- Kafka30 ms
Laat ze vallen
- NATS Core0,3 ms
- Redis Pub/Sub1,25 ms
Toon de cijfers als tabel
| Broker | Latency | Doorvoer |
|---|---|---|
| JetStream | 3 ms | zo'n 300.000 ber./s |
| RabbitMQ | 12,5 ms | zo'n 75.000 ber./s |
| Kafka | 30 ms | zo'n 750.000 ber./s |
| NATS Core | 0,3 ms | zo'n 11.000.000 ber./s |
| Redis Pub/Sub | 1,25 ms | zo'n 500.000 ber./s |
Kafka verwerkt meer berichten per seconde, maar geen enkele Discord-bot komt in de buurt van het plafond van JetStream, en Kafka brengt partities, rebalancing van consumer groups en een KRaft-quorum mee om te beheren. JetStream is één kleine binary die een bot met een handvol shards naast al de rest kan draaien.
Hoe dit er in productie uitziet
Hylist.io, een serverlijst die ik run, gebruikt deze opzet. De bot is geschreven in Rust op Tokio en draait als 2 replica’s met samen 4 shards op Docker Swarm. JetStream draagt 10 streams die meer dan 11 soorten workers voeden, op subjects zoals votes.cast, servers.check en tasks.media.
Een paar details die er echt toe deden:
- Shards worden geclaimd via Postgres. Elke replica schrijft elke 10 seconden een heartbeat naar een tabel
discord_bot_shards. Een rij zonder heartbeat in 30 seconden, drie gemiste slagen, mag geclaimd worden.pg_try_advisory_xact_lockzorgt dat twee replica’s nooit dezelfde shard claimen, en bij het afsluiten geeftrelease_all_shards()ze meteen vrij, in plaats van de 30 seconden af te wachten. - Werk is opgesplitst per soort. De stream TASKS heeft
tasks.process,tasks.mediaentasks.dead, met aparte consumers voor CPU-zwaar en I/O-zwaar werk. Een stapel videotranscodes houdt zo nooit een stem op. De stream SERVERS heeft 10 consumer-replica’s, omdat servers controleren zowel vaak gebeurt als tijdgevoelig is. - Elke worker heeft een healthpoort, van 9001 tot 9011, en Swarm controleert die elke 10 seconden.
- Loggen blokkeert nooit. Fouten gaan naar Sentry met een samplerate van 20%, en logs lopen via
tracingvan Rust met een niet-blokkerende writer. Een logcall die blokkeert, zou de async-runtime waarop hij draait stilleggen.
De gateway op Kubernetes
Op Kubernetes past de gateway in een StatefulSet. Die pods krijgen vaste namen, discord-shard-0, discord-shard-1 enzovoort, en dat nummer kan dienen als shard-ID.
apiVersion: apps/v1
kind: StatefulSet
metadata:
name: discord-shard
namespace: discord-bot
spec:
serviceName: discord-shard
replicas: 3
selector:
matchLabels:
app: discord-shard
template:
metadata:
labels:
app: discord-shard
spec:
terminationGracePeriodSeconds: 30
containers:
- name: shard
image: registry.example.com/discord-bot:1.4.2
env:
- name: SHARD_ID
valueFrom:
fieldRef:
fieldPath: metadata.labels['apps.kubernetes.io/pod-index']
- name: SHARD_COUNT
value: "3"
- name: NATS_URL
value: nats://nats.discord-bot.svc.cluster.local:4222
- name: DISCORD_TOKEN
valueFrom:
secretKeyRef:
name: discord-secrets
key: bot-token
ports:
- name: health
containerPort: 8080
readinessProbe:
httpGet: { path: /health/ready, port: health }
initialDelaySeconds: 10
periodSeconds: 5
failureThreshold: 3
livenessProbe:
httpGet: { path: /health/live, port: health }
initialDelaySeconds: 30
periodSeconds: 10
failureThreshold: 5
resources:
requests: { memory: 256Mi, cpu: 250m }
limits: { memory: 512Mi }
De delen die het werk doen:
apps.kubernetes.io/pod-indexis een label dat Kubernetes sinds versie 1.28 op elke pod van een StatefulSet zet. Lees je het in alsSHARD_ID, dan hoeft geen enkele pod zijn eigen nummer uit te zoeken.- Pods starten één voor één. Een StatefulSet wacht tot elke pod klaar is voor hij de volgende start. Antwoordt
/health/readypas zodra de shard geïdentificeerd is, dan krijg je de 5 seconden tussenruimte die Discord vraagt vanzelf. - Updates gaan ook één pod tegelijk, het hoogste nummer eerst. De shard die herstart, hervat zijn sessie terwijl de andere twee doordraaien.
terminationGracePeriodSecondsmoet langer zijn dan je afsluiten duurt. Meer daarover bij wanneer er iets faalt.
Het aantal shards veranderen
SHARD_COUNT zit in de formule. Pas je het aan, dan verhuizen guilds naar andere shards, en moet elke shard opnieuw verbinden met het nieuwe aantal. Tools zoals Marver en Kubecord helpen dat te coördineren.
Laat dat niet over aan een autoscaler. Tien nieuwe shards kosten bijna een minuut aan identificeren, en in die tijd krijgen sommige guilds helemaal geen events. Bekijk het aanbevolen aantal van /gateway/bot één keer per week en pas het met de hand aan, op een rustig uur. Workers zijn anders: die schaal je zo vaak als je wilt, want ze houden geen verbinding met Discord vast.
De bot op Docker Swarm
Swarm heeft geen StatefulSets, dus shards hebben een andere manier nodig om te beslissen wie wat bezit: advisory locks in Postgres zoals bij Hylist.io, een key-valuebucket in NATS, of een lease in Redis. In ruil krijg je een veel kleiner systeem om te beheren. Mirantis heeft beloofd Swarm tot 2030 te ondersteunen (The Decipherist). Als ruwe grens: onder 20 shards is Swarm ruim genoeg, boven 50 is Kubernetes zijn extra werk waard.
# docker-compose.swarm.yml
services:
discord-bot:
image: registry.example.com/discord-bot:1.4.2
environment:
NATS_URL: nats://nats:4222
DATABASE_URL: postgres://bot:${PG_PASSWORD}@postgres:5432/bot
secrets: [discord_token]
stop_grace_period: 30s
healthcheck:
test: ["CMD", "curl", "-f", "http://localhost:9001/health"]
interval: 10s
timeout: 5s
retries: 3
deploy:
replicas: 2
update_config:
parallelism: 1
delay: 30s
order: stop-first
restart_policy:
condition: on-failure
delay: 5s
max_attempts: 3
networks: [bot-internal]
nats:
image: nats:2.11
command: ["--jetstream", "--store_dir", "/data"]
volumes: [nats-data:/data]
deploy:
resources:
limits: { memory: 128M }
networks: [bot-internal]
postgres:
image: postgres:16-alpine
environment:
POSTGRES_USER: bot
POSTGRES_PASSWORD: ${PG_PASSWORD}
volumes: [pg-data:/var/lib/postgresql/data]
deploy:
placement:
constraints: [node.labels.db == true]
networks: [bot-internal]
networks:
bot-internal:
driver: overlay
volumes:
nats-data:
pg-data:
secrets:
discord_token:
external: true
Een paar keuzes die uitleg verdienen:
delay: 30smetparallelism: 1geeft elke replica de tijd om zijn shards te claimen en te hervatten voor de volgende neergaat.order: stop-firststopt de oude replica voor de nieuwe start, zodat twee replica’s nooit dezelfde shard vasthouden.- Vaste versies.
nats:2.11enpostgres:16-alpinein plaats vanlatest, zodat een nieuwe deploy je wachtrij nooit onverwacht upgradet. - Postgres staat vast op één node. Een Swarm-volume leeft op de node die het aanmaakte, dus een database die naar een andere node verhuist, begint leeg.
- Het wachtwoord komt uit de omgeving en het Discord-token uit een Swarm-secret, zodat geen van beide in het bestand belandt.
NATS zelf is licht: de image is kleiner dan 10 MB, en hij draait op minimaal 1 vCPU en 32 MiB geheugen (NATS-documentatie).
De streams en consumers opzetten
Met de opdrachtregeltool nats maak je één stream voor alle Discord-events:
nats stream add DISCORD_EVENTS \
--subjects "discord.events.>" \
--storage file \
--retention limits \
--max-msgs=-1 \
--max-bytes 1GB \
--max-age 24h \
--discard old \
--replicas 1
--replicas 1 is prima op één server. Op een cluster van drie NATS-servers gebruik je 3, zodat de stream het verlies van één ervan overleeft. --max-age 24h en --max-bytes 1GB leggen een plafond op hoeveel er kan opstapelen als alle workers lang plat liggen.
Elke soort werk krijgt dan een eigen consumer, die bijhoudt wat hij al heeft afgehandeld:
nats consumer add DISCORD_EVENTS moderation-worker \
--filter "discord.events.message_create" \
--deliver all \
--ack explicit \
--max-deliver 3 \
--wait 30s \
--pull \
--max-pending 100
nats consumer add DISCORD_EVENTS voice-tracker \
--filter "discord.events.voice_state_update" \
--deliver all \
--ack explicit \
--max-deliver 5 \
--wait 10s \
--pull \
--max-pending 50
De ack-wachttijd (--wait) is de instelling om over na te denken. Zo lang wacht JetStream op een bevestiging van een worker voor hij het bericht aan een andere geeft. Te kort, en trage handlers krijgen dubbels terwijl ze nog bezig zijn. Te lang, en de berichten van een gecrashte worker blijven al die tijd liggen. Begin net boven de traagste normale run van je handler.
Wanneer er iets faalt
Herstel gebeurt in twee lagen, en elke laag dekt een ander soort fout.
De verbinding met Discord. Verliest een shard zijn verbinding, dan verbindt hij opnieuw en stuurt RESUME met zijn sessie-ID en het laatste volgnummer dat hij zag. Discord speelt de gemiste events opnieuw af. Is de sessie verlopen, dan valt de shard terug op een nieuwe IDENTIFY. Discord documenteert niet precies hoe lang een sessie hervatbaar blijft. Ga er dus van uit dat je bij een onderbreking van meer dan een paar seconden events kunt verliezen, en synchroniseer opnieuw waar je bot op steunt.
Het werk zelf. Een worker die halverwege een taak crasht, bevestigt zijn bericht nooit, dus JetStream levert het opnieuw af zodra de ack-wachttijd verstreken is. Een duurzame consumer gaat na een herstart verder bij het eerste onbevestigde bericht. --max-deliver voorkomt dat een bericht dat de worker telkens laat crashen, eindeloos rondgaat.
Rond beide doet de orchestrator zijn deel: probes in Kubernetes of healthchecks in Swarm herstarten wat niet meer antwoordt.
Netjes afsluiten
De meeste verloren events vallen tijdens deploys, niet bij crashes. Stuurt de orchestrator SIGTERM, stop dan eerst met events van Discord aannemen, en drain daarna NATS, zodat alles wat al binnen is gepubliceerd wordt en alles wat in behandeling is afgewerkt raakt. Doe je het omgekeerd, dan hebben events die tussen de twee stappen binnenkomen nergens heen te gaan.
import asyncio
import signal
class GracefulShutdown:
def __init__(self, bot, nats):
self.bot = bot
self.nats = nats
self.shutting_down = False
def register(self):
loop = asyncio.get_running_loop()
for sig in (signal.SIGTERM, signal.SIGINT):
loop.add_signal_handler(sig, lambda: asyncio.create_task(self.shutdown()))
async def shutdown(self):
if self.shutting_down:
return
self.shutting_down = True
# Stop receiving from Discord, then publish and finish what is in hand.
await self.bot.close()
await self.nats.drain()
terminationGracePeriodSeconds op Kubernetes, of stop_grace_period op Swarm, moet langer zijn dan dit duurt. Anders wordt het proces halverwege het drainen gestopt.
Waar je op let
Drie groepen cijfers vertellen je het meeste wat je moet weten.
Per shard: de tijd tot de heartbeat-ACK, normaal ruim onder 500 ms; het aantal guilds, dat over de shards ongeveer gelijk hoort te zijn; en events per minuut. Een shard waarvan de events plots naar nul zakken terwijl zijn verbinding er goed uitziet, zit vast.
Per consumer: wachtende berichten, verstreken ack-wachttijden, en het aandeel berichten dat meer dan één keer is afgeleverd.
Per machine: geheugen en CPU, met alerts op trends in plaats van losse waarden. Een lek van 1 MB per uur vult een limiet van 512 MB in zo’n drie weken, en een trendalert vangt het in de eerste dagen.
| Meting | Waarschuwing | Kritiek |
|---|---|---|
| Tijd tot heartbeat-ACK | boven 1.000 ms | boven 5.000 ms |
| Wachtende berichten | boven 1.000 | boven 10.000 |
| Opnieuw afgeleverd | boven 5% | boven 15% |
| Tijd sinds het laatste event | boven 30 s | boven 120 s |
| Geheugen | boven 80% van de limiet | boven 95% |
Begin met vijf tot tien alerts. Elke alert die afgaat zonder dat iemand iets moet doen, leert het team de volgende te negeren.
Test hoe je leest
Drie dashboards. Beslis zelf of elk ervan een echt probleem toont, en open dan het antwoord.
De wachtrij die blijft groeien
stream DISCORD_EVENTS consumer moderation-worker pending 4,012 (10 minutes ago: 380) redelivered 0.4% workers 3 running, 3 ready
Is dit een echt probleem?
Ja. Het aantal wachtende berichten is in tien minuten meer dan vertienvoudigd, terwijl elke worker zich gezond meldt.
De workers draaien, maar kunnen niet volgen. Weinig heraflevering betekent dat ze niet crashen of vastlopen; ze zijn gewoon te traag voor de huidige last, vaak door één trage stap zoals een databasecall. Zet er workers bij om de achterstand weg te werken, en zoek dan die trage stap.
Eén tragere heartbeat
shard guilds heartbeat ACK events/min 0 2,418 92 ms 3,910 1 2,377 88 ms 3,850 2 2,402 181 ms 3,880 3 2,391 90 ms 3,870
Is dit een echt probleem?
Nee. De heartbeat van shard 2 is dubbel zo traag als de andere, maar ver onder de waarschuwing van 1.000 ms, en zijn events blijven stromen.
Heartbeat-tijden schommelen met de route naar Discord en de last op de machine. Wat telt, is dat shard 2 evenveel events afhandelt als de andere. Hou hem in het oog als hij blijft stijgen.
De aanhoudende heraflevering
consumer voice-tracker pending 42 redelivered 18% (last hour) ack wait 10s handler p95 9.4s
Is dit een echt probleem?
Ja. Bijna één op de vijf berichten wordt twee keer afgeleverd, omdat de traagste runs van de handler dicht bij de ack-wachttijd van 10 seconden komen.
JetStream denkt dat de worker gestorven is en geeft het bericht aan een andere, terwijl de eerste nog bezig is. Zet de ack-wachttijd boven de traagste normale run, of maak de handler sneller. Zorg hoe dan ook dat hetzelfde event twee keer afhandelen geen kwaad kan.
Dit op A-Line.cloud
Alles hierboven kun je zelf doen, en op een paar servers is het een redelijk weekendproject. Wil je het platform eronder liever niet zelf beheren, dan draait A-Line.cloud hetzelfde patroon voor je:
- Beheerde NATS met JetStream, zodat de stream in het midden er is zonder dat je hem zelf draait.
- Workers die schalen op wachtende berichten, via KEDA: meer workers als de wachtrij groeit, minder als ze leeg is.
- Rolling deploys die pas verdergaan zodra de nieuwe versie klaar is, en terugrollen als een deploy mislukt.
- Builds vanuit GitHub en certificaten die voor je geregeld worden, zonder Kubernetes-YAML om te schrijven.
A-Line.cloud werkt voorlopig op uitnodiging. Draai je zo’n bot en wil je hem verhuizen, vraag dan toegang aan en vertel ons wat hij vandaag doet.
Veelgestelde vragen
Hoeveel shards heeft mijn bot nodig?
Vraag het aan Discord: het endpoint /gateway/bot geeft een aanbevolen aantal terug. Onder 2.500 guilds volstaat één shard; daarboven verplicht Discord sharding. Veel teams beginnen met iets meer dan aanbevolen, omdat het aantal later veranderen betekent dat elke shard opnieuw moet verbinden.
Heb ik hiervoor Kubernetes nodig?
Nee. Voor een bot tot zo’n 20 shards doet Docker Swarm met een Postgres-tabel voor shardeigendom het werk, en dat is veel minder om te leren en te beheren. Kubernetes begint te lonen als je tientallen shards en veel soorten workers draait, of als je het al voor andere dingen gebruikt.
Waarom geen Redis Pub/Sub als wachtrij?
Redis Pub/Sub levert een bericht alleen af aan wie op dat moment luistert. Herstart een worker, dan zijn zijn berichten weg. Redis Streams bewaren berichten wel en ondersteunen bevestigingen, dus als je Redis al draait, zijn die een redelijk alternatief voor JetStream.
Waarom falen slash-commando’s tijdens een deploy?
Discord geeft je 3 seconden om op een interactie te antwoorden. Herstart de worker die ze afhandelt, dan verstrijkt die tijd en ziet de gebruiker “The application did not respond”. Hou tijdens een deploy minstens één worker voor interacties klaar, of stuur meteen een uitgesteld antwoord en doe het werk daarna: een uitgesteld antwoord geeft je tot 15 minuten.
Geeft RESUME elk gemist event terug?
Alleen zolang de sessie nog geldig is. Discord speelt de events af na het laatste volgnummer dat je shard zag. Is de sessie verlopen, dan identificeert de shard opnieuw en zijn de events daartussen verloren. Laat de bot na een nieuwe IDENTIFY de toestand waar hij op steunt opnieuw laden, in plaats van aan te nemen dat er niets veranderd is.
Wat je als eerste verandert
Zet JetStream tussen je gateway en je handlers. Met de stream in het midden geeft de gateway alleen door, en kunnen de workers komen en gaan zonder dat er een event verloren gaat. Herstart daarna op een rustig uur een worker en kijk hoe het aantal wachtende berichten stijgt en weer naar nul zakt, net als in de demo hierboven.