diff --git a/docs/events/gateway.mdx b/docs/events/gateway.mdx index a432fff794..dfc338ae66 100644 --- a/docs/events/gateway.mdx +++ b/docs/events/gateway.mdx @@ -601,7 +601,7 @@ As apps grow and are added to an increasing number of guilds, some developers ma Each shard can only support a maximum of 2500 guilds, and apps that are in 2500+ guilds *must* enable sharding. ::: -To enable sharding on a connection, the app should send the `shard` array in the [Identify](/docs/events/gateway-events#identify) payload. The first item in this array should be the zero-based integer value of the current shard, while the second represents the total number of shards. DMs will only be sent to shard 0. +To enable sharding on a connection, the app should send the `shard` array in the [Identify](/docs/events/gateway-events#identify) payload. The first item in this array should be the zero-based integer value of the current shard, while the second represents the total number of shards. :::info The [Get Gateway Bot](/docs/events/gateway#get-gateway-bot) endpoint provides a recommended number of shards for your app in the `shards` field @@ -615,7 +615,11 @@ To calculate which events will be sent to which shard, the following formula can shard_id = (guild_id >> 22) % num_shards ``` -As an example, if you wanted to split the connection between three shards, you'd use the following values for `shard` for each connection: `[0, 3]`, `[1, 3]`, and `[2, 3]`. Note that only the first shard (`[0, 3]`) would receive DMs. +As an example, if you wanted to split the connection between three shards, you'd use the following values for `shard` for each connection: `[0, 3]`, `[1, 3]`, and `[2, 3]`. + +:::info +Gateway events that do not contain a `guild_id` will only be sent to the first shard (`shard_id: 0`). This includes Direct Message (DM), subscription and entitlement events. +::: Note that `num_shards` does not relate to (or limit) the total number of potential sessions. It is only used for *routing* traffic. As such, sessions do not have to be identified in an evenly-distributed manner when sharding. You can establish multiple sessions with the same `[shard_id, num_shards]`, or sessions with different `num_shards` values. This allows you to create sessions that will handle more or less traffic for more fine-tuned load balancing, or to orchestrate "zero-downtime" scaling/updating by handing off traffic to a new deployment of sessions with a higher or lower `num_shards` count that are prepared in parallel.