Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Update tiered cache documentation #6817

Merged
merged 4 commits into from
Apr 1, 2024
Merged

Update tiered cache documentation #6817

Changes from 2 commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
6f051f7
Update tiered cache documentation
kolchfa-aws Apr 1, 2024
1126349
Remove comma
kolchfa-aws Apr 1, 2024
3497488
Update _search-plugins/caching/tiered-cache.md
kolchfa-aws Apr 1, 2024
b173172
Editorial comments
kolchfa-aws Apr 1, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
40 changes: 21 additions & 19 deletions _search-plugins/caching/tiered-cache.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -11,11 +11,11 @@
This is an experimental feature and is not recommended for use in a production environment. For updates on the progress of the feature or if you want to leave feedback, see the associated [GitHub issue](https://github.com/opensearch-project/OpenSearch/issues/10024).
{: .warning}

A tiered cache is a multi-level cache, in which each tier has its own characteristics and performance levels. By combining different tiers, you can achieve a balance between cache performance and size.
A tiered cache is a multi-level cache in which each tier has its own characteristics and performance levels. By combining different tiers, you can achieve a balance between cache performance and size.

## Types of tiered caches

OpenSearch 2.13 provides an implementation of _tiered spillover cache_. This implementation spills the evicted items from upper to lower tiers. The upper tier is smaller in size but offers better latency, like the on-heap tier. The lower tier is larger in size but is slower in terms of latency compared to the upper tier. A disk cache is an example of a lower tier. OpenSearch 2.13 offers on-heap and disk tiers.
OpenSearch 2.13 provides an implementation of _tiered spillover cache_. This implementation spills the evicted items from upper to lower tiers. The upper tier, such as the on-heap tier, is smaller in size but offers better latency. The lower tier, such as a disk cache, is larger in size but is slower in terms of latency. OpenSearch 2.13 offers on-heap and disk tiers.
kolchfa-aws marked this conversation as resolved.
Show resolved Hide resolved

## Enabling a tiered cache

Expand All @@ -30,7 +30,7 @@

## Installing required plugins

A tiered cache provides a way to plug in any disk or on-heap tier implementation. You can install the plugins you intend to use in the tiered cache. As of OpenSearch 2.13, the available cache plugin is the `cache-ehcache` plugin. This plugin provides a disk cache implementation to use within a tiered cache as a disk tier.
To use tiered caching, install a tiered cache plugin. As of OpenSearch 2.13, the only available cache plugin is the `cache-ehcache` plugin. This plugin provides a disk cache implementation to use within a tiered cache as a disk tier. For more information about installing non-bundled plugins, see [Additional plugins]({{site.url}}{{site.baseurl}}/install-and-configure/plugins/#additional-plugins).

A tiered cache will fail to initialize if the `cache-ehcache` plugin is not installed or disk cache properties are not set.
{: .warning}
Expand All @@ -41,42 +41,44 @@

### Cache store name

Set the cache store name to `tiered_spillover` to use the OpenSearch-provided tiered spillover cache implementation:
To use the OpenSearch-provided tiered spillover cache implementation, set the cache store name to `tiered_spillover`:

```yaml
indices.request.cache.store.name: tiered_spillover: true
indices.request.cache.store.name: tiered_spillover
```
{% include copy.html %}

### Setting on-heap and disk store tiers

The `opensearch_onheap` setting is the built-in on-heap cache available in OpenSearch. The `ehcache_disk` setting is the disk cache implementation from [Ehcache](https://www.ehcache.org/). This requires installing the `cache-ehcache` plugin:
Set the on-heap and disk store tiers as follows:

```yaml
indices.request.cache.tiered_spillover.onheap.store.name: opensearch_onheap
indices.request.cache.tiered_spillover.disk.store.name: ehcache_disk
```
{% include copy.html %}

For more information about installing non-bundled plugins, see [Additional plugins]({{site.url}}{{site.baseurl}}/install-and-configure/plugins/#additional-plugins).
The `opensearch_onheap` setting is the built-in on-heap cache available in OpenSearch.
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The setting can't literally be the cache.

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Reworded.


The `ehcache_disk` setting is the disk cache implementation from [Ehcache](https://www.ehcache.org/). Using `ehcache_disk` requires installing the `cache-ehcache` plugin.

Check failure on line 63 in _search-plugins/caching/tiered-cache.md

View workflow job for this annotation

GitHub Actions / vale

[vale] _search-plugins/caching/tiered-cache.md#L63 

[OpenSearch.Spelling] Error: Ehcache. If you are referencing a setting, variable, format, function, or repository, surround it with tic marks.
Raw output 
{"message": "[OpenSearch.Spelling] Error: Ehcache. If you are referencing a setting, variable, format, function, or repository, surround it with tic marks.", "location": {"path": "_search-plugins/caching/tiered-cache.md", "range": {"start": {"line": 63, "column": 67}}}, "severity": "ERROR"}
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The setting can't literally be the disk cache implementation.

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Reworded.


### Configuring on-heap and disk stores

The following table lists the cache store settings for the `opensearch_onheap` store.

Setting | Default | Description
:--- | :--- | :---
`indices.request.cache.opensearch_onheap.size` | 1% of the heap | The size of the on-heap cache. Optional.
`indices.request.cache.opensearch_onheap.expire` | `MAX_VALUE` (disabled) | Specify a time-to-live (TTL) for the cached results. Optional.
Setting | Data type | Default | Description
:--- | :--- | :--- | :---
`indices.request.cache.opensearch_onheap.size` | Percentage (for example, `1%`) | 1% of the heap | The size of the on-heap cache. Optional.
`indices.request.cache.opensearch_onheap.expire` | Integer | `MAX_VALUE` (disabled) | Specify a time-to-live (TTL) for the cached results. Optional.

The following table lists the disk cache store settings for the `ehcache_disk` store.

Setting | Default | Description
:--- | :--- | :---
`indices.request.cache.ehcache_disk.max_size_in_bytes` | `1073741824` (1 GB) | Defines the size of the disk cache. Optional.
`indices.request.cache.ehcache_disk.storage.path` | `""` | Defines the storage path for the disk cache. Required.
`indices.request.cache.ehcache_disk.expire_after_access` | `MAX_VALUE` (disabled) | Specify a time-to-live (TTL) for the cached results. Optional.
`indices.request.cache.ehcache_disk.alias` | `ehcacheDiskCache#INDICES_REQUEST_CACHE` (this is an example of request cache) | Specify an alias for the disk cache. Optional.
`indices.request.cache.ehcache_disk.segments` | `16` | Defines the number of segments the disk cache is separated into. Used for concurrency. Optional.
`indices.request.cache.ehcache_disk.concurrency` | `1` | Defines the number of distinct write queues created for the disk store, where a group of segments share a write queue. Optional.
Setting | Data type | Default | Description
:--- | :--- | :--- | :---
`indices.request.cache.ehcache_disk.storage.path` | String | `""` | Defines the storage path for the disk cache. Required.
`indices.request.cache.ehcache_disk.max_size_in_bytes` | Integer | `1073741824` (1 GB) | Defines the size of the disk cache, in bytes. Optional.
`indices.request.cache.ehcache_disk.expire_after_access` | Integer | `MAX_VALUE` (disabled) | Specify a time-to-live (TTL) for the cached results. Optional.
`indices.request.cache.ehcache_disk.alias` | String | `ehcacheDiskCache#INDICES_REQUEST_CACHE` (this is an example of request cache) | Specify an alias for the disk cache. Optional.
`indices.request.cache.ehcache_disk.segments` | Integer | `16` | Defines the number of segments the disk cache is separated into. Used for concurrency. Optional.
`indices.request.cache.ehcache_disk.concurrency` | Integer | `1` | Defines the number of distinct write queues created for the disk store, where a group of segments share a write queue. Optional.

Loading