> For the complete documentation index, see [llms.txt](https://boxlang.ortusbooks.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://boxlang.ortusbooks.com/boxlang-+-++/modules/bx-mcp/reference/tools/performance-and-health.md).

# Performance & Health

This page covers the performance snapshot tool (`PerformanceTools`) and the system health aggregator (`SystemTools`).

***

## Performance Snapshot — `PerformanceTools`

| Tool                       | Description                                                                                                                                                                                                           |
| -------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `performance_get_snapshot` | Single round-trip snapshot of memory, GC, CPU, threads, top memory pools, top executors, slow queries, slow requests, slow HTTP/SOAP calls, buffer pools, optional web server metrics, and a structured health report |

The `performance_get_snapshot` tool provides a holistic view of runtime health in a single call. It combines data from:

* **JVM Memory** — Heap and non-heap usage with pool breakdown
* **Garbage Collection** — Collection counts and cumulative time per algorithm
* **CPU** — Available processors, system load average, process CPU time
* **Threads** — Total, daemon, peak, and per-state counts
* **Top Memory Pools** — Highest-usage memory pools by percentage
* **Top Executors** — Most saturated async executor pools
* **Slow Queries** — Recent slow SQL samples
* **Slow Requests** — Recent slow inbound request samples
* **Slow HTTP** — Recent slow outbound HTTP/SOAP call samples
* **Buffer Pools** — Direct and mapped buffer usage
* **Web Server** — Undertow worker pool and listener metrics (when available)
* **Health Report** — Structured health assessment with score and issues

***

## System Health Aggregator — `SystemTools`

| Tool                | Description                                                                                            |
| ------------------- | ------------------------------------------------------------------------------------------------------ |
| `system_get_health` | Unified health across all subsystems: datasources, caches, watchers, schedulers, executors, web server |

The `system_get_health` tool calls every subsystem health endpoint in a single round-trip and returns a consolidated report:

```json
{
  "status": "warning",
  "score": 65,
  "issues": [
    { "code": "executors:EXECUTOR_DEGRADED", "severity": "warning", ... }
  ],
  "subsystems": {
    "datasources": { "status": "healthy", "score": 100, "issues": [], ... },
    "caches": { "status": "warning", "score": 85, "issues": [...], ... },
    "watchers": { "status": "healthy", "score": 100, "issues": [], ... },
    "schedulers": { "status": "healthy", "score": 100, "issues": [], ... },
    "executors": { "status": "warning", "score": 65, "issues": [...], ... },
    "webServer": { "status": "healthy", "score": 100, "available": true, ... }
  },
  "scoreBreakdown": {
    "base": 100,
    "subsystems": [
      { "subsystem": "datasources", "score": 100, "status": "healthy" },
      ...
    ]
  }
}
```

The overall score is the **minimum subsystem score** (weakest-link model). Issue codes are prefixed with the subsystem name (e.g., `executors:EXECUTOR_DEGRADED`).

***

## Health Report Schema

All `*_get_health` tools return a consistent structured report. See the [Health Reports reference](/boxlang-+-++/modules/bx-mcp/reference/health-reports.md) for the complete schema, scoring model, and issue code catalog.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://boxlang.ortusbooks.com/boxlang-+-++/modules/bx-mcp/reference/tools/performance-and-health.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.