system-memory-pools

Retrieves the current status of heap and off-heap memory. Specifying a scope lets you retrieve off-heap memory pool or object information.

Command properties

Property	Description
Command type	Driver query
Required permission	None
License usage	Not counted
Parallel execution	Not supported
Distributed execution	Not supported

Syntax

system-memory-pools [scope={pools|objects}]

Options

scope={pools|objects}: Specifies the detailed scope within off-heap to retrieve. If not specified, returns one summary record each for the heap and off-heap areas.

pools: Retrieves usage and available capacity per off-heap memory pool. Returns the same result as the system-offheap-pools command.
objects: Retrieves information about objects allocated in off-heap memory. Returns the same result as the system-memory-objects command.

Output fields

When scope is not specified:

Field	Type	Description
type	string	Memory area type. `heap`: JVM heap memory, `offheap`: off-heap memory outside the JVM heap
free	long	Approximate free memory size (unit: bytes). Returned only when `type=heap`.
total	long	Approximate total memory size (unit: bytes). Returned only when `type=heap`.
object_count	integer	Number of objects in the direct buffer area. Returned only when `type=offheap`.
total_capacity	long	Total number of objects the direct buffer can accommodate. Returned only when `type=offheap`.

When scope=pools:

Field	Type	Description
type	string	Memory type. Always `offheap`
name	string	Off-heap memory pool name
using	long	Current usage of the memory pool (unit: bytes)
available	long	Available capacity of the memory pool (unit: bytes). The total pool size minus current usage.

When scope=objects:

Field	Type	Description
type	string	Memory type. Always `offheap`
name	string	Name of the object allocated in off-heap memory
using	long	Memory size currently used by the object (unit: bytes)

Error codes

Parsing errors

Error code	Message	Description
95091	invalid-scope-option	The `scope` value is not `pools` or `objects`

Runtime errors

Error code	Message	Description	Behavior
95091	invalid-scope-option	The `scope` value is not `pools` or `objects`	Abort query

Description

The system-memory-pools command retrieves system memory information. When scope is not specified, it returns one summary record each for the JVM heap and off-heap areas. The heap record (type=heap) contains the approximate free memory (free) and total memory (total) as reported by the JVM Runtime. The off-heap record (type=offheap) contains the number of objects in the direct buffer area and the total number of objects the buffer can accommodate.

Specifying scope=pools retrieves usage and available capacity per off-heap memory pool. Specifying scope=objects retrieves the names and memory usage of objects allocated in off-heap. Each mode returns the same result as the system-offheap-pools and system-memory-objects commands, respectively.

Examples

Retrieve heap and off-heap memory summary
```
system-memory-pools
```
Retrieves a summary of JVM heap free/total capacity and off-heap object count.
Retrieve off-heap memory pool usage
```
system-memory-pools scope=pools
```
Retrieves current usage and available capacity for each off-heap memory pool.
Retrieve off-heap object information
```
system-memory-pools scope=objects
```
Retrieves the names and memory usage of objects allocated in off-heap memory.

Calculate heap memory usage percentage

system-memory-pools
| search type = "heap"
| eval used = total - free
| eval used_pct = round(used * 100 / total, 1)
| fields type, used, total, used_pct

Calculates heap memory usage and usage percentage (%).