O que é sharding no Discord e quando seu bot precisa

Um bot do Discord recebe quase tudo por uma conexão WebSocket com o Gateway: mensagens, entradas em servidores, mudanças de cargo, eventos de voz. Enquanto o bot está em poucos servidores, uma conexão dá conta. Quando ele cresce, o volume de eventos numa única sessão vira um problema, e o Discord passa a exigir que você divida a carga.

Essa divisão se chama sharding. Ela assusta porque costuma aparecer na hora errada: o bot cresce, para de conectar e o log mostra um código de erro que ninguém viu antes. Entender como funciona antes disso evita a correria.

O que é sharding no Discord?#

Sharding é abrir várias sessões com o Gateway em vez de uma só. Cada sessão é um shard, identificado por um número a partir de 0, e cada shard recebe os eventos de uma fatia dos servidores do bot.

Na prática, quando o bot se identifica no Gateway, ele envia um par [shard_id, num_shards]. Um bot com três shards abre três conexões e manda [0, 3], [1, 3] e [2, 3]. Para os usuários nada muda: é o mesmo bot, com o mesmo token e os mesmos comandos. Só a forma de receber eventos é que fica dividida.

Shard não é o mesmo que processo. Vários shards podem rodar dentro de um único processo, ou cada shard pode ter o seu próprio processo. Essa escolha é sua, e afeta memória e isolamento, como você vai ver adiante.

Como o Discord decide qual shard recebe cada servidor?#

Pela fórmula documentada do Gateway:

shard_id = (guild_id >> 22) % num_shards

O ID de um servidor é um snowflake. Os bits deslocados (>> 22) correspondem ao momento em que o servidor foi criado, e o resto da divisão pelo número de shards define o destino. Como os IDs são grandes demais para números comuns em JavaScript, use BigInt:

// Calcula qual shard recebe os eventos de um servidor
function shardDoServidor(guildId, numShards) {
  return Number((BigInt(guildId) >> 22n) % BigInt(numShards));
}

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

Dois detalhes importam. Primeiro, eventos sem guild_id, como mensagens diretas, chegam só ao shard 0. Segundo, a fórmula garante que um servidor sempre cai no mesmo shard enquanto o número total não mudar. Se você aumentar de 4 para 8 shards, os servidores são redistribuídos.

Quando o seu bot precisa de sharding?#

A regra oficial é objetiva: cada shard suporta no máximo 2.500 servidores, e apps em 2.500 servidores ou mais precisam ativar sharding. Se o bot tentar se conectar com uma sessão grande demais, o Gateway fecha a conexão com 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.

Esse código não permite reconexão: o bot fica offline até você ativar o sharding. O guia do discord.js recomenda começar a preparar o código por volta de 2.000 servidores, para não ser pego de surpresa, e usar cerca de 1.000 servidores por shard.

Para saber quantos shards usar, pergunte ao Discord. O endpoint GET /gateway/bot, autenticado com o token do bot, devolve:

• shards: o número recomendado de shards.
• session_start_limit: quantas sessões você ainda pode iniciar (total, remaining, reset_after) e o max_concurrency, quantos shards podem se identificar a cada 5 segundos.

As bibliotecas fazem essa consulta sozinhas quando você usa o modo automático. Abaixo de 2.500 servidores o sharding é opcional, e para a maioria dos bots pequenos ele não traz vantagem nenhuma. Um app que recebe interações apenas por HTTP, sem abrir o Gateway, também não precisa.

Sharding interno ou um processo por shard?#

As bibliotecas oferecem dois modelos:

O guia do discord.js avisa que o sharding interno não é ideal para bots maiores por causa do uso de memória. Para quem está chegando aos 2.500 servidores, o ShardingManager é o caminho mais comum no Node.js.

Como ativar sharding no discord.js e no discord.py?#

No discord.js v14, o arquivo do bot continua quase igual. Renomeie-o para bot.js e crie um index.js que inicia os shards (os exemplos usam import, então o package.json precisa de "type": "module"):

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

const manager = new ShardingManager("./bot.js", {
  token: process.env.DISCORD_TOKEN,
  totalShards: "auto", // pergunta ao Discord quantos shards usar
});

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

await manager.spawn();

// bot.js: o bot de sempre, agora rodando como um 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]} pronto com ${client.guilds.cache.size} servidores`);
});

client.on(Events.InteractionCreate, async (interaction) => {
  if (!interaction.isChatInputCommand() || interaction.commandName !== "servidores") return;
  // cada shard só conhece os próprios servidores: some os de todos
  const porShard = await client.shard.fetchClientValues("guilds.cache.size");
  const total = porShard.reduce((soma, n) => soma + n, 0);
  await interaction.reply(`Estou em ${total} servidores.`);
});

client.login(process.env.DISCORD_TOKEN);

O exemplo supõe um comando /servidores já registrado. Registre o listener shardCreate antes de chamar spawn(), como o guia recomenda.

No discord.py 2.x, troque discord.Client por discord.AutoShardedClient (ou commands.Bot por commands.AutoShardedBot). Sem shard_count, a biblioteca consulta o Gateway e decide quantos shards abrir, tudo num único processo:

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"])

Se o bot ainda não existe, comece por como hospedar um bot discord.js ou como hospedar um bot discord.py.

O que muda no código quando o bot tem shards?#

Com sharding interno, quase nada: o processo continua vendo todos os servidores. Com um processo por shard, algumas suposições quebram:

• Contagens globais. client.guilds.cache.size mostra só os servidores daquele shard. Use fetchClientValues ou broadcastEval para somar.
• Estado em memória. Um cache, um contador ou uma fila em memória existe uma vez por processo. Estado que precisa ser compartilhado vai para um banco de dados ou um Redis.
• DMs. Só o shard 0 recebe. Lógica que depende de mensagem direta roda lá.
• Inicialização. Os shards se identificam em grupos de max_concurrency a cada 5 segundos, então um bot com muitos shards demora para ficar todo online.
• Reinícios. Cada sessão iniciada conta no session_start_limit. O limite diário costuma ser de 1.000 sessões, e um bot que reinicia em loop pode esgotá-lo: quando isso acontece, o Discord encerra todas as sessões e redefine o token do bot. Veja o erro 429 do Discord.

Bots muito grandes, com mais de 150.000 servidores, passam para o sharding de bots grandes (large bot sharding): o Discord informa um número e o total de shards precisa ser múltiplo dele, ou a conexão fecha com 4010 Invalid shard.

Quanto de recurso o sharding consome?#

Sharding não cria trabalho novo: os mesmos eventos chegam, só que divididos. O que aumenta é a base fixa. No modelo de um processo por shard, cada processo carrega o próprio runtime, a biblioteca e os próprios caches, então quatro processos gastam mais memória de base que um processo com quatro shards internos.

Por isso, meça antes de escolher o modelo. Rode o bot com a carga real, anote o pico de memória de cada processo e some. O artigo sobre quanta RAM um bot do Discord precisa mostra como medir e como reduzir o cache, que costuma pesar mais que os shards em si.

Como fazer isso na Square Cloud#

Na Square Cloud, bots do Discord rodam em containers isolados com discord.js, discord.py, JDA, Discord.Net ou outra biblioteca de Gateway, com sharding e voz. Tanto o sharding interno quanto o ShardingManager funcionam dentro da mesma aplicação, e a latência média até o Gateway do Discord é de cerca de 30 ms.

A RAM do plano é um pool compartilhado entre suas aplicações, com mínimo de 256 MB por bot, e uma aplicação pode usar até 32 GB. Quando o bot crescer, você mesmo aumenta a RAM nas configurações ou pela API, com base nas métricas de CPU e RAM do painel. Não há autoscaling: o ajuste é decisão sua.

Os containers ficam sempre ligados, com reinício automático (ligado por padrão no deploy pelo painel) quando o processo encerra com erro, e os logs em tempo real mostram cada shard conectando. Veja os detalhes em hospedagem de bots do Discord.