멀티클러스터
여러 프로세스(클러스터)로 봇을 분산 운영할 때 clusterId를 설정하는 방법을 설명합니다.
참고
단일 프로세스로 봇을 운영한다면 clusterId를 설정할 필요 없습니다. shardId는 SDK가 자동으로 포함합니다.
clusterId 설정
각 클러스터 프로세스에서 createDicolytics 호출 시 고유한 clusterId를 지정합니다.
ts
const analytics = createDicolytics(client, {
apiKey: process.env.DICOLYTICS_KEY!,
clusterId: 0,
});ts
const analytics = createDicolytics(client, {
apiKey: process.env.DICOLYTICS_KEY!,
clusterId: 1,
});python
analytics = create_dicolytics(bot, api_key=os.environ["DICOLYTICS_KEY"], cluster_id=0)python
analytics = create_dicolytics(bot, api_key=os.environ["DICOLYTICS_KEY"], cluster_id=1)clusterId는 0 ~ 32,767 범위의 정수입니다. 설정하면 해당 프로세스에서 발생하는 모든 이벤트의 data.clusterId 필드에 포함됩니다.
환경변수로 동적 설정
배포 환경에서는 환경변수로 클러스터 ID를 전달하는 것이 일반적입니다.
ts
const analytics = createDicolytics(client, {
apiKey: process.env.DICOLYTICS_KEY!,
clusterId: Number(process.env.CLUSTER_ID),
});python
analytics = create_dicolytics(bot,
api_key=os.environ["DICOLYTICS_KEY"],
cluster_id=int(os.environ["CLUSTER_ID"]),
)데이터 분리 방식
- 이벤트 (상호작용, 작업, 게이트웨이 이벤트, 커스텀):
project_id기준으로 합산됩니다. 대시보드 보고서에서 보는 수치는 항상 전체 클러스터 합계입니다. - 스냅샷 (heartbeat, guild_snapshot):
(project_id, cluster_id, shard_id)조합으로 분리 저장됩니다. 서버 수, 메모리, CPU, 핑 등은 각 샤드별로 독립 기록됩니다.
상태 페이지에서 확인
clusterId를 설정하면 대시보드의 상태 페이지에 클러스터 > 샤드 계층 구조가 표시됩니다. 각 샤드 카드를 클릭하면 시간별 성능 추이(핑, 메모리, CPU, 이벤트 루프)를 확인할 수 있습니다.
ShardingManager 연동
ShardingManager를 사용하는 경우, 각 샤드 프로세스에서 SDK 인스턴스를 생성하면 됩니다. ShardingManager는 하나의 머신에서 여러 샤드 프로세스를 생성하므로 clusterId를 설정하지 않아도 됩니다.
멀티클러스터는 여러 머신에 ShardingManager를 분산 배포하는 경우입니다. 이때 각 머신(클러스터)을 구분하기 위해 clusterId가 필요합니다.
ts
import { ShardingManager } from 'discord.js';
const manager = new ShardingManager('./bot.ts', {
totalShards: 'auto',
token: process.env.DISCORD_TOKEN,
});
manager.spawn();ts
import { Client, GatewayIntentBits } from 'discord.js';
import { createDicolytics } from '@dicolytics/discord.js';
const client = new Client({
intents: [GatewayIntentBits.Guilds],
});
// ShardingManager 사용 시 clusterId를 설정할 필요 없음
// shardId는 SDK가 자동으로 포함합니다
const analytics = createDicolytics(client, {
apiKey: process.env.DICOLYTICS_KEY!,
});
client.login(process.env.DISCORD_TOKEN);