> ## Documentation Index
> Fetch the complete documentation index at: https://docs.volvox.bot/llms.txt
> Use this file to discover all available pages before exploring further.
# Real-Time Discord Server Analytics with Live Insight
> Live Insight tracks Discord server activity in real time with charts for messages, active members, command usage, response times, and uptime.
# Analytics (Live Insight)
Live Insight gives you a real-time view into your server's health and activity. The Overview dashboard groups analytics into Messages, Voice Tracking, and Community Engagement sub-tabs.
## What it does
* **Message volume** — Track messages over time by channel and member
* **Engagement metrics** — Active users, average messages per user, and lifetime reaction totals
* **Activity Over Time** — Compare message volume with voice minutes on a single graph with its own range picker (1d, 7d, 14d, 30d, 60d, 90d, 6 month, 1 year, or Custom)
* **Weekly Activity Heatmap** — Message density by day of week and hour, with weekday labels that follow your browser locale
* **Voice sessions** — Tracked joins, active sessions, unique participants, total voice time, average duration, top voice channels, and recent session activity
* **AI usage breakdown** — Per-model request counts, prompt and completion tokens, and estimated spend in USD
* **Recent events feed** — The 10 most recent messages and slash command uses, sourced from your live conversation history
* **Bot usage** — How often members run commands and start AI conversations
* **Performance** — Bot response times, AI triage phase latency, and resource usage
* **Server health** — Overall server health score
## Settings location
Analytics does not have a dedicated Settings tab. Use the dashboard controls on **Dashboard -> Analytics** for date ranges and exports.
Voice session collection is controlled by **Settings -> Onboarding & Growth -> Engagement -> Voice Session Tracking**. It is on by default, but it only records sessions while the top-level **Engagement** setting is enabled.
Voice reputation rewards are configured separately under **Settings -> Onboarding & Growth -> Reputation -> Voice XP**, where you can enable or disable voice XP and set whole XP per minute.
Related AI triage performance settings are in **Settings -> AI & Automation -> Triage -> Performance**.
## How to use
1. Open the dashboard -> **Overview** for your server snapshot and analytics sub-tabs.
2. Use **Messages** for message volume, top channels, AI usage, and command telemetry.
3. Use **Voice Tracking** for voice joins, duration, live rooms, top channels, and recent sessions.
4. Use **Community Engagement** for active members, reaction totals, XP economy, and activity heatmaps.
5. Use the **Activity Graph** range buttons on the Messages sub-tab to zoom in or out on community activity.
6. Use the date range picker to focus on specific periods.
7. Check **Performance** for technical health metrics.
Analytics queries support a custom range of up to 366 days. Rolling presets cover everything from the last 24 hours up to the last year.
Dashboard analytics dates, times, chart labels, and heatmap buckets display in the viewer's local browser time. Exports keep ISO timestamps where a machine-readable value is required.
## Activity graph
The Activity Graph on the **Messages** sub-tab plots community message volume over time so you can spot growth, lulls, and traffic spikes at a glance. The chart shares its range with the rest of the dashboard, so switching the range here also updates the surrounding KPIs and breakdowns.
### Select a range
Use the range buttons above the chart to switch between rolling windows or set a custom range:
| Button | Window |
| --------- | ------------------------------------------------- |
| `1d` | Last 24 hours |
| `7d` | Last 7 days |
| `14d` | Last 14 days |
| `30d` | Last 30 days |
| `60d` | Last 60 days |
| `90d` | Last 90 days |
| `6 month` | Last 183 days |
| `1 year` | Last 365 days |
| `Custom` | Select exact start and end dates (up to 366 days) |
Select **Custom** to reveal date inputs, select a **Start** and **End** date, then select **Apply** to load the range. The Apply button stays disabled until both dates are filled in and **Start** is on or before **End**. The currently selected range button stays highlighted so you always know which window you're looking at.
The dashboard remembers your selected range while you navigate between sub-tabs, so you can compare voice and engagement metrics across the same window without re-selecting it.
## Share or bookmark a sub-tab
The Overview dashboard tracks the active sub-tab in the URL through a `tab` query parameter. You can bookmark, refresh, or share a direct link to the view you want a teammate to land on.
| Sub-tab | URL |
| -------------------- | -------------------------- |
| Messages | `/dashboard?tab=messages` |
| Voice Tracking | `/dashboard?tab=voice` |
| Community Engagement | `/dashboard?tab=community` |
When you select a sub-tab from the dashboard sidebar, the URL updates in place without a full page reload. Open `/dashboard` without a `tab` parameter to land on **Messages** by default.
## Messages dashboard
The **Messages** sub-tab is the default Analytics view at `/dashboard?tab=messages`. It shows message volume, active users, average messages per user, channel activity, AI usage, recent events, command usage, and dashboard-wide date range controls.
Use this tab when you need the quick server pulse: who is talking, where activity is happening, which commands are being used, and whether AI usage or spend changed during the selected range.
## Voice tracking dashboard
The **Voice Tracking** sub-tab lives at `/dashboard?tab=voice`. It focuses on voice joins, active sessions, total voice time, average duration, top voice channels, and recent session activity.
Use it to spot active voice rooms, review participation patterns, and confirm whether voice tracking is producing fresh session data.
## Community engagement dashboard
The **Community Engagement** sub-tab lives at `/dashboard?tab=community`. It shows active members, reaction totals, XP economy signals, weekly activity heatmaps, and the Activity Over Time graph for messages and voice minutes.
Use it for longer-term engagement review, activity rhythm, and XP/community health checks.
## Available metrics
| Metric | Description |
| --------------------------- | ----------------------------------------------------------------- |
| Messages per day | Total message count over time |
| Active users | Unique members who sent messages in the selected range |
| Avg messages per user | Mean messages per active user |
| Lifetime reactions given | All-time reactions sent by tracked members in the server |
| Lifetime reactions received | All-time reactions received by tracked members in the server |
| Voice sessions | Voice channel sessions started in the selected range |
| Active voice sessions | Voice sessions still open when analytics last refreshed |
| Voice time | Total and average voice duration from tracked sessions |
| Top voice channels | Voice rooms ranked by session count and total duration |
| Recent voice sessions | Latest voice sessions with duration and active status |
| AI usage by model | Requests, prompt and completion tokens, and cost in USD per model |
| Recent events | Latest messages and slash command uses across tracked channels |
| Command usage | Bot command frequency |
| Response time | Average bot response latency |
| Triage latency | Recent AI triage evaluation timing by outcome and phase |
| Uptime | Bot and service uptime percentage |
AI usage and cost figures appear when the bot has recorded usage data for the selected range. If no usage data exists, the dashboard reports the AI usage source as unavailable instead of showing zeros.
## Activity over time
The **Activity Over Time** graph on the **Community Engagement** tab plots messages and voice minutes side by side. You can see when chat and voice spike together, or when one carries the server while the other goes quiet.
* **Messages** plot in the primary Volvox green, stacked behind voice
* **Voice minutes** plot in neon orange on top
* Hover any point to see the bucket label, message count, and voice time formatted as `Hh Mm`
* Buckets switch to hourly resolution for **1d** ranges and daily resolution everywhere else
### Range presets
The graph has its own range picker, separate from the dashboard-wide date range:
| Preset | Window |
| --------- | --------------------------------------------- |
| `1d` | Last 24 hours, hourly buckets |
| `7d` | Last 7 days |
| `14d` | Last 14 days |
| `30d` | Last 30 days |
| `60d` | Last 60 days |
| `90d` | Last 90 days |
| `6 month` | Last 6 months |
| `1 year` | Last 12 months |
| `Custom` | Select any start and end date, up to 366 days |
Selecting **Custom** opens a date picker. Ranges longer than 366 days are clamped to keep the graph readable.
## Triage latency
The **Triage latency** widget on the Performance sub-tab breaks down recent AI triage evaluations so you can see where time is spent before the bot replies. Each evaluation runs through several internal phases, including context fetch, classification, memory lookup, and response generation. The widget surfaces the timing for each phase.
Use it when:
* AI replies feel slow and you want to see which phase is the bottleneck
* You're tuning `memoryTimeoutMs` or other triage performance knobs in **Settings -> AI & Automation -> Triage -> Performance**
* You want to confirm mem0 cache hits are landing instead of paying full API latency on every message
### Summary cards
| Card | What it shows |
| ------------ | ----------------------------------------------------------------------------------- |
| Triage p95 | 95th percentile total triage time across recent evaluations |
| Classify Avg | Average classifier phase time, with the latest provider call duration |
| Memory Avg | Average time spent waiting on user memory, with cache hits on the latest evaluation |
| Respond Avg | Average responder phase time, with the latest provider call duration |
### Phase averages chart
The bar chart plots the average duration of each triage phase across recent samples:
| Phase | Description |
| ------------- | ----------------------------------------------------------------- |
| Budget | Per-guild budget and rate-limit checks |
| Context | Loading recent channel messages for the prompt |
| Classify Prep | Building the classifier prompt |
| Classify | Classifier model call (decides whether to reply, search, or skip) |
| Memory | Waiting on mem0 user memory lookup (capped by `memoryTimeoutMs`) |
| Respond Prep | Building the responder prompt |
| Respond | Responder model call that generates the reply |
| Stats | Recording usage and analytics for the evaluation |
| Discord | Sending the final reply through the Discord API |
### Recent evaluations table
The recent evaluations panel lists the last 20 triage runs with:
* **Time** — When the evaluation finished
* **Outcome** — Whether triage replied, skipped, or hit an error, plus the classification or skip reason
* **Slowest** — The phase that took the longest in that evaluation
* **Total** — End-to-end triage duration in milliseconds
* **Memory** — Memory wait time, cache hits, and live mem0 API searches
Outcome chips above the table show the count of each outcome (for example `replied: 12`, `skipped: 7`) so you can tell at a glance how often the bot is choosing to reply.
The widget only shows data once the bot has run triage in your server. If you see "No triage samples yet", trigger an AI conversation in any channel where triage is enabled and refresh the page.
## Performance dashboard
The operator-only **Performance** page at `/dashboard/performance` shows runtime health across the deployment: bot health, heap and RSS memory trends, CPU utilization, uptime, average and percentile latency, and recent AI triage phase timings.
Only global admins can see this page. Server owners and server admins keep using the server-scoped Analytics tabs unless they also operate the deployment.
## AI usage ops dashboard
The operator-only **AI Usage** page at `/dashboard/ai-usage` shows deployment-wide AI usage across every server. It is visible only to global admins configured through `BOT_OWNER_IDS`.
Use **System Ops -> AI Usage** when you need to inspect:
* input, output, and total tokens
* cache read and cache creation tokens, including cache read/write rates
* estimated AI cost in USD
* average latency, p95 latency, and generated tokens per second
* provider, model, and request-type comparisons
* top servers by AI usage, with server names when the bot can resolve them
* recent expensive or slow AI requests
The page supports `24h`, `7d`, `30d`, and `90d` ranges plus provider, model, and request-type filters for `classify`, `respond`, `safety`, and `automod` calls. It uses the global `ai_usage` telemetry table, so it is meant for deployment operators rather than per-server admins.
Server-scoped AI usage remains on **Dashboard -> Analytics -> Messages**. The AI Usage ops page is global and may expose cross-server usage patterns, so keep `BOT_OWNER_IDS` restricted to trusted operators.
## Weekly activity heatmap
The **Weekly Activity Heatmap** shows message density across day of week and hour of day, using the same Community Engagement range as the rest of that tab. Weekday labels follow your browser locale. When the selected range is a week or shorter, each row also shows the matching calendar date so you can tell `Mon 12 May` apart from `Mon 19 May` at a glance.