메트릭과 차원
대시보드에서 사용하는 모든 메트릭(수치)과 차원(분석 기준)을 정리합니다.
메트릭
메트릭은 대시보드에서 볼 수 있는 수치입니다. 보고서의 KPI 카드, 차트 Y축, 탐색(Explore)의 메트릭 셀렉터에서 사용됩니다.
핵심 메트릭
| 메트릭 | 의미 | 계산 방식 |
|---|---|---|
interactions | 상호작용 건수 | 상호작용 이벤트의 count(*) |
actions | 작업 건수 | 작업 이벤트의 count(*) |
discord_events | 게이트웨이 이벤트 건수 | 이벤트 집계의 sum(data.count) |
events | 전체 이벤트 레코드 수 | 모든 이벤트의 count(*) |
custom_events | 커스텀 이벤트 건수 | event_type = custom인 이벤트의 count(*) |
errors | 오류 건수 | error + command_error 이벤트의 count(*) |
사용자/서버 메트릭
| 메트릭 | 의미 | 계산 방식 |
|---|---|---|
unique_users | 고유 사용자 수 | user_id의 HLL 근사 카운트 |
unique_guilds | 고유 서버 수 | guild_id의 HLL 근사 카운트 |
guild_count | 봇이 참여 중인 서버 수 | 스냅샷 테이블의 max(guildCount) |
member_reach | 도달 가능한 총 멤버 수 | 스냅샷 테이블의 sum(memberCount) |
HLL 근사치 (unique_users, unique_guilds)
고유 사용자 수와 고유 서버 수는 HyperLogLog(HLL) 알고리즘으로 계산됩니다. 정확한 COUNT(DISTINCT)가 아닌 근사치이며, 오차는 약 ±2%입니다. 대시보드에서 이 수치 옆에 "근사치" 뱃지가 표시됩니다.
HLL을 사용하는 이유는 성능입니다. 수백만 개의 고유 값을 정확히 세려면 막대한 메모리와 시간이 필요하지만, HLL은 고정된 소량의 메모리로 빠르게 추정합니다.
성능 메트릭
| 메트릭 | 의미 | 계산 방식 |
|---|---|---|
avg_latency | 평균 응답 지연 | 상호작용의 avg(data.latencyMs) (latencyMs > 0인 것만) |
p95_latency | 95번째 백분위 응답 지연 | 상호작용의 percentile_cont(0.95, data.latencyMs) |
음성/메시지 메트릭
| 메트릭 | 의미 | 계산 방식 |
|---|---|---|
voice_sessions | 음성 세션 수 | action_voice_session 이벤트의 count(*) |
voice_minutes | 음성 총 시간 (분) | sum(data.durationMs) / 60000 |
messages_sent | 봇 발신 메시지 수 | action_message_send 이벤트의 count(*) |
파생(derived) 메트릭
| 메트릭 | 의미 | 데이터 출처 |
|---|---|---|
guild_count | 봇 전체 서버 수 | heartbeat 스냅샷의 data.guildCount 합계 |
member_reach | 도달 멤버 수 | guild_snapshot의 data.memberCount 합계 |
guild_count vs unique_guilds
두 메트릭은 다른 것을 측정합니다.
guild_count: 현재 봇이 참여 중인 서버의 총 수. 스냅샷에서 가져옵니다. 해당 기간에 상호작용이 없어도 카운트됩니다.unique_guilds: 해당 기간에 이벤트가 발생한 서버의 고유 수. HLL 근사치입니다. 활동이 없는 서버는 포함되지 않습니다.
차원
차원은 메트릭을 나누는 기준입니다. 탐색(Explore)의 차원 셀렉터, 보고서의 필터에서 사용됩니다.
| 차원 | 의미 | 사용 예시 |
|---|---|---|
date | 날짜 | 일별 추이 차트 |
hour | 시간 | 시간대별 히트맵 |
event_type | 이벤트 타입 | 타입별 건수 비교 |
command | 명령어/customId | 명령어 랭킹 |
interaction_kind | 상호작용 종류 | slash/button/select 등 구분 |
guild_id | 서버 ID | 서버별 활동 비교 |
user_id | 사용자 ID | 사용자별 활동 비교 |
channel_id | 채널 ID | 채널별 활동 비교 |
error_fingerprint | 오류 지문 | 동일 오류 그룹화 |
custom_event_name | 커스텀 이벤트 이름 | 커스텀 이벤트별 구분 |
shard_id | 샤드 ID | 샤드별 분포 |
success | 성공 여부 | 성공/실패 비율 |
시간 차원과 비시간 차원
- 시간 차원 (
date,hour)을 선택하면 라인 차트(시계열)로 표시됩니다. - 비시간 차원 (
command,guild_id등)을 선택하면 가로 막대 차트로 표시됩니다.
대시보드에서 수치 읽는 법
KPI 카드
보고서 상단의 KPI 카드는 선택한 기간의 메트릭 값과 **이전 기간 대비 변화율(delta %)**을 표시합니다.
상호작용 고유 사용자 평균 지연
12,450 1,823 (근사치) 42ms
+15.3% +8.7% -12.1%- 양수(+): 이전 기간보다 증가
- 음수(-): 이전 기간보다 감소
- 이전 기간은 선택한 기간과 동일한 길이입니다 (예: 최근 7일 → 그 전 7일)
근사치 뱃지
unique_users와 unique_guilds 메트릭 옆에는 "근사치" 뱃지가 표시됩니다. 이 수치는 HLL 알고리즘으로 추정된 값이므로 ±2% 오차가 있을 수 있습니다.
기간 비교
기간 선택기에서 두 기간을 선택하면 KPI 카드에 두 기간의 수치가 나란히 표시됩니다. 차트에서는 현재 기간은 실선, 이전 기간은 점선으로 비교할 수 있습니다.
관련 문서
- 수집 체계 -- 메트릭의 원본 데이터가 어떻게 수집되는지
- 탐색(Explore) -- 메트릭과 차원으로 커스텀 쿼리 만들기
- 홈 개요 -- KPI 카드와 차트 구성