> ## Documentation Index
> Fetch the complete documentation index at: https://docs.genesiscomputing.com/llms.txt
> Use this file to discover all available pages before exploring further.

# System Stats Tools

> Collect OS-level metrics, monitor resource utilization, and track system health for diagnostics and capacity planning.

## **Overview**

### **Tool Name**

```json theme={null}
system_stats_tools
```

### **Purpose**

The **system\_stats\_tools** group provides real-time performance telemetry and health insights. Use it to fetch current server time and timezone, gather CPU, memory, disk, network, and process metrics, and build a reliable picture of platform load and stability.

### **Key Features & Functions**

<Steps>
  <Step title="Current Time & Timezone" icon="clock">
    Retrieve authoritative server datetime, timezone, and sync context for logs and distributed jobs.
  </Step>

  <Step title="CPU & Load" icon="microchip">
    Capture CPU utilization and load averages to spot saturation and sizing gaps.
  </Step>

  <Step title="Memory Utilization" icon="memory">
    Track total, used, cached, and available memory to prevent swapping.
  </Step>

  <Step title="Disk & I/O" icon="code">
    Inspect free space and IOPS to protect pipelines from storage contention.
  </Step>

  <Step title="Network Throughput" icon="network-wired">
    Observe interface bytes per second and error counters for connectivity health.
  </Step>

  <Step title="Processes & Uptime" icon="meter">
    Surface top consumers, uptime, and boot time for triage and audits.
  </Step>

  <Step title="Health Signals" icon="heart">
    Combine metrics into health indicators and alerts for proactive action.
  </Step>
</Steps>

<Tip>
  Capture a baseline during normal load, then compare after each release or workload change to quantify impact.
</Tip>

## **Input Parameters for Each Function**

### **`get_server_datetime`**

**Parameters**

No parameters.

### **`get_system_stats`**

**Parameters**

No parameters.

## **Use Cases**

1. **High-load monitoring**
   Track CPU, memory, and I/O while ETL or ML jobs run to detect bottlenecks.
2. **Capacity planning**
   Export daily snapshots to trend headroom and justify hardware or quota changes.
3. **Incident triage**
   Compare current metrics with baseline to isolate the noisy neighbor or failing disk.
4. **SLA verification**
   Correlate job runtimes with system pressure to validate performance agreements.
5. **Time synchronization checks**
   Confirm server time and timezone for consistent, debuggable logs.

<Warning>
  Polling too frequently increases overhead. Start with one metric pull per 30 to 60 seconds, then adjust based on needs.
</Warning>

## **Workflow/How It Works**

1. **Fetch time context** with `get_server_datetime` to stamp logs and verify timezone.
2. **Pull point-in-time metrics** using `get_system_stats` for CPU, memory, disk, network, and processes.
3. **Store snapshots** in your monitoring datastore for trend analysis.
4. **Compare to baseline** to detect regressions after deploys or config changes.
5. **Alert on thresholds** such as CPU greater than 85 percent for 5 minutes or disk free less than 15 percent.

<Note>
  Align time sources across nodes to keep multi-host traces and metrics comparable.
</Note>

## **Integration Relevance**

* **genesis\_job\_tools** to correlate background job activity with resource spikes.
* **system\_manager\_tools** to verify health before maintenance and after restarts.
* **harvester\_tools** to watch metadata crawls for resource pressure.
* **data\_connector\_tools** to contextualize slow queries with host contention.
* Any tool that schedules heavy workloads benefits from pre- and post-run stats.

## **Configuration Details**

* Ensure the runtime has permissions for OS metrics and sensors.
* Choose a sampling cadence that balances fidelity and overhead.
* Normalize units and field names when exporting to external observability stacks.
* Keep timezone consistent across environments to simplify comparisons.
* Retain history according to compliance and troubleshooting needs.

## **Limitations or Notes**

1. Metrics availability varies by OS, virtualization layer, and permissions.
2. High-frequency polling can distort readings and consume resources.
3. Some hardware sensors may be missing in cloud or containerized environments.
4. Network counters may exclude virtual interfaces without elevated access.
5. Real-time values fluctuate, so use smoothing or short windows when alerting.
6. Large fleets require aggregation and sampling to stay efficient.
7. In a Databricks App, this MCP server receives an allowlisted environment rather
   than the server's full environment. See [Genesis as a Databricks App](/docs/deployments/Databricks/Genesis-On-Databricks#genesis-as-a-databricks-app)
   for the environment filtering behavior and its security limitations.

## **Output**

* **Server DateTime**: Current timestamp, timezone, and sync context.
* **CPU Metrics**: Utilization by core and load averages.
* **Memory Metrics**: Total, used, free, buffers, cache.
* **Disk Metrics**: Free space, read or write rates, and latency where available.
* **Network Metrics**: Per-interface throughput and error counts.
* **Processes**: Top consumers by CPU or memory with PIDs.
* **Uptime**: System uptime and last boot time.
* **Health Summary**: Optional composite indicators and threshold flags.