Skip to content

Commit 3e79c43

Browse files
Adds documentation for tiered caching stats API (#7158) (#7211)
1 parent d1da6f2 commit 3e79c43

File tree

2 files changed

+62
-2
lines changed

2 files changed

+62
-2
lines changed

_api-reference/nodes-apis/nodes-stats.md

+52-1
Original file line numberDiff line numberDiff line change
@@ -53,6 +53,7 @@ indexing_pressure | Statistics about the node's indexing pressure.
5353
shard_indexing_pressure | Statistics about shard indexing pressure.
5454
resource_usage_stats | Node-level resource usage statistics, such as CPU and JVM memory.
5555
admission_control | Statistics about admission control.
56+
caches | Statistics about caches.
5657

5758
To filter the information returned for the `indices` metric, you can use specific `index_metric` values. You can use these only when you use the following query types:
5859

@@ -87,6 +88,18 @@ GET _nodes/stats/indices/docs,search
8788
```
8889
{% include copy-curl.html %}
8990

91+
You can also use specific `index_metric` values in the `caches` metric to specify which caches will return statistics.
92+
The following index metrics are supported:
93+
94+
- request_cache
95+
96+
For example, the following query requests statistics for the `request_cache`:
97+
98+
```json
99+
GET _nodes/stats/caches/request_cache
100+
```
101+
{% include copy-curl.html %}
102+
90103
## Query parameters
91104

92105
The following table lists the available query parameters. All query parameters are optional.
@@ -97,7 +110,7 @@ completion_fields | String | The fields to include in completion statistics. Sup
97110
fielddata_fields | String | The fields to include in fielddata statistics. Supports comma-separated lists and wildcard expressions.
98111
fields | String | The fields to include. Supports comma-separated lists and wildcard expressions.
99112
groups | String | A comma-separated list of search groups to include in the search statistics.
100-
level | String | Specifies whether statistics are aggregated at the cluster, index, or shard level. Valid values are `indices`, `node`, and `shard`.
113+
level | String | Specifies whether statistics for the `indices` metric are aggregated at the cluster, index, or shard level. Valid values are `indices`, `node`, and `shard`. When used for the `caches` metric, `indices`, `shard`, and `tier` are valid. The `tier` value is ignored if the [tiered spillover cache]({{site.url}}{{site.baseurl}}/search-plugins/caching/tiered-cache/) is not in use.
101114
timeout | Time | Sets the time limit for node response. Default is `30s`.
102115
include_segment_file_sizes | Boolean | If segment statistics are requested, this field specifies to return the aggregated disk usage of every Lucene index file. Default is `false`.
103116

@@ -754,6 +767,16 @@ Select the arrow to view the example response.
754767
}
755768
}
756769
}
770+
},
771+
"caches" : {
772+
"request_cache" : {
773+
"size_in_bytes" : 1649,
774+
"evictions" : 0,
775+
"hit_count" : 0,
776+
"miss_count" : 18,
777+
"item_count" : 18,
778+
"store_name" : "opensearch_onheap"
779+
}
757780
}
758781
}
759782
}
@@ -809,6 +832,7 @@ http.total_opened | Integer | The total number of HTTP connections the node has
809832
[search_backpressure]({{site.url}}{{site.baseurl}}/opensearch/search-backpressure#search-backpressure-stats-api) | Object | Statistics related to search backpressure.
810833
[resource_usage_stats](#resource_usage_stats) | Object | Statistics related to resource usage for the node.
811834
[admission_control](#admission_control) | Object | Statistics related to admission control for the node.
835+
[caches](#caches) | Object | Statistics related to caches on the node.
812836

813837
### `indices`
814838

@@ -1278,6 +1302,33 @@ admission_control.global_cpu_usage.transport.rejection_count.indexing | Integer
12781302
admission_control.global_io_usage.transport.rejection_count.search | Integer | The total number of search rejections in the transport layer when the node IO usage limit was met. Any additional search requests are rejected until the system recovers. The CPU usage limit is configured in the `admission_control.search.io_usage.limit` setting (Linux only).
12791303
admission_control.global_io_usage.transport.rejection_count.indexing | Integer | The total number of indexing rejections in the transport layer when the node IO usage limit was met. Any additional indexing requests are rejected until the system recovers. The IO usage limit is configured in the `admission_control.indexing.io_usage.limit` setting (Linux only).
12801304

1305+
### `caches`
1306+
1307+
Because this API supports the experimental [tiered caching feature]({{site.url}}{{site.baseurl}}/search-plugins/caching/tiered-cache/), the responses found in this section may change. If the tiered caching feature flag is not enabled, the API will return `0` for all values.
1308+
{: .warning}
1309+
1310+
The `caches` object contains cache statistics, such as the `request_cache` statistics. The total values within each sub-metric are always returned, regardless of the value of the query parameter `level`.
1311+
1312+
Field | Field type | Description
1313+
:--- | :--- | :---
1314+
request_cache | Object | Statistics for the request cache.
1315+
request_cache.size_in_bytes | Integer | The total size, in bytes, of the request cache.
1316+
request_cache.evictions | Integer | The total number of evictions from the request cache.
1317+
request_cache.hit_count | Integer | The total hit count for the request cache.
1318+
request_cache.miss_count | Integer | The total miss count for the request cache.
1319+
request_cache.item_count | Integer | The total number of items in the request cache.
1320+
request_cache.store_name | String | The name of the store type used by the request cache. See [tiered cache]({{site.url}}{{site.baseurl}}/search-plugins/caching/tiered-cache/) for more information.
1321+
1322+
If the `level` query parameter is set to one of its valid values, `indices`, `shard`, or `tier`, additional fields will be present in `caches.request_cache` that categorize the values by these levels.
1323+
For example, if `level=indices,tier`, the tiered cache is in use, and the node has indexes named `index0` and `index1`, then the `caches` object will contain the same five metrics for each combination of level values, as shown in the following table.
1324+
1325+
Field | Field type | Description
1326+
:--- | :--- | :---
1327+
request_cache.indices.index0.tier.on_heap | Object | Contains the five metrics for `index0` on the heap tier.
1328+
request_cache.indices.index0.tier.disk | Object | Contains the five metrics for `index0` on the disk tier.
1329+
request_cache.indices.index1.tier.on_heap | Object | Contains the five metrics for `index1` on the heap tier.
1330+
request_cache.indices.index1.tier.disk | Object | Contains the five metrics for `index1` on the disk tier.
1331+
12811332
## Required permissions
12821333

12831334
If you use the Security plugin, make sure you have the appropriate permissions: `cluster:monitor/nodes/stats`.

_search-plugins/caching/tiered-cache.md

+10-1
Original file line numberDiff line numberDiff line change
@@ -98,4 +98,13 @@ The following table lists the settings related to the deletion of stale entries
9898
Setting | Data type | Default | Description
9999
:--- | :--- |:--------| :---
100100
`indices.requests.cache.cleanup.staleness_threshold` | String | `0%` | Defines the percentage of stale keys in the cache post. After identification, all stale cache entries are deleted. Optional.
101-
`indices.requests.cache.cleanup.interval` | Time unit | `1m` | Defines the frequency at which the request cache's stale entries are deleted. Optional.
101+
`indices.requests.cache.cleanup.interval` | Time unit | `1m` | Defines the frequency at which the request cache's stale entries are deleted. Optional.
102+
103+
## Getting statistics for the `tiered_spillover` store
104+
105+
To assess the impact of using the tiered spillover cache, use the [Node Stats API]({{site.url}}{{site.baseurl}}/api-reference/nodes-apis/nodes-stats/#caches), as shown in the following example:
106+
107+
```json
108+
GET /_nodes/stats/caches/request_cache?level=tier
109+
```
110+

0 commit comments

Comments
 (0)