Skip to main content

​
Overview

The GuildQueueStatistics class provides comprehensive statistics and metrics about a guild queue’s state, including latency, playback status, track counts, and memory usage. It is accessible via queue.stats.

​
Constructor

new GuildQueueStatistics<Meta = any>(queue: GuildQueue<Meta>)
​
queue
GuildQueue<Meta>
required
The guild queue instance to generate statistics for

​
Properties

​
queue
GuildQueue<Meta>
The guild queue instance associated with this statistics manager

​
Methods

​
generate()

Generates a comprehensive statistics snapshot of the current queue state. 
stats.generate(): GuildQueueStatisticsMetadata
​
returns
GuildQueueStatisticsMetadata
Complete statistics object containing various metrics
Example: 
const stats = queue.stats.generate();

console.log('Queue Statistics:');
console.log('- Event Loop Lag:', stats.latency.eventLoop, 'ms');
console.log('- Voice Ping:', stats.latency.voiceConnection, 'ms');
console.log('- Playing:', stats.status.playing);
console.log('- Paused:', stats.status.paused);
console.log('- Tracks in Queue:', stats.tracksCount);
console.log('- History Size:', stats.historySize);
console.log('- Listeners:', stats.listeners);
console.log('- Memory (Heap Used):', Math.round(stats.memoryUsage.heapUsed / 1024 / 1024), 'MB');
console.log('- Node Version:', stats.versions.node);
console.log('- Player Version:', stats.versions.player);

​
Usage Examples

​
Display Queue Statistics

import { EmbedBuilder } from 'discord.js';
import { useQueue } from 'discord-player';

export async function showStats(interaction) {
  const queue = useQueue(interaction.guildId);
  
  if (!queue) {
    return interaction.reply('No active queue!');
  }
  
  const stats = queue.stats.generate();
  
  const embed = new EmbedBuilder()
    .setTitle('Queue Statistics')
    .setColor('#0099ff')
    .addFields(
      {
        name: 'Latency',
        value: [
          `Event Loop: ${stats.latency.eventLoop}ms`,
          `Voice Connection: ${stats.latency.voiceConnection}ms`
        ].join('\n'),
        inline: true
      },
      {
        name: 'Status',
        value: [
          `Playing: ${stats.status.playing ? '✅' : '❌'}`,
          `Paused: ${stats.status.paused ? '✅' : '❌'}`,
          `Buffering: ${stats.status.buffering ? '✅' : '❌'}`
        ].join('\n'),
        inline: true
      },
      {
        name: 'Queue Info',
        value: [
          `Tracks: ${stats.tracksCount}`,
          `History: ${stats.historySize}`,
          `Listeners: ${stats.listeners}`
        ].join('\n'),
        inline: true
      },
      {
        name: 'Memory Usage',
        value: [
          `Heap: ${Math.round(stats.memoryUsage.heapUsed / 1024 / 1024)}MB / ${Math.round(stats.memoryUsage.heapTotal / 1024 / 1024)}MB`,
          `RSS: ${Math.round(stats.memoryUsage.rss / 1024 / 1024)}MB`
        ].join('\n'),
        inline: false
      },
      {
        name: 'Versions',
        value: [
          `Node.js: ${stats.versions.node}`,
          `Discord Player: ${stats.versions.player}`,
          `Extractors: ${stats.extractors}`
        ].join('\n'),
        inline: false
      }
    );
  
  await interaction.reply({ embeds: [embed] });
}

​
Monitor Performance

export function monitorQueuePerformance(queue) {
  setInterval(() => {
    const stats = queue.stats.generate();
    
    // Check for high event loop lag
    if (stats.latency.eventLoop > 100) {
      console.warn(`High event loop lag detected: ${stats.latency.eventLoop}ms`);
    }
    
    // Check for high voice connection latency
    if (stats.latency.voiceConnection > 200) {
      console.warn(`High voice latency detected: ${stats.latency.voiceConnection}ms`);
    }
    
    // Check memory usage
    const heapUsedMB = stats.memoryUsage.heapUsed / 1024 / 1024;
    if (heapUsedMB > 500) {
      console.warn(`High memory usage detected: ${Math.round(heapUsedMB)}MB`);
    }
  }, 30000); // Check every 30 seconds
}

​
Health Check Endpoint

import express from 'express';
import { useMainPlayer } from 'discord-player';

const app = express();
const player = useMainPlayer();

app.get('/health/queue/:guildId', (req, res) => {
  const queue = player.nodes.get(req.params.guildId);
  
  if (!queue) {
    return res.status(404).json({ error: 'Queue not found' });
  }
  
  const stats = queue.stats.generate();
  
  // Determine health status
  const isHealthy = 
    stats.latency.eventLoop < 100 &&
    stats.latency.voiceConnection < 200 &&
    !stats.status.buffering;
  
  res.json({
    healthy: isHealthy,
    statistics: stats
  });
});

​
Log Statistics

export function logQueueStats(queue) {
  const stats = queue.stats.generate();
  
  const logData = {
    timestamp: new Date().toISOString(),
    guild: queue.guild.name,
    latency: stats.latency,
    status: stats.status,
    tracks: stats.tracksCount,
    history: stats.historySize,
    listeners: stats.listeners,
    memory: {
      heapUsed: Math.round(stats.memoryUsage.heapUsed / 1024 / 1024),
      heapTotal: Math.round(stats.memoryUsage.heapTotal / 1024 / 1024)
    }
  };
  
  console.log('Queue Stats:', JSON.stringify(logData, null, 2));
}

​
Performance Dashboard

import { useQueue } from 'discord-player';

export async function showDashboard(interaction) {
  const queue = useQueue(interaction.guildId);
  
  if (!queue) {
    return interaction.reply('No active queue!');
  }
  
  const stats = queue.stats.generate();
  
  // Create performance indicators
  const latencyIndicator = stats.latency.voiceConnection < 100 ? '🟢' : 
                          stats.latency.voiceConnection < 200 ? '🟡' : '🔴';
  
  const eventLoopIndicator = stats.latency.eventLoop < 50 ? '🟢' : 
                            stats.latency.eventLoop < 100 ? '🟡' : '🔴';
  
  const memoryPercent = (stats.memoryUsage.heapUsed / stats.memoryUsage.heapTotal) * 100;
  const memoryIndicator = memoryPercent < 70 ? '🟢' : 
                         memoryPercent < 90 ? '🟡' : '🔴';
  
  const dashboard = [
    '**Performance Dashboard**',
    '',
    `${latencyIndicator} Voice Latency: ${stats.latency.voiceConnection}ms`,
    `${eventLoopIndicator} Event Loop: ${stats.latency.eventLoop}ms`,
    `${memoryIndicator} Memory: ${Math.round(memoryPercent)}% (${Math.round(stats.memoryUsage.heapUsed / 1024 / 1024)}MB)`,
    '',
    '**Queue Status**',
    `Playing: ${stats.status.playing ? '✅' : '❌'}`,
    `Tracks: ${stats.tracksCount}`,
    `Listeners: ${stats.listeners}`,
    '',
    `Node.js ${stats.versions.node} | Discord Player ${stats.versions.player}`
  ].join('\n');
  
  await interaction.reply(dashboard);
}

​
Notes

  • Statistics are generated on-demand and represent a snapshot at the time of the call
  • Event loop lag is measured by the player instance and shared across all queues
  • Voice connection latency represents the WebSocket ping to Discord
  • Memory usage reflects the entire Node.js process, not just the queue
  • The listeners count excludes bots
  • Use statistics for monitoring, debugging, and performance optimization
  • Consider caching statistics if calling generate() frequently to avoid performance overhead

Build docs developers (and LLMs) love

Get started for freeTalk to us