Analytics Module

@zumito-team/analytics-module provides configurable server analytics for your Zumito bot. Tracks messages, members, voice activity, and command usage with per-guild granularity. Includes optional web dashboard pages with Chart.js for both the admin and user panels.

Installation

npm install @zumito-team/analytics-module

Add to your zumito.config.ts:

Modules (recommended)

import { defineConfig } from 'zumito-framework';
import { analyticsModule } from '@zumito-team/analytics-module';

export default defineConfig({
    modules: [
        analyticsModule({
            defaultTrackCommandPerformance: true,
        }),
    ]
});

Or with plain string:

import { defineConfig } from 'zumito-framework';

export default defineConfig({
    modules: ['@zumito-team/analytics-module']
});

Legacy bundles

{
    path: path.join(__dirname, "node_modules", "@zumito-team", "analytics-module", "dist"),
}

What it provides

AnalyticsCollector service

Available via ServiceContainer.getService(AnalyticsCollector). Other modules can query analytics data.

| Method | Description | |---|---| | recordMessage(guildId) | Track a message sent in a guild | | recordMemberJoin(guildId) | Track a member joining | | recordMemberLeave(guildId) | Track a member leaving | | recordVoiceJoin(guildId, channelId, userId) | Track voice channel join | | recordVoiceLeave(guildId, channelId, userId) | Track voice channel leave (auto-calculates duration) | | recordCommand(payload) | Track a command execution (success/failure + execution time) | | recordMemberCount(guildId, count) | Store current member count snapshot | | getGuildStats(guildId, daysBack) | Get daily stats for a guild | | getGlobalStatsSummary(daysBack) | Get aggregated global stats | | getGuildGrowth(daysBack) | Get active guilds per day | | getMessagesPerDay(daysBack) | Get messages per day (global) | | getCommandsPerDay(guildId, daysBack) | Get commands per day | | getTopCommands(guildId, daysBack, limit) | Get most used commands | | getSlowestCommands(guildId, daysBack, limit) | Get commands sorted by avg execution time | | getVoiceChannelStats(guildId, daysBack) | Get per-channel voice stats | | getConfig(guildId) | Get guild analytics configuration | | updateConfig(guildId, partial) | Update guild analytics configuration | | runCleanup() | Run data retention cleanup manually | | startCleanupScheduler() | Start automatic cleanup scheduler | | stopCleanupScheduler() | Stop automatic cleanup scheduler | | clearVoiceSessions() | Clear in-memory voice session tracking |

Events tracked

| Event | Source | Description | |---|---|---| | messageCreate | discord | Message count per guild | | guildMemberAdd | discord | Join count + member snapshot | | guildMemberRemove | discord | Leave count + member snapshot | | voiceStateUpdate | discord | Voice activity (minutes) per guild/channel | | commandExecuted | framework | Command usage + execution time |

Commands

| Command | Type | Description | |---|---|---| | /stats | Slash + Prefix | Shows server stats embed (last 7 days) | | /analytics-config | Slash + Prefix (admin-only) | View/toggle analytics settings per guild |

Admin Panel

• /admin/analytics — Global bot statistics: guild growth, messages/day, commands/day, top commands, slowest commands
• Date range selector: 7 / 30 / 90 days
• Chart.js visualizations (line, bar, horizontal bar charts)

User Panel

• /panel/:guildId/analytics — Per-server statistics: messages, joins/leaves, voice activity, commands, top commands
• If track_command_performance enabled: slowest commands chart
• If track_per_channel_voice enabled: per-channel voice breakdown
• Date range selector: 7 / 30 / 90 days

Configuration

Global defaults

Import and configure global defaults before the module initializes:

import { AnalyticsModuleConfig } from '@zumito-team/analytics-module';

AnalyticsModuleConfig.configure({
    defaultRetentionDays: 90,
    cleanupIntervalHours: 24,
    defaultTrackMessages: true,
    defaultTrackVoice: true,
    defaultTrackMembers: true,
    defaultTrackCommands: true,
    defaultTrackCommandPerformance: false,
    defaultTrackPerChannelVoice: false,
});

| Setting | Default | Description | |---|---|---| | defaultRetentionDays | 90 | Days to keep data before auto-deletion | | cleanupIntervalHours | 24 | How often cleanup runs | | defaultTrackMessages | true | Track messages by default | | defaultTrackVoice | true | Track voice activity by default | | defaultTrackMembers | true | Track joins/leaves by default | | defaultTrackCommands | true | Track command usage by default | | defaultTrackCommandPerformance | false | Track execution time per command | | defaultTrackPerChannelVoice | false | Track per-channel voice stats |

Per-guild configuration

Use /analytics-config or the public API:

const collector = ServiceContainer.getService(AnalyticsCollector);
await collector.updateConfig(guildId, {
    enabled: true,
    track_commands: true,
    track_command_performance: true,  // enable execution time tracking
    retention_days: 180,              // 6 months for premium
});

Per-guild DB fields:

| Field | Type | Default | |---|---|---| | guild_id | string | Primary key | | enabled | boolean | true | | track_messages | boolean | true | | track_voice | boolean | true | | track_members | boolean | true | | track_commands | boolean | true | | track_command_performance | boolean | false | | track_per_channel_voice | boolean | false | | retention_days | number | Globally configured default (90) | | public_stats_page | boolean | false |

Extending

Consuming AnalyticsCollector in other modules

import { AnalyticsCollector, type CommandExecutedPayload } from '@zumito-team/analytics-module';
import { ServiceContainer } from 'zumito-framework';

const collector = ServiceContainer.getService(AnalyticsCollector) as AnalyticsCollector;

// Query stats
const stats = await collector.getGuildStats(guildId, 30);

// Get top commands
const top = await collector.getTopCommands(null, 7, 5);

// Get global summary
const summary = await collector.getGlobalStatsSummary(7);

Tracking custom events

// Track custom event as a message
await collector.recordMessage(guildId);

// Track a custom metric directly via DB
const db = ServiceContainer.getService(DatabaseManager);
const repo = db.getRepository(GuildDailyStats);
await repo.insert({ id: `${guildId}_${today()}`, guild_id: guildId, date: today(), message_count: 1 });

Premium integration

Set a higher retention for premium guilds:

// In your premium module
await collector.updateConfig(guildId, { retention_days: 180 });

Data models

GuildDailyStats

Per-guild daily aggregate: id = {guild_id}_{date}

| Field | Type | |---|---| | id | string (PK) | | guild_id | string | | date | string (YYYY-MM-DD) | | message_count | number | | join_count | number | | leave_count | number | | voice_minutes | number | | command_count | number | | member_count | number |

CommandDailyStats

Per-command daily stats: id = {guild_id}_{command_name}_{date}

| Field | Type | |---|---| | id | string (PK) | | guild_id | string | | command_name | string | | date | string (YYYY-MM-DD) | | usage_count | number | | total_execution_time_ms | number | | error_count | number |

VoiceChannelDailyStats

Per-channel voice stats: id = {guild_id}_{channel_id}_{date}

| Field | Type | |---|---| | id | string (PK) | | guild_id | string | | channel_id | string | | date | string (YYYY-MM-DD) | | total_minutes | number | | unique_users | number |

Dependencies

• zumito-framework
• ejs — Template rendering
• @zumito-team/admin-module — Optional admin panel integration
• @zumito-team/user-panel-module — Optional user panel integration

Related modules

• Admin Module — Panel where global bot stats appear
• User Panel — Panel where per-server stats appear
• Logger — Complementary event logging