System Utility

Overview

The System Utility feature provides server-side diagnostics and performance monitoring endpoints. Administrators can inspect memory usage, CPU performance, disk space, database health, and run profiling/debugging tools. Essential for monitoring production deployments and troubleshooting performance issues.

---

Key Features

• Performance Profiling: CPU profiling and heap analysis
• Debugging Tools: Node.js inspector integration
• System Metrics: Real-time memory, CPU, disk, database monitoring
• Health Monitoring: Comprehensive health checks and diagnostics
• Database Analysis: Database statistics and connection verification
• Global Admin Only: All endpoints require global admin permissions

---

Database Collections

Collection	Purpose
countly.plugins	Used only by /o/system/dbcheck as a lightweight connectivity probe ({ _id: "plugins" }).
No dedicated System Utility feature collections	Most endpoints read host/runtime state and do not persist feature-specific data in MongoDB.

Configuration & Settings

System utilities use core configuration. See api/config.js for settings.

API Endpoints

Inspector (Debugging)

Endpoint	Method	Purpose
Start Inspector	POST	Enable Node.js inspector debugging
Stop Inspector	POST	Disable Node.js inspector

Profiler (Performance Analysis)

Endpoint	Method	Purpose
Start Profiler	POST	Start CPU/memory profiling
Stop Profiler	POST	Stop profiling and save results
Take Heap Snapshot	GET	Capture memory heap snapshot
List Profiler Files	GET	List available profiler results
Download Profiler Data	GET	Download all profiler files

System Metrics (Monitoring)

Endpoint	Method	Purpose
Get Memory Stats	GET	System and process memory usage
Get Disk Stats	GET	Disk space and utilization
Get CPU Stats	GET	CPU usage and performance
Get Database Stats	GET	Database disk usage
Get Overall Stats	GET	Combined system statistics
Health Check	GET	System health status
Database Check	GET	Database connection status

---

Data Structures

Memory Response

{
  "overall": {
    "total": "15.5 GB",
    "free": "4.2 GB",
    "used": "11.3 GB",
    "usage": "72.9%"
  },
  "process": {
    "heap_used": "85 MB",
    "heap_total": "128 MB",
    "external": "2.1 MB"
  },
  "details": [
    {
      "id": "Mem",
      "total": "16384",
      "free": "4096",
      "used": "12288",
      "usage": "75%"
    }
  ]
}

Disk Response

{
  "overall": {
    "total": "500 GB",
    "free": "150 GB",
    "used": "350 GB",
    "usage": "70%"
  },
  "details": [
    {
      "id": "/",
      "total": "500 GB",
      "free": "150 GB",
      "used": "350 GB",
      "usage": "70%"
    }
  ]
}

CPU Response

{
  "overall": {
    "usage": "45.2%",
    "cores": 8
  },
  "cores": [
    {
      "id": "cpu0",
      "usage": "42.1%"
    },
    {
      "id": "cpu1",
      "usage": "48.3%"
    }
  ]
}

---

Authentication

All endpoints require:

• API key with global admin permissions
• Cannot be executed by regular users or app-level admins
• Restricted to server administrator role

Permission structure:

global-admin validation(params, () => {
  // Execute endpoint logic
});

---

Common Use Cases

1. Production Monitoring

Monitor server resources in real-time to ensure healthy operation

Related Endpoints:

• Health Check
• Get Memory Stats
• Get CPU Stats

2. Performance Troubleshooting

Identify memory leaks and CPU bottlenecks

Related Endpoints:

• Start Profiler
• Take Heap Snapshot
• Stop Profiler

3. Remote Debugging

Debug Node.js processes on production servers

Related Endpoints:

• Start Inspector
• Stop Inspector

4. Capacity Planning

Track disk and resource usage trends

Related Endpoints:

• Get Disk Stats
• Get Database Stats
• Get Overall Stats

5. Health Verification

Verify database connectivity and system health

Related Endpoints:

• Database Check
• Health Check

---

Technical Specifications

Inspector

Port: Configurable via masterInspectorPort (default: 9229)

Runtime: 2 hours maximum (auto-stop)

Use Case: Remote debugging with Chrome DevTools

Profiler

Format: V8 CPU profiler format

Output: Heap snapshots and CPU profiles

Storage: Temporary files in feature directory

Use Case: Performance analysis and memory leak detection

System Metrics

Source: System commands (free, df, ps, etc.)

Update Frequency: On-demand

Caching: No caching (always fresh)

accuracy: System-dependent

---

Related Documentation

Last Updated

2026-02-17