Sharding

Scale Kythia to thousands of servers using the built-in ShardingManager with crash-loop detection and OOM kill protection.

Discord requires bots to shard once they reach 2,500 guilds. Kythia Core exports a ShardingManager that wraps Discord.js's built-in manager with important production safeguards built in.

// sharding.js
const { ShardingManager } = require('kythia-core');
require('dotenv').config();

const manager = new ShardingManager({
  scriptPath: 'dist/index.js',
  token: process.env.DISCORD_TOKEN,
  totalShards: 'auto',
});

await manager.spawn();

{
  "scripts": {
    "start": "node sharding.js",
    "dev": "node index.js"
  }
}

node sharding.js

flowchart TD
    A([Shard Process Crashes]) --> B{Exit code 137\nor SIGKILL?}
    B -- Yes --> OOM[Log OOM Kill Alert\nActionable advice about heap size]
    B -- No --> C[Increment restart counter\nfor this shard]
    C --> D{Died >= 3 times\nin last 5 minutes?}
    D -- No --> RESPAWN[Respawn shard normally]
    D -- Yes --> E[Log Crash Loop Alert\nShard ID + restart count]
    E --> F[Pause respawning\nfor 2 minutes]
    F --> RESPAWN

    style OOM fill:#c0392b,color:#fff
    style E fill:#e67e22,color:#fff
    style RESPAWN fill:#27ae60,color:#fff

// Total restarts for a specific shard
const count = manager.getShardRestartCount(shardId);

// Stats for all shards
const stats = manager.getShardStats();
// → { 0: { restarts: 2, lastRestart: Date }, 1: { restarts: 0 } }

Even without sharding, the ShutdownManager runs a memory pressure monitor every 5 minutes:

flowchart LR
    POLL([Every 5 minutes]) --> MEASURE[Measure V8 heap usage\nvs heap_size_limit]
    MEASURE --> CHECK{Heap usage %?}
    CHECK -- ">= 80%" --> WARN[WARN log emitted]
    CHECK -- ">= 95%" --> ERROR[ERROR log emitted]
    CHECK -- "< 80%" --> OK[No action]

    style WARN fill:#e67e22,color:#fff
    style ERROR fill:#c0392b,color:#fff
    style OK fill:#27ae60,color:#fff

The threshold uses heap_size_limit — the actual V8 ceiling — not the reported heapTotal, giving you accurate warning before the process gets OOM-killed.

The ShutdownManager exposes a master uptime counter that survives shard restarts and reconnections:

const { shutdownManager } = container;
const uptimeSeconds = shutdownManager.getMasterUptime();

Unlike client.uptime (resets on reconnect), this measures true wall-clock time since the master process started.