수집 체계
SDK가 봇의 활동을 어떻게 감지하고, 어떤 경로로 서버에 전달하는지 전체 흐름을 설명합니다.
3대 카테고리
Dicolytics SDK는 봇의 활동을 3가지 카테고리로 분류하여 수집합니다.
| 카테고리 | 무엇을 | 감지 방식 | 전송 방식 | 메트릭 |
|---|---|---|---|---|
| 상호작용 | 사용자 → 봇 | interactionCreate 리스너 | 건별 즉시 큐잉 | interactions |
| 작업 | 봇 → Discord API | REST 메서드 패치 | 건별 즉시 큐잉 | actions |
| 이벤트 | 서버에서 발생 | 게이트웨이 리스너 | 60초 카운터 집계 | discord_events |
상호작용
사용자가 봇에게 보내는 입력입니다. 슬래시 명령어, 버튼 클릭, 셀렉트 메뉴 선택, 모달 제출, 컨텍스트 메뉴, 자동완성 요청 6종을 수집합니다. interactionCreate 이벤트를 감지하여 각 상호작용을 건별로 즉시 이벤트 큐에 추가합니다. 응답 지연 시간(latencyMs), 성공 여부(success), 15초 타임아웃 여부(timedOut) 등의 메타데이터를 포함합니다.
작업
봇이 Discord REST API를 호출하는 행위입니다. 메시지 전송, 역할 부여, 멤버 차단 등 22종을 감지합니다. client.rest의 post/patch/put/delete 메서드를 패치하여 URL 패턴으로 작업 종류를 분류합니다. 상호작용과 마찬가지로 건별로 즉시 큐에 추가됩니다.
이벤트
Discord 게이트웨이에서 발생하는 서버 활동입니다. 멤버 입퇴장, 메시지 생성/수정/삭제, 채널 변동 등 24종을 수집합니다. 대형 봇은 초당 수백~수천 건의 게이트웨이 이벤트가 발생하므로, 건별 전송 대신 60초 카운터로 집계하여 전송합니다.
인텐트 자동 감지
SDK는 client.options.intents 비트마스크를 확인하여, 활성화된 인텐트에 해당하는 이벤트만 리스너를 등록합니다. 예를 들어 GuildMessages 인텐트가 없으면 event_message_create 리스너는 등록되지 않습니다.
전송 흐름
봇 프로세스
┌──────────────────────────────────────────────────────────┐
│ │
│ 상호작용 감지 ──┐ │
│ 작업 감지 ──────┼──→ 이벤트 큐 ──→ 플러시 ──→ HTTP POST │
│ 이벤트 집계 ────┘ (최대 5,000건) (5초/50건) │
│ │
└──────────────────────────────────────────────────────────┘
│
▼
POST /v1/events
│
▼
┌───────────────────┐
│ Dicolytics 서버 │
│ 검증 & 저장 │
└───────────────────┘
│
▼
┌───────────────────┐
│ 데이터베이스 │
└───────────────────┘큐와 플러시
- 이벤트가 발생하면 이벤트 큐에 추가됩니다.
- 다음 조건 중 하나를 만족하면 플러시가 실행됩니다:
- 큐에 50개 이상의 이벤트가 대기 중
- 마지막 플러시 후 5초 경과 (
flushIntervalMs옵션으로 변경 가능)
- 플러시 시 최대 500개씩 배치로 묶어
POST /v1/events로 전송합니다. - 동시 전송은 1개만 허용합니다 (순서 보장).
버퍼 제한
이벤트 큐의 최대 크기는 5,000건입니다.
참고
네트워크 장애 등으로 전송이 지연되어 큐가 5,000건을 초과하면, 가장 오래된 이벤트부터 폐기됩니다. 정상 연결이 복구되면 자동으로 전송이 재개됩니다.
HTTP 배치 구조
하나의 HTTP 요청에 담기는 데이터 구조입니다.
{
"batchId": "01912345-6789-7abc-...",
"sdk": { "name": "@dicolytics/discord.js", "version": "0.5.0" }, // Python SDK: "dicolytics-discord.py"
"sentAt": "2025-01-15T12:00:00.000Z",
"events": [
{
"id": "01912345-6789-7def-...",
"type": "interaction_slash",
"ts": "2025-01-15T11:59:58.123Z",
"guildId": "123456789012345678",
"userId": "987654321098765432",
"data": { "commandName": "play rock", "latencyMs": 42, "success": true }
}
]
}- batchId: 전송 시도마다 새로 생성 (UUIDv7)
- events[].id: 이벤트별 고유 ID (UUIDv7). 재시도 시 동일 ID를 재사용하여 서버 측에서 중복 제거합니다.
- 배치당 최대 500개 이벤트, 1 MiB 크기 제한
- 1 MiB 초과 시 배치를 반으로 분할하여 재전송합니다.
자세한 전송 정책은 전송과 재시도를 참고하세요.
Python SDK
Python SDK(dicolytics)는 엔벨로프의 sdk 필드에 "name": "dicolytics-discord.py", "version": "0.1.0"을 전송합니다. 엔벨로프 포맷은 discord.js SDK와 동일합니다.
스냅샷
이벤트와 별도로, SDK는 주기적 스냅샷을 수집합니다. 스냅샷은 events 테이블에 저장되지 않으며 할당량에 포함되지 않습니다.
| 스냅샷 종류 | 주기 | 내용 |
|---|---|---|
heartbeat | 60초 (설정 가능) | 봇 상태: 서버 수, 핑, 메모리, CPU, 음성 연결 등 |
guild_snapshot | 60초 (설정 가능) | 캐시된 각 서버: 멤버 수, 온라인 수, 이름, 로케일 |
api_routes_snapshot | 5분 | 상위 10개 API 라우트 사용 통계 |
스냅샷 주기는 snapshotIntervalMs 옵션으로 변경할 수 있습니다. 자세한 내용은 설정 옵션을 참고하세요.
기타 이벤트
3대 카테고리 외에 SDK가 자동으로 수집하는 이벤트도 있습니다.
| 이벤트 | 감지 방식 | 설명 |
|---|---|---|
command_error | reply 메서드 reject/throw | 상호작용 응답 중 발생한 오류 |
error | captureError() 또는 unhandledRejection | 수동 보고 또는 자동 캡처 |
guild_join / guild_leave | guildCreate / guildDelete | 봇이 서버에 추가/제거됨 |
shard_ready 등 4종 | 샤드 생명주기 이벤트 | 샤드 연결/해제/재개/재연결 |
전체 이벤트 타입 목록은 이벤트 레퍼런스를 참고하세요.
데이터 보호
SDK는 봇 운영자의 프라이버시를 존중합니다.
- 메시지 내용은 절대 수집하지 않습니다. 발신 메시지 건수만 기록합니다.
- 수신 메시지 이벤트(
messageCreate등)의 내용도 수집하지 않습니다. 건수만 집계합니다. guildName과locale은 Discord에서 공개적으로 표시되는 정보입니다.- 오류 페이로드는
name(200자),message(2 KiB),stack(8 KiB)으로 제한됩니다. - 문자열 속성은 개당 4 KiB, 이벤트
data전체는 16 KiB로 제한됩니다. - 순환 참조와 직렬화 불가능한 값은 자동 제거됩니다.