이벤트 24종

Discord 게이트웨이에서 발생하는 서버 활동 24종의 집계 방식과 인텐트 요구사항을 설명합니다.

집계 방식

대형 봇은 초당 수백~수천 건의 게이트웨이 이벤트가 발생합니다. 이를 건별로 전송하면 네트워크 트래픽과 DB 부하가 폭발적으로 증가합니다.

SDK는 게이트웨이 이벤트를 건별로 전송하지 않고, 60초마다 카운터를 집계하여 하나의 이벤트로 전송합니다.

{
  "type": "event_message_create",
  "ts": "2025-01-15T12:01:00.000Z",
  "data": { "count": 832 }
}

위 예시는 "직전 60초 동안 messageCreate 이벤트가 832건 발생했다"는 의미입니다.

discord_events vs events 메트릭

대시보드에서 두 가지 메트릭을 구분해야 합니다.

• discord_events = sum(data.count) -- 실제 게이트웨이 이벤트 총 건수
• events = count(*) -- 집계 이벤트 레코드 수 (60초에 1건)

예를 들어 1시간 동안 event_message_create가 분당 100건씩 발생했다면:

• discord_events = 6,000 (실제 메시지 수)
• events = 60 (60초마다 1건의 집계 레코드)

이벤트 타입과 인텐트

인텐트 불필요

다음 이벤트들은 기본 Guilds 인텐트만으로 수집됩니다.

event_type	discord.js 이벤트	설명
event_channel_create	channelCreate	채널 생성
event_channel_update	channelUpdate	채널 수정
event_channel_delete	channelDelete	채널 삭제
event_role_create	roleCreate	역할 생성
event_role_update	roleUpdate	역할 수정
event_role_delete	roleDelete	역할 삭제
event_thread_create	threadCreate	스레드 생성
event_thread_update	threadUpdate	스레드 수정
event_thread_delete	threadDelete	스레드 삭제
event_invite_create	inviteCreate	초대 생성
event_invite_delete	inviteDelete	초대 삭제/만료
event_voice_state	voiceStateUpdate	음성 상태 변경 (입장/퇴장/이동/뮤트)

GuildMembers 인텐트 필요 특권

event_type	discord.js 이벤트	설명
event_member_join	guildMemberAdd	멤버 서버 입장
event_member_leave	guildMemberRemove	멤버 서버 퇴장
event_member_update	guildMemberUpdate	멤버 정보 변경 (닉네임, 역할, 부스트 등)

GuildModeration 인텐트 필요

event_type	discord.js 이벤트	설명
event_ban_add	guildBanAdd	멤버 차단
event_ban_remove	guildBanRemove	멤버 차단 해제

GuildMessages 인텐트 필요

event_type	discord.js 이벤트	설명
event_message_create	messageCreate	메시지 생성
event_message_update	messageUpdate	메시지 수정
event_message_delete	messageDelete	메시지 삭제

GuildMessageReactions 인텐트 필요

event_type	discord.js 이벤트	설명
event_reaction_add	messageReactionAdd	리액션 추가
event_reaction_remove	messageReactionRemove	리액션 제거

GuildMessageTyping 인텐트 필요

event_type	discord.js 이벤트	설명
event_typing_start	typingStart	타이핑 시작

GuildPresences 인텐트 필요 특권

event_type	discord.js 이벤트	설명
event_presence_update	presenceUpdate	프레즌스 변경 (온라인/자리비움/오프라인)

참고

GuildMembers와 GuildPresences는 **특권 인텐트(Privileged Intent)**입니다. Discord Developer Portal에서 봇의 설정 페이지로 이동하여 해당 인텐트를 활성화해야 합니다. 활성화하지 않으면 관련 이벤트가 게이트웨이에서 전달되지 않으며, SDK도 수집할 수 없습니다.

100개 이상의 서버에 있는 봇은 특권 인텐트 사용을 위해 Discord의 별도 심사가 필요합니다.

인텐트 자동 감지

SDK는 client.options.intents 비트마스크를 확인하여, 활성화된 인텐트에 해당하는 이벤트만 리스너를 등록합니다.

const client = new Client({
  intents: [
    GatewayIntentBits.Guilds,          // 채널, 역할, 스레드, 초대, 음성 상태
    GatewayIntentBits.GuildMessages,   // 메시지 생성/수정/삭제
    GatewayIntentBits.GuildMembers,    // 멤버 입퇴장/수정 (특권)
  ],
});

위 설정이면 event_message_create, event_member_join 등은 수집되지만, event_reaction_add(GuildMessageReactions 필요)나 event_presence_update(GuildPresences 필요)는 리스너가 등록되지 않습니다.

참고

SDK가 이벤트를 수집하려면 discord.js 클라이언트에 해당 인텐트가 활성화되어 있어야 합니다. 하지만 인텐트를 추가하면 게이트웨이 트래픽이 증가할 수 있으므로, 필요한 인텐트만 활성화하세요.

서버별/사용자별 구분 없음

게이트웨이 이벤트는 전체 트래픽 볼륨 파악을 목적으로 수집됩니다. 개별 이벤트의 guild_id나 user_id는 기록하지 않습니다.

• "어떤 서버에서 메시지가 가장 많이 생성되는가" → 이 질문에는 답할 수 없습니다
• "봇 전체에서 분당 메시지 생성 건수가 어떻게 변하는가" → 이 질문에 답할 수 있습니다

서버별 활동을 추적하려면 커스텀 이벤트로 직접 기록하세요.

대시보드에서 확인

게이트웨이 이벤트 데이터는 대시보드의 보고서에서 확인합니다.

• 홈 개요의 이벤트 탭: 전체 discord_events 추이
• 탐색(Explore): event_type = event_* 필터로 타입별 분석
• 메트릭 셀렉터에서 discord_events를 선택하면 실제 건수 합계(sum(count))를 볼 수 있습니다

관련 문서

• 수집 체계 -- 전체 수집 흐름과 집계 방식
• 메트릭과 차원 -- discord_events 메트릭 상세
• 설정 옵션 -- disabledEvents로 특정 이벤트 비활성화
• 이벤트 레퍼런스 -- 전체 이벤트 타입 목록