mertricServices.js

Go to the documentation of this file.

/**
 * @file Agent Metrics Data Access Service
 * @description
 * Provides database query functions for retrieving agent performance metrics data.
 * This module serves as the data access layer for the agent_metrics table, supporting
 * both real-time monitoring (latest metrics) and historical analysis (time-series data
 * for graphs and trend analysis).
 *
 * Key features:
 * - **Latest metrics**: Retrieve most recent performance snapshot for an agent
 * - **Historical data**: Time-series queries for graphing and analysis
 * - **Configurable time windows**: Historical queries support custom day ranges
 *
 * Typical use cases:
 * - Dashboard widgets showing current agent status (CPU, memory, disk, network)
 * - Performance graphs over time (30-day default, configurable)
 * - Alerting based on metric thresholds
 * - Capacity planning and trend analysis
 *
 * Database schema:
 * - Table: `agent_metrics`
 * - Key columns: agent_uuid, ts (timestamp), cpu_percent, memory_percent, disk_percent, network_io
 * - Indexed on: agent_uuid, ts for efficient time-series queries
 * @module services/metricServices
 * @requires ./db - PostgreSQL database pool
 * @note This file is misnamed as "mertricServices.js" (typo) but kept for compatibility
 */
 
const pool = require('./db');
 
/**
 * Retrieves the latest (most recent) metrics snapshot for a specific agent.
 *
 * Returns the single most recent metrics row from the agent_metrics table, containing
 * performance data like CPU usage, memory usage, disk space, network I/O, and timestamp.
 * Used for real-time agent status displays and dashboards.
 * @async
 * @function getLatestAgentMetrics
 * @param {string} agent_uuid - Unique identifier of the agent (UUID format)
 * @returns {Promise<object | null>} Latest metrics object with columns from agent_metrics table, or null if no metrics found
 * @example
 * const latest = await getLatestAgentMetrics('550e8400-e29b-41d4-a716-446655440000');
 * console.log(latest.cpu_percent); // e.g., 45.2
 * console.log(latest.memory_percent); // e.g., 78.5
 * console.log(latest.ts); // e.g., 2025-01-15T10:30:00.000Z
 */
 
// Latest metrics (1 row)
/**
 *
 * @param agent_uuid
 */
async function getLatestAgentMetrics(agent_uuid) {
  const res = await pool.query(
    `SELECT *
     FROM agent_metrics
     WHERE agent_uuid = $1
     ORDER BY ts DESC
     LIMIT 1`,
    [agent_uuid]
  );
 
  return res.rows[0] || null;
}
 
/**
 * Retrieves historical metrics data for a specific agent within a time window.
 *
 * Returns time-series array of all metrics data points within the specified number of
 * days, ordered chronologically (oldest to newest). Used for generating performance
 * graphs, trend analysis, and historical reporting. Default 30-day window provides
 * sufficient data for monthly performance review.
 * @async
 * @function getAgentMetricsHistory
 * @param {string} agent_uuid - Unique identifier of the agent (UUID format)
 * @param {number} [days=30] - Number of days of historical data to retrieve (default: 30)
 * @returns {Promise<object[]>} Array of metrics objects ordered by timestamp (ascending), empty array if no data
 * @example
 * // Get 30 days of history (default)
 * const history = await getAgentMetricsHistory('550e8400-e29b-41d4-a716-446655440000');
 * console.log(history.length); // e.g., 43200 (30 days * 24 hours * 60 minutes if sampled per minute)
 * @example
 * // Get last 7 days only
 * const weekHistory = await getAgentMetricsHistory('550e8400-e29b-41d4-a716-446655440000', 7);
 * // Use for graphing: weekHistory.map(m => ({ time: m.ts, cpu: m.cpu_percent }))
 */
 
// Historical metrics (graph)
/**
 *
 * @param agent_uuid
 * @param days
 */
async function getAgentMetricsHistory(agent_uuid, days = 30) {
  const res = await pool.query(
    `SELECT *
     FROM agent_metrics
     WHERE agent_uuid = $1
     AND ts > NOW() - INTERVAL '${days} days'
     ORDER BY ts ASC`,
    [agent_uuid]
  );
 
  return res.rows;
}
 
module.exports = {
  getLatestAgentMetrics,
  getAgentMetricsHistory
};