Compare commits
1 Commits
| Author | SHA1 | Date | |
|---|---|---|---|
 keithhc2
|
7c892e1057 |
@@ -3,5 +3,3 @@ _site
|
||||
.jekyll-metadata
|
||||
.DS_Store
|
||||
Gemfile.lock
|
||||
.idea
|
||||
.jekyll-cache
|
||||
|
||||
@@ -1 +1 @@
|
||||
Copyright 2021 OpenSearch contributors.
|
||||
Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
|
||||
|
||||
@@ -34,7 +34,7 @@ If you encounter problems or have questions when contributing to the documentati
|
||||
|
||||
After each commit to this repository, GitHub Pages automatically uses [Jekyll](https://jekyllrb.com) to rebuild the [website](https://docs-beta.opensearch.org). The whole process takes around 30 seconds.
|
||||
|
||||
This repository contains many [Markdown](https://guides.github.com/features/mastering-markdown/) files in the `/docs` directory. Each Markdown file correlates with one page on the website.
|
||||
This repository contains many [Markdown](https://guides.github.com/features/mastering-markdown/) files in the `/docs` directory. Each Markdown file correlates with one page on the website. For example, the Markdown file for [this page](https://docs-beta.opensearch.org/docs/opensearch/) is [here](https://github.com/opensearch-project/documentation-website/blob/master/docs/opensearch/index.md).
|
||||
|
||||
Using plain text on GitHub has many advantages:
|
||||
|
||||
@@ -273,4 +273,4 @@ This project is licensed under the Apache-2.0 License.
|
||||
|
||||
## Copyright
|
||||
|
||||
Copyright 2021 OpenSearch contributors.
|
||||
Copyright Amazon.com, Inc. or its affiliates. All rights reserved.
|
||||
|
||||
@@ -1,66 +0,0 @@
|
||||
---
|
||||
layout: default
|
||||
title: Agents and ingestion tools
|
||||
nav_order: 100
|
||||
has_children: false
|
||||
has_toc: false
|
||||
---
|
||||
|
||||
# Agents and ingestion tools
|
||||
|
||||
Historically, many multiple popular agents and ingestion tools have worked with Elasticsearch OSS, such as Beats, Logstash, Fluentd, FluentBit, and OpenTelemetry. OpenSearch aims to continue to support a broad set of agents and ingestion tools, but not all have been tested or have explicitly added OpenSearch compatibility.
|
||||
|
||||
As an intermediate solution, we are adding a [version value](https://github.com/opensearch-project/OpenSearch/issues/693) to `opensearch.yml`. This change will let you set OpenSearch 1.x clusters to report version 7.10.2 (or any other arbitrary value). By reporting 7.10.2, the cluster will be able to connect with tools that check for a particular version number.
|
||||
|
||||
For a longer term solution, we plan to create an OpenSearch output plugin for Logstash. This plugin *does not exist yet*, but we've included it in the compatibility matrices below based on its expected behavior.
|
||||
|
||||
|
||||
## Downloads
|
||||
|
||||
These versions of Logstash and Beats offer the best compatibility with OpenSearch. For more information, see the [compatibility matrices](#compatibility-matrices).
|
||||
|
||||
- [Logstash OSS 7.12.1](https://www.elastic.co/downloads/past-releases/logstash-oss-7-12-1)
|
||||
- [Filebeat OSS 7.12.1](https://www.elastic.co/downloads/past-releases/filebeat-oss-7-12-1)
|
||||
- [Metricbeat OSS 7.12.1](https://www.elastic.co/downloads/past-releases/metricbeat-oss-7-12-1)
|
||||
- [Packetbeat OSS 7.12.1](https://www.elastic.co/downloads/past-releases/packetbeat-oss-7-12-1)
|
||||
- [Heartbeat OSS 7.12.1](https://elastic.co/downloads/past-releases/heartbeat-oss-7-12-1)
|
||||
- [Winlogbeat OSS 7.12.1](https://www.elastic.co/downloads/past-releases/winlogbeat-oss-7-12-1)
|
||||
- [Auditbeat OSS 7.12.1](https://elastic.co/downloads/past-releases/auditbeat-oss-7-12-1)
|
||||
|
||||
|
||||
## Compatibility Matrices
|
||||
|
||||
*Italicized* cells are untested, but indicate what a value theoretically should be based on existing information.
|
||||
|
||||
|
||||
### Compatibility Matrix for Logstash
|
||||
|
||||
| | Logstash OSS 7.x to 7.11.x | Logstash OSS 7.12.x\* | Logstash 7.13.x without OpenSearch output plugin | Logstash 7.13.x with OpenSearch output plugin\*\* |
|
||||
| :---| :--- | :--- | :--- | :--- |
|
||||
| Elasticsearch OSS v7.x to v7.9.x | *Yes* | *Yes* | *No* | *Yes* |
|
||||
| Elasticsearch OSS v7.10.2 | *Yes* | *Yes* | *No* | *Yes* |
|
||||
| ODFE OSS v1.x to 1.12 | *Yes* | *Yes* | *No* | *Yes* |
|
||||
| ODFE 1.13 | *Yes* | *Yes* | *No* | *Yes* |
|
||||
| OpenSearch 1.0 | [Yes via version setting](https://github.com/opensearch-project/OpenSearch/issues/693) | [Yes via version setting](https://github.com/opensearch-project/OpenSearch/issues/693) | *No* | *Yes* |
|
||||
|
||||
\* Most current compatible version with Elasticsearch OSS.
|
||||
|
||||
\*\* Planning to build.
|
||||
|
||||
|
||||
### Compatibility Matrix for Beats
|
||||
|
||||
| | Beats OSS 7.x to 7.11.x\*\* | Beats OSS 7.12.x\* | Beats 7.13.x |
|
||||
| :--- | :--- | :--- | :--- |
|
||||
| Elasticsearch OSS v7.x to v7.9.x | *Yes* | *Yes* | No |
|
||||
| Elasticsearch OSS v7.10.2 | *Yes* | *Yes* | No |
|
||||
| ODFE OSS v1.x to 1.12 | *Yes* | *Yes* | No |
|
||||
| ODFE 1.13 | *Yes* | *Yes* | No |
|
||||
| OpenSearch 1.0 | [Yes via version setting](https://github.com/opensearch-project/OpenSearch/issues/693) | [Yes via version setting](https://github.com/opensearch-project/OpenSearch/issues/693) | No |
|
||||
| Logstash OSS 7.x to 7.11.x | *Yes* | *Yes* | *Yes* |
|
||||
| Logstash OSS 7.12.x\* | *Yes* | *Yes* | *Yes* |
|
||||
| Logstash 7.13.x with OpenSearch output plugin | *Yes* | *Yes* | *Yes* |
|
||||
|
||||
\* Most current compatible version with Elasticsearch OSS.
|
||||
|
||||
\*\* Beats OSS includes all Apache 2.0 Beats agents (i.e. Filebeat, Metricbeat, Auditbeat, Heartbeat, Winlogbeat, Packetbeat).
|
||||
@@ -1,124 +0,0 @@
|
||||
---
|
||||
layout: default
|
||||
title: Java high-level REST client
|
||||
nav_order: 97
|
||||
---
|
||||
|
||||
# Java high-level REST client
|
||||
|
||||
The Elasticsearch OSS Java high-level REST client allows you to interact with your OpenSearch clusters and indices through Java methods and data structures rather than HTTP methods and JSON.
|
||||
|
||||
You submit requests to your cluster using request objects, which allows you to create indices, add data to documents, or complete other operations with your cluster. In return, you get back response objects that have all of the available information, such as the associated index or ID, from your cluster.
|
||||
|
||||
## Setup
|
||||
|
||||
To start using the Elasticsearch OSS Java high-level REST client, ensure that you have the following dependency in your project's `pom.xml` file:
|
||||
|
||||
```
|
||||
<dependency>
|
||||
<groupId>org.elasticsearch.client</groupId>
|
||||
<artifactId>elasticsearch-rest-high-level-client</artifactId>
|
||||
<version>7.10.2</version>
|
||||
</dependency>
|
||||
```
|
||||
|
||||
You can now start your OpenSearch cluster. The 7.10.2 high-level REST client works with the 1.x versions of OpenSearch.
|
||||
|
||||
## Sample code
|
||||
|
||||
```java
|
||||
import org.apache.http.HttpHost;
|
||||
import org.apache.http.auth.AuthScope;
|
||||
import org.apache.http.auth.UsernamePasswordCredentials;
|
||||
import org.apache.http.client.CredentialsProvider;
|
||||
import org.apache.http.impl.client.BasicCredentialsProvider;
|
||||
import org.apache.http.impl.nio.client.HttpAsyncClientBuilder;
|
||||
import org.elasticsearch.action.admin.indices.delete.DeleteIndexRequest;
|
||||
import org.elasticsearch.action.delete.DeleteRequest;
|
||||
import org.elasticsearch.action.delete.DeleteResponse;
|
||||
import org.elasticsearch.action.get.GetRequest;
|
||||
import org.elasticsearch.action.get.GetResponse;
|
||||
import org.elasticsearch.action.index.IndexRequest;
|
||||
import org.elasticsearch.action.index.IndexResponse;
|
||||
import org.elasticsearch.action.support.master.AcknowledgedResponse;
|
||||
import org.elasticsearch.client.RequestOptions;
|
||||
import org.elasticsearch.client.RestClient;
|
||||
import org.elasticsearch.client.RestClientBuilder;
|
||||
import org.elasticsearch.client.RestHighLevelClient;
|
||||
import org.elasticsearch.client.indices.CreateIndexRequest;
|
||||
import org.elasticsearch.client.indices.CreateIndexResponse;
|
||||
import org.elasticsearch.common.settings.Settings;
|
||||
import org.elasticsearch.common.xcontent.XContentType;
|
||||
|
||||
import java.io.IOException;
|
||||
import java.util.HashMap;
|
||||
|
||||
public class RESTClientSample {
|
||||
|
||||
public static void main(String[] args) throws IOException {
|
||||
|
||||
//Point to keystore with appropriate certificates for security.
|
||||
System.setProperty("javax.net.ssl.trustStore", "/full/path/to/keystore");
|
||||
System.setProperty("javax.net.ssl.trustStorePassword", password-to-keystore);
|
||||
|
||||
//Establish credentials to use basic authentication.
|
||||
//Only for demo purposes. Do not specify your credentials in code.
|
||||
final CredentialsProvider credentialsProvider = new BasicCredentialsProvider();
|
||||
|
||||
credentialsProvider.setCredentials(AuthScope.ANY,
|
||||
new UsernamePasswordCredentials("admin", "admin"));
|
||||
|
||||
//Create a client.
|
||||
RestClientBuilder builder = RestClient.builder(new HttpHost("localhost", 9200, "https"))
|
||||
.setHttpClientConfigCallback(new RestClientBuilder.HttpClientConfigCallback() {
|
||||
@Override
|
||||
public HttpAsyncClientBuilder customizeHttpClient(HttpAsyncClientBuilder httpClientBuilder) {
|
||||
return httpClientBuilder.setDefaultCredentialsProvider(credentialsProvider);
|
||||
}
|
||||
});
|
||||
RestHighLevelClient client = new RestHighLevelClient(builder);
|
||||
|
||||
//Create a non-default index with custom settings and mappings.
|
||||
CreateIndexRequest createIndexRequest = new CreateIndexRequest("test-index");
|
||||
|
||||
createIndexRequest.settings(Settings.builder() //Specify in the settings how many shards you want in the index.
|
||||
.put("index.number_of_shards", 4)
|
||||
.put("index.number_of_replicas", 3)
|
||||
);
|
||||
//Create a set of maps for the index's mappings.
|
||||
HashMap<String, String> typeMapping = new HashMap<String,String>();
|
||||
typeMapping.put("type", "integer");
|
||||
HashMap<String, Object> ageMapping = new HashMap<String, Object>();
|
||||
ageMapping.put("age", typeMapping);
|
||||
HashMap<String, Object> mapping = new HashMap<String, Object>();
|
||||
mapping.put("properties", ageMapping);
|
||||
createIndexRequest.mapping(mapping);
|
||||
CreateIndexResponse createIndexResponse = client.indices().create(createIndexRequest, RequestOptions.DEFAULT
|
||||
|
||||
//Adding data to the index.
|
||||
IndexRequest request = new IndexRequest("custom-index"); //Add a document to the custom-index we created.
|
||||
request.id("1"); //Assign an ID to the document.
|
||||
|
||||
HashMap<String, String> stringMapping = new HashMap<String, String>();
|
||||
stringMapping.put("message:", "Testing Java REST client");
|
||||
request.source(stringMapping); //Place your content into the index's source.
|
||||
IndexResponse indexResponse = client.index(request, RequestOptions.DEFAULT);
|
||||
|
||||
//Getting back the document
|
||||
GetRequest getRequest = new GetRequest("custom-index", "1");
|
||||
GetResponse response = client.get(getRequest, RequestOptions.DEFAULT);
|
||||
|
||||
System.out.println(response.getSourceAsString());
|
||||
|
||||
//Delete the document
|
||||
DeleteRequest deleteDocumentRequest = new DeleteRequest("custom-index", "1"); //Index name followed by the ID.
|
||||
DeleteResponse deleteResponse = client.delete(deleteDocumentRequest, RequestOptions.DEFAULT);
|
||||
|
||||
//Delete the index
|
||||
DeleteIndexRequest deleteIndexRequest = new DeleteIndexRequest("custom-index"); //Index name.
|
||||
AcknowledgedResponse deleteIndexResponse = client.indices().delete(deleteIndexRequest, RequestOptions.DEFAULT);
|
||||
|
||||
client.close();
|
||||
}
|
||||
}
|
||||
```
|
||||
+17
-72
@@ -1,11 +1,26 @@
|
||||
# Welcome to Jekyll!
|
||||
#
|
||||
# This config file is meant for settings that affect your whole blog, values
|
||||
# which you are expected to set up once and rarely edit after that. If you find
|
||||
# yourself editing this file very often, consider using Jekyll's data files
|
||||
# feature for the data you need to update frequently.
|
||||
#
|
||||
# For technical reasons, this file is *NOT* reloaded automatically when you use
|
||||
# 'bundle exec jekyll serve'. If you change this file, please restart the server process.
|
||||
|
||||
# Site settings
|
||||
# These are used to personalize your new site. If you look in the HTML files,
|
||||
# you will see them accessed via {{ site.title }}, {{ site.email }}, and so on.
|
||||
# You can create any custom variable you would like, and they will be accessible
|
||||
# in the templates via {{ site.myvariable }}.
|
||||
title: OpenSearch documentation
|
||||
description: >- # this means to ignore newlines until "baseurl:"
|
||||
Documentation for OpenSearch, the Apache 2.0 search, analytics, and visualization suite with advanced security, alerting, SQL support, automated index management, deep performance analysis, and more.
|
||||
baseurl: "" # the subpath of your site, e.g. /blog
|
||||
url: "https://docs-beta.opensearch.org" # the base hostname & protocol for your site, e.g. http://example.com
|
||||
permalink: /:path/
|
||||
permalink: pretty
|
||||
|
||||
opensearch_version: 1.0.0-rc1
|
||||
opensearch_version: 1.0.0-beta1
|
||||
opensearch_major_minor_version: 1.0
|
||||
|
||||
# Build settings
|
||||
@@ -24,76 +39,6 @@ aux_links:
|
||||
- "https://opensearch.org"
|
||||
color_scheme: opensearch
|
||||
|
||||
# Define Jekyll collections
|
||||
collections:
|
||||
# Define a collection named "tests", its documents reside in the "_tests" directory
|
||||
upgrade-to:
|
||||
permalink: /:collection/:path/
|
||||
output: true
|
||||
opensearch:
|
||||
permalink: /:collection/:path/
|
||||
output: true
|
||||
dashboards:
|
||||
permalink: /:collection/:path/
|
||||
output: true
|
||||
security-plugin:
|
||||
permalink: /:collection/:path/
|
||||
output: true
|
||||
search-plugins:
|
||||
permalink: /:collection/:path/
|
||||
output: true
|
||||
im-plugin:
|
||||
permalink: /:collection/:path/
|
||||
output: true
|
||||
monitoring-plugins:
|
||||
permalink: /:collection/:path/
|
||||
output: true
|
||||
clients:
|
||||
permalink: /:collection/:path/
|
||||
output: true
|
||||
troubleshoot:
|
||||
permalink: /:collection/:path/
|
||||
output: true
|
||||
external_links:
|
||||
permalink: /:collection/:path/
|
||||
output: true
|
||||
|
||||
just_the_docs:
|
||||
# Define the collections used in the theme
|
||||
collections:
|
||||
upgrade-to:
|
||||
name: Upgrade to OpenSearch
|
||||
# nav_exclude: true
|
||||
nav_fold: true
|
||||
# search_exclude: true
|
||||
opensearch:
|
||||
name: OpenSearch
|
||||
nav_fold: true
|
||||
dashboards:
|
||||
name: OpenSearch Dashboards
|
||||
nav_fold: true
|
||||
security-plugin:
|
||||
name: Security plugin
|
||||
nav_fold: true
|
||||
search-plugins:
|
||||
name: Search plugins
|
||||
nav_fold: true
|
||||
im-plugin:
|
||||
name: Index management plugin
|
||||
nav_fold: true
|
||||
monitoring-plugins:
|
||||
name: Monitoring plugins
|
||||
nav_fold: true
|
||||
clients:
|
||||
name: Clients and tools
|
||||
nav_fold: true
|
||||
troubleshoot:
|
||||
name: Troubleshooting
|
||||
nav_fold: true
|
||||
external_links:
|
||||
name: External links
|
||||
|
||||
|
||||
# Enable or disable the site search
|
||||
# Supports true (default) or false
|
||||
search_enabled: true
|
||||
|
||||
@@ -1,17 +0,0 @@
|
||||
---
|
||||
layout: default
|
||||
title: Browser compatibility
|
||||
parent: OpenSearch Dashboards
|
||||
nav_order: 3
|
||||
---
|
||||
|
||||
# Browser compatibility
|
||||
|
||||
OpenSearch Dashboards supports the following web browsers:
|
||||
|
||||
- Chrome
|
||||
- Firefox
|
||||
- Safari
|
||||
- Edge (Chromium)
|
||||
|
||||
Other Chromium-based browsers might work, as well. Internet Explorer and Microsoft Edge Legacy are **not** supported.
|
||||
@@ -1,41 +0,0 @@
|
||||
---
|
||||
layout: default
|
||||
title: Configure TLS
|
||||
parent: Install OpenSearch Dashboards
|
||||
nav_order: 40
|
||||
---
|
||||
|
||||
# Configure TLS for OpenSearch Dashboards
|
||||
|
||||
By default, for ease of testing and getting started, OpenSearch Dashboards runs over HTTP. To enable TLS for HTTPS, update the following settings in `opensearch_dashboards.yml`.
|
||||
|
||||
Setting | Description
|
||||
:--- | :---
|
||||
opensearch.ssl.verificationMode | This setting is for communications between OpenSearch and OpenSearch Dashboards. Valid values are `full`, `certificate`, or `none`. We recommend `full` if you enable TLS, which enables hostname verification. `certificate` just checks the certificate, not the hostname, and `none` performs no checks (suitable for HTTP). Default is `full`.
|
||||
opensearch.ssl.certificateAuthorities | If `opensearch.ssl.verificationMode` is `full` or `certificate`, specify the full path (e.g. `[ "/usr/share/opensearch-dashboards-1.0.0/config/root-ca.pem" ]` to the certificate authority for your OpenSearch cluster.
|
||||
server.ssl.enabled | This setting is for communications between OpenSearch Dashboards and the web browser. Set to true for HTTPS, false for HTTP.
|
||||
server.ssl.certificate | If `server.ssl.enabled` is true, specify the full path (e.g. `/usr/share/opensearch-dashboards-1.0.0/config/my-client-cert.pem` to a valid client certificate for your OpenSearch cluster. You can [generate your own]({{site.url}}{{site.baseurl}}/security-plugin/configuration/generate-certificates/) or get one from a certificate authority.
|
||||
server.ssl.key | If `server.ssl.enabled` is true, specify the full path (e.g. `/usr/share/opensearch-dashboards-1.0.0/config/my-client-cert-key.pem` to the key for your client certificate. You can [generate your own]({{site.url}}{{site.baseurl}}/security-plugin/configuration/generate-certificates/) or get one from a certificate authority.
|
||||
opensearch_security.cookie.secure | If you enable TLS for OpenSearch Dashboards, change this setting to `true`. For HTTP, set it to `false`.
|
||||
|
||||
This `opensearch_dashboards.yml` configuration shows OpenSearch and OpenSearch Dashboards running on the same machine with the demo configuration:
|
||||
|
||||
```yml
|
||||
opensearch.hosts: ["https://localhost:9200"]
|
||||
opensearch.ssl.verificationMode: full
|
||||
opensearch.username: "kibanaserver"
|
||||
opensearch.password: "kibanaserver"
|
||||
opensearch.requestHeadersWhitelist: [ authorization,securitytenant ]
|
||||
server.ssl.enabled: true
|
||||
server.ssl.certificate: /usr/share/opensearch-1.0.0/config/client-cert.pem
|
||||
server.ssl.key: /usr/share/opensearch-1.0.0/config/client-cert-key.pem
|
||||
opensearch.ssl.certificateAuthorities: [ "/usr/share/opensearch-1.0.0/config/root-ca.pem" ]
|
||||
opensearch_security.multitenancy.enabled: true
|
||||
opensearch_security.multitenancy.tenants.preferred: ["Private", "Global"]
|
||||
opensearch_security.readonly_mode.roles: ["kibana_read_only"]
|
||||
opensearch_security.cookie.secure: true
|
||||
```
|
||||
|
||||
If you use the Docker install, you can pass a custom `opensearch_dashboards.yml` to the container. To learn more, see the [Docker installation page]({{site.url}}{{site.baseurl}}/opensearch/install/docker/).
|
||||
|
||||
After enabling these settings and starting OpenSearch Dashboards, you can connect to it at `https://localhost:5601`. You might have to acknowledge a browser warning if your certificates are self-signed. To avoid this sort of warning (or outright browser incompatibility), best practice is to use certificates from trusted certificate authority.
|
||||
@@ -1,118 +0,0 @@
|
||||
---
|
||||
layout: default
|
||||
title: Notebooks
|
||||
nav_order: 50
|
||||
redirect_from: /docs/notebooks/
|
||||
has_children: false
|
||||
---
|
||||
|
||||
# Notebooks
|
||||
|
||||
An OpenSearch Dashboards notebook is an interface that lets you easily combine code snippets, live visualizations, and narrative text in a single notebook interface.
|
||||
|
||||
Notebooks let you interactively explore data by running different visualizations that you can share with team members to collaborate on a project.
|
||||
|
||||
A notebook is a document composed of two elements: code blocks (Markdown/SQL/PPL) and visualizations. Choose multiple timelines to compare and contrast visualizations.
|
||||
|
||||
You can also generate [reports]({{site.url}}{{site.baseurl}}/dashboards/reporting/) directly from your notebooks.
|
||||
|
||||
Common use cases include creating postmortem reports, designing runbooks, building live infrastructure reports, and writing documentation.
|
||||
|
||||
Tenants in OpenSearch Dashboards are spaces for saving notebooks and other OpenSearch Dashboards objects. For more information, see [OpenSearch Dashboards multi-tenancy]({{site.url}}{{site.baseurl}}/security-plugin/access-control/multi-tenancy/).
|
||||
{: .note }
|
||||
|
||||
|
||||
## Get started with notebooks
|
||||
|
||||
To get started, choose **Notebooks** within OpenSearch Dashboards.
|
||||
|
||||
|
||||
### Step 1: Create a notebook
|
||||
|
||||
A notebook is an interface for creating reports.
|
||||
|
||||
1. Choose **Create notebook** and enter a descriptive name.
|
||||
1. Choose **Create**.
|
||||
|
||||
Choose **Actions** to rename, duplicate, or delete a notebook.
|
||||
|
||||
|
||||
### Step 2: Add a paragraph
|
||||
|
||||
Paragraphs combine code blocks and visualizations for describing data.
|
||||
|
||||
#### Add a code block
|
||||
|
||||
Code blocks support markdown, SQL, and PPL languages.
|
||||
|
||||
Specify the input language on the first line using `%[language type]` syntax.
|
||||
For example, type `%md` for markdown, `%sql` for SQL, and `%ppl` for PPL.
|
||||
|
||||
##### Sample markdown block
|
||||
|
||||
```
|
||||
%md
|
||||
Add in text formatted in markdown.
|
||||
```
|
||||
|
||||
|
||||
|
||||
##### Sample SQL block
|
||||
|
||||
```sql
|
||||
%sql
|
||||
Select * from opensearch_dashboards_sample_data_flights limit 20;
|
||||
```
|
||||
|
||||
|
||||
|
||||
##### Sample PPL block
|
||||
|
||||
```
|
||||
%ppl
|
||||
source=opensearch_dashboards_sample_data_logs | head 20
|
||||
```
|
||||
|
||||
|
||||
|
||||
|
||||
#### Add a visualization
|
||||
|
||||
1. To add a visualization, choose **Add paragraph** and select **Visualization**.
|
||||
1. In **Title**, select your visualization and choose a date range. You can choose multiple timelines to compare and contrast visualizations.
|
||||
1. To run and save a paragraph, choose **Run**.
|
||||
|
||||
|
||||
|
||||
## Paragraph actions
|
||||
|
||||
You can perform the following actions on paragraphs:
|
||||
|
||||
- Add a new paragraph to the top of a report.
|
||||
- Add a new paragraph to the bottom of a report.
|
||||
- Run all the paragraphs at the same time.
|
||||
- Clear the outputs of all paragraphs.
|
||||
- Delete all the paragraphs.
|
||||
- Move paragraphs up and down.
|
||||
|
||||
## Sample notebooks
|
||||
|
||||
We prepared the following sample notebooks that showcase a variety of use cases:
|
||||
|
||||
- Using SQL to query the OpenSearch Dashboards sample flight data.
|
||||
- Using PPL to query the OpenSearch Dashboards sample web logs data.
|
||||
- Using PPL and visualizations to perform sample root cause event analysis on the OpenSearch Dashboards sample web logs data.
|
||||
|
||||
To add a sample notebook, choose **Actions** and select **Add sample notebooks**.
|
||||
|
||||
## Create a report
|
||||
|
||||
You can use notebooks to create PNG and PDF reports:
|
||||
|
||||
1. From the top menu bar, choose **Reporting actions**.
|
||||
1. You can choose to **Download PDF** or **Download PNG**.
|
||||
|
||||
Reports generate asynchronously in the background and might take a few minutes, depending on the size of the report. A notification appears when your report is ready to download.
|
||||
|
||||
1. To create a schedule-based report, choose **Create report definition**. For steps to create a report definition, see [Create reports using a definition]({{site.url}}{{site.baseurl}}/dashboards/reporting#create-reports-using-a-definition).
|
||||
1. To see all your reports, choose **View all reports**.
|
||||
@@ -1,7 +0,0 @@
|
||||
---
|
||||
layout: default
|
||||
title: Javadoc
|
||||
nav_order: 1
|
||||
permalink: /javadoc/
|
||||
redirect_to: https://opensearch.org/docs/javadocs/
|
||||
---
|
||||
@@ -1,156 +0,0 @@
|
||||
---
|
||||
layout: default
|
||||
title: Index transforms
|
||||
nav_order: 20
|
||||
has_children: true
|
||||
redirect_from: /docs/im/index-transforms/
|
||||
has_toc: false
|
||||
---
|
||||
|
||||
# Index transforms
|
||||
|
||||
Whereas index rollup jobs let you reduce data granularity by rolling up old data into condensed indices, transform jobs let you create a different, summarized view of your data centered around certain fields, so you can visualize or analyze the data in different ways.
|
||||
|
||||
For example, suppose that you have airline data that’s scattered across multiple fields and categories, and you want to view a summary of the data that’s organized by airline, quarter, and then price. You can use a transform job to create a new, summarized index that’s organized by those specific categories.
|
||||
|
||||
You can use transform jobs in two ways:
|
||||
|
||||
1. Use the OpenSearch Dashboards UI to specify the index you want to transform and any optional data filters you want to use to filter the original index. Then select the fields you want to transform and the aggregations to use in the transformation. Finally, define a schedule for your job to follow.
|
||||
2. Use the transforms API to specify all the details about your job: the index you want to transform, target groups you want the transformed index to have, any aggregations you want to use to group columns, and a schedule for your job to follow.
|
||||
|
||||
OpenSearch Dashboards provides a detailed summary of the jobs you created and their relevant information, such as associated indices and job statuses. You can review and edit your job’s details and selections before creation, and even preview a transformed index’s data as you’re choosing which fields to transform. However, you can also use the REST API to create transform jobs and preview transform job results, but you must know all of the necessary settings and parameters to submit them as part of the HTTP request body. Submitting your transform job configurations as JSON scripts offers you more portability, allowing you to share and replicate your transform jobs, which is harder to do using OpenSearch Dashboards.
|
||||
|
||||
Your use cases will help you decide which method to use to create transform jobs.
|
||||
|
||||
## Create a transform job
|
||||
|
||||
If you don't have any data in your cluster, you can use the sample flight data within OpenSearch Dashboards to try out transform jobs. Otherwise, after launching OpenSearch Dashboards, choose **Index Management**. Select **Transform Jobs**, and choose **Create Transform Job**.
|
||||
|
||||
### Step 1: Choose indices
|
||||
|
||||
1. In the **Job name and description** section, specify a name and an optional description for your job.
|
||||
2. In the **Indices** section, select the source and target index. You can either select an existing target index or create a new one by entering a name for your new index. If you want to transform just a subset of your source index, choose **Add Data Filter**, and use the OpenSearch query DSL to specify a subset of your source index. For more information about the OpenSearch query DSL, see [query DSL]({{site.url}}{{site.baseurl}}/opensearch/query-dsl/).
|
||||
3. Choose **Next**.
|
||||
|
||||
### Step 2: Select fields to transform
|
||||
|
||||
After specifying the indices, you can select the fields you want to use in your transform job, as well as whether to use groupings or aggregations.
|
||||
|
||||
You can use groupings to place your data into separate buckets in your transformed index. For example, if you want to group all of the airport destinations within the sample flight data, you can group the `DestAirportID` field into a target field of `DestAirportID_terms` field, and you can find the grouped airport IDs in your transformed index after the transform job finishes.
|
||||
|
||||
On the other hand, aggregations let you perform simple calculations. For example, you can include an aggregation in your transform job to define a new field of `sum_of_total_ticket_price` that calculates the sum of all airplane tickets, and then analyze the newly summer data within your transformed index.
|
||||
|
||||
1. In the data table, select the fields you want to transform and expand the drop-down menu within the column header to choose the grouping or aggregation you want to use.
|
||||
|
||||
Currently, transform jobs support histogram, date_histogram, and terms groupings. For more information about groupings, see [Bucket Aggregations]({{site.url}}{{site.baseurl}}/opensearch/bucket-agg/). In terms of aggregations, you can select from `sum`, `avg`, `max`, `min`, `value_count`, `percentiles`, and `scripted_metric`. For more information about aggregations, see [Metric Aggregations]({{site.url}}{{site.baseurl}}/opensearch/metric-agg/).
|
||||
|
||||
2. Repeat step 1 for any other fields that you want to transform.
|
||||
3. After selecting the fields that you want to transform and verifying the transformation, choose **Next**.
|
||||
|
||||
### Step 3: Specify a schedule
|
||||
|
||||
You can configure transform jobs to run once or multiple times on a schedule. Transform jobs are enabled by default.
|
||||
|
||||
1. For **transformation execution frequency**, select **Define by fixed interval** and specify a **transform interval**.
|
||||
2. Under **Advanced**, specify an optional amount for **Pages per execution**. A larger number means more data is processed in each search request, but also uses more memory and causes higher latency. Exceeding allowed memory limits can cause exceptions and errors to occur.
|
||||
3. Choose **Next**.
|
||||
|
||||
### Step 4: Review and confirm details
|
||||
|
||||
After confirming your transform job’s details are correct, choose **Create Transform Job**. If you want to edit any part of the job, choose **Edit** of the section you want to change, and make the necessary changes. You can’t change aggregations or groupings after creating a job.
|
||||
|
||||
### Step 5: Search through the transformed index.
|
||||
|
||||
Once the transform job finishes, you can use the `_search` API operation to search the target index.
|
||||
|
||||
```json
|
||||
GET <target_index>/_search
|
||||
```
|
||||
|
||||
For example, after running a transform job that transforms the flight data based on a `DestAirportID` field, you can run the following request that returns all of the fields that have a value of `SFO`.
|
||||
|
||||
**Sample Request**
|
||||
|
||||
```json
|
||||
GET finished_flight_job/_search
|
||||
{
|
||||
"query": {
|
||||
"match": {
|
||||
"DestAirportID_terms" : "SFO"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Sample Response**
|
||||
|
||||
```json
|
||||
{
|
||||
"took" : 3,
|
||||
"timed_out" : false,
|
||||
"_shards" : {
|
||||
"total" : 5,
|
||||
"successful" : 5,
|
||||
"skipped" : 0,
|
||||
"failed" : 0
|
||||
},
|
||||
"hits" : {
|
||||
"total" : {
|
||||
"value" : 4,
|
||||
"relation" : "eq"
|
||||
},
|
||||
"max_score" : 3.845883,
|
||||
"hits" : [
|
||||
{
|
||||
"_index" : "finished_flight_job",
|
||||
"_type" : "_doc",
|
||||
"_id" : "dSNKGb8U3OJOmC4RqVCi1Q",
|
||||
"_score" : 3.845883,
|
||||
"_source" : {
|
||||
"transform._id" : "sample_flight_job",
|
||||
"transform._doc_count" : 14,
|
||||
"Carrier_terms" : "Dashboards Airlines",
|
||||
"DestAirportID_terms" : "SFO"
|
||||
}
|
||||
},
|
||||
{
|
||||
"_index" : "finished_flight_job",
|
||||
"_type" : "_doc",
|
||||
"_id" : "_D7oqOy7drx9E-MG96U5RA",
|
||||
"_score" : 3.845883,
|
||||
"_source" : {
|
||||
"transform._id" : "sample_flight_job",
|
||||
"transform._doc_count" : 14,
|
||||
"Carrier_terms" : "Logstash Airways",
|
||||
"DestAirportID_terms" : "SFO"
|
||||
}
|
||||
},
|
||||
{
|
||||
"_index" : "finished_flight_job",
|
||||
"_type" : "_doc",
|
||||
"_id" : "YuZ8tOt1OsBA54e84WuAEw",
|
||||
"_score" : 3.6988301,
|
||||
"_source" : {
|
||||
"transform._id" : "sample_flight_job",
|
||||
"transform._doc_count" : 11,
|
||||
"Carrier_terms" : "ES-Air",
|
||||
"DestAirportID_terms" : "SFO"
|
||||
}
|
||||
},
|
||||
{
|
||||
"_index" : "finished_flight_job",
|
||||
"_type" : "_doc",
|
||||
"_id" : "W_-e7bVmH6eu8veJeK8ZxQ",
|
||||
"_score" : 3.6988301,
|
||||
"_source" : {
|
||||
"transform._id" : "sample_flight_job",
|
||||
"transform._doc_count" : 10,
|
||||
"Carrier_terms" : "JetBeats",
|
||||
"DestAirportID_terms" : "SFO"
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
|
||||
```
|
||||
@@ -1,713 +0,0 @@
|
||||
---
|
||||
layout: default
|
||||
title: Transforms APIs
|
||||
nav_order: 45
|
||||
parent: Index transforms
|
||||
has_toc: true
|
||||
---
|
||||
|
||||
# Transforms APIs
|
||||
|
||||
Aside from using OpenSearch Dashboards, you can also use the REST API to create, start, stop, and complete other operations relative to transform jobs.
|
||||
|
||||
#### Table of contents
|
||||
- TOC
|
||||
{:toc}
|
||||
|
||||
## Create a transform job
|
||||
|
||||
Creates a transform job.
|
||||
|
||||
**Sample Request**
|
||||
|
||||
```json
|
||||
PUT _plugins/_transform/<transform_id>
|
||||
|
||||
{
|
||||
"transform": {
|
||||
"enabled": true,
|
||||
"schedule": {
|
||||
"interval": {
|
||||
"period": 1,
|
||||
"unit": "Minutes",
|
||||
"start_time": 1602100553
|
||||
}
|
||||
},
|
||||
"description": "Sample transform job",
|
||||
"source_index": "sample_index",
|
||||
"target_index": "sample_target",
|
||||
"data_selection_query": {
|
||||
"match_all": {}
|
||||
},
|
||||
"page_size": 1,
|
||||
"groups": [
|
||||
{
|
||||
"terms": {
|
||||
"source_field": "customer_gender",
|
||||
"target_field": "gender"
|
||||
}
|
||||
},
|
||||
{
|
||||
"terms": {
|
||||
"source_field": "day_of_week",
|
||||
"target_field": "day"
|
||||
}
|
||||
}
|
||||
],
|
||||
"aggregations": {
|
||||
"quantity": {
|
||||
"sum": {
|
||||
"field": "total_quantity"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Sample Response**
|
||||
|
||||
```json
|
||||
{
|
||||
"_id": "sample",
|
||||
"_version": 7,
|
||||
"_seq_no": 13,
|
||||
"_primary_term": 1,
|
||||
"transform": {
|
||||
"transform_id": "sample",
|
||||
"schema_version": 7,
|
||||
"schedule": {
|
||||
"interval": {
|
||||
"start_time": 1621467964243,
|
||||
"period": 1,
|
||||
"unit": "Minutes"
|
||||
}
|
||||
},
|
||||
"metadata_id": null,
|
||||
"updated_at": 1621467964243,
|
||||
"enabled": true,
|
||||
"enabled_at": 1621467964243,
|
||||
"description": "Sample transform job",
|
||||
"source_index": "sample_index",
|
||||
"data_selection_query": {
|
||||
"match_all": {
|
||||
"boost": 1.0
|
||||
}
|
||||
},
|
||||
"target_index": "sample_target",
|
||||
"roles": [],
|
||||
"page_size": 1,
|
||||
"groups": [
|
||||
{
|
||||
"terms": {
|
||||
"source_field": "customer_gender",
|
||||
"target_field": "gender"
|
||||
}
|
||||
},
|
||||
{
|
||||
"terms": {
|
||||
"source_field": "day_of_week",
|
||||
"target_field": "day"
|
||||
}
|
||||
}
|
||||
],
|
||||
"aggregations": {
|
||||
"quantity": {
|
||||
"sum": {
|
||||
"field": "total_quantity"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
You can specify the following options in the HTTP request body:
|
||||
|
||||
Option | Data Type | Description | Required
|
||||
:--- | :--- | :--- | :---
|
||||
enabled | Boolean | If true, the transform job is enabled at creation. | No
|
||||
schedule | JSON | The schedule the transform job runs on. | Yes
|
||||
start_time | Integer | The Unix epoch time of the transform job's start time. | Yes
|
||||
description | String | Describes the transform job. | No
|
||||
metadata_id | String | Any metadata to be associated with the transform job. | No
|
||||
source_index | String | The source index whose data to transform. | Yes
|
||||
target_index | String | The target index the newly transformed data is added into. You can create a new index or update an existing one. | Yes
|
||||
data_selection_query | JSON | The query DSL to use to filter a subset of the source index for the transform job. See [query DSL]({{site.url}}{{site.baseurl}}/opensearch/query-dsl) for more information. | Yes
|
||||
page_size | Integer | The number of fields to transform at a time. Higher number means higher performance but requires more memory and can cause higher latency. (Default: 1) | Yes
|
||||
groups | Array | Specifies the grouping(s) to use in the transform job. Supported groups are `terms`, `histogram`, and `date_histogram`. For more information, see [Bucket Aggregations]({{site.url}}{{site.baseurl}}/opensearch/bucket-agg). | Yes if not using aggregations
|
||||
source_field | String | The field(s) to transform | Yes
|
||||
aggregations | JSON | The aggregations to use in the transform job. Supported aggregations are: `sum`, `max`, `min`, `value_count`, `avg`, `scripted_metric`, and `percentiles`. For more information, see [Metric Aggregations]({{site.url}}{{site.baseurl}}/opensearch/metric-agg). | Yes if not using groups
|
||||
|
||||
## Update a transform job
|
||||
|
||||
Updates a transform job if `transform_id` already exists.
|
||||
|
||||
**Sample Request**
|
||||
|
||||
```json
|
||||
PUT _plugins/_transform/<transform_id>
|
||||
|
||||
{
|
||||
"transform": {
|
||||
"enabled": true,
|
||||
"schedule": {
|
||||
"interval": {
|
||||
"period": 1,
|
||||
"unit": "Minutes",
|
||||
"start_time": 1602100553
|
||||
}
|
||||
},
|
||||
"description": "Sample transform job",
|
||||
"source_index": "sample_index",
|
||||
"target_index": "sample_target",
|
||||
"data_selection_query": {
|
||||
"match_all": {}
|
||||
},
|
||||
"page_size": 1,
|
||||
"groups": [
|
||||
{
|
||||
"terms": {
|
||||
"source_field": "customer_gender",
|
||||
"target_field": "gender"
|
||||
}
|
||||
},
|
||||
{
|
||||
"terms": {
|
||||
"source_field": "day_of_week",
|
||||
"target_field": "day"
|
||||
}
|
||||
}
|
||||
],
|
||||
"aggregations": {
|
||||
"quantity": {
|
||||
"sum": {
|
||||
"field": "total_quantity"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Sample Response**
|
||||
|
||||
```json
|
||||
{
|
||||
"_id": "sample",
|
||||
"_version": 2,
|
||||
"_seq_no": 14,
|
||||
"_primary_term": 1,
|
||||
"transform": {
|
||||
"transform_id": "sample",
|
||||
"schema_version": 7,
|
||||
"schedule": {
|
||||
"interval": {
|
||||
"start_time": 1602100553,
|
||||
"period": 1,
|
||||
"unit": "Minutes"
|
||||
}
|
||||
},
|
||||
"metadata_id": null,
|
||||
"updated_at": 1621889843874,
|
||||
"enabled": true,
|
||||
"enabled_at": 1621889843874,
|
||||
"description": "Sample transform job",
|
||||
"source_index": "sample_index",
|
||||
"data_selection_query": {
|
||||
"match_all": {
|
||||
"boost": 1.0
|
||||
}
|
||||
},
|
||||
"target_index": "sample_target",
|
||||
"roles": [],
|
||||
"page_size": 1,
|
||||
"groups": [
|
||||
{
|
||||
"terms": {
|
||||
"source_field": "customer_gender",
|
||||
"target_field": "gender"
|
||||
}
|
||||
},
|
||||
{
|
||||
"terms": {
|
||||
"source_field": "day_of_week",
|
||||
"target_field": "day"
|
||||
}
|
||||
}
|
||||
],
|
||||
"aggregations": {
|
||||
"quantity": {
|
||||
"sum": {
|
||||
"field": "total_quantity"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
The `Update` operation supports the following URL parameters:
|
||||
|
||||
Parameter | Description | Required
|
||||
:---| :--- | :---
|
||||
`if_seq_no` | Only perform the transform operation if the last operation that changed the transform job has the specified sequence number. | No
|
||||
`if_primary_term` | Only perform the transform operation if the last operation that changed the transform job has the specified sequence term. | No
|
||||
|
||||
## Get a transform job's details
|
||||
|
||||
Returns a transform job's details.
|
||||
|
||||
**Sample Request**
|
||||
|
||||
```json
|
||||
GET _plugins/_transform/<transform_id>
|
||||
```
|
||||
|
||||
**Sample Response**
|
||||
|
||||
```json
|
||||
{
|
||||
"_id": "sample",
|
||||
"_version": 7,
|
||||
"_seq_no": 13,
|
||||
"_primary_term": 1,
|
||||
"transform": {
|
||||
"transform_id": "sample",
|
||||
"schema_version": 7,
|
||||
"schedule": {
|
||||
"interval": {
|
||||
"start_time": 1621467964243,
|
||||
"period": 1,
|
||||
"unit": "Minutes"
|
||||
}
|
||||
},
|
||||
"metadata_id": null,
|
||||
"updated_at": 1621467964243,
|
||||
"enabled": true,
|
||||
"enabled_at": 1621467964243,
|
||||
"description": "Sample transform job",
|
||||
"source_index": "sample_index",
|
||||
"data_selection_query": {
|
||||
"match_all": {
|
||||
"boost": 1.0
|
||||
}
|
||||
},
|
||||
"target_index": "sample_target",
|
||||
"roles": [],
|
||||
"page_size": 1,
|
||||
"groups": [
|
||||
{
|
||||
"terms": {
|
||||
"source_field": "customer_gender",
|
||||
"target_field": "gender"
|
||||
}
|
||||
},
|
||||
{
|
||||
"terms": {
|
||||
"source_field": "day_of_week",
|
||||
"target_field": "day"
|
||||
}
|
||||
}
|
||||
],
|
||||
"aggregations": {
|
||||
"quantity": {
|
||||
"sum": {
|
||||
"field": "total_quantity"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
You can also get details of all transform jobs by omitting `transform_id`.
|
||||
|
||||
**Sample Request**
|
||||
|
||||
```json
|
||||
GET _plugins/_transform/
|
||||
```
|
||||
|
||||
**Sample Response**
|
||||
|
||||
```json
|
||||
{
|
||||
"total_transforms": 1,
|
||||
"transforms": [
|
||||
{
|
||||
"_id": "sample",
|
||||
"_seq_no": 13,
|
||||
"_primary_term": 1,
|
||||
"transform": {
|
||||
"transform_id": "sample",
|
||||
"schema_version": 7,
|
||||
"schedule": {
|
||||
"interval": {
|
||||
"start_time": 1621467964243,
|
||||
"period": 1,
|
||||
"unit": "Minutes"
|
||||
}
|
||||
},
|
||||
"metadata_id": null,
|
||||
"updated_at": 1621467964243,
|
||||
"enabled": true,
|
||||
"enabled_at": 1621467964243,
|
||||
"description": "Sample transform job",
|
||||
"source_index": "sample_index",
|
||||
"data_selection_query": {
|
||||
"match_all": {
|
||||
"boost": 1.0
|
||||
}
|
||||
},
|
||||
"target_index": "sample_target",
|
||||
"roles": [],
|
||||
"page_size": 1,
|
||||
"groups": [
|
||||
{
|
||||
"terms": {
|
||||
"source_field": "customer_gender",
|
||||
"target_field": "gender"
|
||||
}
|
||||
},
|
||||
{
|
||||
"terms": {
|
||||
"source_field": "day_of_week",
|
||||
"target_field": "day"
|
||||
}
|
||||
}
|
||||
],
|
||||
"aggregations": {
|
||||
"quantity": {
|
||||
"sum": {
|
||||
"field": "total_quantity"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
You can specify these options as the `GET` API operation’s URL parameters to filter results:
|
||||
|
||||
Parameter | Description | Required
|
||||
:--- | :--- | :---
|
||||
from | The starting index to search from. (Default: 0) | No
|
||||
size | Specifies the amount of results to return (Default: 10) | No
|
||||
search |The search term to use to filter results. | No
|
||||
sortField | The field to sort results with. | No
|
||||
sortDirection | Specifies the direction to sort results in. Can be `ASC` or `DESC`. (Default: ASC) | No
|
||||
|
||||
For example, this request returns two results starting from the eighth index.
|
||||
|
||||
**Sample Request**
|
||||
|
||||
```json
|
||||
GET _plugins/_transform?size=2&from=8
|
||||
```
|
||||
|
||||
**Sample Response**
|
||||
|
||||
```json
|
||||
{
|
||||
"total_transforms": 18,
|
||||
"transforms": [
|
||||
{
|
||||
"_id": "sample8",
|
||||
"_seq_no": 93,
|
||||
"_primary_term": 1,
|
||||
"transform": {
|
||||
"transform_id": "sample8",
|
||||
"schema_version": 7,
|
||||
"schedule": {
|
||||
"interval": {
|
||||
"start_time": 1622063596812,
|
||||
"period": 1,
|
||||
"unit": "Minutes"
|
||||
}
|
||||
},
|
||||
"metadata_id": "y4hFAB2ZURQ2dzY7BAMxWA",
|
||||
"updated_at": 1622063657233,
|
||||
"enabled": false,
|
||||
"enabled_at": null,
|
||||
"description": "Sample transform job",
|
||||
"source_index": "sample_index3",
|
||||
"data_selection_query": {
|
||||
"match_all": {
|
||||
"boost": 1.0
|
||||
}
|
||||
},
|
||||
"target_index": "sample_target3",
|
||||
"roles": [],
|
||||
"page_size": 1,
|
||||
"groups": [
|
||||
{
|
||||
"terms": {
|
||||
"source_field": "customer_gender",
|
||||
"target_field": "gender"
|
||||
}
|
||||
},
|
||||
{
|
||||
"terms": {
|
||||
"source_field": "day_of_week",
|
||||
"target_field": "day"
|
||||
}
|
||||
}
|
||||
],
|
||||
"aggregations": {
|
||||
"quantity": {
|
||||
"sum": {
|
||||
"field": "total_quantity"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
{
|
||||
"_id": "sample9",
|
||||
"_seq_no": 98,
|
||||
"_primary_term": 1,
|
||||
"transform": {
|
||||
"transform_id": "sample9",
|
||||
"schema_version": 7,
|
||||
"schedule": {
|
||||
"interval": {
|
||||
"start_time": 1622063598065,
|
||||
"period": 1,
|
||||
"unit": "Minutes"
|
||||
}
|
||||
},
|
||||
"metadata_id": "x8tCIiYMTE3veSbIJkit5A",
|
||||
"updated_at": 1622063658388,
|
||||
"enabled": false,
|
||||
"enabled_at": null,
|
||||
"description": "Sample transform job",
|
||||
"source_index": "sample_index4",
|
||||
"data_selection_query": {
|
||||
"match_all": {
|
||||
"boost": 1.0
|
||||
}
|
||||
},
|
||||
"target_index": "sample_target4",
|
||||
"roles": [],
|
||||
"page_size": 1,
|
||||
"groups": [
|
||||
{
|
||||
"terms": {
|
||||
"source_field": "customer_gender",
|
||||
"target_field": "gender"
|
||||
}
|
||||
},
|
||||
{
|
||||
"terms": {
|
||||
"source_field": "day_of_week",
|
||||
"target_field": "day"
|
||||
}
|
||||
}
|
||||
],
|
||||
"aggregations": {
|
||||
"quantity": {
|
||||
"sum": {
|
||||
"field": "total_quantity"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
## Start a transform job
|
||||
|
||||
Transform jobs created using the API are automatically enabled, but if you ever need to enable a job, you can use the `start` API operation.
|
||||
|
||||
**Sample Request**
|
||||
|
||||
```json
|
||||
POST _plugins/_transform/<transform_id>/_start
|
||||
```
|
||||
|
||||
**Sample Response**
|
||||
|
||||
```json
|
||||
{
|
||||
"acknowledged": true
|
||||
}
|
||||
```
|
||||
|
||||
## Stop a transform job
|
||||
|
||||
Stops/disables a transform job.
|
||||
|
||||
**Sample Request**
|
||||
|
||||
```json
|
||||
POST _plugins/_transform/<transform_id>/_stop
|
||||
```
|
||||
|
||||
**Sample Response**
|
||||
|
||||
```json
|
||||
{
|
||||
"acknowledged": true
|
||||
}
|
||||
```
|
||||
|
||||
## Get the status of a transform job
|
||||
|
||||
Returns the status and metadata of a transform job.
|
||||
|
||||
**Sample Request**
|
||||
|
||||
```json
|
||||
GET _plugins/_transform/<transform_id>/_explain
|
||||
```
|
||||
|
||||
**Sample Response**
|
||||
|
||||
```json
|
||||
{
|
||||
"sample": {
|
||||
"metadata_id": "PzmjweME5xbgkenl9UpsYw",
|
||||
"transform_metadata": {
|
||||
"transform_id": "sample",
|
||||
"last_updated_at": 1621883525873,
|
||||
"status": "finished",
|
||||
"failure_reason": "null",
|
||||
"stats": {
|
||||
"pages_processed": 0,
|
||||
"documents_processed": 0,
|
||||
"documents_indexed": 0,
|
||||
"index_time_in_millis": 0,
|
||||
"search_time_in_millis": 0
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Preview a transform job's results
|
||||
|
||||
Returns a preview of what a transformed index would look like.
|
||||
|
||||
**Sample Request**
|
||||
|
||||
```json
|
||||
POST _plugins/_transform/_preview
|
||||
|
||||
{
|
||||
"transform": {
|
||||
"enabled": false,
|
||||
"schedule": {
|
||||
"interval": {
|
||||
"period": 1,
|
||||
"unit": "Minutes",
|
||||
"start_time": 1602100553
|
||||
}
|
||||
},
|
||||
"description": "test transform",
|
||||
"source_index": "sample_index",
|
||||
"target_index": "sample_target",
|
||||
"data_selection_query": {
|
||||
"match_all": {}
|
||||
},
|
||||
"page_size": 10,
|
||||
"groups": [
|
||||
{
|
||||
"terms": {
|
||||
"source_field": "customer_gender",
|
||||
"target_field": "gender"
|
||||
}
|
||||
},
|
||||
{
|
||||
"terms": {
|
||||
"source_field": "day_of_week",
|
||||
"target_field": "day"
|
||||
}
|
||||
}
|
||||
],
|
||||
"aggregations": {
|
||||
"quantity": {
|
||||
"sum": {
|
||||
"field": "total_quantity"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Sample Response**
|
||||
|
||||
```json
|
||||
{
|
||||
"documents" : [
|
||||
{
|
||||
"quantity" : 862.0,
|
||||
"gender" : "FEMALE",
|
||||
"day" : "Friday"
|
||||
},
|
||||
{
|
||||
"quantity" : 682.0,
|
||||
"gender" : "FEMALE",
|
||||
"day" : "Monday"
|
||||
},
|
||||
{
|
||||
"quantity" : 772.0,
|
||||
"gender" : "FEMALE",
|
||||
"day" : "Saturday"
|
||||
},
|
||||
{
|
||||
"quantity" : 669.0,
|
||||
"gender" : "FEMALE",
|
||||
"day" : "Sunday"
|
||||
},
|
||||
{
|
||||
"quantity" : 887.0,
|
||||
"gender" : "FEMALE",
|
||||
"day" : "Thursday"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
## Delete a transform job
|
||||
|
||||
Deletes a transform job. This operation does not delete the source or target indices.
|
||||
|
||||
**Sample Request**
|
||||
|
||||
```json
|
||||
DELETE _plugins/_transform/<transform_id>
|
||||
```
|
||||
|
||||
**Sample Response**
|
||||
|
||||
```json
|
||||
{
|
||||
"took": 205,
|
||||
"errors": false,
|
||||
"items": [
|
||||
{
|
||||
"delete": {
|
||||
"_index": ".opensearch-ism-config",
|
||||
"_type": "_doc",
|
||||
"_id": "sample",
|
||||
"_version": 4,
|
||||
"result": "deleted",
|
||||
"forced_refresh": true,
|
||||
"_shards": {
|
||||
"total": 2,
|
||||
"successful": 1,
|
||||
"failed": 0
|
||||
},
|
||||
"_seq_no": 6,
|
||||
"_primary_term": 1,
|
||||
"status": 200
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
@@ -1,49 +0,0 @@
|
||||
---
|
||||
layout: default
|
||||
title: Settings
|
||||
parent: Index State Management
|
||||
redirect_from: /docs/ism/settings/
|
||||
nav_order: 4
|
||||
---
|
||||
|
||||
# ISM settings
|
||||
|
||||
We don't recommend changing these settings; the defaults should work well for most use cases.
|
||||
|
||||
Index State Management (ISM) stores its configuration in the `.opendistro-ism-config` index. Don't modify this index without using the [ISM API operations]({{site.url}}{{site.baseurl}}/im-plugin/ism/api/).
|
||||
|
||||
All settings are available using the OpenSearch `_cluster/settings` operation. None require a restart, and all can be marked `persistent` or `transient`.
|
||||
|
||||
Setting | Default | Description
|
||||
:--- | :--- | :---
|
||||
`plugins.index_state_management.enabled` | True | Specifies whether ISM is enabled or not.
|
||||
`plugins.index_state_management.job_interval` | 5 minutes | The interval at which the managed index jobs are run.
|
||||
`plugins.index_state_management.coordinator.sweep_period` | 10 minutes | How often the routine background sweep is run.
|
||||
`plugins.index_state_management.coordinator.backoff_millis` | 50 milliseconds | The backoff time between retries for failures in the `ManagedIndexCoordinator` (such as when we update managed indices).
|
||||
`plugins.index_state_management.coordinator.backoff_count` | 2 | The count of retries for failures in the `ManagedIndexCoordinator`.
|
||||
`plugins.index_state_management.history.enabled` | True | Specifies whether audit history is enabled or not. The logs from ISM are automatically indexed to a logs document.
|
||||
`plugins.index_state_management.history.max_docs` | 2,500,000 | The maximum number of documents before rolling over the audit history index.
|
||||
`plugins.index_state_management.history.max_age` | 24 hours | The maximum age before rolling over the audit history index.
|
||||
`plugins.index_state_management.history.rollover_check_period` | 8 hours | The time between rollover checks for the audit history index.
|
||||
`plugins.index_state_management.history.rollover_retention_period` | 30 days | How long audit history indices are kept.
|
||||
`plugins.index_state_management.allow_list` | All actions | List of actions that you can use.
|
||||
|
||||
|
||||
## Audit history indices
|
||||
|
||||
If you don't want to disable ISM audit history or shorten the retention period, you can create an [index template]({{site.url}}{{site.baseurl}}/opensearch/index-templates/) to reduce the shard count of the history indices:
|
||||
|
||||
```json
|
||||
PUT _index_template/ism_history_indices
|
||||
{
|
||||
"index_patterns": [
|
||||
".opendistro-ism-managed-index-history-*"
|
||||
],
|
||||
"template": {
|
||||
"settings": {
|
||||
"number_of_shards": 1,
|
||||
"number_of_replicas": 0
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
+5
-27
@@ -60,7 +60,7 @@
|
||||
{%- for node in pages_list -%}
|
||||
{%- if node.parent == nil -%}
|
||||
{%- unless node.nav_exclude -%}
|
||||
<li class="nav-list-item{% if page.collection == include.key and page.url == node.url or page.parent == node.title or page.grand_parent == node.title %} active{% endif %}">
|
||||
<li class="nav-list-item{% if page.url == node.url or page.parent == node.title or page.grand_parent == node.title %} active{% endif %}">
|
||||
{%- if node.has_children -%}
|
||||
<a href="#" class="nav-list-expander"><svg viewBox="0 0 24 24"><use xlink:href="#svg-arrow-right"></use></svg></a>
|
||||
{%- endif -%}
|
||||
@@ -90,36 +90,14 @@
|
||||
</li>
|
||||
{%- endunless -%}
|
||||
{%- endfor -%}
|
||||
|
||||
</ul>
|
||||
{%- endif -%}
|
||||
</li>
|
||||
{%- endunless -%}
|
||||
{%- endif -%}
|
||||
{%- endfor -%}
|
||||
<li class="nav-list-item">
|
||||
<a href="https://opensearch.org/docs/javadocs/" target="_blank" class="nav-list-link">Javadoc <svg class="external-arrow" width="16" height="16" fill="#002A3A"><use xlink:href="#external-arrow"></use></svg></a>
|
||||
</li>
|
||||
</ul>
|
||||
|
||||
{%- if page.collection == include.key -%}
|
||||
|
||||
{%- for node in pages_list -%}
|
||||
{%- if node.parent == nil -%}
|
||||
{%- if page.parent == node.title or page.grand_parent == node.title -%}
|
||||
{%- assign first_level_url = node.url | absolute_url -%}
|
||||
{%- endif -%}
|
||||
{%- if node.has_children -%}
|
||||
{%- assign children_list = pages_list | where: "parent", node.title -%}
|
||||
{%- for child in children_list -%}
|
||||
{%- if child.has_children -%}
|
||||
{%- if page.url == child.url or page.parent == child.title and page.grand_parent == child.parent -%}
|
||||
{%- assign second_level_url = child.url | absolute_url -%}
|
||||
{%- endif -%}
|
||||
{%- endif -%}
|
||||
{%- endfor -%}
|
||||
{%- endif -%}
|
||||
{%- endif -%}
|
||||
{%- endfor -%}
|
||||
|
||||
{% if page.has_children == true and page.has_toc != false %}
|
||||
{%- assign toc_list = pages_list | where: "parent", page.title | where: "grand_parent", page.parent -%}
|
||||
{%- endif -%}
|
||||
|
||||
{%- endif -%}
|
||||
|
||||
+32
-29
@@ -38,6 +38,13 @@ layout: table_wrappers
|
||||
<path d="M13 2H6a2 2 0 0 0-2 2v16a2 2 0 0 0 2 2h12a2 2 0 0 0 2-2V9z"></path><polyline points="13 2 13 9 20 9"></polyline>
|
||||
</svg>
|
||||
</symbol>
|
||||
<symbol id="external-arrow" viewBox="0 0 16 16">
|
||||
<title>External</title>
|
||||
<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" fill="currentColor" viewBox="0 0 16 16">
|
||||
<path fill-rule="evenodd" d="M8.636 3.5a.5.5 0 0 0-.5-.5H1.5A1.5 1.5 0 0 0 0 4.5v10A1.5 1.5 0 0 0 1.5 16h10a1.5 1.5 0 0 0 1.5-1.5V7.864a.5.5 0 0 0-1 0V14.5a.5.5 0 0 1-.5.5h-10a.5.5 0 0 1-.5-.5v-10a.5.5 0 0 1 .5-.5h6.636a.5.5 0 0 0 .5-.5z"/>
|
||||
<path fill-rule="evenodd" d="M16 .5a.5.5 0 0 0-.5-.5h-5a.5.5 0 0 0 0 1h3.793L6.146 9.146a.5.5 0 1 0 .708.708L15 1.707V5.5a.5.5 0 0 0 1 0v-5z"/>
|
||||
</svg>
|
||||
</symbol>
|
||||
</svg>
|
||||
|
||||
<div class="side-bar">
|
||||
@@ -48,14 +55,6 @@ layout: table_wrappers
|
||||
</a>
|
||||
</div>
|
||||
<nav role="navigation" aria-label="Main" id="site-nav" class="site-nav">
|
||||
{% assign pages_top_size = site.html_pages
|
||||
| where_exp:"item", "item.title != nil"
|
||||
| where_exp:"item", "item.parent == nil"
|
||||
| where_exp:"item", "item.nav_exclude != true"
|
||||
| size %}
|
||||
{% if pages_top_size > 0 %}
|
||||
{% include nav.html pages=site.html_pages key=nil %}
|
||||
{% endif %}
|
||||
{% if site.just_the_docs.collections %}
|
||||
{% assign collections_size = site.just_the_docs.collections | size %}
|
||||
{% for collection_entry in site.just_the_docs.collections %}
|
||||
@@ -63,31 +62,19 @@ layout: table_wrappers
|
||||
{% assign collection_value = collection_entry[1] %}
|
||||
{% assign collection = site[collection_key] %}
|
||||
{% if collection_value.nav_exclude != true %}
|
||||
{% if collections_size > 1 or pages_top_size > 0 %}
|
||||
{% if collection_value.nav_fold == true %}
|
||||
<ul class="nav-list nav-category-list">
|
||||
<li class="nav-list-item{% if page.collection == collection_key %} active{% endif %}">
|
||||
{%- if collection.size > 0 -%}
|
||||
<a href="#" class="nav-list-expander"><svg viewBox="0 0 24 24"><use xlink:href="#svg-arrow-right"></use></svg></a>
|
||||
{%- endif -%}
|
||||
<div class="nav-category">{{ collection_value.name }}</div>
|
||||
{% include nav.html pages=collection key=collection_key %}
|
||||
</li>
|
||||
</ul>
|
||||
{% else %}
|
||||
<div class="nav-category">{{ collection_value.name }}</div>
|
||||
{% include nav.html pages=collection key=collection_key %}
|
||||
{% endif %}
|
||||
{% else %}
|
||||
{% include nav.html pages=collection key=collection_key %}
|
||||
{% if collections_size > 1 %}
|
||||
<div class="nav-category">{{ collection_value.name }}</div>
|
||||
{% endif %}
|
||||
{% include nav.html pages=collection %}
|
||||
{% endif %}
|
||||
{% endfor %}
|
||||
{% else %}
|
||||
{% include nav.html pages=site.html_pages %}
|
||||
{% endif %}
|
||||
</nav>
|
||||
<footer class="site-footer">
|
||||
<p class="text-small text-grey-dk-100">See a problem? Submit <a href="https://github.com/opensearch-project/documentation-website/issues">issues</a> or <a href="https://github.com/opensearch-project/documentation-website/edit/main/{{ page.path }}">edit this page</a> on <a href="https://github.com/opensearch-project/documentation-website/">GitHub</a>.</p>
|
||||
<p class="text-small text-grey-dk-100 mb-0">© 2021 OpenSearch contributors. This documentation is under the Apache License 2.0.</p>
|
||||
<p class="text-small text-grey-dk-100">See a problem? Submit <a href="https://github.com/opensearch-project/documentation-website/issues">issues</a> or <a href="https://github.com/opensearch-project/documentation-website/edit/main/{{ page.path }}">edit this page</a> on GitHub.</p>
|
||||
<p class="text-small text-grey-dk-100 mb-0">© Amazon Web Services, Inc. or its affiliates. All rights reserved.</p>
|
||||
</footer>
|
||||
</div>
|
||||
<div class="main" id="top">
|
||||
@@ -123,6 +110,21 @@ layout: table_wrappers
|
||||
<div id="main-content-wrap" class="main-content-wrap">
|
||||
{% unless page.url == "/" %}
|
||||
{% if page.parent %}
|
||||
{%- for node in pages_list -%}
|
||||
{%- if node.parent == nil -%}
|
||||
{%- if page.parent == node.title or page.grand_parent == node.title -%}
|
||||
{%- assign first_level_url = node.url | absolute_url -%}
|
||||
{%- endif -%}
|
||||
{%- if node.has_children -%}
|
||||
{%- assign children_list = pages_list | where: "parent", node.title -%}
|
||||
{%- for child in children_list -%}
|
||||
{%- if page.url == child.url or page.parent == child.title -%}
|
||||
{%- assign second_level_url = child.url | absolute_url -%}
|
||||
{%- endif -%}
|
||||
{%- endfor -%}
|
||||
{%- endif -%}
|
||||
{%- endif -%}
|
||||
{%- endfor -%}
|
||||
<nav aria-label="Breadcrumb" class="breadcrumb-nav">
|
||||
<ol class="breadcrumb-nav-list">
|
||||
{% if page.grand_parent %}
|
||||
@@ -140,7 +142,7 @@ layout: table_wrappers
|
||||
{% if site.heading_anchors != false %}
|
||||
{% include vendor/anchor_headings.html html=content beforeHeading="true" anchorBody="<svg viewBox=\"0 0 16 16\" aria-hidden=\"true\"><use xlink:href=\"#svg-link\"></use></svg>" anchorClass="anchor-heading" anchorAttrs="aria-labelledby=\"%html_id%\"" %}
|
||||
{% else %}
|
||||
<p class="warning" style="margin-top: 0">This documentation remains in a beta state. It has content gaps and might contain bugs.</p>
|
||||
<p class="warning" style="margin-top: 0">Like OpenSearch itself, this documentation is a beta. It has content gaps and might contain bugs.</p>
|
||||
{{ content }}
|
||||
{% endif %}
|
||||
|
||||
@@ -148,7 +150,8 @@ layout: table_wrappers
|
||||
<hr>
|
||||
<h2 class="text-delta">Table of contents</h2>
|
||||
<ul>
|
||||
{% for child in toc_list %}
|
||||
{%- assign children_list = pages_list | where: "parent", page.title | where: "grand_parent", page.parent -%}
|
||||
{% for child in children_list %}
|
||||
<li>
|
||||
<a href="{{ child.url | absolute_url }}">{{ child.title }}</a>{% if child.summary %} - {{ child.summary }}{% endif %}
|
||||
</li>
|
||||
|
||||
@@ -1,42 +0,0 @@
|
||||
---
|
||||
layout: default
|
||||
title: Settings
|
||||
parent: Anomaly detection
|
||||
nav_order: 4
|
||||
---
|
||||
|
||||
# Settings
|
||||
|
||||
The anomaly detection plugin adds several settings to the standard OpenSearch cluster settings.
|
||||
The settings are dynamic, so you can change the default behavior of the plugin without restarting your cluster.
|
||||
You can mark settings as `persistent` or `transient`.
|
||||
|
||||
For example, to update the retention period of the result index:
|
||||
|
||||
```json
|
||||
PUT _cluster/settings
|
||||
{
|
||||
"transient": {
|
||||
"plugins.anomaly_detection.ad_result_history_retention_period": "5m"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Setting | Default | Description
|
||||
:--- | :--- | :---
|
||||
`plugins.anomaly_detection.enabled` | True | Whether the anomaly detection plugin is enabled or not. If disabled, all detectors immediately stop running.
|
||||
`plugins.anomaly_detection.max_anomaly_detectors` | 1,000 | The maximum number of non-high cardinality detectors (no category field) users can create.
|
||||
`plugins.anomaly_detection.max_multi_entity_anomaly_detectors` | 10 | The maximum number of high cardinality detectors (with category field) in a cluster.
|
||||
`plugins.anomaly_detection.max_anomaly_features` | 5 | The maximum number of features for a detector.
|
||||
`plugins.anomaly_detection.ad_result_history_rollover_period` | 12h | How often the rollover condition is checked. If `true`, the plugin rolls over the result index to a new index.
|
||||
`plugins.anomaly_detection.ad_result_history_max_docs` | 250000000 | The maximum number of documents in one result index. The plugin only counts refreshed documents in the primary shards.
|
||||
`plugins.anomaly_detection.ad_result_history_retention_period` | 30d | The maximum age of the result index. If its age exceeds the threshold, the plugin deletes the rolled over result index. If the cluster has only one result index, the plugin keeps the index even if it's older than its configured retention period.
|
||||
`plugins.anomaly_detection.max_entities_per_query` | 1,000 | The maximum unique values per detection interval for high cardinality detectors. By default, if the category field has more than 1,000 unique values in a detector interval, the plugin selects the top 1,000 values and orders them by `doc_count`.
|
||||
`plugins.anomaly_detection.max_entities_for_preview` | 30 | The maximum unique category field values displayed with the preview operation for high cardinality detectors. If the category field has more than 30 unique values, the plugin selects the top 30 values and orders them by `doc_count`.
|
||||
`plugins.anomaly_detection.max_primary_shards` | 10 | The maximum number of primary shards an anomaly detection index can have.
|
||||
`plugins.anomaly_detection.filter_by_backend_roles` | False | When you enable the security plugin and set this to `true`, the plugin filters results based on the user's backend role(s).
|
||||
`plugins.anomaly_detection.max_cache_miss_handling_per_second` | 100 | High cardinality detectors use a cache to store active models. In the event of a cache miss, the cache gets the models from the model checkpoint index. Use this setting to limit the rate of fetching models. Because the thread pool for a GET operation has a queue of 1,000, we recommend setting this value below 1,000.
|
||||
`plugins.anomaly_detection.max_batch_task_per_node` | 2 | Starting a historical detector triggers a batch task. This setting is the number of batch tasks that you can run per data node. You can tune this setting from 1 to 1000. If the data nodes can't support all batch tasks and you're not sure if the data nodes are capable of running more historical detectors, add more data nodes instead of changing this setting to a higher value.
|
||||
`plugins.anomaly_detection.max_old_ad_task_docs_per_detector` | 10 | You can run the same historical detector many times. For each run, the anomaly detection plugin creates a new task. This setting is the number of previous tasks the plugin keeps. Set this value to at least 1 to track its last run. You can keep a maximum of 1,000 old tasks to avoid overwhelming the cluster.
|
||||
`plugins.anomaly_detection.batch_task_piece_size` | 1000 | The date range for a historical task is split into smaller pieces and the anomaly detection plugin runs the task piece by piece. Each piece contains 1,000 detection intervals by default. For example, if detector interval is 1 minute and one piece is 1000 minutes, the feature data is queried every 1,000 minutes. You can change this setting from 1 to 10,000.
|
||||
`plugins.anomaly_detection.batch_task_piece_interval_seconds` | 5 | Add a time interval between historical detector tasks. This interval prevents the task from consuming too much of the available resources and starving other operations like search and bulk index. You can change this setting from 1 to 600 seconds.
|
||||
@@ -1,59 +0,0 @@
|
||||
---
|
||||
layout: default
|
||||
title: Management
|
||||
parent: Alerting
|
||||
nav_order: 5
|
||||
---
|
||||
|
||||
# Management
|
||||
|
||||
|
||||
## Alerting indices
|
||||
|
||||
The alerting feature creates several indices and one alias. The security plugin demo script configures them as [system indices]({{site.url}}{{site.baseurl}}/security-plugin/configuration/system-indices/) for an extra layer of protection. Don't delete these indices or modify their contents without using the alerting APIs.
|
||||
|
||||
Index | Purpose
|
||||
:--- | :---
|
||||
`.opendistro-alerting-alerts` | Stores ongoing alerts.
|
||||
`.opendistro-alerting-alert-history-<date>` | Stores a history of completed alerts.
|
||||
`.opendistro-alerting-config` | Stores monitors, triggers, and destinations. [Take a snapshot]({{site.url}}{{site.baseurl}}/opensearch/snapshot-restore) of this index to back up your alerting configuration.
|
||||
`.opendistro-alerting-alert-history-write` (alias) | Provides a consistent URI for the `.opendistro-alerting-alert-history-<date>` index.
|
||||
|
||||
All alerting indices are hidden by default. For a summary, make the following request:
|
||||
|
||||
```
|
||||
GET _cat/indices?expand_wildcards=open,hidden
|
||||
```
|
||||
|
||||
|
||||
## Alerting settings
|
||||
|
||||
We don't recommend changing these settings; the defaults should work well for most use cases.
|
||||
|
||||
All settings are available using the OpenSearch `_cluster/settings` API. None require a restart, and all can be marked `persistent` or `transient`.
|
||||
|
||||
Setting | Default | Description
|
||||
:--- | :--- | :---
|
||||
`plugins.scheduled_jobs.enabled` | true | Whether the alerting plugin is enabled or not. If disabled, all monitors immediately stop running.
|
||||
`plugins.alerting.index_timeout` | 60s | The timeout for creating monitors and destinations using the REST APIs.
|
||||
`plugins.alerting.request_timeout` | 10s | The timeout for miscellaneous requests from the plugin.
|
||||
`plugins.alerting.action_throttle_max_value` | 24h | The maximum amount of time you can set for action throttling. By default, this value displays as 1440 minutes in OpenSearch Dashboards.
|
||||
`plugins.alerting.input_timeout` | 30s | How long the monitor can take to issue the search request.
|
||||
`plugins.alerting.bulk_timeout` | 120s | How long the monitor can write alerts to the alert index.
|
||||
`plugins.alerting.alert_backoff_count` | 3 | The number of retries for writing alerts before the operation fails.
|
||||
`plugins.alerting.alert_backoff_millis` | 50ms | The amount of time to wait between retries---increases exponentially after each failed retry.
|
||||
`plugins.alerting.alert_history_rollover_period` | 12h | How frequently to check whether the `.opendistro-alerting-alert-history-write` alias should roll over to a new history index and whether the Alerting plugin should delete any history indices.
|
||||
`plugins.alerting.move_alerts_backoff_millis` | 250 | The amount of time to wait between retries---increases exponentially after each failed retry.
|
||||
`plugins.alerting.move_alerts_backoff_count` | 3 | The number of retries for moving alerts to a deleted state after their monitor or trigger has been deleted.
|
||||
`plugins.alerting.monitor.max_monitors` | 1000 | The maximum number of monitors users can create.
|
||||
`plugins.alerting.alert_history_max_age` | 30d | The oldest document to store in the `.opendistro-alert-history-<date>` index before creating a new index. If the number of alerts in this time period does not exceed `alert_history_max_docs`, alerting creates one history index per period (e.g. one index every 30 days).
|
||||
`plugins.alerting.alert_history_max_docs` | 1000 | The maximum number of alerts to store in the `.opendistro-alert-history-<date>` index before creating a new index.
|
||||
`plugins.alerting.alert_history_enabled` | true | Whether to create `.opendistro-alerting-alert-history-<date>` indices.
|
||||
`plugins.alerting.alert_history_retention_period` | 60d | The amount of time to keep history indices before automatically deleting them.
|
||||
`plugins.alerting.destination.allow_list` | ["chime", "slack", "custom_webhook", "email", "test_action"] | The list of allowed destinations. If you don't want to allow users to a certain type of destination, you can remove it from this list, but we recommend leaving this setting as-is.
|
||||
`plugins.alerting.filter_by_backend_roles` | "false" | Restricts access to monitors by backend role. See [Alerting security]({{site.url}}{{site.baseurl}}/monitoring-plugins/alerting/security/).
|
||||
`plugins.scheduled_jobs.sweeper.period` | 5m | The alerting feature uses its "job sweeper" component to periodically check for new or updated jobs. This setting is the rate at which the sweeper checks to see if any jobs (monitors) have changed and need to be rescheduled.
|
||||
`plugins.scheduled_jobs.sweeper.page_size` | 100 | The page size for the sweeper. You shouldn't need to change this value.
|
||||
`plugins.scheduled_jobs.sweeper.backoff_millis` | 50ms | The amount of time the sweeper waits between retries---increases exponentially after each failed retry.
|
||||
`plugins.scheduled_jobs.sweeper.retry_count` | 3 | The total number of times the sweeper should retry before throwing an error.
|
||||
`plugins.scheduled_jobs.request_timeout` | 10s | The timeout for the request that sweeps shards for jobs.
|
||||
@@ -1,301 +0,0 @@
|
||||
---
|
||||
layout: default
|
||||
title: Data streams
|
||||
nav_order: 13
|
||||
---
|
||||
|
||||
# Data streams
|
||||
|
||||
If you're ingesting continuously generated time-series data such as logs, events, and metrics into OpenSearch, you're likely in a scenario where:
|
||||
|
||||
- You’re ingesting documents that grow rapidly.
|
||||
- You don’t need to update older documents.
|
||||
- Your searches generally target the newer documents.
|
||||
|
||||
A typical workflow to manage time-series data is as follows:
|
||||
|
||||
- To split your data into an index for each day, use the rollover operation.
|
||||
- To perform searches on a virtual index name that gets expanded to the underlying indices, create an [index alias]({{site.url}}{{site.baseurl}}/opensearch/index-alias/).
|
||||
- To perform a write operation on an index alias, configure the latest index as the write index.
|
||||
- To configure new indices, extract common mappings and settings into an [index template]({{site.url}}{{site.baseurl}}/opensearch/index-templates/).
|
||||
|
||||
Even after you perform all these operations, you’re still not enforcing the best practices when dealing with time-series data. For example, you can modify the indices directly. You’re able to ingest documents without a timestamp field, which might result in slower queries.
|
||||
|
||||
Data streams abstract the complexity and enforce the best practices for managing time-series data.
|
||||
|
||||
With data streams, you can store append-only time-series data across multiple indices with a single endpoint for ingesting and searching data. It replaces index aliases for time-series data.
|
||||
|
||||
## About data streams
|
||||
|
||||
A data stream consists of one or more hidden auto-generated backing indices. These backing indices are named using the following convention:
|
||||
|
||||
```
|
||||
.ds-<data-stream-name>-<generation-id>
|
||||
```
|
||||
|
||||
For example, `.ds-logs-redis-000003`, where generation-id is a six-digit, zero-padded integer that acts as a cumulative count of the data stream’s rollovers, starting at `000001`.
|
||||
|
||||
The most recently created backing index is the data stream’s write index. You can’t add documents directly to any of the backing indices. You can only add them via the data stream handle:
|
||||
|
||||
|
||||
|
||||
The data stream routes search requests to all of its backing indices. It uses the timestamp field to intelligently route search requests to the right set of indices and shards:
|
||||
|
||||
|
||||
|
||||
The following operations are not supported on the write index because they might hinder the indexing operation:
|
||||
|
||||
- close
|
||||
- clone
|
||||
- delete
|
||||
- shrink
|
||||
- split
|
||||
|
||||
## Get started with data streams
|
||||
|
||||
### Step 1: Create an index template
|
||||
|
||||
To create a data stream, you first need to create an index template that configures a set of indices as a data stream. The `data_stream` object indicates that it’s a data stream and not a regular index template. The index pattern matches with the name of the data stream:
|
||||
|
||||
```json
|
||||
PUT _index_template/logs-template
|
||||
{
|
||||
"index_patterns": [
|
||||
"my-data-stream",
|
||||
"logs-*"
|
||||
],
|
||||
"data_stream": {},
|
||||
"priority": 100
|
||||
}
|
||||
```
|
||||
|
||||
In this case, each ingested document must have an `@timestamp` field.
|
||||
You also have the ability to define your own custom timestamp field as a property in the `data_stream` object. You can also add index mappings and other settings here, just as you would for a regular index template.
|
||||
|
||||
```json
|
||||
PUT _index_template/logs-template-nginx
|
||||
{
|
||||
"index_patterns": "logs-nginx",
|
||||
"data_stream": {
|
||||
"timestamp_field": {
|
||||
"name": "request_time"
|
||||
}
|
||||
},
|
||||
"priority": 200,
|
||||
"template": {
|
||||
"settings": {
|
||||
"number_of_shards": 1,
|
||||
"number_of_replicas": 0
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
In this case, `logs-nginx` index matches both the `logs-template` and `logs-template-nginx` templates. When you have a tie, OpenSearch selects the matching index template with the higher priority value.
|
||||
|
||||
### Step 2: Create a data stream
|
||||
|
||||
After you create an index template, you can create a data stream.
|
||||
You can use the data stream API to explicitly create a data stream. The data stream API initializes the first backing index:
|
||||
|
||||
```json
|
||||
PUT _data_stream/logs-redis
|
||||
PUT _data_stream/logs-nginx
|
||||
```
|
||||
|
||||
You can also directly start ingesting data without creating a data stream.
|
||||
|
||||
Because we have a matching index template with a data_stream object, OpenSearch automatically creates the data stream:
|
||||
|
||||
```json
|
||||
POST logs-staging/_doc
|
||||
{
|
||||
"message": "login attempt failed",
|
||||
"@timestamp": "2013-03-01T00:00:00"
|
||||
}
|
||||
```
|
||||
|
||||
To see information about a specific data stream:
|
||||
|
||||
```json
|
||||
GET _data_stream/logs-nginx
|
||||
```
|
||||
|
||||
#### Sample response
|
||||
|
||||
```json
|
||||
{
|
||||
"data_streams" : [
|
||||
{
|
||||
"name" : "logs-nginx",
|
||||
"timestamp_field" : {
|
||||
"name" : "request_time"
|
||||
},
|
||||
"indices" : [
|
||||
{
|
||||
"index_name" : ".ds-logs-nginx-000001",
|
||||
"index_uuid" : "-VhmuhrQQ6ipYCmBhn6vLw"
|
||||
}
|
||||
],
|
||||
"generation" : 1,
|
||||
"status" : "GREEN",
|
||||
"template" : "logs-template-nginx"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
You can see the name of the timestamp field, the list of the backing indices, and the template that's used to create the data stream. You can also see the health of the data stream, which represents the lowest status of all its backing indices.
|
||||
|
||||
To see more insights about the data stream, use the `_stats` endpoint:
|
||||
|
||||
```json
|
||||
GET _data_stream/logs-nginx/_stats
|
||||
```
|
||||
|
||||
#### Sample response
|
||||
|
||||
```json
|
||||
{
|
||||
"_shards" : {
|
||||
"total" : 1,
|
||||
"successful" : 1,
|
||||
"failed" : 0
|
||||
},
|
||||
"data_stream_count" : 1,
|
||||
"backing_indices" : 1,
|
||||
"total_store_size_bytes" : 208,
|
||||
"data_streams" : [
|
||||
{
|
||||
"data_stream" : "logs-nginx",
|
||||
"backing_indices" : 1,
|
||||
"store_size_bytes" : 208,
|
||||
"maximum_timestamp" : 0
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
### Step 3: Ingest data into the data stream
|
||||
|
||||
To ingest data into a data stream, you can use the regular indexing APIs. Make sure every document that you index has a timestamp field. If you try to ingest a document that doesn't have a timestamp field, you get an error.
|
||||
|
||||
```json
|
||||
POST logs-redis/_doc
|
||||
{
|
||||
"message": "login attempt",
|
||||
"@timestamp": "2013-03-01T00:00:00"
|
||||
}
|
||||
```
|
||||
|
||||
### Step 4: Searching a data stream
|
||||
|
||||
You can search a data stream just like you search a regular index or an index alias.
|
||||
The search operation applies to all of the backing indices (all data present in the stream).
|
||||
|
||||
```json
|
||||
GET logs-redis/_search
|
||||
{
|
||||
"query": {
|
||||
"match": {
|
||||
"message": "login"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### Sample response
|
||||
|
||||
```json
|
||||
{
|
||||
"took" : 514,
|
||||
"timed_out" : false,
|
||||
"_shards" : {
|
||||
"total" : 5,
|
||||
"successful" : 5,
|
||||
"skipped" : 0,
|
||||
"failed" : 0
|
||||
},
|
||||
"hits" : {
|
||||
"total" : {
|
||||
"value" : 1,
|
||||
"relation" : "eq"
|
||||
},
|
||||
"max_score" : 0.2876821,
|
||||
"hits" : [
|
||||
{
|
||||
"_index" : ".ds-logs-redis-000001",
|
||||
"_type" : "_doc",
|
||||
"_id" : "-rhVmXoBL6BAVWH3mMpC",
|
||||
"_score" : 0.2876821,
|
||||
"_source" : {
|
||||
"message" : "login attempt",
|
||||
"@timestamp" : "2013-03-01T00:00:00"
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Step 5: Rollover a data stream
|
||||
|
||||
A rollover operation creates a new backing index that becomes the data stream’s new write index.
|
||||
|
||||
To perform manual rollover operation on the data stream:
|
||||
|
||||
```json
|
||||
POST logs-redis/_rollover
|
||||
```
|
||||
|
||||
#### Sample response
|
||||
|
||||
```json
|
||||
{
|
||||
"acknowledged" : true,
|
||||
"shards_acknowledged" : true,
|
||||
"old_index" : ".ds-logs-redis-000001",
|
||||
"new_index" : ".ds-logs-redis-000002",
|
||||
"rolled_over" : true,
|
||||
"dry_run" : false,
|
||||
"conditions" : { }
|
||||
}
|
||||
```
|
||||
|
||||
If you now perform a `GET` operation on the `logs-redis` data stream, you see that the generation ID is incremented from 1 to 2.
|
||||
|
||||
You can also set up an [Index State Management (ISM) policy]({{site.url}}{{site.baseurl}}/ism/policies/) to automate the rollover process for the data stream.
|
||||
The ISM policy is applied to the backing indices at the time of their creation. When you associate a policy to a data stream, it only affects the future backing indices of that data stream.
|
||||
|
||||
You also don’t need to provide the `rollover_alias` setting, because the ISM policy infers this information from the backing index.
|
||||
|
||||
### Step 6: Manage data streams in OpenSearch Dashboards
|
||||
|
||||
To manage data streams from OpenSearch Dashboards, open **OpenSearch Dashboards**, choose **Index Management**, select **Indices** or **Policy managed indices**.
|
||||
|
||||
You see a toggle switch for data streams that you can use to show or hide indices belonging to a data stream.
|
||||
|
||||
When you enable this switch, you see a data stream multi-select dropdown menu that you can use for filtering data streams.
|
||||
You also see a data stream column that shows you the name of the parent data stream the index is contained in.
|
||||
|
||||
|
||||
|
||||
You can select one or more data streams and apply an ISM policy on them. You can also apply a policy on any individual backing index.
|
||||
|
||||
You can performing visualizations on a data stream just like you would on a regular index or index alias.
|
||||
|
||||
### Step 7: Delete a data stream
|
||||
|
||||
The delete operation first deletes the backing indices of a data stream and then deletes the data stream itself.
|
||||
|
||||
To delete a data stream and all of its hidden backing indices:
|
||||
|
||||
```json
|
||||
DELETE _data_stream/<name_of_data_stream>
|
||||
```
|
||||
|
||||
You can use wildcards to delete more than one data stream.
|
||||
|
||||
We recommend deleting data from a data stream using an ISM policy.
|
||||
|
||||
You can also use [asynchronous search]({{site.url}}{{site.baseurl}}/async/index/) and [SQL]({{site.url}}{{site.baseurl}}/sql/index/) and [PPL]({{site.url}}{{site.baseurl}}/ppl/index/) to query your data stream directly. You can also use the security plugin to define granular permissions on the data stream name.
|
||||
@@ -1,407 +0,0 @@
|
||||
---
|
||||
layout: default
|
||||
title: Index templates
|
||||
nav_order: 15
|
||||
---
|
||||
|
||||
# Index templates
|
||||
|
||||
Index templates let you initialize new indices with predefined mappings and settings. For example, if you continuously index log data, you can define an index template so that all of these indices have the same number of shards and replicas.
|
||||
|
||||
### Create a template
|
||||
|
||||
To create an index template, use a POST request:
|
||||
|
||||
```json
|
||||
POST _index_template
|
||||
```
|
||||
|
||||
This command creates a template named `daily_logs` and applies it to any new index whose name matches the regular expression `logs-2020-01-*` and also adds it to the `my_logs` alias:
|
||||
|
||||
```json
|
||||
PUT _index_template/daily_logs
|
||||
{
|
||||
"index_patterns": [
|
||||
"logs-2020-01-*"
|
||||
],
|
||||
"template": {
|
||||
"aliases": {
|
||||
"my_logs": {}
|
||||
},
|
||||
"settings": {
|
||||
"number_of_shards": 2,
|
||||
"number_of_replicas": 1
|
||||
},
|
||||
"mappings": {
|
||||
"properties": {
|
||||
"timestamp": {
|
||||
"type": "date",
|
||||
"format": "yyyy-MM-dd HH:mm:ss||yyyy-MM-dd||epoch_millis"
|
||||
},
|
||||
"value": {
|
||||
"type": "double"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
You should see the following response:
|
||||
|
||||
```json
|
||||
{
|
||||
"acknowledged": true
|
||||
}
|
||||
```
|
||||
|
||||
If you create an index named `logs-2020-01-01`, you can see that it has the mappings and settings from the template:
|
||||
|
||||
```json
|
||||
PUT logs-2020-01-01
|
||||
GET logs-2020-01-01
|
||||
```
|
||||
|
||||
```json
|
||||
{
|
||||
"logs-2020-01-01": {
|
||||
"aliases": {
|
||||
"my_logs": {}
|
||||
},
|
||||
"mappings": {
|
||||
"properties": {
|
||||
"timestamp": {
|
||||
"type": "date",
|
||||
"format": "yyyy-MM-dd HH:mm:ss||yyyy-MM-dd||epoch_millis"
|
||||
},
|
||||
"value": {
|
||||
"type": "double"
|
||||
}
|
||||
}
|
||||
},
|
||||
"settings": {
|
||||
"index": {
|
||||
"creation_date": "1578107970779",
|
||||
"number_of_shards": "2",
|
||||
"number_of_replicas": "1",
|
||||
"uuid": "U1vMDMOHSAuS2IzPcPHpOA",
|
||||
"version": {
|
||||
"created": "7010199"
|
||||
},
|
||||
"provided_name": "logs-2020-01-01"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Any additional indices that match this pattern---`logs-2020-01-02`, `logs-2020-01-03`, and so on---will inherit the same mappings and settings.
|
||||
|
||||
### Retrieve a template
|
||||
|
||||
To list all index templates:
|
||||
|
||||
```json
|
||||
GET _cat/templates
|
||||
```
|
||||
|
||||
To find a template by its name:
|
||||
|
||||
```json
|
||||
GET _index_template/daily_logs
|
||||
```
|
||||
|
||||
To get a list of all your templates:
|
||||
|
||||
```json
|
||||
GET _index_template/daily_logs
|
||||
```
|
||||
|
||||
To get a list of all templates that match a pattern:
|
||||
|
||||
```json
|
||||
GET _index_template/daily*
|
||||
```
|
||||
|
||||
To check if a specific template exists:
|
||||
|
||||
```json
|
||||
HEAD _index_template/<name>
|
||||
```
|
||||
|
||||
### Configure multiple templates
|
||||
|
||||
You can create multiple index templates for your indices. If the index name matches more than one template, OpenSearch merges all mappings and settings from all matching templates and applies them to the index.
|
||||
|
||||
The settings from the more recently created index templates override the settings of older index templates. So, you can first define a few common settings in a generic template that can act as a catch-all and then add more specialized settings as required.
|
||||
|
||||
An even better approach is to explicitly specify template priority using the `order` parameter. OpenSearch applies templates with lower priority numbers first and then overrides them with templates with higher priority numbers.
|
||||
|
||||
For example, say you have the following two templates that both match the `logs-2020-01-02` index and there’s a conflict in the `number_of_shards` field:
|
||||
|
||||
#### Template 1
|
||||
|
||||
```json
|
||||
PUT _index_template/template-01
|
||||
{
|
||||
"index_patterns": [
|
||||
"logs*"
|
||||
],
|
||||
"priority": 0,
|
||||
"template": {
|
||||
"settings": {
|
||||
"number_of_shards": 2
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### Template 2
|
||||
|
||||
```json
|
||||
PUT _index_template/template-02
|
||||
{
|
||||
"index_patterns": [
|
||||
"logs-2020-01-*"
|
||||
],
|
||||
"priority": 1,
|
||||
"template": {
|
||||
"settings": {
|
||||
"number_of_shards": 3
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Because `template-02` has a higher `priority` value, it takes precedence over `template-01` . The `logs-2020-01-02` index would have the `number_of_shards` value as 3.
|
||||
|
||||
### Delete a template
|
||||
|
||||
You can delete an index template using its name:
|
||||
|
||||
```json
|
||||
DELETE _index_template/daily_logs
|
||||
```
|
||||
|
||||
## Composable index templates
|
||||
|
||||
Managing multiple index templates has the following challenges:
|
||||
|
||||
- If you have duplication between index templates, storing these index templates results in a bigger cluster state.
|
||||
- If you want to make a change across all your index templates, you have to manually make the change for each template.
|
||||
- If an index matches multiple templates, OpenSearch might merge the templates in an unexpected way that you discover only after an index is created.
|
||||
|
||||
You can use composable index templates to overcome these challenges. Composable index templates let you abstract common settings, mappings, and aliases into a reusable building block called a component template.
|
||||
|
||||
You can combine component templates to compose an index template.
|
||||
|
||||
Settings and mappings that you specify directly in the [create index]({{site.url}}{{site.baseurl}}/opensearch/rest-api/create-index/) request override any settings or mappings specified in an index template and its component templates.
|
||||
{: .note }
|
||||
|
||||
### Create a component template
|
||||
|
||||
Let's define two component templates---`component_template_1` and `component_template_2`:
|
||||
|
||||
#### Component template 1
|
||||
|
||||
```json
|
||||
PUT _component_template/component_template_1
|
||||
{
|
||||
"template": {
|
||||
"mappings": {
|
||||
"properties": {
|
||||
"@timestamp": {
|
||||
"type": "date"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### Component template 2
|
||||
|
||||
```json
|
||||
PUT _component_template/component_template_2
|
||||
{
|
||||
"template": {
|
||||
"mappings": {
|
||||
"properties": {
|
||||
"ip_address": {
|
||||
"type": "ip"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Use component templates to create an index template
|
||||
|
||||
When creating index templates, you need to include the component templates in a `composed_of` list.
|
||||
|
||||
OpenSearch applies the component templates in the order in which you specify them within the index template. The settings, mappings, and aliases that you specify inside the index template are applied last.
|
||||
|
||||
```json
|
||||
PUT _index_template/daily_logs
|
||||
{
|
||||
"index_patterns": [
|
||||
"logs-2020-01-*"
|
||||
],
|
||||
"template": {
|
||||
"aliases": {
|
||||
"my_logs": {}
|
||||
},
|
||||
"settings": {
|
||||
"number_of_shards": 2,
|
||||
"number_of_replicas": 1
|
||||
},
|
||||
"mappings": {
|
||||
"properties": {
|
||||
"timestamp": {
|
||||
"type": "date",
|
||||
"format": "yyyy-MM-dd HH:mm:ss||yyyy-MM-dd||epoch_millis"
|
||||
},
|
||||
"value": {
|
||||
"type": "double"
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
"priority": 200,
|
||||
"composed_of": [
|
||||
"component_template_1",
|
||||
"component_template_2"
|
||||
],
|
||||
"version": 3,
|
||||
"_meta": {
|
||||
"description": "using component templates"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
If you create an index named `logs-2020-01-01`, you can see that it derives its mappings and settings from both the component templates:
|
||||
|
||||
```json
|
||||
PUT logs-2020-01-01
|
||||
GET logs-2020-01-01
|
||||
```
|
||||
|
||||
#### Sample response
|
||||
|
||||
```json
|
||||
{
|
||||
"logs-2020-01-01": {
|
||||
"aliases": {
|
||||
"my_logs": {}
|
||||
},
|
||||
"mappings": {
|
||||
"properties": {
|
||||
"@timestamp": {
|
||||
"type": "date"
|
||||
},
|
||||
"ip_address": {
|
||||
"type": "ip"
|
||||
},
|
||||
"timestamp": {
|
||||
"type": "date",
|
||||
"format": "yyyy-MM-dd HH:mm:ss||yyyy-MM-dd||epoch_millis"
|
||||
},
|
||||
"value": {
|
||||
"type": "double"
|
||||
}
|
||||
}
|
||||
},
|
||||
"settings": {
|
||||
"index": {
|
||||
"creation_date": "1625382479459",
|
||||
"number_of_shards": "2",
|
||||
"number_of_replicas": "1",
|
||||
"uuid": "rYUlpOXDSUSuZifQLPfa5A",
|
||||
"version": {
|
||||
"created": "7100299"
|
||||
},
|
||||
"provided_name": "logs-2020-01-01"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Simulate multi-component templates
|
||||
|
||||
For index templates composed of multiple component templates, you can simulate applying a new template to verify whether the settings are applied as you expect.
|
||||
|
||||
To simulate the settings that would be applied to a specific index name:
|
||||
|
||||
```json
|
||||
POST _index_template/_simulate_index/<index_name>
|
||||
```
|
||||
|
||||
To simulate the settings that would be applied from an existing template:
|
||||
|
||||
```json
|
||||
POST _index_template/_simulate/<index_template>
|
||||
```
|
||||
|
||||
You can also specify a template definition in the simulate request:
|
||||
|
||||
```json
|
||||
POST _index_template/_simulate
|
||||
{
|
||||
"index_patterns": [
|
||||
"logs-2020-01-*"
|
||||
],
|
||||
"template": {
|
||||
"settings" : {
|
||||
"index.number_of_shards" : 3
|
||||
}
|
||||
},
|
||||
"composed_of": ["component_template_1", "component_template_2"]
|
||||
}
|
||||
```
|
||||
|
||||
The `_simulate` API returns the final settings, mappings, and aliases that will be applied to indices that match the index pattern. You can also see any overlapping templates whose configuration is superseded by the simulated template body or higher priority templates:
|
||||
|
||||
```json
|
||||
{
|
||||
"template" : {
|
||||
"settings" : {
|
||||
"index" : {
|
||||
"number_of_shards" : "3"
|
||||
}
|
||||
},
|
||||
"mappings" : {
|
||||
"properties" : {
|
||||
"@timestamp" : {
|
||||
"type" : "date"
|
||||
},
|
||||
"ip_address" : {
|
||||
"type" : "ip"
|
||||
}
|
||||
}
|
||||
},
|
||||
"aliases" : { }
|
||||
},
|
||||
"overlapping" : [
|
||||
{
|
||||
"name" : "daily_logs",
|
||||
"index_patterns" : [
|
||||
"logs-2020-01-*"
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
## Index template options
|
||||
|
||||
You can specify the following template options:
|
||||
|
||||
Option | Type | Description | Required
|
||||
:--- | :--- | :--- | :---
|
||||
`template` | `Object` | Specify index settings, mappings, and aliases. | No
|
||||
`priority` | `Integer` | The priority of the index template. | No
|
||||
`composed_of` | `String array` | The names of component templates applied on a new index together with the current template. | No
|
||||
`version` | `Integer` | Specify a version number to simplify template management. Default is `null`. | No
|
||||
`_meta ` | `Object` | Specify meta information about the template. | No
|
||||
@@ -1,19 +0,0 @@
|
||||
---
|
||||
layout: default
|
||||
title: Compatibility
|
||||
parent: Install OpenSearch
|
||||
nav_order: 2
|
||||
---
|
||||
|
||||
# Operating system and JVM compatibility
|
||||
|
||||
- We recommend installing OpenSearch on RHEL- or Debian-based Linux distributions that use [systemd](https://en.wikipedia.org/wiki/Systemd), such as CentOS, Amazon Linux 2, and Ubuntu (LTS). OpenSearch should work on many Linux distributions, but we only test a handful.
|
||||
- The OpenSearch tarball ships with a compatible version of Java in the `jdk` directory. To find its version, run `./jdk/bin/java -version`. For example, the OpenSearch 1.0.0 tarball ships with Java 15 (non-LTS).
|
||||
|
||||
{% comment %}`./jdk/bin/java -version` doesn't work on macOS with zsh at the moment, and I have no idea why. Maybe we need a macOS artifact. Regardless, the command works on Amazon Linux 2 with bash and presumably other distros. - aetter{% endcomment %}
|
||||
|
||||
To use a different Java installation, set the `OPENSEARCH_JAVA_HOME` environment variable to the Java install location. We recommend Java 11 (LTS), but OpenSearch also works with Java 8.
|
||||
|
||||
OpenSearch version | Compatible Java versions | Recommended operating systems
|
||||
:--- | :--- | :---
|
||||
1.x | 8, 11 | Red Hat Enterprise Linux 7, 8; CentOS 7, 8; Amazon Linux 2; Ubuntu 16.04, 18.04, 20.04
|
||||
@@ -1,122 +0,0 @@
|
||||
---
|
||||
layout: default
|
||||
title: Query DSL
|
||||
nav_order: 27
|
||||
has_children: true
|
||||
redirect_from:
|
||||
- /opensearch/query-dsl/
|
||||
---
|
||||
|
||||
# Query DSL
|
||||
|
||||
While you can use HTTP request parameters to perform simple searches, you can also use the OpenSearch query domain-specific language (DSL), which provides a wider range of search options. The query DSL uses the HTTP request body, so you can more easily customize your queries to get the exact results that you want.
|
||||
|
||||
For example, the following request performs a simple search to search for a `speaker` field that has a value of `queen`.
|
||||
|
||||
**Sample request**
|
||||
```json
|
||||
GET _search?q=speaker:queen
|
||||
```
|
||||
|
||||
**Sample response**
|
||||
```
|
||||
{
|
||||
"took": 87,
|
||||
"timed_out": false,
|
||||
"_shards": {
|
||||
"total": 68,
|
||||
"successful": 68,
|
||||
"skipped": 0,
|
||||
"failed": 0
|
||||
},
|
||||
"hits": {
|
||||
"total": {
|
||||
"value": 4080,
|
||||
"relation": "eq"
|
||||
},
|
||||
"max_score": 4.4368687,
|
||||
"hits": [
|
||||
{
|
||||
"_index": "new_shakespeare",
|
||||
"_type": "_doc",
|
||||
"_id": "28559",
|
||||
"_score": 4.4368687,
|
||||
"_source": {
|
||||
"type": "line",
|
||||
"line_id": 28560,
|
||||
"play_name": "Cymbeline",
|
||||
"speech_number": 20,
|
||||
"line_number": "1.1.81",
|
||||
"speaker": "QUEEN",
|
||||
"text_entry": "No, be assured you shall not find me, daughter,"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
With query DSL, however, you can include an HTTP request body to look for results more tailored to your needs. The following example shows how to search for `speaker` and `text_entry` fields that have a value of `QUEEN`.
|
||||
|
||||
**Sample request**
|
||||
```json
|
||||
{
|
||||
"query": {
|
||||
"multi_match": {
|
||||
"query": "QUEEN",
|
||||
"fields": ["speaker", "text_entry"]
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Sample Response**
|
||||
```json
|
||||
{
|
||||
"took": 39,
|
||||
"timed_out": false,
|
||||
"_shards": {
|
||||
"total": 68,
|
||||
"successful": 68,
|
||||
"skipped": 0,
|
||||
"failed": 0
|
||||
},
|
||||
"hits": {
|
||||
"total": {
|
||||
"value": 5837,
|
||||
"relation": "eq"
|
||||
},
|
||||
"max_score": 7.8623476,
|
||||
"hits": [
|
||||
{
|
||||
"_index": "new_shakespeare",
|
||||
"_type": "_doc",
|
||||
"_id": "100763",
|
||||
"_score": 7.8623476,
|
||||
"_source": {
|
||||
"type": "line",
|
||||
"line_id": 100764,
|
||||
"play_name": "Troilus and Cressida",
|
||||
"speech_number": 43,
|
||||
"line_number": "3.1.68",
|
||||
"speaker": "PANDARUS",
|
||||
"text_entry": "Sweet queen, sweet queen! thats a sweet queen, i faith."
|
||||
}
|
||||
},
|
||||
{
|
||||
"_index": "shakespeare",
|
||||
"_type": "_doc",
|
||||
"_id": "28559",
|
||||
"_score": 5.8923807,
|
||||
"_source": {
|
||||
"type": "line",
|
||||
"line_id": 28560,
|
||||
"play_name": "Cymbeline",
|
||||
"speech_number": 20,
|
||||
"line_number": "1.1.81",
|
||||
"speaker": "QUEEN",
|
||||
"text_entry": "No, be assured you shall not find me, daughter,"
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
The OpenSearch query DSL comes in three varieties: term-level queries, full-text queries, and boolean queries. You can even perform more complicated searches by using different elements from each variety to find whatever data you need.
|
||||
@@ -1,61 +0,0 @@
|
||||
---
|
||||
layout: default
|
||||
title: cat aliases
|
||||
parent: CAT
|
||||
grand_parent: REST API reference
|
||||
nav_order: 1
|
||||
has_children: false
|
||||
---
|
||||
|
||||
# cat aliases
|
||||
|
||||
The cat aliases operation lists the mapping of aliases to indices, plus routing and filtering information.
|
||||
|
||||
## Example
|
||||
|
||||
```json
|
||||
GET _cat/aliases?v
|
||||
```
|
||||
|
||||
To limit the information to a specific alias, add the alias name after your query:
|
||||
|
||||
```json
|
||||
GET _cat/aliases/<alias>?v
|
||||
```
|
||||
|
||||
If you want to get information for more than one alias, separate the alias names with commas:
|
||||
|
||||
```json
|
||||
GET _cat/aliases/alias1,alias2,alias3
|
||||
```
|
||||
|
||||
## Path and HTTP methods
|
||||
|
||||
```
|
||||
GET _cat/aliases/<alias>
|
||||
GET _cat/aliases
|
||||
```
|
||||
|
||||
|
||||
## URL parameters
|
||||
|
||||
All cat aliases URL parameters are optional.
|
||||
|
||||
In addition to the [common URL parameters]({{site.url}}{{site.baseurl}}/opensearch/rest-api/cat/index#common-url-parameters), you can specify the following parameters:
|
||||
|
||||
Parameter | Type | Description
|
||||
:--- | :--- | :---
|
||||
local | Boolean | Whether to return information from the local node only instead of from the master node. Default is false.
|
||||
expand_wildcards | Enum | Expands wildcard expressions to concrete indices. Combine multiple values with commas. Supported values are `all`, `open`, `closed`, `hidden`, and `none`. Default is `open`.
|
||||
|
||||
## Response
|
||||
|
||||
The following response shows that `alias1` refers to a `movies` index and has a configured filter:
|
||||
|
||||
```json
|
||||
alias | index | filter | routing.index | routing.search | is_write_index
|
||||
alias1 | movies | * | - | - | -
|
||||
.kibana | .kibana_1 | - | - | - | -
|
||||
```
|
||||
|
||||
To learn more about index aliases, see [Index aliases]({{site.url}}{{site.baseurl}}/opensearch/index-alias).
|
||||
@@ -1,61 +0,0 @@
|
||||
---
|
||||
layout: default
|
||||
title: cat allocation
|
||||
parent: CAT
|
||||
grand_parent: REST API reference
|
||||
nav_order: 5
|
||||
has_children: false
|
||||
---
|
||||
|
||||
# cat allocation
|
||||
|
||||
The cat allocation operation lists the allocation of disk space for indices and the number of shards on each node.
|
||||
|
||||
## Example
|
||||
|
||||
```json
|
||||
GET _cat/allocation?v
|
||||
```
|
||||
|
||||
To limit the information to a specific node, add the node name after your query:
|
||||
|
||||
```json
|
||||
GET _cat/allocation/<node_name>
|
||||
```
|
||||
|
||||
If you want to get information for more than one node, separate the node names with commas:
|
||||
|
||||
```json
|
||||
GET _cat/aliases/node_name_1,node_name_2,node_name_3
|
||||
```
|
||||
|
||||
## Path and HTTP methods
|
||||
|
||||
```
|
||||
GET _cat/allocation?v
|
||||
GET _cat/allocation/<node_name>
|
||||
```
|
||||
|
||||
## URL parameters
|
||||
|
||||
All cat allocation URL parameters are optional.
|
||||
|
||||
In addition to the [common URL parameters]({{site.url}}{{site.baseurl}}/opensearch/rest-api/cat/index#common-url-parameters), you can specify the following parameters:
|
||||
|
||||
Parameter | Type | Description
|
||||
:--- | :--- | :---
|
||||
bytes | Byte size | Specify the units for byte size. For example, `7kb` or `6gb`. For more information, see [Supported units]({{site.url}}{{site.baseurl}}/opensearch/units/).
|
||||
local | Boolean | Whether to return information from the local node only instead of from the master node. Default is false.
|
||||
master_timeout | Time | The amount of time to wait for a connection to the master node. Default is 30 seconds.
|
||||
|
||||
|
||||
|
||||
## Response
|
||||
|
||||
The following response shows that 8 shards are allocated to each the two nodes available:
|
||||
|
||||
```json
|
||||
shards | disk.indices | disk.used | disk.avail | disk.total | disk.percent host | ip | node
|
||||
8 | 989.4kb | 25.9gb | 32.4gb | 58.4gb | 44 172.18.0.4 | 172.18.0.4 | odfe-node1
|
||||
8 | 962.4kb | 25.9gb | 32.4gb | 58.4gb | 44 172.18.0.3 | 172.18.0.3 | odfe-node2
|
||||
```
|
||||
@@ -1,51 +0,0 @@
|
||||
---
|
||||
layout: default
|
||||
title: cat count
|
||||
parent: CAT
|
||||
grand_parent: REST API reference
|
||||
nav_order: 10
|
||||
has_children: false
|
||||
---
|
||||
|
||||
# cat count
|
||||
|
||||
The cat count operation lists the number of documents in your cluster.
|
||||
|
||||
## Example
|
||||
|
||||
```json
|
||||
GET _cat/count?v
|
||||
```
|
||||
|
||||
To see the number of documents in a specific index or alias, add the index or alias name after your query:
|
||||
|
||||
```json
|
||||
GET _cat/count/<index_or_alias>?v
|
||||
```
|
||||
|
||||
If you want to get information for more than one index or alias, separate the index or alias names with commas:
|
||||
|
||||
```json
|
||||
GET _cat/aliases/index_or_alias_1,index_or_alias_2,index_or_alias_3
|
||||
```
|
||||
|
||||
## Path and HTTP methods
|
||||
|
||||
```
|
||||
GET _cat/count?v
|
||||
GET _cat/count/<index>?v
|
||||
```
|
||||
|
||||
## URL parameters
|
||||
|
||||
All cat count URL parameters are optional. You can specify any of the [common URL parameters]({{site.url}}{{site.baseurl}}/opensearch/rest-api/cat/index#common-url-parameters).
|
||||
|
||||
|
||||
## Response
|
||||
|
||||
The following response shows the overall document count as 1625:
|
||||
|
||||
```json
|
||||
epoch | timestamp | count
|
||||
1624237738 | 01:08:58 | 1625
|
||||
```
|
||||
@@ -1,57 +0,0 @@
|
||||
---
|
||||
layout: default
|
||||
title: cat field data
|
||||
parent: CAT
|
||||
grand_parent: REST API reference
|
||||
nav_order: 15
|
||||
has_children: false
|
||||
---
|
||||
|
||||
# cat fielddata
|
||||
|
||||
The cat fielddata operation lists the memory size used by each field per node.
|
||||
|
||||
## Example
|
||||
|
||||
```json
|
||||
GET _cat/fielddata?v
|
||||
```
|
||||
|
||||
To limit the information to a specific field, add the field name after your query:
|
||||
|
||||
```json
|
||||
GET _cat/fielddata/<field_name>?v
|
||||
```
|
||||
|
||||
If you want to get information for more than one field, separate the field names with commas:
|
||||
|
||||
```json
|
||||
GET _cat/aliases/field_name_1,field_name_2,field_name_3
|
||||
```
|
||||
|
||||
## Path and HTTP methods
|
||||
|
||||
```
|
||||
GET _cat/fielddata?v
|
||||
GET _cat/fielddata/<field_name>?v
|
||||
```
|
||||
|
||||
## URL parameters
|
||||
|
||||
All cat fielddata URL parameters are optional.
|
||||
|
||||
In addition to the [common URL parameters]({{site.url}}{{site.baseurl}}/opensearch/rest-api/cat/index#common-url-parameters), you can specify the following parameter:
|
||||
|
||||
Parameter | Type | Description
|
||||
:--- | :--- | :---
|
||||
bytes | Byte size | Specify the units for byte size. For example, `7kb` or `6gb`. For more information, see [Supported units]({{site.url}}{{site.baseurl}}/opensearch/units/).
|
||||
|
||||
## Response
|
||||
|
||||
The following response shows the memory size for all fields as 284 bytes:
|
||||
|
||||
```json
|
||||
id host ip node field size
|
||||
1vo54NuxSxOrbPEYdkSF0w 172.18.0.4 172.18.0.4 odfe-node1 _id 284b
|
||||
ZaIkkUd4TEiAihqJGkp5CA 172.18.0.3 172.18.0.3 odfe-node2 _id 284b
|
||||
```
|
||||
@@ -1,42 +0,0 @@
|
||||
---
|
||||
layout: default
|
||||
title: cat health
|
||||
parent: CAT
|
||||
grand_parent: REST API reference
|
||||
nav_order: 20
|
||||
has_children: false
|
||||
---
|
||||
|
||||
# cat health
|
||||
|
||||
The cat health operation lists the status of the cluster, how long the cluster has been up, the number of nodes, and other useful information that helps you analyze the health of your cluster.
|
||||
|
||||
## Example
|
||||
|
||||
```json
|
||||
GET _cat/health?v
|
||||
```
|
||||
|
||||
## Path and HTTP methods
|
||||
|
||||
```
|
||||
GET _cat/health?v
|
||||
```
|
||||
|
||||
## URL parameters
|
||||
|
||||
All cat health URL parameters are optional.
|
||||
|
||||
Parameter | Type | Description
|
||||
:--- | :--- | :---
|
||||
time | Time | Specify the units for time. For example, `5d` or `7h`. For more information, see [Supported units]({{site.url}}{{site.baseurl}}/opensearch/units/).
|
||||
ts | Boolean | If true, returns HH:MM:SS and Unix epoch timestamps. Default is true.
|
||||
|
||||
## Response
|
||||
|
||||
```json
|
||||
GET _cat/health?v&time=5d
|
||||
|
||||
epoch | timestamp | cluster | status | node.total | node.data | shards | pri | relo | init | unassign | pending_tasks | max_task_wait_time | active_shards_percent
|
||||
1624248112 | 04:01:52 | odfe-cluster | green | 2 | 2 | 16 | 8 | 0 | 0 | 0 | 0 | - | 100.0%
|
||||
```
|
||||
@@ -1,61 +0,0 @@
|
||||
---
|
||||
layout: default
|
||||
title: cat indices
|
||||
parent: CAT
|
||||
grand_parent: REST API reference
|
||||
nav_order: 25
|
||||
has_children: false
|
||||
---
|
||||
|
||||
# cat indices
|
||||
|
||||
The cat indices operation lists information related to indices—how much disk space they are using, how many shards they have, their health status, and so on.
|
||||
|
||||
## Example
|
||||
|
||||
```
|
||||
GET _cat/indices?v
|
||||
```
|
||||
|
||||
To limit the information to a specific index, add the index name after your query.
|
||||
|
||||
```
|
||||
GET _cat/indices/<index>?v
|
||||
```
|
||||
|
||||
If you want to get information for more than one index, separate the indices with commas:
|
||||
|
||||
```json
|
||||
GET _cat/aliases/index1,index2,index3
|
||||
```
|
||||
|
||||
## Path and HTTP methods
|
||||
|
||||
```
|
||||
GET _cat/indices/<index>
|
||||
GET _cat/indices
|
||||
```
|
||||
|
||||
## URL parameters
|
||||
|
||||
All cat indices URL parameters are optional.
|
||||
|
||||
In addition to the [common URL parameters]({{site.url}}{{site.baseurl}}/opensearch/rest-api/cat/index#common-url-parameters), you can specify the following parameters:
|
||||
|
||||
Parameter | Type | Description
|
||||
:--- | :--- | :---
|
||||
bytes | Byte size | Specify the units for byte size. For example, `7kb` or `6gb`. For more information, see [Supported units]({{site.url}}{{site.baseurl}}/opensearch/units/).
|
||||
health | String | Limit indices based on their health status. Supported values are `green`, `yellow`, and `red`.
|
||||
include_unloaded_segments | Boolean | Whether to include information from segments not loaded into memory. Default is false.
|
||||
master_timeout | Time | The amount of time to wait for a connection to the master node. Default is 30 seconds.
|
||||
pri | Boolean | Whether to return information only from the primary shards. Default is false.
|
||||
time | Time | Specify the units for time. For example, `5d` or `7h`. For more information, see [Supported units]({{site.url}}{{site.baseurl}}/opensearch/units/).
|
||||
expand_wildcards | Enum | Expands wildcard expressions to concrete indices. Combine multiple values with commas. Supported values are `all`, `open`, `closed`, `hidden`, and `none`. Default is `open`.
|
||||
|
||||
|
||||
## Response
|
||||
|
||||
```json
|
||||
health | status | index | uuid | pri | rep | docs.count | docs.deleted | store.size | pri.store.size
|
||||
green | open | movies | UZbpfERBQ1-3GSH2bnM3sg | 1 | 1 | 1 | 0 | 7.7kb | 3.8kb
|
||||
```
|
||||
@@ -1,42 +0,0 @@
|
||||
---
|
||||
layout: default
|
||||
title: cat master
|
||||
parent: CAT
|
||||
grand_parent: REST API reference
|
||||
nav_order: 30
|
||||
has_children: false
|
||||
---
|
||||
|
||||
# cat master
|
||||
|
||||
The cat master operation lists information that helps identify the elected master node.
|
||||
|
||||
## Example
|
||||
|
||||
```
|
||||
GET _cat/master?v
|
||||
```
|
||||
|
||||
## Path and HTTP methods
|
||||
|
||||
```
|
||||
GET _cat/master
|
||||
```
|
||||
|
||||
## URL parameters
|
||||
|
||||
All cat master URL parameters are optional.
|
||||
|
||||
In addition to the [common URL parameters]({{site.url}}{{site.baseurl}}/opensearch/rest-api/cat/index#common-url-parameters), you can specify the following parameters:
|
||||
|
||||
Parameter | Type | Description
|
||||
:--- | :--- | :---
|
||||
master_timeout | Time | The amount of time to wait for a connection to the master node. Default is 30 seconds.
|
||||
|
||||
|
||||
## Response
|
||||
|
||||
```json
|
||||
id | host | ip | node
|
||||
ZaIkkUd4TEiAihqJGkp5CA | 172.18.0.3 | 172.18.0.3 | odfe-node2
|
||||
```
|
||||
@@ -1,43 +0,0 @@
|
||||
---
|
||||
layout: default
|
||||
title: cat nodeattrs
|
||||
parent: CAT
|
||||
grand_parent: REST API reference
|
||||
nav_order: 35
|
||||
has_children: false
|
||||
---
|
||||
|
||||
# cat nodeattrs
|
||||
|
||||
The cat nodeattrs operation lists the attributes of custom nodes.
|
||||
|
||||
## Example
|
||||
|
||||
```
|
||||
GET _cat/nodeattrs?v
|
||||
```
|
||||
|
||||
## Path and HTTP methods
|
||||
|
||||
```
|
||||
GET _cat/nodeattrs
|
||||
```
|
||||
|
||||
## URL parameters
|
||||
|
||||
All cat nodeattrs URL parameters are optional.
|
||||
|
||||
In addition to the [common URL parameters]({{site.url}}{{site.baseurl}}/opensearch/rest-api/cat/index#common-url-parameters), you can specify the following parameters:
|
||||
|
||||
Parameter | Type | Description
|
||||
:--- | :--- | :---
|
||||
local | Boolean | Whether to return information from the local node only instead of from the master node. Default is false.
|
||||
master_timeout | Time | The amount of time to wait for a connection to the master node. Default is 30 seconds.
|
||||
|
||||
|
||||
## Response
|
||||
|
||||
```json
|
||||
node | host | ip | attr | value
|
||||
odfe-node2 | 172.18.0.3 | 172.18.0.3 | testattr | test
|
||||
```
|
||||
@@ -1,50 +0,0 @@
|
||||
---
|
||||
layout: default
|
||||
title: cat nodes
|
||||
parent: CAT
|
||||
grand_parent: REST API reference
|
||||
nav_order: 40
|
||||
has_children: false
|
||||
---
|
||||
|
||||
# cat nodes
|
||||
|
||||
The cat nodes operation lists node-level information, including node roles and load metrics.
|
||||
|
||||
A few important node metrics are `pid`, `name`, `master`, `ip`, `port`, `version`, `build`, `jdk`, along with `disk`, `heap`, `ram`, and `file_desc`.
|
||||
|
||||
## Example
|
||||
|
||||
```
|
||||
GET _cat/nodes?v
|
||||
```
|
||||
|
||||
## Path and HTTP methods
|
||||
|
||||
```
|
||||
GET _cat/nodes
|
||||
```
|
||||
|
||||
## URL parameters
|
||||
|
||||
All cat nodes URL parameters are optional.
|
||||
|
||||
In addition to the [common URL parameters]({{site.url}}{{site.baseurl}}/opensearch/rest-api/cat/index#common-url-parameters), you can specify the following parameters:
|
||||
|
||||
Parameter | Type | Description
|
||||
:--- | :--- | :---
|
||||
bytes | Byte size | Specify the units for byte size. For example, `7kb` or `6gb`. For more information, see [Supported units]({{site.url}}{{site.baseurl}}/opensearch/units/).
|
||||
full_id | Boolean | If true, return the full node ID. If false, return the shortened node ID. Defaults to false.
|
||||
local | Boolean | Whether to return information from the local node only instead of from the master node. Default is false.
|
||||
master_timeout | Time | The amount of time to wait for a connection to the master node. Default is 30 seconds.
|
||||
time | Time | Specify the units for time. For example, `5d` or `7h`. For more information, see [Supported units]({{site.url}}{{site.baseurl}}/opensearch/units/).
|
||||
include_unloaded_segments | Boolean | Whether to include information from segments not loaded into memory. Default is false.
|
||||
|
||||
|
||||
## Response
|
||||
|
||||
```json
|
||||
ip | heap.percent | ram.percent | cpu load_1m | load_5m | load_15m | node.role | master | name
|
||||
172.18.0.3 | 31 | 97 | 3 | 0.03 | 0.10 | 0.14 dimr | * | odfe-node2
|
||||
172.18.0.4 | 45 | 97 | 3 | 0.19 | 0.14 | 0.15 dimr | - | odfe-node1
|
||||
```
|
||||
@@ -1,44 +0,0 @@
|
||||
---
|
||||
layout: default
|
||||
title: cat pending tasks
|
||||
parent: CAT
|
||||
grand_parent: REST API reference
|
||||
nav_order: 45
|
||||
has_children: false
|
||||
---
|
||||
|
||||
# cat pending tasks
|
||||
|
||||
The cat pending tasks operation lists the progress of all pending tasks, including task priority and time in queue.
|
||||
|
||||
## Example
|
||||
|
||||
```
|
||||
GET _cat/pending_tasks?v
|
||||
```
|
||||
|
||||
## Path and HTTP methods
|
||||
|
||||
```
|
||||
GET _cat/pending_tasks
|
||||
```
|
||||
|
||||
## URL parameters
|
||||
|
||||
All cat nodes URL parameters are optional.
|
||||
|
||||
In addition to the [common URL parameters]({{site.url}}{{site.baseurl}}/opensearch/rest-api/cat/index#common-url-parameters), you can specify the following parameters:
|
||||
|
||||
Parameter | Type | Description
|
||||
:--- | :--- | :---
|
||||
local | Boolean | Whether to return information from the local node only instead of from the master node. Default is false.
|
||||
master_timeout | Time | The amount of time to wait for a connection to the master node. Default is 30 seconds.
|
||||
time | Time | Specify the units for time. For example, `5d` or `7h`. For more information, see [Supported units]({{site.url}}{{site.baseurl}}/opensearch/units/).
|
||||
|
||||
|
||||
## Response
|
||||
|
||||
```json
|
||||
insertOrder | timeInQueue | priority | source
|
||||
1786 | 1.8s | URGENT | shard-started
|
||||
```
|
||||
@@ -1,62 +0,0 @@
|
||||
---
|
||||
layout: default
|
||||
title: cat plugins
|
||||
parent: CAT
|
||||
grand_parent: REST API reference
|
||||
nav_order: 50
|
||||
has_children: false
|
||||
---
|
||||
|
||||
# cat plugins
|
||||
|
||||
The cat plugins operation lists the names, components, and versions of the installed plugins.
|
||||
|
||||
## Example
|
||||
|
||||
```
|
||||
GET _cat/plugins?v
|
||||
```
|
||||
|
||||
## Path and HTTP methods
|
||||
|
||||
```
|
||||
GET _cat/plugins
|
||||
```
|
||||
|
||||
## URL parameters
|
||||
|
||||
All cat plugins URL parameters are optional.
|
||||
|
||||
In addition to the [common URL parameters]({{site.url}}{{site.baseurl}}/opensearch/rest-api/cat/index#common-url-parameters), you can specify the following parameters:
|
||||
|
||||
Parameter | Type | Description
|
||||
:--- | :--- | :---
|
||||
local | Boolean | Whether to return information from the local node only instead of from the master node. Default is false.
|
||||
master_timeout | Time | The amount of time to wait for a connection to the master node. Default is 30 seconds.
|
||||
|
||||
|
||||
## Response
|
||||
|
||||
```json
|
||||
name component version
|
||||
odfe-node2 opendistro-alerting 1.13.1.0
|
||||
odfe-node2 opendistro-anomaly-detection 1.13.0.0
|
||||
odfe-node2 opendistro-asynchronous-search 1.13.0.1
|
||||
odfe-node2 opendistro-index-management 1.13.2.0
|
||||
odfe-node2 opendistro-job-scheduler 1.13.0.0
|
||||
odfe-node2 opendistro-knn 1.13.0.0
|
||||
odfe-node2 opendistro-performance-analyzer 1.13.0.0
|
||||
odfe-node2 opendistro-reports-scheduler 1.13.0.0
|
||||
odfe-node2 opendistro-sql 1.13.2.0
|
||||
odfe-node2 opendistro_security 1.13.1.0
|
||||
odfe-node1 opendistro-alerting 1.13.1.0
|
||||
odfe-node1 opendistro-anomaly-detection 1.13.0.0
|
||||
odfe-node1 opendistro-asynchronous-search 1.13.0.1
|
||||
odfe-node1 opendistro-index-management 1.13.2.0
|
||||
odfe-node1 opendistro-job-scheduler 1.13.0.0
|
||||
odfe-node1 opendistro-knn 1.13.0.0
|
||||
odfe-node1 opendistro-performance-analyzer 1.13.0.0
|
||||
odfe-node1 opendistro-reports-scheduler 1.13.0.0
|
||||
odfe-node1 opendistro-sql 1.13.2.0
|
||||
odfe-node1 opendistro_security 1.13.1.0
|
||||
```
|
||||
@@ -1,57 +0,0 @@
|
||||
---
|
||||
layout: default
|
||||
title: cat recovery
|
||||
parent: CAT
|
||||
grand_parent: REST API reference
|
||||
nav_order: 50
|
||||
has_children: false
|
||||
---
|
||||
|
||||
# cat recovery
|
||||
|
||||
The cat recovery operation lists all completed and ongoing index and shard recoveries.
|
||||
|
||||
## Example
|
||||
|
||||
```
|
||||
GET _cat/recovery?v
|
||||
```
|
||||
|
||||
To see only the recoveries of a specific index, add the index name after your query.
|
||||
|
||||
```
|
||||
GET _cat/recovery/<index>?v
|
||||
```
|
||||
|
||||
If you want to get information for more than one index, separate the indices with commas:
|
||||
|
||||
```json
|
||||
GET _cat/aliases/index1,index2,index3
|
||||
```
|
||||
|
||||
## Path and HTTP methods
|
||||
|
||||
```
|
||||
GET _cat/recovery
|
||||
```
|
||||
|
||||
## URL parameters
|
||||
|
||||
All cat recovery URL parameters are optional.
|
||||
|
||||
In addition to the [common URL parameters]({{site.url}}{{site.baseurl}}/opensearch/rest-api/cat/index#common-url-parameters), you can specify the following parameters:
|
||||
|
||||
Parameter | Type | Description
|
||||
:--- | :--- | :---
|
||||
active_only | Boolean | Whether to only include ongoing shard recoveries. Default is false.
|
||||
bytes | Byte size | Specify the units for byte size. For example, `7kb` or `6gb`. For more information, see [Supported units]({{site.url}}{{site.baseurl}}/opensearch/units/).
|
||||
detailed | Boolean | Whether to include detailed information about shard recoveries. Default is false.
|
||||
time | Time | Specify the units for time. For example, `5d` or `7h`. For more information, see [Supported units]({{site.url}}{{site.baseurl}}/opensearch/units/).
|
||||
|
||||
## Response
|
||||
|
||||
```json
|
||||
index | shard | time | type | stage | source_host | source_node | target_host | target_node | repository | snapshot | files | files_recovered | files_percent | files_total | bytes | bytes_recovered | bytes_percent | bytes_total | translog_ops | translog_ops_recovered | translog_ops_percent
|
||||
movies | 0 | 117ms | empty_store | done | n/a | n/a | 172.18.0.4 | odfe-node1 | n/a | n/a | 0 | 0 | 0.0% | 0 | 0 | 0 | 0.0% | 0 | 0 | 0 | 100.0%
|
||||
movies | 0 | 382ms | peer | done | 172.18.0.4 | odfe-node1 | 172.18.0.3 | odfe-node2 | n/a | n/a | 1 | 1 | 100.0% | 1 | 208 | 208 | 100.0% | 208 | 1 | 1 | 100.0%
|
||||
```
|
||||
@@ -1,44 +0,0 @@
|
||||
---
|
||||
layout: default
|
||||
title: cat repositories
|
||||
parent: CAT
|
||||
grand_parent: REST API reference
|
||||
nav_order: 55
|
||||
has_children: false
|
||||
---
|
||||
|
||||
# cat repositories
|
||||
|
||||
The cat repositories operation lists all completed and ongoing index and shard recoveries.
|
||||
|
||||
## Example
|
||||
|
||||
```
|
||||
GET _cat/repositories?v
|
||||
```
|
||||
|
||||
## Path and HTTP methods
|
||||
|
||||
```
|
||||
GET _cat/repositories
|
||||
```
|
||||
|
||||
## URL parameters
|
||||
|
||||
All cat repositories URL parameters are optional.
|
||||
|
||||
In addition to the [common URL parameters]({{site.url}}{{site.baseurl}}/opensearch/rest-api/cat/index#common-url-parameters), you can specify the following parameters:
|
||||
|
||||
Parameter | Type | Description
|
||||
:--- | :--- | :---
|
||||
local | Boolean | Whether to return information from the local node only instead of from the master node. Default is false.
|
||||
master_timeout | Time | The amount of time to wait for a connection to the master node. Default is 30 seconds.
|
||||
|
||||
|
||||
## Response
|
||||
|
||||
```json
|
||||
id type
|
||||
repo1 fs
|
||||
repo2 s3
|
||||
```
|
||||
@@ -1,55 +0,0 @@
|
||||
---
|
||||
layout: default
|
||||
title: cat segments
|
||||
parent: CAT
|
||||
grand_parent: REST API reference
|
||||
nav_order: 55
|
||||
has_children: false
|
||||
---
|
||||
|
||||
# cat segments
|
||||
|
||||
The cat segments operation lists Lucene segment-level information for each index.
|
||||
|
||||
## Example
|
||||
|
||||
```
|
||||
GET _cat/segments?v
|
||||
```
|
||||
|
||||
To see only the information about segments of a specific index, add the index name after your query.
|
||||
|
||||
```
|
||||
GET _cat/segments/<index>?v
|
||||
```
|
||||
|
||||
If you want to get information for more than one index, separate the indices with commas:
|
||||
|
||||
```
|
||||
GET _cat/segments/index1,index2,index3
|
||||
```
|
||||
|
||||
## Path and HTTP methods
|
||||
|
||||
```
|
||||
GET _cat/segments
|
||||
```
|
||||
|
||||
## URL parameters
|
||||
|
||||
All cat segments URL parameters are optional.
|
||||
|
||||
In addition to the [common URL parameters]({{site.url}}{{site.baseurl}}/opensearch/rest-api/cat/index#common-url-parameters), you can specify the following parameter:
|
||||
|
||||
Parameter | Type | Description
|
||||
:--- | :--- | :---
|
||||
bytes | Byte size | Specify the units for byte size. For example, `7kb` or `6gb`. For more information, see [Supported units]({{site.url}}{{site.baseurl}}/opensearch/units/)..
|
||||
|
||||
|
||||
## Response
|
||||
|
||||
```json
|
||||
index | shard | prirep | ip | segment | generation | docs.count | docs.deleted | size | size.memory | committed | searchable | version | compound
|
||||
movies | 0 | p | 172.18.0.4 | _0 | 0 | 1 | 0 | 3.5kb | 1364 | true | true | 8.7.0 | true
|
||||
movies | 0 | r | 172.18.0.3 | _0 | 0 | 1 | 0 | 3.5kb | 1364 | true | true | 8.7.0 | true
|
||||
```
|
||||
@@ -1,58 +0,0 @@
|
||||
---
|
||||
layout: default
|
||||
title: cat shards
|
||||
parent: CAT
|
||||
grand_parent: REST API reference
|
||||
nav_order: 60
|
||||
has_children: false
|
||||
---
|
||||
|
||||
# cat shards
|
||||
|
||||
The cat shards operation lists the state of all primary and replica shards and how they are distributed.
|
||||
|
||||
## Example
|
||||
|
||||
```
|
||||
GET _cat/shards?v
|
||||
```
|
||||
|
||||
To see only the information about shards of a specific index, add the index name after your query.
|
||||
|
||||
```
|
||||
GET _cat/shards/<index>?v
|
||||
```
|
||||
|
||||
If you want to get information for more than one index, separate the indices with commas:
|
||||
|
||||
```
|
||||
GET _cat/shards/index1,index2,index3
|
||||
```
|
||||
|
||||
## Path and HTTP methods
|
||||
|
||||
```
|
||||
GET _cat/shards
|
||||
```
|
||||
|
||||
## URL parameters
|
||||
|
||||
All cat shards URL parameters are optional.
|
||||
|
||||
In addition to the [common URL parameters]({{site.url}}{{site.baseurl}}/opensearch/rest-api/cat/index#common-url-parameters), you can specify the following parameter:
|
||||
|
||||
Parameter | Type | Description
|
||||
:--- | :--- | :---
|
||||
bytes | Byte size | Specify the units for byte size. For example, `7kb` or `6gb`. For more information, see [Supported units]({{site.url}}{{site.baseurl}}/opensearch/units/).
|
||||
local | Boolean | Whether to return information from the local node only instead of from the master node. Default is false.
|
||||
master_timeout | Time | The amount of time to wait for a connection to the master node. Default is 30 seconds.
|
||||
time | Time | Specify the units for time. For example, `5d` or `7h`. For more information, see [Supported units]({{site.url}}{{site.baseurl}}/opensearch/units/).
|
||||
|
||||
|
||||
## Response
|
||||
|
||||
```json
|
||||
index | shard | prirep | state | docs | store | ip | | node
|
||||
plugins | 0 | p | STARTED | 0 | 208b | 172.18.0.4 | odfe-node1
|
||||
plugins | 0 | r | STARTED | 0 | 208b | 172.18.0.3 | odfe-node2
|
||||
```
|
||||
@@ -1,44 +0,0 @@
|
||||
---
|
||||
layout: default
|
||||
title: cat snapshots
|
||||
parent: CAT
|
||||
grand_parent: REST API reference
|
||||
nav_order: 65
|
||||
has_children: false
|
||||
---
|
||||
|
||||
# cat snapshots
|
||||
|
||||
The cat snapshots operation lists all snapshots for a repository.
|
||||
|
||||
## Example
|
||||
|
||||
```
|
||||
GET _cat/snapshots?v
|
||||
```
|
||||
|
||||
## Path and HTTP methods
|
||||
|
||||
```
|
||||
GET _cat/snapshots
|
||||
```
|
||||
|
||||
## URL parameters
|
||||
|
||||
All cat snapshots URL parameters are optional.
|
||||
|
||||
In addition to the [common URL parameters]({{site.url}}{{site.baseurl}}/opensearch/rest-api/cat/index#common-url-parameters), you can specify the following parameter:
|
||||
|
||||
Parameter | Type | Description
|
||||
:--- | :--- | :---
|
||||
master_timeout | Time | The amount of time to wait for a connection to the master node. Default is 30 seconds.
|
||||
time | Time | Specify the units for time. For example, `5d` or `7h`. For more information, see [Supported units]({{site.url}}{{site.baseurl}}/opensearch/units/).
|
||||
|
||||
|
||||
## Response
|
||||
|
||||
```json
|
||||
index | shard | prirep | state | docs | store | ip | | node
|
||||
plugins | 0 | p | STARTED | 0 | 208b | 172.18.0.4 | odfe-node1
|
||||
plugins | 0 | r | STARTED | 0 | 208b | 172.18.0.3 | odfe-node2
|
||||
```
|
||||
@@ -1,45 +0,0 @@
|
||||
---
|
||||
layout: default
|
||||
title: cat tasks
|
||||
parent: CAT
|
||||
grand_parent: REST API reference
|
||||
nav_order: 70
|
||||
has_children: false
|
||||
---
|
||||
|
||||
# cat tasks
|
||||
|
||||
The cat tasks operation lists the progress of all tasks currently running on your cluster.
|
||||
|
||||
## Example
|
||||
|
||||
```
|
||||
GET _cat/tasks?v
|
||||
```
|
||||
|
||||
## Path and HTTP methods
|
||||
|
||||
```
|
||||
GET _cat/tasks
|
||||
```
|
||||
|
||||
## URL parameters
|
||||
|
||||
All cat tasks URL parameters are optional.
|
||||
|
||||
In addition to the [common URL parameters]({{site.url}}{{site.baseurl}}/opensearch/rest-api/cat/index#common-url-parameters), you can specify the following parameter:
|
||||
|
||||
Parameter | Type | Description
|
||||
:--- | :--- | :---
|
||||
nodes | List | A comma-separated list of node IDs or names to limit the returned information. Use `_local` to return information from the node you're connecting to, specify the node name to get information from specific nodes, or keep the parameter empty to get information from all nodes.
|
||||
detailed | Boolean | Returns detailed task information. (Default: false)
|
||||
parent_task_id | String | Returns tasks with a specified parent task ID (node_id:task_number). Keep empty or set to -1 to return all.
|
||||
time | Time | Specify the units for time. For example, `5d` or `7h`. For more information, see [Supported units]({{site.url}}{{site.baseurl}}/opensearch/units/).
|
||||
|
||||
|
||||
## Response
|
||||
|
||||
```json
|
||||
action | task_id | parent_task_id | type | start_time | timestamp | running_time | ip | node
|
||||
cluster:monitor/tasks/lists | 1vo54NuxSxOrbPEYdkSF0w:168062 | - | transport | 1624337809471 | 04:56:49 | 489.5ms | 172.18.0.4 | odfe-node1
|
||||
```
|
||||
@@ -1,51 +0,0 @@
|
||||
---
|
||||
layout: default
|
||||
title: cat templates
|
||||
parent: CAT
|
||||
grand_parent: REST API reference
|
||||
nav_order: 70
|
||||
has_children: false
|
||||
---
|
||||
|
||||
# cat templates
|
||||
|
||||
The cat templates operation lists the names, patterns, order numbers, and version numbers of index templates.
|
||||
|
||||
## Example
|
||||
|
||||
```
|
||||
GET _cat/templates?v
|
||||
```
|
||||
|
||||
If you want to get information for more than one template, separate the template names with commas:
|
||||
|
||||
```
|
||||
GET _cat/shards/template_name_1,template_name_2,template_name_3
|
||||
```
|
||||
|
||||
## Path and HTTP methods
|
||||
|
||||
```
|
||||
GET _cat/templates
|
||||
```
|
||||
|
||||
## URL parameters
|
||||
|
||||
All cat templates URL parameters are optional.
|
||||
|
||||
In addition to the [common URL parameters]({{site.url}}{{site.baseurl}}/opensearch/rest-api/cat/index#common-url-parameters), you can specify the following parameter:
|
||||
|
||||
Parameter | Type | Description
|
||||
:--- | :--- | :---
|
||||
local | Boolean | Whether to return information from the local node only instead of from the master node. Default is false.
|
||||
master_timeout | Time | The amount of time to wait for a connection to the master node. Default is 30 seconds.
|
||||
|
||||
|
||||
## Response
|
||||
|
||||
```
|
||||
name | index_patterns order version composed_of
|
||||
tenant_template | [kibana*] | 0 |
|
||||
```
|
||||
|
||||
To learn more about index templates, see [Index templates]({{site.url}}{{site.baseurl}}/opensearch/index-templates).
|
||||
@@ -1,51 +0,0 @@
|
||||
---
|
||||
layout: default
|
||||
title: cat thread pool
|
||||
parent: CAT
|
||||
grand_parent: REST API reference
|
||||
nav_order: 75
|
||||
has_children: false
|
||||
---
|
||||
|
||||
# cat thread pool
|
||||
|
||||
The cat thread pool operation lists the active, queued, and rejected threads of different thread pools on each node.
|
||||
|
||||
## Example
|
||||
|
||||
```
|
||||
GET _cat/thread_pool?v
|
||||
```
|
||||
|
||||
If you want to get information for more than one thread pool, separate the thread pool names with commas:
|
||||
|
||||
```
|
||||
GET _cat/v/thread_pool_name_1,thread_pool_name_2,thread_pool_name_3
|
||||
```
|
||||
|
||||
## Path and HTTP methods
|
||||
|
||||
```
|
||||
GET _cat/thread_pool
|
||||
```
|
||||
|
||||
## URL parameters
|
||||
|
||||
All cat thread pool URL parameters are optional.
|
||||
|
||||
In addition to the [common URL parameters]({{site.url}}{{site.baseurl}}/opensearch/rest-api/cat/index#common-url-parameters), you can specify the following parameter:
|
||||
|
||||
Parameter | Type | Description
|
||||
:--- | :--- | :---
|
||||
local | Boolean | Whether to return information from the local node only instead of from the master node. Default is false.
|
||||
master_timeout | Time | The amount of time to wait for a connection to the master node. Default is 30 seconds.
|
||||
|
||||
|
||||
## Response
|
||||
|
||||
```json
|
||||
node_name name active queue rejected
|
||||
odfe-node2 ad-batch-task-threadpool 0 0 0
|
||||
odfe-node2 ad-threadpool 0 0 0
|
||||
odfe-node2 analyze 0 0 0s
|
||||
```
|
||||
@@ -1,58 +0,0 @@
|
||||
---
|
||||
layout: default
|
||||
title: CAT
|
||||
parent: REST API reference
|
||||
nav_order: 100
|
||||
has_children: true
|
||||
redirect_from:
|
||||
- /opensearch/catapis/
|
||||
---
|
||||
|
||||
# cat API
|
||||
|
||||
You can get essential statistics about your cluster in an easy-to-understand, tabular format using the compact and aligned text (CAT) API. The cat API is a human-readable interface that returns plain text instead of traditional JSON.
|
||||
|
||||
Using the cat API, you can answer questions like which node is the elected master, what state is the cluster in, how many documents are in each index, and so on.
|
||||
|
||||
## Example
|
||||
|
||||
To see the available operations in the cat API, use the following command:
|
||||
|
||||
```
|
||||
GET _cat
|
||||
```
|
||||
|
||||
## Common URL parameters
|
||||
|
||||
You can use the following string parameters with your query.
|
||||
|
||||
Parameter | Description
|
||||
:--- | :--- |
|
||||
`?v` | Makes the output more verbose by adding headers to the columns. It also adds some formatting to help align each of the columns together. All examples in this section include the `v` parameter.
|
||||
`?help` | Lists the default and other available headers for a given operation.
|
||||
`?h` | Limits the output to specific headers.
|
||||
`?format` | Outputs the result in JSON, YAML, or CBOR formats.
|
||||
`?sort` | Sorts the output by the specified columns.
|
||||
|
||||
To see what each column represents, use the `?v` parameter:
|
||||
|
||||
```
|
||||
GET _cat/<operation_name>?v
|
||||
```
|
||||
|
||||
To see all the available headers, use the `?help` parameter:
|
||||
|
||||
```
|
||||
GET _cat/<operation_name>?help
|
||||
```
|
||||
|
||||
To limit the output to a subset of headers, use the `?h` parameter:
|
||||
|
||||
```
|
||||
GET _cat/<operation_name>?h=<header_name_1>,<header_name_2>&v
|
||||
```
|
||||
|
||||
Typically, for any operation you can find out what headers are available using the `?help` parameter, and then use the `?h` parameter to limit the output to only the headers that you care about.
|
||||
|
||||
If you use the security plugin, make sure you have the appropriate permissions.
|
||||
{: .note }
|
||||
@@ -1,144 +0,0 @@
|
||||
---
|
||||
layout: default
|
||||
title: Cluster allocation explain
|
||||
parent: REST API reference
|
||||
nav_order: 10
|
||||
---
|
||||
|
||||
# Cluster allocation explain
|
||||
|
||||
The most basic cluster allocation explain request finds an unassigned shard and explains why it can't be allocated to a node.
|
||||
|
||||
If you add some options, you can instead get information on a specific shard, including why OpenSearch assigned it to its current node.
|
||||
|
||||
|
||||
## Example
|
||||
|
||||
```json
|
||||
GET _cluster/allocation/explain?include_yes_decisions=true
|
||||
{
|
||||
"index": "movies",
|
||||
"shard": 0,
|
||||
"primary": true
|
||||
}
|
||||
```
|
||||
|
||||
|
||||
## Path and HTTP methods
|
||||
|
||||
```
|
||||
GET _cluster/allocation/explain
|
||||
POST _cluster/allocation/explain
|
||||
```
|
||||
|
||||
|
||||
## URL parameters
|
||||
|
||||
All cluster allocation explain parameters are optional.
|
||||
|
||||
Parameter | Type | Description
|
||||
:--- | :--- | :---
|
||||
include_yes_decisions | Boolean | OpenSearch makes a series of yes or no decisions when trying to allocate a shard to a node. If this parameter is true, OpenSearch includes the (generally more numerous) "yes" decisions in its response. Default is false.
|
||||
include_disk_info | Boolean | Whether to include information about disk usage in the response. Default is false.
|
||||
|
||||
|
||||
## Request body
|
||||
|
||||
All cluster allocation explain fields are optional.
|
||||
|
||||
Field | Type | Description
|
||||
:--- | :--- | :---
|
||||
current_node | String | If you only want an explanation if the shard happens to be on a particular node, specify that node name here.
|
||||
index | String | The name of the shard's index.
|
||||
primary | Boolean | Whether to provide an explanation for the primary shard (true) or its first replica (false), which share the same shard ID.
|
||||
shard | Integer | The shard ID that you want an explanation for.
|
||||
|
||||
|
||||
## Response
|
||||
|
||||
```json
|
||||
{
|
||||
"index": "movies",
|
||||
"shard": 0,
|
||||
"primary": true,
|
||||
"current_state": "started",
|
||||
"current_node": {
|
||||
"id": "d8jRZcW1QmCBeVFlgOJx5A",
|
||||
"name": "opensearch-node1",
|
||||
"transport_address": "172.24.0.4:9300",
|
||||
"weight_ranking": 1
|
||||
},
|
||||
"can_remain_on_current_node": "yes",
|
||||
"can_rebalance_cluster": "yes",
|
||||
"can_rebalance_to_other_node": "no",
|
||||
"rebalance_explanation": "cannot rebalance as no target node exists that can both allocate this shard and improve the cluster balance",
|
||||
"node_allocation_decisions": [{
|
||||
"node_id": "vRxi4uPcRt2BtHlFoyCyTQ",
|
||||
"node_name": "opensearch-node2",
|
||||
"transport_address": "172.24.0.3:9300",
|
||||
"node_decision": "no",
|
||||
"weight_ranking": 1,
|
||||
"deciders": [{
|
||||
"decider": "max_retry",
|
||||
"decision": "YES",
|
||||
"explanation": "shard has no previous failures"
|
||||
},
|
||||
{
|
||||
"decider": "replica_after_primary_active",
|
||||
"decision": "YES",
|
||||
"explanation": "shard is primary and can be allocated"
|
||||
},
|
||||
{
|
||||
"decider": "enable",
|
||||
"decision": "YES",
|
||||
"explanation": "all allocations are allowed"
|
||||
},
|
||||
{
|
||||
"decider": "node_version",
|
||||
"decision": "YES",
|
||||
"explanation": "can relocate primary shard from a node with version [1.0.0] to a node with equal-or-newer version [1.0.0]"
|
||||
},
|
||||
{
|
||||
"decider": "snapshot_in_progress",
|
||||
"decision": "YES",
|
||||
"explanation": "no snapshots are currently running"
|
||||
},
|
||||
{
|
||||
"decider": "restore_in_progress",
|
||||
"decision": "YES",
|
||||
"explanation": "ignored as shard is not being recovered from a snapshot"
|
||||
},
|
||||
{
|
||||
"decider": "filter",
|
||||
"decision": "YES",
|
||||
"explanation": "node passes include/exclude/require filters"
|
||||
},
|
||||
{
|
||||
"decider": "same_shard",
|
||||
"decision": "NO",
|
||||
"explanation": "a copy of this shard is already allocated to this node [[movies][0], node[vRxi4uPcRt2BtHlFoyCyTQ], [R], s[STARTED], a[id=x8w7QxWdQQa188HKGn0iMQ]]"
|
||||
},
|
||||
{
|
||||
"decider": "disk_threshold",
|
||||
"decision": "YES",
|
||||
"explanation": "enough disk for shard on node, free: [35.9gb], shard size: [15.1kb], free after allocating shard: [35.9gb]"
|
||||
},
|
||||
{
|
||||
"decider": "throttling",
|
||||
"decision": "YES",
|
||||
"explanation": "below shard recovery limit of outgoing: [0 < 2] incoming: [0 < 2]"
|
||||
},
|
||||
{
|
||||
"decider": "shards_limit",
|
||||
"decision": "YES",
|
||||
"explanation": "total shard limits are disabled: [index: -1, cluster: -1] <= 0"
|
||||
},
|
||||
{
|
||||
"decider": "awareness",
|
||||
"decision": "YES",
|
||||
"explanation": "allocation awareness is not enabled, set cluster setting [cluster.routing.allocation.awareness.attributes] to enable it"
|
||||
}
|
||||
]
|
||||
}]
|
||||
}
|
||||
```
|
||||
@@ -1,71 +0,0 @@
|
||||
---
|
||||
layout: default
|
||||
title: Cluster health
|
||||
parent: REST API reference
|
||||
nav_order: 15
|
||||
---
|
||||
|
||||
# Cluster health
|
||||
|
||||
The most basic cluster health request returns a simple status of the health of your cluster. OpenSearch expresses cluster health in three colors: green, yellow, and red. A green status means all primary shards and their replicas are allocated to nodes. A yellow status means all primary shards are allocated to nodes, but some replicas aren't. A red status means at least one primary shard is not allocated to any node.
|
||||
|
||||
To get the status of a specific index, provide the index name.
|
||||
|
||||
## Example
|
||||
|
||||
This request waits 50 seconds for the cluster to reach the yellow status or better:
|
||||
|
||||
```
|
||||
GET _cluster/health?wait_for_status=yellow&timeout=50s
|
||||
```
|
||||
|
||||
If the cluster health becomes yellow or green before 50 seconds elapse, it returns a response immediately. Otherwise it returns a response as soon as it exceeds the timeout.
|
||||
|
||||
## Path and HTTP methods
|
||||
|
||||
```
|
||||
GET _cluster/health
|
||||
GET _cluster/health/<index>
|
||||
```
|
||||
|
||||
## URL parameters
|
||||
|
||||
All cluster health parameters are optional.
|
||||
|
||||
Parameter | Type | Description
|
||||
:--- | :--- | :---
|
||||
expand_wildcards | Enum | Expands wildcard expressions to concrete indices. Combine multiple values with commas. Supported values are `all`, `open`, `closed`, `hidden`, and `none`. Default is `open`.
|
||||
level | Enum | The level of detail for returned health information. Supported values are `cluster`, `indices`, and `shards`. Default is `cluster`.
|
||||
local | Boolean | Whether to return information from the local node only instead of from the master node. Default is false.
|
||||
master_timeout | Time | The amount of time to wait for a connection to the master node. Default is 30 seconds.
|
||||
timeout | Time | The amount of time to wait for a response. If the timeout expires, the request fails. Default is 30 seconds.
|
||||
wait_for_active_shards | String | Wait until the specified number of shards is active before returning a response. `all` for all shards. Default is `0`.
|
||||
wait_for_events | Enum | Wait until all currently queued events with the given priority are processed. Supported values are `immediate`, `urgent`, `high`, `normal`, `low`, and `languid`.
|
||||
wait_for_no_relocating_shards | Boolean | Whether to wait until there are no relocating shards in the cluster. Default is false.
|
||||
wait_for_no_initializing_shards | Boolean | Whether to wait until there are no initializing shards in the cluster. Default is false.
|
||||
wait_for_status | Enum | Wait until the cluster is in a specific state or better. Supported values are `green`, `yellow`, and `red`.
|
||||
|
||||
<!-- wait_for_nodes | string | Wait until the specified number of nodes is available. Also supports operators <=, >=, <, and >
|
||||
# Not working properly when tested -->
|
||||
|
||||
## Response
|
||||
|
||||
```json
|
||||
{
|
||||
"cluster_name" : "opensearch-cluster",
|
||||
"status" : "green",
|
||||
"timed_out" : false,
|
||||
"number_of_nodes" : 2,
|
||||
"number_of_data_nodes" : 2,
|
||||
"active_primary_shards" : 6,
|
||||
"active_shards" : 12,
|
||||
"relocating_shards" : 0,
|
||||
"initializing_shards" : 0,
|
||||
"unassigned_shards" : 0,
|
||||
"delayed_unassigned_shards" : 0,
|
||||
"number_of_pending_tasks" : 0,
|
||||
"number_of_in_flight_fetch" : 0,
|
||||
"task_max_waiting_in_queue_millis" : 0,
|
||||
"active_shards_percent_as_number" : 100.0
|
||||
}
|
||||
```
|
||||
@@ -1,83 +0,0 @@
|
||||
---
|
||||
layout: default
|
||||
title: Cluster settings
|
||||
parent: REST API reference
|
||||
nav_order: 20
|
||||
---
|
||||
|
||||
# Cluster settings
|
||||
|
||||
The cluster settings operation lets you check the current settings for your cluster, review default settings, and change settings. When you update a setting using the API, OpenSearch applies it to all nodes in the cluster.
|
||||
|
||||
|
||||
## Examples
|
||||
|
||||
```json
|
||||
GET _cluster/settings?include_defaults=true
|
||||
```
|
||||
|
||||
```json
|
||||
PUT _cluster/settings
|
||||
{
|
||||
"persistent": {
|
||||
"action": {
|
||||
"auto_create_index": false
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
|
||||
## Path and HTTP methods
|
||||
|
||||
```
|
||||
GET _cluster/settings
|
||||
PUT _cluster/settings
|
||||
```
|
||||
|
||||
|
||||
## URL parameters
|
||||
|
||||
All cluster settings parameters are optional.
|
||||
|
||||
Parameter | Type | Description
|
||||
:--- | :--- | :---
|
||||
flat_settings | Boolean | Whether to return settings in the flat form, which can improve readability, especially for heavily nested settings. For example, the flat form of `"cluster": { "max_shards_per_node": 500 }` is `"cluster.max_shards_per_node": "500"`.
|
||||
include_defaults (GET only) | Boolean | Whether to include default settings as part of the response. This parameter is useful for identifying the names and current values of settings you want to update.
|
||||
master_timeout | Time | The amount of time to wait for a response from the master node. Default is 30 seconds.
|
||||
timeout (PUT only) | Time | The amount of time to wait for a response from the cluster. Default is 30 seconds.
|
||||
|
||||
|
||||
## Request body
|
||||
|
||||
The GET operation has no request body options.
|
||||
|
||||
For a PUT operation, the request body must contain `transient` or `persistent`, along with the setting you want to update:
|
||||
|
||||
```json
|
||||
PUT _cluster/settings
|
||||
{
|
||||
"persistent": {
|
||||
"cluster": {
|
||||
"max_shards_per_node": 500
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
For more information about transient settings, persistent settings, and precedence, see [OpenSearch configuration]({{site.url}}{{site.baseurl}}/opensearch/configuration/).
|
||||
|
||||
|
||||
## Response
|
||||
|
||||
```json
|
||||
{
|
||||
"acknowledged": true,
|
||||
"persistent": {
|
||||
"cluster": {
|
||||
"max_shards_per_node": "500"
|
||||
}
|
||||
},
|
||||
"transient": {}
|
||||
}
|
||||
```
|
||||
@@ -1,80 +0,0 @@
|
||||
---
|
||||
layout: default
|
||||
title: Alias
|
||||
parent: REST API reference
|
||||
grand_parent: OpenSearch
|
||||
nav_order: 8
|
||||
---
|
||||
|
||||
# Alias
|
||||
|
||||
An alias is a virtual pointer that you can use to reference one or more indices. Creating and updating aliases are atomic operations, so you can reindex your data and point an alias at it without any downtime.
|
||||
|
||||
|
||||
## Example
|
||||
|
||||
```json
|
||||
POST _aliases
|
||||
{
|
||||
"actions": [
|
||||
{
|
||||
"add": {
|
||||
"index": "movies",
|
||||
"alias": "movies-alias1"
|
||||
}
|
||||
},
|
||||
{
|
||||
"remove": {
|
||||
"index": "old-index",
|
||||
"alias": "old-index-alias"
|
||||
}
|
||||
}
|
||||
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
## Path and HTTP methods
|
||||
|
||||
```
|
||||
POST _aliases
|
||||
```
|
||||
|
||||
## URL parameters
|
||||
|
||||
All alias parameters are optional.
|
||||
|
||||
Parameter | Data Type | Description
|
||||
:--- | :--- | :---
|
||||
master_timeout | Time | The amount of time to wait for a response from the master node. Default is `30s`.
|
||||
timeout | Time | The amount of time to wait for a response from the cluster. Default is `30s`.
|
||||
|
||||
## Request body
|
||||
|
||||
In your request body, you need to specify what action to take, the alias name, and the index you want to associate with the alias. Other fields are optional.
|
||||
|
||||
Field | Data Type | Description | Required
|
||||
:--- | :--- | :--- | :---
|
||||
actions | Array | Set of actions you want to perform on the index. Valid options are: `add`, `remove`, and `remove_index`. You must have at least one action in the array. | Yes
|
||||
add | N/A | Adds an alias to the specified index. | No
|
||||
remove | N/A | Removes an alias from the specified index. | No
|
||||
remove_index | N/A | Deletes an index. | No
|
||||
index | String | Name of the index you want to associate with the alias. Supports wildcard expressions. | Yes if you don't supply an `indices` field in the body.
|
||||
indices | Array | Array of index names you want to associate with the alias. | Yes if you don't supply an `index` field in the body.
|
||||
alias | String | The name of the alias. | Yes if you don't supply an `aliases` field in the body.
|
||||
aliases | Array | Array of alias names. | Yes if you don't supply an `alias` field in the body.
|
||||
filter | Object | A filter to use with the alias, so the alias points to a filtered part of the index. | No
|
||||
is_hidden | Boolean | Specifies whether the alias should be hidden from results that include wildcard expressions | No
|
||||
must_exist | Boolean | Specifies whether the alias to remove must exist. | No
|
||||
is_write_index | Boolean | Specifies whether the index should be a write index. An alias can only have one write index at a time. | No
|
||||
routing | String | Used to assign a custom value to a shard for specific operations. | No
|
||||
index_routing | String | Assigns a custom value to a shard only for index operations. | No
|
||||
search_routing | String | Assigns a custom value to a shard only for search operations. | No
|
||||
|
||||
## Response
|
||||
|
||||
```json
|
||||
{
|
||||
"acknowledged": true
|
||||
}
|
||||
```
|
||||
@@ -1,162 +0,0 @@
|
||||
---
|
||||
layout: default
|
||||
title: Create index
|
||||
parent: REST API reference
|
||||
grand_parent: OpenSearch
|
||||
nav_order: 7
|
||||
---
|
||||
|
||||
# Create index
|
||||
|
||||
While you can create an index by using a document as a base, you can also just create an empty index for use later.
|
||||
|
||||
## Example
|
||||
|
||||
The following example demonstrates how to create an index with a non-default number of primary and replica shards, specifies that `age` is of type `integer`, and assigns a `sample-alias1` alias to the index.
|
||||
|
||||
```json
|
||||
PUT /sample-index1
|
||||
|
||||
{
|
||||
"settings": {
|
||||
"index": {
|
||||
"number_of_shards": 2,
|
||||
"number_of_replicas": 1
|
||||
}
|
||||
},
|
||||
"mappings": {
|
||||
"properties": {
|
||||
"age": {
|
||||
"type": "integer"
|
||||
}
|
||||
}
|
||||
},
|
||||
"aliases": {
|
||||
"sample-alias1": {}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Path and HTTP methods
|
||||
|
||||
```
|
||||
PUT <index-name>
|
||||
```
|
||||
|
||||
## Index naming restrictions
|
||||
|
||||
OpenSearch indices have the following naming restrictions:
|
||||
|
||||
- All letters must be lowercase.
|
||||
- Index names can't begin with underscores (`_`) or hyphens (`-`).
|
||||
- Index names can't contain spaces, commas, or the following characters:
|
||||
|
||||
`:`, `"`, `*`, `+`, `/`, `\`, `|`, `?`, `#`, `>`, or `<`
|
||||
|
||||
## URL parameters
|
||||
|
||||
You can include the following URL parameters in your request. All parameters are optional.
|
||||
|
||||
Parameter | Type | Description
|
||||
:--- | :--- | :---
|
||||
include_type_name | Boolean | If `true`, the request expects a type in the body of mappings. Because OpenSearch indices all have a type of `_doc`, we recommend that this parameter is left as the default of `false.`
|
||||
wait_for_active_shards | String | Specifies the number of active shards that must be available before OpenSearch processes the request. Default is 1 (only the primary shard). Set to `all` or a positive integer. Values greater than 1 require replicas. For example, if you specify a value of 3, the index must have two replicas distributed across two additional nodes for the request to succeed.
|
||||
master_timeout | Time | How long to wait for a connection to the master node. Default is `30s`.
|
||||
timeout | Time | How long to wait for the request to return. Default is `30s`.
|
||||
|
||||
## Request body
|
||||
|
||||
As part of your request, you can supply parameters in your request's body that specify index settings, mappings, and [aliases]({{site.url}}{{site.baseurl}}/opensearch/index-alias/) for your newly created index. The following sections provide more information about index settings and mappings.
|
||||
|
||||
|
||||
### Index settings
|
||||
|
||||
Index settings are separated into two varieties: static index settings and dynamic index settings. Static index settings are settings that you specify at index creation and can't change later. You can change dynamic settings at any time, including at index creation.
|
||||
|
||||
#### Static index settings
|
||||
|
||||
Setting | Description
|
||||
:--- | :---
|
||||
index.number_of_shards | The number of primary shards in the index. Default is 1.
|
||||
index.number_of_routing_shards | The number of routing shards used to split an index.
|
||||
index.shard.check_on_startup | Whether the index's shards should be checked for corruption. Available options are `false` (do not check for corruption), `checksum` (check for physical corruption), and `true` (check for both physical and logical corruption). Default is `false`.
|
||||
index.codec | The compression type to use to compress stored data. Available values are `best_compression` and `default`.
|
||||
index.routing_partition_size | The number of shards a custom routing value can go to. Routing helps an imbalanced cluster by relocating values to a subset of shards rather than just a single shard. To enable, set this value to greater than 1 but less than `index.number_of_shards`. Default is 1.
|
||||
index.soft_deletes_enabled | Whether to retain a history of operations performed on the index.
|
||||
index.soft_deletes.retention_lease.period | The maximum amount of time to retain a shard's history of operations. Default is `12h`.
|
||||
index.load_fixed_bitset_filters_eagerly | Indicates whether cached filters should be pre-loaded for nested queries. Available options are `true` and `false`. Default is `true`.
|
||||
index.hidden | Whether the index should be hidden. Hidden indices are not returned as part of queries that have wildcards. Available options are `true` and `false`. Default is `false`.
|
||||
|
||||
#### Dynamic index Settings
|
||||
|
||||
Setting | Description
|
||||
:--- | :---
|
||||
index.number_of_replicas | The number of replica shards each primary shard should have. For example, if you have 4 primary shards and set `index.number_of_replicas` to 3, the index has 12 replica shards. Default is 1.
|
||||
index.auto_expand_replicas | Automatically expands the number of replicas based on the amount of data nodes in the cluster. Specify a lower bound and upper limit (for example, 0-9), or `all` for the upper limit. For example, if you have 5 data nodes and set `index.auto_expand_replicas` to 0-3, then the cluster does not autoamtically add another replica shard. However, if you set this value to `0-all` and add 2 more nodes for a total of 7, the cluster will expand to now have 6 replica shards. Default is disabled.
|
||||
index.search.idle.after | Amount of time a shard should wait for a search or get request until it goes idle. Default is `30s`.
|
||||
index.refresh_interval | How often the index should refresh, which publishes its most recent changes and makes them available for searching. Can be set to `-1` to disable refreshing. Default is `1s`.
|
||||
index.max_result_window | The maximum value of `from` + `size` for searches to the index. `from` is the starting index to search from, and `size` is the amount of results to return. Default: 10000.
|
||||
index.max_inner_result_window | The maximum value of `from` + `size` for inner hits definitions and top hits aggregations to the index. `from` is the starting index to search from, and `size` is the amount of top hits to return. Default is 100.
|
||||
index.max_rescore_window | The maximum value of `window_size` for rescore requests to the index. Rescore requests reorder the index's documents and return a new score, which can be more precise. Default is the same as index.max_inner_result_window or 10000 by default.
|
||||
index.max_docvalue_fields_search | Maximum amount of `docvalue_fields` allowed in a query. Default is 100.
|
||||
index.max_script_fields | Maximum amount of `script_fields` allowed in a query. Default is 32.
|
||||
index.max_ngram_diff | Maximum allowed difference between `min_gram` and `max_gram` values for `NGramTokenizer` and `NGramTokenFilter`. Default is 1.
|
||||
index.max_shingle_diff | Maximum allowed difference between `max_shingle_size` and `min_shingle_size` for the `shingle` token filter. Default is 3.
|
||||
index.max_refresh_listeners | Maximum amount of refresh listeners available on the index's shards.
|
||||
index.analyze.max_token_count | Maximum amount of tokens that can return from the `_analyze` API operation. Default is 10000.
|
||||
index.highlight.max_analyzed_offset | The maximum amount of characters that will be analyzed in a highlight request. Default is 1000000.
|
||||
index.max_terms_count | The maximum amount of terms that can be used in a terms query. Default is 65536.
|
||||
index.max_regex_length | The maximum character length of regex that can be in a regexp query. Default is 1000.
|
||||
index.query.default_field | A field or list of fields that OpenSearch uses in queries in case a field isn't specified in the parameters.
|
||||
index.routing.allocation.enable | Specifies options for the index's shard allocation. Available options are `all` (allow shard allocation for all shards), `primaries` (allow shard allocation only for primary shards), `new_primaries` (allow shard allocaiton only for new primary shards), and `none` (do not allow shard allocation). Default is `all`.
|
||||
index.routing.rebalance.enable | Enables shard rebalancing for the index. Available options are `all` (allow shard rebalancing for all shards), `primaries`, (allow shard rebalancing only for primary shards), `replicas` (allow shard rebalancing only for replicas), and `none` (do not allow shard rebalancing). Default is `all`.
|
||||
index.gc_deletes | Amount of time to retain a deleted document's version number. Default is `60s`.
|
||||
index.default_pipeline | The default ingest node pipeline for the index. If the default pipeline is set and the pipeline does not exist, then index requests fail. The pipeline name `_none` specifies that the index does not have an ingest pipeline.
|
||||
index.final_pipeline | The final ingest node pipeline for the index. If the final pipeline is set and the pipeline does not exist, then index requests fail. The pipeline name `_none` specifies that the index does not have an ingest pipeline.
|
||||
|
||||
### Mappings
|
||||
|
||||
Mappings define how a documents and its fields are stored and indexed. If you're just starting to build out your cluster and data, you may not know exactly how your data should be stored. In those cases, you can use dynamic mappings, which tell OpenSearch to dynamically add data and their fields. However, if you know exactly what types your data fall under and want to enforce that standard, then you can use explicit mappings.
|
||||
|
||||
For example, if you want to indicate that `year` should be of type `text` instead of an `integer`, and `age` should be an `integer`, you can do so with explicit mappings. Using dynamic mapping, OpenSearch might interpret both `year` and `age` as integers.
|
||||
|
||||
#### Dynamic mapping types
|
||||
|
||||
Type | Description
|
||||
:--- | :---
|
||||
null | A `null` field can't be indexed or searched. When a field is set to null, OpenSearch behaves as if that field has no values.
|
||||
boolean | OpenSearch accepts `true` and `false` as boolean values. An empty string is equal to `false.`
|
||||
float | A single-precision 32-bit floating point number.
|
||||
double | A double-precision 64-bit floating point number.
|
||||
integer | A signed 32-bit number.
|
||||
object | Objects are standard JSON objects, which can have fields and mappings of their own. For example, a `movies` object can have additional properties such as `title`, `year`, and `director`.
|
||||
array | Arrays in OpenSearch can only store values of one type, such as an array of just integers or strings. Empty arrays are treated as though they are fields with no values.
|
||||
text | A string sequence of characters that represent full-text values.
|
||||
keyword | A string sequence of structured characters, such as an email or ZIP code.
|
||||
date detection string | Enabled by default, if new string fields match a date's format, then the string is processed as a `date` field. For example, `date: "2012/03/11"` is processed as a date.
|
||||
numeric detection string | If disabled, OpenSearch may automatically process numeric values as strings when they should be processed as numbers. When enabled, OpenSearch can process strings into `long`, `integer`, `short`, `byte`, `double`, `float`, `half_float`, `scaled_float`, `unsigned_long`. Default is disabled.
|
||||
|
||||
#### Explicit mapping
|
||||
|
||||
If you know exactly what your data's typings need to be, you can specify them in your request body when creating your index.
|
||||
|
||||
```json
|
||||
{
|
||||
"mappings": {
|
||||
"properties": {
|
||||
"year": { "type" : "text" },
|
||||
"age": { "type" : "integer" },
|
||||
"director":{ "type" : "text" }
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Response
|
||||
```json
|
||||
{
|
||||
"acknowledged": true,
|
||||
"shards_acknowledged": true,
|
||||
"index": "sample-index1"
|
||||
}
|
||||
```
|
||||
@@ -1,77 +0,0 @@
|
||||
---
|
||||
layout: default
|
||||
title: Get document
|
||||
parent: Document APIs
|
||||
grand_parent: REST API reference
|
||||
nav_order: 5
|
||||
---
|
||||
|
||||
# Get document
|
||||
|
||||
After adding a JSON document to your index, you can use the get document API operation to retrieve the document's information and data.
|
||||
|
||||
## Example
|
||||
|
||||
```json
|
||||
GET sample-index1/_doc/1
|
||||
```
|
||||
|
||||
## Path and HTTP methods
|
||||
|
||||
```
|
||||
GET <index>/_doc/<_id>
|
||||
HEAD <index>/_doc/<_id>
|
||||
```
|
||||
```
|
||||
GET <index>/_source/<_id>
|
||||
HEAD <index>/_source/<_id>
|
||||
```
|
||||
|
||||
## URL parameters
|
||||
|
||||
All get document URL parameters are optional.
|
||||
|
||||
Parameter | Type | Description
|
||||
:--- | :--- | :---
|
||||
preference | string | Specifies a preference of which shard to retrieve results from. Available options are `_local`, which tells the operation to retrieve results from a locally allocated shard replica, and a custom string value assigned to a specific shard replica. By default, OpenSearch executes get document operations on random shards.
|
||||
realtime | boolean | Specifies whether the operation should run in realtime. If false, the operation waits for the index to refresh to analyze the source to retrieve data, which makes the operation near-realtime. Default is true.
|
||||
refresh | boolean | If true, OpenSearch refreshes shards to make the operation visible to searching. Default is false.
|
||||
routing | string | A value used to route the operation to a specific shard.
|
||||
stored_fields | boolean | If true, the operation retrieves document fields stored in the index rather than the document's `_source`. Default is false.
|
||||
_source | string | Whether to include the `_source` field in the response body. Default is true.
|
||||
_source_excludes | string | A comma-separated list of source fields to exclude in the query response.
|
||||
_source_includes | string | A comma-separated list of source fields to include in the query response.
|
||||
version | integer | The version of the document to return, which must match the current version of the document.
|
||||
version_type | enum | Retrieves a specifically typed document. Available options are `external` (retrieve the document if the specified version number is greater than the document's current version) and `external_gte` (retrieve the document if the specified version number is greater than or equal to the document's current verison). For example, to retrieve version 3 of a document, use `/_doc/1?version=3&version_type=external`.
|
||||
|
||||
|
||||
## Response
|
||||
```json
|
||||
{
|
||||
"_index": "sample-index1",
|
||||
"_type": "_doc",
|
||||
"_id": "1",
|
||||
"_version": 1,
|
||||
"_seq_no": 0,
|
||||
"_primary_term": 9,
|
||||
"found": true,
|
||||
"_source": {
|
||||
"text": "This is just some sample text."
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Response body fields
|
||||
|
||||
Field | Description
|
||||
:--- | :---
|
||||
_index | The name of the index.
|
||||
_type | The document's type. OpenSearch only supports one type, which is `_doc`.
|
||||
_id | The document's id.
|
||||
_version | The document's version number. Updated whenever the document changes.
|
||||
_seq_no | The sequnce number assigned when the document is indexed.
|
||||
primary_term | The primary term assigned when the document is indexed.
|
||||
found | Whether the document exists.
|
||||
_routing | The shard that the document is routed to. If the document is not routed to a particular shard, this field is omitted.
|
||||
_source | Contains the document's data if `found` is true. If `_source` is set to false or `stored_fields` is set to true in the URL parameters, this field is omitted.
|
||||
_fields | Contains the document's data that's stored in the index. Only returned if both `stored_fields` and `found` are true.
|
||||
@@ -1,28 +0,0 @@
|
||||
---
|
||||
layout: default
|
||||
title: Document APIs
|
||||
parent: REST API reference
|
||||
has_children: true
|
||||
nav_order: 7
|
||||
---
|
||||
|
||||
# Document APIs
|
||||
|
||||
The document APIs allow you to handle documents relative to your index, such as adding, updating, and deleting documents.
|
||||
|
||||
Document APIs are separated into two categories: single document operations and multi-document operations. Multi-document operations offer performance advantages over submitting many individual requests, so whenever practical, we recommend that you use multi-document operations.
|
||||
|
||||
## Single document operations
|
||||
|
||||
- Index
|
||||
- Get
|
||||
- Delete
|
||||
- Update
|
||||
|
||||
## Multi-document operations
|
||||
|
||||
- Bulk
|
||||
- Multi get
|
||||
- Delete by query
|
||||
- Update by query
|
||||
- Reindex
|
||||
@@ -1,108 +0,0 @@
|
||||
---
|
||||
layout: default
|
||||
title: Scroll
|
||||
parent: REST API reference
|
||||
nav_order: 120
|
||||
---
|
||||
|
||||
# Scroll
|
||||
|
||||
You can use the `scroll` operation to retrieve a large number of results. For example, for machine learning jobs, you can request an unlimited number of results in batches.
|
||||
|
||||
To use the `scroll` operation, add a `scroll` parameter to the request header with a search context to tell OpenSearch how long you need to keep scrolling. This search context needs to be long enough to process a single batch of results.
|
||||
|
||||
Because search contexts consume a lot of memory, we suggest you don't use the `scroll` operation for frequent user queries. Instead, use the `sort` parameter with the `search_after` parameter to scroll responses for user queries.
|
||||
{: .note }
|
||||
|
||||
## Example
|
||||
|
||||
To set the number of results that you want returned for each batch, use the `size` parameter:
|
||||
|
||||
```json
|
||||
GET shakespeare/_search?scroll=10m
|
||||
{
|
||||
"size": 10000
|
||||
}
|
||||
```
|
||||
|
||||
OpenSearch caches the results and returns a scroll ID to access them in batches:
|
||||
|
||||
```json
|
||||
"_scroll_id" : "DXF1ZXJ5QW5kRmV0Y2gBAAAAAAAAAAUWdmpUZDhnRFBUcWFtV21nMmFwUGJEQQ=="
|
||||
```
|
||||
|
||||
Pass this scroll ID to the `scroll` operation to get back the next batch of results:
|
||||
|
||||
```json
|
||||
GET _search/scroll
|
||||
{
|
||||
"scroll": "10m",
|
||||
"scroll_id": "DXF1ZXJ5QW5kRmV0Y2gBAAAAAAAAAAUWdmpUZDhnRFBUcWFtV21nMmFwUGJEQQ=="
|
||||
}
|
||||
```
|
||||
|
||||
Using this scroll ID, you get results in batches of 10,000 as long as the search context is still open. Typically, the scroll ID does not change between requests, but it *can* change, so make sure to always use the latest scroll ID. If you don't send the next scroll request within the set search context, the `scroll` operation does not return any results.
|
||||
|
||||
If you expect billions of results, use a sliced scroll. Slicing allows you to perform multiple scroll operations for the same request, but in parallel.
|
||||
Set the ID and the maximum number of slices for the scroll:
|
||||
|
||||
```json
|
||||
GET shakespeare/_search?scroll=10m
|
||||
{
|
||||
"slice": {
|
||||
"id": 0,
|
||||
"max": 10
|
||||
},
|
||||
"query": {
|
||||
"match_all": {}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
With a single scroll ID, you get back 10 results.
|
||||
You can have up to 10 IDs.
|
||||
|
||||
Close the search context when you’re done scrolling, because the `scroll` operation continues to consume computing resources until the timeout:
|
||||
|
||||
```json
|
||||
DELETE _search/scroll/DXF1ZXJ5QW5kRmV0Y2gBAAAAAAAAAAcWdmpUZDhnRFBUcWFtV21nMmFwUGJEQQ==
|
||||
```
|
||||
|
||||
To close all open scroll contexts:
|
||||
|
||||
```json
|
||||
DELETE _search/scroll/_all
|
||||
```
|
||||
|
||||
The `scroll` operation corresponds to a specific timestamp. It doesn't consider documents added after that timestamp as potential results.
|
||||
|
||||
|
||||
## Path and HTTP methods
|
||||
|
||||
```
|
||||
GET _search/scroll
|
||||
POST _search/scroll
|
||||
```
|
||||
```
|
||||
GET _search/scroll/<scroll-id>
|
||||
POST _search/scroll/<scroll-id>
|
||||
```
|
||||
|
||||
## URL parameters
|
||||
|
||||
All scroll parameters are optional.
|
||||
|
||||
Parameter | Type | Description
|
||||
:--- | :--- | :---
|
||||
scroll | Time | Specifies the amount of time the search context is maintained.
|
||||
scroll_id | String | The scroll ID for the search.
|
||||
rest_total_hits_as_int | Boolean | Whether the `hits.total` property is returned as an integer or an object. Default is false.
|
||||
|
||||
## Response
|
||||
|
||||
```json
|
||||
{
|
||||
"succeeded": true,
|
||||
"num_freed": 1
|
||||
}
|
||||
```
|
||||
@@ -31,10 +31,6 @@ code {
|
||||
padding-top: 2rem;
|
||||
}
|
||||
|
||||
.nav-category {
|
||||
text-align: start;
|
||||
}
|
||||
|
||||
.main-content {
|
||||
ol {
|
||||
> li {
|
||||
|
||||
@@ -1,60 +0,0 @@
|
||||
---
|
||||
layout: default
|
||||
title: k-NN Index
|
||||
nav_order: 1
|
||||
parent: k-NN
|
||||
has_children: false
|
||||
redirect_from: /docs/knn/knn-index/
|
||||
---
|
||||
|
||||
# k-NN Index
|
||||
|
||||
## knn_vector data type
|
||||
|
||||
The k-NN plugin introduces a custom data type, the `knn_vector`, that allows users to ingest their k-NN vectors
|
||||
into an OpenSearch index.
|
||||
|
||||
```json
|
||||
"my_vector": {
|
||||
"type": "knn_vector",
|
||||
"dimension": 4,
|
||||
"method": {
|
||||
"name": "hnsw",
|
||||
"space_type": "l2",
|
||||
"engine": "nmslib",
|
||||
"parameters": {
|
||||
"ef_construction": 128,
|
||||
"m": 24
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Mapping Pararameter | Required | Default | Updateable | Description
|
||||
:--- | :--- | :--- | :--- | :---
|
||||
`type` | true | n/a | false | The type of the field
|
||||
`dimension` | true | n/a | false | The vector dimension for the field
|
||||
`method` | false | null | false | The configuration for the Approximate nearest neighbor method
|
||||
`method.name` | true, if `method` is specified | n/a | false | The identifier for the nearest neighbor method. Currently, "hnsw" is the only valid method.
|
||||
`method.space_type` | false | "l2" | false | The vector space used to calculate the distance between vectors. Refer to [here]({{site.url}}{{site.baseurl}}/search-plugins/knn/approximate-knn#spaces)) to see available spaces.
|
||||
`method.engine` | false | "nmslib" | false | The approximate k-NN library to use for indexing and search. Currently, "nmslib" is the only valid engine.
|
||||
`method.parameters` | false | null | false | The parameters used for the nearest neighbor method.
|
||||
`method.parameters.ef_construction` | false | 512 | false | The size of the dynamic list used during k-NN graph creation. Higher values lead to a more accurate graph, but slower indexing speed. Only valid for "hnsw" method.
|
||||
`method.parameters.m` | false | 16 | false | The number of bidirectional links that the plugin creates for each new element. Increasing and decreasing this value can have a large impact on memory consumption. Keep this value between 2-100. Only valid for "hnsw" method
|
||||
|
||||
## Index settings
|
||||
|
||||
Additionally, the k-NN plugin introduces several index settings that can be used to configure the k-NN structure as well.
|
||||
|
||||
At the moment, several parameters defined in the settings are in the deprecation process. Those parameters should be set
|
||||
in the mapping instead of the index settings. Parameters set in the mapping will override the parameters set in the
|
||||
index settings. Setting the parameters in the mapping allows an index to have multiple `knn_vector` fields with
|
||||
different parameters.
|
||||
|
||||
Setting | Default | Updateable | Description
|
||||
:--- | :--- | :--- | :---
|
||||
`index.knn` | false | false | Whether the index should build hnsw graphs for the `knn_vector` fields. If set to false, the `knn_vector` fields will be stored in doc values, but Approximate k-NN search functionality will be disabled.
|
||||
`index.knn.algo_param.ef_search` | 512 | true | The size of the dynamic list used during k-NN searches. Higher values lead to more accurate but slower searches.
|
||||
`index.knn.algo_param.ef_construction` | 512 | false | (Deprecated in 1.0.0. Use the mapping parameters to set this value instead.) Refer to mapping definition.
|
||||
`index.knn.algo_param.m` | 16 | false | (Deprecated in 1.0.0. Use the mapping parameters to set this value instead.) Refer to mapping definition.
|
||||
`index.knn.space_type` | "l2" | false | (Deprecated in 1.0.0. Use the mapping parameters to set this value instead.) Refer to mapping definition.
|
||||
@@ -1,50 +0,0 @@
|
||||
---
|
||||
layout: default
|
||||
title: Settings
|
||||
parent: Piped processing language
|
||||
nav_order: 3
|
||||
redirect_from: /docs/ppl/settings/
|
||||
---
|
||||
|
||||
# Settings
|
||||
|
||||
The PPL plugin adds a few settings to the standard OpenSearch cluster settings. Most are dynamic, so you can change the default behavior of the plugin without restarting your cluster.
|
||||
|
||||
You can update these settings like any other cluster setting:
|
||||
|
||||
```json
|
||||
PUT _cluster/settings
|
||||
{
|
||||
"transient": {
|
||||
"plugins": {
|
||||
"ppl": {
|
||||
"enabled": "false"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Similarly, you can also update the settings by sending request to the plugin setting endpoint `_plugins/_query/settings` :
|
||||
```json
|
||||
PUT _plugins/_query/settings
|
||||
{
|
||||
"transient": {
|
||||
"plugins": {
|
||||
"ppl": {
|
||||
"enabled": "false"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Requests to `_plugins/_ppl` include index names in the request body, so they have the same access policy considerations as the `bulk`, `mget`, and `msearch` operations. If you set the `rest.action.multi.allow_explicit_index` parameter to `false`, the PPL plugin is disabled.
|
||||
|
||||
You can specify the settings shown in the following table:
|
||||
|
||||
Setting | Description | Default
|
||||
:--- | :--- | :---
|
||||
`plugins.ppl.enabled` | Change to `false` to disable the PPL component. | True
|
||||
`plugins.query.memory_limit` | Set heap memory usage limit. If a query crosses this limit, it's terminated. | 85%
|
||||
`plugins.query.size_limit` | Set the maximum number of results that you want to see. This impacts the accuracy of aggregation operations. For example, if you have 1000 documents in an index, by default, only 200 documents are extracted from the index for aggregation. | 200
|
||||
@@ -1,40 +0,0 @@
|
||||
---
|
||||
layout: default
|
||||
title: Settings
|
||||
parent: SQL
|
||||
nav_order: 16
|
||||
redirect_from: /docs/sql/settings/
|
||||
---
|
||||
|
||||
# Settings
|
||||
|
||||
The SQL plugin adds a few settings to the standard OpenSearch cluster settings. Most are dynamic, so you can change the default behavior of the plugin without restarting your cluster.
|
||||
|
||||
You can update these settings like any other cluster setting:
|
||||
|
||||
```json
|
||||
PUT _cluster/settings
|
||||
{
|
||||
"transient" : {
|
||||
"plugins.sql.enabled" : false
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Similarly, you can also update the settings by sending the request to the plugin setting endpoint `_plugins/_query/setting`:
|
||||
```json
|
||||
PUT _plugins/_query/settings
|
||||
{
|
||||
"transient" : {
|
||||
"plugins.sql.enabled" : false
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Setting | Default | Description
|
||||
:--- | :--- | :---
|
||||
`plugins.sql.enabled` | True | Change to `false` to disable the plugin.
|
||||
`plugins.sql.slowlog` | 2 seconds | Configure the time limit (in seconds) for slow queries. The plugin logs slow queries as `Slow query: elapsed=xxx (ms)` in `opensearch.log`.
|
||||
`plugins.sql.cursor.keep_alive` | 1 minute | This value configures how long the cursor context is kept open. Cursor contexts are resource heavy, so we recommend a low value.
|
||||
`plugins.query.memory_limit` | 85% | This setting configures the heap memory usage limit for the circuit breaker of the query engine.
|
||||
`plugins.query.size_limit` | 200 | The setting sets the default size of index that the query engine fetches from OpenSearch.
|
||||
@@ -1,109 +0,0 @@
|
||||
---
|
||||
layout: default
|
||||
title: Audit Log Storage Types
|
||||
parent: Audit Logs
|
||||
nav_order: 10
|
||||
redirect_from: /docs/security/audit-logs/storage-types/
|
||||
---
|
||||
|
||||
# Audit log storage types
|
||||
|
||||
Audit logs can take up quite a bit of space, so the security plugin offers several options for storage locations.
|
||||
|
||||
Setting | Description
|
||||
:--- | :---
|
||||
debug | Outputs to stdout. Useful for testing and debugging.
|
||||
internal_opensearch | Writes to an audit index on the current OpenSearch cluster.
|
||||
external_opensearch | Writes to an audit index on a remote OpenSearch cluster.
|
||||
webhook | Sends events to an arbitrary HTTP endpoint.
|
||||
log4j | Writes the events to a Log4j logger. You can use any Log4j [appender](https://logging.apache.org/log4j/2.x/manual/appenders.html), such as SNMP, JDBC, Cassandra, and Kafka.
|
||||
|
||||
You configure the output location in `opensearch.yml`:
|
||||
|
||||
```
|
||||
plugins.security.audit.type: <debug|internal_opensearch|external_opensearch|webhook|log4j>
|
||||
```
|
||||
|
||||
`external_opensearch`, `webhook`, and `log4j` all have additional configuration options. Details follow.
|
||||
|
||||
|
||||
## External OpenSearch
|
||||
|
||||
The `external_opensearch` storage type requires one or more OpenSearch endpoints with a host/IP address and port. Optionally, provide the index name and a document type.
|
||||
|
||||
```yml
|
||||
plugins.security.audit.type: external_opensearch
|
||||
plugins.security.audit.config.http_endpoints: [<endpoints>]
|
||||
plugins.security.audit.config.index: <indexname>
|
||||
plugins.security.audit.config.type: _doc
|
||||
```
|
||||
|
||||
The security plugin uses the OpenSearch REST API to send events, just like any other indexing request. For `plugins.security.audit.config.http_endpoints`, use a comma-separated list of hosts/IP addresses and the REST port (default 9200).
|
||||
|
||||
```
|
||||
plugins.security.audit.config.http_endpoints: [192.168.178.1:9200,192.168.178.2:9200]
|
||||
```
|
||||
|
||||
If you use `external_opensearch` and the remote cluster also uses the security plugin, you must supply some additional parameters for authentication. These parameters depend on which authentication type you configured for the remote cluster.
|
||||
|
||||
|
||||
### TLS settings
|
||||
|
||||
Name | Data Type | Description
|
||||
:--- | :--- | :---
|
||||
`plugins.security.audit.config.enable_ssl` | Boolean | If you enabled SSL/TLS on the receiving cluster, set to true. The default is false.
|
||||
`plugins.security.audit.config.verify_hostnames` | Boolean | Whether to verify the hostname of the SSL/TLS certificate of the receiving cluster. Default is true.
|
||||
`plugins.security.audit.config.pemtrustedcas_filepath` | String | The trusted root certificate of the external OpenSearch cluster, relative to the `config` directory.
|
||||
`plugins.security.audit.config.pemtrustedcas_content` | String | Instead of specifying the path (`plugins.security.audit.config.pemtrustedcas_filepath`), you can configure the Base64-encoded certificate content directly.
|
||||
`plugins.security.audit.config.enable_ssl_client_auth` | Boolean | Whether to enable SSL/TLS client authentication. If you set this to true, the audit log module sends the node's certificate along with the request. The receiving cluster can use this certificate to verify the identity of the caller.
|
||||
`plugins.security.audit.config.pemcert_filepath` | String | The path to the TLS certificate to send to the external OpenSearch cluster, relative to the `config` directory.
|
||||
`plugins.security.audit.config.pemcert_content` | String | Instead of specifying the path (`plugins.security.audit.config.pemcert_filepath`), you can configure the Base64-encoded certificate content directly.
|
||||
`plugins.security.audit.config.pemkey_filepath` | String | The path to the private key of the TLS certificate to send to the external OpenSearch cluster, relative to the `config` directory.
|
||||
`plugins.security.audit.config.pemkey_content` | String | Instead of specifying the path (`plugins.security.audit.config.pemkey_filepath`), you can configure the Base64-encoded certificate content directly.
|
||||
`plugins.security.audit.config.pemkey_password` | String | The password of the private key.
|
||||
|
||||
|
||||
### Basic auth settings
|
||||
|
||||
If you enabled HTTP basic authentication on the receiving cluster, use these settings to specify the username and password:
|
||||
|
||||
```yml
|
||||
plugins.security.audit.config.username: <username>
|
||||
plugins.security.audit.config.password: <password>
|
||||
```
|
||||
|
||||
|
||||
## Webhook
|
||||
|
||||
Use the following keys to configure the `webhook` storage type.
|
||||
|
||||
Name | Data Type | Description
|
||||
:--- | :--- | :---
|
||||
`plugins.security.audit.config.webhook.url` | String | The HTTP or HTTPS URL to send the logs to.
|
||||
`plugins.security.audit.config.webhook.ssl.verify` | Boolean | If true, the TLS certificate provided by the endpoint (if any) will be verified. If set to false, no verification is performed. You can disable this check if you use self-signed certificates.
|
||||
`plugins.security.audit.config.webhook.ssl.pemtrustedcas_filepath` | String | The path to the trusted certificate against which the webhook's TLS certificate is validated.
|
||||
`plugins.security.audit.config.webhook.ssl.pemtrustedcas_content` | String | Same as `plugins.security.audit.config.webhook.ssl.pemtrustedcas_content`, but you can configure the base 64 encoded certificate content directly.
|
||||
`plugins.security.audit.config.webhook.format` | String | The format in which the audit log message is logged, can be one of `URL_PARAMETER_GET`, `URL_PARAMETER_POST`, `TEXT`, `JSON`, `SLACK`. See [Formats](#formats).
|
||||
|
||||
|
||||
### Formats
|
||||
|
||||
Format | Description
|
||||
:--- | :---
|
||||
`URL_PARAMETER_GET` | Uses HTTP GET to send logs to the webhook URL. All logged information is appended to the URL as request parameters.
|
||||
`URL_PARAMETER_POST` | Uses HTTP POST to send logs to the webhook URL. All logged information is appended to the URL as request parameters.
|
||||
`TEXT` | Uses HTTP POST to send logs to the webhook URL. The request body contains the audit log message in plain text format.
|
||||
`JSON` | Uses HTTP POST to send logs to the webhook URL. The request body contains the audit log message in JSON format.
|
||||
`SLACK` | Uses HTTP POST to send logs to the webhook URL. The request body contains the audit log message in JSON format suitable for consumption by Slack. The default implementation returns `"text": "<AuditMessage#toText>"`.
|
||||
|
||||
|
||||
## Log4j
|
||||
|
||||
The `log4j` storage type lets you specify the name of the logger and log level.
|
||||
|
||||
```yml
|
||||
plugins.security.audit.config.log4j.logger_name: audit
|
||||
plugins.security.audit.config.log4j.level: INFO
|
||||
```
|
||||
|
||||
By default, the security plugin uses the logger name `audit` and logs the events on `INFO` level. Audit events are stored in JSON format.
|
||||
@@ -1,25 +0,0 @@
|
||||
---
|
||||
layout: default
|
||||
title: Configuration
|
||||
nav_order: 5
|
||||
has_children: true
|
||||
has_toc: false
|
||||
redirect_from:
|
||||
- /docs/security/configuration/
|
||||
- /security-plugin/configuration/
|
||||
---
|
||||
|
||||
# Security configuration
|
||||
|
||||
The plugin includes demo certificates so that you can get up and running quickly, but before using OpenSearch in a production environment, you must configure it manually:
|
||||
|
||||
1. [Replace the demo certificates]({{site.url}}{{site.baseurl}}/opensearch/install/docker-security).
|
||||
1. [Reconfigure opensearch.yml to use your certificates]({{site.url}}{{site.baseurl}}/security-plugin/configuration/tls).
|
||||
1. [Reconfigure config.yml to use your authentication backend]({{site.url}}{{site.baseurl}}/security-plugin/configuration/configuration/) (if you don't plan to use the internal user database).
|
||||
1. [Modify the configuration YAML files]({{site.url}}{{site.baseurl}}/security-plugin/configuration/yaml).
|
||||
1. If you plan to use the internal user database, [set a password policy in opensearch.yml]({{site.url}}{{site.baseurl}}/security-plugin/configuration/yaml/#opensearchyml).
|
||||
1. [Apply changes using securityadmin.sh]({{site.url}}{{site.baseurl}}/security-plugin/configuration/security-admin).
|
||||
1. Start OpenSearch.
|
||||
1. [Add users, roles, role mappings, and tenants]({{site.url}}{{site.baseurl}}/security-plugin/access-control/index/).
|
||||
|
||||
If you don't want to use the plugin, see [Disable security]({{site.url}}{{site.baseurl}}/security-plugin/configuration/disable).
|
||||
@@ -1,26 +0,0 @@
|
||||
---
|
||||
layout: default
|
||||
title: System Indices
|
||||
parent: Configuration
|
||||
nav_order: 15
|
||||
redirect_from: /docs/security/configuration/system-indices/
|
||||
---
|
||||
|
||||
# System indices
|
||||
|
||||
By default, OpenSearch has a protected system index, `.opendistro_security`, which you create using [securityadmin.sh]({{site.url}}{{site.baseurl}}/security-plugin/configuration/security-admin/). Even if your user account has read permissions for all indices, you can't directly access the data in this system index.
|
||||
|
||||
You can add additional system indices in in `opensearch.yml`. In addition to automatically creating `.opendistro_security`, the demo configuration adds several indices for the various OpenSearch plugins that integrate with the security plugin:
|
||||
|
||||
```yml
|
||||
plugins.security.system_indices.enabled: true
|
||||
plugins.security.system_indices.indices: [".opendistro-alerting-config", ".opendistro-alerting-alert*", ".opendistro-anomaly-results*", ".opendistro-anomaly-detector*", ".opendistro-anomaly-checkpoints", ".opendistro-anomaly-detection-state", ".opendistro-reports-*", ".opendistro-notifications-*", ".opendistro-notebooks", ".opendistro-asynchronous-search-response*"]
|
||||
```
|
||||
|
||||
To access these indices, you must authenticate with an [admin certificate]({{site.url}}{{site.baseurl}}/security-plugin/configuration/tls#configure-admin-certificates):
|
||||
|
||||
```bash
|
||||
curl -k --cert ./kirk.pem --key ./kirk-key.pem -XGET 'https://localhost:9200/.opendistro_security/_search'
|
||||
```
|
||||
|
||||
The alternative is to remove indices from the `plugins.security.system_indices.indices` list on each node and restart OpenSearch.
|
||||
@@ -1,38 +0,0 @@
|
||||
---
|
||||
layout: default
|
||||
title: Upgrade from Kibana OSS to OpenSearch Dashboards
|
||||
nav_order: 50
|
||||
redirect_from:
|
||||
- /migrate/dashboards/
|
||||
---
|
||||
|
||||
# Upgrade from Kibana OSS to OpenSearch Dashboards
|
||||
|
||||
Kibana OSS stores its visualizations and dashboards in one or more indices (`.kibana*`) on the Elasticsearch OSS cluster. As such, the most important step is to leave those indices intact as you upgrade from Elasticsearch OSS to OpenSearch.
|
||||
|
||||
Consider exporting all Kibana objects prior to starting the upgrade. In Kibana, choose **Stack Management**, **Saved Objects**, **Export objects**.
|
||||
{: .tip }
|
||||
|
||||
1. After you upgrade your Elasticsearch OSS cluster to OpenSearch, stop Kibana.
|
||||
|
||||
1. For safety, make a backup copy of `<kibana-dir>/config/kibana.yml`.
|
||||
|
||||
1. Extract the OpenSearch Dashboards tarball to a new directory.
|
||||
|
||||
1. Port your settings from `<kibana-dir>/config/kibana.yml` to `<dashboards-dir>/config/opensearch_dashboards.yml`.
|
||||
|
||||
In general, settings with `elasticsearch` in their names map to `opensearch` (e.g. `elasticsearch.shardTimeout` and `opensearch.shardTimeout`) and settings with `kibana` in their names map to `opensearchDashboards` (e.g. `kibana.defaultAppId` and `opensearchDashboards.defaultAppId`). Most other settings use the same names.
|
||||
|
||||
For a full list of OpenSearch Dashboards settings, see [here](https://github.com/opensearch-project/OpenSearch-Dashboards/blob/main/config/opensearch_dashboards.yml){:target='\_blank'}.
|
||||
|
||||
1. If your OpenSearch cluster uses the security plugin, preserve and modify the default settings in `opensearch_dashboards.yml`, particularly `opensearch.username` and `opensearch.password`.
|
||||
|
||||
If you disabled the security plugin on your OpenSearch cluster, remove or comment out all `opensearch_security` settings. Then run `rm -rf plugins/security-dashboards/` to remove the security plugin.
|
||||
|
||||
1. Start OpenSearch Dashboards:
|
||||
|
||||
```
|
||||
./bin/opensearch-dashboards
|
||||
```
|
||||
|
||||
1. Log in, and verify that your saved searches, visualizations, and dashboards are present.
|
||||
@@ -1,15 +0,0 @@
|
||||
---
|
||||
layout: default
|
||||
title: Upgrade Docker clusters to OpenSearch
|
||||
nav_order: 25
|
||||
redirect_from:
|
||||
- /migrate/docker-migrate/
|
||||
---
|
||||
|
||||
# Upgrade Docker clusters to OpenSearch
|
||||
|
||||
If you use a container orchestration system like Kubernetes (or manage your containers manually) and want to avoid downtime, think of the process not as an upgrade of each node, but as a decommissioning and replacement of each node. One by one, add OpenSearch nodes to the cluster and remove Elasticsearch OSS nodes, pointing to existing data volumes as necessary and allowing time for all indices to return to a green status prior to proceeding.
|
||||
|
||||
If you use Docker Compose, we highly recommend that you perform what amounts to a [cluster restart upgrade]({{site.url}}{{site.baseurl}}/migrate/upgrade-migrate/). Update your cluster configuration with new images, new settings, and new environment variables, and test it. Then stop and start the cluster. This process requires downtime, but takes very few steps and lets you continue to treat the cluster as a single entity that you can reliably deploy and redeploy.
|
||||
|
||||
The most important step is to leave your data volumes intact. **Don't** run `docker-compose down -v`.
|
||||
@@ -1,21 +0,0 @@
|
||||
---
|
||||
layout: default
|
||||
title: About the process
|
||||
nav_order: 1
|
||||
redirect_from:
|
||||
- /migrate/
|
||||
- /upgrade-to/
|
||||
---
|
||||
|
||||
# About the process
|
||||
|
||||
The process of upgrading from Elasticsearch OSS (including Open Distro for Elasticsearch) to OpenSearch varies depending on your current version of Elasticsearch OSS, install type, tolerance for downtime, and cost-sensitivity. Rather than concrete steps to cover every situation, we have general guidance for the process.
|
||||
|
||||
Three approaches exist:
|
||||
|
||||
- Use a snapshot to [migrate your Elasticsearch OSS data]({{site.url}}{{site.baseurl}}/upgrade-to/snapshot-migrate/) to a new OpenSearch cluster.
|
||||
- Perform a [rolling upgrade or cluster restart upgrade]({{site.url}}{{site.baseurl}}/upgrade-to/upgrade-to/) on your existing nodes.
|
||||
- Replace existing Elasticsearch OSS nodes with new OpenSearch nodes. Node replacement is most popular when upgrading [Docker clusters]({{site.url}}{{site.baseurl}}/upgrade-to/docker-upgrade-to/).
|
||||
|
||||
Regardless of your approach, to safeguard against data loss, we recommend that you take a [snapshot]({{site.url}}{{site.baseurl}}/opensearch/snapshot-restore/) of all indices prior to any migration.
|
||||
{: .tip }
|
||||
@@ -1,13 +0,0 @@
|
||||
---
|
||||
layout: default
|
||||
title: Use snapshots to migrate data
|
||||
nav_order: 5
|
||||
redirect_from:
|
||||
- /migrate/snapshot-migrate/
|
||||
---
|
||||
|
||||
# Use snapshots to migrate data
|
||||
|
||||
One popular approach is to take a [snapshot]({{site.url}}{{site.baseurl}}/opensearch/snapshot-restore/) of your Elasticsearch OSS 6.x or 7.x indices, [create an OpenSearch cluster]({{site.url}}{{site.baseurl}}/opensearch/install/), restore the snapshot on the new cluster, and point your clients to the new host.
|
||||
|
||||
The snapshot approach can mean running two clusters in parallel, but lets you validate that the OpenSearch cluster is working in a way that meets your needs prior to modifying the Elasticsearch OSS cluster.
|
||||
@@ -1,174 +0,0 @@
|
||||
---
|
||||
layout: default
|
||||
title: Upgrade from Elasticsearch OSS to OpenSearch
|
||||
nav_order: 15
|
||||
redirect_from:
|
||||
- /migrate/upgrade-migrate/
|
||||
---
|
||||
|
||||
# Upgrade from Elasticsearch OSS to OpenSearch
|
||||
|
||||
If you want to upgrade from an existing Elasticsearch OSS cluster to OpenSearch and find the [snapshot approach]({{site.url}}{{site.baseurl}}/migrate/snapshot-migrate/) unappealing, you can upgrade your existing nodes from Elasticsearch OSS to OpenSearch.
|
||||
|
||||
If your existing cluster runs an older version of Elasticsearch OSS, the first step is to upgrade to version 6.x or 7.x. Elasticsearch OSS supports two types of upgrades: rolling and cluster restart.
|
||||
|
||||
- Rolling upgrades let you shut down one node at a time for minimal disruption of service.
|
||||
|
||||
Rolling upgrades work between minor versions (e.g. 6.5 to 6.8) and also support a single path to the next major version (e.g. 6.8 to 7.10.2). Performing these upgrades might require intermediate upgrades to arrive at your desired version and can affect cluster performance as nodes leave and rejoin, but the cluster remains available throughout the process.
|
||||
|
||||
- Cluster restart upgrades require you to shut down all nodes, perform the upgrade, and restart the cluster.
|
||||
|
||||
Cluster restart upgrades work between minor versions (e.g. 6.5 to 6.8) and the next major version (for example, 6.x to 7.10.2). Cluster restart upgrades are faster to perform and require fewer intermediate upgrades, but require downtime.
|
||||
|
||||
|
||||
## Upgrade paths
|
||||
|
||||
Elasticsearch OSS version | Rolling upgrade path | Cluster restart upgrade path
|
||||
:--- | :--- | :---
|
||||
5.x | Upgrade to 5.6, upgrade to 6.8, reindex all 5.x indices, upgrade to 7.10.2, and upgrade to OpenSearch. | Upgrade to 6.8, reindex all 5.x indices, and upgrade to OpenSearch.
|
||||
6.x | Upgrade to 6.8, upgrade to 7.10.2, and upgrade to OpenSearch. | Upgrade to OpenSearch.
|
||||
7.x | Upgrade to OpenSearch. | Upgrade to OpenSearch.
|
||||
|
||||
|
||||
## Upgrade Elasticsearch OSS
|
||||
|
||||
1. Disable shard allocation to prevent Elasticsearch OSS from replicating shards as you shut down nodes:
|
||||
|
||||
```json
|
||||
PUT _cluster/settings
|
||||
{
|
||||
"persistent": {
|
||||
"cluster.routing.allocation.enable": "primaries"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
1. Stop Elasticsearch OSS on one node (rolling upgrade) or all nodes (cluster restart upgrade).
|
||||
|
||||
On Linux distributions that use systemd, use this command:
|
||||
|
||||
```bash
|
||||
sudo systemctl stop elasticsearch.service
|
||||
```
|
||||
|
||||
For tarball installations, find the process ID (`ps aux`) and kill it (`kill <pid>`).
|
||||
|
||||
1. Upgrade the node (rolling) or all nodes (cluster restart).
|
||||
|
||||
The exact command varies by package manager, but likely looks something like this:
|
||||
|
||||
```bash
|
||||
sudo yum install elasticsearch-oss-7.10.2 --enablerepo=elasticsearch
|
||||
```
|
||||
|
||||
For tarball installations, extract to a new directory to ensure you **do not overwrite** your `config`, `data`, and `logs` directories. Ideally, these directories should have their own, independent paths and *not* be colocated with the Elasticsearch application directory. Then set the `ES_PATH_CONF` environment variable to the directory that contains `elasticsearch.yml` (e.g. `/etc/elasticesarch/`). In `elasticsearch.yml`, set `path.data` and `path.logs` to your `data` and `logs` directories (e.g. `/var/lib/elasticsearch` and `/var/log/opensearch`).
|
||||
|
||||
1. Restart Elasticsearch OSS on the node (rolling) or all nodes (cluster restart).
|
||||
|
||||
On Linux distributions that use systemd, use this command:
|
||||
|
||||
```bash
|
||||
sudo systemctl start elasticsearch.service
|
||||
```
|
||||
|
||||
For tarball installations, run `./bin/elasticsearch -d`.
|
||||
|
||||
1. Wait for the node to rejoin the cluster (rolling) or for the cluster to start (cluster restart). Check the `_nodes` summary to verify that all nodes are available and running the expected version:
|
||||
|
||||
```bash
|
||||
# Elasticsearch OSS
|
||||
curl -XGET 'localhost:9200/_nodes/_all?pretty=true'
|
||||
# Open Distro for Elasticsearch with security plugin enabled
|
||||
curl -XGET 'https://localhost:9200/_nodes/_all?pretty=true' -u 'admin:admin' -k
|
||||
```
|
||||
|
||||
Specifically, check the `nodes.<node-id>.version` portion of the response. Also check `_cat/indices?v` for a green status on all indices.
|
||||
|
||||
1. (Rolling) Repeat steps 2--5 until all nodes are using the new version.
|
||||
|
||||
1. After all nodes are using the new version, re-enable shard allocation:
|
||||
|
||||
```json
|
||||
PUT _cluster/settings
|
||||
{
|
||||
"persistent": {
|
||||
"cluster.routing.allocation.enable": "all"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
1. If you upgraded from 5.x to 6.x, [reindex]({{site.url}}{{site.baseurl}}/opensearch/reindex-data/) all indices.
|
||||
|
||||
1. Repeat all steps as necessary until you arrive at your desired Elasticsearch OSS version.
|
||||
|
||||
|
||||
## Upgrade to OpenSearch
|
||||
|
||||
1. Disable shard allocation to prevent Elasticsearch OSS from replicating shards as you shut down nodes:
|
||||
|
||||
```json
|
||||
PUT _cluster/settings
|
||||
{
|
||||
"persistent": {
|
||||
"cluster.routing.allocation.enable": "primaries"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
1. Stop Elasticsearch OSS on one node (rolling upgrade) or all nodes (cluster restart upgrade).
|
||||
|
||||
On Linux distributions that use systemd, use this command:
|
||||
|
||||
```bash
|
||||
sudo systemctl stop elasticsearch.service
|
||||
```
|
||||
|
||||
For tarball installations, find the process ID (`ps aux`) and kill it (`kill <pid>`).
|
||||
|
||||
1. Upgrade the node (rolling) or all nodes (cluster restart).
|
||||
|
||||
1. Extract the OpenSearch tarball to a new directory to ensure you **do not overwrite** your Elasticsearch OSS `config`, `data`, and `logs` directories.
|
||||
|
||||
1. (Optional) Copy or move your Elasticsearch OSS `data` and `logs` directories to new paths. For example, you might move `/var/lib/elasticsearch` to `/var/lib/opensearch`.
|
||||
|
||||
1. Set the `OPENSEARCH_PATH_CONF` environment variable to the directory that contains `opensearch.yml` (e.g. `/etc/opensearch`).
|
||||
|
||||
1. In `opensearch.yml`, set `path.data` and `path.logs`. You might also want to disable the security plugin for now. `opensearch.yml` might look something like this:
|
||||
|
||||
```yml
|
||||
path.data: /var/lib/opensearch
|
||||
path.logs: /var/log/opensearch
|
||||
plugins.security.disabled: true
|
||||
```
|
||||
|
||||
1. Port your settings from `elasticsearch.yml` to `opensearch.yml`. Most settings use the same names. At a minimum, specify `cluster.name`, `node.name`, `discovery.seed_hosts`, and `cluster.initial_master_nodes`.
|
||||
|
||||
1. (Optional) Add your certificates to your `config` directory, add them to `opensearch.yml`, and initialize the security plugin.
|
||||
|
||||
1. Start OpenSearch on the node (rolling) or all nodes (cluster restart).
|
||||
|
||||
For the tarball, run `./bin/opensearch -d`.
|
||||
|
||||
1. Wait for the OpenSearch node to rejoin the cluster (rolling) or for the cluster to start (cluster restart). Check the `_nodes` summary to verify that all nodes are available and running the expected version:
|
||||
|
||||
```bash
|
||||
# Security plugin disabled
|
||||
curl -XGET 'localhost:9200/_nodes/_all?pretty=true'
|
||||
# Security plugin enabled
|
||||
curl -XGET -k -u 'admin:admin' 'https://localhost:9200/_nodes/_all?pretty=true'
|
||||
```
|
||||
|
||||
Specifically, check the `nodes.<node-id>.version` portion of the response. Also check `_cat/indices?v` for a green status on all indices.
|
||||
|
||||
1. (Rolling) Repeat steps 2--5 until all nodes are using OpenSearch.
|
||||
|
||||
1. After all nodes are using the new version, re-enable shard allocation:
|
||||
|
||||
```json
|
||||
PUT _cluster/settings
|
||||
{
|
||||
"persistent": {
|
||||
"cluster.routing.allocation.enable": "all"
|
||||
}
|
||||
}
|
||||
```
|
||||
+1
-1
@@ -2,4 +2,4 @@
|
||||
# Run `bundle exec jekyll serve` first.
|
||||
# Uses https://github.com/stevenvachon/broken-link-checker
|
||||
# I have no idea why we have to exclude the ISM section, but that's the only way I can get this to run. - ae
|
||||
blc http://localhost:4000 -ro --exclude "*opensearch.org/*" --exclude "*github.com/opensearch-project/documentation-website/*" --exclude "*apache.org*" --exclude "https://localhost:5601/"
|
||||
blc http://127.0.0.1:4000/docs/ -ro --filter-level 0 --exclude http://localhost:5601/
|
||||
|
||||
@@ -28,7 +28,7 @@ This command creates a detector named `http_requests` that finds anomalies based
|
||||
#### Request
|
||||
|
||||
```json
|
||||
POST _plugins/_anomaly_detection/detectors
|
||||
POST _opensearch/_anomaly_detection/detectors
|
||||
{
|
||||
"name": "test-detector",
|
||||
"description": "Test detector",
|
||||
@@ -143,7 +143,7 @@ To set a category field for high cardinality:
|
||||
#### Request
|
||||
|
||||
```json
|
||||
POST _plugins/_anomaly_detection/detectors
|
||||
POST _opensearch/_anomaly_detection/detectors
|
||||
{
|
||||
"name": "Host OK Rate Detector",
|
||||
"description": "ok rate",
|
||||
@@ -243,7 +243,7 @@ To create a historical detector:
|
||||
#### Request
|
||||
|
||||
```json
|
||||
POST _plugins/_anomaly_detection/detectors
|
||||
POST _opensearch/_anomaly_detection/detectors
|
||||
{
|
||||
"name": "test1",
|
||||
"description": "test historical detector",
|
||||
@@ -312,7 +312,7 @@ Passes a date range to the anomaly detector to return any anomalies within that
|
||||
#### Request
|
||||
|
||||
```json
|
||||
POST _plugins/_anomaly_detection/detectors/<detectorId>/_preview
|
||||
POST _opensearch/_anomaly_detection/detectors/<detectorId>/_preview
|
||||
{
|
||||
"period_start": 1588838250000,
|
||||
"period_end": 1589443050000
|
||||
@@ -452,7 +452,7 @@ Starts a real-time or historical anomaly detector job.
|
||||
#### Request
|
||||
|
||||
```json
|
||||
POST _plugins/_anomaly_detection/detectors/<detectorId>/_start
|
||||
POST _opensearch/_anomaly_detection/detectors/<detectorId>/_start
|
||||
```
|
||||
|
||||
#### Sample response
|
||||
@@ -476,7 +476,7 @@ Stops a real-time or historical anomaly detector job.
|
||||
#### Request
|
||||
|
||||
```json
|
||||
POST _plugins/_anomaly_detection/detectors/<detectorId>/_stop
|
||||
POST _opensearch/_anomaly_detection/detectors/<detectorId>/_stop
|
||||
```
|
||||
|
||||
#### Sample response
|
||||
@@ -494,8 +494,8 @@ Returns all results for a search query.
|
||||
#### Request
|
||||
|
||||
```json
|
||||
GET _plugins/_anomaly_detection/detectors/results/_search
|
||||
POST _plugins/_anomaly_detection/detectors/results/_search
|
||||
GET _opensearch/_anomaly_detection/detectors/results/_search
|
||||
POST _opensearch/_anomaly_detection/detectors/results/_search
|
||||
|
||||
{
|
||||
"query": {
|
||||
@@ -596,7 +596,7 @@ To see an ordered set of anomaly records for an entity with an anomaly within a
|
||||
#### Request
|
||||
|
||||
```json
|
||||
POST _plugins/_anomaly_detection/detectors/results/_search
|
||||
POST _opensearch/_anomaly_detection/detectors/results/_search
|
||||
{
|
||||
"query": {
|
||||
"bool": {
|
||||
@@ -782,7 +782,7 @@ To get the latest task:
|
||||
#### Request
|
||||
|
||||
```json
|
||||
GET _plugins/_anomaly_detection/detectors/<detector_id>?task=true
|
||||
GET _opensearch/_anomaly_detection/detectors/<detector_id>?task=true
|
||||
```
|
||||
|
||||
To query the anomaly results with `task_id`:
|
||||
@@ -790,7 +790,7 @@ To query the anomaly results with `task_id`:
|
||||
#### Request
|
||||
|
||||
```json
|
||||
GET _plugins/_anomaly_detection/detectors/results/_search
|
||||
GET _opensearch/_anomaly_detection/detectors/results/_search
|
||||
{
|
||||
"query": {
|
||||
"term": {
|
||||
@@ -940,7 +940,7 @@ To delete a detector, you need to first stop the detector.
|
||||
#### Request
|
||||
|
||||
```json
|
||||
DELETE _plugins/_anomaly_detection/detectors/<detectorId>
|
||||
DELETE _opensearch/_anomaly_detection/detectors/<detectorId>
|
||||
```
|
||||
|
||||
|
||||
@@ -975,7 +975,7 @@ To update a detector, you need to first stop the detector.
|
||||
#### Request
|
||||
|
||||
```json
|
||||
PUT _plugins/_anomaly_detection/detectors/<detectorId>
|
||||
PUT _opensearch/_anomaly_detection/detectors/<detectorId>
|
||||
{
|
||||
"name": "test-detector",
|
||||
"description": "Test detector",
|
||||
@@ -1091,7 +1091,7 @@ To update a historical detector:
|
||||
#### Request
|
||||
|
||||
```json
|
||||
PUT _plugins/_anomaly_detection/detectors/<detectorId>
|
||||
PUT _opensearch/_anomaly_detection/detectors/<detectorId>
|
||||
{
|
||||
"name": "test1",
|
||||
"description": "test historical detector",
|
||||
@@ -1145,7 +1145,7 @@ Returns all information about a detector based on the `detector_id`.
|
||||
#### Request
|
||||
|
||||
```json
|
||||
GET _plugins/_anomaly_detection/detectors/<detectorId>
|
||||
GET _opensearch/_anomaly_detection/detectors/<detectorId>
|
||||
```
|
||||
|
||||
#### Sample response
|
||||
@@ -1215,7 +1215,7 @@ Use `job=true` to get anomaly detection job information.
|
||||
#### Request
|
||||
|
||||
```json
|
||||
GET _plugins/_anomaly_detection/detectors/<detectorId>?job=true
|
||||
GET _opensearch/_anomaly_detection/detectors/<detectorId>?job=true
|
||||
```
|
||||
|
||||
#### Sample response
|
||||
@@ -1304,7 +1304,7 @@ Use `task=true` to get historical detector task information.
|
||||
#### Request
|
||||
|
||||
```json
|
||||
GET _plugins/_anomaly_detection/detectors/<detectorId>?task=true
|
||||
GET _opensearch/_anomaly_detection/detectors/<detectorId>?task=true
|
||||
```
|
||||
|
||||
#### Sample response
|
||||
@@ -1491,8 +1491,8 @@ Returns all anomaly detectors for a search query.
|
||||
#### Request
|
||||
|
||||
```json
|
||||
GET _plugins/_anomaly_detection/detectors/_search
|
||||
POST _plugins/_anomaly_detection/detectors/_search
|
||||
GET _opensearch/_anomaly_detection/detectors/_search
|
||||
POST _opensearch/_anomaly_detection/detectors/_search
|
||||
|
||||
Sample Input:
|
||||
{
|
||||
@@ -1597,10 +1597,10 @@ Provides information about how the plugin is performing.
|
||||
#### Request
|
||||
|
||||
```json
|
||||
GET _plugins/_anomaly_detection/stats
|
||||
GET _plugins/_anomaly_detection/<nodeId>/stats
|
||||
GET _plugins/_anomaly_detection/<nodeId>/stats/<stat>
|
||||
GET _plugins/_anomaly_detection/stats/<stat>
|
||||
GET _opensearch/_anomaly_detection/stats
|
||||
GET _opensearch/_anomaly_detection/<nodeId>/stats
|
||||
GET _opensearch/_anomaly_detection/<nodeId>/stats/<stat>
|
||||
GET _opensearch/_anomaly_detection/stats/<stat>
|
||||
```
|
||||
|
||||
#### Sample response
|
||||
@@ -1697,7 +1697,7 @@ Create a monitor to set up alerts for the detector.
|
||||
#### Request
|
||||
|
||||
```json
|
||||
POST _plugins/_alerting/monitors
|
||||
POST _opensearch/_alerting/monitors
|
||||
{
|
||||
"type": "monitor",
|
||||
"name": "test-monitor",
|
||||
@@ -1919,23 +1919,23 @@ It also helps track the initialization percentage, the required shingles, and th
|
||||
#### Request
|
||||
|
||||
```json
|
||||
GET _plugins/_anomaly_detection/detectors/<detectorId>/_profile/
|
||||
GET _plugins/_anomaly_detection/detectors/<detectorId>/_profile?_all=true
|
||||
GET _plugins/_anomaly_detection/detectors/<detectorId>/_profile/<type>
|
||||
GET /_plugins/_anomaly_detection/detectors/<detectorId>/_profile/<type1>,<type2>
|
||||
GET _opensearch/_anomaly_detection/detectors/<detectorId>/_profile/
|
||||
GET _opensearch/_anomaly_detection/detectors/<detectorId>/_profile?_all=true
|
||||
GET _opensearch/_anomaly_detection/detectors/<detectorId>/_profile/<type>
|
||||
GET /_opensearch/_anomaly_detection/detectors/<detectorId>/_profile/<type1>,<type2>
|
||||
```
|
||||
|
||||
#### Sample Responses
|
||||
|
||||
```json
|
||||
GET _plugins/_anomaly_detection/detectors/<detectorId>/_profile
|
||||
GET _opensearch/_anomaly_detection/detectors/<detectorId>/_profile
|
||||
|
||||
{
|
||||
"state":"DISABLED",
|
||||
"error":"Stopped detector: AD models memory usage exceeds our limit."
|
||||
}
|
||||
|
||||
GET _plugins/_anomaly_detection/detectors/<detectorId>/_profile?_all=true&pretty
|
||||
GET _opensearch/_anomaly_detection/detectors/<detectorId>/_profile?_all=true&pretty
|
||||
|
||||
{
|
||||
"state": "RUNNING",
|
||||
@@ -1970,7 +1970,7 @@ GET _plugins/_anomaly_detection/detectors/<detectorId>/_profile?_all=true&pretty
|
||||
}
|
||||
}
|
||||
|
||||
GET _plugins/_anomaly_detection/detectors/<detectorId>/_profile/total_size_in_bytes
|
||||
GET _opensearch/_anomaly_detection/detectors/<detectorId>/_profile/total_size_in_bytes
|
||||
|
||||
{
|
||||
"total_size_in_bytes" : 13369344
|
||||
@@ -1984,7 +1984,7 @@ You can use this data to estimate how much memory is required for anomaly detect
|
||||
#### Request
|
||||
|
||||
```json
|
||||
GET /_plugins/_anomaly_detection/detectors/<detectorId>/_profile?_all=true&pretty
|
||||
GET /_opensearch/_anomaly_detection/detectors/<detectorId>/_profile?_all=true&pretty
|
||||
|
||||
{
|
||||
"state": "RUNNING",
|
||||
@@ -2043,7 +2043,7 @@ If there are no anomaly results for an entity, either the entity doesn't have an
|
||||
#### Request
|
||||
|
||||
```json
|
||||
GET /_plugins/_anomaly_detection/detectors/<detectorId>/_profile?_all=true&entity=i-00f28ec1eb8997686
|
||||
GET /_opensearch/_anomaly_detection/detectors/<detectorId>/_profile?_all=true&entity=i-00f28ec1eb8997686
|
||||
{
|
||||
"category_field": "host",
|
||||
"value": "i-00f28ec1eb8997686",
|
||||
@@ -2067,8 +2067,8 @@ For a historical detector, specify `_all` or `ad_task` to see information about
|
||||
#### Request
|
||||
|
||||
```json
|
||||
GET _plugins/_anomaly_detection/detectors/<detectorId>/_profile?_all
|
||||
GET _plugins/_anomaly_detection/detectors/<detectorId>/_profile/ad_task
|
||||
GET _opensearch/_anomaly_detection/detectors/<detectorId>/_profile?_all
|
||||
GET _opensearch/_anomaly_detection/detectors/<detectorId>/_profile/ad_task
|
||||
```
|
||||
|
||||
#### Sample Responses
|
||||
@@ -3,8 +3,6 @@ layout: default
|
||||
title: Anomaly detection
|
||||
nav_order: 46
|
||||
has_children: true
|
||||
redirect_from:
|
||||
- /monitoring-plugins/ad/
|
||||
---
|
||||
|
||||
# Anomaly detection
|
||||
@@ -15,7 +13,7 @@ It can be challenging to discover anomalies using conventional methods such as c
|
||||
|
||||
Anomaly detection automatically detects anomalies in your OpenSearch data in near real-time using the Random Cut Forest (RCF) algorithm. RCF is an unsupervised machine learning algorithm that models a sketch of your incoming data stream to compute an `anomaly grade` and `confidence score` value for each incoming data point. These values are used to differentiate an anomaly from normal variations. For more information about how RCF works, see [Random Cut Forests](https://pdfs.semanticscholar.org/8bba/52e9797f2e2cc9a823dbd12514d02f29c8b9.pdf?_ga=2.56302955.1913766445.1574109076-1059151610.1574109076).
|
||||
|
||||
You can pair the anomaly detection plugin with the [alerting plugin]({{site.url}}{{site.baseurl}}/monitoring-plugins/alerting/) to notify you as soon as an anomaly is detected.
|
||||
You can pair the anomaly detection plugin with the [alerting plugin](../alerting/) to notify you as soon as an anomaly is detected.
|
||||
|
||||
To use the anomaly detection plugin, your computer needs to have more than one CPU core.
|
||||
{: .note }
|
||||
@@ -54,7 +52,7 @@ A feature is the field in your index that you want to check for anomalies. A det
|
||||
|
||||
For example, if you choose `min()`, the detector focuses on finding anomalies based on the minimum values of your feature. If you choose `average()`, the detector finds anomalies based on the average values of your feature.
|
||||
|
||||
A multi-feature model correlates anomalies across all its features. The [curse of dimensionality](https://en.wikipedia.org/wiki/Curse_of_dimensionality) makes it less likely for multi-feature models to identify smaller anomalies as compared to a single-feature model. Adding more features might negatively impact the [precision and recall](https://en.wikipedia.org/wiki/Precision_and_recall) of a model. A higher proportion of noise in your data might further amplify this negative impact. Selecting the optimal feature set is usually an iterative process. We recommend experimenting with a historical detector with different feature sets and checking the precision before moving on to real-time detectors. By default, the maximum number of features for a detector is 5. You can adjust this limit with the `plugins.anomaly_detection.max_anomaly_features` setting.
|
||||
A multi-feature model correlates anomalies across all its features. The [curse of dimensionality](https://en.wikipedia.org/wiki/Curse_of_dimensionality) makes it less likely for multi-feature models to identify smaller anomalies as compared to a single-feature model. Adding more features might negatively impact the [precision and recall](https://en.wikipedia.org/wiki/Precision_and_recall) of a model. A higher proportion of noise in your data might further amplify this negative impact. Selecting the optimal feature set is usually an iterative process. We recommend experimenting with a historical detector with different feature sets and checking the precision before moving on to real-time detectors. By default, the maximum number of features for a detector is 5. You can adjust this limit with the `opendistro.anomaly_detection.max_anomaly_features` setting.
|
||||
{: .note }
|
||||
|
||||
1. On the **Model configuration** page, enter the **Feature name**.
|
||||
@@ -102,11 +100,11 @@ Examine the sample preview and use it to fine-tune your feature configurations (
|
||||
Choose the **Anomaly results** tab. You need to wait for some time to see the anomaly results. If the detector interval is 10 minutes, the detector might take more than an hour to start, as it's waiting for sufficient data to generate anomalies.
|
||||
|
||||
A shorter interval means the model passes the shingle process more quickly and starts to generate the anomaly results sooner.
|
||||
Use the [profile detector]({{site.url}}{{site.baseurl}}/monitoring-plugins/ad/api#profile-detector) operation to make sure you have sufficient data points.
|
||||
Use the [profile detector](./api#profile-detector) operation to make sure you have sufficient data points.
|
||||
|
||||
If you see the detector pending in "initialization" for longer than a day, aggregate your existing data using the detector interval to check for any missing data points. If you find a lot of missing data points from the aggregated data, consider increasing the detector interval.
|
||||
|
||||
|
||||
|
||||
|
||||
Analize anomalies with the following visualizations:
|
||||
|
||||
@@ -115,7 +113,7 @@ Analize anomalies with the following visualizations:
|
||||
- **Feature breakdown** - plots the features based on the aggregation method. You can vary the date-time range of the detector.
|
||||
- **Anomaly occurrence** - shows the `Start time`, `End time`, `Data confidence`, and `Anomaly grade` for each detected anomaly.
|
||||
|
||||
`Anomaly grade` is a number between 0 and 1 that indicates how anomalous a data point is. An anomaly grade of 0 represents “not an anomaly,” and a non-zero value represents the relative severity of the anomaly.
|
||||
`Anomaly grade` is a number between 0 and 1 that indicates how anomalous a data point is. An anomaly grade of 0 represents “not an anomaly,” and a non-zero value represents the relative severity of the anomaly.
|
||||
|
||||
`Data confidence` is an estimate of the probability that the reported anomaly grade matches the expected anomaly grade. Confidence increases as the model observes more data and learns the data behavior and trends. Note that confidence is distinct from model accuracy.
|
||||
|
||||
@@ -126,7 +124,7 @@ Choose a filled rectangle to see a more detailed view of the anomaly.
|
||||
|
||||
### Step 4: Set up alerts
|
||||
|
||||
Choose **Set up alerts** and configure a monitor to notify you when anomalies are detected. For steps to create a monitor and set up notifications based on your anomaly detector, see [Monitors]({{site.url}}{{site.baseurl}}/monitoring-plugins/alerting/monitors/).
|
||||
Choose **Set up alerts** and configure a monitor to notify you when anomalies are detected. For steps to create a monitor and set up notifications based on your anomaly detector, see [Monitors](../alerting/monitors/).
|
||||
|
||||
If you stop or delete a detector, make sure to delete any monitors associated with it.
|
||||
|
||||
@@ -10,24 +10,24 @@ has_children: false
|
||||
|
||||
You can use the security plugin with anomaly detection in OpenSearch to limit non-admin users to specific actions. For example, you might want some users to only be able to create, update, or delete detectors, while others to only view detectors.
|
||||
|
||||
All anomaly detection indices are protected as system indices. Only a super admin user or an admin user with a TLS certificate can access system indices. For more information, see [System indices]({{site.url}}{{site.baseurl}}/security-plugin/configuration/system-indices/).
|
||||
All anomaly detection indices are protected as system indices. Only a super admin user or an admin user with a TLS certificate can access system indices. For more information, see [System indices](../../security/configuration/system-indices/).
|
||||
|
||||
|
||||
Security for anomaly detection works the same as [security for alerting]({{site.url}}{{site.baseurl}}/monitoring-plugins/alerting/security/).
|
||||
Security for anomaly detection works the same as [security for alerting](../../alerting/security/).
|
||||
|
||||
## Basic permissions
|
||||
|
||||
As an admin user, you can use the security plugin to assign specific permissions to users based on which APIs they need access to. For a list of supported APIs, see [Anomaly detection API]({{site.url}}{{site.baseurl}}/monitoring-plugins/ad/api/).
|
||||
As an admin user, you can use the security plugin to assign specific permissions to users based on which APIs they need access to. For a list of supported APIs, see [Anomaly detection API](../api/).
|
||||
|
||||
The security plugin has two built-in roles that cover most anomaly detection use cases: `anomaly_full_access` and `anomaly_read_access`. For descriptions of each, see [Predefined roles]({{site.url}}{{site.baseurl}}/security-plugin/access-control/users-roles#predefined-roles).
|
||||
The security plugin has two built-in roles that cover most anomaly detection use cases: `anomaly_full_access` and `anomaly_read_access`. For descriptions of each, see [Predefined roles](../../security/access-control/users-roles/#predefined-roles).
|
||||
|
||||
If these roles don't meet your needs, mix and match individual anomaly detection [permissions]({{site.url}}{{site.baseurl}}/security-plugin/access-control/permissions/) to suit your use case. Each action corresponds to an operation in the REST API. For example, the `cluster:admin/opensearch/ad/detector/delete` permission lets you delete detectors.
|
||||
If these roles don't meet your needs, mix and match individual anomaly detection [permissions](../../security/access-control/permissions/) to suit your use case. Each action corresponds to an operation in the REST API. For example, the `cluster:admin/opensearch/ad/detector/delete` permission lets you delete detectors.
|
||||
|
||||
## (Advanced) Limit access by backend role
|
||||
|
||||
Use backend roles to configure fine-grained access to individual detectors based on roles. For example, users of different departments in an organization can view detectors owned by their own department.
|
||||
|
||||
First, make sure your users have the appropriate [backend roles]({{site.url}}{{site.baseurl}}/security-plugin/access-control/index/). Backend roles usually come from an [LDAP server]({{site.url}}{{site.baseurl}}/security-plugin/configuration/ldap/) or [SAML provider]({{site.url}}{{site.baseurl}}/security-plugin/configuration/saml/), but if you use the internal user database, you can use the REST API to [add them manually]({{site.url}}{{site.baseurl}}/security-plugin/access-control/api#create-user).
|
||||
First, make sure your users have the appropriate [backend roles](../../security/access-control/). Backend roles usually come from an [LDAP server](../../security/configuration/ldap/) or [SAML provider](../../security/configuration/saml/), but if you use the internal user database, you can use the REST API to [add them manually](../../security/access-control/api/#create-user).
|
||||
|
||||
Next, enable the following setting:
|
||||
|
||||
@@ -35,7 +35,7 @@ Next, enable the following setting:
|
||||
PUT _cluster/settings
|
||||
{
|
||||
"transient": {
|
||||
"plugins.anomaly_detection.filter_by_backend_roles": "true"
|
||||
"opendistro.anomaly_detection.filter_by_backend_roles": "true"
|
||||
}
|
||||
}
|
||||
```
|
||||
@@ -46,7 +46,7 @@ For example, consider two users: `alice` and `bob`.
|
||||
`alice` has an analyst backend role:
|
||||
|
||||
```json
|
||||
PUT _plugins/_security/api/internalusers/alice
|
||||
PUT _opensearch/_security/api/internalusers/alice
|
||||
{
|
||||
"password": "alice",
|
||||
"backend_roles": [
|
||||
@@ -59,7 +59,7 @@ PUT _plugins/_security/api/internalusers/alice
|
||||
`bob` has a human-resources backend role:
|
||||
|
||||
```json
|
||||
PUT _plugins/_security/api/internalusers/bob
|
||||
PUT _opensearch/_security/api/internalusers/bob
|
||||
{
|
||||
"password": "bob",
|
||||
"backend_roles": [
|
||||
@@ -72,7 +72,7 @@ PUT _plugins/_security/api/internalusers/bob
|
||||
Both `alice` and `bob` have full access to anomaly detection:
|
||||
|
||||
```json
|
||||
PUT _plugins/_security/api/rolesmapping/anomaly_full_access
|
||||
PUT _opensearch/_security/api/rolesmapping/anomaly_full_access
|
||||
{
|
||||
"backend_roles": [],
|
||||
"hosts": [],
|
||||
@@ -0,0 +1,42 @@
|
||||
---
|
||||
layout: default
|
||||
title: Settings
|
||||
parent: Anomaly detection
|
||||
nav_order: 4
|
||||
---
|
||||
|
||||
# Settings
|
||||
|
||||
The anomaly detection plugin adds several settings to the standard OpenSearch cluster settings.
|
||||
The settings are dynamic, so you can change the default behavior of the plugin without restarting your cluster.
|
||||
You can mark settings as `persistent` or `transient`.
|
||||
|
||||
For example, to update the retention period of the result index:
|
||||
|
||||
```json
|
||||
PUT _cluster/settings
|
||||
{
|
||||
"transient": {
|
||||
"opendistro.anomaly_detection.ad_result_history_retention_period": "5m"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Setting | Default | Description
|
||||
:--- | :--- | :---
|
||||
`opendistro.anomaly_detection.enabled` | True | Whether the anomaly detection plugin is enabled or not. If disabled, all detectors immediately stop running.
|
||||
`opendistro.anomaly_detection.max_anomaly_detectors` | 1,000 | The maximum number of non-high cardinality detectors (no category field) users can create.
|
||||
`opendistro.anomaly_detection.max_multi_entity_anomaly_detectors` | 10 | The maximum number of high cardinality detectors (with category field) in a cluster.
|
||||
`opendistro.anomaly_detection.max_anomaly_features` | 5 | The maximum number of features for a detector.
|
||||
`opendistro.anomaly_detection.ad_result_history_rollover_period` | 12h | How often the rollover condition is checked. If `true`, the plugin rolls over the result index to a new index.
|
||||
`opendistro.anomaly_detection.ad_result_history_max_docs` | 250000000 | The maximum number of documents in one result index. The plugin only counts refreshed documents in the primary shards.
|
||||
`opendistro.anomaly_detection.ad_result_history_retention_period` | 30d | The maximum age of the result index. If its age exceeds the threshold, the plugin deletes the rolled over result index. If the cluster has only one result index, the plugin keeps the index even if it's older than its configured retention period.
|
||||
`opendistro.anomaly_detection.max_entities_per_query` | 1,000 | The maximum unique values per detection interval for high cardinality detectors. By default, if the category field has more than 1,000 unique values in a detector interval, the plugin selects the top 1,000 values and orders them by `doc_count`.
|
||||
`opendistro.anomaly_detection.max_entities_for_preview` | 30 | The maximum unique category field values displayed with the preview operation for high cardinality detectors. If the category field has more than 30 unique values, the plugin selects the top 30 values and orders them by `doc_count`.
|
||||
`opendistro.anomaly_detection.max_primary_shards` | 10 | The maximum number of primary shards an anomaly detection index can have.
|
||||
`opendistro.anomaly_detection.filter_by_backend_roles` | False | When you enable the security plugin and set this to `true`, the plugin filters results based on the user's backend role(s).
|
||||
`opendistro.anomaly_detection.max_cache_miss_handling_per_second` | 100 | High cardinality detectors use a cache to store active models. In the event of a cache miss, the cache gets the models from the model checkpoint index. Use this setting to limit the rate of fetching models. Because the thread pool for a GET operation has a queue of 1,000, we recommend setting this value below 1,000.
|
||||
`opendistro.anomaly_detection.max_batch_task_per_node` | 2 | Starting a historical detector triggers a batch task. This setting is the number of batch tasks that you can run per data node. You can tune this setting from 1 to 1000. If the data nodes can't support all batch tasks and you're not sure if the data nodes are capable of running more historical detectors, add more data nodes instead of changing this setting to a higher value.
|
||||
`opendistro.anomaly_detection.max_old_ad_task_docs_per_detector` | 10 | You can run the same historical detector many times. For each run, the anomaly detection plugin creates a new task. This setting is the number of previous tasks the plugin keeps. Set this value to at least 1 to track its last run. You can keep a maximum of 1,000 old tasks to avoid overwhelming the cluster.
|
||||
`opendistro.anomaly_detection.batch_task_piece_size` | 1000 | The date range for a historical task is split into smaller pieces and the anomaly detection plugin runs the task piece by piece. Each piece contains 1,000 detection intervals by default. For example, if detector interval is 1 minute and one piece is 1000 minutes, the feature data is queried every 1,000 minutes. You can change this setting from 1 to 10,000.
|
||||
`opendistro.anomaly_detection.batch_task_piece_interval_seconds` | 5 | Add a time interval between historical detector tasks. This interval prevents the task from consuming too much of the available resources and starving other operations like search and bulk index. You can change this setting from 1 to 600 seconds.
|
||||
@@ -24,7 +24,7 @@ Use the alerting API to programmatically manage monitors and alerts.
|
||||
#### Request
|
||||
|
||||
```json
|
||||
POST _plugins/_alerting/monitors
|
||||
POST _opensearch/_alerting/monitors
|
||||
{
|
||||
"type": "monitor",
|
||||
"name": "test-monitor",
|
||||
@@ -174,7 +174,7 @@ If you use a custom webhook for your destination and need to embed JSON in the m
|
||||
}
|
||||
```
|
||||
|
||||
If you want to specify a timezone, you can do so by including a [cron expression]({{site.url}}{{site.baseurl}}/monitoring-plugins/alerting/cron/) with a timezone name in the `schedule` section of your request.
|
||||
If you want to specify a timezone, you can do so by including a [cron expression](../cron/) with a timezone name in the `schedule` section of your request.
|
||||
|
||||
The following example creates a monitor that runs at 12:10 PM Pacific Time on the 1st day of every month.
|
||||
|
||||
@@ -252,7 +252,7 @@ When you update a monitor, include the current version number as a parameter. Op
|
||||
#### Request
|
||||
|
||||
```json
|
||||
PUT _plugins/_alerting/monitors/<monitor_id>
|
||||
PUT _opensearch/_alerting/monitors/<monitor_id>
|
||||
{
|
||||
"type": "monitor",
|
||||
"name": "test-monitor",
|
||||
@@ -372,7 +372,7 @@ PUT _plugins/_alerting/monitors/<monitor_id>
|
||||
#### Request
|
||||
|
||||
```
|
||||
GET _plugins/_alerting/monitors/<monitor_id>
|
||||
GET _opensearch/_alerting/monitors/<monitor_id>
|
||||
```
|
||||
|
||||
#### Sample response
|
||||
@@ -439,15 +439,15 @@ GET _plugins/_alerting/monitors/<monitor_id>
|
||||
|
||||
## Monitor stats
|
||||
|
||||
Returns statistics about the alerting feature. Use `_plugins/_alerting/stats` to find node IDs and metrics. Then you can drill down using those values.
|
||||
Returns statistics about the alerting feature. Use `_opensearch/_alerting/stats` to find node IDs and metrics. Then you can drill down using those values.
|
||||
|
||||
#### Request
|
||||
|
||||
```json
|
||||
GET _plugins/_alerting/stats
|
||||
GET _plugins/_alerting/stats/<metric>
|
||||
GET _plugins/_alerting/<node-id>/stats
|
||||
GET _plugins/_alerting/<node-id>/stats/<metric>
|
||||
GET _opensearch/_alerting/stats
|
||||
GET _opensearch/_alerting/stats/<metric>
|
||||
GET _opensearch/_alerting/<node-id>/stats
|
||||
GET _opensearch/_alerting/<node-id>/stats/<metric>
|
||||
```
|
||||
|
||||
#### Sample response
|
||||
@@ -460,7 +460,7 @@ GET _plugins/_alerting/<node-id>/stats/<metric>
|
||||
"failed": 0
|
||||
},
|
||||
"cluster_name": "475300751431:alerting65-dont-delete",
|
||||
"plugins.scheduled_jobs.enabled": true,
|
||||
"opensearch.scheduled_jobs.enabled": true,
|
||||
"scheduled_job_index_exists": true,
|
||||
"scheduled_job_index_status": "green",
|
||||
"nodes_on_schedule": 9,
|
||||
@@ -631,7 +631,7 @@ GET _plugins/_alerting/<node-id>/stats/<metric>
|
||||
#### Request
|
||||
|
||||
```
|
||||
DELETE _plugins/_alerting/monitors/<monitor_id>
|
||||
DELETE _opensearch/_alerting/monitors/<monitor_id>
|
||||
```
|
||||
|
||||
#### Sample response
|
||||
@@ -662,7 +662,7 @@ DELETE _plugins/_alerting/monitors/<monitor_id>
|
||||
#### Request
|
||||
|
||||
```json
|
||||
GET _plugins/_alerting/monitors/_search
|
||||
GET _opensearch/_alerting/monitors/_search
|
||||
{
|
||||
"query": {
|
||||
"match" : {
|
||||
@@ -762,7 +762,7 @@ You can add the optional `?dryrun=true` parameter to the URL to show the results
|
||||
#### Request
|
||||
|
||||
```json
|
||||
POST _plugins/_alerting/monitors/<monitor_id>/_execute
|
||||
POST _opensearch/_alerting/monitors/<monitor_id>/_execute
|
||||
```
|
||||
|
||||
#### Sample response
|
||||
@@ -793,7 +793,7 @@ Returns an array of all alerts.
|
||||
#### Request
|
||||
|
||||
```json
|
||||
GET _plugins/_alerting/monitors/alerts
|
||||
GET _opensearch/_alerting/monitors/alerts
|
||||
```
|
||||
|
||||
#### Response
|
||||
@@ -862,7 +862,7 @@ GET _plugins/_alerting/monitors/alerts
|
||||
#### Request
|
||||
|
||||
```json
|
||||
POST _plugins/_alerting/monitors/<monitor-id>/_acknowledge/alerts
|
||||
POST _opensearch/_alerting/monitors/<monitor-id>/_acknowledge/alerts
|
||||
{
|
||||
"alerts": ["eQURa3gBKo1jAh6qUo49"]
|
||||
}
|
||||
@@ -886,7 +886,7 @@ POST _plugins/_alerting/monitors/<monitor-id>/_acknowledge/alerts
|
||||
#### Requests
|
||||
|
||||
```json
|
||||
POST _plugins/_alerting/destinations
|
||||
POST _opensearch/_alerting/destinations
|
||||
{
|
||||
"name": "my-destination",
|
||||
"type": "slack",
|
||||
@@ -895,7 +895,7 @@ POST _plugins/_alerting/destinations
|
||||
}
|
||||
}
|
||||
|
||||
POST _plugins/_alerting/destinations
|
||||
POST _opensearch/_alerting/destinations
|
||||
{
|
||||
"type": "custom_webhook",
|
||||
"name": "my-custom-destination",
|
||||
@@ -912,27 +912,6 @@ POST _plugins/_alerting/destinations
|
||||
"host": "hooks.chime.aws"
|
||||
}
|
||||
}
|
||||
|
||||
POST _plugins/_alerting/destinations
|
||||
{
|
||||
"type": "email",
|
||||
"name": "my-email-destination",
|
||||
"email": {
|
||||
"email_account_id": "YjY7mXMBx015759_IcfW",
|
||||
"recipients": [
|
||||
{
|
||||
"type": "email_group",
|
||||
"email_group_id": "YzY-mXMBx015759_dscs"
|
||||
},
|
||||
{
|
||||
"type": "email",
|
||||
"email": "example@email.com"
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
|
||||
// The email_account_id and email_group_id will be the document IDs of the email_account and email_group you have created.
|
||||
```
|
||||
|
||||
#### Sample response
|
||||
@@ -960,7 +939,7 @@ POST _plugins/_alerting/destinations
|
||||
#### Request
|
||||
|
||||
```json
|
||||
PUT _plugins/_alerting/destinations/<destination-id>
|
||||
PUT _opensearch/_alerting/destinations/<destination-id>
|
||||
{
|
||||
"name": "my-updated-destination",
|
||||
"type": "slack",
|
||||
@@ -997,7 +976,7 @@ Retrieve one destination.
|
||||
#### Requests
|
||||
|
||||
```json
|
||||
GET _plugins/_alerting/destinations/<destination-id>
|
||||
GET _opensearch/_alerting/destinations/<destination-id>
|
||||
```
|
||||
|
||||
#### Sample response
|
||||
@@ -1042,7 +1021,7 @@ Retrieve all destinations.
|
||||
#### Requests
|
||||
|
||||
```json
|
||||
GET _plugins/_alerting/destinations
|
||||
GET _opensearch/_alerting/destinations
|
||||
```
|
||||
|
||||
#### Sample response
|
||||
@@ -1085,7 +1064,7 @@ GET _plugins/_alerting/destinations
|
||||
#### Request
|
||||
|
||||
```
|
||||
DELETE _plugins/_alerting/destinations/<destination-id>
|
||||
DELETE _opensearch/_alerting/destinations/<destination-id>
|
||||
```
|
||||
|
||||
#### Sample response
|
||||
@@ -1113,7 +1092,7 @@ DELETE _plugins/_alerting/destinations/<destination-id>
|
||||
|
||||
#### Request
|
||||
```json
|
||||
POST _plugins/_alerting/destinations/email_accounts
|
||||
POST _opensearch/_alerting/destinations/email_accounts
|
||||
{
|
||||
"name": "example_account",
|
||||
"email": "example@email.com",
|
||||
@@ -1145,7 +1124,7 @@ POST _plugins/_alerting/destinations/email_accounts
|
||||
|
||||
#### Request
|
||||
```json
|
||||
PUT _plugins/_alerting/destinations/email_accounts/<email_account_id>
|
||||
PUT _opensearch/_alerting/destinations/email_accounts/<email_account_id>
|
||||
{
|
||||
"name": "example_account",
|
||||
"email": "example@email.com",
|
||||
@@ -1176,7 +1155,7 @@ PUT _plugins/_alerting/destinations/email_accounts/<email_account_id>
|
||||
|
||||
#### Request
|
||||
```json
|
||||
GET _plugins/_alerting/destinations/email_accounts/<email_account_id>
|
||||
GET _opensearch/_alerting/destinations/email_accounts/<email_account_id>
|
||||
{
|
||||
"name": "example_account",
|
||||
"email": "example@email.com",
|
||||
@@ -1207,7 +1186,7 @@ GET _plugins/_alerting/destinations/email_accounts/<email_account_id>
|
||||
|
||||
#### Request
|
||||
```
|
||||
DELETE _plugins/_alerting/destinations/email_accounts/<email_account_id>
|
||||
DELETE _opensearch/_alerting/destinations/email_accounts/<email_account_id>
|
||||
```
|
||||
#### Sample response
|
||||
|
||||
@@ -1234,7 +1213,7 @@ DELETE _plugins/_alerting/destinations/email_accounts/<email_account_id>
|
||||
#### Request
|
||||
|
||||
```json
|
||||
POST _plugins/_alerting/destinations/email_accounts/_search
|
||||
POST _opensearch/_alerting/destinations/email_accounts/_search
|
||||
{
|
||||
"from": 0,
|
||||
"size": 20,
|
||||
@@ -1300,7 +1279,7 @@ POST _plugins/_alerting/destinations/email_accounts/_search
|
||||
#### Request
|
||||
|
||||
```json
|
||||
POST _plugins/_alerting/destinations/email_groups
|
||||
POST _opensearch/_alerting/destinations/email_groups
|
||||
{
|
||||
"name": "example_email_group",
|
||||
"emails": [{
|
||||
@@ -1334,7 +1313,7 @@ POST _plugins/_alerting/destinations/email_groups
|
||||
#### Request
|
||||
|
||||
```json
|
||||
PUT _plugins/_alerting/destinations/email_groups/<email_group_id>
|
||||
PUT _opensearch/_alerting/destinations/email_groups/<email_group_id>
|
||||
{
|
||||
"name": "example_email_group",
|
||||
"emails": [{
|
||||
@@ -1366,7 +1345,7 @@ PUT _plugins/_alerting/destinations/email_groups/<email_group_id>
|
||||
|
||||
#### Request
|
||||
```json
|
||||
GET _plugins/_alerting/destinations/email_groups/<email_group_id>
|
||||
GET _opensearch/_alerting/destinations/email_groups/<email_group_id>
|
||||
{
|
||||
"name": "example_email_group",
|
||||
"emails": [{
|
||||
@@ -1398,7 +1377,7 @@ GET _plugins/_alerting/destinations/email_groups/<email_group_id>
|
||||
|
||||
#### Request
|
||||
```
|
||||
DELETE _plugins/_alerting/destinations/email_groups/<email_group_id>
|
||||
DELETE _opensearch/_alerting/destinations/email_groups/<email_group_id>
|
||||
```
|
||||
#### Sample response
|
||||
|
||||
@@ -1425,7 +1404,7 @@ DELETE _plugins/_alerting/destinations/email_groups/<email_group_id>
|
||||
#### Request
|
||||
|
||||
```json
|
||||
POST _plugins/_alerting/destinations/email_groups/_search
|
||||
POST _opensearch/_alerting/destinations/email_groups/_search
|
||||
{
|
||||
"from": 0,
|
||||
"size": 20,
|
||||
@@ -4,9 +4,6 @@ title: Cron
|
||||
nav_order: 20
|
||||
parent: Alerting
|
||||
has_children: false
|
||||
redirect_from:
|
||||
- /alerting/cron/
|
||||
- /docs/alerting/cron/
|
||||
---
|
||||
|
||||
# Cron expression reference
|
||||
@@ -64,4 +61,4 @@ Every three hours on the first day of every other month:
|
||||
|
||||
## API
|
||||
|
||||
For an example of how to use a custom cron expression in an API call, see the [create monitor API operation]({{site.url}}{{site.baseurl}}/monitoring-plugins/alerting/api#request-1).
|
||||
For an example of how to use a custom cron expression in an API call, see the [create monitor API operation](../api/#request-1).
|
||||
@@ -3,8 +3,6 @@ layout: default
|
||||
title: Alerting
|
||||
nav_order: 34
|
||||
has_children: true
|
||||
redirect_from:
|
||||
- /monitoring-plugins/alerting/
|
||||
---
|
||||
|
||||
# Alerting
|
||||
@@ -15,4 +13,4 @@ The alerting feature notifies you when data from one or more OpenSearch indices
|
||||
|
||||
To get started, choose **Alerting** in OpenSearch Dashboards.
|
||||
|
||||
|
||||
|
||||
@@ -32,14 +32,68 @@ Destination | A reusable location for an action, such as Amazon Chime, Slack, or
|
||||
|
||||
1. Choose **Alerting**, **Destinations**, **Add destination**.
|
||||
1. Specify a name for the destination so that you can identify it later.
|
||||
1. For **Type**, choose Slack, Amazon Chime, custom webhook, or [email](#email-as-a-destination).
|
||||
1. For **Type**, choose Slack, Amazon Chime, Amazon Simple Notification Service (SNS), custom webhook, or [email](#email-as-a-destination).
|
||||
|
||||
For Email type, refer to [Email as a destination](#email-as-a-destination) section below. For all other types, specify the webhook URL. For more information about webhooks, see the documentation for [Slack](https://api.slack.com/incoming-webhooks) and [Chime](https://docs.aws.amazon.com/chime/latest/ug/webhooks.html).
|
||||
For more information about Amazon SNS or email type, refer to their respective sections below. For Amazon Chime, Slack, or custom webhook, specify the webhook URL. For more information about webhooks, see the documentation for [Slack](https://api.slack.com/incoming-webhooks) and [Chime](https://docs.aws.amazon.com/chime/latest/ug/webhooks.html).
|
||||
|
||||
For custom webhooks, you must specify more information: parameters and headers. For example, if your endpoint requires basic authentication, you might need to add a header with a key of `Authorization` and a value of `Basic <Base64-encoded-credential-string>`. You might also need to change `Content-Type` to whatever your webhook requires. Popular values are `application/json`, `application/xml`, and `text/plain`.
|
||||
|
||||
This information is stored in plain text in the OpenSearch cluster. We will improve this design in the future, but for now, the encoded credentials (which are neither encrypted nor hashed) might be visible to other OpenSearch users.
|
||||
|
||||
### Amazon SNS as a destination
|
||||
|
||||
OpenSearch supports Amazon SNS for notifications. This integration with Amazon SNS means that, in addition to the other destinations, the alerting plugin can send emails, text messages, and even run AWS Lambda functions using SNS topics. For more information about Amazon SNS, see the [Amazon Simple Notification Service Developer Guide](https://docs.aws.amazon.com/sns/latest/dg/welcome.html).
|
||||
|
||||
To use Amazon SNS as a destination:
|
||||
|
||||
1. Enter a unique name for your destination.
|
||||
1. For **destination type**, choose **Amazon SNS**.
|
||||
1. Specify the SNS topic ARN that you want to use.
|
||||
|
||||
The alerting plugin currently supports user authentication through OpenSearch's keystore and IAM in Amazon Web Services. If you run your OpenSearch cluster on AWS infrastructure (an Amazon EC2 instance), the alerting plugin automatically retrieves the credentials of an IAM role associated with your EC2 instance. If you're not running your cluster on Amazon EC2, you must add your IAM user's access key and secret key to OpenSearch's keystore.
|
||||
|
||||
To use either method, first ensure that the IAM role you want to use has the following trust relationship and permissions:
|
||||
|
||||
```json
|
||||
{
|
||||
"Version": "2012-10-17",
|
||||
"Statement": [{
|
||||
"Effect": "Allow",
|
||||
"Principal": {
|
||||
"Service": "ec2.amazonaws.com"
|
||||
},
|
||||
"Action": "sts:AssumeRole"
|
||||
}]
|
||||
}
|
||||
```
|
||||
|
||||
```json
|
||||
{
|
||||
"Version": "2012-10-17",
|
||||
"Statement": [{
|
||||
"Effect": "Allow",
|
||||
"Action": "sns:Publish",
|
||||
"Resource": "sns-topic-arn"
|
||||
}]
|
||||
}
|
||||
```
|
||||
|
||||
#### Using an IAM role's credentials
|
||||
|
||||
If you're running your OpenSearch cluster on AWS infrastructure, Amazon EC2 will automatically retrieve your IAM role's credentials and access the SNS topic, so you don't have to add any user ceredentials.
|
||||
|
||||
In OpenSearch Dashboards, choose **Create**.
|
||||
|
||||
#### Adding access key and secret access key
|
||||
|
||||
After ensuring that your IAM user has the necessary trust relationship and permissions, run the following commands in your terminal and follow the prompts to add your IAM user's access key and secret key.
|
||||
|
||||
```
|
||||
./bin/opensearch-keystore add opensearch.alerting.destination.sns.access.key
|
||||
./bin/opensearch-keystore add opensearch.alerting.destination.sns.secret.key
|
||||
```
|
||||
|
||||
In OpenSearch Dashboards, choose **Create**.
|
||||
|
||||
### Email as a destination
|
||||
|
||||
@@ -78,8 +132,8 @@ You can enter individual email addresses or an email group in the **Recipients**
|
||||
If your email provider requires SSL or TLS, you must authenticate each sender account before you can send an email. Enter these credentials in the OpenSearch keystore using the CLI. Run the following commands (in your OpenSearch directory) to enter your username and password. The `<sender_name>` is the name you entered for **Sender** earlier.
|
||||
|
||||
```bash
|
||||
./bin/opensearch-keystore add plugins.alerting.destination.email.<sender_name>.username
|
||||
./bin/opensearch-keystore add plugins.alerting.destination.email.<sender_name>.password
|
||||
./bin/opensearch-keystore add opensearch.alerting.destination.email.<sender_name>.username
|
||||
./bin/opensearch-keystore add opensearch.alerting.destination.email.<sender_name>.password
|
||||
```
|
||||
|
||||
**Note**: Keystore settings are node-specific. You must run these commands on each node.
|
||||
@@ -94,7 +148,6 @@ POST _nodes/reload_secure_settings
|
||||
}
|
||||
```
|
||||
|
||||
|
||||
---
|
||||
|
||||
## Create monitors
|
||||
@@ -102,7 +155,7 @@ POST _nodes/reload_secure_settings
|
||||
1. Choose **Alerting**, **Monitors**, **Create monitor**.
|
||||
1. Specify a name for the monitor.
|
||||
|
||||
The anomaly detection option is for pairing with the anomaly detection plugin. See [Anomaly Detection]({{site.url}}{{site.baseurl}}/monitoring-plugins/ad/).
|
||||
The anomaly detection option is for pairing with the anomaly detection plugin. See [Anomaly Detection](../../ad/).
|
||||
For anomaly detector, choose an appropriate schedule for the monitor based on the detector interval. Otherwise, the alerting monitor might miss reading the results.
|
||||
|
||||
For example, assume you set the monitor interval and the detector interval as 5 minutes, and you start the detector at 12:00. If an anomaly is detected at 12:05, it might be available at 12:06 because of the delay between writing the anomaly and it being available for queries. The monitor reads the anomaly results between 12:00 and 12:05, so it does not get the anomaly results available at 12:06.
|
||||
@@ -114,13 +167,13 @@ Whenever you update a detector’s interval, make sure to update the associated
|
||||
|
||||
1. Choose one or more indices. You can also use `*` as a wildcard to specify an index pattern.
|
||||
|
||||
If you use the security plugin, you can only choose indices that you have permission to access. For details, see [Alerting security]({{site.url}}{{site.baseurl}}/security-plugin/).
|
||||
If you use the security plugin, you can only choose indices that you have permission to access. For details, see [Alerting security](../security/).
|
||||
|
||||
1. Define the monitor in one of three ways: visually, using a query, or using an anomaly detector.
|
||||
|
||||
- Visual definition works well for monitors that you can define as "some value is above or below some threshold for some amount of time."
|
||||
|
||||
- Query definition gives you flexibility in terms of what you query for (using [the OpenSearch query DSL]({{site.url}}{{site.baseurl}}/opensearch/query-dsl/full-text)) and how you evaluate the results of that query (Painless scripting).
|
||||
- Query definition gives you flexibility in terms of what you query for (using [the OpenSearch query DSL](../../opensearch/full-text)) and how you evaluate the results of that query (Painless scripting).
|
||||
|
||||
This example averages the `cpu_usage` field:
|
||||
|
||||
@@ -172,12 +225,12 @@ Whenever you update a detector’s interval, make sure to update the associated
|
||||
|
||||
1. To define a monitor visually, choose **Define using visual graph**. Then choose an aggregation (for example, `count()` or `average()`), a set of documents, and a timeframe. Visual definition works well for most monitors.
|
||||
|
||||
To use a query, choose **Define using extraction query**, add your query (using [the OpenSearch query DSL]({{site.url}}{{site.baseurl}}/opensearch/query-dsl/full-text/)), and test it using the **Run** button.
|
||||
To use a query, choose **Define using extraction query**, add your query (using [the OpenSearch query DSL](../../opensearch/full-text/)), and test it using the **Run** button.
|
||||
|
||||
The monitor makes this query to OpenSearch as often as the schedule dictates; check the **Query Performance** section and make sure you're comfortable with the performance implications.
|
||||
|
||||
To use an anomaly detector, choose **Define using Anomaly detector** and select your **Detector**.
|
||||
1. Choose a frequency and timezone for your monitor. Note that you can only pick a timezone if you choose Daily, Weekly, Monthly, or [custom cron expression]({{site.url}}{{site.baseurl}}/monitoring-plugins/alerting/cron/) for frequency.
|
||||
1. Choose a frequency and timezone for your monitor. Note that you can only pick a timezone if you choose Daily, Weekly, Monthly, or [custom cron expression](../cron/) for frequency.
|
||||
1. Choose **Create**.
|
||||
|
||||
|
||||
@@ -265,7 +318,7 @@ Below are some variables you can include in your message using Mustache template
|
||||
Variable | Data Type | Description
|
||||
:--- | :--- | :---
|
||||
`ctx.monitor` | JSON | Includes `ctx.monitor.name`, `ctx.monitor.type`, `ctx.monitor.enabled`, `ctx.monitor.enabled_time`, `ctx.monitor.schedule`, `ctx.monitor.inputs`, `triggers` and `ctx.monitor.last_update_time`.
|
||||
`ctx.monitor.user` | JSON | Includes information about the user who created the monitor. Includes `ctx.monitor.user.backend_roles` and `ctx.monitor.user.roles`, which are arrays that contain the backend roles and roles assigned to the user. See [alerting security]({{site.url}}{{site.baseurl}}/monitoring-plugins/alerting/security/) for more information.
|
||||
`ctx.monitor.user` | JSON | Includes information about the user who created the monitor. Includes `ctx.monitor.user.backend_roles` and `ctx.monitor.user.roles`, which are arrays that contain the backend roles and roles assigned to the user. See [alerting security](../security/) for more information.
|
||||
`ctx.monitor.enabled` | Boolean | Whether the monitor is enabled.
|
||||
`ctx.monitor.enabled_time` | Milliseconds | Unix epoch time of when the monitor was last enabled.
|
||||
`ctx.monitor.schedule` | JSON | Contains a schedule of how often or when the monitor should run.
|
||||
@@ -316,7 +369,7 @@ Variable | Data Type | Description
|
||||
|
||||
## Add actions
|
||||
|
||||
The final step in creating a monitor is to add one or more actions. Actions send notifications when trigger conditions are met and support [Slack](https://slack.com/), [Amazon Chime](https://aws.amazon.com/chime/), and webhooks.
|
||||
The final step in creating a monitor is to add one or more actions. Actions send notifications when trigger conditions are met and support [Slack](https://slack.com/), [Amazon Chime](https://aws.amazon.com/chime/), [Amazon Simple Notification Service](https://aws.amazon.com/sns/), and webhooks.
|
||||
|
||||
If you don't want to receive notifications for alerts, you don't have to add actions to your triggers. Instead, you can periodically check OpenSearch Dashboards.
|
||||
{: .tip }
|
||||
@@ -1,6 +1,6 @@
|
||||
---
|
||||
layout: default
|
||||
title: Alerting security
|
||||
title: Alerting Security
|
||||
nav_order: 10
|
||||
parent: Alerting
|
||||
has_children: false
|
||||
@@ -13,9 +13,9 @@ If you use the security plugin alongside alerting, you might want to limit certa
|
||||
|
||||
## Basic permissions
|
||||
|
||||
The security plugin has three built-in roles that cover most alerting use cases: `alerting_read_access`, `alerting_ack_alerts`, and `alerting_full_access`. For descriptions of each, see [Predefined roles]({{site.url}}{{site.baseurl}}/security-plugin/access-control/users-roles#predefined-roles).
|
||||
The security plugin has three built-in roles that cover most alerting use cases: `alerting_read_access`, `alerting_ack_alerts`, and `alerting_full_access`. For descriptions of each, see [Predefined roles](../../security/access-control/users-roles/#predefined-roles).
|
||||
|
||||
If these roles don't meet your needs, mix and match individual alerting [permissions]({{site.url}}{{site.baseurl}}/security-plugin/access-control/permissions/) to suit your use case. Each action corresponds to an operation in the REST API. For example, the `cluster:admin/opensearch/alerting/destination/delete` permission lets you delete destinations.
|
||||
If these roles don't meet your needs, mix and match individual alerting [permissions](../../security/access-control/permissions/) to suit your use case. Each action corresponds to an operation in the REST API. For example, the `cluster:admin/opensearch/alerting/destination/delete` permission lets you delete destinations.
|
||||
|
||||
|
||||
## How monitors access data
|
||||
@@ -29,14 +29,14 @@ Later, the user `psantos` wants to edit the monitor to run every two hours, but
|
||||
- Update the monitor so that it only checks `store1-returns`.
|
||||
- Ask an administrator for read access to the other two indices.
|
||||
|
||||
After making the change, the monitor now runs with the same permissions as `psantos`, including any [document-level security]({{site.url}}{{site.baseurl}}/security-plugin/access-control/document-level-security/) queries, [excluded fields]({{site.url}}{{site.baseurl}}/security-plugin/access-control/field-level-security/), and [masked fields]({{site.url}}{{site.baseurl}}/security-plugin/access-control/field-masking/). If you use an extraction query to define your monitor, use the **Run** button to ensure that the response includes the fields you need.
|
||||
After making the change, the monitor now runs with the same permissions as `psantos`, including any [document-level security](../../security/access-control/document-level-security/) queries, [excluded fields](../../security/access-control/field-level-security/), and [masked fields](../../security/access-control/field-masking/). If you use an extraction query to define your monitor, use the **Run** button to ensure that the response includes the fields you need.
|
||||
|
||||
|
||||
## (Advanced) Limit access by backend role
|
||||
|
||||
Out of the box, the alerting plugin has no concept of ownership. For example, if you have the `cluster:admin/opensearch/alerting/monitor/write` permission, you can edit *all* monitors, regardless of whether you created them. If a small number of trusted users manage your monitors and destinations, this lack of ownership generally isn't a problem. A larger organization might need to segment access by backend role.
|
||||
|
||||
First, make sure that your users have the appropriate [backend roles]({{site.url}}{{site.baseurl}}/security-plugin/access-control/index/). Backend roles usually come from an [LDAP server]({{site.url}}{{site.baseurl}}/security-plugin/configuration/ldap/) or [SAML provider]({{site.url}}{{site.baseurl}}/security-plugin/configuration/saml/). However, if you use the internal user database, you can use the REST API to [add them manually]({{site.url}}{{site.baseurl}}/security-plugin/access-control/api#create-user).
|
||||
First, make sure that your users have the appropriate [backend roles](../../security/access-control/). Backend roles usually come from an [LDAP server](../../security/configuration/ldap/) or [SAML provider](../../security/configuration/saml/). However, if you use the internal user database, you can use the REST API to [add them manually](../../security/access-control/api/#create-user).
|
||||
|
||||
Next, enable the following setting:
|
||||
|
||||
@@ -44,7 +44,7 @@ Next, enable the following setting:
|
||||
PUT _cluster/settings
|
||||
{
|
||||
"transient": {
|
||||
"plugins.alerting.filter_by_backend_roles": "true"
|
||||
"opendistro.alerting.filter_by_backend_roles": "true"
|
||||
}
|
||||
}
|
||||
```
|
||||
@@ -58,7 +58,7 @@ If `jdoe` creates a monitor, `jroe` can see and modify it, but `psantos` can't.
|
||||
|
||||
<!-- ## (Advanced) Limit access by individual
|
||||
|
||||
If you only want users to be able to see and modify their own monitors and destinations, duplicate the `alerting_full_access` role and add the following [DLS query]({{site.url}}{{site.baseurl}}/security-plugin/access-control/document-level-security/) to it:
|
||||
If you only want users to be able to see and modify their own monitors and destinations, duplicate the `alerting_full_access` role and add the following [DLS query](../../security/access-control/document-level-security/) to it:
|
||||
|
||||
```json
|
||||
{
|
||||
@@ -0,0 +1,59 @@
|
||||
---
|
||||
layout: default
|
||||
title: Management
|
||||
parent: Alerting
|
||||
nav_order: 5
|
||||
---
|
||||
|
||||
# Management
|
||||
|
||||
|
||||
## Alerting indices
|
||||
|
||||
The alerting feature creates several indices and one alias. The security plugin demo script configures them as [system indices](../../security/configuration/system-indices/) for an extra layer of protection. Don't delete these indices or modify their contents without using the alerting APIs.
|
||||
|
||||
Index | Purpose
|
||||
:--- | :---
|
||||
`.opendistro-alerting-alerts` | Stores ongoing alerts.
|
||||
`.opendistro-alerting-alert-history-<date>` | Stores a history of completed alerts.
|
||||
`.opendistro-alerting-config` | Stores monitors, triggers, and destinations. [Take a snapshot](../../opensearch/snapshot-restore) of this index to back up your alerting configuration.
|
||||
`.opendistro-alerting-alert-history-write` (alias) | Provides a consistent URI for the `.opendistro-alerting-alert-history-<date>` index.
|
||||
|
||||
All alerting indices are hidden by default. For a summary, make the following request:
|
||||
|
||||
```
|
||||
GET _cat/indices?expand_wildcards=open,hidden
|
||||
```
|
||||
|
||||
|
||||
## Alerting settings
|
||||
|
||||
We don't recommend changing these settings; the defaults should work well for most use cases.
|
||||
|
||||
All settings are available using the OpenSearch `_cluster/settings` API. None require a restart, and all can be marked `persistent` or `transient`.
|
||||
|
||||
Setting | Default | Description
|
||||
:--- | :--- | :---
|
||||
`opensearch.scheduled_jobs.enabled` | true | Whether the alerting plugin is enabled or not. If disabled, all monitors immediately stop running.
|
||||
`opendistro.alerting.index_timeout` | 60s | The timeout for creating monitors and destinations using the REST APIs.
|
||||
`opendistro.alerting.request_timeout` | 10s | The timeout for miscellaneous requests from the plugin.
|
||||
`opendistro.alerting.action_throttle_max_value` | 24h | The maximum amount of time you can set for action throttling. By default, this value displays as 1440 minutes in OpenSearch Dashboards.
|
||||
`opendistro.alerting.input_timeout` | 30s | How long the monitor can take to issue the search request.
|
||||
`opendistro.alerting.bulk_timeout` | 120s | How long the monitor can write alerts to the alert index.
|
||||
`opendistro.alerting.alert_backoff_count` | 3 | The number of retries for writing alerts before the operation fails.
|
||||
`opendistro.alerting.alert_backoff_millis` | 50ms | The amount of time to wait between retries---increases exponentially after each failed retry.
|
||||
`opendistro.alerting.alert_history_rollover_period` | 12h | How frequently to check whether the `.opendistro-alerting-alert-history-write` alias should roll over to a new history index and whether the Alerting plugin should delete any history indices.
|
||||
`opendistro.alerting.move_alerts_backoff_millis` | 250 | The amount of time to wait between retries---increases exponentially after each failed retry.
|
||||
`opendistro.alerting.move_alerts_backoff_count` | 3 | The number of retries for moving alerts to a deleted state after their monitor or trigger has been deleted.
|
||||
`opendistro.alerting.monitor.max_monitors` | 1000 | The maximum number of monitors users can create.
|
||||
`opendistro.alerting.alert_history_max_age` | 30d | The oldest document to store in the `.opensearch-alert-history-<date>` index before creating a new index. If the number of alerts in this time period does not exceed `alert_history_max_docs`, alerting creates one history index per period (e.g. one index every 30 days).
|
||||
`opendistro.alerting.alert_history_max_docs` | 1000 | The maximum number of alerts to store in the `.opensearch-alert-history-<date>` index before creating a new index.
|
||||
`opendistro.alerting.alert_history_enabled` | true | Whether to create `.opendistro-alerting-alert-history-<date>` indices.
|
||||
`opendistro.alerting.alert_history_retention_period` | 60d | The amount of time to keep history indices before automatically deleting them.
|
||||
`opendistro.alerting.destination.allow_list` | ["chime", "slack", "custom_webhook", "email", "test_action"] | The list of allowed destinations. If you don't want to allow users to a certain type of destination, you can remove it from this list, but we recommend leaving this setting as-is.
|
||||
`opendistro.alerting.filter_by_backend_roles` | "false" | Restricts access to monitors by backend role. See [Alerting security](../security/).
|
||||
`opensearch.scheduled_jobs.sweeper.period` | 5m | The alerting feature uses its "job sweeper" component to periodically check for new or updated jobs. This setting is the rate at which the sweeper checks to see if any jobs (monitors) have changed and need to be rescheduled.
|
||||
`opensearch.scheduled_jobs.sweeper.page_size` | 100 | The page size for the sweeper. You shouldn't need to change this value.
|
||||
`opensearch.scheduled_jobs.sweeper.backoff_millis` | 50ms | The amount of time the sweeper waits between retries---increases exponentially after each failed retry.
|
||||
`opensearch.scheduled_jobs.sweeper.retry_count` | 3 | The total number of times the sweeper should retry before throwing an error.
|
||||
`opensearch.scheduled_jobs.request_timeout` | 10s | The timeout for the request that sweeps shards for jobs.
|
||||
@@ -3,9 +3,6 @@ layout: default
|
||||
title: Asynchronous search
|
||||
nav_order: 51
|
||||
has_children: true
|
||||
redirect_from:
|
||||
- /docs/async/
|
||||
- /search-plugins/async/
|
||||
---
|
||||
|
||||
# Asynchronous search
|
||||
@@ -16,10 +13,10 @@ Asynchronous search in OpenSearch lets you send search requests that run in the
|
||||
|
||||
## REST API
|
||||
|
||||
To perform an asynchronous search, send requests to `_plugins/_asynchronous_search`, with your query in the request body:
|
||||
To perform an asynchronous search, send requests to `_opensearch/_asynchronous_search`, with your query in the request body:
|
||||
|
||||
```json
|
||||
POST _plugins/_asynchronous_search
|
||||
POST _opensearch/_asynchronous_search
|
||||
```
|
||||
|
||||
You can specify the following options.
|
||||
@@ -33,7 +30,7 @@ Options | Description | Default value | Required
|
||||
#### Sample request
|
||||
|
||||
```json
|
||||
POST _plugins/_asynchronous_search/?pretty&size=10&wait_for_completion_timeout=1ms&keep_on_completion=true&request_cache=false
|
||||
POST _opensearch/_asynchronous_search/?pretty&size=10&wait_for_completion_timeout=1ms&keep_on_completion=true&request_cache=false
|
||||
{
|
||||
"aggs": {
|
||||
"city": {
|
||||
@@ -116,7 +113,7 @@ Options | Description
|
||||
After you submit an asynchronous search request, you can request partial responses with the ID that you see in the asynchronous search response.
|
||||
|
||||
```json
|
||||
GET _plugins/_asynchronous_search/<ID>?pretty
|
||||
GET _opensearch/_asynchronous_search/<ID>?pretty
|
||||
```
|
||||
|
||||
#### Sample response
|
||||
@@ -192,7 +189,7 @@ For asynchronous searches with `keep_on_completion` as `true` and a sufficiently
|
||||
You can use the DELETE API operation to delete any ongoing asynchronous search by its ID. If the search is still running, it’s canceled. If the search is complete, the saved search results are deleted.
|
||||
|
||||
```json
|
||||
DELETE _plugins/_asynchronous_search/<ID>?pretty
|
||||
DELETE _opensearch/_asynchronous_search/<ID>?pretty
|
||||
```
|
||||
|
||||
#### Sample response
|
||||
@@ -208,7 +205,7 @@ DELETE _plugins/_asynchronous_search/<ID>?pretty
|
||||
You can use the stats API operation to monitor asynchronous searches that are running, completed, and/or persisted.
|
||||
|
||||
```json
|
||||
GET _plugins/_asynchronous_search/stats
|
||||
GET _opensearch/_asynchronous_search/stats
|
||||
```
|
||||
|
||||
#### Sample response
|
||||
@@ -4,20 +4,19 @@ title: Asynchronous search security
|
||||
nav_order: 2
|
||||
parent: Asynchronous search
|
||||
has_children: false
|
||||
redirect_from: /docs/async/security/
|
||||
---
|
||||
|
||||
# Asynchronous search security
|
||||
|
||||
You can use the security plugin with asynchronous searches to limit non-admin users to specific actions. For example, you might want some users to only be able to submit or delete asynchronous searches, while you might want others to only view the results.
|
||||
|
||||
All asynchronous search indices are protected as system indices. Only a super admin user or an admin user with a Transport Layer Security (TLS) certificate can access system indices. For more information, see [System indices]({{site.url}}{{site.baseurl}}/security-plugin/configuration/system-indices/).
|
||||
All asynchronous search indices are protected as system indices. Only a super admin user or an admin user with a Transport Layer Security (TLS) certificate can access system indices. For more information, see [System indices](../../security/configuration/system-indices/).
|
||||
|
||||
## Basic permissions
|
||||
|
||||
As an admin user, you can use the security plugin to assign specific permissions to users based on which API operations they need access to. For a list of supported APIs operations, see [Asynchronous search]({{site.url}}{{site.baseurl}}/).
|
||||
As an admin user, you can use the security plugin to assign specific permissions to users based on which API operations they need access to. For a list of supported APIs operations, see [Asynchronous search](../).
|
||||
|
||||
The security plugin has two built-in roles that cover most asynchronous search use cases: `asynchronous_search_full_access` and `asynchronous_search_read_access`. For descriptions of each, see [Predefined roles]({{site.url}}{{site.baseurl}}/security-plugin/access-control/users-roles#predefined-roles).
|
||||
The security plugin has two built-in roles that cover most asynchronous search use cases: `asynchronous_search_full_access` and `asynchronous_search_read_access`. For descriptions of each, see [Predefined roles](../../security/access-control/users-roles/#predefined-roles).
|
||||
|
||||
If these roles don’t meet your needs, mix and match individual asynchronous search permissions to suit your use case. Each action corresponds to an operation in the REST API. For example, the `cluster:admin/opensearch/asynchronous_search/delete` permission lets you delete a previously submitted asynchronous search.
|
||||
|
||||
@@ -25,7 +24,7 @@ If these roles don’t meet your needs, mix and match individual asynchronous se
|
||||
|
||||
Use backend roles to configure fine-grained access to asynchronous searches based on roles. For example, users of different departments in an organization can view asynchronous searches owned by their own department.
|
||||
|
||||
First, make sure your users have the appropriate [backend roles]({{site.url}}{{site.baseurl}}/security-plugin/access-control/index/). Backend roles usually come from an [LDAP server]({{site.url}}{{site.baseurl}}/security-plugin/configuration/ldap/) or [SAML provider]({{site.url}}{{site.baseurl}}/security-plugin/configuration/saml/). However, if you use the internal user database, you can use the REST API to [add them manually]({{site.url}}{{site.baseurl}}/security-plugin/access-control/api#create-user).
|
||||
First, make sure your users have the appropriate [backend roles](../../security/access-control/). Backend roles usually come from an [LDAP server](../../security/configuration/ldap/) or [SAML provider](../../security/configuration/saml/). However, if you use the internal user database, you can use the REST API to [add them manually](../../security/access-control/api/#create-user).
|
||||
|
||||
Now when users view asynchronous search resources in OpenSearch Dashboards (or make REST API calls), they only see asynchronous searches submitted by users who have a subset of the backend role.
|
||||
For example, consider two users: `judy` and `elon`.
|
||||
@@ -33,7 +32,7 @@ For example, consider two users: `judy` and `elon`.
|
||||
`judy` has an IT backend role:
|
||||
|
||||
```json
|
||||
PUT _plugins/_security/api/internalusers/judy
|
||||
PUT _opensearch/_security/api/internalusers/judy
|
||||
{
|
||||
"password": "judy",
|
||||
"backend_roles": [
|
||||
@@ -46,7 +45,7 @@ PUT _plugins/_security/api/internalusers/judy
|
||||
`elon` has an admin backend role:
|
||||
|
||||
```json
|
||||
PUT _plugins/_security/api/internalusers/elon
|
||||
PUT _opensearch/_security/api/internalusers/elon
|
||||
{
|
||||
"password": "elon",
|
||||
"backend_roles": [
|
||||
@@ -59,7 +58,7 @@ PUT _plugins/_security/api/internalusers/elon
|
||||
Both `judy` and `elon` have full access to asynchronous search:
|
||||
|
||||
```json
|
||||
PUT _plugins/_security/api/rolesmapping/async_full_access
|
||||
PUT _opensearch/_security/api/rolesmapping/async_full_access
|
||||
{
|
||||
"backend_roles": [],
|
||||
"hosts": [],
|
||||
@@ -3,7 +3,6 @@ layout: default
|
||||
title: Settings
|
||||
parent: Asynchronous search
|
||||
nav_order: 4
|
||||
redirect_from: /docs/async/settings/
|
||||
---
|
||||
|
||||
# Settings
|
||||
@@ -3,16 +3,13 @@ layout: default
|
||||
title: OpenSearch CLI
|
||||
nav_order: 52
|
||||
has_children: false
|
||||
redirect_from:
|
||||
- /docs/odfe-cli/
|
||||
- /docs/cli/
|
||||
---
|
||||
|
||||
# OpenSearch CLI
|
||||
|
||||
The OpenSearch CLI command line interface (opensearch-cli) lets you manage your OpenSearch cluster from the command line and automate tasks.
|
||||
|
||||
Currently, opensearch-cli supports the [Anomaly Detection]({{site.url}}{{site.baseurl}}/monitoring-plugins/ad/) and [k-NN]({{site.url}}{{site.baseurl}}/search-plugins/knn/) plugins, along with arbitrary REST API paths. Among other things, you can use opensearch-cli to create and delete detectors, start and stop them, and check k-NN statistics.
|
||||
Currently, opensearch-cli supports the [Anomaly Detection](../ad/) and [k-NN](../knn/) plugins, along with arbitrary REST API paths. Among other things, you can use opensearch-cli to create and delete detectors, start and stop them, and check k-NN statistics.
|
||||
|
||||
Profiles let you easily access different clusters or sign requests with different credentials. opensearch-cli supports unauthenticated requests, HTTP basic signing, and IAM signing for Amazon Web Services.
|
||||
|
||||
@@ -1,13 +1,14 @@
|
||||
---
|
||||
layout: default
|
||||
title: Index rollups
|
||||
title: Index Rollups
|
||||
nav_order: 35
|
||||
parent: Index management
|
||||
has_children: true
|
||||
redirect_from: /docs/ism/index-rollups/
|
||||
has_toc: false
|
||||
---
|
||||
|
||||
# Index rollups
|
||||
# Index Rollups
|
||||
|
||||
Time series data increases storage costs, strains cluster health, and slows down aggregations over time. Index rollup lets you periodically reduce data granularity by rolling up old data into summarized indices.
|
||||
|
||||
@@ -51,7 +52,7 @@ The order in which you select attributes is critical. A city followed by a demog
|
||||
Specify a schedule to roll up your indices as it’s being ingested. The index rollup job is enabled by default.
|
||||
|
||||
1. Specify if the data is continuous or not.
|
||||
3. For roll up execution frequency, select **Define by fixed interval** and specify the **Rollup interval** and the time unit or **Define by cron expression** and add in a cron expression to select the interval. To learn how to define a cron expression, see [Alerting]({{site.url}}{{site.baseurl}}/monitoring-plugins/alerting/cron/).
|
||||
3. For roll up execution frequency, select **Define by fixed interval** and specify the **Rollup interval** and the time unit or **Define by cron expression** and add in a cron expression to select the interval. To learn how to define a cron expression, see [Alerting](../alerting/cron/).
|
||||
4. Specify the number of pages per execution process. A larger number means faster execution and more cost for memory.
|
||||
5. (Optional) Add a delay to the roll up executions. This is the amount of time the job waits for data ingestion to accommodate any processing time. For example, if you set this value to 10 minutes, an index rollup that executes at 2 PM to roll up 1 PM to 2 PM of data starts at 2:10 PM.
|
||||
6. Choose **Next**.
|
||||
@@ -62,7 +63,7 @@ Review your configuration and select **Create**.
|
||||
|
||||
### Step 5: Search the target index
|
||||
|
||||
You can use the standard `_search` API to search the target index. Make sure that the query matches the constraints of the target index. For example, if you don’t set up terms aggregations on a field, you don’t receive results for terms aggregations. If you don’t set up the maximum aggregations, you don’t receive results for maximum aggregations.
|
||||
You can use the standard `_search` API to search the target index. Make sure that the query matches the constraints of the target index. For example, if don’t set up terms aggregations on a field, you don’t receive results for terms aggregations. If you don’t set up the maximum aggregations, you don’t receive results for maximum aggregations.
|
||||
|
||||
You can’t access the internal structure of the data in the target index because the plugin automatically rewrites the query in the background to suit the target index. This is to make sure you can use the same query for the source and target index.
|
||||
|
||||
@@ -218,7 +219,7 @@ Create an index rollup job.
|
||||
This example picks the `order_date`, `customer_gender`, `geoip.city_name`, `geoip.region_name`, and `day_of_week` fields and rolls them into an `example_rollup` target index:
|
||||
|
||||
```json
|
||||
PUT _plugins/_rollup/jobs/example
|
||||
PUT _opensearch/_rollup/jobs/example
|
||||
{
|
||||
"rollup": {
|
||||
"enabled": true,
|
||||
@@ -1,12 +1,13 @@
|
||||
---
|
||||
layout: default
|
||||
title: Index rollups API
|
||||
parent: Index rollups
|
||||
title: Index Rollups API
|
||||
parent: Index Rollups
|
||||
grand_parent: Index management
|
||||
redirect_from: /docs/ism/rollup-api/
|
||||
nav_order: 9
|
||||
---
|
||||
|
||||
# Index rollups API
|
||||
# Index Rollups API
|
||||
|
||||
Use the index rollup operations to programmatically work with index rollup jobs.
|
||||
|
||||
@@ -27,8 +28,8 @@ You must provide the `seq_no` and `primary_term` parameters.
|
||||
#### Request
|
||||
|
||||
```json
|
||||
PUT _plugins/_rollup/jobs/<rollup_id> // Create
|
||||
PUT _plugins/_rollup/jobs/<rollup_id>?if_seq_no=1&if_primary_term=1 // Update
|
||||
PUT _opensearch/_rollup/jobs/<rollup_id> // Create
|
||||
PUT _opensearch/_rollup/jobs/<rollup_id>?if_seq_no=1&if_primary_term=1 // Update
|
||||
{
|
||||
"rollup": {
|
||||
"source_index": "nyc-taxi-data",
|
||||
@@ -140,7 +141,7 @@ Returns all information about an index rollup job based on the `rollup_id`.
|
||||
#### Request
|
||||
|
||||
```json
|
||||
GET _plugins/_rollup/jobs/<rollup_id>
|
||||
GET _opensearch/_rollup/jobs/<rollup_id>
|
||||
```
|
||||
|
||||
|
||||
@@ -165,7 +166,7 @@ Deletes an index rollup job based on the `rollup_id`.
|
||||
#### Request
|
||||
|
||||
```json
|
||||
DELETE _plugins/_rollup/jobs/<rollup_id>
|
||||
DELETE _opensearch/_rollup/jobs/<rollup_id>
|
||||
```
|
||||
|
||||
#### Sample response
|
||||
@@ -184,8 +185,8 @@ Start or stop an index rollup job.
|
||||
#### Request
|
||||
|
||||
```json
|
||||
POST _plugins/_rollup/jobs/<rollup_id>/_start
|
||||
POST _plugins/_rollup/jobs/<rollup_id>/_stop
|
||||
POST _opensearch/_rollup/jobs/<rollup_id>/_start
|
||||
POST _opensearch/_rollup/jobs/<rollup_id>/_stop
|
||||
```
|
||||
|
||||
|
||||
@@ -205,7 +206,7 @@ Returns detailed metadata information about the index rollup job and its current
|
||||
#### Request
|
||||
|
||||
```json
|
||||
GET _plugins/_rollup/jobs/<rollup_id>/_explain
|
||||
GET _opensearch/_rollup/jobs/<rollup_id>/_explain
|
||||
```
|
||||
|
||||
|
||||
@@ -1,13 +1,11 @@
|
||||
---
|
||||
layout: default
|
||||
title: About Index Management
|
||||
nav_order: 1
|
||||
has_children: false
|
||||
redirect_from:
|
||||
- /im-plugin/
|
||||
title: Index management
|
||||
nav_order: 30
|
||||
has_children: true
|
||||
---
|
||||
|
||||
# About Index Management
|
||||
# Index Management
|
||||
OpenSearch Dashboards
|
||||
{: .label .label-yellow :}
|
||||
|
||||
@@ -2,6 +2,7 @@
|
||||
layout: default
|
||||
title: ISM API
|
||||
parent: Index State Management
|
||||
grand_parent: Index management
|
||||
redirect_from: /docs/ism/api/
|
||||
nav_order: 5
|
||||
---
|
||||
@@ -27,7 +28,7 @@ Creates a policy.
|
||||
#### Request
|
||||
|
||||
```json
|
||||
PUT _plugins/_ism/policies/policy_1
|
||||
PUT _opensearch/_ism/policies/policy_1
|
||||
{
|
||||
"policy": {
|
||||
"description": "ingesting logs",
|
||||
@@ -144,7 +145,7 @@ Adds a policy to an index. This operation does not change the policy if the inde
|
||||
#### Request
|
||||
|
||||
```json
|
||||
POST _plugins/_ism/add/index_1
|
||||
POST _opensearch/_ism/add/index_1
|
||||
{
|
||||
"policy_id": "policy_1"
|
||||
}
|
||||
@@ -170,7 +171,7 @@ Updates a policy. Use the `seq_no` and `primary_term` parameters to update an ex
|
||||
#### Request
|
||||
|
||||
```json
|
||||
PUT _plugins/_ism/policies/policy_1?if_seq_no=7&if_primary_term=1
|
||||
PUT _opensearch/_ism/policies/policy_1?if_seq_no=7&if_primary_term=1
|
||||
{
|
||||
"policy": {
|
||||
"description": "ingesting logs",
|
||||
@@ -287,7 +288,7 @@ Gets the policy by `policy_id`.
|
||||
#### Request
|
||||
|
||||
```json
|
||||
GET _plugins/_ism/policies/policy_1
|
||||
GET _opensearch/_ism/policies/policy_1
|
||||
```
|
||||
|
||||
|
||||
@@ -357,7 +358,7 @@ Removes any ISM policy from the index.
|
||||
#### Request
|
||||
|
||||
```json
|
||||
POST _plugins/_ism/remove/index_1
|
||||
POST _opensearch/_ism/remove/index_1
|
||||
```
|
||||
|
||||
|
||||
@@ -384,7 +385,7 @@ In this example, the policy applied on the `index_1` index is changed to `policy
|
||||
#### Request
|
||||
|
||||
```json
|
||||
POST _plugins/_ism/change_policy/index_1
|
||||
POST _opensearch/_ism/change_policy/index_1
|
||||
{
|
||||
"policy_id": "policy_1",
|
||||
"state": "delete",
|
||||
@@ -416,7 +417,7 @@ Retries the failed action for an index. For the retry call to succeed, ISM must
|
||||
#### Request
|
||||
|
||||
```json
|
||||
POST _plugins/_ism/retry/index_1
|
||||
POST _opensearch/_ism/retry/index_1
|
||||
{
|
||||
"state": "delete"
|
||||
}
|
||||
@@ -442,7 +443,7 @@ Gets the current state of the index. You can use index patterns to get the statu
|
||||
#### Request
|
||||
|
||||
```json
|
||||
GET _plugins/_ism/explain/index_1
|
||||
GET _opensearch/_ism/explain/index_1
|
||||
```
|
||||
|
||||
|
||||
@@ -451,12 +452,13 @@ GET _plugins/_ism/explain/index_1
|
||||
```json
|
||||
{
|
||||
"index_1": {
|
||||
"index.plugins.index_state_management.policy_id": "policy_1"
|
||||
"index.opendistro.index_state_management.policy_id": "policy_1"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
The `plugins.index_state_management.policy_id` setting is deprecated starting from ODFE version 1.13.0. We retain this field in the response API for consistency.
|
||||
The `opendistro.index_state_management.policy_id` setting is deprecated starting from version 1.13.0.
|
||||
We retain this field in the response API for consistency.
|
||||
|
||||
---
|
||||
|
||||
@@ -467,7 +469,7 @@ Deletes the policy by `policy_id`.
|
||||
#### Request
|
||||
|
||||
```json
|
||||
DELETE _plugins/_ism/policies/policy_1
|
||||
DELETE _opensearch/_ism/policies/policy_1
|
||||
```
|
||||
|
||||
|
||||
@@ -2,10 +2,9 @@
|
||||
layout: default
|
||||
title: Index State Management
|
||||
nav_order: 3
|
||||
parent: Index management
|
||||
has_children: true
|
||||
redirect_from:
|
||||
- /docs/im/ism/
|
||||
- /docs/ism/
|
||||
redirect_from: /docs/ism/
|
||||
has_toc: false
|
||||
---
|
||||
|
||||
@@ -21,7 +20,7 @@ For example, you can define a policy that moves your index into a `read_only` st
|
||||
|
||||
You might want to perform an index rollover after a certain amount of time or run a `force_merge` operation on an index during off-peak hours to improve search performance during peak hours.
|
||||
|
||||
To use the ISM plugin, your user role needs to be mapped to the `all_access` role that gives you full access to the cluster. To learn more, see [Users and roles]({{site.url}}{{site.baseurl}}/security-plugin/access-control/users-roles/).
|
||||
To use the ISM plugin, your user role needs to be mapped to the `all_access` role that gives you full access to the cluster. To learn more, see [Users and roles](../security/access-control/users-roles/).
|
||||
{: .note }
|
||||
|
||||
## Get started with ISM
|
||||
@@ -30,7 +29,7 @@ To get started, choose **Index Management** in OpenSearch Dashboards.
|
||||
|
||||
### Step 1: Set up policies
|
||||
|
||||
A policy is a set of rules that describes how an index should be managed. For information about creating a policy, see [Policies]({{site.url}}{{site.baseurl}}/im-plugin/ism/policies/).
|
||||
A policy is a set of rules that describes how an index should be managed. For information about creating a policy, see [Policies](policies/).
|
||||
|
||||
1. Choose the **Index Policies** tab.
|
||||
2. Choose **Create policy**.
|
||||
@@ -42,7 +41,7 @@ After you create a policy, your next step is to attach this policy to an index o
|
||||
You can set up an `ism_template` in the policy so when you create an index that matches the ISM template pattern, the index will have this policy attached to it:
|
||||
|
||||
```json
|
||||
PUT _plugins/_ism/policies/policy_id
|
||||
PUT _opensearch/_ism/policies/policy_id
|
||||
{
|
||||
"policy": {
|
||||
"description": "Example policy.",
|
||||
@@ -56,7 +55,7 @@ PUT _plugins/_ism/policies/policy_id
|
||||
}
|
||||
```
|
||||
|
||||
For an example ISM template policy, see [Sample policy with ISM template]({{site.url}}{{site.baseurl}}/im-plugin/ism/policies#sample-policy-with-ism-template).
|
||||
For an example ISM template policy, see [Sample policy with ISM template](policies/#sample-policy-with-ism-template).
|
||||
|
||||
Older versions of the plugin include the `policy_id` in an index template, so when an index is created that matches the index template pattern, the index will have the policy attached to it:
|
||||
|
||||
@@ -85,20 +84,20 @@ The `opendistro.index_state_management.policy_id` setting is deprecated. You can
|
||||
4. From the **Policy ID** menu, choose the policy that you created.
|
||||
You can see a preview of your policy.
|
||||
5. If your policy includes a rollover operation, specify a rollover alias.
|
||||
Make sure that the alias that you enter already exists. For more information about the rollover operation, see [rollover]({{site.url}}{{site.baseurl}}/im-plugin/ism/policies#rollover).
|
||||
Make sure that the alias that you enter already exists. For more information about the rollover operation, see [rollover](policies/#rollover).
|
||||
6. Choose **Apply**.
|
||||
|
||||
After you attach a policy to an index, ISM creates a job that runs every 5 minutes by default to perform policy actions, check conditions, and transition the index into different states. To change the default time interval for this job, see [Settings]({{site.url}}{{site.baseurl}}/im-plugin/ism/settings/).
|
||||
After you attach a policy to an index, ISM creates a job that runs every 5 minutes by default to perform policy actions, check conditions, and transition the index into different states. To change the default time interval for this job, see [Settings](settings/).
|
||||
|
||||
If you want to use an OpenSearch operation to create an index with a policy already attached to it, see [create index]({{site.url}}{{site.baseurl}}/im-plugin/ism/api#create-index).
|
||||
If you want to use an OpenSearch operation to create an index with a policy already attached to it, see [create index](api/#create-index).
|
||||
|
||||
### Step 3: Manage indices
|
||||
|
||||
1. Choose **Managed Indices**.
|
||||
2. To change your policy, see [Change Policy]({{site.url}}{{site.baseurl}}/im-plugin/ism/managedindices#change-policy).
|
||||
2. To change your policy, see [Change Policy](managedindices/#change-policy).
|
||||
3. To attach a rollover alias to your index, select your policy and choose **Add rollover alias**.
|
||||
Make sure that the alias that you enter already exists. For more information about the rollover operation, see [rollover]({{site.url}}{{site.baseurl}}/im-plugin/ism/policies#rollover).
|
||||
Make sure that the alias that you enter already exists. For more information about the rollover operation, see [rollover](policies/#rollover).
|
||||
4. To remove a policy, choose your policy, and then choose **Remove policy**.
|
||||
5. To retry a policy, choose your policy, and then choose **Retry policy**.
|
||||
|
||||
For information about managing your policies, see [Managed Indices]({{site.url}}{{site.baseurl}}/im-plugin/ism/managedindices/).
|
||||
For information about managing your policies, see [Managed Indices](managedindices/).
|
||||
@@ -3,6 +3,7 @@ layout: default
|
||||
title: Managed Indices
|
||||
nav_order: 3
|
||||
parent: Index State Management
|
||||
grand_parent: Index management
|
||||
redirect_from: /docs/ism/managedindices/
|
||||
has_children: false
|
||||
---
|
||||
@@ -3,6 +3,7 @@ layout: default
|
||||
title: Policies
|
||||
nav_order: 1
|
||||
parent: Index State Management
|
||||
grand_parent: Index management
|
||||
redirect_from: /docs/ism/policies/
|
||||
has_children: false
|
||||
---
|
||||
@@ -88,7 +89,7 @@ The following example action has a timeout period of one hour. The policy retrie
|
||||
}
|
||||
```
|
||||
|
||||
For a list of available unit types, see [Supported units]({{site.url}}{{site.baseurl}}/opensearch/units/).
|
||||
For a list of available unit types, see [Supported units](../../../opensearch/units/).
|
||||
|
||||
## ISM supported operations
|
||||
|
||||
@@ -159,7 +160,7 @@ Parameter | Description | Type | Required
|
||||
}
|
||||
```
|
||||
|
||||
For information about setting replicas, see [Primary and replica shards]({{site.url}}{{site.baseurl}}/opensearch#primary-and-replica-shards).
|
||||
For information about setting replicas, see [Primary and replica shards](../../../opensearch/#primary-and-replica-shards).
|
||||
|
||||
### close
|
||||
|
||||
@@ -200,7 +201,7 @@ Deletes a managed index.
|
||||
Rolls an alias over to a new index when the managed index meets one of the rollover conditions.
|
||||
|
||||
The index format must match the pattern: `^.*-\d+$`. For example, `(logs-000001)`.
|
||||
Set `index.plugins.index_state_management.rollover_alias` as the alias to rollover.
|
||||
Set `index.opendistro.index_state_management.rollover_alias` as the alias to rollover.
|
||||
|
||||
Parameter | Description | Type | Example | Required
|
||||
:--- | :--- |:--- |:--- |
|
||||
@@ -308,7 +309,7 @@ Parameter | Description | Type
|
||||
|
||||
### snapshot
|
||||
|
||||
Backup your cluster’s indices and state. For more information about snapshots, see [Take and restore snapshots]({{site.url}}{{site.baseurl}}/opensearch/snapshot-restore/).
|
||||
Backup your cluster’s indices and state. For more information about snapshots, see [Take and restore snapshots](../../../opensearch/snapshot-restore/).
|
||||
|
||||
The `snapshot` operation has the following parameters:
|
||||
|
||||
@@ -435,7 +436,7 @@ Note that this condition does not execute at exactly 5:00 PM; the job still exec
|
||||
|
||||
A window of an hour, which this example uses, is generally sufficient, but you might increase it to 2--3 hours to avoid missing the window and having to wait a week for the transition to occur. Alternately, you could use a broader expression such as `* * * * SAT,SUN` to have the transition occur at any time during the weekend.
|
||||
|
||||
For information on writing cron expressions, see [Cron expression reference]({{site.url}}{{site.baseurl}}/monitoring-plugins/alerting/cron/).
|
||||
For information on writing cron expressions, see [Cron expression reference](../../../alerting/cron/).
|
||||
|
||||
---
|
||||
|
||||
@@ -525,7 +526,7 @@ The following sample template policy is for a rollover use case.
|
||||
1. Create a policy with an `ism_template` field:
|
||||
|
||||
```json
|
||||
PUT _plugins/_ism/policies/rollover_policy
|
||||
PUT _opensearch/_ism/policies/rollover_policy
|
||||
{
|
||||
"policy": {
|
||||
"description": "Example rollover policy.",
|
||||
@@ -560,7 +561,7 @@ The following sample template policy is for a rollover use case.
|
||||
{
|
||||
"index_patterns": ["log*"],
|
||||
"settings": {
|
||||
"plugins.index_state_management.rollover_alias": "log"
|
||||
"opendistro.index_state_management.rollover_alias": "log"
|
||||
}
|
||||
}
|
||||
```
|
||||
@@ -662,4 +663,4 @@ After 30 days, the policy moves this index into a `delete` state. The service se
|
||||
|
||||
This diagram shows the `states`, `transitions`, and `actions` of the above policy as a finite-state machine. For more information about finite-state machines, see [Wikipedia](https://en.wikipedia.org/wiki/Finite-state_machine).
|
||||
|
||||
|
||||
|
||||
@@ -0,0 +1,50 @@
|
||||
---
|
||||
layout: default
|
||||
title: Settings
|
||||
parent: Index State Management
|
||||
grand_parent: Index management
|
||||
redirect_from: /docs/ism/settings/
|
||||
nav_order: 4
|
||||
---
|
||||
|
||||
# ISM Settings
|
||||
|
||||
We don't recommend changing these settings; the defaults should work well for most use cases.
|
||||
|
||||
Index State Management (ISM) stores its configuration in the `.opendistro-ism-config` index. Don't modify this index without using the [ISM API operations](../api/).
|
||||
|
||||
All settings are available using the OpenSearch `_cluster/settings` operation. None require a restart, and all can be marked `persistent` or `transient`.
|
||||
|
||||
Setting | Default | Description
|
||||
:--- | :--- | :---
|
||||
`opendistro.index_state_management.enabled` | True | Specifies whether ISM is enabled or not.
|
||||
`opendistro.index_state_management.job_interval` | 5 minutes | The interval at which the managed index jobs are run.
|
||||
`opendistro.index_state_management.coordinator.sweep_period` | 10 minutes | How often the routine background sweep is run.
|
||||
`opendistro.index_state_management.coordinator.backoff_millis` | 50 milliseconds | The backoff time between retries for failures in the `ManagedIndexCoordinator` (such as when we update managed indices).
|
||||
`opendistro.index_state_management.coordinator.backoff_count` | 2 | The count of retries for failures in the `ManagedIndexCoordinator`.
|
||||
`opendistro.index_state_management.history.enabled` | True | Specifies whether audit history is enabled or not. The logs from ISM are automatically indexed to a logs document.
|
||||
`opendistro.index_state_management.history.max_docs` | 2,500,000 | The maximum number of documents before rolling over the audit history index.
|
||||
`opendistro.index_state_management.history.max_age` | 24 hours | The maximum age before rolling over the audit history index.
|
||||
`opendistro.index_state_management.history.rollover_check_period` | 8 hours | The time between rollover checks for the audit history index.
|
||||
`opendistro.index_state_management.history.rollover_retention_period` | 30 days | How long audit history indices are kept.
|
||||
`opendistro.index_state_management.allow_list` | All actions | List of actions that you can use.
|
||||
|
||||
|
||||
## Audit history indices
|
||||
|
||||
If you don't want to disable ISM audit history or shorten the retention period, you can create an [index template](../../../opensearch/index-templates/) to reduce the shard count of the history indices:
|
||||
|
||||
```json
|
||||
PUT _index_template/ism_history_indices
|
||||
{
|
||||
"index_patterns": [
|
||||
".opendistro-ism-managed-index-history-*"
|
||||
],
|
||||
"template": {
|
||||
"settings": {
|
||||
"number_of_shards": 1,
|
||||
"number_of_replicas": 0
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
@@ -1,7 +1,8 @@
|
||||
---
|
||||
layout: default
|
||||
title: Refresh search analyzer
|
||||
title: Refresh Search Analyzer
|
||||
nav_order: 40
|
||||
parent: Index management
|
||||
has_children: false
|
||||
redirect_from: /docs/ism/refresh-analyzer/
|
||||
has_toc: false
|
||||
@@ -12,7 +13,7 @@ has_toc: false
|
||||
With ISM installed, you can refresh search analyzers in real time with the following API:
|
||||
|
||||
```json
|
||||
POST /_plugins/_refresh_search_analyzers/<index or alias or wildcard>
|
||||
POST /_opensearch/_refresh_search_analyzers/<index or alias or wildcard>
|
||||
```
|
||||
For example, if you change the synonym list in your analyzer, the change takes effect without you needing to close and reopen the index.
|
||||
|
||||
|
Before Width: | Height: | Size: 328 KiB After Width: | Height: | Size: 328 KiB |
|
Before Width: | Height: | Size: 36 KiB After Width: | Height: | Size: 36 KiB |
|
Before Width: | Height: | Size: 3.1 MiB After Width: | Height: | Size: 3.1 MiB |
|
Before Width: | Height: | Size: 24 KiB After Width: | Height: | Size: 24 KiB |
|
Before Width: | Height: | Size: 18 KiB After Width: | Height: | Size: 18 KiB |
|
Before Width: | Height: | Size: 28 KiB After Width: | Height: | Size: 28 KiB |
|
Before Width: | Height: | Size: 152 KiB After Width: | Height: | Size: 152 KiB |
|
Before Width: | Height: | Size: 68 KiB After Width: | Height: | Size: 68 KiB |
|
Before Width: | Height: | Size: 25 KiB After Width: | Height: | Size: 25 KiB |
|
Before Width: | Height: | Size: 31 KiB After Width: | Height: | Size: 31 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 121 KiB |
|
Before Width: | Height: | Size: 43 KiB After Width: | Height: | Size: 43 KiB |
|
Before Width: | Height: | Size: 236 KiB After Width: | Height: | Size: 236 KiB |
|
Before Width: | Height: | Size: 220 KiB After Width: | Height: | Size: 220 KiB |
|
Before Width: | Height: | Size: 31 KiB After Width: | Height: | Size: 31 KiB |
Some files were not shown because too many files have changed in this diff Show More
Reference in New Issue
Block a user