¿Qué es el sharding en Discord y cuándo lo necesita tu bot?

Un bot de Discord recibe casi todo por una conexión WebSocket con el Gateway: mensajes, entradas en servidores, cambios de rol, eventos de voz. Mientras el bot está en pocos servidores, una conexión basta. Cuando crece, el volumen de eventos en una sola sesión se convierte en un problema, y Discord empieza a exigir que repartas la carga.

Ese reparto se llama sharding. Suele aparecer en el peor momento: el bot crece, deja de conectarse y el log muestra un código de error que nadie había visto. Entender cómo funciona antes te ahorra las prisas.

¿Qué es el sharding en Discord?#

El sharding consiste en abrir varias sesiones con el Gateway en lugar de una sola. Cada sesión es un shard, identificado por un número que empieza en 0, y cada shard recibe los eventos de una parte de los servidores del bot.

En la práctica, cuando el bot se identifica en el Gateway, envía un par [shard_id, num_shards]. Un bot con tres shards abre tres conexiones y envía [0, 3], [1, 3] y [2, 3]. Para los usuarios no cambia nada: es el mismo bot, con el mismo token y los mismos comandos. Solo cambia la forma de recibir los eventos.

Un shard no es lo mismo que un proceso. Varios shards pueden correr dentro de un único proceso, o cada shard puede tener su propio proceso. Esa decisión es tuya, y afecta a la memoria y al aislamiento, como verás más abajo.

¿Cómo decide Discord qué shard recibe cada servidor?#

Con la fórmula documentada del Gateway:

shard_id = (guild_id >> 22) % num_shards

El ID de un servidor es un snowflake. Los bits desplazados (>> 22) corresponden al momento en que se creó el servidor, y el resto de la división entre el número de shards define el destino. Como los IDs son demasiado grandes para los números normales de JavaScript, usa BigInt:

// Calcula qué shard recibe los eventos de un servidor
function shardDelServidor(guildId, numShards) {
  return Number((BigInt(guildId) >> 22n) % BigInt(numShards));
}

console.log(shardDelServidor("197038439483310086", 4)); // 2

Hay dos detalles importantes. Primero, los eventos sin guild_id, como los mensajes directos, llegan solo al shard 0. Segundo, la fórmula garantiza que un servidor siempre cae en el mismo shard mientras el total no cambie. Si pasas de 4 a 8 shards, los servidores se redistribuyen.

¿Cuándo necesita sharding tu bot?#

La regla oficial es clara: cada shard admite como máximo 2.500 servidores, y las apps con 2.500 servidores o más tienen que activar el sharding. Si el bot intenta conectarse con una sesión demasiado grande, el Gateway cierra la conexión con este código:

4011 Sharding required
The session would have handled too many guilds - you are required to shard your connection in order to connect.

Este código no permite reconectar: el bot queda offline hasta que actives el sharding. La guía de discord.js recomienda preparar el código hacia los 2.000 servidores, para que no te tome por sorpresa, y usar unos 1.000 servidores por shard.

Para saber cuántos shards usar, pregúntale a Discord. El endpoint GET /gateway/bot, autenticado con el token del bot, devuelve:

• shards: el número recomendado de shards.
• session_start_limit: cuántas sesiones puedes iniciar todavía (total, remaining, reset_after) y el max_concurrency, cuántos shards pueden identificarse cada 5 segundos.

Las bibliotecas hacen esta consulta por su cuenta en el modo automático. Por debajo de 2.500 servidores el sharding es opcional, y para la mayoría de los bots pequeños no aporta ninguna ventaja. Una app que recibe interacciones solo por HTTP, sin abrir el Gateway, tampoco lo necesita.

¿Sharding interno o un proceso por shard?#

Las bibliotecas ofrecen dos modelos:

La guía de discord.js advierte que el sharding interno no es ideal para bots grandes por el uso de memoria. Para un bot que se acerca a los 2.500 servidores, ShardingManager es el camino más habitual en Node.js.

¿Cómo activar el sharding en discord.js y discord.py?#

En discord.js v14, el archivo del bot queda casi igual. Renómbralo a bot.js y crea un index.js que inicie los shards (los ejemplos usan import, así que tu package.json necesita "type": "module"):

// index.js: inicia un proceso por shard
import { ShardingManager } from "discord.js";

const manager = new ShardingManager("./bot.js", {
  token: process.env.DISCORD_TOKEN,
  totalShards: "auto", // pregunta a Discord cuántos shards usar
});

manager.on("shardCreate", (shard) => console.log(`Shard ${shard.id} creado`));

await manager.spawn();

// bot.js: el bot de siempre, ahora como un shard
import { Client, Events, GatewayIntentBits } from "discord.js";

const client = new Client({ intents: [GatewayIntentBits.Guilds] });

client.once(Events.ClientReady, () => {
  console.log(`Shard ${client.shard.ids[0]} listo con ${client.guilds.cache.size} servidores`);
});

client.on(Events.InteractionCreate, async (interaction) => {
  if (!interaction.isChatInputCommand() || interaction.commandName !== "servidores") return;
  // cada shard solo conoce sus propios servidores: súmalos todos
  const porShard = await client.shard.fetchClientValues("guilds.cache.size");
  const total = porShard.reduce((suma, n) => suma + n, 0);
  await interaction.reply(`Estoy en ${total} servidores.`);
});

client.login(process.env.DISCORD_TOKEN);

El ejemplo supone que el comando /servidores ya está registrado. Registra el listener shardCreate antes de llamar a spawn(), como recomienda la guía.

En discord.py 2.x, cambia discord.Client por discord.AutoShardedClient (o commands.Bot por commands.AutoShardedBot). Sin shard_count, la biblioteca consulta el Gateway y decide cuántos shards abrir, todo en un único proceso:

import os

import discord

intents = discord.Intents.default()
client = discord.AutoShardedClient(intents=intents)


@client.event
async def on_ready():
    print(f"{client.shard_count} shards, {len(client.guilds)} servidores")
    for shard_id, latencia in client.latencies:
        print(f"shard {shard_id}: {latencia * 1000:.0f} ms")


client.run(os.environ["DISCORD_TOKEN"])

Si el bot todavía no existe, empieza por cómo alojar un bot de discord.js o cómo alojar un bot de discord.py.

¿Qué cambia en el código cuando el bot tiene shards?#

Con sharding interno, casi nada: el proceso sigue viendo todos los servidores. Con un proceso por shard, algunas suposiciones dejan de valer:

• Conteos globales. client.guilds.cache.size muestra solo los servidores de ese shard. Usa fetchClientValues o broadcastEval para sumarlos.
• Estado en memoria. Una caché, un contador o una cola en memoria existe una vez por proceso. El estado que deba compartirse va a una base de datos o a Redis.
• DMs. Solo los recibe el shard 0. La lógica que depende de mensajes directos corre allí.
• Arranque. Los shards se identifican en grupos de max_concurrency cada 5 segundos, así que un bot con muchos shards tarda en estar todo en línea.
• Reinicios. Cada sesión iniciada cuenta para el session_start_limit. El límite diario suele ser de 1.000 sesiones, y un bot que se reinicia en bucle puede agotarlo: cuando eso pasa, Discord cierra todas las sesiones y restablece el token del bot. Mira el error 429 de Discord.

Los bots muy grandes, con más de 150.000 servidores, pasan al sharding para bots grandes: Discord te da un número y el total de shards tiene que ser múltiplo de él, o la conexión se cierra con 4010 Invalid shard.

¿Cuántos recursos consume el sharding?#

El sharding no crea trabajo nuevo: llegan los mismos eventos, solo que repartidos. Lo que crece es la base fija. Con un proceso por shard, cada proceso carga su propio runtime, la biblioteca y sus propias cachés, así que cuatro procesos gastan más memoria de base que un proceso con cuatro shards internos.

Por eso, mide antes de elegir el modelo. Ejecuta el bot con la carga real, anota el pico de memoria de cada proceso y súmalos. El artículo sobre cuánta RAM necesita un bot de Discord muestra cómo medir y cómo reducir la caché, que suele pesar más que los shards en sí.

Cómo hacerlo en Square Cloud#

En Square Cloud, los bots de Discord corren en contenedores aislados con discord.js, discord.py, JDA, Discord.Net u otra biblioteca de Gateway, con sharding y voz. Tanto el sharding interno como ShardingManager funcionan dentro de la misma aplicación, y la latencia media hasta el Gateway de Discord es de unos 30 ms.

La RAM del plan es un pool compartido entre tus aplicaciones, con un mínimo de 256 MB por bot, y una aplicación puede usar hasta 32 GB. Cuando el bot crezca, tú mismo subes la RAM en la configuración o por la API, según las métricas de CPU y RAM del panel. No hay autoscaling: el ajuste es decisión tuya.

Los contenedores están siempre encendidos, con reinicio automático (activado por defecto en el deploy desde el panel) cuando el proceso termina con error, y los logs en tiempo real muestran cada shard conectándose. Mira los detalles en hosting para bots de Discord.