설정 옵션 v0.5.0

createDicolytics(client, options)에 전달하는 모든 옵션을 정리합니다.

전체 옵션 표

옵션	타입	기본값	설명
apiKey	string	(필수)	프로젝트 API 키. dk_live_... 형식.
endpoint	string	https://api.dicolytics.com	API 기본 URL.
disabledEvents	string[]	[]	비활성화할 자동 수집 이벤트 타입 배열.
debug	boolean	false	SDK 진단 로그를 console.warn으로 출력합니다.
snapshotIntervalMs	number	60000	하트비트/서버 스냅샷 주기 (ms).
flushIntervalMs	number	5000	이벤트 큐 플러시 주기 (ms).
requestTimeoutMs	number	10000	HTTP 요청 타임아웃 (ms).
clusterId	number	--	멀티클러스터 환경용 클러스터 식별자.
autoCapturePromiseRejections	boolean	false	처리되지 않은 Promise rejection을 자동 보고합니다.

Python SDK (discord.py)

Python SDK(dicolytics)에서는 create_dicolytics(bot, **options)를 사용합니다. 모든 옵션은 snake_case입니다: api_key, disabled_events, snapshot_interval_ms, flush_interval_ms, request_timeout_ms, cluster_id, auto_capture_exceptions, debug, endpoint.

옵션 상세

apiKey 필수

discord.js

createDicolytics(client, {
  apiKey: process.env.DICOLYTICS_KEY!,
});

discord.py

create_dicolytics(bot, api_key=os.environ["DICOLYTICS_KEY"])

프로젝트의 API 키입니다. dk_live_ 접두사로 시작합니다. HTTP 요청의 Authorization: Bearer 헤더로 전송됩니다.

apiKey가 비어 있거나 누락되면 동기적으로 TypeError를 던집니다. 이 옵션만 유일하게 예외를 발생시킵니다.

endpoint

discord.js

createDicolytics(client, {
  apiKey: '...',
  endpoint: 'https://analytics.example.com',
});

discord.py

create_dicolytics(bot, api_key="...", endpoint="https://analytics.example.com")

API 기본 URL입니다. SDK는 POST {endpoint}/v1/events로 이벤트를 전송합니다. 대부분의 사용자는 변경할 필요 없습니다.

참고

SDK는 HTTP 301/302 리다이렉트를 따르지 않습니다. 리다이렉트가 감지되면 전송이 영구 비활성화됩니다. 반드시 최종 URL을 직접 지정하세요.

disabledEvents

discord.js

createDicolytics(client, {
  apiKey: '...',
  disabledEvents: [
    'guild_snapshot',       // 서버별 스냅샷 비활성화
    'action_message_send',  // 메시지 전송 감지 비활성화
    'event_typing_start',   // 타이핑 이벤트 비활성화
  ],
});

discord.py

create_dicolytics(bot,
    api_key="...",
    disabled_events=[
        "guild_snapshot",       # 서버별 스냅샷 비활성화
        "action_message_send",  # 메시지 전송 감지 비활성화
        "event_typing_start",   # 타이핑 이벤트 비활성화
    ],
)

자동 수집 이벤트 중 특정 타입을 비활성화합니다. custom 타입은 비활성화할 수 없습니다 -- track()을 호출하지 않으면 됩니다.

비활성화 가능한 전체 이벤트 타입은 이벤트 레퍼런스를 참고하세요.

debug

discord.js

createDicolytics(client, {
  apiKey: '...',
  debug: true,
});

discord.py

create_dicolytics(bot, api_key="...", debug=True)

true로 설정하면 SDK 내부 동작, 옵션 검증 결과, 전송 상태 등을 console.warn으로 출력합니다. 프로덕션에서는 끄는 것을 권장합니다.

API 키 경고는 항상 출력

debug가 false여도 잘못된 API 키 경고(401 응답)는 1회 출력됩니다.

snapshotIntervalMs

discord.js

createDicolytics(client, {
  apiKey: '...',
  snapshotIntervalMs: 120_000, // 2분마다
});

discord.py

create_dicolytics(bot, api_key="...", snapshot_interval_ms=120_000)  # 2분마다

하트비트와 서버 스냅샷의 수집 주기를 밀리초로 지정합니다. 벽시계(wall-clock) 경계에 정렬되어 실행됩니다.

항목	값
기본값	60000 (60초)
최솟값	10000 (10초)

벽시계 정렬이란?

예를 들어 주기가 60초이고 봇이 12:00:37에 시작하면, 첫 스냅샷은 12:01:00에 실행됩니다. 이렇게 하면 여러 샤드/클러스터의 스냅샷 시각이 자연스럽게 정렬되어 집계가 정확해집니다.

flushIntervalMs

이벤트 큐를 서버로 전송하는 주기입니다. 대기 이벤트가 50개에 도달해도 즉시 플러시됩니다.

항목	값
기본값	5000 (5초)
최솟값	250 (0.25초)

참고

플러시 주기를 짧게 설정하면 네트워크 요청이 더 자주 발생합니다. 실시간성이 중요한 경우가 아니라면 기본값 5초를 유지하세요.

requestTimeoutMs

각 HTTP 요청의 타임아웃을 밀리초로 지정합니다. AbortController로 제어됩니다.

항목	값
기본값	10000 (10초)
최솟값	1000 (1초)

clusterId

discord.js

createDicolytics(client, {
  apiKey: '...',
  clusterId: 0,
});

discord.py

create_dicolytics(bot, api_key="...", cluster_id=0)

멀티클러스터 환경에서 각 클러스터를 구분하는 정수 식별자입니다 (0 ~ 32,767). 설정하면 모든 이벤트의 data.clusterId에 포함됩니다. 대시보드 상태 페이지에서 클러스터 > 샤드 계층 구조를 볼 수 있습니다.

자세한 내용은 멀티클러스터를 참고하세요.

참고

단일 프로세스로 봇을 운영한다면 이 옵션을 설정할 필요가 없습니다. shardId는 자동으로 포함됩니다.

autoCapturePromiseRejections

discord.js

createDicolytics(client, {
  apiKey: '...',
  autoCapturePromiseRejections: true,
});

discord.py

create_dicolytics(bot, api_key="...", auto_capture_exceptions=True)

true로 설정하면 프로세스의 unhandledRejection 이벤트를 감지하여 error 타입 이벤트로 자동 보고합니다.

참고

이 옵션은 오류를 보고만 할 뿐, 프로세스를 종료하거나 예외를 삼키지 않습니다. Node.js의 기본 동작에 영향을 주지 않습니다.

옵션 검증 규칙

상황	동작
apiKey 누락 또는 빈 문자열	TypeError 동기 예외
숫자 옵션이 최솟값 미만	기본값으로 대체 (debug: true일 때 경고 로그)
clusterId가 정수가 아니거나 범위 밖	무시 (debug: true일 때 경고 로그)
알 수 없는 옵션 키	무시

전체 예시

discord.js

import { Client, GatewayIntentBits } from 'discord.js';
import { createDicolytics } from '@dicolytics/discord.js';

const client = new Client({
  intents: [
    GatewayIntentBits.Guilds,
    GatewayIntentBits.GuildMessages,
    GatewayIntentBits.GuildMembers,
  ],
});

const analytics = createDicolytics(client, {
  apiKey: process.env.DICOLYTICS_KEY!,
  debug: process.env.NODE_ENV !== 'production',
  disabledEvents: ['event_typing_start'],
  snapshotIntervalMs: 60_000,
  flushIntervalMs: 5_000,
  requestTimeoutMs: 10_000,
  autoCapturePromiseRejections: true,
});

client.login(process.env.DISCORD_TOKEN);

discord.py

import os
import discord
from dicolytics import create_dicolytics

bot = discord.Bot()

analytics = create_dicolytics(bot,
    api_key=os.environ["DICOLYTICS_KEY"],
    debug=os.environ.get("ENV") != "production",
    disabled_events=["event_typing_start"],
    snapshot_interval_ms=60_000,
    flush_interval_ms=5_000,
    request_timeout_ms=10_000,
    auto_capture_exceptions=True,
)

bot.run(os.environ["DISCORD_TOKEN"])