From d31b21082db53c6ba228ec8c8899f2f457ec846e Mon Sep 17 00:00:00 2001 From: Xue Zhou Date: Mon, 19 Jul 2021 23:16:03 -0700 Subject: [PATCH 001/167] Update configuration.md --- _opensearch/configuration.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/_opensearch/configuration.md b/_opensearch/configuration.md index a6a0f995..726591a2 100755 --- a/_opensearch/configuration.md +++ b/_opensearch/configuration.md @@ -65,4 +65,8 @@ PUT _cluster/settings You can find `opensearch.yml` in `/usr/share/opensearch/config/opensearch.yml` (Docker) or `/etc/opensearch/opensearch.yml` (most Linux distributions) on each node. +You can edit the `OPENSEARCH_PATH_CONF=/etc/opensearch` to change the config directory location. This variable is sourced from `/etc/default/opensearch`(Debian package) and `/etc/sysconfig/opensearch`(RPM package). + +If you set your customized `OPENSEARCH_PATH_CONF` variable, be aware that other default environment variables will not be loaded. + The demo configuration includes a number of settings for the security plugin that you should modify before using OpenSearch for a production workload. To learn more, see [Security]({{site.url}}{{site.baseurl}}/security-plugin/). From 305266b1dc158247ef81e70d8bff283c7302f449 Mon Sep 17 00:00:00 2001 From: Xue Zhou Date: Mon, 19 Jul 2021 23:57:13 -0700 Subject: [PATCH 002/167] =?UTF-8?q?=E2=80=9Cconfiguration-change=E2=80=9D?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Xue Zhou --- _im-plugin/ism/api.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/_im-plugin/ism/api.md b/_im-plugin/ism/api.md index 20646487..4b568ad6 100644 --- a/_im-plugin/ism/api.md +++ b/_im-plugin/ism/api.md @@ -160,6 +160,10 @@ POST _plugins/_ism/add/index_1 } ``` +If you use a wildcard `*` while adding a policy to an index, the ISM plugin interprets `*` as all indices, including system indices like `.opendistro-security`, which stores users, roles, and tenants. A delete action in your policy might accidentally delete all user roles and tenants in your cluster. +Don't use the broad `*` wildcard, and instead add a prefix, such as `my-logs*`, when specifying indices with the `_ism/add` API. +{: .warning } + --- From 8e3451358bfad4166528bc34cd5ba17d45010dad Mon Sep 17 00:00:00 2001 From: closingin <2735603+closingin@users.noreply.github.com> Date: Mon, 2 Aug 2021 11:49:32 +0200 Subject: [PATCH 003/167] feat: add a link to the developer guide Signed-off-by: closingin <2735603+closingin@users.noreply.github.com> --- _external_links/developer-guide.md | 7 +++++++ 1 file changed, 7 insertions(+) create mode 100644 _external_links/developer-guide.md diff --git a/_external_links/developer-guide.md b/_external_links/developer-guide.md new file mode 100644 index 00000000..17fb165c --- /dev/null +++ b/_external_links/developer-guide.md @@ -0,0 +1,7 @@ +--- +layout: default +title: Developer Guide +nav_order: 2 +permalink: /developer-guide/ +redirect_to: https://github.com/opensearch-project/OpenSearch-Dashboards/blob/main/DEVELOPER_GUIDE.md +--- From 0bf8624824ed4954e2ad3eda2464552c5aab3c5e Mon Sep 17 00:00:00 2001 From: aetter Date: Thu, 19 Aug 2021 12:56:53 -0700 Subject: [PATCH 004/167] Getting started content for Python --- _clients/java-rest-high-level.md | 2 +- _clients/python.md | 122 +++++++++++++++++++++++++++++++ 2 files changed, 123 insertions(+), 1 deletion(-) create mode 100644 _clients/python.md diff --git a/_clients/java-rest-high-level.md b/_clients/java-rest-high-level.md index 1dcf1563..3f7260cf 100644 --- a/_clients/java-rest-high-level.md +++ b/_clients/java-rest-high-level.md @@ -1,7 +1,7 @@ --- layout: default title: Java high-level REST client -nav_order: 97 +nav_order: 60 --- # Java high-level REST client diff --git a/_clients/python.md b/_clients/python.md new file mode 100644 index 00000000..1a5bf9b0 --- /dev/null +++ b/_clients/python.md @@ -0,0 +1,122 @@ +--- +layout: default +title: Python client +nav_order: 70 +--- + +# Python client + +The OpenSearch Python client provides a more natural syntax for interacting with your cluster. Rather than sending HTTP requests raw JSON bodies to a given URL, you can create an OpenSearch client for your cluster and call the client's built-in functions. + + +## Setup + +To add the client to your project, install it using pip: + +```bash +pip install +``` + +Then import it like any other module: + +```python +from opensearch import OpenSearch +``` + + +## Sample code + +```python +from opensearch import OpenSearch + +host = 'localhost' +port = 9200 +auth = ('admin', 'admin') # For testing only. Don't store credentials in code. +ca_certs_path = '/full/path/to/root-ca.pem' # Provide a CA bundle if you use intermediate CAs with your root CA + +# Optional client certificates if you don't want to use HTTP basic authentication. +# client_cert_path = '/full/path/to/client.pem' +# client_key_path = '/full/path/to/client-key.pem' + +# Create the client with SSL/TLS enabled, but hostname verification disabled. +client = OpenSearch( + hosts = [{'host': host, 'port': port}], + http_compress=True, # enables gzip compression for request bodies + http_auth = auth, + # client_cert = client_cert_path, + # client_key = client_key_path, + use_ssl = True, + verify_certs = True, + ssl_assert_hostname = False, + ssl_show_warn = False, + ca_certs = ca_certs_path +) + +# Create an index with non-default settings. +index_name = 'python-test-index3' +index_body = { + 'settings': { + 'index': { + 'number_of_shards': 4 + } + } +} + +response = client.indices.create(index_name, body=index_body) +print('\nCreating index:') +print(response) + +# Add a document to the index. +document = { + 'title': 'Moneyball', + 'director': 'Bennett Miller', + 'year': '2011' +} +id = '1' + +response = client.index( + index=index_name, + body=document, + id=id, + refresh=True +) + +print('\nAdding document:') +print(response) + +# Search for the document. +q = 'miller' +query = { + 'size': 5, + 'query': { + 'multi_match': { + 'query': q, + 'fields': ['title^2', 'director'] + } + } +} + +response = client.search( + body=query, + index=index_name +) +print('\nSearch results:') +print(response) + +# Delete the document. +response = client.delete( + index=index_name, + id=id +) + +print('\nDeleting document:') +print(response) + +# Delete the index. +response = client.indices.delete( + index=index_name +) + +print('\nDeleting index:') +print(response) +``` From 9ce5d95786a3baf50be225cdf6c44a3943ff2988 Mon Sep 17 00:00:00 2001 From: aetter Date: Thu, 19 Aug 2021 13:23:14 -0700 Subject: [PATCH 005/167] Clean up spacing --- _clients/python.md | 22 +++++++++++----------- 1 file changed, 11 insertions(+), 11 deletions(-) diff --git a/_clients/python.md b/_clients/python.md index 1a5bf9b0..0a44cfa9 100644 --- a/_clients/python.md +++ b/_clients/python.md @@ -32,7 +32,7 @@ from opensearch import OpenSearch host = 'localhost' port = 9200 auth = ('admin', 'admin') # For testing only. Don't store credentials in code. -ca_certs_path = '/full/path/to/root-ca.pem' # Provide a CA bundle if you use intermediate CAs with your root CA +ca_certs_path = '/full/path/to/root-ca.pem' # Provide a CA bundle if you use intermediate CAs with your root CA. # Optional client certificates if you don't want to use HTTP basic authentication. # client_cert_path = '/full/path/to/client.pem' @@ -41,7 +41,7 @@ ca_certs_path = '/full/path/to/root-ca.pem' # Provide a CA bundle if you use int # Create the client with SSL/TLS enabled, but hostname verification disabled. client = OpenSearch( hosts = [{'host': host, 'port': port}], - http_compress=True, # enables gzip compression for request bodies + http_compress = True, # enables gzip compression for request bodies http_auth = auth, # client_cert = client_cert_path, # client_key = client_key_path, @@ -75,10 +75,10 @@ document = { id = '1' response = client.index( - index=index_name, - body=document, - id=id, - refresh=True + index = index_name, + body = document, + id = id, + refresh = True ) print('\nAdding document:') @@ -97,16 +97,16 @@ query = { } response = client.search( - body=query, - index=index_name + body = query, + index = index_name ) print('\nSearch results:') print(response) # Delete the document. response = client.delete( - index=index_name, - id=id + index = index_name, + id = id ) print('\nDeleting document:') @@ -114,7 +114,7 @@ print(response) # Delete the index. response = client.indices.delete( - index=index_name + index = index_name ) print('\nDeleting index:') From 30facfe628124b75cf17d44c90e946a20b1ce8ca Mon Sep 17 00:00:00 2001 From: aetter Date: Thu, 19 Aug 2021 14:38:30 -0700 Subject: [PATCH 006/167] Typo --- _clients/python.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/_clients/python.md b/_clients/python.md index 0a44cfa9..879513ce 100644 --- a/_clients/python.md +++ b/_clients/python.md @@ -6,7 +6,7 @@ nav_order: 70 # Python client -The OpenSearch Python client provides a more natural syntax for interacting with your cluster. Rather than sending HTTP requests raw JSON bodies to a given URL, you can create an OpenSearch client for your cluster and call the client's built-in functions. +The OpenSearch Python client provides a more natural syntax for interacting with your cluster. Rather than sending HTTP requests with raw JSON bodies to a given URL, you can create an OpenSearch client for your cluster and call the client's built-in functions. ## Setup From f3a9bad35c582625d1ffdee3d717b63fbd86ed84 Mon Sep 17 00:00:00 2001 From: ict-one-nl Date: Wed, 25 Aug 2021 13:54:54 +0200 Subject: [PATCH 007/167] Use same attribute name as cluster page Simple fix, but because https://opensearch.org/docs/opensearch/cluster/ uses the node.attr.temp setting and this page uses the box_type setting a less experienced user like me easily makes a mistake (not comprehending the exact workings). Using the temp attribute here as well would have saved me a couple of hours and some grey hairs. --- _im-plugin/ism/policies.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/_im-plugin/ism/policies.md b/_im-plugin/ism/policies.md index e6bfa983..fe723d9a 100644 --- a/_im-plugin/ism/policies.md +++ b/_im-plugin/ism/policies.md @@ -347,7 +347,7 @@ Parameter | Description | Type | Required | Default ### allocation -Allocate the index to a node with a specific attribute. +Allocate the index to a node with a specific attribute set like this {{site.url}}{{site.baseurl}}/opensearch/cluster/#advanced-step-7-set-up-a-hot-warm-architecture For example, setting `require` to `warm` moves your data only to "warm" nodes. The `allocation` operation has the following parameters: @@ -363,7 +363,7 @@ Parameter | Description | Type | Required "actions": [ { "allocation": { - "require": { "box_type": "warm" } + "require": { "temp": "warm" } } } ] From 12ce7e5fea5c7c5499da834b36b2617afff79c30 Mon Sep 17 00:00:00 2001 From: ashwinkumar12345 Date: Wed, 25 Aug 2021 11:05:24 -0700 Subject: [PATCH 008/167] rough draft --- _clients/go.md | 93 ++++++++++++++++++++++++++++++++ _clients/java-rest-high-level.md | 2 +- 2 files changed, 94 insertions(+), 1 deletion(-) create mode 100644 _clients/go.md diff --git a/_clients/go.md b/_clients/go.md new file mode 100644 index 00000000..4273d8b9 --- /dev/null +++ b/_clients/go.md @@ -0,0 +1,93 @@ +--- +layout: default +title: Go client +nav_order: 80 +--- + +# Go client + +<> + +## Setup + +To add the client to your project, import it like any other module: + +```go +go mod init +go get github.com/opensearch-project/opensearch-go +``` + +### Sample response + +```go +go: downloading github.com/opensearch-project/opensearch-go v0.0.0-20210823214927-3567f157dece +go get: added github.com/opensearch-project/opensearch-go v0.0.0-20210823214927-3567f157dece +``` + +## Sample code + +Create a new file called main.go: + + +```go +package main + +import ( + "crypto/tls" + "fmt" + "github.com/opensearch-project/opensearch-go" + "log" + "net/http" +) + +func main () { + // Instantiate a new OpenSearch client object instance + + client, err := opensearch.NewClient(opensearch.Config{ + Transport: &http.Transport{ + TLSClientConfig: &tls.Config{InsecureSkipVerify: true}, + }, + Addresses: []string{"https://localhost:9200"}, + Username: "admin", // For testing only. Don't store credentials in code. + Password: "admin", + }) + +// ca_certs_path = '/full/path/to/root-ca.pem' # Provide a CA bundle if you use intermediate CAs with your root CA. Optional client certificates if you don't want to use HTTP basic authentication. +// client_cert_path = '/full/path/to/client.pem' +// client_key_path = '/full/path/to/client-key.pem' + + if err != nil { + fmt.Println("cannot initialize", err) + } + +// Have the client instance return a response + + log.Println(client.Info()) +} +``` + +```go +$ go run main.go + +2021/08/24 23:56:05 [200 OK] { + "name" : "c825aab1d9cc", + "cluster_name" : "docker-cluster", + "cluster_uuid" : "jsIDR0FTR5qXZr4XkZ-GlA", + "version" : { + "distribution" : "opensearch", + "number" : "1.0.0", + "build_type" : "tar", + "build_hash" : "34550c5b17124ddc59458ef774f6b43a086522e3", + "build_date" : "2021-07-02T23:22:21.383695Z", + "build_snapshot" : false, + "lucene_version" : "8.8.2", + "minimum_wire_compatibility_version" : "6.8.0", + "minimum_index_compatibility_version" : "6.0.0-beta1" + }, + "tagline" : "The OpenSearch Project: https://opensearch.org/" +} + +``` + +For all APIs - +https://github.com/opensearch-project/opensearch-go/tree/main/opensearchapi diff --git a/_clients/java-rest-high-level.md b/_clients/java-rest-high-level.md index a9ed5945..def97086 100644 --- a/_clients/java-rest-high-level.md +++ b/_clients/java-rest-high-level.md @@ -1,7 +1,7 @@ --- layout: default title: Java high-level REST client -nav_order: 97 +nav_order: 60 --- # Java high-level REST client From df42f777f9eac79b819f0469b756199a4c4a78dd Mon Sep 17 00:00:00 2001 From: ashwinkumar12345 Date: Wed, 25 Aug 2021 11:21:56 -0700 Subject: [PATCH 009/167] changed window size to shingle size --- _monitoring-plugins/ad/index.md | 8 +++----- 1 file changed, 3 insertions(+), 5 deletions(-) diff --git a/_monitoring-plugins/ad/index.md b/_monitoring-plugins/ad/index.md index 1874a37c..be661b80 100644 --- a/_monitoring-plugins/ad/index.md +++ b/_monitoring-plugins/ad/index.md @@ -79,13 +79,11 @@ This formula provides a good starting point, but make sure to test with a repres For example, for a cluster with 3 data nodes, each with 8G of JVM heap size, a maximum memory percentage of 10% (default), and the entity size of the detector as 1MB: the total number of unique entities supported is (8.096 * 10^9 * 0.1 / 1M ) * 3 = 2429. -#### Set a window size +#### Set a shingle size -Set the number of aggregation intervals from your data stream to consider in a detection window. It's best to choose this value based on your actual data to see which one leads to the best results for your use case. +Set the number of aggregation intervals from your data stream to consider in a detection window. It’s best to choose this value based on your actual data to see which one leads to the best results for your use case. -Based on experiments performed on a wide variety of one-dimensional data streams, we recommend using a window size between 1 and 16. The default window size is 8. If you set the category field for high cardinality, the default window size is 1. - -If you expect missing values in your data or if you want to base the anomalies on the current interval, choose 1. If your data is continuously ingested and you want to base the anomalies on multiple intervals, choose a larger window size. +The anomaly detector expects the shingle size to be in the range of 1 and 60. The default shingle size is 8. We recommend that you don't choose 1 unless you have two or more features. Smaller values might increase [recall](https://en.wikipedia.org/wiki/Precision_and_recall) but also false positives. #### Preview sample anomalies From 0376c4b6d9e73a523ab1e8e054fe3fcbd23b0c7d Mon Sep 17 00:00:00 2001 From: aetter Date: Wed, 25 Aug 2021 14:55:03 -0700 Subject: [PATCH 010/167] Fix link. --- _im-plugin/ism/policies.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/_im-plugin/ism/policies.md b/_im-plugin/ism/policies.md index fe723d9a..ec4bf737 100644 --- a/_im-plugin/ism/policies.md +++ b/_im-plugin/ism/policies.md @@ -347,7 +347,7 @@ Parameter | Description | Type | Required | Default ### allocation -Allocate the index to a node with a specific attribute set like this {{site.url}}{{site.baseurl}}/opensearch/cluster/#advanced-step-7-set-up-a-hot-warm-architecture +Allocate the index to a node with a specific attribute set [like this]({{site.url}}{{site.baseurl}}/opensearch/cluster/#advanced-step-7-set-up-a-hot-warm-architecture). For example, setting `require` to `warm` moves your data only to "warm" nodes. The `allocation` operation has the following parameters: From bdffb128d851007866e1d525c7a5fb82b7830bef Mon Sep 17 00:00:00 2001 From: aetter Date: Wed, 25 Aug 2021 15:17:51 -0700 Subject: [PATCH 011/167] Some redirects for OpenSearch Dashboards 1.0.0 --- _dashboards/index.md | 3 +++ _dashboards/maptiles.md | 4 ++++ _opensearch/index.md | 3 +++ 3 files changed, 10 insertions(+) diff --git a/_dashboards/index.md b/_dashboards/index.md index d4ac0e23..df5a9516 100644 --- a/_dashboards/index.md +++ b/_dashboards/index.md @@ -5,9 +5,12 @@ nav_order: 1 has_children: false has_toc: false redirect_from: + - /docs/opensearch-dashboards/ - /dashboards/ --- +{%- comment -%}The `/docs/opensearch-dashboards/` redirect is specifically to support the UI links in OpenSearch Dashboards 1.0.0.{%- endcomment -%} + # OpenSearch Dashboards OpenSearch Dashboards is the default visualization tool for data in OpenSearch. It also serves as a user interface for many of the OpenSearch plugins, including security, alerting, Index State Management, SQL, and more. diff --git a/_dashboards/maptiles.md b/_dashboards/maptiles.md index 1bbf27f6..f7a43046 100644 --- a/_dashboards/maptiles.md +++ b/_dashboards/maptiles.md @@ -2,8 +2,12 @@ layout: default title: WMS map server nav_order: 5 +redirect_from: + - /docs/opensearch-dashboards/maptiles/ --- +{%- comment -%}The `/docs/opensearch-dashboards/maptiles/` redirect is specifically to support the UI links in OpenSearch Dashboards 1.0.0.{%- endcomment -%} + # Configure WMS map server OpenSearch Dashboards includes default map tiles, but if you need more specialized maps, you can configure OpenSearch Dashboards to use a WMS map server: diff --git a/_opensearch/index.md b/_opensearch/index.md index dbafecf0..505faeec 100644 --- a/_opensearch/index.md +++ b/_opensearch/index.md @@ -5,9 +5,12 @@ nav_order: 1 has_children: false has_toc: false redirect_from: + - /docs/opensearch/ - /opensearch/ --- +{%- comment -%}The `/docs/opensearch/` redirect is specifically to support the UI links in OpenSearch Dashboards 1.0.0.{%- endcomment -%} + # Introduction to OpenSearch OpenSearch is a distributed search and analytics engine based on [Apache Lucene](https://lucene.apache.org/). After adding your data to OpenSearch, you can perform full-text searches on it with all of the features you might expect: search by field, search multiple indices, boost fields, rank results by score, sort results by field, and aggregate results. From 78621f98e3970c7505ab3890144173e293b7e41c Mon Sep 17 00:00:00 2001 From: ashwinkumar12345 Date: Wed, 25 Aug 2021 16:34:46 -0700 Subject: [PATCH 012/167] minor change --- _monitoring-plugins/ad/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/_monitoring-plugins/ad/index.md b/_monitoring-plugins/ad/index.md index be661b80..5cb67b7a 100644 --- a/_monitoring-plugins/ad/index.md +++ b/_monitoring-plugins/ad/index.md @@ -83,7 +83,7 @@ For example, for a cluster with 3 data nodes, each with 8G of JVM heap size, a m Set the number of aggregation intervals from your data stream to consider in a detection window. It’s best to choose this value based on your actual data to see which one leads to the best results for your use case. -The anomaly detector expects the shingle size to be in the range of 1 and 60. The default shingle size is 8. We recommend that you don't choose 1 unless you have two or more features. Smaller values might increase [recall](https://en.wikipedia.org/wiki/Precision_and_recall) but also false positives. +The anomaly detector expects the shingle size to be in the range of 1 and 60. The default shingle size is 8. We recommend that you don't choose 1 unless you have two or more features. Smaller values might increase [recall](https://en.wikipedia.org/wiki/Precision_and_recall) but also false positives. Larger values might be useful for ignoring noise in a signal. #### Preview sample anomalies From ac9acb3c62287e1403fc0ad7c29cf28c1ddaee8e Mon Sep 17 00:00:00 2001 From: aetter Date: Thu, 26 Aug 2021 09:15:50 -0700 Subject: [PATCH 013/167] Adds some statements around compatibility Should (hopefully) apply to all clients. --- _clients/index.md | 14 +++++++++++++- _clients/python.md | 2 ++ 2 files changed, 15 insertions(+), 1 deletion(-) diff --git a/_clients/index.md b/_clients/index.md index bdf2bf05..3880a3bb 100644 --- a/_clients/index.md +++ b/_clients/index.md @@ -9,6 +9,18 @@ redirect_from: # OpenSearch client compatibility +OpenSearch provides clients for several popular programming languages, with more coming. In general, clients are compatible with clusters running the same major version of OpenSearch (`major.minor.patch`). + +For example, a 1.0.0 client works with an OpenSearch 1.1.0 cluster, but might not support any non-breaking API changes in OpenSearch 1.1.0. A 1.2.0 client works with the same cluster, but might allow you to pass unsupported options in certain functions. We recommend using the same version for both, but if your tests pass after a cluster upgrade, you don't necessarily need to upgrade your clients immediately. + +* [OpenSearch Java client]({{site.url}}{{site.baseurl}}/clients/java/) +* [OpenSearch Python client]({{site.url}}{{site.baseurl}}/clients/python/) +* [OpenSearch JavaScript (Node.js) client]({{site.url}}{{site.baseurl}}/clients/nodejs/) +* [OpenSearch Go client]({{site.url}}{{site.baseurl}}/clients/golang/) + + +## Legacy clients + Most clients that work with Elasticsearch OSS 7.10.2 *should* work with OpenSearch, but the latest versions of those clients might include license or version checks that artificially break compatibility. This page includes recommendations around which versions of those clients to use for best compatibility with OpenSearch. Client | Recommended version @@ -18,7 +30,7 @@ Client | Recommended version [Python Elasticsearch client](https://pypi.org/project/elasticsearch/7.13.4/) | 7.13.4 [Elasticsearch Node.js client](https://www.npmjs.com/package/@elastic/elasticsearch/v/7.13.0) | 7.13.0 -Clients exist for a wide variety of languages, so if you test a client and verify that it works, please [submit a PR](https://github.com/opensearch-project/documentation-website/pulls) and add it to this table. +If you test a legacy client and verify that it works, please [submit a PR](https://github.com/opensearch-project/documentation-website/pulls) and add it to this table. {% comment %} diff --git a/_clients/python.md b/_clients/python.md index 879513ce..f2abffe5 100644 --- a/_clients/python.md +++ b/_clients/python.md @@ -23,6 +23,8 @@ Then import it like any other module: from opensearch import OpenSearch ``` +If you prefer to add the client manually or just want to examine the source code, see [opensearch-py on GitHub](https://github.com/opensearch-project/opensearch-py). + ## Sample code From 9a2e6ed0284c65bf0ac2620feba7d8dc4d15c3b4 Mon Sep 17 00:00:00 2001 From: ashwinkumar12345 Date: Thu, 26 Aug 2021 11:33:21 -0700 Subject: [PATCH 014/167] spacing --- _clients/go.md | 132 ++++++++++++++++++++++++++++++------------------- 1 file changed, 82 insertions(+), 50 deletions(-) diff --git a/_clients/go.md b/_clients/go.md index 4273d8b9..d9bc751a 100644 --- a/_clients/go.md +++ b/_clients/go.md @@ -6,7 +6,8 @@ nav_order: 80 # Go client -<> +The OpenSearch Go client lets you programmatically interact with data in your OpenSearch cluster as part of your Go application. + ## Setup @@ -17,77 +18,108 @@ go mod init go get github.com/opensearch-project/opensearch-go ``` -### Sample response - -```go -go: downloading github.com/opensearch-project/opensearch-go v0.0.0-20210823214927-3567f157dece -go get: added github.com/opensearch-project/opensearch-go v0.0.0-20210823214927-3567f157dece -``` - ## Sample code -Create a new file called main.go: - - ```go package main import ( + "context" "crypto/tls" "fmt" - "github.com/opensearch-project/opensearch-go" - "log" + opensearch "github.com/opensearch-project/opensearch-go" + opensearchapi "github.com/opensearch-project/opensearch-go/opensearchapi" "net/http" + "strings" ) -func main () { - // Instantiate a new OpenSearch client object instance +const IndexName = "go-test-index1" +func main() { + + // Initialize the client with SSL/TLS enabled. client, err := opensearch.NewClient(opensearch.Config{ Transport: &http.Transport{ TLSClientConfig: &tls.Config{InsecureSkipVerify: true}, }, Addresses: []string{"https://localhost:9200"}, - Username: "admin", // For testing only. Don't store credentials in code. - Password: "admin", + Username: "admin", // For testing only. Don't store credentials in code. + Password: "admin", }) - -// ca_certs_path = '/full/path/to/root-ca.pem' # Provide a CA bundle if you use intermediate CAs with your root CA. Optional client certificates if you don't want to use HTTP basic authentication. -// client_cert_path = '/full/path/to/client.pem' -// client_key_path = '/full/path/to/client-key.pem' - if err != nil { fmt.Println("cannot initialize", err) } -// Have the client instance return a response - + // Print OpenSearch version information. log.Println(client.Info()) + + // Define a mapping. + mapping := strings.NewReader(`{ + 'settings': { + 'index': { + 'number_of_shards': 4 + } + } + }`) + + // Create an index with non-default settings. + res := opensearchapi.CreateRequest{ + Index: IndexName, + Body: mapping, + } + fmt.Println("creating index", res) + + // Add a document to the index. + document := strings.NewReader(`{ + "title": "Moneyball", + "director": "Bennett Miller", + "year": "2011" + }`) + + docId := "1" + req := opensearchapi.IndexRequest{ + Index: IndexName, + DocumentID: docId, + Body: document, + } + insertResponse, err := req.Do(context.Background(), client) + fmt.Println(insertResponse) + + // Search for the document. + content := strings.NewReader(`{ + "size": 5, + "query": { + "multi_match": { + "query": "miller", + "fields": ["title^2", "director"] + } + } + }`) + + search := opensearchapi.SearchRequest{ + Body: content, + } + + searchResponse, err := search.Do(context.Background(), client) + fmt.Println(searchResponse) + + // Delete the document. + delete := opensearchapi.DeleteRequest{ + Index: IndexName, + DocumentID: docId, + } + + deleteResponse, err := delete.Do(context.Background(), client) + fmt.Println("deleting document") + fmt.Println(deleteResponse) + + // Delete the index. + deleteIndex := opensearchapi.IndicesDeleteRequest{ + Index: []string{IndexName}, + } + + deleteIndexResponse, err := deleteIndex.Do(context.Background(), client) + fmt.Println("deleting index") + fmt.Println(deleteIndexResponse) } ``` - -```go -$ go run main.go - -2021/08/24 23:56:05 [200 OK] { - "name" : "c825aab1d9cc", - "cluster_name" : "docker-cluster", - "cluster_uuid" : "jsIDR0FTR5qXZr4XkZ-GlA", - "version" : { - "distribution" : "opensearch", - "number" : "1.0.0", - "build_type" : "tar", - "build_hash" : "34550c5b17124ddc59458ef774f6b43a086522e3", - "build_date" : "2021-07-02T23:22:21.383695Z", - "build_snapshot" : false, - "lucene_version" : "8.8.2", - "minimum_wire_compatibility_version" : "6.8.0", - "minimum_index_compatibility_version" : "6.0.0-beta1" - }, - "tagline" : "The OpenSearch Project: https://opensearch.org/" -} - -``` - -For all APIs - -https://github.com/opensearch-project/opensearch-go/tree/main/opensearchapi From bfc56f2f7fbf9cf97910483bddb9ca0286b640bc Mon Sep 17 00:00:00 2001 From: ashwinkumar12345 Date: Thu, 26 Aug 2021 11:39:32 -0700 Subject: [PATCH 015/167] incorporated feedback --- _clients/go.md | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/_clients/go.md b/_clients/go.md index d9bc751a..37c89e94 100644 --- a/_clients/go.md +++ b/_clients/go.md @@ -11,10 +11,15 @@ The OpenSearch Go client lets you programmatically interact with data in your Op ## Setup -To add the client to your project, import it like any other module: +If you're creating a new project: ```go go mod init +``` + +To add the client to your project, import it like any other module: + +```go go get github.com/opensearch-project/opensearch-go ``` From 1c4f81eb53185387b27afdd961b32739475a9478 Mon Sep 17 00:00:00 2001 From: ashwinkumar12345 Date: Thu, 26 Aug 2021 11:41:09 -0700 Subject: [PATCH 016/167] minor fix --- _clients/go.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/_clients/go.md b/_clients/go.md index 37c89e94..e77fc0dd 100644 --- a/_clients/go.md +++ b/_clients/go.md @@ -55,8 +55,8 @@ func main() { fmt.Println("cannot initialize", err) } - // Print OpenSearch version information. - log.Println(client.Info()) + // Print OpenSearch version information on console. + fmt.Println(client.Info()) // Define a mapping. mapping := strings.NewReader(`{ From c9728698934f57a36278d85314ab647407c06f90 Mon Sep 17 00:00:00 2001 From: aetter Date: Thu, 26 Aug 2021 11:50:46 -0700 Subject: [PATCH 017/167] Link to pip, because why not --- _clients/python.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/_clients/python.md b/_clients/python.md index f2abffe5..cdc7dc29 100644 --- a/_clients/python.md +++ b/_clients/python.md @@ -11,7 +11,7 @@ The OpenSearch Python client provides a more natural syntax for interacting with ## Setup -To add the client to your project, install it using pip: +To add the client to your project, install it using [pip](https://pip.pypa.io/): ```bash pip install From cea3ba7ce9450617dac23521bd1f2277931d89dd Mon Sep 17 00:00:00 2001 From: Liz Snyder Date: Thu, 26 Aug 2021 12:44:58 -0700 Subject: [PATCH 018/167] Getting started docs for javascript --- _clients/javascript.md | 141 +++++++++++++++++++++++++++++++++++++++++ 1 file changed, 141 insertions(+) create mode 100644 _clients/javascript.md diff --git a/_clients/javascript.md b/_clients/javascript.md new file mode 100644 index 00000000..60c1cba1 --- /dev/null +++ b/_clients/javascript.md @@ -0,0 +1,141 @@ +--- +layout: default +title: Javascript client +nav_order: 80 +--- + +# Javascript client + +The OpenSearch Javascript client provides a safer and easier way to interact with your OpenSearch cluster. Rather than using OpenSearch from the browser and potentially exposing your data to the public, you can build an OpenSearch client that takes care of sending requests to your cluster. + +The client contains a library of APIs that let you perform different operations on your cluster and return a standard response body. The example here demonstrates some basic operations like creating an index, adding documents, and searching your data. + + +## Setup + +To add the client to your project, install it from npm: + +```bash +npm install @opensearch/opensearch +``` + +If you prefer to add the client manually or just want to examine the source code, see [opensearch-js](https://github.com/opensearch-project/opensearch-js) on GitHub. + +Then require the client: + +```javascript +const { Client } = require('@opensearch/opensearch') +``` + + +## Sample code + +```javascript +'use strict'; + +var host = 'localhost'; +var protocol = 'https'; +var port = 9200; +var auth = 'admin:admin'; // For testing only. Don't store credentials in code. +var ca_certs_path = '/full/path/to/root-ca.pem'; + +// Optional client certificates if you don't want to use HTTP basic authentication. +// var client_cert_path = '/full/path/to/client.pem' +// var client_key_path = '/full/path/to/client-key.pem' + +// Create a client with SSL/TLS enabled. +var { Client } = require('@opensearch/opensearch'); +var fs = require('fs'); +var client = new Client({ + node: protocol + '://' + auth + '@' + host + ':' + port, + ssl: { + ca: fs.readFileSync(ca_certs_path), + // cert: fs.readFileSync(client_cert_path), + // key: fs.readFileSync(client_key_path) + } +}) + +async function search() { + + // Create an index with non-default settings. + var index_name = 'books' + var settings = { + 'settings': { + 'index': { + 'number_of_shards': 4, + 'number_of_replicas': 3 + } + } + } + + var response = await client.indices.create({ + index: index_name, + body: settings + }) + + console.log('Creating index:') + console.log(response.body) + + // Add a document to the index. + var document = { + 'title': 'The Outsider', + 'author': 'Stephen King', + 'year': '2018', + 'genre': 'Crime fiction' + } + + var id = '1' + + var response = await client.index({ + id: id, + index: index_name, + body: document + }) + + console.log('Adding document:') + console.log(response.body) + + // Force an index refresh so the subsequent search returns results. + client.indices.refresh({ + index: index_name + }) + + // Search for the document. + var query = { + 'query': { + 'match': { + 'title': { + 'query': 'The Outsider' + } + } + } + } + + var response = await client.search({ + index: index_name, + body: query + }) + + console.log('Search results:') + console.log(response.body.hits) + + // Delete the document. + var response = await client.delete({ + index: index_name, + id: id + }) + + console.log('Deleting document:') + console.log(response.body) + + // Delete the index. + var response = await client.indices.delete({ + index: index_name + }) + + console.log('Deleting index:') + console.log(response.body) +} + +search().catch(console.log) +``` From 4d39000cd3daa41336c031fbdf26566b2b8c25d1 Mon Sep 17 00:00:00 2001 From: Liz Snyder Date: Thu, 26 Aug 2021 12:51:04 -0700 Subject: [PATCH 019/167] Add command to install specific version --- _clients/javascript.md | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/_clients/javascript.md b/_clients/javascript.md index 60c1cba1..42a00f67 100644 --- a/_clients/javascript.md +++ b/_clients/javascript.md @@ -19,6 +19,12 @@ To add the client to your project, install it from npm: npm install @opensearch/opensearch ``` +To install a specific major version of the client, run the following command: + +```bash +npm install @opensearch/opensearch@ +``` + If you prefer to add the client manually or just want to examine the source code, see [opensearch-js](https://github.com/opensearch-project/opensearch-js) on GitHub. Then require the client: From 51d359ec4075a41e2bdb14567ea6fb1113f621fa Mon Sep 17 00:00:00 2001 From: Liz Snyder Date: Thu, 26 Aug 2021 13:34:19 -0700 Subject: [PATCH 020/167] Remove index refresh --- _clients/javascript.md | 8 ++------ 1 file changed, 2 insertions(+), 6 deletions(-) diff --git a/_clients/javascript.md b/_clients/javascript.md index 42a00f67..f6490863 100644 --- a/_clients/javascript.md +++ b/_clients/javascript.md @@ -95,17 +95,13 @@ async function search() { var response = await client.index({ id: id, index: index_name, - body: document + body: document, + refresh: true }) console.log('Adding document:') console.log(response.body) - // Force an index refresh so the subsequent search returns results. - client.indices.refresh({ - index: index_name - }) - // Search for the document. var query = { 'query': { From e210d7d217586d64f3421e80d9c4af892237b74c Mon Sep 17 00:00:00 2001 From: Liz Snyder Date: Thu, 26 Aug 2021 13:36:12 -0700 Subject: [PATCH 021/167] Fix nav order to not conflict with Go --- _clients/javascript.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/_clients/javascript.md b/_clients/javascript.md index f6490863..2c4946f4 100644 --- a/_clients/javascript.md +++ b/_clients/javascript.md @@ -1,7 +1,7 @@ --- layout: default title: Javascript client -nav_order: 80 +nav_order: 90 --- # Javascript client From 18d389187943d1a3002ac916a5f6741b7573c148 Mon Sep 17 00:00:00 2001 From: Liz Snyder Date: Thu, 26 Aug 2021 15:23:06 -0700 Subject: [PATCH 022/167] Specify how to turn off cert verification --- _clients/javascript.md | 1 + 1 file changed, 1 insertion(+) diff --git a/_clients/javascript.md b/_clients/javascript.md index 2c4946f4..55134c00 100644 --- a/_clients/javascript.md +++ b/_clients/javascript.md @@ -56,6 +56,7 @@ var client = new Client({ node: protocol + '://' + auth + '@' + host + ':' + port, ssl: { ca: fs.readFileSync(ca_certs_path), + // You can turn off certificate verification (rejectUnauthorized: false) if you're using self-signed certificates with a hostname mismatch. // cert: fs.readFileSync(client_cert_path), // key: fs.readFileSync(client_key_path) } From 36853b648465dd96ae24ac0b9d84c3c2b862da5f Mon Sep 17 00:00:00 2001 From: aetter Date: Fri, 27 Aug 2021 12:46:55 -0700 Subject: [PATCH 023/167] Update external link to Dashboards developer guide --- _external_links/developer-guide.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/_external_links/developer-guide.md b/_external_links/developer-guide.md index 17fb165c..5f07b6ae 100644 --- a/_external_links/developer-guide.md +++ b/_external_links/developer-guide.md @@ -1,7 +1,7 @@ --- layout: default -title: Developer Guide +title: Dashboards developer guide nav_order: 2 -permalink: /developer-guide/ +permalink: /dashboards-developer-guide/ redirect_to: https://github.com/opensearch-project/OpenSearch-Dashboards/blob/main/DEVELOPER_GUIDE.md --- From fbc0447bcdad8e2a83caa74153d3a46d3a5b280d Mon Sep 17 00:00:00 2001 From: ashwinkumar12345 Date: Fri, 27 Aug 2021 13:20:59 -0700 Subject: [PATCH 024/167] added more context --- _clients/go.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/_clients/go.md b/_clients/go.md index e77fc0dd..06b6e533 100644 --- a/_clients/go.md +++ b/_clients/go.md @@ -25,6 +25,8 @@ go get github.com/opensearch-project/opensearch-go ## Sample code +This sample code creates a client, adds an index with non-default settings, inserts a document, searches for the document, deletes the document, and finally deletes the index: + ```go package main From 7aed3bfbf1a1af94a0c21795bbc2165d9df14c09 Mon Sep 17 00:00:00 2001 From: ashwinkumar12345 Date: Fri, 27 Aug 2021 14:00:26 -0700 Subject: [PATCH 025/167] updated code to check error message --- _clients/go.md | 173 ++++++++++++++++++++++++++----------------------- 1 file changed, 93 insertions(+), 80 deletions(-) diff --git a/_clients/go.md b/_clients/go.md index 06b6e533..6db260ac 100644 --- a/_clients/go.md +++ b/_clients/go.md @@ -29,104 +29,117 @@ This sample code creates a client, adds an index with non-default settings, inse ```go package main - import ( - "context" - "crypto/tls" - "fmt" - opensearch "github.com/opensearch-project/opensearch-go" - opensearchapi "github.com/opensearch-project/opensearch-go/opensearchapi" - "net/http" - "strings" + "os" + "context" + "crypto/tls" + "fmt" + opensearch "github.com/opensearch-project/opensearch-go" + opensearchapi "github.com/opensearch-project/opensearch-go/opensearchapi" + "net/http" + "strings" ) - const IndexName = "go-test-index1" - func main() { + // Initialize the client with SSL/TLS enabled. + client, err := opensearch.NewClient(opensearch.Config{ + Transport: &http.Transport{ + TLSClientConfig: &tls.Config{InsecureSkipVerify: true}, + }, + Addresses: []string{"https://localhost:9200"}, + Username: "admin", // For testing only. Don't store credentials in code. + Password: "admin", + }) + if err != nil { + fmt.Println("cannot initialize", err) + os.Exit(1) + } - // Initialize the client with SSL/TLS enabled. - client, err := opensearch.NewClient(opensearch.Config{ - Transport: &http.Transport{ - TLSClientConfig: &tls.Config{InsecureSkipVerify: true}, - }, - Addresses: []string{"https://localhost:9200"}, - Username: "admin", // For testing only. Don't store credentials in code. - Password: "admin", - }) - if err != nil { - fmt.Println("cannot initialize", err) - } + // Print OpenSearch version information on console. + fmt.Println(client.Info()) - // Print OpenSearch version information on console. - fmt.Println(client.Info()) - - // Define a mapping. - mapping := strings.NewReader(`{ - 'settings': { - 'index': { + // Define index mapping. + mapping := strings.NewReader(`{ + 'settings': { + 'index': { 'number_of_shards': 4 } } - }`) + }`) - // Create an index with non-default settings. - res := opensearchapi.CreateRequest{ - Index: IndexName, - Body: mapping, - } - fmt.Println("creating index", res) + // Create an index with non-default settings. + res := opensearchapi.CreateRequest{ + Index: IndexName, + Body: mapping, + } + fmt.Println("creating index", res) - // Add a document to the index. - document := strings.NewReader(`{ - "title": "Moneyball", - "director": "Bennett Miller", - "year": "2011" - }`) + // Add a document to the index. + document := strings.NewReader(`{ + "title": "Moneyball", + "director": "Bennett Miller", + "year": "2011" + }`) - docId := "1" - req := opensearchapi.IndexRequest{ - Index: IndexName, - DocumentID: docId, - Body: document, - } - insertResponse, err := req.Do(context.Background(), client) - fmt.Println(insertResponse) + docId := "1" + req := opensearchapi.IndexRequest{ + Index: IndexName, + DocumentID: docId, + Body: document, + } + insertResponse, err := req.Do(context.Background(), client) + if err != nil { + fmt.Println("failed to insert document ", err) + os.Exit(1) + } + fmt.Println(insertResponse) - // Search for the document. - content := strings.NewReader(`{ - "size": 5, - "query": { - "multi_match": { - "query": "miller", - "fields": ["title^2", "director"] - } - } - }`) + // Search for the document. + content := strings.NewReader(`{ + "size": 5, + "query": { + "multi_match": { + "query": "miller", + "fields": ["title^2", "director"] + } + } + }`) - search := opensearchapi.SearchRequest{ - Body: content, - } + search := opensearchapi.SearchRequest{ + Body: content, + } - searchResponse, err := search.Do(context.Background(), client) - fmt.Println(searchResponse) + searchResponse, err := search.Do(context.Background(), client) + if err != nil { + fmt.Println("failed to search document ", err) + os.Exit(1) + } + fmt.Println(searchResponse) - // Delete the document. - delete := opensearchapi.DeleteRequest{ - Index: IndexName, - DocumentID: docId, - } + // Delete the document. + delete := opensearchapi.DeleteRequest{ + Index: IndexName, + DocumentID: docId, + } - deleteResponse, err := delete.Do(context.Background(), client) - fmt.Println("deleting document") - fmt.Println(deleteResponse) + deleteResponse, err := delete.Do(context.Background(), client) + if err != nil { + fmt.Println("failed to delete document ", err) + os.Exit(1) + } + fmt.Println("deleting document") + fmt.Println(deleteResponse) - // Delete the index. - deleteIndex := opensearchapi.IndicesDeleteRequest{ - Index: []string{IndexName}, - } + // Delete previously created index. + deleteIndex := opensearchapi.IndicesDeleteRequest{ + Index: []string{IndexName}, + } - deleteIndexResponse, err := deleteIndex.Do(context.Background(), client) - fmt.Println("deleting index") - fmt.Println(deleteIndexResponse) + deleteIndexResponse, err := deleteIndex.Do(context.Background(), client) + if err != nil { + fmt.Println("failed to delete index ", err) + os.Exit(1) + } + fmt.Println("deleting index", deleteIndexResponse) } ``` From 17f91f09a398aae31174147b14efbd828e0ec839 Mon Sep 17 00:00:00 2001 From: keithhc2 Date: Mon, 30 Aug 2021 11:29:19 -0700 Subject: [PATCH 026/167] Language tweaks everywhere --- .../rest-api/document-apis/delete-by-query.md | 20 ++++++------- .../rest-api/document-apis/delete-document.md | 4 +-- .../rest-api/document-apis/get-documents.md | 4 +-- .../rest-api/document-apis/index-document.md | 10 +++---- .../rest-api/document-apis/multi-get.md | 14 ++++----- .../rest-api/document-apis/update-by-query.md | 30 +++++++++---------- .../rest-api/document-apis/update-document.md | 14 ++++----- 7 files changed, 46 insertions(+), 50 deletions(-) diff --git a/_opensearch/rest-api/document-apis/delete-by-query.md b/_opensearch/rest-api/document-apis/delete-by-query.md index b9c17308..de717005 100644 --- a/_opensearch/rest-api/document-apis/delete-by-query.md +++ b/_opensearch/rest-api/document-apis/delete-by-query.md @@ -37,7 +37,8 @@ All URL parameters are optional. Parameter | Type | Description :--- | :--- | :--- | :--- -<index> | String | Name of the data streams, indices, or aliases to delete from. Supports wildcards. If left blank, OpenSearch searches all indices. +<index> | String | Name or list of the data streams, indices, or aliases to delete from. Supports wildcards. If left blank, OpenSearch searches all indices. +allow_no_indices - Whether to ignore wildcards that don’t match any indices. Default is `true`. allow_no_indices | Boolean | False indicates to OpenSearch the request should return an error if any wildcard expression or index alias targets only missing or closed indices. Default is true. analyzer | String | The analyzer to use in the query string. analyze_wildcard | Boolean | Specifies whether to analyze wildcard and prefix queries. Default is false. @@ -47,19 +48,18 @@ df | String | The default field in case a field prefix is not provided in the qu expand_wildcards | String | Specifies the type of index that wildcard expressions can match. Supports comma-separated values. Valid values are `all` (match any index), `open` (match open, non-hidden indices), `closed` (match closed, non-hidden indices), `hidden` (match hidden indices), and `none` (deny wildcard expressions). Default is `open`. from | Integer | The starting index to search from. Default is 0. ignore_unavailable | Boolean | Specifies whether to include missing or closed indices in the response. Default is false. -lenient | Boolean | Specifies whether OpenSearch should ignore format-based query failures (for example, querying a text field for an integer). Default is false. -max_docs | Integer | Maximum amount of documents the operation should process. Default is all documents. -preference | String | Specifies the shard or node OpenSearch should perform the operation on. -q | String | Query in the Lucene query string syntax. -request_cache | Boolean | Specifies whether OpenSearch should use the request cache for the request. Default is whether it's enabled in the index's settings. -refresh | Boolean | Specifies whether OpenSearch should refresh all of the shards involved in the delete request once the operation finishes. Default is false. +lenient | Boolean | Specifies whether OpenSearch should accept requests if queries have format errors (for example, querying a text field for an integer). Default is false. +max_docs | Integer | How many documents the delete by query operation should process at most. Default is all documents. +preference | String | Specifies which shard or node OpenSearch should perform the delete by query operation on. +q | String | Lucene query string's query. +request_cache | Boolean | Specifies whether OpenSearch should use the request cache. Default is whether it’s enabled in the index’s settings. +refresh | Boolean | If true, OpenSearch refreshes shards to make the delete by query operation available to search results. Valid options are `true`, `false`, and `wait_for`, which tells OpenSearch to wait for a refresh before executing the operation. Default is `false`. requests_per_second | Integer | Specifies the request's throttling in sub-requests per second. Default is -1, which means no throttling. routing | String | Value used to route the operation to a specific shard. scroll | Time | Amount of time the search context should be open. -scroll_size | Integer | Size of the scroll request of the operation. Default is 1000. +scroll_size | Integer | Size of the operation's scroll requests. Default is 1000. search_type | String | Whether OpenSearch should use global term and document frequencies calculating revelance scores. Valid choices are `query_then_fetch` and `dfs_query_then_fetch`. `query_then_fetch` scores documents using local term and document frequencies for the shard. It’s usually faster but less accurate. `dfs_query_then_fetch` scores documents using global term and document frequencies across all shards. It’s usually slower but more accurate. Default is `query_then_fetch`. -search_timeout | Time | Amount of time until timeout for the search request. Default is no timeout. -slices | Integer | Number of sub-tasks OpenSearch should divide this task into. Default is 1, which means OpenSearch should not divide this task. +search_timeout | Time | How long to wait until OpenSearch deems the request timed out. Default is no timeout. sort | String | A comma-separated list of <field> : <direction> pairs to sort by. _source | String | Specifies whether to include the `_source` field in the response. _source_excludes | String | A comma-separated list of source fields to exclude from the response. diff --git a/_opensearch/rest-api/document-apis/delete-document.md b/_opensearch/rest-api/document-apis/delete-document.md index 0d56a3ec..f67cf280 100644 --- a/_opensearch/rest-api/document-apis/delete-document.md +++ b/_opensearch/rest-api/document-apis/delete-document.md @@ -30,9 +30,9 @@ Parameter | Type | Description | Required <_id> | String | The ID of the document to delete. | Yes if_seq_no | Integer | Only perform the delete operation if the document's version number matches the specified number. | No if_primary_term | Integer | Only perform the delete operation if the document has the specified primary term. | No -refresh | Enum | If true, OpenSearch refreshes shards to make the operation visible to searching. Valid options are `true`, `false`, and `wait_for`, which tells OpenSearch to wait for a refresh before executing the operation. Default is false. | No +refresh | Enum | If true, OpenSearch refreshes shards to make the delete operation available to search results. Valid options are `true`, `false`, and `wait_for`, which tells OpenSearch to wait for a refresh before executing the operation. Default is `false`. | No routing | String | Value used to route the operation to a specific shard. | No -timeout | Time | How long to wait for a response from the cluster. | No +timeout | Time | How long to wait for a response from the cluster. Default is `1m`. | No version | Integer | The version of the document to delete, which must match the last updated version of the document. | No 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 version). For example, to delete version 3 of a document, use `/_doc/1?version=3&version_type=external`. | No wait_for_active_shards | String | The number of active shards that must be available before OpenSearch processes the delete 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 operation to succeed. | No diff --git a/_opensearch/rest-api/document-apis/get-documents.md b/_opensearch/rest-api/document-apis/get-documents.md index 931e89a1..896e1717 100644 --- a/_opensearch/rest-api/document-apis/get-documents.md +++ b/_opensearch/rest-api/document-apis/get-documents.md @@ -35,9 +35,9 @@ 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. +refresh | Boolean | If true, OpenSearch refreshes shards to make the get operation available to search results. Valid options are `true`, `false`, and `wait_for`, which tells OpenSearch to wait for a refresh before executing the operation. 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. +stored_fields | Boolean | Whether the get operation should retrieve fields stored in the index. 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. diff --git a/_opensearch/rest-api/document-apis/index-document.md b/_opensearch/rest-api/document-apis/index-document.md index 2317e308..d83ba319 100644 --- a/_opensearch/rest-api/document-apis/index-document.md +++ b/_opensearch/rest-api/document-apis/index-document.md @@ -39,11 +39,11 @@ Parameter | Type | Description | Required :--- | :--- | :--- | :--- <index> | String | Name of the index. | Yes <_id> | String | A unique identifier to attach to the document. To automatically generate an ID, use `POST /doc` in your request instead of PUT. | No -if_seq_no | Integer | Only perform the operation if the document has the specified sequence number. | No -if_primary_term | Integer | Only perform the operation if the document has the specified primary term. | No +if_seq_no | Integer | Only perform the index operation if the document has the specified sequence number. | No +if_primary_term | Integer | Only perform the index operation if the document has the specified primary term.| No op_type | Enum | Specifies the type of operation to complete with the document. Valid values are `create` (create the index if it doesn't exist) and `index`. If a document ID is included in the request, then the default is `index`. Otherwise, the default is `create`. | No -pipeline | String | ID used to route the indexing operation to a certain pipeline. | No -routing | String | Value used to assign operations to specific shards. | No +pipeline | String | Route the index operation to a certain pipeline. | No +routing | String | value used to assign the index operation to a specific shard. | No timeout | Time | How long to wait for a response from the cluster. Default is `1m`. | No version | Integer | The document's version number. | No version_type | Enum | Assigns a specific type to the document. Valid 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 version). For example, to index version 3 of a document, use `/_doc/1?version=3&version_type=external`. | No @@ -86,7 +86,7 @@ _index | The name of the index. _type | The document's type. OpenSearch supports only one type, which is `_doc`. _id | The document's ID. _version | The document's version. -_result | The result of the index operation. +result | The result of the index operation. _shards | Detailed information about the cluster's shards. total | The total number of shards. successful | The number of shards OpenSearch succssfully added the document to. diff --git a/_opensearch/rest-api/document-apis/multi-get.md b/_opensearch/rest-api/document-apis/multi-get.md index c294a669..3890e4a5 100644 --- a/_opensearch/rest-api/document-apis/multi-get.md +++ b/_opensearch/rest-api/document-apis/multi-get.md @@ -3,12 +3,12 @@ layout: default title: Multi-get document parent: Document APIs grand_parent: REST API reference -nav_order: 25 +nav_order: 30 --- # Multi-get documents - -Introduced 1.0 {: .label .label-purple } +Introduced 1.0 +{: .label .label-purple } The multi-get operation allows you to execute multiple GET operations in one request, so you can get back all documents that match your criteria. @@ -69,11 +69,11 @@ All multi-get URL parameters are optional. Parameter | Type | Description :--- | :--- | :--- | :--- <index> | String | Name of the index to retrieve documents from. -preference | String | The node or shard that OpenSearch should perform the operation on. Default is random. +preference | String | Specifies the nodes or shards OpenSearch should execute the multi-get operation on. Default is random. 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`. +refresh | Boolean | If true, OpenSearch refreshes shards to make the multi-get operation available to search results. Valid options are `true`, `false`, and `wait_for`, which tells OpenSearch to wait for a refresh before executing the operation. Default is `false`. +routing | String | Value used to route the multi-get operation to a specific shard. +stored_fields | Boolean | Specifies whether OpenSearch should retrieve documents fields from the index instead of the document's `_source`. Default is `false`. _source | String | Whether to include the `_source` field in the query response. 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. diff --git a/_opensearch/rest-api/document-apis/update-by-query.md b/_opensearch/rest-api/document-apis/update-by-query.md index 6b3dece2..f6d32d9e 100644 --- a/_opensearch/rest-api/document-apis/update-by-query.md +++ b/_opensearch/rest-api/document-apis/update-by-query.md @@ -44,31 +44,31 @@ All URL parameters are optional. Parameter | Type | Description :--- | :--- | :--- | :--- -<target-index> | String | Comma-separated list of indices to update. To update all indices, use * or omit this parameter. -allow_no_indices | String | If false, the request returns an error if wildcard expressions match closed or missing indices. Default is true. +<index> | String | Comma-separated list of indices to update. To update all indices, use * or omit this parameter. +allow_no_indices | String | Whether to ignore wildcards that don’t match any indices. Default is true. analyzer | String | Analyzer to use in the query string. -analyze_wildcard | Boolean | Whether the operation should include wildcard and prefix queries in the analysis. Default is false. -conflicts | String | Specifies whether the operation should continue if the request runs into version conflicts. Valid options are `abort` and `proceed`. Default is `abort`. -default_operator | String | The default operator the string query should use. Valid options are `AND` and `OR`. Default is `OR`. -df | String | The default field when the query string does not have a field prefix. +analyze_wildcard | Boolean | Whether the update operation should include wildcard and prefix queries in the analysis. Default is false. +conflicts | String | Indicates to OpenSearch what should happen if the update by query operation runs into a version conflict. Valid options are `abort` and `proceed`. Default is `abort`. +default_operator | String | Indicates whether the default operator for a string query should be `AND` or `OR`. Default is `OR`. +df | String | The default field if a field prefix is not provided in the query string. expand_wildcards | String | Specifies the type of index that wildcard expressions can match. Supports comma-separated values. Valid values are `all` (match any index), `open` (match open, non-hidden indices), `closed` (match closed, non-hidden indices), `hidden` (match hidden indices), and `none` (deny wildcard expressions). Default is `open`. from | Integer | The starting index to search from. Default is 0. ignore_unavailable | Boolean | Whether to exclude missing or closed indices in the response. Default is false. -lenient | Boolean | Whether OpenSearch should ignore format-based query failures (for example, querying an integer field for a string). Default is false. -max_docs | Integer | Maximum number of documents the request should process. Default is all documents. +lenient | Boolean | Specifies whether OpenSearch should accept requests if queries have format errors (for example, querying a text field for an integer). Default is false. +max_docs | Integer | How many documents the update by query operation should process at most. Default is all documents. pipeline | String | ID of the pipeline to use to process documents. -preference | String | The node or shard OpenSearch should perform the operation on. -q | String | Query in the Lucene query string syntax. -request_cache | Boolean | Whether OpenSearch should use the request cache for the operation. Default is whether it's enabled in the index's settings. -refresh | Boolean | Specifies whether OpenSearch should refresh shards involved in the operation to make the operation visible to searching. +preference | String | Specifies which shard or node OpenSearch should perform the update by query operation on. +q | String | Lucene query string's query. +request_cache | Boolean | Specifies whether OpenSearch should use the request cache. Default is whether it’s enabled in the index’s settings. +refresh | Boolean | If true, OpenSearch refreshes shards to make the update by query operation available to search results. Valid options are `true`, `false`, and `wait_for`, which tells OpenSearch to wait for a refresh before executing the operation. Default is `false`. requests_per_second | Integer | Specifies the request's throttling in sub-requests per second. Default is -1, which means no throttling. -routing | String | Value used to route the operation to a specific shard. +routing | String | Value used to route the update by query operation to a specific shard. scroll | Time | How long to keep the search context open. scroll_size | Integer | Size of the operation's scroll request. Default is 1000. search_type | String | Whether OpenSearch should use global term and document frequencies calculating revelance scores. Valid choices are `query_then_fetch` and `dfs_query_then_fetch`. `query_then_fetch` scores documents using local term and document frequencies for the shard. It’s usually faster but less accurate. `dfs_query_then_fetch` scores documents using global term and document frequencies across all shards. It’s usually slower but more accurate. Default is `query_then_fetch`. -search_timeout | Time | Amount of time until timeout for the search request. Default is no timeout. +search_timeout | Time | How long to wait until OpenSearch deems the request timed out. Default is no timeout. slices | Integer | Number of sub-tasks OpenSearch should divide this task into. Default is 1, which means OpenSearch should not divide this task. -sort | String | A comma-separated list of <field> : <direction> pairs to sort by. +sort | List | A comma-separated list of <field> : <direction> pairs to sort by. _source | String | Whether to include the `_source` field in the response. _source_excludes | String | A comma-separated list of source fields to exclude from the response. _source_includes | String | A comma-separated list of source fields to include in the response. diff --git a/_opensearch/rest-api/document-apis/update-document.md b/_opensearch/rest-api/document-apis/update-document.md index 23b06773..d0144f62 100644 --- a/_opensearch/rest-api/document-apis/update-document.md +++ b/_opensearch/rest-api/document-apis/update-document.md @@ -17,7 +17,7 @@ POST /sample-index1/_update/1 { "doc": { "first_name" : "Bruce", - "last_name" : "Wayne" + "last_name" : "Wayne", } } ``` @@ -28,11 +28,7 @@ POST /sample-index1/_update/1 POST /test-index1/_update/1 { "script" : { - "source": "ctx._source.oldValue += params.newValue", - "lang": "painless", - "params" : { - "newValue" : 10 - } + "source": "ctx._source.secret_identity = \"Batman\"", } } ``` @@ -50,12 +46,12 @@ Parameter | Type | Description | Required <index-name> | String | Name of the index. | Yes <_id> | String | The ID of the document to update. | Yes if_seq_no | Integer | Only perform the delete operation if the document's version number matches the specified number. | No -if_primary_term | Integer | Only perform the delete operation if the document has the specified primary term. | No +if_primary_term | Integer | Perform the update operation if the document has the specified primary term. | No lang | String | Language of the script. Default is `painless`. | No require_alias | Boolean | Specifies whether the destination must be an index alias. Default is false. | No -refresh | Enum | If true, OpenSearch refreshes shards to make the operation visible to searching. Valid options are `true`, `false`, and `wait_for`, which tells OpenSearch to wait for a refresh before executing the operation. Default is false. | No +refresh | Enum | If true, OpenSearch refreshes shards to make the operation visible to searching. Valid options are `true`, `false`, and `wait_for`, which tells OpenSearch to wait for a refresh before executing the operation. Default is `false`. | No retry_on_conflict | Integer | The amount of times OpenSearch should retry the operation if there's a document conflict. Default is 0. | No -routing | String | Value used to route the operation to a specific shard. | No +routing | String | Value to route the update operation to a specific shard. | No _source | List | Whether to include the `_source` field in the response body. Default is true. | No _source_excludes | List | A comma-separated list of source fields to exclude in the query response. | No _source_includes | List | A comma-separated list of source fields to include in the query response. | No From d941cb6ad7d7a66453c0bfe21dbdfba6369ad122 Mon Sep 17 00:00:00 2001 From: keithhc2 Date: Mon, 30 Aug 2021 11:32:24 -0700 Subject: [PATCH 027/167] Fixed typos --- .../rest-api/document-apis/delete-by-query.md | 2 +- .../rest-api/document-apis/delete-document.md | 4 +- _opensearch/rest-api/document-apis/reindex.md | 50 +++++++++++++++++++ .../rest-api/document-apis/update-document.md | 8 +-- 4 files changed, 57 insertions(+), 7 deletions(-) create mode 100644 _opensearch/rest-api/document-apis/reindex.md diff --git a/_opensearch/rest-api/document-apis/delete-by-query.md b/_opensearch/rest-api/document-apis/delete-by-query.md index de717005..adc13c79 100644 --- a/_opensearch/rest-api/document-apis/delete-by-query.md +++ b/_opensearch/rest-api/document-apis/delete-by-query.md @@ -28,7 +28,7 @@ POST sample-index1/_delete_by_query ## Path and HTTP methods ``` -POST /_delete_by_query +POST /_delete_by_query ``` ## URL parameters diff --git a/_opensearch/rest-api/document-apis/delete-document.md b/_opensearch/rest-api/document-apis/delete-document.md index f67cf280..a1723e0d 100644 --- a/_opensearch/rest-api/document-apis/delete-document.md +++ b/_opensearch/rest-api/document-apis/delete-document.md @@ -19,14 +19,14 @@ DELETE /sample-index1/_doc/1 ## Path and HTTP methods ``` -DELETE //_doc/<_id> +DELETE //_doc/<_id> ``` ## URL parameters Parameter | Type | Description | Required :--- | :--- | :--- | :--- -<index-name> | String | The index to delete from. | Yes +<index> | String | The index to delete from. | Yes <_id> | String | The ID of the document to delete. | Yes if_seq_no | Integer | Only perform the delete operation if the document's version number matches the specified number. | No if_primary_term | Integer | Only perform the delete operation if the document has the specified primary term. | No diff --git a/_opensearch/rest-api/document-apis/reindex.md b/_opensearch/rest-api/document-apis/reindex.md new file mode 100644 index 00000000..c2d45603 --- /dev/null +++ b/_opensearch/rest-api/document-apis/reindex.md @@ -0,0 +1,50 @@ +--- +layout: default +title: Reindex +parent: Document APIs +grand_parent: REST API reference +nav_order: 60 +--- + +# Reindex +Introduced 1.0 +{: .label .label-purple} + +You can use the `reindex` operation to copy every document or a subset of documents in your index into another index. + +## Example + +```json + +``` + +## Path and HTTP methods + +``` + +``` + +## URL parameters + + +Parameter | Type | Description | Required +:--- | :--- | :--- | :--- + + +## Request body + +Your request body must contain the information you want to index. + +```json + +``` + +## Response +```json + +``` + +## Response body fields + +Field | Description +:--- | :--- diff --git a/_opensearch/rest-api/document-apis/update-document.md b/_opensearch/rest-api/document-apis/update-document.md index d0144f62..68dab500 100644 --- a/_opensearch/rest-api/document-apis/update-document.md +++ b/_opensearch/rest-api/document-apis/update-document.md @@ -17,7 +17,7 @@ POST /sample-index1/_update/1 { "doc": { "first_name" : "Bruce", - "last_name" : "Wayne", + "last_name" : "Wayne" } } ``` @@ -28,7 +28,7 @@ POST /sample-index1/_update/1 POST /test-index1/_update/1 { "script" : { - "source": "ctx._source.secret_identity = \"Batman\"", + "source": "ctx._source.secret_identity = \"Batman\"" } } ``` @@ -36,14 +36,14 @@ POST /test-index1/_update/1 ## Path and HTTP methods ``` -POST //_update/<_id> +POST //_update/<_id> ``` ## URL parameters Parameter | Type | Description | Required :--- | :--- | :--- | :--- -<index-name> | String | Name of the index. | Yes +<index> | String | Name of the index. | Yes <_id> | String | The ID of the document to update. | Yes if_seq_no | Integer | Only perform the delete operation if the document's version number matches the specified number. | No if_primary_term | Integer | Perform the update operation if the document has the specified primary term. | No From edd9d2e31384a52817a528620dccc5ea984859e0 Mon Sep 17 00:00:00 2001 From: keithhc2 Date: Mon, 30 Aug 2021 11:34:01 -0700 Subject: [PATCH 028/167] Fixed even more typos --- _opensearch/rest-api/document-apis/delete-by-query.md | 2 +- _opensearch/rest-api/document-apis/multi-get.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/_opensearch/rest-api/document-apis/delete-by-query.md b/_opensearch/rest-api/document-apis/delete-by-query.md index adc13c79..47a53f62 100644 --- a/_opensearch/rest-api/document-apis/delete-by-query.md +++ b/_opensearch/rest-api/document-apis/delete-by-query.md @@ -3,7 +3,7 @@ layout: default title: Delete by query parent: Document APIs grand_parent: REST API reference -nav_order: 25 +nav_order: 30 --- # Delete by query diff --git a/_opensearch/rest-api/document-apis/multi-get.md b/_opensearch/rest-api/document-apis/multi-get.md index 3890e4a5..1e23b124 100644 --- a/_opensearch/rest-api/document-apis/multi-get.md +++ b/_opensearch/rest-api/document-apis/multi-get.md @@ -3,7 +3,7 @@ layout: default title: Multi-get document parent: Document APIs grand_parent: REST API reference -nav_order: 30 +nav_order: 25 --- # Multi-get documents From 5ddabb88bd14dbdfabd984f72e657dd94fe6b24f Mon Sep 17 00:00:00 2001 From: keithhc2 Date: Mon, 30 Aug 2021 11:35:11 -0700 Subject: [PATCH 029/167] Fixed heading and styling --- _opensearch/rest-api/document-apis/get-documents.md | 2 ++ _opensearch/rest-api/document-apis/multi-get.md | 1 - 2 files changed, 2 insertions(+), 1 deletion(-) diff --git a/_opensearch/rest-api/document-apis/get-documents.md b/_opensearch/rest-api/document-apis/get-documents.md index 896e1717..dce4d322 100644 --- a/_opensearch/rest-api/document-apis/get-documents.md +++ b/_opensearch/rest-api/document-apis/get-documents.md @@ -7,6 +7,8 @@ nav_order: 5 --- # Get document +Introduced 1.0 +{: .label .label-purple} After adding a JSON document to your index, you can use the get document API operation to retrieve the document's information and data. diff --git a/_opensearch/rest-api/document-apis/multi-get.md b/_opensearch/rest-api/document-apis/multi-get.md index 1e23b124..886933cb 100644 --- a/_opensearch/rest-api/document-apis/multi-get.md +++ b/_opensearch/rest-api/document-apis/multi-get.md @@ -16,7 +16,6 @@ The multi-get operation allows you to execute multiple GET operations in one req ```json GET _mget - { "docs": [ { From 7faade1bdf2b4d2b1ed1c358e71ab0cfc0d21c0e Mon Sep 17 00:00:00 2001 From: keithhc2 Date: Mon, 30 Aug 2021 11:38:59 -0700 Subject: [PATCH 030/167] Maybe this can resolve conflicts --- _opensearch/rest-api/document-apis/delete-by-query.md | 2 +- _opensearch/rest-api/document-apis/get-documents.md | 2 -- _opensearch/rest-api/document-apis/multi-get.md | 2 -- 3 files changed, 1 insertion(+), 5 deletions(-) diff --git a/_opensearch/rest-api/document-apis/delete-by-query.md b/_opensearch/rest-api/document-apis/delete-by-query.md index 47a53f62..59bb0516 100644 --- a/_opensearch/rest-api/document-apis/delete-by-query.md +++ b/_opensearch/rest-api/document-apis/delete-by-query.md @@ -3,7 +3,7 @@ layout: default title: Delete by query parent: Document APIs grand_parent: REST API reference -nav_order: 30 +nav_order: 40 --- # Delete by query diff --git a/_opensearch/rest-api/document-apis/get-documents.md b/_opensearch/rest-api/document-apis/get-documents.md index dce4d322..896e1717 100644 --- a/_opensearch/rest-api/document-apis/get-documents.md +++ b/_opensearch/rest-api/document-apis/get-documents.md @@ -7,8 +7,6 @@ nav_order: 5 --- # Get document -Introduced 1.0 -{: .label .label-purple} After adding a JSON document to your index, you can use the get document API operation to retrieve the document's information and data. diff --git a/_opensearch/rest-api/document-apis/multi-get.md b/_opensearch/rest-api/document-apis/multi-get.md index 886933cb..006ade95 100644 --- a/_opensearch/rest-api/document-apis/multi-get.md +++ b/_opensearch/rest-api/document-apis/multi-get.md @@ -7,8 +7,6 @@ nav_order: 25 --- # Multi-get documents -Introduced 1.0 -{: .label .label-purple } The multi-get operation allows you to execute multiple GET operations in one request, so you can get back all documents that match your criteria. From 26d3dfe351b1aface7bf3b9f82d5c18cd50f015d Mon Sep 17 00:00:00 2001 From: keithhc2 Date: Mon, 30 Aug 2021 11:42:00 -0700 Subject: [PATCH 031/167] Maybe this is the label --- _opensearch/rest-api/document-apis/multi-get.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/_opensearch/rest-api/document-apis/multi-get.md b/_opensearch/rest-api/document-apis/multi-get.md index 006ade95..886933cb 100644 --- a/_opensearch/rest-api/document-apis/multi-get.md +++ b/_opensearch/rest-api/document-apis/multi-get.md @@ -7,6 +7,8 @@ nav_order: 25 --- # Multi-get documents +Introduced 1.0 +{: .label .label-purple } The multi-get operation allows you to execute multiple GET operations in one request, so you can get back all documents that match your criteria. From 36694537f6870b24cc4e01a314ad21ada8c26eed Mon Sep 17 00:00:00 2001 From: keithhc2 Date: Mon, 30 Aug 2021 11:42:52 -0700 Subject: [PATCH 032/167] Space? --- _opensearch/rest-api/document-apis/multi-get.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/_opensearch/rest-api/document-apis/multi-get.md b/_opensearch/rest-api/document-apis/multi-get.md index 886933cb..ab2ab1ec 100644 --- a/_opensearch/rest-api/document-apis/multi-get.md +++ b/_opensearch/rest-api/document-apis/multi-get.md @@ -7,7 +7,7 @@ nav_order: 25 --- # Multi-get documents -Introduced 1.0 +Introduced 1.0 {: .label .label-purple } The multi-get operation allows you to execute multiple GET operations in one request, so you can get back all documents that match your criteria. From f464d0104180e44e762381da197c84b7b96bbed7 Mon Sep 17 00:00:00 2001 From: keithhc2 Date: Mon, 30 Aug 2021 11:44:35 -0700 Subject: [PATCH 033/167] Revert "Fixed typos" This reverts commit d941cb6ad7d7a66453c0bfe21dbdfba6369ad122. --- .../rest-api/document-apis/delete-by-query.md | 2 +- .../rest-api/document-apis/delete-document.md | 4 +- _opensearch/rest-api/document-apis/reindex.md | 50 ------------------- .../rest-api/document-apis/update-document.md | 8 +-- 4 files changed, 7 insertions(+), 57 deletions(-) delete mode 100644 _opensearch/rest-api/document-apis/reindex.md diff --git a/_opensearch/rest-api/document-apis/delete-by-query.md b/_opensearch/rest-api/document-apis/delete-by-query.md index 59bb0516..440734ca 100644 --- a/_opensearch/rest-api/document-apis/delete-by-query.md +++ b/_opensearch/rest-api/document-apis/delete-by-query.md @@ -28,7 +28,7 @@ POST sample-index1/_delete_by_query ## Path and HTTP methods ``` -POST /_delete_by_query +POST /_delete_by_query ``` ## URL parameters diff --git a/_opensearch/rest-api/document-apis/delete-document.md b/_opensearch/rest-api/document-apis/delete-document.md index a1723e0d..f67cf280 100644 --- a/_opensearch/rest-api/document-apis/delete-document.md +++ b/_opensearch/rest-api/document-apis/delete-document.md @@ -19,14 +19,14 @@ DELETE /sample-index1/_doc/1 ## Path and HTTP methods ``` -DELETE //_doc/<_id> +DELETE //_doc/<_id> ``` ## URL parameters Parameter | Type | Description | Required :--- | :--- | :--- | :--- -<index> | String | The index to delete from. | Yes +<index-name> | String | The index to delete from. | Yes <_id> | String | The ID of the document to delete. | Yes if_seq_no | Integer | Only perform the delete operation if the document's version number matches the specified number. | No if_primary_term | Integer | Only perform the delete operation if the document has the specified primary term. | No diff --git a/_opensearch/rest-api/document-apis/reindex.md b/_opensearch/rest-api/document-apis/reindex.md deleted file mode 100644 index c2d45603..00000000 --- a/_opensearch/rest-api/document-apis/reindex.md +++ /dev/null @@ -1,50 +0,0 @@ ---- -layout: default -title: Reindex -parent: Document APIs -grand_parent: REST API reference -nav_order: 60 ---- - -# Reindex -Introduced 1.0 -{: .label .label-purple} - -You can use the `reindex` operation to copy every document or a subset of documents in your index into another index. - -## Example - -```json - -``` - -## Path and HTTP methods - -``` - -``` - -## URL parameters - - -Parameter | Type | Description | Required -:--- | :--- | :--- | :--- - - -## Request body - -Your request body must contain the information you want to index. - -```json - -``` - -## Response -```json - -``` - -## Response body fields - -Field | Description -:--- | :--- diff --git a/_opensearch/rest-api/document-apis/update-document.md b/_opensearch/rest-api/document-apis/update-document.md index 68dab500..d0144f62 100644 --- a/_opensearch/rest-api/document-apis/update-document.md +++ b/_opensearch/rest-api/document-apis/update-document.md @@ -17,7 +17,7 @@ POST /sample-index1/_update/1 { "doc": { "first_name" : "Bruce", - "last_name" : "Wayne" + "last_name" : "Wayne", } } ``` @@ -28,7 +28,7 @@ POST /sample-index1/_update/1 POST /test-index1/_update/1 { "script" : { - "source": "ctx._source.secret_identity = \"Batman\"" + "source": "ctx._source.secret_identity = \"Batman\"", } } ``` @@ -36,14 +36,14 @@ POST /test-index1/_update/1 ## Path and HTTP methods ``` -POST //_update/<_id> +POST //_update/<_id> ``` ## URL parameters Parameter | Type | Description | Required :--- | :--- | :--- | :--- -<index> | String | Name of the index. | Yes +<index-name> | String | Name of the index. | Yes <_id> | String | The ID of the document to update. | Yes if_seq_no | Integer | Only perform the delete operation if the document's version number matches the specified number. | No if_primary_term | Integer | Perform the update operation if the document has the specified primary term. | No From 449177c07e83a8d0fb3de1fce5a7066d56773b4c Mon Sep 17 00:00:00 2001 From: keithhc2 Date: Mon, 30 Aug 2021 11:47:02 -0700 Subject: [PATCH 034/167] Fixed typos --- _opensearch/rest-api/document-apis/delete-by-query.md | 2 +- _opensearch/rest-api/document-apis/delete-document.md | 4 ++-- _opensearch/rest-api/document-apis/update-document.md | 8 ++++---- 3 files changed, 7 insertions(+), 7 deletions(-) diff --git a/_opensearch/rest-api/document-apis/delete-by-query.md b/_opensearch/rest-api/document-apis/delete-by-query.md index 440734ca..59bb0516 100644 --- a/_opensearch/rest-api/document-apis/delete-by-query.md +++ b/_opensearch/rest-api/document-apis/delete-by-query.md @@ -28,7 +28,7 @@ POST sample-index1/_delete_by_query ## Path and HTTP methods ``` -POST /_delete_by_query +POST /_delete_by_query ``` ## URL parameters diff --git a/_opensearch/rest-api/document-apis/delete-document.md b/_opensearch/rest-api/document-apis/delete-document.md index f67cf280..a1723e0d 100644 --- a/_opensearch/rest-api/document-apis/delete-document.md +++ b/_opensearch/rest-api/document-apis/delete-document.md @@ -19,14 +19,14 @@ DELETE /sample-index1/_doc/1 ## Path and HTTP methods ``` -DELETE //_doc/<_id> +DELETE //_doc/<_id> ``` ## URL parameters Parameter | Type | Description | Required :--- | :--- | :--- | :--- -<index-name> | String | The index to delete from. | Yes +<index> | String | The index to delete from. | Yes <_id> | String | The ID of the document to delete. | Yes if_seq_no | Integer | Only perform the delete operation if the document's version number matches the specified number. | No if_primary_term | Integer | Only perform the delete operation if the document has the specified primary term. | No diff --git a/_opensearch/rest-api/document-apis/update-document.md b/_opensearch/rest-api/document-apis/update-document.md index d0144f62..68dab500 100644 --- a/_opensearch/rest-api/document-apis/update-document.md +++ b/_opensearch/rest-api/document-apis/update-document.md @@ -17,7 +17,7 @@ POST /sample-index1/_update/1 { "doc": { "first_name" : "Bruce", - "last_name" : "Wayne", + "last_name" : "Wayne" } } ``` @@ -28,7 +28,7 @@ POST /sample-index1/_update/1 POST /test-index1/_update/1 { "script" : { - "source": "ctx._source.secret_identity = \"Batman\"", + "source": "ctx._source.secret_identity = \"Batman\"" } } ``` @@ -36,14 +36,14 @@ POST /test-index1/_update/1 ## Path and HTTP methods ``` -POST //_update/<_id> +POST //_update/<_id> ``` ## URL parameters Parameter | Type | Description | Required :--- | :--- | :--- | :--- -<index-name> | String | Name of the index. | Yes +<index> | String | Name of the index. | Yes <_id> | String | The ID of the document to update. | Yes if_seq_no | Integer | Only perform the delete operation if the document's version number matches the specified number. | No if_primary_term | Integer | Perform the update operation if the document has the specified primary term. | No From 94503ea959c740f7ced7a518c6664e33ecf15399 Mon Sep 17 00:00:00 2001 From: Keith Chan <12404772+keithhc2@users.noreply.github.com> Date: Mon, 30 Aug 2021 11:54:46 -0700 Subject: [PATCH 035/167] Language tweaks --- _opensearch/rest-api/update-mapping.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/_opensearch/rest-api/update-mapping.md b/_opensearch/rest-api/update-mapping.md index 0d0d451c..0108442f 100644 --- a/_opensearch/rest-api/update-mapping.md +++ b/_opensearch/rest-api/update-mapping.md @@ -47,12 +47,12 @@ All update mapping parameters are optional. Parameter | Data Type | Description :--- | :--- | :--- -allow_no_indices | Boolean | If false, the request returns an error if any wildcard expresion or index alias targets any closed or missing indices. Defaults to false. +allow_no_indices | Boolean | Whether to ignore wildcards that don’t match any indices. Default is true. expand_wildcards | String | Expands wildcard expressions to different indices. Combine multiple values with commas. Available values are `all` (match all indices), `open` (match open indices), `closed` (match closed indices), `hidden` (match hidden indices), and `none` (do not accept wildcard expressions), which must be used with `open`, `closed`, or both. Default is `open`. ignore_unavailable | Boolean | If true, OpenSearch does not include missing or closed indices in the response. 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 response to return. Default is `30s`. -write_index_only | Boolean | If true, the specified mappings are applied only to the write index. +write_index_only | Boolean | Whether OpenSearch should apply mapping updates only to the write index. ## Request body From dc48c6ced5d1a35867e1d3a9f7e9304bbde51ff2 Mon Sep 17 00:00:00 2001 From: ashwinkumar12345 Date: Mon, 30 Aug 2021 12:58:30 -0700 Subject: [PATCH 036/167] added count API --- _opensearch/rest-api/count.md | 103 ++++++++++++++++++++++++++++++++++ 1 file changed, 103 insertions(+) create mode 100644 _opensearch/rest-api/count.md diff --git a/_opensearch/rest-api/count.md b/_opensearch/rest-api/count.md new file mode 100644 index 00000000..7a1a8568 --- /dev/null +++ b/_opensearch/rest-api/count.md @@ -0,0 +1,103 @@ +--- +layout: default +title: Count +parent: REST API reference +nav_order: 150 +--- + +# Count +Introduced 1.0 +{: .label .label-purple } + +The count API gives you quick access to the number of documents that match a query. +You can also the use the count API to see the total number of documents in an index, a data stream, or an entire cluster. + + +## Example + +To see the number of documents that match a query: + +```json +GET opensearch_dashboards_sample_data_logs/_count +{ + "query": { + "term": { + "response": "200" + } + } +} +``` + +You can also use the search API for the same result: + +```json +GET opensearch_dashboards_sample_data_logs/_search +{ + "query": { + "term": { + "response": "200" + } + }, + "size": 0, + "track_total_hits": true +} +``` + +To see the number of documents in an index: + +```json +GET opensearch_dashboards_sample_data_logs/_count +``` + +To check for the number of documents in a [data stream]({{site.url}}{{site.baseurl}}/opensearch/data-streams/), replace the index name with the data stream name. + +To see the number of documents in your cluster: + +```json +GET _count +``` + +Alternatively, you could use the [cat indices]({{site.url}}{{site.baseurl}}/opensearch/rest-api/cat/cat-indices/) and [cat count]({{site.url}}{{site.baseurl}}/opensearch/rest-api/cat/cat-count/) APIs to see the number of documents per index or data stream. +{: .note } + + +## Path and HTTP methods + +``` +GET /_count/ +POST /_count/ +``` + + +## URL parameters + +All count parameters are optional. + +Parameter | Type | Description +:--- | :--- | :--- +`allow_no_indices` | Boolean | If false, the request returns an error if any wildcard expression or index alias targets any closed or missing indices. Default is false. +`analyzer` | String | The analyzer to use in the query string. +`analyze_wildcard` | Boolean | Specifies whether to analyze wildcard and prefix queries. Default is false. +`default_operator` | String | Indicates whether the default operator for a string query should be AND or OR. Default is OR. +`df` | String | The default field in case a field prefix is not provided in the query string. +`expand_wildcards` | String | Specifies the type of index that wildcard expressions can match. Supports comma-separated values. Valid values are `all` (match any index), `open` (match open, non-hidden indices), `closed` (match closed, non-hidden indices), `hidden` (match hidden indices), and `none` (deny wildcard expressions). Default is `open`. +`ignore_unavailable` | Boolean | Specifies whether to include missing or closed indices in the response. Default is false. +`lenient` | Boolean | Specifies whether OpenSearch should accept requests if queries have format errors (for example, querying a text field for an integer). Default is false. +`min_score` | Float | Include only documents with a minimum `_score` value in the result. +`routing` | String | Value used to route the operation to a specific shard. +`preference` | String | Specifies which shard or node OpenSearch should perform the count operation on. +`terminate_after` | Integer | The maximum number of documents OpenSearch should process before terminating the request. + +## Response + +```json +{ + "count" : 14074, + "_shards" : { + "total" : 1, + "successful" : 1, + "skipped" : 0, + "failed" : 0 + } +} +``` From baa5622f9d4a4910b57bcb05dffbe4ce3ac52cef Mon Sep 17 00:00:00 2001 From: ashwinkumar12345 Date: Tue, 31 Aug 2021 10:29:20 -0700 Subject: [PATCH 037/167] minor changes --- _opensearch/rest-api/count.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/_opensearch/rest-api/count.md b/_opensearch/rest-api/count.md index 7a1a8568..b7b6b12d 100644 --- a/_opensearch/rest-api/count.md +++ b/_opensearch/rest-api/count.md @@ -10,7 +10,7 @@ Introduced 1.0 {: .label .label-purple } The count API gives you quick access to the number of documents that match a query. -You can also the use the count API to see the total number of documents in an index, a data stream, or an entire cluster. +You can also use it to check the document count of an index, data stream, or cluster. ## Example From 60b1859f1e39612deb27d17ac90b51967934a516 Mon Sep 17 00:00:00 2001 From: aetter Date: Tue, 31 Aug 2021 10:43:48 -0700 Subject: [PATCH 038/167] Remove "About data streams," "Date math support for index names," and "Simulate multi-component templates" --- _opensearch/data-streams.md | 26 ------------- _opensearch/date_math_support.md | 60 ---------------------------- _opensearch/index-templates.md | 65 ------------------------------- images/data_stream_indexing.png | Bin 49786 -> 0 bytes images/data_stream_searching.png | Bin 45589 -> 0 bytes 5 files changed, 151 deletions(-) delete mode 100644 _opensearch/date_math_support.md delete mode 100644 images/data_stream_indexing.png delete mode 100644 images/data_stream_searching.png diff --git a/_opensearch/data-streams.md b/_opensearch/data-streams.md index 312e5335..07d8b136 100644 --- a/_opensearch/data-streams.md +++ b/_opensearch/data-streams.md @@ -15,32 +15,6 @@ Data streams simplify this bootstrapping process and enforce a setup that best s A data stream is internally composed of multiple backing indices. Search requests are routed to all the backing indices, while indexing requests are routed to the latest write index. You can use [ISM]({{site.url}}{{site.baseurl}}/im-plugin/ism/index/) policies to automatically handle rollovers or deletion of indices in a data stream, based on your use case. -## 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-- -``` - -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: - -![data stream indexing diagram]({{site.url}}{{site.baseurl}}/images/data_stream_indexing.png) - -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: - -![data stream indexing diagram]({{site.url}}{{site.baseurl}}/images/data_stream_searching.png) - -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 diff --git a/_opensearch/date_math_support.md b/_opensearch/date_math_support.md deleted file mode 100644 index 2d997904..00000000 --- a/_opensearch/date_math_support.md +++ /dev/null @@ -1,60 +0,0 @@ ---- -layout: default -title: Date math support for index names -nav_order: 92 ---- - -# Date math support for index names - -Date math is shorthand arithmetic for finding relative dates. - -If you're indexing time-series data with the dates mapped in the index names, you can use date math in your queries to filter index names and limit the number of searched indices. - -## Date math syntax - -The date math syntax for an index name is as follows: - -``` - -``` - -- `static_name`: The unchanged or static portion of the index name. To use the characters `{` and `}` in the static part of an index name, escape them with a backslash `\`. -- `date_math_expr`: The changing or dynamic portion of the index name that’s computed by the date math expression. For example, `now+1h` adds one hour, `now-1d` subtracts one hour, and `now/d` rounds down to the nearest day, where `now` represents the current timestamp. -- `date_format`: (Optional) Specify the format for the computed date. The default value is `YYYY.MM.dd`. Make sure that you’re using the correct small or capital letters in the date format. For example, `mm` denotes minute of hour, while `MM` denotes month of year. Similarly, `hh` denotes the hour in the `1-12` range in combination with AM/PM, while `HH` denotes the hour in the `0-23` 24-hour range. -- `time_zone`: (Optional) Specify the timezone offset. The default value is UTC. For example, the UTC time offset for PST is `-08:00`. - -## Date math example - -You must enclose date math index names within angle brackets. - -If today is 22nd March, 2024: - -- `` resolves to `logstash-2024.03.22` -- `` resolves to `logstash-2024.03.01` -- `` resolves to `logstash-2024.03` -- `` resolves to `logstash-2024.02` -- `` resolves to `logstash-2024.03.23` - -You need to encode all special characters in URI format: - -Special characters | URI format -:--- | :--- -`<` | %3C -`>` | %3E -`/` | %2F -`{` | %7B -`}` | %7D -`|` | %7C -`+` | %2B -`:` | %3A -`,` | %2C -`\` | %5C - -If you are searching for errors in your daily logs with the default Logstash index name format `logstash-YYYY.MM.dd`, you can use date math to restrict the search to indices of the past three days: - -``` -# GET ,,/_search -GET %3Clogstash-%7Bnow%2Fd-2d%7D%3E%2C%3Clogstash-%7Bnow%2Fd-1d%7D%3E%2C%3Clogstash-%7Bnow%2Fd%7D%3E/_search -``` - -This date math expression is evaluated at runtime. diff --git a/_opensearch/index-templates.md b/_opensearch/index-templates.md index 8d49b891..c258c518 100644 --- a/_opensearch/index-templates.md +++ b/_opensearch/index-templates.md @@ -328,71 +328,6 @@ GET 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/ -``` - -To simulate the settings that would be applied from an existing template: - -```json -POST _index_template/_simulate/ -``` - -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 diff --git a/images/data_stream_indexing.png b/images/data_stream_indexing.png deleted file mode 100644 index 7bd21ac0738c76ce580c5c95ae65becd8ceddbd5..0000000000000000000000000000000000000000 GIT binary patch literal 0 HcmV?d00001 literal 49786 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 C9TR;3 From ffe3f7799378d61aece932d24982231dcf0ddf38 Mon Sep 17 00:00:00 2001 From: aetter Date: Tue, 31 Aug 2021 10:50:48 -0700 Subject: [PATCH 039/167] Light edits to data streams --- _opensearch/data-streams.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/_opensearch/data-streams.md b/_opensearch/data-streams.md index 07d8b136..ff06d6e1 100644 --- a/_opensearch/data-streams.md +++ b/_opensearch/data-streams.md @@ -8,11 +8,11 @@ nav_order: 13 If you're ingesting continuously generated time-series data such as logs, events, and metrics into OpenSearch, you're likely in a scenario where the number of documents grows rapidly and you don't need to update older documents. -A typical workflow to manage time-series data involves multiple steps such as creating a rollover index alias, defining a write index, and defining common mappings and settings for the backing indices. +A typical workflow to manage time-series data involves multiple steps, such as creating a rollover index alias, defining a write index, and defining common mappings and settings for the backing indices. -Data streams simplify this bootstrapping process and enforce a setup that best suits time-series data, such as being designed primarily for append-only data, and ensuring that each document has a timestamp field. +Data streams simplify this process and enforce a setup that best suits time-series data, such as being designed primarily for append-only data and ensuring that each document has a timestamp field. -A data stream is internally composed of multiple backing indices. Search requests are routed to all the backing indices, while indexing requests are routed to the latest write index. You can use [ISM]({{site.url}}{{site.baseurl}}/im-plugin/ism/index/) policies to automatically handle rollovers or deletion of indices in a data stream, based on your use case. +A data stream is internally composed of multiple backing indices. Search requests are routed to all the backing indices, while indexing requests are routed to the latest write index. [ISM]({{site.url}}{{site.baseurl}}/im-plugin/ism/index/) policies let you automatically handle index rollovers or deletions. ## Get started with data streams From cda046f727dd071caded8c0feeffa8359d83b80f Mon Sep 17 00:00:00 2001 From: aetter Date: Wed, 1 Sep 2021 11:25:39 -0700 Subject: [PATCH 040/167] Version bumps for 1.0.1 --- README.md | 2 +- _config.yml | 2 +- _dashboards/install/plugins.md | 45 ++++++++++-------------------- _opensearch/install/plugins.md | 50 ++++++++++++---------------------- version-history.md | 1 + 5 files changed, 35 insertions(+), 65 deletions(-) diff --git a/README.md b/README.md index 175730e0..093941af 100644 --- a/README.md +++ b/README.md @@ -196,7 +196,7 @@ If you're making major changes to the documentation and need to see the rendered ## New releases 1. Branch. -1. Change the `opensearch_version` and `opensearch_major_version` variables in `_config.yml`. +1. Change the `opensearch_version` and `opensearch_major_minor_version` variables in `_config.yml`. 1. Start up a new cluster using the updated Docker Compose file in `docs/install/docker.md`. 1. Update the version table in `version-history.md`. diff --git a/_config.yml b/_config.yml index 0b56bce3..3c01797d 100644 --- a/_config.yml +++ b/_config.yml @@ -5,7 +5,7 @@ baseurl: "/docs" # the subpath of your site, e.g. /blog url: "https://opensearch.org" # the base hostname & protocol for your site, e.g. http://example.com permalink: /:path/ -opensearch_version: 1.0.0 +opensearch_version: 1.0.1 opensearch_major_minor_version: 1.0 # Build settings diff --git a/_dashboards/install/plugins.md b/_dashboards/install/plugins.md index 805423c9..06b3c4c9 100644 --- a/_dashboards/install/plugins.md +++ b/_dashboards/install/plugins.md @@ -28,6 +28,21 @@ If you don't want to use the all-in-one installation options, you can install th + + 1.0.1 + +

alertingDashboards          1.0.0.0
+anomalyDetectionDashboards  1.0.0.0
+ganttChartDashboards        1.0.0.0
+indexManagementDashboards   1.0.1.0
+notebooksDashboards         1.0.0.0
+queryWorkbenchDashboards    1.0.0.0
+reportsDashboards           1.0.1.0
+securityDashboards          1.0.1.0
+traceAnalyticsDashboards    1.0.0.0
+
+ + 1.0.0 @@ -40,36 +55,6 @@ queryWorkbenchDashboards 1.0.0.0 reportsDashboards 1.0.0.0 securityDashboards 1.0.0.0 traceAnalyticsDashboards 1.0.0.0 - - - - - 1.0.0-rc1 - -
alertingDashboards          1.0.0.0-rc1
-anomalyDetectionDashboards  1.0.0.0-rc1
-ganttChartDashboards        1.0.0.0-rc1
-indexManagementDashboards   1.0.0.0-rc1
-notebooksDashboards         1.0.0.0-rc1
-queryWorkbenchDashboards    1.0.0.0-rc1
-reportsDashboards           1.0.0.0-rc1
-securityDashboards          1.0.0.0-rc1
-traceAnalyticsDashboards    1.0.0.0-rc1
-
- - - - 1.0.0-beta1 - -
alertingDashboards          1.0.0.0-beta1
-anomalyDetectionDashboards  1.0.0.0-beta1
-ganttChartDashboards        1.0.0.0-beta1
-indexManagementDashboards   1.0.0.0-beta1
-notebooksDashboards         1.0.0.0-beta1
-queryWorkbenchDashboards    1.0.0.0-beta1
-reportsDashboards           1.0.0.0-beta1
-securityDashboards          1.0.0.0-beta1
-traceAnalyticsDashboards    1.0.0.0-beta1
 
diff --git a/_opensearch/install/plugins.md b/_opensearch/install/plugins.md index 800ab2f7..40fdefc7 100644 --- a/_opensearch/install/plugins.md +++ b/_opensearch/install/plugins.md @@ -29,6 +29,23 @@ If you don't want to use the all-in-one OpenSearch installation options, you can + + 1.0.1 + +
opensearch-alerting             1.0.0.0
+opensearch-anomaly-detection    1.0.0.0
+opensearch-asynchronous-search  1.0.0.0
+opensearch-index-management     1.0.1.0
+opensearch-job-scheduler        1.0.0.0
+opensearch-knn                  1.0.0.0
+opensearch-notebooks            1.0.0.0
+opensearch-performance-analyzer 1.0.1.0
+opensearch-reports-scheduler    1.0.0.0
+opensearch-security             1.0.1.0
+opensearch-sql                  1.0.0.0
+
+ + 1.0.0 @@ -43,39 +60,6 @@ opensearch-performance-analyzer 1.0.0.0 opensearch-reports-scheduler 1.0.0.0 opensearch-security 1.0.0.0 opensearch-sql 1.0.0.0 - - - - - 1.0.0-rc1 - -
opensearch-alerting             1.0.0.0-rc1
-opensearch-anomaly-detection    1.0.0.0-rc1
-opensearch-asynchronous-search  1.0.0.0-rc1
-opensearch-index-management     1.0.0.0-rc1
-opensearch-job-scheduler        1.0.0.0-rc1
-opensearch-knn                  1.0.0.0-rc1
-opensearch-notebooks            1.0.0.0-rc1
-opensearch-performance-analyzer 1.0.0.0-rc1
-opensearch-reports-scheduler    1.0.0.0-rc1
-opensearch-security             1.0.0.0-rc1
-opensearch-sql                  1.0.0.0-rc1
-
- - - - 1.0.0-beta1 - -
opensearch-alerting             1.0.0.0-beta1
-opensearch-anomaly-detection    1.0.0.0-beta1
-opensearch-asynchronous-search  1.0.0.0-beta1
-opensearch-index-management     1.0.0.0-beta1
-opensearch-job-scheduler        1.0.0.0-beta1
-opensearch-knn                  1.0.0.0-beta1
-opensearch-performance-analyzer 1.0.0.0-beta1
-opensearch-reports-scheduler    1.0.0.0-beta1
-opensearch-security             1.0.0.0-beta1
-opensearch-sql                  1.0.0.0-beta1
 
diff --git a/version-history.md b/version-history.md index 7b4f165b..bb67d8b9 100644 --- a/version-history.md +++ b/version-history.md @@ -9,6 +9,7 @@ permalink: /version-history/ OpenSearch version | Release highlights | Release date :--- | :--- | :--- | :--- +[1.0.1](https://github.com/opensearch-project/opensearch-build/tree/main/release-notes/opensearch-release-notes-1.0.1.md) | Bug fixes. | 1 September 2021 [1.0.0](https://github.com/opensearch-project/opensearch-build/tree/main/release-notes/opensearch-release-notes-1.0.0.md) | General availability release. Adds compatibility setting for clients that require a version check before connecting. | 12 July 2021 [1.0.0-rc1](https://github.com/opensearch-project/opensearch-build/tree/main/release-notes/opensearch-release-notes-1.0.0-rc1.md) | First release candidate. | 7 June 2021 [1.0.0-beta1](https://github.com/opensearch-project/opensearch-build/tree/main/release-notes/opensearch-release-notes-1.0.0-beta1.md) | Initial beta release. Refactors plugins to work with OpenSearch. | 13 May 2021 From ecea83707d2576f07ec0b63a54e406eaafcf1b47 Mon Sep 17 00:00:00 2001 From: aetter Date: Wed, 1 Sep 2021 11:37:54 -0700 Subject: [PATCH 041/167] Adds Lucene version variable, minor improvements to REST API and query DSL --- _config.yml | 1 + _opensearch/metric-agg.md | 4 +- _opensearch/query-dsl/full-text.md | 14 +-- _opensearch/query-dsl/term.md | 10 +- _opensearch/rest-api/document-apis/bulk.md | 2 +- .../rest-api/document-apis/delete-by-query.md | 3 +- .../rest-api/document-apis/update-by-query.md | 2 +- _opensearch/rest-api/explain.md | 2 +- _opensearch/rest-api/multi-search.md | 95 ++++++++++++------- _opensearch/rest-api/scroll.md | 2 +- _opensearch/rest-api/update-mapping.md | 2 +- _search-plugins/async/index.md | 8 +- _search-plugins/knn/approximate-knn.md | 2 +- 13 files changed, 92 insertions(+), 55 deletions(-) diff --git a/_config.yml b/_config.yml index 3c01797d..ae992e6d 100644 --- a/_config.yml +++ b/_config.yml @@ -7,6 +7,7 @@ permalink: /:path/ opensearch_version: 1.0.1 opensearch_major_minor_version: 1.0 +lucene_version: 8_8_2 # Build settings markdown: kramdown diff --git a/_opensearch/metric-agg.md b/_opensearch/metric-agg.md index 13f82bc8..9211aacc 100644 --- a/_opensearch/metric-agg.md +++ b/_opensearch/metric-agg.md @@ -88,8 +88,8 @@ GET opensearch_dashboards_sample_data_ecommerce/_search } ``` -The cardinality count is approximate. -If you had tens of thousands of products in your store, an accurate cardinality calculation requires loading all the values into a hash set and returning its size. This approach doesn't scale well because it requires more memory and causes high latency. +Cardinality count is approximate. +If you have tens of thousands of products in your hypothetical store, an accurate cardinality calculation requires loading all the values into a hash set and returning its size. This approach doesn't scale well; it requires huge amounts of memory and can cause high latencies. You can control the trade-off between memory and accuracy with the `precision_threshold` setting. This setting defines the threshold below which counts are expected to be close to accurate. Above this value, counts might become a bit less accurate. The default value of `precision_threshold` is 3,000. The maximum supported value is 40,000. diff --git a/_opensearch/query-dsl/full-text.md b/_opensearch/query-dsl/full-text.md index c751ee3d..f834f31f 100644 --- a/_opensearch/query-dsl/full-text.md +++ b/_opensearch/query-dsl/full-text.md @@ -21,7 +21,7 @@ This page lists all full-text query types and common options. Given the sheer nu ## Match -Creates a [boolean query](https://lucene.apache.org/core/8_4_0/core/org/apache/lucene/search/BooleanQuery.html) that returns results if the search term is present in the field. +Creates a [boolean query](https://lucene.apache.org/core/{{site.lucene_version}}/core/org/apache/lucene/search/BooleanQuery.html) that returns results if the search term is present in the field. The most basic form of the query provides only a field (`title`) and a term (`wind`): @@ -126,7 +126,7 @@ GET _search ## Match boolean prefix -Similar to [match](#match), but creates a [prefix query](https://lucene.apache.org/core/8_4_0/core/org/apache/lucene/search/PrefixQuery.html) out of the last term in the query string. +Similar to [match](#match), but creates a [prefix query](https://lucene.apache.org/core/{{site.lucene_version}}/core/org/apache/lucene/search/PrefixQuery.html) out of the last term in the query string. ```json GET _search @@ -164,7 +164,7 @@ GET _search ## Match phrase -Creates a [phrase query](https://lucene.apache.org/core/8_4_0/core/org/apache/lucene/search/PhraseQuery.html) that matches a sequence of terms. +Creates a [phrase query](https://lucene.apache.org/core/{{site.lucene_version}}/core/org/apache/lucene/search/PhraseQuery.html) that matches a sequence of terms. ```json GET _search @@ -198,7 +198,7 @@ GET _search ## Match phrase prefix -Similar to [match phrase](#match-phrase), but creates a [prefix query](https://lucene.apache.org/core/8_4_0/core/org/apache/lucene/search/PrefixQuery.html) out of the last term in the query string. +Similar to [match phrase](#match-phrase), but creates a [prefix query](https://lucene.apache.org/core/{{site.lucene_version}}/core/org/apache/lucene/search/PrefixQuery.html) out of the last term in the query string. ```json GET _search @@ -410,7 +410,7 @@ Option | Valid values | Description `allow_leading_wildcard` | Boolean | Whether `*` and `?` are allowed as the first character of a search term. The default is true. `analyze_wildcard` | Boolean | Whether OpenSearch should attempt to analyze wildcard terms. Some analyzers do a poor job at this task, so the default is false. `analyzer` | `standard, simple, whitespace, stop, keyword, pattern, , fingerprint` | The analyzer you want to use for the query. Different analyzers have different character filters, tokenizers, and token filters. The `stop` analyzer, for example, removes stop words (e.g. "an," "but," "this") from the query string. -`auto_generate_synonyms_phrase_query` | Boolean | A value of true (default) automatically generates [phrase queries](https://lucene.apache.org/core/8_4_0/core/org/apache/lucene/search/PhraseQuery.html) for multi-term synonyms. For example, if you have the synonym `"ba, batting average"` and search for "ba," OpenSearch searches for `ba OR "batting average"` (if this option is true) or `ba OR (batting AND average)` (if this option is false). +`auto_generate_synonyms_phrase_query` | Boolean | A value of true (default) automatically generates [phrase queries](https://lucene.apache.org/core/{{site.lucene_version}}/core/org/apache/lucene/search/PhraseQuery.html) for multi-term synonyms. For example, if you have the synonym `"ba, batting average"` and search for "ba," OpenSearch searches for `ba OR "batting average"` (if this option is true) or `ba OR (batting AND average)` (if this option is false). `boost` | Floating-point | Boosts the clause by the given multiplier. Useful for weighing clauses in compound queries. The default is 1.0. `cutoff_frequency` | Between `0.0` and `1.0` or a positive integer | This value lets you define high and low frequency terms based on number of occurrences in the index. Numbers between 0 and 1 are treated as a percentage. For example, 0.10 is 10%. This value means that if a word occurs within the search field in more than 10% of the documents on the shard, OpenSearch considers the word "high frequency" and deemphasizes it when calculating search score.

Because this setting is *per shard*, testing its impact on search results can be challenging unless a cluster has many documents. `enable_position_increments` | Boolean | When true, result queries are aware of position increments. This setting is useful when the removal of stop words leaves an unwanted "gap" between terms. The default is true. @@ -420,7 +420,7 @@ Option | Valid values | Description `fuzzy_transpositions` | Boolean | Setting `fuzzy_transpositions` to true (default) adds swaps of adjacent characters to the insert, delete, and substitute operations of the `fuzziness` option. For example, the distance between `wind` and `wnid` is 1 if `fuzzy_transpositions` is true (swap "n" and "i") and 2 if it is false (delete "n", insert "n").

If `fuzzy_transpositions` is false, `rewind` and `wnid` have the same distance (2) from `wind`, despite the more human-centric opinion that `wnid` is an obvious typo. The default is a good choice for most use cases. `lenient` | Boolean | Setting `lenient` to true lets you ignore data type mismatches between the query and the document field. For example, a query string of "8.2" could match a field of type `float`. The default is false. `low_freq_operator` | `and, or` | The operator for low-frequency terms. The default is `or`. See [Common terms](#common-terms) queries and `operator` in this table. -`max_determinized_states` | Positive integer | The maximum number of "[states](https://lucene.apache.org/core/8_4_0/core/org/apache/lucene/util/automaton/Operations.html#DEFAULT_MAX_DETERMINIZED_STATES)" (a measure of complexity) that Lucene can create for query strings that contain regular expressions (e.g. `"query": "/wind.+?/"`). Larger numbers allow for queries that use more memory. The default is 10,000. +`max_determinized_states` | Positive integer | The maximum number of "[states](https://lucene.apache.org/core/{{site.lucene_version}}/core/org/apache/lucene/util/automaton/Operations.html#DEFAULT_MAX_DETERMINIZED_STATES)" (a measure of complexity) that Lucene can create for query strings that contain regular expressions (e.g. `"query": "/wind.+?/"`). Larger numbers allow for queries that use more memory. The default is 10,000. `max_expansions` | Positive integer | Fuzzy queries "expand to" a number of matching terms that are within the distance specified in `fuzziness`. Then OpenSearch tries to match those terms against its indices. `max_expansions` specifies the maximum number of terms that the fuzzy query expands to. The default is 50. `minimum_should_match` | Positive or negative integer, positive or negative percentage, combination | If the query string contains multiple search terms and you used the `or` operator, the number of terms that need to match for the document to be considered a match. For example, if `minimum_should_match` is 2, "wind often rising" does not match "The Wind Rises." If `minimum_should_match` is 1, it matches. This option also has `low_freq` and `high_freq` properties for [Common terms](#common-terms) queries. `operator` | `or, and` | If the query string contains multiple search terms, whether all terms need to match (`and`) or only one term needs to match (`or`) for a document to be considered a match. @@ -428,7 +428,7 @@ Option | Valid values | Description `prefix_length` | `0` (default) or a positive integer | The number of leading characters that are not considered in fuzziness. `quote_field_suffix` | String | This option lets you search different fields depending on whether terms are wrapped in quotes. For example, if `quote_field_suffix` is `".exact"` and you search for `"lightly"` (in quotes) in the `title` field, OpenSearch searches the `title.exact` field. This second field might use a different type (e.g. `keyword` rather than `text`) or a different analyzer. The default is null. `rewrite` | `constant_score, scoring_boolean, constant_score_boolean, top_terms_N, top_terms_boost_N, top_terms_blended_freqs_N` | Determines how OpenSearch rewrites and scores multi-term queries. The default is `constant_score`. -`slop` | `0` (default) or a positive integer | Controls the degree to which words in a query can be misordered and still be considered a match. From the [Lucene documentation](https://lucene.apache.org/core/8_4_0/core/org/apache/lucene/search/PhraseQuery.html#getSlop--): "The number of other words permitted between words in query phrase. For example, to switch the order of two words requires two moves (the first move places the words atop one another), so to permit re-orderings of phrases, the slop must be at least two. A value of zero requires an exact match." +`slop` | `0` (default) or a positive integer | Controls the degree to which words in a query can be misordered and still be considered a match. From the [Lucene documentation](https://lucene.apache.org/core/{{site.lucene_version}}/core/org/apache/lucene/search/PhraseQuery.html#getSlop--): "The number of other words permitted between words in query phrase. For example, to switch the order of two words requires two moves (the first move places the words atop one another), so to permit re-orderings of phrases, the slop must be at least two. A value of zero requires an exact match." `tie_breaker` | `0.0` (default) to `1.0` | Changes the way OpenSearch scores searches. For example, a `type` of `best_fields` typically uses the highest score from any one field. If you specify a `tie_breaker` value between 0.0 and 1.0, the score changes to highest score + `tie_breaker` * score for all other matching fields. If you specify a value of 1.0, OpenSearch adds together the scores for all matching fields (effectively defeating the purpose of `best_fields`). `time_zone` | UTC offset | The time zone to use (e.g. `-08:00`) if the query string contains a date range (e.g. `"query": "wind rises release_date[2012-01-01 TO 2014-01-01]"`). The default is `UTC`. `type` | `best_fields, most_fields, cross-fields, phrase, phrase_prefix` | Determines how OpenSearch executes the query and scores the results. The default is `best_fields`. diff --git a/_opensearch/query-dsl/term.md b/_opensearch/query-dsl/term.md index e2bcb8ee..72c71bd5 100644 --- a/_opensearch/query-dsl/term.md +++ b/_opensearch/query-dsl/term.md @@ -430,7 +430,7 @@ Wildcard queries tend to be slow because they need to iterate over a lot of term ## Regex -Use the `regex` query to search for terms that match a regular expression. +Use the `regexp` query to search for terms that match a regular expression. This regular expression matches any single uppercase or lowercase letter: @@ -439,12 +439,14 @@ GET shakespeare/_search { "query": { "regexp": { - "play_name": "H[a-zA-Z]+mlet" + "play_name": "[a-zA-Z]amlet" } } } ``` -Regular expressions are applied to the terms in the field and not the entire value of the field. +A few important notes: -The efficiency of your regular expression depends a lot on the patterns you write. Make sure that you write `regex` queries with either a prefix or suffix to improve performance. +- Regular expressions are applied to the terms in the field (i.e. tokens), not the entire field. +- Regular expressions use the Lucene syntax, which differs from more standardized implementations. Test thoroughly to ensure that you receive the results you expect. To learn more, see [the Lucene documentation](https://lucene.apache.org/core/{{site.lucene_version}}/core/index.html). +- `regexp` queries can be expensive operations and require the `search.allow_expensive_queries` setting to be set to `true`. Before making frequent `regexp` queries, test their impact on cluster performance and examine alternative queries for achieving similar results. diff --git a/_opensearch/rest-api/document-apis/bulk.md b/_opensearch/rest-api/document-apis/bulk.md index 4139471e..c10a3932 100644 --- a/_opensearch/rest-api/document-apis/bulk.md +++ b/_opensearch/rest-api/document-apis/bulk.md @@ -32,7 +32,7 @@ POST _bulk ``` POST _bulk -POST {index}/_bulk +POST /_bulk ``` Specifying the index in the path means you don't need to include it in the [request body]({{site.url}}{{site.baseurl}}/opensearch/rest-api/document-apis/bulk/#request-body). diff --git a/_opensearch/rest-api/document-apis/delete-by-query.md b/_opensearch/rest-api/document-apis/delete-by-query.md index 59bb0516..e858d1d1 100644 --- a/_opensearch/rest-api/document-apis/delete-by-query.md +++ b/_opensearch/rest-api/document-apis/delete-by-query.md @@ -38,8 +38,7 @@ All URL parameters are optional. Parameter | Type | Description :--- | :--- | :--- | :--- <index> | String | Name or list of the data streams, indices, or aliases to delete from. Supports wildcards. If left blank, OpenSearch searches all indices. -allow_no_indices - Whether to ignore wildcards that don’t match any indices. Default is `true`. -allow_no_indices | Boolean | False indicates to OpenSearch the request should return an error if any wildcard expression or index alias targets only missing or closed indices. Default is true. +allow_no_indices | Boolean | Whether to ignore wildcards that don’t match any indices. Default is `true`. analyzer | String | The analyzer to use in the query string. analyze_wildcard | Boolean | Specifies whether to analyze wildcard and prefix queries. Default is false. conflicts | String | Indicates to OpenSearch what should happen if the delete by query operation runs into a version conflict. Valid options are `abort` and `proceed`. Default is `abort`. diff --git a/_opensearch/rest-api/document-apis/update-by-query.md b/_opensearch/rest-api/document-apis/update-by-query.md index f6d32d9e..0e66d1ae 100644 --- a/_opensearch/rest-api/document-apis/update-by-query.md +++ b/_opensearch/rest-api/document-apis/update-by-query.md @@ -45,7 +45,7 @@ All URL parameters are optional. Parameter | Type | Description :--- | :--- | :--- | :--- <index> | String | Comma-separated list of indices to update. To update all indices, use * or omit this parameter. -allow_no_indices | String | Whether to ignore wildcards that don’t match any indices. Default is true. +allow_no_indices | Boolean | Whether to ignore wildcards that don’t match any indices. Default is `true`. analyzer | String | Analyzer to use in the query string. analyze_wildcard | Boolean | Whether the update operation should include wildcard and prefix queries in the analysis. Default is false. conflicts | String | Indicates to OpenSearch what should happen if the update by query operation runs into a version conflict. Valid options are `abort` and `proceed`. Default is `abort`. diff --git a/_opensearch/rest-api/explain.md b/_opensearch/rest-api/explain.md index 1d56dbd7..cbc7c5b0 100644 --- a/_opensearch/rest-api/explain.md +++ b/_opensearch/rest-api/explain.md @@ -11,7 +11,7 @@ Introduced 1.0 Wondering why a specific document ranks higher (or lower) for a query? You can use the explain API for an explanation of how the relevance score (`_score`) is calculated for every result. -OpenSearch uses a probabilistic ranking framework called [Okapi BM25](https://en.wikipedia.org/wiki/Okapi_BM25) to calculate relevance scores. Okapi BM25 is based on the original [TF/IDF](http://lucene.apache.org/core/4_0_0/core/org/apache/lucene/search/package-summary.html#scoring) framework used by Apache Lucene. +OpenSearch uses a probabilistic ranking framework called [Okapi BM25](https://en.wikipedia.org/wiki/Okapi_BM25) to calculate relevance scores. Okapi BM25 is based on the original [TF/IDF](http://lucene.apache.org/core/{{site.lucene_version}}/core/org/apache/lucene/search/package-summary.html#scoring) framework used by Apache Lucene. The explain API is an expensive operation in terms of both resources and time. On production clusters, we recommend using it sparingly for the purpose of troubleshooting. {: .warning } diff --git a/_opensearch/rest-api/multi-search.md b/_opensearch/rest-api/multi-search.md index 674c222c..ecdfb26d 100644 --- a/_opensearch/rest-api/multi-search.md +++ b/_opensearch/rest-api/multi-search.md @@ -1,63 +1,94 @@ --- layout: default -title: Multi search +title: Multi-search parent: REST API reference nav_order: 130 --- -# Multi search +# Multi-search Introduced 1.0 {: .label .label-purple } -The multi-search operation lets you bundle multiple search requests and send them to your OpenSearch cluster in a single request. This operation executes searches in parallel, so you get back the response more quickly as compared to independent search requests. It also executes each request independently, so the failure of one request doesn't affect the others. +As the name suggests, the multi-search operation lets you bundle multiple search requests into a single request. OpenSearch then executes the searches in parallel, so you get back the response more quickly compared to sending one request per search. OpenSearch executes each search independently, so the failure of one doesn't affect the others. -The multi-search request body follows this pattern: - -``` -header\n -body\n -header\n -body\n -``` - -OpenSearch uses newline characters to parse multi-search requests and requires that each request ends with a newline character. ## Example ```json GET _msearch -{"index":"opensearch_dashboards_sample_data_logs"} -{"query":{"match_all":{}},"from":0,"size":10} -{"index":"opensearch_dashboards_sample_data_ecommerce","search_type":"dfs_query_then_fetch"} -{"query":{"match_all":{}}} +{ "index": "opensearch_dashboards_sample_data_logs"} +{ "query": { "match_all": {} }, "from": 0, "size": 10} +{ "index": "opensearch_dashboards_sample_data_ecommerce", "search_type": "dfs_query_then_fetch"} +{ "query": { "match_all": {} } } + ``` + ## Path and HTTP methods ``` -GET /_msearch +GET _msearch +GET /_msearch +POST _msearch +POST /_msearch ``` -## URL parameters -All multi-search URL parameters are optional. +## Request body -Parameter | Type | Description +The multi-search request body follows this pattern: + +``` +Metadata\n +Query\n +Metadata\n +Query\n + +``` + +- Metadata lines include options, such as which indices to search and the type of search. +- Query lines use the [query DSL]({{site.url}}{{site.baseurl}}/opensearch/query-dsl/). + +Just like the [bulk]({{site.url}}{{site.baseurl}}/opensearch/rest-api/document-apis/bulk/) operation, the JSON doesn't need to be minified---spaces are fine---but it does need to be on a single line. OpenSearch uses newline characters to parse multi-search requests and requires that the request body end with a newline character. + + +## URL parameters and metadata options + +All multi-search URL parameters are optional. Some can also be applied per-search as part of each metadata line. + +Parameter | Type | Description | Supported in metadata line :--- | :--- | :--- -`allow_no_indices` | Boolean | Whether to ignore wildcards that don't match any indices. Default is `true`. -`css_minimize_roundtrips` | Boolean | If true, network roundtrips between the local node and remote clusters are minimized for cross-cluster search requests. Default is `true`. -`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`. -`ignore_unavailable` | Boolean | If an index from the indices list doesn’t exist, whether to ignore it rather than fail the query. Default is `false`. -`max_concurrent_searches` | Integer | Maximum number of searches executed in parallel. Default is `max(1, (number of of data nodes * min(search thread pool size, 10)))`. -`max_concurrent_shard_requests` | Integer | Maximum number of concurrent shard requests that each sub-search request executes per node. Default is 5. If you have an environment where a very low number of concurrent search requests is expected, a higher value of this parameter might improve performance. -`pre_filter_shard_size` | Integer | Defines a threshold that enforces a round-trip to pre-filter search shards that cannot possibly match. This filter phase can limit the number of searched shards significantly. For instance, if a date range filter is applied, then all indices that don't contain documents within that date range are skipped. Default is 128. -`rest_total_hits_as_int` | String | Whether the `hits.total` property is returned as an integer or an object. Default is `false`. -`search_type` | String | Whether global term and document frequencies are used when calculating the relevance score. Valid choices are `query_then_fetch` and `dfs_query_then_fetch`. `query_then_fetch` scores documents using local term and document frequencies for the shard. It's usually faster but less accurate. `dfs_query_then_fetch` scores documents using global term and document frequencies across all shards. It's usually slower but more accurate. Default is `query_then_fetch`. -`typed_keys` | Boolean | Whether aggregation names are prefixed by their internal types in the response. Default is `false`. +allow_no_indices | Boolean | Whether to ignore wildcards that don't match any indices. Default is `true`. | Yes +css_minimize_roundtrips | Boolean | Whether OpenSearch should try to minimize the number of network round trips between the coordinating node and remote clusters (only applicable to cross-cluster search requests). Default is `true`. | No +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`. | Yes +ignore_unavailable | Boolean | If an index from the indices list doesn’t exist, whether to ignore it rather than fail the query. Default is `false`. | Yes +max_concurrent_searches | Integer | The maximum number of concurrent searches. The default depends on your node count and search thread pool size. Higher values can improve performance, but risk overloading the cluster. | No +max_concurrent_shard_requests | Integer | Maximum number of concurrent shard requests that each search executes per node. Default is 5. Higher values can improve performance, but risk overloading the cluster. | No +pre_filter_shard_size | Integer | Default is 128. | No +rest_total_hits_as_int | String | Whether the `hits.total` property is returned as an integer (`true`) or an object (`false`). Default is `false`. | No +search_type | String | Affects relevance score. Valid options are `query_then_fetch` and `dfs_query_then_fetch`. `query_then_fetch` scores documents using term and document frequencies for the shard (faster, less accurate), whereas `dfs_query_then_fetch` uses term and document frequencies across all shards (slower, more accurate). Default is `query_then_fetch`. | Yes +typed_keys | Boolean | Whether to prefix aggregation names with their internal types in the response. Default is `false`. | No + +{% comment %}Regarding `pre_filter_shard_size`: The description from the REST API specification is unintelligible---to me, anyway. I wasn't able to learn anything from reading the source code, either, so I've included the default value and nothing else in the table above. - aetter + +From the REST API specification: A threshold that enforces a pre-filter round trip to prefilter search shards based on query rewriting if the number of shards the search request expands to exceeds the threshold. This filter roundtrip can limit the number of shards significantly if for instance a shard can not match any documents based on its rewrite method ie. if date filters are mandatory to match but the shard bounds and the query are disjoint.{% endcomment %} + + +## Metadata-only options + +Some options can't be applied as URL parameters to the entire request. Instead, you can apply them per-search as part of each metadata line. All are optional. + +Option | Type | Description +:--- | :--- | :--- +index | String, string array | If you don't specify an index or multiple indices as part of the URL (or want to override the URL value for an individual search), you can include it here. Examples include `"logs-*"` and `["my-store", "sample_data_ecommerce"]`. +preference | String | The nodes or shards that you'd like to perform the search. This setting can be useful for testing, but in most situations, the default behavior provides the best search latencies. Options include `_local`, `_only_local`, `_prefer_nodes`, `_only_nodes`, and `_shards`. These last three options accept a list of nodes or shards. Examples include `"_only_nodes:data-node1,data-node2"` and `"_shards:0,1`. +request_cache | Boolean | Whether to cache results, which can improve latency for repeat searches. Default is to use the `index.requests.cache.enable` setting for the index (which defaults to `true` for new indices). +routing | String | Comma-separated custom routing values (e.g. `"routing": "value1,value2,value3"`. + ## Response -You get back the responses in an array form, where the search response for each search request matches its order in the original multi-search request. +OpenSearch returns an array with the results of each search in the same order as the multi-search request. ```json { diff --git a/_opensearch/rest-api/scroll.md b/_opensearch/rest-api/scroll.md index beffb655..42317200 100644 --- a/_opensearch/rest-api/scroll.md +++ b/_opensearch/rest-api/scroll.md @@ -98,7 +98,7 @@ 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. +rest_total_hits_as_int | Boolean | Whether the `hits.total` property is returned as an integer (`true`) or an object (`false`). Default is `false`. ## Response diff --git a/_opensearch/rest-api/update-mapping.md b/_opensearch/rest-api/update-mapping.md index 0108442f..d39fbcb0 100644 --- a/_opensearch/rest-api/update-mapping.md +++ b/_opensearch/rest-api/update-mapping.md @@ -47,7 +47,7 @@ All update mapping parameters are optional. Parameter | Data Type | Description :--- | :--- | :--- -allow_no_indices | Boolean | Whether to ignore wildcards that don’t match any indices. Default is true. +allow_no_indices | Boolean | Whether to ignore wildcards that don’t match any indices. Default is `true`. expand_wildcards | String | Expands wildcard expressions to different indices. Combine multiple values with commas. Available values are `all` (match all indices), `open` (match open indices), `closed` (match closed indices), `hidden` (match hidden indices), and `none` (do not accept wildcard expressions), which must be used with `open`, `closed`, or both. Default is `open`. ignore_unavailable | Boolean | If true, OpenSearch does not include missing or closed indices in the response. master_timeout | Time | How long to wait for a connection to the master node. Default is `30s`. diff --git a/_search-plugins/async/index.md b/_search-plugins/async/index.md index 552c6a96..2a3f51cf 100644 --- a/_search-plugins/async/index.md +++ b/_search-plugins/async/index.md @@ -194,12 +194,16 @@ For asynchronous searches with `keep_on_completion` as `true` and a sufficiently Introduced 1.0 {: .label .label-purple } -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. +To delete an asynchronous search: -```json +``` DELETE _plugins/_asynchronous_search/?pretty ``` +- If the search is still running, OpenSearch cancels it. +- If the search is complete, OpenSearch deletes the saved results. + + #### Sample response ```json diff --git a/_search-plugins/knn/approximate-knn.md b/_search-plugins/knn/approximate-knn.md index 9b32bc7a..90691b37 100644 --- a/_search-plugins/knn/approximate-knn.md +++ b/_search-plugins/knn/approximate-knn.md @@ -11,7 +11,7 @@ has_math: true The approximate k-NN method uses [nmslib's](https://github.com/nmslib/nmslib/) implementation of the Hierarchical Navigable Small World (HNSW) algorithm to power k-NN search. In this case, approximate means that for a given search, the neighbors returned are an estimate of the true k-nearest neighbors. Of the three methods, this method offers the best search scalability for large data sets. Generally speaking, once the data set gets into the hundreds of thousands of vectors, this approach is preferred. -The k-NN plugin builds an HNSW graph of the vectors for each "knn-vector field"/ "Lucene segment" pair during indexing that can be used to efficiently find the k-nearest neighbors to a query vector during search. To learn more about Lucene segments, please refer to [Apache Lucene's documentation](https://lucene.apache.org/core/8_7_0/core/org/apache/lucene/codecs/lucene87/package-summary.html#package.description). These graphs are loaded into native memory during search and managed by a cache. To learn more about pre-loading graphs into memory, refer to the [warmup API]({{site.url}}{{site.baseurl}}/search-plugins/knn/api#warmup-operation). Additionally, you can see what graphs are already loaded in memory, which you can learn more about in the [stats API section]({{site.url}}{{site.baseurl}}/search-plugins/knn/api#stats). +The k-NN plugin builds an HNSW graph of the vectors for each "knn-vector field"/ "Lucene segment" pair during indexing that can be used to efficiently find the k-nearest neighbors to a query vector during search. To learn more about Lucene segments, see the [Apache Lucene documentation](https://lucene.apache.org/core/{{site.lucene_version}}/core/org/apache/lucene/codecs/lucene87/package-summary.html#package.description). These graphs are loaded into native memory during search and managed by a cache. To learn more about pre-loading graphs into memory, refer to the [warmup API]({{site.url}}{{site.baseurl}}/search-plugins/knn/api#warmup-operation). Additionally, you can see what graphs are already loaded in memory, which you can learn more about in the [stats API section]({{site.url}}{{site.baseurl}}/search-plugins/knn/api#stats). Because the graphs are constructed during indexing, it is not possible to apply a filter on an index and then use this search method. All filters are applied on the results produced by the approximate nearest neighbor search. From 34068f01bd7e31856519c4dda0b1e9bd3153c647 Mon Sep 17 00:00:00 2001 From: aetter Date: Wed, 1 Sep 2021 16:29:19 -0700 Subject: [PATCH 042/167] Add note about enabling compatibility setting during upgrade --- _clients/agents-and-ingestion-tools/index.md | 6 ++++++ _upgrade-to/upgrade-to.md | 6 ++++++ 2 files changed, 12 insertions(+) diff --git a/_clients/agents-and-ingestion-tools/index.md b/_clients/agents-and-ingestion-tools/index.md index 7b9ca7fb..ed326279 100644 --- a/_clients/agents-and-ingestion-tools/index.md +++ b/_clients/agents-and-ingestion-tools/index.md @@ -27,6 +27,12 @@ PUT _cluster/settings } ``` +[Just like any other setting]({{site.url}}{{site.baseurl}}/opensearch/configuration/), the alternative is to add the following line to `opensearch.yml` on each node and then restart the node: + +```yml +compatibility.override_main_response_version: true +``` + ## Downloads diff --git a/_upgrade-to/upgrade-to.md b/_upgrade-to/upgrade-to.md index 1fed63f3..a415b621 100644 --- a/_upgrade-to/upgrade-to.md +++ b/_upgrade-to/upgrade-to.md @@ -144,6 +144,12 @@ If you are upgrading an Open Distro for Elasticsearch cluster, we recommend firs 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) If you're actively connecting to the cluster with legacy clients that check for a particular version number, such as Logstash OSS, add a [compatibility setting]({{site.url}}{{site.baseurl}}/clients/agents-and-ingestion-tools/) to `opensearch.yml`: + + ```yml + compatibility.override_main_response_version: true + ``` + 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). From b1d3a5906b578eb47985f357ca614ac1c0718860 Mon Sep 17 00:00:00 2001 From: Keith Chan <12404772+keithhc2@users.noreply.github.com> Date: Wed, 1 Sep 2021 19:13:23 -0700 Subject: [PATCH 043/167] Language tweaks to create-index --- _opensearch/rest-api/create-index.md | 22 +++++++++++----------- 1 file changed, 11 insertions(+), 11 deletions(-) diff --git a/_opensearch/rest-api/create-index.md b/_opensearch/rest-api/create-index.md index 38170c37..9ff027f0 100644 --- a/_opensearch/rest-api/create-index.md +++ b/_opensearch/rest-api/create-index.md @@ -83,9 +83,8 @@ index.number_of_routing_shards | The number of routing shards used to split an i 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.load_fixed_bitset_filters_eagerly | Whether OpenSearch should pre-load cached filters. 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 @@ -93,23 +92,24 @@ index.hidden | Whether the index should be hidden. Hidden indices are not return 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.auto_expand_replicas | Whether the cluster should automatically add replica shards based on the number of data nodes. 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_inner_result_window | aximum value of `from` + `size` to return nested search hits and most relevant document aggregated during the query. `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.max_script_fields | Maximum amount of`script_fields` allowed in a query. Default is 32. +index.max_ngram_diff | Maximum difference between `min_gram` and `max_gram` values for `NGramTokenizer` and `NGramTokenFilter` fields. Default is 1. +index.max_shingle_diff | Maximum difference between `max_shingle_size` and `min_shingle_size` to feed into the `shingle` token filter. Default is 3. +index.max_refresh_listeners | Maximum amount of refresh listeners each shard is allowed to have. 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.highlight.max_analyzed_offset | The amount of characters a highlight request can analyze. Default is 1000000. +index.max_terms_count | The maximum amount of terms a terms query can accept. 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.allocation.enable | Specifies options for the index’s shard allocation. Available options are all (allow allocation for all shards), primaries (allow allocation only for primary shards), new_primaries (allow allocation only for new primary shards), and none (do not allow allocation). Default is all. +index.routing.rebalance.enable - Shard rebalancing for the index. Available options are `all` (allow rebalancing for all shards), `primaries` (allow rebalancing only for primary shards), `replicas` (allow rebalancing only for replicas), and `none` (do not allow rebalancing). 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. From eaba608cfd2898cbf2554886568c6e2dc0ebc6d3 Mon Sep 17 00:00:00 2001 From: aetter Date: Tue, 7 Sep 2021 15:28:29 -0700 Subject: [PATCH 044/167] Update some Dashboards settings paths --- .../access-control/multi-tenancy.md | 20 +++++++++---------- .../access-control/users-roles.md | 2 +- 2 files changed, 11 insertions(+), 11 deletions(-) diff --git a/_security-plugin/access-control/multi-tenancy.md b/_security-plugin/access-control/multi-tenancy.md index 537841c2..5b7ed3f5 100644 --- a/_security-plugin/access-control/multi-tenancy.md +++ b/_security-plugin/access-control/multi-tenancy.md @@ -47,21 +47,21 @@ Setting | Description opensearch.username: kibanaserver opensearch.password: kibanaserver opensearch.requestHeadersWhitelist: ["securitytenant","Authorization"] -plugins.security.multitenancy.enabled: true -plugins.security.multitenancy.tenants.enable_global: true -plugins.security.multitenancy.tenants.enable_private: true -plugins.security.multitenancy.tenants.preferred: ["Private", "Global"] -plugins.security.multitenancy.enable_filter: false +opensearch_security.multitenancy.enabled: true +opensearch_security.multitenancy.tenants.enable_global: true +opensearch_security.multitenancy.tenants.enable_private: true +opensearch_security.multitenancy.tenants.preferred: ["Private", "Global"] +opensearch_security.multitenancy.enable_filter: false ``` Setting | Description :--- | :--- `opensearch.requestHeadersWhitelist` | OpenSearch Dashboards requires that you whitelist all HTTP headers that it passes to OpenSearch. Multi-tenancy uses a specific header, `securitytenant`, that must be present with the standard `Authorization` header. If the `securitytenant` header is not whitelisted, OpenSearch Dashboards starts with a red status. -`plugins.security.multitenancy.enabled` | Enables or disables multi-tenancy in OpenSearch Dashboards. Default is true. -`plugins.security.multitenancy.tenants.enable_global` | Enables or disables the global tenant. Default is true. -`plugins.security.multitenancy.tenants.enable_private` | Enables or disables the private tenant. Default is true. -`plugins.security.multitenancy.tenants.preferred` | Lets you change ordering in the **Tenants** tab of OpenSearch Dashboards. By default, the list starts with global and private (if enabled) and then proceeds alphabetically. You can add tenants here to move them to the top of the list. -`plugins.security.multitenancy.enable_filter` | If you have many tenants, you can add a search bar to the top of the list. Default is false. +`opensearch_security.multitenancy.enabled` | Enables or disables multi-tenancy in OpenSearch Dashboards. Default is true. +`opensearch_security.multitenancy.tenants.enable_global` | Enables or disables the global tenant. Default is true. +`opensearch_security.multitenancy.tenants.enable_private` | Enables or disables the private tenant. Default is true. +`opensearch_security.multitenancy.tenants.preferred` | Lets you change ordering in the **Tenants** tab of OpenSearch Dashboards. By default, the list starts with global and private (if enabled) and then proceeds alphabetically. You can add tenants here to move them to the top of the list. +`opensearch_security.multitenancy.enable_filter` | If you have many tenants, you can add a search bar to the top of the list. Default is false. ## Add tenants diff --git a/_security-plugin/access-control/users-roles.md b/_security-plugin/access-control/users-roles.md index 445e1e63..b4e58c7a 100644 --- a/_security-plugin/access-control/users-roles.md +++ b/_security-plugin/access-control/users-roles.md @@ -109,7 +109,7 @@ Role | Description `anomaly_full_access` | Grants full permissions to all anomaly detection actions. `anomaly_read_access` | Grants permissions to view detectors, but not create, modify, or delete detectors. `all_access` | Grants full access to the cluster: all cluster-wide operations, write to all indices, write to all tenants. -`kibana_read_only` | A special role that prevents users from making changes to visualizations, dashboards, and other OpenSearch Dashboards objects. See `plugins.security.readonly_mode.roles` in `opensearch_dashboards.yml`. Pair with the `kibana_user` role. +`kibana_read_only` | A special role that prevents users from making changes to visualizations, dashboards, and other OpenSearch Dashboards objects. See `opensearch_security.readonly_mode.roles` in `opensearch_dashboards.yml`. Pair with the `kibana_user` role. `kibana_user` | Grants permissions to use OpenSearch Dashboards: cluster-wide searches, index monitoring, and write to various OpenSearch Dashboards indices. `logstash` | Grants permissions for Logstash to interact with the cluster: cluster-wide searches, cluster monitoring, and write to the various Logstash indices. `manage_snapshots` | Grants permissions to manage snapshot repositories, take snapshots, and restore snapshots. From 243c7315e439bc4d08218c105e0d08424ee4a77f Mon Sep 17 00:00:00 2001 From: aetter Date: Wed, 8 Sep 2021 08:34:57 -0700 Subject: [PATCH 045/167] Update generate-certificates.md --- _security-plugin/configuration/generate-certificates.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/_security-plugin/configuration/generate-certificates.md b/_security-plugin/configuration/generate-certificates.md index 69945d7e..da73f7ec 100755 --- a/_security-plugin/configuration/generate-certificates.md +++ b/_security-plugin/configuration/generate-certificates.md @@ -42,10 +42,10 @@ You can optionally add the `-aes256` option to encrypt the key using the AES-256 Next, use the key to generate a self-signed certificate for the root CA: ```bash -openssl req -new -x509 -sha256 -key root-ca-key.pem -out root-ca.pem -days 30 +openssl req -new -x509 -sha256 -key root-ca-key.pem -out root-ca.pem -days 730 ``` -Change `-days 30` to 3650 (10 years) or some other number to set a non-default expiration date. The default value of 30 days is best for testing purposes. +The default `-days` value of 30 is only useful for testing purposes. This sample command specifies 730 (two years) for the certificate expiration date, but use whatever value makes sense for your organization. - The `-x509` option specifies that you want a self-signed certificate rather than a certificate request. - The `-sha256` option sets the hash algorithm to SHA-256. SHA-256 is the default in later versions of OpenSSL, but earlier versions might use SHA-1. @@ -78,7 +78,7 @@ Follow the prompts to fill in the details. You don't need to specify a challenge Finally, generate the certificate itself: ```bash -openssl x509 -req -in admin.csr -CA root-ca.pem -CAkey root-ca-key.pem -CAcreateserial -sha256 -out admin.pem -days 30 +openssl x509 -req -in admin.csr -CA root-ca.pem -CAkey root-ca-key.pem -CAcreateserial -sha256 -out admin.pem -days 730 ``` Just like the root certificate, use the `-days` option to specify an expiration date of longer than 30 days. From 2c713e43adf9ee0ac39679eb0c6b5c4067dcd085 Mon Sep 17 00:00:00 2001 From: aetter Date: Wed, 8 Sep 2021 10:08:33 -0700 Subject: [PATCH 046/167] Update index.md --- _opensearch/query-dsl/index.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/_opensearch/query-dsl/index.md b/_opensearch/query-dsl/index.md index 3d1b7de8..ac55e7ea 100644 --- a/_opensearch/query-dsl/index.md +++ b/_opensearch/query-dsl/index.md @@ -5,8 +5,11 @@ nav_order: 27 has_children: true redirect_from: - /opensearch/query-dsl/ + - /docs/opensearch/query-dsl/ --- +{%- comment -%}The `/docs/opensearch/query-dsl/` redirect is specifically to support the UI links in OpenSearch Dashboards 1.0.0.{%- endcomment -%} + # 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. From c507de5b9fb5ccc437cc815fd94f214e49855b00 Mon Sep 17 00:00:00 2001 From: aetter Date: Thu, 9 Sep 2021 11:22:13 -0700 Subject: [PATCH 047/167] Minor wording changes for Beats OSS --- _clients/agents-and-ingestion-tools/index.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/_clients/agents-and-ingestion-tools/index.md b/_clients/agents-and-ingestion-tools/index.md index ed326279..04adfb1e 100644 --- a/_clients/agents-and-ingestion-tools/index.md +++ b/_clients/agents-and-ingestion-tools/index.md @@ -38,7 +38,7 @@ compatibility.override_main_response_version: true You can download the OpenSearch output plugin for Logstash from [OpenSearch downloads](https://opensearch.org/downloads.html). The Logstash output plugin is compatible with OpenSearch and Elasticsearch OSS (7.10.2 or lower). -These versions of Beats offer the best compatibility with OpenSearch. For more information, see the [compatibility matrices](#compatibility-matrices). +These are the latest versions of Beats OSS with OpenSearch compatibility. For more information, see the [compatibility matrices](#compatibility-matrices). - [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) @@ -47,7 +47,7 @@ These versions of Beats offer the best compatibility with OpenSearch. For more i - [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) -Some users report compatibility issues with ingest pipelines on these versions of Beats. If you use ingest pipelines with OpenSearch, consider using the 7.10.2 versions of Beats OSS instead. +Some users report compatibility issues with ingest pipelines on these versions of Beats. If you use ingest pipelines with OpenSearch, consider using the 7.10.2 versions of Beats instead. {: .note } From 0b9f1973581ecfa81065ccaf06c9cacf1026b403 Mon Sep 17 00:00:00 2001 From: keithhc2 Date: Fri, 10 Sep 2021 11:57:30 -0700 Subject: [PATCH 048/167] Added security to ISM --- _im-plugin/ism/api.md | 2 +- _im-plugin/ism/security.md | 40 +++++++++++++++++++ .../access-control/users-roles.md | 2 + 3 files changed, 43 insertions(+), 1 deletion(-) create mode 100644 _im-plugin/ism/security.md diff --git a/_im-plugin/ism/api.md b/_im-plugin/ism/api.md index af139695..3f7e0d1c 100644 --- a/_im-plugin/ism/api.md +++ b/_im-plugin/ism/api.md @@ -2,7 +2,7 @@ layout: default title: ISM API parent: Index State Management -nav_order: 5 +nav_order: 20 --- # ISM API diff --git a/_im-plugin/ism/security.md b/_im-plugin/ism/security.md new file mode 100644 index 00000000..b996e319 --- /dev/null +++ b/_im-plugin/ism/security.md @@ -0,0 +1,40 @@ +--- +layout: default +title: ISM security +nav_order: 10 +parent: Index State Management +has_children: false +--- + +# ISM security + +Using the security plugin with index state management lets you limit non-admin users to certain actions. For example, you might want to set up your security such that a group of users can only read ISM policies, while others can create, delete, or change policies. + +All index state management data are protected as system indices, and only a super admin or an admin 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). + +## Basic permissions + +The security plugin comes with two built-in roles that cover most ISM use cases: `ism_read_access` and `ism_full_access`. For descriptions of each, see [Predefined roles]({{site.url}}{{site.baseurl}}/security-plugin/access-control/users-roles#predefined-roles). + +With security enabled, users not only need the correct index management permissions, but they also need permissions to relevant indices to execute [REST API]({{site.url}}{{site.baseurl}}/im-plugin/ism/api) calls. For example, if a user wants to use the REST API to attach a policy to an index named `system-logs`, they would need the necessary REST API permissions as well as access to `system-logs`. + +## (Advanced) Limit access by backend role + +You can use backend roles to configure fine-grained access to ISM policies and actions. For example, users of different departments in an organization might view different policies depending on what roles and permissions they are assigned. + +First, ensure 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). + +Use the REST API to enable the following setting: + +```json +PUT _cluster/settings +{ + "transient": { + "plugins.index_management.filter_by_backend_roles": "true" + } +} +``` + +With security enabled, only users who share at least one backend role can see and execute the policies and actions relevant to their roles. + +For example, consider a scenario with three users: `John` and `Jill`, who have the backend role `helpdesk_staff`, and `Jane`, who has the backend role `phone_operator`. `John` wants to create a policy that performs a rollup job on an index named `airline_data`, so `John` would need a backend role that has permissions to access that index, create relevant policies, and execute relevant actions, and `Jill` would be able to access the same index, policy, and job. However, `Jane` cannot access or edit those resources or actions. diff --git a/_security-plugin/access-control/users-roles.md b/_security-plugin/access-control/users-roles.md index 445e1e63..1422d972 100644 --- a/_security-plugin/access-control/users-roles.md +++ b/_security-plugin/access-control/users-roles.md @@ -121,6 +121,8 @@ Role | Description `reports_full_access` | Grants full permissions to reports. `asynchronous_search_full_access` | Grants full permissions to all asynchronous search actions. `asynchronous_search_read_access` | Grants permissions to view asynchronous searches, but not to submit, modify, or delete async searches. +`ism_read_access` | Grants users permissions to view policies and current index states, but they are unable to create, add, update, or remove policies. +`ism_full_access` | Grants full permissions to all ISM actions. For more detailed summaries of the permissions for each role, reference their action groups against the descriptions in [Default action groups]({{site.url}}{{site.baseurl}}/security-plugin/access-control/default-action-groups/). From b0301949812f929eb0d0dfc7d2a0933b8aea0e01 Mon Sep 17 00:00:00 2001 From: ashwinkumar12345 Date: Fri, 10 Sep 2021 14:25:00 -0700 Subject: [PATCH 049/167] incorporated feedback --- _opensearch/rest-api/count.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/_opensearch/rest-api/count.md b/_opensearch/rest-api/count.md index b7b6b12d..c3463a08 100644 --- a/_opensearch/rest-api/count.md +++ b/_opensearch/rest-api/count.md @@ -28,7 +28,7 @@ GET opensearch_dashboards_sample_data_logs/_count } ``` -You can also use the search API for the same result: +The following call to the search API produces equivalent results: ```json GET opensearch_dashboards_sample_data_logs/_search From 50f3fa51d84c99f38580da1bb91523f63874a798 Mon Sep 17 00:00:00 2001 From: aetter Date: Fri, 10 Sep 2021 15:01:43 -0700 Subject: [PATCH 050/167] Update python.md --- _clients/python.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/_clients/python.md b/_clients/python.md index cdc7dc29..bcb1ff93 100644 --- a/_clients/python.md +++ b/_clients/python.md @@ -14,7 +14,7 @@ The OpenSearch Python client provides a more natural syntax for interacting with To add the client to your project, install it using [pip](https://pip.pypa.io/): ```bash -pip install +pip install opensearch ``` Then import it like any other module: From ed8230cb02fafacfd531c8e15e422ecae79157a4 Mon Sep 17 00:00:00 2001 From: aetter Date: Tue, 14 Sep 2021 09:08:45 -0700 Subject: [PATCH 051/167] Update delay to milliseconds, page_size to integer --- _im-plugin/index-rollups/rollup-api.md | 60 +++++++++++++------------- 1 file changed, 30 insertions(+), 30 deletions(-) diff --git a/_im-plugin/index-rollups/rollup-api.md b/_im-plugin/index-rollups/rollup-api.md index 06df2e7a..07a06a41 100644 --- a/_im-plugin/index-rollups/rollup-api.md +++ b/_im-plugin/index-rollups/rollup-api.md @@ -90,36 +90,36 @@ You can specify the following options. Options | Description | Type | Required :--- | :--- |:--- |:--- | -`source_index` | The name of the detector. | `string` | Yes -`target_index` | Specify the target index that the rolled up data is ingested into. You could either create a new target index or use an existing index. The target index cannot be a combination of raw and rolled up data. | `string` | Yes -`schedule` | Schedule of the index rollup job which can be an interval or a cron expression. | `object` | Yes -`schedule.interval` | Specify the frequency of execution of the rollup job. | `object` | No -`schedule.interval.start_time` | Start time of the interval. | `timestamp` | Yes -`schedule.interval.period` | Define the interval period. | `string` | Yes -`schedule.interval.unit` | Specify the time unit of the interval. | `string` | Yes -`schedule.interval.cron` | Optionally, specify a cron expression to define therollup frequency. | `list` | No -`schedule.interval.cron.expression` | Specify a Unix cron expression. | `string` | Yes -`schedule.interval.cron.timezone` | Specify timezones as defined by the IANA Time Zone Database. Defaults to UTC. | `string` | No -`description` | Optionally, describe the rollup job. | `string` | No -`enabled` | When true, the index rollup job is scheduled. Default is true. | `boolean` | Yes -`continuous` | Specify whether or not the index rollup job continuously rolls up data forever or just executes over the current data set once and stops. Default is false. | `boolean` | Yes -`error_notification` | Set up a Mustache message template sent for error notifications. For example, if an index rollup job fails, the system sends a message to a Slack channel. | `object` | No -`page_size` | Specify the number of buckets to paginate through at a time while rolling up. | `number` | Yes -`delay` | Specify time value to delay execution of the index rollup job. | `time_unit` | No -`dimensions` | Specify aggregations to create dimensions for the roll up time window. | `object` | Yes -`dimensions.date_histogram` | Specify either fixed_interval or calendar_interval, but not both. Either one limits what you can query in the target index. | `object` | No -`dimensions.date_histogram.fixed_interval` | Specify the fixed interval for aggregations in milliseconds, seconds, minutes, hours, or days. | `string` | No -`dimensions.date_histogram.calendar_interval` | Specify the calendar interval for aggregations in minutes, hours, days, weeks, months, quarters, or years. | `string` | No -`dimensions.date_histogram.field` | Specify the date field used in date histogram aggregation. | `string` | No -`dimensions.date_histogram.timezone` | Specify the timezones as defined by the IANA Time Zone Database. The default is UTC. | `string` | No -`dimensions.terms` | Specify the term aggregations that you want to roll up. | `object` | No -`dimensions.terms.fields` | Specify terms aggregation for compatible fields. | `object` | No -`dimensions.histogram` | Specify the histogram aggregations that you want to roll up. | `object` | No -`dimensions.histogram.field` | Add a field for histogram aggregations. | `string` | Yes -`dimensions.histogram.interval` | Specify the histogram aggregation interval for the field. | `long` | Yes -`dimensions.metrics` | Specify a list of objects that represent the fields and metrics that you want to calculate. | `nested object` | No -`dimensions.metrics.field` | Specify the field that you want to perform metric aggregations on. | `string` | No -`dimensions.metrics.field.metrics` | Specify the metric aggregations you want to calculate for the field. | `multiple strings` | No +`source_index` | The name of the detector. | String | Yes +`target_index` | Specify the target index that the rolled up data is ingested into. You could either create a new target index or use an existing index. The target index cannot be a combination of raw and rolled up data. | String | Yes +`schedule` | Schedule of the index rollup job which can be an interval or a cron expression. | Object | Yes +`schedule.interval` | Specify the frequency of execution of the rollup job. | Object | No +`schedule.interval.start_time` | Start time of the interval. | Timestamp | Yes +`schedule.interval.period` | Define the interval period. | String | Yes +`schedule.interval.unit` | Specify the time unit of the interval. | String | Yes +`schedule.interval.cron` | Optionally, specify a cron expression to define therollup frequency. | List | No +`schedule.interval.cron.expression` | Specify a Unix cron expression. | String | Yes +`schedule.interval.cron.timezone` | Specify timezones as defined by the IANA Time Zone Database. Defaults to UTC. | String | No +`description` | Optionally, describe the rollup job. | String | No +`enabled` | When true, the index rollup job is scheduled. Default is true. | Boolean | Yes +`continuous` | Specify whether or not the index rollup job continuously rolls up data forever or just executes over the current data set once and stops. Default is false. | Boolean | Yes +`error_notification` | Set up a Mustache message template sent for error notifications. For example, if an index rollup job fails, the system sends a message to a Slack channel. | Object | No +`page_size` | Specify the number of buckets to paginate through at a time while rolling up. | Integer | Yes +`delay` | The number of milliseconds to delay execution of the index rollup job. | Long | No +`dimensions` | Specify aggregations to create dimensions for the roll up time window. | Object | Yes +`dimensions.date_histogram` | Specify either fixed_interval or calendar_interval, but not both. Either one limits what you can query in the target index. | Object | No +`dimensions.date_histogram.fixed_interval` | Specify the fixed interval for aggregations in milliseconds, seconds, minutes, hours, or days. | String | No +`dimensions.date_histogram.calendar_interval` | Specify the calendar interval for aggregations in minutes, hours, days, weeks, months, quarters, or years. | String | No +`dimensions.date_histogram.field` | Specify the date field used in date histogram aggregation. | String | No +`dimensions.date_histogram.timezone` | Specify the timezones as defined by the IANA Time Zone Database. The default is UTC. | String | No +`dimensions.terms` | Specify the term aggregations that you want to roll up. | Object | No +`dimensions.terms.fields` | Specify terms aggregation for compatible fields. | Object | No +`dimensions.histogram` | Specify the histogram aggregations that you want to roll up. | Object | No +`dimensions.histogram.field` | Add a field for histogram aggregations. | String | Yes +`dimensions.histogram.interval` | Specify the histogram aggregation interval for the field. | Long | Yes +`dimensions.metrics` | Specify a list of objects that represent the fields and metrics that you want to calculate. | Nested object | No +`dimensions.metrics.field` | Specify the field that you want to perform metric aggregations on. | String | No +`dimensions.metrics.field.metrics` | Specify the metric aggregations you want to calculate for the field. | Multiple strings | No #### Sample response From 125585f04e5207092b2ab19e0cf4368d813aedf9 Mon Sep 17 00:00:00 2001 From: aetter Date: Tue, 14 Sep 2021 09:10:35 -0700 Subject: [PATCH 052/167] OK fine we can call it a number --- _im-plugin/index-rollups/rollup-api.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/_im-plugin/index-rollups/rollup-api.md b/_im-plugin/index-rollups/rollup-api.md index 07a06a41..7aa878d3 100644 --- a/_im-plugin/index-rollups/rollup-api.md +++ b/_im-plugin/index-rollups/rollup-api.md @@ -104,7 +104,7 @@ Options | Description | Type | Required `enabled` | When true, the index rollup job is scheduled. Default is true. | Boolean | Yes `continuous` | Specify whether or not the index rollup job continuously rolls up data forever or just executes over the current data set once and stops. Default is false. | Boolean | Yes `error_notification` | Set up a Mustache message template sent for error notifications. For example, if an index rollup job fails, the system sends a message to a Slack channel. | Object | No -`page_size` | Specify the number of buckets to paginate through at a time while rolling up. | Integer | Yes +`page_size` | Specify the number of buckets to paginate through at a time while rolling up. | Number | Yes `delay` | The number of milliseconds to delay execution of the index rollup job. | Long | No `dimensions` | Specify aggregations to create dimensions for the roll up time window. | Object | Yes `dimensions.date_histogram` | Specify either fixed_interval or calendar_interval, but not both. Either one limits what you can query in the target index. | Object | No From 2a0cf500cc8de02f9f46a611707e789f88945e62 Mon Sep 17 00:00:00 2001 From: ashwinkumar12345 Date: Tue, 14 Sep 2021 11:10:11 -0700 Subject: [PATCH 053/167] updated helm project path --- _opensearch/install/helm.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/_opensearch/install/helm.md b/_opensearch/install/helm.md index a5bc7d50..55458626 100644 --- a/_opensearch/install/helm.md +++ b/_opensearch/install/helm.md @@ -31,16 +31,16 @@ The default Helm chart deploys a three-node cluster. We recommend that you have ## Install OpenSearch using Helm -1. Clone the [opensearch-devops](https://github.com/opensearch-project/opensearch-devops/) repository: +1. Clone the [helm-charts](https://github.com/opensearch-project/helm-charts) repository: ```bash - git clone https://github.com/opensearch-project/opensearch-devops.git + git clone https://github.com/opensearch-project/helm-charts ``` 1. Change to the `opensearch` directory: ```bash - cd Helm/opensearch + cd charts/opensearch ``` 1. Package the Helm chart: From 35a7b186fc0e1d955e28ca1e8ae9d69e306cee76 Mon Sep 17 00:00:00 2001 From: Keith Chan <12404772+keithhc2@users.noreply.github.com> Date: Tue, 14 Sep 2021 14:03:29 -0700 Subject: [PATCH 054/167] Fixed broken link --- _opensearch/rest-api/document-apis/update-by-query.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/_opensearch/rest-api/document-apis/update-by-query.md b/_opensearch/rest-api/document-apis/update-by-query.md index 0e66d1ae..bb7ebe2b 100644 --- a/_opensearch/rest-api/document-apis/update-by-query.md +++ b/_opensearch/rest-api/document-apis/update-by-query.md @@ -80,7 +80,7 @@ wait_for_active_shards | String | The number of shards that must be active befor ## Request body -To update your indices and documents by query, you must include a [query]({{site.baseurl}}{{site.url}}/opensearch/query-dsl/index) and a script in the request body that OpenSearch can run to update your documents. If you don't specify a query, then every document in the index gets updated. +To update your indices and documents by query, you must include a [query]({{site.url}}{{site.baseurl}}/opensearch/query-dsl/index) and a script in the request body that OpenSearch can run to update your documents. If you don't specify a query, then every document in the index gets updated. ```json { From a69440b2626e495f438468e1d064ed4821ccee40 Mon Sep 17 00:00:00 2001 From: keithhc2 Date: Wed, 15 Sep 2021 13:47:04 -0700 Subject: [PATCH 055/167] Addressed comments --- _im-plugin/ism/security.md | 40 ------------------ _im-plugin/refresh-analyzer/index.md | 2 +- _im-plugin/security.md | 41 +++++++++++++++++++ .../access-control/users-roles.md | 3 +- 4 files changed, 43 insertions(+), 43 deletions(-) delete mode 100644 _im-plugin/ism/security.md create mode 100644 _im-plugin/security.md diff --git a/_im-plugin/ism/security.md b/_im-plugin/ism/security.md deleted file mode 100644 index b996e319..00000000 --- a/_im-plugin/ism/security.md +++ /dev/null @@ -1,40 +0,0 @@ ---- -layout: default -title: ISM security -nav_order: 10 -parent: Index State Management -has_children: false ---- - -# ISM security - -Using the security plugin with index state management lets you limit non-admin users to certain actions. For example, you might want to set up your security such that a group of users can only read ISM policies, while others can create, delete, or change policies. - -All index state management data are protected as system indices, and only a super admin or an admin 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). - -## Basic permissions - -The security plugin comes with two built-in roles that cover most ISM use cases: `ism_read_access` and `ism_full_access`. For descriptions of each, see [Predefined roles]({{site.url}}{{site.baseurl}}/security-plugin/access-control/users-roles#predefined-roles). - -With security enabled, users not only need the correct index management permissions, but they also need permissions to relevant indices to execute [REST API]({{site.url}}{{site.baseurl}}/im-plugin/ism/api) calls. For example, if a user wants to use the REST API to attach a policy to an index named `system-logs`, they would need the necessary REST API permissions as well as access to `system-logs`. - -## (Advanced) Limit access by backend role - -You can use backend roles to configure fine-grained access to ISM policies and actions. For example, users of different departments in an organization might view different policies depending on what roles and permissions they are assigned. - -First, ensure 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). - -Use the REST API to enable the following setting: - -```json -PUT _cluster/settings -{ - "transient": { - "plugins.index_management.filter_by_backend_roles": "true" - } -} -``` - -With security enabled, only users who share at least one backend role can see and execute the policies and actions relevant to their roles. - -For example, consider a scenario with three users: `John` and `Jill`, who have the backend role `helpdesk_staff`, and `Jane`, who has the backend role `phone_operator`. `John` wants to create a policy that performs a rollup job on an index named `airline_data`, so `John` would need a backend role that has permissions to access that index, create relevant policies, and execute relevant actions, and `Jill` would be able to access the same index, policy, and job. However, `Jane` cannot access or edit those resources or actions. diff --git a/_im-plugin/refresh-analyzer/index.md b/_im-plugin/refresh-analyzer/index.md index d9beb9bb..641d3484 100644 --- a/_im-plugin/refresh-analyzer/index.md +++ b/_im-plugin/refresh-analyzer/index.md @@ -1,7 +1,7 @@ --- layout: default title: Refresh search analyzer -nav_order: 40 +nav_order: 50 has_children: false redirect_from: /im-plugin/refresh-analyzer/ has_toc: false diff --git a/_im-plugin/security.md b/_im-plugin/security.md new file mode 100644 index 00000000..2fa6d456 --- /dev/null +++ b/_im-plugin/security.md @@ -0,0 +1,41 @@ +--- +layout: default +title: Index management security +nav_order: 40 +has_children: false +--- + +# Index management security + +Using the security plugin with index management lets you limit non-admin users to certain actions. For example, you might want to set up your security such that a group of users can only read ISM policies, while others can create, delete, or change policies. + +All index management data are protected as system indices, and only a super admin or an admin 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). + +## Basic permissions + +The security plugin comes with one role that offers full access to index management: `index_management_full_access`. For a description of the role's permissions, see [Predefined roles]({{site.url}}{{site.baseurl}}/security-plugin/access-control/users-roles#predefined-roles). + +With security enabled, users not only need the correct index management permissions, but they also need permissions to execute actions to involved indices. For example, if a user wants to use the REST API to attach a policy that executes a transform job to an index named `system-logs`, they would need the permissions to attach a policy and execute a transform job, as well as access to `system-logs`. + +Finally, with the exceptions of Create Policy, Get Policy, and Delete Policy, users also need the `indices:admin/opensearch/ism/managedindex` permission to execute [ISM APIs]({{site.url}}{{site.baseurl}}/im-plugin/ism/api). + +## (Advanced) Limit access by backend role + +You can use backend roles to configure fine-grained access to index management policies and actions. For example, users of different departments in an organization might view different policies depending on what roles and permissions they are assigned. + +First, ensure 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). + +Use the REST API to enable the following setting: + +```json +PUT _cluster/settings +{ + "transient": { + "plugins.index_management.filter_by_backend_roles": "true" + } +} +``` + +With security enabled, only users who share at least one backend role can see and execute the policies and actions relevant to their roles. + +For example, consider a scenario with three users: `John` and `Jill`, who have the backend role `helpdesk_staff`, and `Jane`, who has the backend role `phone_operator`. `John` wants to create a policy that performs a rollup job on an index named `airline_data`, so `John` would need a backend role that has permissions to access that index, create relevant policies, and execute relevant actions, and `Jill` would be able to access the same index, policy, and job. However, `Jane` cannot access or edit those resources or actions. diff --git a/_security-plugin/access-control/users-roles.md b/_security-plugin/access-control/users-roles.md index 1422d972..86424304 100644 --- a/_security-plugin/access-control/users-roles.md +++ b/_security-plugin/access-control/users-roles.md @@ -121,8 +121,7 @@ Role | Description `reports_full_access` | Grants full permissions to reports. `asynchronous_search_full_access` | Grants full permissions to all asynchronous search actions. `asynchronous_search_read_access` | Grants permissions to view asynchronous searches, but not to submit, modify, or delete async searches. -`ism_read_access` | Grants users permissions to view policies and current index states, but they are unable to create, add, update, or remove policies. -`ism_full_access` | Grants full permissions to all ISM actions. +`index_management_full_access` | Grants full permissions to all index management actions, including ISM, transforms, and rollups. For more detailed summaries of the permissions for each role, reference their action groups against the descriptions in [Default action groups]({{site.url}}{{site.baseurl}}/security-plugin/access-control/default-action-groups/). From ba9f43262276530ada4eb08e1de7e6199d0a0426 Mon Sep 17 00:00:00 2001 From: aetter Date: Thu, 16 Sep 2021 14:38:01 -0700 Subject: [PATCH 056/167] Fix table --- _opensearch/rest-api/create-index.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/_opensearch/rest-api/create-index.md b/_opensearch/rest-api/create-index.md index 9ff027f0..87dc7591 100644 --- a/_opensearch/rest-api/create-index.md +++ b/_opensearch/rest-api/create-index.md @@ -96,10 +96,10 @@ index.auto_expand_replicas | Whether the cluster should automatically add replic 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 | aximum value of `from` + `size` to return nested search hits and most relevant document aggregated during the query. `from` is the starting index to search from, and `size` is the amount of top hits to return. Default is 100. +index.max_inner_result_window | Maximum value of `from` + `size` to return nested search hits and most relevant document aggregated during the query. `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_script_fields | Maximum amount of `script_fields` allowed in a query. Default is 32. index.max_ngram_diff | Maximum difference between `min_gram` and `max_gram` values for `NGramTokenizer` and `NGramTokenFilter` fields. Default is 1. index.max_shingle_diff | Maximum difference between `max_shingle_size` and `min_shingle_size` to feed into the `shingle` token filter. Default is 3. index.max_refresh_listeners | Maximum amount of refresh listeners each shard is allowed to have. @@ -109,12 +109,12 @@ index.max_terms_count | The maximum amount of terms a terms query can accept. De 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 allocation for all shards), primaries (allow allocation only for primary shards), new_primaries (allow allocation only for new primary shards), and none (do not allow allocation). Default is all. -index.routing.rebalance.enable - Shard rebalancing for the index. Available options are `all` (allow rebalancing for all shards), `primaries` (allow rebalancing only for primary shards), `replicas` (allow rebalancing only for replicas), and `none` (do not allow rebalancing). 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.routing.rebalance.enable | Enables shard rebalancing for the index. Available options are `all` (allow rebalancing for all shards), `primaries` (allow rebalancing only for primary shards), `replicas` (allow rebalancing only for replicas), and `none` (do not allow 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. From 21ae64aac987263d5700b843ee6502f22939b7b9 Mon Sep 17 00:00:00 2001 From: aetter Date: Fri, 17 Sep 2021 14:17:21 -0700 Subject: [PATCH 057/167] Move to h2 --- _security-plugin/configuration/generate-certificates.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/_security-plugin/configuration/generate-certificates.md b/_security-plugin/configuration/generate-certificates.md index da73f7ec..8206e2fa 100755 --- a/_security-plugin/configuration/generate-certificates.md +++ b/_security-plugin/configuration/generate-certificates.md @@ -91,7 +91,7 @@ Follow the steps in [Generate an admin certificate](#generate-an-admin-certifica If you generate node certificates and have `plugins.security.ssl.transport.enforce_hostname_verification` set to `true` (default), be sure to specify a common name (CN) for the certificate that matches the hostname of the intended node. If you want to use the same node certificate on all nodes (not recommended), set hostname verification to `false`. For more information, see [Configure TLS certificates]({{site.url}}{{site.baseurl}}/security-plugin/configuration/tls#advanced-hostname-verification-and-dns-lookup). -### Sample script +## Sample script If you already know the certificate details and don't want to specify them interactively, use the `-subj` option in your `root-ca.pem` and CSR commands. This script creates a root certificate, admin certificate, two node certificates, and a client certificate, all with an expiration dates of two years (730 days): From 538703d4227378c173565b5f30e5c56125eb9c3e Mon Sep 17 00:00:00 2001 From: keithhc2 Date: Fri, 17 Sep 2021 14:58:07 -0700 Subject: [PATCH 058/167] Changed transform to rollup --- _im-plugin/security.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/_im-plugin/security.md b/_im-plugin/security.md index 2fa6d456..d5d48ac6 100644 --- a/_im-plugin/security.md +++ b/_im-plugin/security.md @@ -15,7 +15,7 @@ All index management data are protected as system indices, and only a super admi The security plugin comes with one role that offers full access to index management: `index_management_full_access`. For a description of the role's permissions, see [Predefined roles]({{site.url}}{{site.baseurl}}/security-plugin/access-control/users-roles#predefined-roles). -With security enabled, users not only need the correct index management permissions, but they also need permissions to execute actions to involved indices. For example, if a user wants to use the REST API to attach a policy that executes a transform job to an index named `system-logs`, they would need the permissions to attach a policy and execute a transform job, as well as access to `system-logs`. +With security enabled, users not only need the correct index management permissions, but they also need permissions to execute actions to involved indices. For example, if a user wants to use the REST API to attach a policy that executes a rollup job to an index named `system-logs`, they would need the permissions to attach a policy and execute a rollup job, as well as access to `system-logs`. Finally, with the exceptions of Create Policy, Get Policy, and Delete Policy, users also need the `indices:admin/opensearch/ism/managedindex` permission to execute [ISM APIs]({{site.url}}{{site.baseurl}}/im-plugin/ism/api). From 05ba9198f60666f343e420d96b020ecf1a359588 Mon Sep 17 00:00:00 2001 From: ashwinkumar12345 Date: Mon, 20 Sep 2021 13:22:18 -0700 Subject: [PATCH 059/167] modified description --- _clients/go.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/_clients/go.md b/_clients/go.md index 6db260ac..46b359aa 100644 --- a/_clients/go.md +++ b/_clients/go.md @@ -6,7 +6,7 @@ nav_order: 80 # Go client -The OpenSearch Go client lets you programmatically interact with data in your OpenSearch cluster as part of your Go application. +The OpenSearch Go client lets you build a Go application that interacts with the data in your OpenSearch cluster. ## Setup From 6bf8a7d51aa1a745685d82fc7ab03d20f3b8c828 Mon Sep 17 00:00:00 2001 From: ashwinkumar12345 Date: Mon, 20 Sep 2021 13:27:13 -0700 Subject: [PATCH 060/167] minor change --- _clients/go.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/_clients/go.md b/_clients/go.md index 46b359aa..ac09a0c8 100644 --- a/_clients/go.md +++ b/_clients/go.md @@ -6,7 +6,7 @@ nav_order: 80 # Go client -The OpenSearch Go client lets you build a Go application that interacts with the data in your OpenSearch cluster. +The OpenSearch Go client lets you easily connect your Go application with the data in your OpenSearch cluster. ## Setup From 54a0b8e755b2f4873f99163949fd60fd0780f96d Mon Sep 17 00:00:00 2001 From: ashwinkumar12345 Date: Mon, 20 Sep 2021 13:29:58 -0700 Subject: [PATCH 061/167] minor change --- _clients/go.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/_clients/go.md b/_clients/go.md index ac09a0c8..75ee300e 100644 --- a/_clients/go.md +++ b/_clients/go.md @@ -6,7 +6,7 @@ nav_order: 80 # Go client -The OpenSearch Go client lets you easily connect your Go application with the data in your OpenSearch cluster. +The OpenSearch Go client lets you connect your Go application with the data in your OpenSearch cluster. ## Setup From 3c98e4b2970464d5c04e0bd2d4d261e07340e463 Mon Sep 17 00:00:00 2001 From: keithhc2 Date: Mon, 20 Sep 2021 16:06:09 -0700 Subject: [PATCH 062/167] Modified monitoring to have two kinds of monitors --- _monitoring-plugins/alerting/api.md | 268 ++++++++++++++++++++++- _monitoring-plugins/alerting/monitors.md | 81 ++++--- 2 files changed, 311 insertions(+), 38 deletions(-) diff --git a/_monitoring-plugins/alerting/api.md b/_monitoring-plugins/alerting/api.md index 0799878a..146f2d9a 100644 --- a/_monitoring-plugins/alerting/api.md +++ b/_monitoring-plugins/alerting/api.md @@ -19,10 +19,11 @@ Use the alerting API to programmatically manage monitors and alerts. --- -## Create monitor +## Create query-level monitor Introduced 1.0 {: .label .label-purple } + #### Request ```json @@ -30,6 +31,7 @@ POST _plugins/_alerting/monitors { "type": "monitor", "name": "test-monitor", + "monitor_type": "query_level_monitor", "enabled": true, "schedule": { "period": { @@ -166,7 +168,7 @@ If you use a custom webhook for your destination and need to embed JSON in the m }, "throttle_enabled": false, "subject_template": { - "source": "TheSubject", + "source": "Subject", "lang": "mustache" } }] @@ -186,6 +188,7 @@ The following example creates a monitor that runs at 12:10 PM Pacific Time on th { "type": "monitor", "name": "test-monitor", + "monitor_type": "query_level_monitor", "enabled": true, "schedule": { "cron" : { @@ -228,7 +231,7 @@ The following example creates a monitor that runs at 12:10 PM Pacific Time on th "name": "test-action", "destination_id": "ld7912sBlQ5JUWWFThoW", "message_template": { - "source": "This is my message body." + "source": "This is a message body." }, "throttle_enabled": true, "throttle": { @@ -236,7 +239,7 @@ The following example creates a monitor that runs at 12:10 PM Pacific Time on th "unit": "MINUTES" }, "subject_template": { - "source": "TheSubject" + "source": "Subject" } }] }] @@ -247,6 +250,263 @@ For a full list of timezone names, refer to [Wikipedia](https://en.wikipedia.org --- +## Create bucket-level monitor + +```json +POST _plugins/_alerting/monitors +{ + "type": "monitor", + "name": "test-bucket-level-monitor", + "monitor_type": "bucket_level_monitor", + "enabled": true, + "schedule": { + "period": { + "interval": 1, + "unit": "MINUTES" + } + }, + "inputs": [ + { + "search": { + "indices": [ + "movies" + ], + "query": { + "size": 0, + "query": { + "bool": { + "filter": [ + { + "range": { + "order_date": { + "from": "{{period_end}}||-1h", + "to": "{{period_end}}", + "include_lower": true, + "include_upper": true, + "format": "epoch_millis" + } + } + } + ] + } + }, + "aggregations": { + "composite_agg": { + "composite": { + "sources": [ + { + "user": { + "terms": { + "field": "user" + } + } + } + ] + }, + "aggregations": { + "avg_products_base_price": { + "avg": { + "field": "products.base_price" + } + } + } + } + } + } + } + } + ], + "triggers": [ + { + "bucket_level_trigger": { + "name": "test-trigger", + "severity": "1", + "condition": { + "buckets_path": { + "_count": "_count", + "avg_products_base_price": "avg_products_base_price" + }, + "parent_bucket_path": "composite_agg", + "script": { + "source": "params._count > 50 || params.avg_products_base_price < 35", + "lang": "painless" + } + }, + "actions": [ + { + "name": "test-action", + "destination_id": "E4o5hnsB6KjPKmHtpfCA", + "message_template": { + "source": """Monitor {{ctx.monitor.name}} just entered alert status. Please investigate the issue. - Trigger: {{ctx.trigger.name}} - Severity: {{ctx.trigger.severity}} - Period start: {{ctx.periodStart}} - Period end: {{ctx.periodEnd}} - Deduped Alerts: {{ctx.dedupedAlerts}} * {{id}} : {{bucket_keys}} {{ctx.dedupedAlerts}} - New Alerts: {{ctx.newAlerts}} * {{id}} : {{bucket_keys}} {{ctx.newAlerts}} - Completed Alerts: {{ctx.completedAlerts}} * {{id}} : {{bucket_keys}} {{ctx.completedAlerts}}""", + "lang": "mustache" + }, + "throttle_enabled": false, + "action_execution_policy": { + "throttle": { + "value": 10, + "unit": "MINUTES" + }, + "action_execution_scope": { + "per_alert": { + "actionable_alerts": [ + "DEDUPED", + "NEW" + ] + } + } + }, + "subject_template": { + "source": "Sample subject", + "lang": "mustache" + } + } + ] + } + } + ] +} +``` + +#### Sample response +```json +{ + "_id" : "Dfxr63sBwex6DxEhHV5N", + "_version" : 1, + "_seq_no" : 3, + "_primary_term" : 1, + "monitor" : { + "type" : "monitor", + "schema_version" : 4, + "name" : "test-bucket-level-monitor", + "monitor_type" : "bucket_level_monitor", + "user" : { + "name" : "", + "backend_roles" : [ ], + "roles" : [ ], + "custom_attribute_names" : [ ], + "user_requested_tenant" : null + }, + "enabled" : true, + "enabled_time" : 1631742270785, + "schedule" : { + "period" : { + "interval" : 1, + "unit" : "MINUTES" + } + }, + "inputs" : [ + { + "search" : { + "indices" : [ + "opensearch_dashboards_sample_data_flights" + ], + "query" : { + "size" : 0, + "query" : { + "bool" : { + "filter" : [ + { + "range" : { + "order_date" : { + "from" : "{{period_end}}||-1h", + "to" : "{{period_end}}", + "include_lower" : true, + "include_upper" : true, + "format" : "epoch_millis", + "boost" : 1.0 + } + } + } + ], + "adjust_pure_negative" : true, + "boost" : 1.0 + } + }, + "aggregations" : { + "composite_agg" : { + "composite" : { + "size" : 10, + "sources" : [ + { + "user" : { + "terms" : { + "field" : "user", + "missing_bucket" : false, + "order" : "asc" + } + } + } + ] + }, + "aggregations" : { + "avg_products_base_price" : { + "avg" : { + "field" : "products.base_price" + } + } + } + } + } + } + } + } + ], + "triggers" : [ + { + "bucket_level_trigger" : { + "id" : "C_xr63sBwex6DxEhHV5B", + "name" : "test-trigger", + "severity" : "1", + "condition" : { + "buckets_path" : { + "_count" : "_count", + "avg_products_base_price" : "avg_products_base_price" + }, + "parent_bucket_path" : "composite_agg", + "script" : { + "source" : "params._count > 50 || params.avg_products_base_price < 35", + "lang" : "painless" + }, + "gap_policy" : "skip" + }, + "actions" : [ + { + "id" : "DPxr63sBwex6DxEhHV5B", + "name" : "test-action", + "destination_id" : "E4o5hnsB6KjPKmHtpfCA", + "message_template" : { + "source" : "Monitor {{ctx.monitor.name}} just entered alert status. Please investigate the issue. - Trigger: {{ctx.trigger.name}} - Severity: {{ctx.trigger.severity}} - Period start: {{ctx.periodStart}} - Period end: {{ctx.periodEnd}} - Deduped Alerts: {{ctx.dedupedAlerts}} * {{id}} : {{bucket_keys}} {{ctx.dedupedAlerts}} - New Alerts: {{ctx.newAlerts}} * {{id}} : {{bucket_keys}} {{ctx.newAlerts}} - Completed Alerts: {{ctx.completedAlerts}} * {{id}} : {{bucket_keys}} {{ctx.completedAlerts}}", + "lang" : "mustache" + }, + "throttle_enabled" : false, + "subject_template" : { + "source" : "The Subject", + "lang" : "mustache" + }, + "throttle" : { + "value" : 10, + "unit" : "MINUTES" + }, + "action_execution_policy" : { + "action_execution_scope" : { + "per_alert" : { + "actionable_alerts" : [ + "DEDUPED", + "NEW" + ] + } + } + } + } + ] + } + } + ], + "last_update_time" : 1631742270785 + } +} +``` + ## Update monitor Introduced 1.0 {: .label .label-purple } diff --git a/_monitoring-plugins/alerting/monitors.md b/_monitoring-plugins/alerting/monitors.md index 85138490..085eafc7 100644 --- a/_monitoring-plugins/alerting/monitors.md +++ b/_monitoring-plugins/alerting/monitors.md @@ -19,11 +19,11 @@ has_children: false Term | Definition :--- | :--- -Monitor | A job that runs on a defined schedule and queries OpenSearch. The results of these queries are then used as input for one or more *triggers*. +Monitor | A job that runs on a defined schedule and queries OpenSearch indices. The results of these queries are then used as input for one or more *triggers*. Trigger | Conditions that, if met, generate *alerts*. Alert | An event associated with a trigger. When an alert is created, the trigger performs *actions*, which can include sending a notification. Action | The information that you want the monitor to send out after being triggered. Actions have a *destination*, a message subject, and a message body. -Destination | A reusable location for an action, such as Amazon Chime, Slack, or a webhook URL. +Destination | A reusable location for an action. Supported locations are Amazon Chime, Email, Slack, or custom webhook. --- @@ -34,9 +34,9 @@ Destination | A reusable location for an action, such as Amazon Chime, Slack, or 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). -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 [Amazon Chime](https://docs.aws.amazon.com/chime/latest/ug/webhooks.html). +For Email, refer to the [Email as a destination](#email-as-a-destination) section below. For all other types, specify the webhook URL. See the documentation for [Slack](https://api.slack.com/incoming-webhooks) and [Amazon Chime](https://docs.aws.amazon.com/chime/latest/ug/webhooks.html) to learn more about webhooks. -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 `. You might also need to change `Content-Type` to whatever your webhook requires. Popular values are `application/json`, `application/xml`, and `text/plain`. +If you're using 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 `. 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. @@ -55,7 +55,7 @@ To configure a sender email, do the following: 1. After you choose **Email** as the destination type, choose **Manage senders**. 1. Choose **Add sender**, **New sender** and enter a unique name. 1. Enter the email address, SMTP host (e.g. `smtp.gmail.com` for a Gmail account), and the port. -1. Choose an encryption method, or use the default value of **None**. However, most email providers require SSL or TLS, which requires a username and password in OpenSearch keystore. Refer to [Authenticate sender account](#authenticate-sender-account) to learn more. +1. Choose an encryption method, or use the default value of **None**. However, most email providers require SSL or TLS, which require a username and password in OpenSearch keystore. Refer to [Authenticate sender account](#authenticate-sender-account) to learn more. 1. Choose **Save** to save the configuration and create the sender. You can create a sender even before you add your credentials to the OpenSearch keystore. However, you must [authenticate each sender account](#authenticate-sender-account) before you use the destination to send your alert. You can reuse senders across many different destinations, but each destination only supports one sender. @@ -101,20 +101,9 @@ POST _nodes/reload_secure_settings 1. Choose **Alerting**, **Monitors**, **Create monitor**. 1. Specify a name for the monitor. +1. Choose either **Per query monitor** or **Per bucket monitor**. -The anomaly detection option is for pairing with the anomaly detection plugin. See [Anomaly Detection]({{site.url}}{{site.baseurl}}/monitoring-plugins/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. - -To avoid this issue, make sure the alerting monitor is at least twice the detector interval. -When you create a monitor using OpenSearch Dashboards, the anomaly detector plugin generates a default monitor schedule that's twice the detector interval. - -Whenever you update a detector’s interval, make sure to update the associated monitor interval as well, as the anomaly detection plugin does not do this automatically. - -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/). +Whereas per query monitors run your specifed query and then check whether the query's results triggers any alerts, per bucket monitors let you select fields to create buckets and categorize your results into those buckets. Doing so gives you finer control over which results should trigger alerts, and trigger conditions get evaluated per bucket. 1. Define the monitor in one of three ways: visually, using a query, or using an anomaly detector. @@ -170,27 +159,45 @@ Whenever you update a detector’s interval, make sure to update the associated "Start" and "end" refer to the interval at which the monitor runs. See [Available variables](#available-variables). -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. - - 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 **Create**. +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/). + + To define a monitor visually, choose **Visual editor**. Then choose an aggregation (for example, `count()` or `average()`), a set of documents, a timeframe, a data filter if you want to monitor a subset of your source index, and a group-by field if you want to categorize your query results into separate buckets, and trigger conditions get evaluated per bucket. At least one group-by field is required if you are creating a per bucket monitor. Visual definition works well for most monitors. + + To use a query, choose **Extraction query editor**, add your query (using [the OpenSearch query DSL]({{site.url}}{{site.baseurl}}/opensearch/query-dsl/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 **Anomaly detector** and select your **Detector**. + + The anomaly detection option is for pairing with the anomaly detection plugin. See [Anomaly Detection]({{site.url}}{{site.baseurl}}/monitoring-plugins/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. + + To avoid this issue, make sure the alerting monitor is at least twice the detector interval. + When you create a monitor using OpenSearch Dashboards, the anomaly detector plugin generates a default monitor schedule that's twice the detector interval. + + Whenever you update a detector’s interval, make sure to update the associated monitor interval as well, as the anomaly detection plugin does not do this automatically. + + **Note**: Anomaly detection is available only if you are defining a per query monitor. + {: .note} + +1. Add a trigger to your monitor. --- ## Create triggers -The next step in creating a monitor is to create a trigger. These steps differ depending on whether you chose **Define using visual graph** or **Define using extraction query** or **Define using Anomaly detector** when you created the monitor. +Steps to create a trigger differ depending on whether you chose **Visual editor**, **Extraction query editor**, or **Anomaly detector** when you created the monitor. -Either way, you begin by specifying a name and severity level for the trigger. Severity levels help you manage alerts. A trigger with a high severity level (e.g. 1) might page a specific individual, whereas a trigger with a low severity level might message a chat room. +You begin by specifying a name and severity level for the trigger. Severity levels help you manage alerts. A trigger with a high severity level (e.g. 1) might page a specific individual, whereas a trigger with a low severity level might message a chat room. -### Visual graph +### Visual editor For **Trigger condition**, specify a threshold for the aggregation and timeframe you chose earlier, such as "is below 1,000" or "is exactly 10." @@ -264,11 +271,11 @@ 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` | Object | 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` | Object | 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.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. +`ctx.monitor.schedule` | Object | Contains a schedule of how often or when the monitor should run. `ctx.monitor.schedule.period.interval` | Integer | The interval at which the monitor runs. `ctx.monitor.schedule.period.unit` | String | The interval's unit of time. `ctx.monitor.inputs` | Array | An array that contains the indices and definition used to create the monitor. @@ -282,7 +289,7 @@ Variable | Data Type | Description `ctx.trigger.id` | String | The trigger's ID. `ctx.trigger.name` | String | The trigger's name. `ctx.trigger.severity` | String | The trigger's severity. -`ctx.trigger.condition`| JSON | Contains the Painless script used when creating the monitor. +`ctx.trigger.condition`| Object | Contains the Painless script used when creating the monitor. `ctx.trigger.condition.script.source` | String | The language used to define the script. Must be painless. `ctx.trigger.condition.script.lang` | String | The script used to define the trigger. `ctx.trigger.actions`| Array | An array with one element that contains information about the action the monitor needs to trigger. @@ -309,7 +316,13 @@ Variable | Data Type | Description `ctx.periodStart` | String | Unix timestamp for the beginning of the period during which the alert triggered. For example, if a monitor runs every ten minutes, a period might begin at 10:40 and end at 10:50. `ctx.periodEnd` | String | The end of the period during which the alert triggered. `ctx.error` | String | The error message if the trigger was unable to retrieve results or unable to evaluate the trigger, typically due to a compile error or null pointer exception. Null otherwise. -`ctx.alert` | JSON | The current, active alert (if it exists). Includes `ctx.alert.id`, `ctx.alert.version`, and `ctx.alert.isAcknowledged`. Null if no alert is active. +`ctx.alert` | Object | The current, active alert (if it exists). Includes `ctx.alert.id`, `ctx.alert.version`, and `ctx.alert.isAcknowledged`. Null if no alert is active. +`ctx.dedupedAlerts` | Object | Alerts that have already been triggered. OpenSearch keeps the existing alert to prevent the plugin from creating endless amounts of the same alerts. Only available with bucket-level monitors. +`ctx.newAlerts` | Object | Newly created alerts. Only available with bucket-level monitors. +`ctx.completedAlerts` | Object | Alerts that are no longer ongoing. Only available with bucket-level monitors. +`bucket_keys` | String | Comma-separated list of the monitor's bucket key values. Available only for `ctx.dedupedAlerts`, `ctx.newAlerts`, and `ctx.completedAlerts`. Accessed through `ctx.dedupedAlerts[0].bucket_keys`. +`parent_bucket_path` | String | The parent bucket path of the bucket that triggered the alert. Accessed through `ctx.dedupedAlerts[0].parent_bucket_path`. + --- From 4ffdce637741c9b0bd8d5c3ea1a98277343d30a4 Mon Sep 17 00:00:00 2001 From: aetter Date: Tue, 21 Sep 2021 11:34:44 -0700 Subject: [PATCH 063/167] Minor improvements Troubleshooting expired certificates, settings, broken link, etc. --- _monitoring-plugins/pa/dashboards.md | 2 +- _monitoring-plugins/pa/index.md | 4 ++-- _opensearch/configuration.md | 8 +++++++ _troubleshoot/index.md | 31 +++++++++++++++++++--------- 4 files changed, 32 insertions(+), 13 deletions(-) diff --git a/_monitoring-plugins/pa/dashboards.md b/_monitoring-plugins/pa/dashboards.md index 2d8c9ec9..561f6fa3 100644 --- a/_monitoring-plugins/pa/dashboards.md +++ b/_monitoring-plugins/pa/dashboards.md @@ -1,6 +1,6 @@ --- layout: default -title: Create Dashboards +title: Create PerfTop Dashboards parent: Performance Analyzer nav_order: 2 --- diff --git a/_monitoring-plugins/pa/index.md b/_monitoring-plugins/pa/index.md index c83df772..006af045 100644 --- a/_monitoring-plugins/pa/index.md +++ b/_monitoring-plugins/pa/index.md @@ -48,11 +48,11 @@ Otherwise, just specify the OpenSearch endpoint: ./opensearch-perf-top-macos --dashboard dashboards/.json --endpoint my-cluster.my-domain.com ``` -PerfTop has four pre-built dashboards in the `dashboards` directory, but you can also [create your own]({{site.url}}{{site.baseurl}}/dashboards/). +PerfTop has four pre-built dashboards in the `dashboards` directory, but you can also [create your own]({{site.url}}{{site.baseurl}}/monitoring-plugins/pa/dashboards/). You can also load the pre-built dashboards (ClusterOverview, ClusterNetworkMemoryAnalysis, ClusterThreadAnalysis, or NodeAnalysis) without the JSON files, such as `--dashboard ClusterThreadAnalysis`. -PerfTop has no interactivity. Start the application, monitor the dashboard, and press esc, q, or Ctrl + C to quit. +PerfTop has no interactivity. Start the application, monitor the dashboard, and press Esc, Q, or Ctrl + C to quit. {: .note } diff --git a/_opensearch/configuration.md b/_opensearch/configuration.md index a6a0f995..d28767bf 100755 --- a/_opensearch/configuration.md +++ b/_opensearch/configuration.md @@ -65,4 +65,12 @@ PUT _cluster/settings You can find `opensearch.yml` in `/usr/share/opensearch/config/opensearch.yml` (Docker) or `/etc/opensearch/opensearch.yml` (most Linux distributions) on each node. +You don't mark settings in `opensearch.yml` as persistent or transient, and settings use the flat form: + +```yml +cluster.name: my-application +action.auto_create_index: true +compatibility.override_main_response_version: true +``` + The demo configuration includes a number of settings for the security plugin that you should modify before using OpenSearch for a production workload. To learn more, see [Security]({{site.url}}{{site.baseurl}}/security-plugin/). diff --git a/_troubleshoot/index.md b/_troubleshoot/index.md index 76a03551..fc11a6b6 100644 --- a/_troubleshoot/index.md +++ b/_troubleshoot/index.md @@ -11,16 +11,32 @@ redirect_from: /troubleshoot/ This page contains a list of common issues and workarounds. -## Java error during startup - -You might see `[ERROR][c.a.o.s.s.t.OpenSearchSecuritySSLNettyTransport] [opensearch-node1] SSL Problem Insufficient buffer remaining for AEAD cipher fragment (2). Needs to be more than tag size (16)` when starting OpenSearch. This problem is a [known issue with Java](https://bugs.openjdk.java.net/browse/JDK-8221218) and doesn't affect the operation of the cluster. - - ## OpenSearch Dashboards fails to start If you encounter the error `FATAL Error: Request Timeout after 30000ms` during startup, try running OpenSearch Dashboards on a more powerful machine. We recommend four CPU cores and 8 GB of RAM. +## Multi-tenancy issues in OpenSearch Dashboards + +If you're testing multiple users in OpenSearch Dashboards and encounter unexpected changes in tenant, use Google Chrome in an Incognito window or Firefox in a Private window. + + +## Expired certificates + +If your certificates have expired, you might receive the following error or something similar: + +``` +ERROR org.opensearch.security.ssl.transport.SecuritySSLNettyTransport - Exception during establishing a SSL connection: javax.net.ssl.SSLHandshakeException: PKIX path validation failed: java.security.cert.CertPathValidatorException: validity check failed +Caused by: java.security.cert.CertificateExpiredException: NotAfter: Thu Sep 16 11:27:55 PDT 2021 +``` + +To check the expiration date for a certificate, run this command: + +```bash +openssl x509 -enddate -noout -in +``` + + ## Encryption at rest The operating system for each OpenSearch node handles encryption of data at rest. To enable encryption at rest in most Linux distributions, use the `cryptsetup` command: @@ -85,8 +101,3 @@ The security plugin blocks the update by script operation (`POST /_update ## Illegal reflective access operation in logs This is a known issue with Performance Analyzer that shouldn't affect functionality. - - -## Multi-tenancy issues in OpenSearch Dashboards - -If you're testing multiple users in OpenSearch Dashboards and encounter unexpected changes in tenant, use Google Chrome in an Incognito window or Firefox in a Private window. From 30378f0076a0a09859233a28f5fe2085165b5ded Mon Sep 17 00:00:00 2001 From: aetter Date: Tue, 21 Sep 2021 12:34:59 -0700 Subject: [PATCH 064/167] Sentence case access control page names --- _security-plugin/access-control/api.md | 2 +- _security-plugin/access-control/cross-cluster-search.md | 4 ++-- _security-plugin/access-control/default-action-groups.md | 4 ++-- _security-plugin/access-control/document-level-security.md | 4 ++-- _security-plugin/access-control/field-level-security.md | 4 ++-- _security-plugin/access-control/field-masking.md | 4 ++-- _security-plugin/access-control/impersonation.md | 4 ++-- _security-plugin/access-control/index.md | 2 +- _security-plugin/access-control/multi-tenancy.md | 4 ++-- _security-plugin/access-control/permissions.md | 2 +- _security-plugin/access-control/users-roles.md | 4 ++-- 11 files changed, 19 insertions(+), 19 deletions(-) diff --git a/_security-plugin/access-control/api.md b/_security-plugin/access-control/api.md index f3c0c685..19dd46ec 100644 --- a/_security-plugin/access-control/api.md +++ b/_security-plugin/access-control/api.md @@ -1,7 +1,7 @@ --- layout: default title: API -parent: Access Control +parent: Access control nav_order: 90 --- diff --git a/_security-plugin/access-control/cross-cluster-search.md b/_security-plugin/access-control/cross-cluster-search.md index 288c82ff..060ad624 100644 --- a/_security-plugin/access-control/cross-cluster-search.md +++ b/_security-plugin/access-control/cross-cluster-search.md @@ -1,7 +1,7 @@ --- layout: default -title: Cross-Cluster Search -parent: Access Control +title: Cross-cluster search +parent: Access control nav_order: 40 --- diff --git a/_security-plugin/access-control/default-action-groups.md b/_security-plugin/access-control/default-action-groups.md index a8793aff..025791b6 100644 --- a/_security-plugin/access-control/default-action-groups.md +++ b/_security-plugin/access-control/default-action-groups.md @@ -1,7 +1,7 @@ --- layout: default -title: Default Action Groups -parent: Access Control +title: Default action groups +parent: Access control nav_order: 51 --- diff --git a/_security-plugin/access-control/document-level-security.md b/_security-plugin/access-control/document-level-security.md index 04db5fa2..a6d9390f 100644 --- a/_security-plugin/access-control/document-level-security.md +++ b/_security-plugin/access-control/document-level-security.md @@ -1,7 +1,7 @@ --- layout: default -title: Document-Level Security -parent: Access Control +title: Document-level security +parent: Access control nav_order: 10 --- diff --git a/_security-plugin/access-control/field-level-security.md b/_security-plugin/access-control/field-level-security.md index b79dc7ec..e306c951 100644 --- a/_security-plugin/access-control/field-level-security.md +++ b/_security-plugin/access-control/field-level-security.md @@ -1,7 +1,7 @@ --- layout: default -title: Field-Level Security -parent: Access Control +title: Field-level security +parent: Access control nav_order: 11 --- diff --git a/_security-plugin/access-control/field-masking.md b/_security-plugin/access-control/field-masking.md index 991edfc9..e00233dd 100644 --- a/_security-plugin/access-control/field-masking.md +++ b/_security-plugin/access-control/field-masking.md @@ -1,7 +1,7 @@ --- layout: default -title: Field Masking -parent: Access Control +title: Field masking +parent: Access control nav_order: 12 --- diff --git a/_security-plugin/access-control/impersonation.md b/_security-plugin/access-control/impersonation.md index cc995785..82966389 100644 --- a/_security-plugin/access-control/impersonation.md +++ b/_security-plugin/access-control/impersonation.md @@ -1,7 +1,7 @@ --- layout: default -title: User Impersonation -parent: Access Control +title: User impersonation +parent: Access control nav_order: 20 --- diff --git a/_security-plugin/access-control/index.md b/_security-plugin/access-control/index.md index 99c081e6..6275487f 100644 --- a/_security-plugin/access-control/index.md +++ b/_security-plugin/access-control/index.md @@ -1,6 +1,6 @@ --- layout: default -title: Access Control +title: Access control nav_order: 10 has_children: true has_toc: false diff --git a/_security-plugin/access-control/multi-tenancy.md b/_security-plugin/access-control/multi-tenancy.md index 5b7ed3f5..bb092851 100644 --- a/_security-plugin/access-control/multi-tenancy.md +++ b/_security-plugin/access-control/multi-tenancy.md @@ -1,7 +1,7 @@ --- layout: default -title: OpenSearch Dashboards Multi-Tenancy -parent: Access Control +title: OpenSearch Dashboards multi-tenancy +parent: Access control nav_order: 30 --- diff --git a/_security-plugin/access-control/permissions.md b/_security-plugin/access-control/permissions.md index 192e8a7b..6e222fbe 100644 --- a/_security-plugin/access-control/permissions.md +++ b/_security-plugin/access-control/permissions.md @@ -1,7 +1,7 @@ --- layout: default title: Permissions -parent: Access Control +parent: Access control nav_order: 50 --- diff --git a/_security-plugin/access-control/users-roles.md b/_security-plugin/access-control/users-roles.md index b4e58c7a..d7bb9b8a 100644 --- a/_security-plugin/access-control/users-roles.md +++ b/_security-plugin/access-control/users-roles.md @@ -1,7 +1,7 @@ --- layout: default -title: Users and Roles -parent: Access Control +title: Users and roles +parent: Access control nav_order: 1 --- From 65f333d038325af731ff13dcae6e45f400d5398b Mon Sep 17 00:00:00 2001 From: aetter Date: Tue, 21 Sep 2021 13:40:38 -0700 Subject: [PATCH 065/167] Update python.md --- _clients/python.md | 12 ++++++++---- 1 file changed, 8 insertions(+), 4 deletions(-) diff --git a/_clients/python.md b/_clients/python.md index bcb1ff93..9ce68bca 100644 --- a/_clients/python.md +++ b/_clients/python.md @@ -8,19 +8,23 @@ nav_order: 70 The OpenSearch Python client provides a more natural syntax for interacting with your cluster. Rather than sending HTTP requests with raw JSON bodies to a given URL, you can create an OpenSearch client for your cluster and call the client's built-in functions. +{% comment %} +`opensearch-py` is the lower-level of the two Python clients. If you want a general client for assorted operations, it's a great choice. If you want a higher-level client strictly for indexing and search operations, consider [opensearch-dsl-py]({{site.url}}{{site.baseurl}}/clients/python-dsl/). +{% endcomment %} + ## Setup To add the client to your project, install it using [pip](https://pip.pypa.io/): ```bash -pip install opensearch +pip install opensearch-py ``` Then import it like any other module: ```python -from opensearch import OpenSearch +from opensearchpy import OpenSearch ``` If you prefer to add the client manually or just want to examine the source code, see [opensearch-py on GitHub](https://github.com/opensearch-project/opensearch-py). @@ -29,7 +33,7 @@ If you prefer to add the client manually or just want to examine the source code ## Sample code ```python -from opensearch import OpenSearch +from opensearchpy import OpenSearch host = 'localhost' port = 9200 @@ -55,7 +59,7 @@ client = OpenSearch( ) # Create an index with non-default settings. -index_name = 'python-test-index3' +index_name = 'python-test-index' index_body = { 'settings': { 'index': { From 66ca05e7145c266b792938b461c686a964156566 Mon Sep 17 00:00:00 2001 From: aetter Date: Tue, 21 Sep 2021 13:56:25 -0700 Subject: [PATCH 066/167] Update links --- _clients/index.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/_clients/index.md b/_clients/index.md index 3880a3bb..d920e16a 100644 --- a/_clients/index.md +++ b/_clients/index.md @@ -15,8 +15,8 @@ For example, a 1.0.0 client works with an OpenSearch 1.1.0 cluster, but might no * [OpenSearch Java client]({{site.url}}{{site.baseurl}}/clients/java/) * [OpenSearch Python client]({{site.url}}{{site.baseurl}}/clients/python/) -* [OpenSearch JavaScript (Node.js) client]({{site.url}}{{site.baseurl}}/clients/nodejs/) -* [OpenSearch Go client]({{site.url}}{{site.baseurl}}/clients/golang/) +* [OpenSearch JavaScript (Node.js) client]({{site.url}}{{site.baseurl}}/clients/javascript/) +* [OpenSearch Go client]({{site.url}}{{site.baseurl}}/clients/go/) ## Legacy clients From 75efdfeae8352e6b26bb3faf6854cf6bb8f503fa Mon Sep 17 00:00:00 2001 From: piellick <18485789+piellick@users.noreply.github.com> Date: Wed, 22 Sep 2021 10:57:09 +0200 Subject: [PATCH 067/167] change ES_HOME env variable to OPENSEARCH_HOME env variable looks wrong on "Launch the agent CLI" --- _opensearch/install/tar.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/_opensearch/install/tar.md b/_opensearch/install/tar.md index 2d0f9310..af45a3af 100644 --- a/_opensearch/install/tar.md +++ b/_opensearch/install/tar.md @@ -111,7 +111,7 @@ In a tarball installation, Performance Analyzer collects data when it is enabled 1. Launch the agent CLI: ```bash - ES_HOME="$PWD" ./bin/performance-analyzer-agent-cli + OPENSEARCH_HOME="$PWD" ./bin/performance-analyzer-agent-cli ``` 1. In a separate window, enable the Performance Analyzer plugin: From 2d228a86ca7b46fdba8bccfe39aada53728ef62a Mon Sep 17 00:00:00 2001 From: Liz Snyder Date: Wed, 22 Sep 2021 12:26:41 -0700 Subject: [PATCH 068/167] Update client name --- _clients/javascript.md | 163 ++++++++++++++++++++--------------------- 1 file changed, 80 insertions(+), 83 deletions(-) diff --git a/_clients/javascript.md b/_clients/javascript.md index 55134c00..5d429a08 100644 --- a/_clients/javascript.md +++ b/_clients/javascript.md @@ -10,19 +10,18 @@ The OpenSearch Javascript client provides a safer and easier way to interact wit The client contains a library of APIs that let you perform different operations on your cluster and return a standard response body. The example here demonstrates some basic operations like creating an index, adding documents, and searching your data. - ## Setup To add the client to your project, install it from npm: ```bash -npm install @opensearch/opensearch +npm install @opensearch-project/opensearch ``` To install a specific major version of the client, run the following command: ```bash -npm install @opensearch/opensearch@ +npm install @opensearch-project/opensearch@ ``` If you prefer to add the client manually or just want to examine the source code, see [opensearch-js](https://github.com/opensearch-project/opensearch-js) on GitHub. @@ -30,115 +29,113 @@ If you prefer to add the client manually or just want to examine the source code Then require the client: ```javascript -const { Client } = require('@opensearch/opensearch') +const { Client } = require("@opensearch-project/opensearch"); ``` - ## Sample code ```javascript -'use strict'; +"use strict"; -var host = 'localhost'; -var protocol = 'https'; +var host = "localhost"; +var protocol = "https"; var port = 9200; -var auth = 'admin:admin'; // For testing only. Don't store credentials in code. -var ca_certs_path = '/full/path/to/root-ca.pem'; +var auth = "admin:admin"; // For testing only. Don't store credentials in code. +var ca_certs_path = "/full/path/to/root-ca.pem"; // Optional client certificates if you don't want to use HTTP basic authentication. // var client_cert_path = '/full/path/to/client.pem' // var client_key_path = '/full/path/to/client-key.pem' // Create a client with SSL/TLS enabled. -var { Client } = require('@opensearch/opensearch'); -var fs = require('fs'); +var { Client } = require("@opensearch/opensearch"); +var fs = require("fs"); var client = new Client({ - node: protocol + '://' + auth + '@' + host + ':' + port, - ssl: { - ca: fs.readFileSync(ca_certs_path), - // You can turn off certificate verification (rejectUnauthorized: false) if you're using self-signed certificates with a hostname mismatch. - // cert: fs.readFileSync(client_cert_path), - // key: fs.readFileSync(client_key_path) - } -}) + node: protocol + "://" + auth + "@" + host + ":" + port, + ssl: { + ca: fs.readFileSync(ca_certs_path), + // You can turn off certificate verification (rejectUnauthorized: false) if you're using self-signed certificates with a hostname mismatch. + // cert: fs.readFileSync(client_cert_path), + // key: fs.readFileSync(client_key_path) + }, +}); async function search() { + // Create an index with non-default settings. + var index_name = "books"; + var settings = { + settings: { + index: { + number_of_shards: 4, + number_of_replicas: 3, + }, + }, + }; - // Create an index with non-default settings. - var index_name = 'books' - var settings = { - 'settings': { - 'index': { - 'number_of_shards': 4, - 'number_of_replicas': 3 - } - } - } + var response = await client.indices.create({ + index: index_name, + body: settings, + }); - var response = await client.indices.create({ - index: index_name, - body: settings - }) + console.log("Creating index:"); + console.log(response.body); - console.log('Creating index:') - console.log(response.body) + // Add a document to the index. + var document = { + title: "The Outsider", + author: "Stephen King", + year: "2018", + genre: "Crime fiction", + }; - // Add a document to the index. - var document = { - 'title': 'The Outsider', - 'author': 'Stephen King', - 'year': '2018', - 'genre': 'Crime fiction' - } + var id = "1"; - var id = '1' + var response = await client.index({ + id: id, + index: index_name, + body: document, + refresh: true, + }); - var response = await client.index({ - id: id, - index: index_name, - body: document, - refresh: true - }) + console.log("Adding document:"); + console.log(response.body); - console.log('Adding document:') - console.log(response.body) + // Search for the document. + var query = { + query: { + match: { + title: { + query: "The Outsider", + }, + }, + }, + }; - // Search for the document. - var query = { - 'query': { - 'match': { - 'title': { - 'query': 'The Outsider' - } - } - } - } + var response = await client.search({ + index: index_name, + body: query, + }); - var response = await client.search({ - index: index_name, - body: query - }) + console.log("Search results:"); + console.log(response.body.hits); - console.log('Search results:') - console.log(response.body.hits) + // Delete the document. + var response = await client.delete({ + index: index_name, + id: id, + }); - // Delete the document. - var response = await client.delete({ - index: index_name, - id: id - }) + console.log("Deleting document:"); + console.log(response.body); - console.log('Deleting document:') - console.log(response.body) + // Delete the index. + var response = await client.indices.delete({ + index: index_name, + }); - // Delete the index. - var response = await client.indices.delete({ - index: index_name - }) - - console.log('Deleting index:') - console.log(response.body) + console.log("Deleting index:"); + console.log(response.body); } -search().catch(console.log) +search().catch(console.log); ``` From 293743e15b249fb45d8a985b481058bd20be84cf Mon Sep 17 00:00:00 2001 From: Liz Snyder Date: Wed, 22 Sep 2021 12:27:39 -0700 Subject: [PATCH 069/167] Missed one --- _clients/javascript.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/_clients/javascript.md b/_clients/javascript.md index 5d429a08..cb308a29 100644 --- a/_clients/javascript.md +++ b/_clients/javascript.md @@ -48,7 +48,7 @@ var ca_certs_path = "/full/path/to/root-ca.pem"; // var client_key_path = '/full/path/to/client-key.pem' // Create a client with SSL/TLS enabled. -var { Client } = require("@opensearch/opensearch"); +var { Client } = require("@opensearch-project/opensearch"); var fs = require("fs"); var client = new Client({ node: protocol + "://" + auth + "@" + host + ":" + port, From 07b0650128bc31b5dbdbb09b00609a0b179a66ca Mon Sep 17 00:00:00 2001 From: aetter Date: Wed, 22 Sep 2021 12:59:25 -0700 Subject: [PATCH 070/167] Add remote cluster information operation --- _opensearch/rest-api/remote-info.md | 40 +++++++++++++++++++++++++++++ 1 file changed, 40 insertions(+) create mode 100644 _opensearch/rest-api/remote-info.md diff --git a/_opensearch/rest-api/remote-info.md b/_opensearch/rest-api/remote-info.md new file mode 100644 index 00000000..e9d88402 --- /dev/null +++ b/_opensearch/rest-api/remote-info.md @@ -0,0 +1,40 @@ +--- +layout: default +title: Remote cluster information +parent: REST API reference +nav_order: 25 +--- + +# Remote cluster information +Introduced 1.0 +{: .label .label-purple } + +This operation provides connection information for any remote OpenSearch clusters that you've configured for the local cluster, such as the remote cluster alias, connection mode (`sniff` or `proxy`), IP addresses for seed nodes, and timeout settings. + +The response is more comprehensive and useful than a call to `_cluster/settings`, which only includes the cluster alias and seed nodes. + + +## Path and HTTP methods + +``` +GET _remote/info +``` + + +## Response + +```json +{ + "opensearch-cluster2": { + "connected": true, + "mode": "sniff", + "seeds": [ + "172.28.0.2:9300" + ], + "num_nodes_connected": 1, + "max_connections_per_cluster": 3, + "initial_connect_timeout": "30s", + "skip_unavailable": false + } +} +``` From a9144167d8db4ff67143a7a5bd58f5eb38b03043 Mon Sep 17 00:00:00 2001 From: aetter Date: Thu, 23 Sep 2021 10:29:51 -0700 Subject: [PATCH 071/167] Note that ISM doesn't run jobs on red clusters --- _im-plugin/ism/index.md | 1 + 1 file changed, 1 insertion(+) diff --git a/_im-plugin/ism/index.md b/_im-plugin/ism/index.md index 7a2a3da3..5e983e45 100644 --- a/_im-plugin/ism/index.md +++ b/_im-plugin/ism/index.md @@ -89,6 +89,7 @@ Make sure that the alias that you enter already exists. For more information abo 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/). +ISM does not run jobs if the cluster state is red. ### Step 3: Manage indices From d2ba96967b8b350d076b43e8aff4a66a3098e0eb Mon Sep 17 00:00:00 2001 From: aetter Date: Fri, 24 Sep 2021 13:49:48 -0700 Subject: [PATCH 072/167] Give CCS Compose file unique node names Avoid weird conflicts if you use our main Compose file and then try to use this one. --- .../access-control/cross-cluster-search.md | 34 +++++++++---------- 1 file changed, 17 insertions(+), 17 deletions(-) diff --git a/_security-plugin/access-control/cross-cluster-search.md b/_security-plugin/access-control/cross-cluster-search.md index 060ad624..3c37f3c6 100644 --- a/_security-plugin/access-control/cross-cluster-search.md +++ b/_security-plugin/access-control/cross-cluster-search.md @@ -65,11 +65,11 @@ Save this file as `docker-compose.yml` and run `docker-compose up` to start two ```yml version: '3' services: - opensearch-node1: + opensearch-ccs-node1: image: opensearchproject/opensearch:{{site.opensearch_version}} - container_name: opensearch-node1 + container_name: opensearch-ccs-node1 environment: - - cluster.name=opensearch-cluster1 + - cluster.name=opensearch-ccs-cluster1 - discovery.type=single-node - bootstrap.memory_lock=true # along with the memlock settings below, disables swapping - "OPENSEARCH_JAVA_OPTS=-Xms512m -Xmx512m" # minimum and maximum Java heap size, recommend setting both to 50% of system RAM @@ -85,11 +85,11 @@ services: networks: - opensearch-net - opensearch-node2: + opensearch-ccs-node2: image: opensearchproject/opensearch:{{site.opensearch_version}} - container_name: opensearch-node2 + container_name: opensearch-ccs-node2 environment: - - cluster.name=opensearch-cluster2 + - cluster.name=opensearch-ccs-cluster2 - discovery.type=single-node - bootstrap.memory_lock=true # along with the memlock settings below, disables swapping - "OPENSEARCH_JAVA_OPTS=-Xms512m -Xmx512m" # minimum and maximum Java heap size, recommend setting both to 50% of system RAM @@ -118,26 +118,26 @@ After the clusters start, verify the names of each: ```json curl -XGET -u 'admin:admin' -k 'https://localhost:9200' { - "cluster_name" : "opensearch-cluster1", + "cluster_name" : "opensearch-ccs-cluster1", ... } curl -XGET -u 'admin:admin' -k 'https://localhost:9250' { - "cluster_name" : "opensearch-cluster2", + "cluster_name" : "opensearch-ccs-cluster2", ... } ``` -Both clusters run on `localhost`, so the important identifier is the port number. In this case, use port 9200 (`opensearch-node1`) as the remote cluster, and port 9250 (`opensearch-node2`) as the coordinating cluster. +Both clusters run on `localhost`, so the important identifier is the port number. In this case, use port 9200 (`opensearch-ccs-node1`) as the remote cluster, and port 9250 (`opensearch-ccs-node2`) as the coordinating cluster. To get the IP address for the remote cluster, first identify its container ID: ```bash docker ps CONTAINER ID IMAGE PORTS NAMES -6fe89ebc5a8e opensearchproject/opensearch:{{site.opensearch_version}} 0.0.0.0:9200->9200/tcp, 0.0.0.0:9600->9600/tcp, 9300/tcp opensearch-node1 -2da08b6c54d8 opensearchproject/opensearch:{{site.opensearch_version}} 9300/tcp, 0.0.0.0:9250->9200/tcp, 0.0.0.0:9700->9600/tcp opensearch-node2 +6fe89ebc5a8e opensearchproject/opensearch:{{site.opensearch_version}} 0.0.0.0:9200->9200/tcp, 0.0.0.0:9600->9600/tcp, 9300/tcp opensearch-ccs-node1 +2da08b6c54d8 opensearchproject/opensearch:{{site.opensearch_version}} 9300/tcp, 0.0.0.0:9250->9200/tcp, 0.0.0.0:9700->9600/tcp opensearch-ccs-node2 ``` Then get that container's IP address: @@ -154,7 +154,7 @@ curl -k -XPUT -H 'Content-Type: application/json' -u 'admin:admin' 'https://loca { "persistent": { "search.remote": { - "opensearch-cluster1": { + "opensearch-ccs-cluster1": { "seeds": ["172.31.0.3:9300"] } } @@ -171,11 +171,11 @@ curl -XPUT -k -H 'Content-Type: application/json' -u 'admin:admin' 'https://loca At this point, cross-cluster search works. You can test it using the `admin` user: ```bash -curl -XGET -k -u 'admin:admin' 'https://localhost:9250/opensearch-cluster1:books/_search?pretty' +curl -XGET -k -u 'admin:admin' 'https://localhost:9250/opensearch-ccs-cluster1:books/_search?pretty' { ... "hits": [{ - "_index": "opensearch-cluster1:books", + "_index": "opensearch-ccs-cluster1:books", "_type": "_doc", "_id": "1", "_score": 1.0, @@ -196,7 +196,7 @@ curl -XPUT -k -u 'admin:admin' 'https://localhost:9250/_plugins/_security/api/in Then run the same search as before with `booksuser`: ```json -curl -XGET -k -u booksuser:password 'https://localhost:9250/opensearch-cluster1:books/_search?pretty' +curl -XGET -k -u booksuser:password 'https://localhost:9250/opensearch-ccs-cluster1:books/_search?pretty' { "error" : { "root_cause" : [ @@ -225,11 +225,11 @@ Both clusters must have the user, but only the remote cluster needs the role and Finally, repeat the search: ```bash -curl -XGET -k -u booksuser:password 'https://localhost:9250/opensearch-cluster1:books/_search?pretty' +curl -XGET -k -u booksuser:password 'https://localhost:9250/opensearch-ccs-cluster1:books/_search?pretty' { ... "hits": [{ - "_index": "opensearch-cluster1:books", + "_index": "opensearch-ccs-cluster1:books", "_type": "_doc", "_id": "1", "_score": 1.0, From b12dab67054b7e615e5c73d018b8d76615633095 Mon Sep 17 00:00:00 2001 From: keithhc2 Date: Fri, 24 Sep 2021 14:13:26 -0700 Subject: [PATCH 073/167] Add descriptions to config yaml files and added some security APIs --- _security-plugin/access-control/api.md | 214 +++++++++++++++---------- _security-plugin/configuration/yaml.md | 9 +- 2 files changed, 139 insertions(+), 84 deletions(-) diff --git a/_security-plugin/access-control/api.md b/_security-plugin/access-control/api.md index 19dd46ec..b5b3e9d3 100644 --- a/_security-plugin/access-control/api.md +++ b/_security-plugin/access-control/api.md @@ -1179,6 +1179,117 @@ PATCH _plugins/_security/api/securityconfig } ``` +--- + +## Distinguished names + +These REST APIs let a super admin allow list distinguished names to enable communication between clusters and/or nodes. + +Before you can use the REST API to add, retrieve, update, or delete any distinguished names, you must first add the following line to `opensearch.yml`: + +```yml +plugins.security.nodes_dn_dynamic_config_enabled: true +``` + + +### Get distinguished names + +Retrieves all allow listed distinguished names. + +#### Request + +``` +GET _plugins/_security/api/nodesdn +``` + +#### Sample response + +```json +{ + "cluster1": { + "nodes_dn": [ + "CN=cluster1.example.com" + ] + } +} +``` + +To get the distinguished names from a specific cluster or node, include its name in the request's URL. + +#### Request + +``` +GET _plugins/_security/api/nodesdn/ +``` + +#### Sample response + +```json +{ + "cluster3": { + "nodes_dn": [ + "CN=cluster3.example.com" + ] + } +} +``` + + +### Add distinguished names + +Adds the specified distinguished names to the cluster's or node's allow list. + +#### Request + +```json +PUT _plugins/_security/api/nodesdn/ +{ + "nodes_dn": [ + "CN=cluster3.example.com" + ] +} +``` + +#### Sample response + +```json +{ + "status": "CREATED", + "message": "'cluster3' created." +} +``` + +If the specified cluster or node already has an allow list of distinguished names, the PUT request updates the list instead. + +#### Sample response + +```json +{ + "status": "OK", + "message": "'cluster7' updated." +} +``` + + +### Delete distinguished names + +Deletes the cluster's allow listed distinguished names. + +#### Request + +``` +DELETE _plugins/_security/api/nodesdn/ +``` + +#### Sample response + +```json +{ + "status": "OK", + "message": "'cluster3' deleted." +} +``` + --- @@ -1188,101 +1299,38 @@ PATCH _plugins/_security/api/securityconfig Introduced 1.0 {: .label .label-purple } -Retrieves the current security plugin configuration in JSON format. +Retrieves the cluster's certificates. #### Request ``` -GET _plugins/_security/api/securityconfig -``` - - -### Update configuration -Introduced 1.0 -{: .label .label-purple } - -Creates or updates the existing configuration using the REST API rather than `securityadmin.sh`. This operation can easily break your existing configuration, so we recommend using `securityadmin.sh` instead. See [Access control for the API](#access-control-for-the-api) for how to enable this operation. - -#### Request - -```json -PUT _plugins/_security/api/securityconfig/config -{ - "dynamic": { - "filtered_alias_mode": "warn", - "disable_rest_auth": false, - "disable_intertransport_auth": false, - "respect_request_indices_options": false, - "opensearch-dashboards": { - "multitenancy_enabled": true, - "server_username": "kibanaserver", - "index": ".opensearch-dashboards" - }, - "http": { - "anonymous_auth_enabled": false - }, - "authc": { - "basic_internal_auth_domain": { - "http_enabled": true, - "transport_enabled": true, - "order": 0, - "http_authenticator": { - "challenge": true, - "type": "basic", - "config": {} - }, - "authentication_backend": { - "type": "intern", - "config": {} - }, - "description": "Authenticate via HTTP Basic against internal users database" - } - }, - "auth_failure_listeners": {}, - "do_not_fail_on_forbidden": false, - "multi_rolespan_enabled": true, - "hosts_resolver_mode": "ip-only", - "do_not_fail_on_forbidden_empty": false - } -} +GET _opendistro/_security/api/ssl/certs ``` #### Sample response ```json { - "status": "OK", - "message": "'config' updated." + "http_certificates_list": [ + { + "issuer_dn": "CN=Example Com Inc. Root CA,OU=Example Com Inc. Root CA,O=Example Com Inc.,DC=example,DC=com", + "subject_dn": "CN=node-0.example.com,OU=node,O=node,L=test,DC=de", + "san": "[[8, 1.2.3.4.5.5], [2, node-0.example.com]", + "not_before": "2018-04-22T03:43:47Z", + "not_after": "2028-04-19T03:43:47Z" + } + ], + "transport_certificates_list": [ + { + "issuer_dn": "CN=Example Com Inc. Root CA,OU=Example Com Inc. Root CA,O=Example Com Inc.,DC=example,DC=com", + "subject_dn": "CN=node-0.example.com,OU=node,O=node,L=test,DC=de", + "san": "[[8, 1.2.3.4.5.5], [2, node-0.example.com]", + "not_before": "2018-04-22T03:43:47Z", + "not_after": "2028-04-19T03:43:47Z" + } + ] } ``` - - -### Patch configuration -Introduced 1.0 -{: .label .label-purple } - -Updates the existing configuration using the REST API rather than `securityadmin.sh`. This operation can easily break your existing configuration, so we recommend using `securityadmin.sh` instead. See [Access control for the API](#access-control-for-the-api) for how to enable this operation. - -#### Request - -```json -PATCH _plugins/_security/api/securityconfig -[ - { - "op": "replace", "path": "/config/dynamic/authc/basic_internal_auth_domain/transport_enabled", "value": "true" - } -] -``` - -#### Sample response - -```json -{ - "status": "OK", - "message": "Resource updated." -} -``` - --- ## Cache diff --git a/_security-plugin/configuration/yaml.md b/_security-plugin/configuration/yaml.md index 6d6bcdd9..f9383b45 100644 --- a/_security-plugin/configuration/yaml.md +++ b/_security-plugin/configuration/yaml.md @@ -315,6 +315,10 @@ _meta: ## tenants.yml +You can use this file to specify and add any number of OpenSearch Dashboards tenants to your OpenSearch cluster. For more information about tenants, see [OpenSearch Dashboards multi-tenancy]({{site.url}}{{site.baseurl}}/security-plugin/access-control/multi-tenancy). + +Like all of the other YAML files, we recommend you use `tenants.yml` to add any tenants you must have in your cluster, and then use OpenSearch Dashboards or the [REST API]({{site.url}}{{site.baseurl}}/security-plugin/access-control/api/#tenants) if you need to further configure or create any other tenants. + ```yml --- _meta: @@ -325,9 +329,12 @@ admin_tenant: description: "Demo tenant for admin user" ``` - ## nodes_dn.yml +`nodes_dn.yml` lets you allow list certificates' [distinguished names (DNs)]({{site.url}}{{site.baseurl}}/security-plugin/configuration/generate-certificates/#add-distinguished-names-to-opensearchyml) to enable communication between any number of nodes and/or clusters. For example, a node that allow lists the DN `CN=node1.example.com` accepts communication from any other node or certificate that uses that DN. + +The DNs get indexed into a [system index]({{site.url}}{{site.baseurl}}/security-plugin/configuration/system-indices) that only a super admin or an admin with a Transport Layer Security (TLS) certificate can access. If you want to programmatically allow list DNs, use the [REST API]({{site.url}}{{site.baseurl}}/security-plugin/access-control/api/#distinguished-names). + ```yml --- _meta: From e8a863e943611f81c171e8a0f07694d87a2a1024 Mon Sep 17 00:00:00 2001 From: keithhc2 Date: Fri, 24 Sep 2021 14:23:17 -0700 Subject: [PATCH 074/167] Minor language tweak --- _security-plugin/access-control/api.md | 15 ++------------- 1 file changed, 2 insertions(+), 13 deletions(-) diff --git a/_security-plugin/access-control/api.md b/_security-plugin/access-control/api.md index b5b3e9d3..7634111b 100644 --- a/_security-plugin/access-control/api.md +++ b/_security-plugin/access-control/api.md @@ -1235,9 +1235,9 @@ GET _plugins/_security/api/nodesdn/ ``` -### Add distinguished names +### Update distinguished names -Adds the specified distinguished names to the cluster's or node's allow list. +Adds or updates the specified distinguished names in the cluster's or node's allow list. #### Request @@ -1259,17 +1259,6 @@ PUT _plugins/_security/api/nodesdn/ } ``` -If the specified cluster or node already has an allow list of distinguished names, the PUT request updates the list instead. - -#### Sample response - -```json -{ - "status": "OK", - "message": "'cluster7' updated." -} -``` - ### Delete distinguished names From 430b9fed507e5ca9289f21869ec620a595a859d7 Mon Sep 17 00:00:00 2001 From: keithhc2 Date: Fri, 24 Sep 2021 14:53:33 -0700 Subject: [PATCH 075/167] Added "security" --- _security-plugin/access-control/api.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/_security-plugin/access-control/api.md b/_security-plugin/access-control/api.md index 7634111b..8c2b8088 100644 --- a/_security-plugin/access-control/api.md +++ b/_security-plugin/access-control/api.md @@ -1288,7 +1288,7 @@ DELETE _plugins/_security/api/nodesdn/ Introduced 1.0 {: .label .label-purple } -Retrieves the cluster's certificates. +Retrieves the cluster's security certificates. #### Request From c85fd21b4feae12a6fa70fc65a19495ad939cf7b Mon Sep 17 00:00:00 2001 From: keithhc2 Date: Mon, 27 Sep 2021 10:07:37 -0700 Subject: [PATCH 076/167] Addressed comments --- _security-plugin/access-control/api.md | 10 +++++----- _security-plugin/configuration/yaml.md | 8 ++++---- 2 files changed, 9 insertions(+), 9 deletions(-) diff --git a/_security-plugin/access-control/api.md b/_security-plugin/access-control/api.md index 8c2b8088..dd5604a3 100644 --- a/_security-plugin/access-control/api.md +++ b/_security-plugin/access-control/api.md @@ -1183,9 +1183,9 @@ PATCH _plugins/_security/api/securityconfig ## Distinguished names -These REST APIs let a super admin allow list distinguished names to enable communication between clusters and/or nodes. +These REST APIs let a super admin add, retrieve, update, or delete any distinguished names from an allow list to enable communication between clusters and/or nodes. -Before you can use the REST API to add, retrieve, update, or delete any distinguished names, you must first add the following line to `opensearch.yml`: +Before you can use the REST API to configure the allow list, you must first add the following line to `opensearch.yml`: ```yml plugins.security.nodes_dn_dynamic_config_enabled: true @@ -1194,7 +1194,7 @@ plugins.security.nodes_dn_dynamic_config_enabled: true ### Get distinguished names -Retrieves all allow listed distinguished names. +Retrieves all distinguished names in the allow list. #### Request @@ -1214,7 +1214,7 @@ GET _plugins/_security/api/nodesdn } ``` -To get the distinguished names from a specific cluster or node, include its name in the request's URL. +To get the distinguished names from a specific cluster's or node's allow list, include the cluster's name in the request path. #### Request @@ -1262,7 +1262,7 @@ PUT _plugins/_security/api/nodesdn/ ### Delete distinguished names -Deletes the cluster's allow listed distinguished names. +Deletes all distinguished names in the specified cluster's or node's allow list. #### Request diff --git a/_security-plugin/configuration/yaml.md b/_security-plugin/configuration/yaml.md index f9383b45..114f080d 100644 --- a/_security-plugin/configuration/yaml.md +++ b/_security-plugin/configuration/yaml.md @@ -126,7 +126,7 @@ plugins.security.restapi.password_validation_error_message: "Password must be mi ## whitelist.yml -You can use `whitelist.yml` to allow list any endpoints and HTTP requests. If enabled, all users except the SuperAdmin are allowed access to only the specified endpoints and HTTP requests, and all other HTTP requests associated with the endpoint are denied. For example, if GET `_cluster/settings` is allow listed, users cannot submit PUT requests to `_cluster/settings` to update cluster settings. +You can use `whitelist.yml` to add any endpoints and HTTP requests to a list of allowed endpoints and requests. If enabled, all users except the super admin are allowed access to only the specified endpoints and HTTP requests, and all other HTTP requests associated with the endpoint are denied. For example, if GET `_cluster/settings` is added to the allow list, users cannot submit PUT requests to `_cluster/settings` to update cluster settings. Note that while you can configure access to endpoints this way, for most cases, it is still best to configure permissions using the security plugin's users and roles, which have more granular settings. @@ -165,7 +165,7 @@ requests: - PUT ``` -You can also allow list custom indices. `whitelist.yml` doesn't support wildcards, so you must manually specify all of the indices you want to allow list. +You can also add custom indices to the allow list. `whitelist.yml` doesn't support wildcards, so you must manually specify all of the indices you want to add. ```yml requests: # Only allow GET requests to /sample-index1/_doc/1 and /sample-index2/_doc/1 @@ -331,9 +331,9 @@ admin_tenant: ## nodes_dn.yml -`nodes_dn.yml` lets you allow list certificates' [distinguished names (DNs)]({{site.url}}{{site.baseurl}}/security-plugin/configuration/generate-certificates/#add-distinguished-names-to-opensearchyml) to enable communication between any number of nodes and/or clusters. For example, a node that allow lists the DN `CN=node1.example.com` accepts communication from any other node or certificate that uses that DN. +`nodes_dn.yml` lets you add certificates' [distinguished names (DNs)]({{site.url}}{{site.baseurl}}/security-plugin/configuration/generate-certificates/#add-distinguished-names-to-opensearchyml) an allow list to enable communication between any number of nodes and/or clusters. For example, a node that has the DN `CN=node1.example.com` in its allow list accepts communication from any other node or certificate that uses that DN. -The DNs get indexed into a [system index]({{site.url}}{{site.baseurl}}/security-plugin/configuration/system-indices) that only a super admin or an admin with a Transport Layer Security (TLS) certificate can access. If you want to programmatically allow list DNs, use the [REST API]({{site.url}}{{site.baseurl}}/security-plugin/access-control/api/#distinguished-names). +The DNs get indexed into a [system index]({{site.url}}{{site.baseurl}}/security-plugin/configuration/system-indices) that only a super admin or an admin with a Transport Layer Security (TLS) certificate can access. If you want to programmatically add DNs to your allow lists, use the [REST API]({{site.url}}{{site.baseurl}}/security-plugin/access-control/api/#distinguished-names). ```yml --- From 7c425f102d3703edbda9d4e8fc6747f221128f3f Mon Sep 17 00:00:00 2001 From: keithhc2 Date: Mon, 27 Sep 2021 12:52:36 -0700 Subject: [PATCH 077/167] Added reindex API --- _opensearch/reindex-data.md | 23 ---- _opensearch/rest-api/document-apis/reindex.md | 121 ++++++++++++++++++ 2 files changed, 121 insertions(+), 23 deletions(-) create mode 100644 _opensearch/rest-api/document-apis/reindex.md diff --git a/_opensearch/reindex-data.md b/_opensearch/reindex-data.md index f1e7164b..6d51a748 100644 --- a/_opensearch/reindex-data.md +++ b/_opensearch/reindex-data.md @@ -156,28 +156,6 @@ POST _reindex } ``` -## Reindex sorted documents - -You can copy certain documents after sorting specific fields in the document. - -This command copies the last 10 documents based on the `timestamp` field: - -```json -POST _reindex -{ - "size":10, - "source":{ - "index":"source", - "sort":{ - "timestamp":"desc" - } - }, - "dest":{ - "index":"destination" - } -} -``` - ## Transform documents during reindexing You can transform your data during the reindexing process using the `script` option. @@ -272,7 +250,6 @@ Option | Valid values | Description | Required `query` | Object | The search query to use for the reindex operation. | No `size` | Integer | The number of documents to reindex. | No `slice` | String | Specify manual or automatic slicing to parallelize reindexing. | No -`sort` | List | Sort specific fields in the document before reindexing. | No ## Destination index options diff --git a/_opensearch/rest-api/document-apis/reindex.md b/_opensearch/rest-api/document-apis/reindex.md new file mode 100644 index 00000000..5ad961a8 --- /dev/null +++ b/_opensearch/rest-api/document-apis/reindex.md @@ -0,0 +1,121 @@ +--- +layout: default +title: Reindex +parent: Document APIs +grand_parent: REST API reference +nav_order: 60 +--- + +# Index document +Introduced 1.0 +{: .label .label-purple} + +The reindex API operation lets you copy all or a subset of your data from a source index into a destination index. + +## Example + +```json +POST /_reindex +{ + "source":{ + "index":"my-source-index" + }, + "dest":{ + "index":"my-destination-index" + } +} +``` + +## Path and HTTP methods + +``` +POST /_reindex +``` + +## URL parameters + +All URL parameters are optional. + +Parameter | Type | Description +:--- | :--- | :--- +refresh | Boolean | If true, OpenSearch refreshes shards to make the reindex operation available to search results. Valid options are `true`, `false`, and `wait_for`, which tells OpenSearch to wait for a refresh before executing the operation. Default is `false`. +timeout | Time | How long to wait for a response from the cluster. Default is `30s`. +wait_for_active_shards | String | The number of active shards that must be available before OpenSearch processes the reindex 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 operation to succeed. +wait_for_completion | Boolean | Waits for the matching tasks to complete. Default is `false`. +requests_per_second | Integer | Specifies the request’s throttling in sub-requests per second. Default is -1, which means no throttling. +require_alias | Boolean | Whether the destination index must be an index alias. Default is false. +scroll | Time | How long to keep the search context open. Default is `5m`. +slices | Integer | Number of sub-tasks OpenSearch should divide this task into. Default is 1, which means OpenSearch should not divide this task. Setting this parameter to `auto` indicates to OpenSearch that it should automatically decide how many slices to split the task into. +max_docs | Integer | How many documents the update by query operation should process at most. Default is all documents. + +## Request body + +Your request body must contain the names of the source index and destination index. All other fields are optional. + +Field | Description +:--- | :--- +conflicts | Indicates to OpenSearch what should happen if the delete by query operation runs into a version conflict. Valid options are `abort` and `proceed`. Default is abort. +source | Information about the source index to include. Valid fields are `index`, `max_docs`, `query`, `remote`, `size`, `slice`, and `_source`. +index | The name of the source index to copy data from. +max_docs | The maximum number of documents to reindex. +query | The search query to use for the reindex operation. +remote | Information about a remote OpenSearch cluster to copy data from. Valid fields are `host`, `username`, `password`, `socket_timeout`, and `connect_timeout`. +host | Host URL of the OpenSearch cluster to copy data from. +username | Username to authenticate with the remote cluster. +password | Password to authenticate with the remote cluster. +socket_timeout | The wait time for socket reads. Default is 30s. +connect_timeout | The wait time for remote connection timeouts. Default is 30s. +size | The number of documents to reindex. +slice | Whether to manually or automatically slice the reindex operation so it executes in parallel. +_source | Whether to reindex source fields. Speicfy a list of fields to reindex or true to reindex all fields. Default is true. +id | The ID to associate with manual slicing. +max | Maximum number of slices. +dest | Information about the destination index. Valid values are `index`, `version_type`, and `op_type`. +index | Name of the destination index. +version_type | The indexing operation's version type. Valid values are `internal`, `external`, `external_gt` (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 or equal to than the document’s current version). +op_type | Whether to copy over documents that are missing in the destination index. Valid values are `create` (ignore documents with the same ID from the source index) and `index` (copy everything from the source index). +script | A script that OpenSearch uses to apply transformations to the data during the reindex operation. +source | The actual script that OpenSearch runs. +lang | The scripting language. Valid options are `painless`, `expression`, `mustache`, and `java`. + +## Response +```json +{ + "took": 28829, + "timed_out": false, + "total": 111396, + "updated": 0, + "created": 111396, + "deleted": 0, + "batches": 112, + "version_conflicts": 0, + "noops": 0, + "retries": { + "bulk": 0, + "search": 0 + }, + "throttled_millis": 0, + "requests_per_second": -1.0, + "throttled_until_millis": 0, + "failures": [] +} +``` + +## Response body fields + +Field | Description +:--- | :--- +took | How long the operation took in milliseconds. +timed_out | Whether the operation timed out. +total | The total number of documents processed. +updated | The number of documents updated in the destination index. +created | The number of documents created in the destination index. +deleted | The number of documents deleted. +batches | Number of scroll responses. +version_conflicts | Number of version conflicts. +noops | How many documents OpenSearch ignored during the operation. +retries | Number of bulk and search retry requests. +throttled_millis | Number of throttled milliseconds during the request. +requests_per_second | Number of requests executed per second during the operation. +throttled_until_millis | The amount of time until OpenSearch executes the next throttled request. +failures | Any failures that occurred during the operation. From eda842a36dbcab88079d40dea535e64fb42dbd0e Mon Sep 17 00:00:00 2001 From: ashwinkumar12345 Date: Mon, 27 Sep 2021 13:08:27 -0700 Subject: [PATCH 078/167] added info about the priority value --- _im-plugin/ism/index.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/_im-plugin/ism/index.md b/_im-plugin/ism/index.md index 5e983e45..f27e2636 100644 --- a/_im-plugin/ism/index.md +++ b/_im-plugin/ism/index.md @@ -55,6 +55,8 @@ PUT _plugins/_ism/policies/policy_id } ``` +If you have more than one template that matches an index pattern, ISM uses the priority value to determine which template to apply. + 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). 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: From b4642195e72df21fdbcb01b88cf2adb02ed63882 Mon Sep 17 00:00:00 2001 From: keithhc2 Date: Mon, 27 Sep 2021 16:09:53 -0700 Subject: [PATCH 079/167] Addressed comments --- _monitoring-plugins/alerting/api.md | 3 +++ _monitoring-plugins/alerting/monitors.md | 4 ++-- 2 files changed, 5 insertions(+), 2 deletions(-) diff --git a/_monitoring-plugins/alerting/api.md b/_monitoring-plugins/alerting/api.md index 146f2d9a..265954ec 100644 --- a/_monitoring-plugins/alerting/api.md +++ b/_monitoring-plugins/alerting/api.md @@ -23,6 +23,7 @@ Use the alerting API to programmatically manage monitors and alerts. Introduced 1.0 {: .label .label-purple } +Query-level monitors run the query and check whether the results should trigger any alerts. For more information about query-level monitors versus bucket-level monitors, see [Create monitors]({{site.url}}{{site.baseurl}}/monitoring-plugins/alerting/monitors/#create-monitors). #### Request @@ -252,6 +253,8 @@ For a full list of timezone names, refer to [Wikipedia](https://en.wikipedia.org ## Create bucket-level monitor +Bucket-level monitors categorize results into buckets separated by fields. For more information about bucket-level monitors versus query-level monitors, see [Create monitors]({{site.url}}{{site.baseurl}}/monitoring-plugins/alerting/monitors/#create-monitors). + ```json POST _plugins/_alerting/monitors { diff --git a/_monitoring-plugins/alerting/monitors.md b/_monitoring-plugins/alerting/monitors.md index 085eafc7..7b6c999a 100644 --- a/_monitoring-plugins/alerting/monitors.md +++ b/_monitoring-plugins/alerting/monitors.md @@ -82,7 +82,7 @@ If your email provider requires SSL or TLS, you must authenticate each sender ac ./bin/opensearch-keystore add plugins.alerting.destination.email..password ``` -**Note**: Keystore settings are node-specific. You must run these commands on each node. +Note: Keystore settings are node-specific. You must run these commands on each node. {: .note} To change or update your credentials (after you've added them to the keystore on every node), call the reload API to automatically update those credentials without restarting OpenSearch: @@ -103,7 +103,7 @@ POST _nodes/reload_secure_settings 1. Specify a name for the monitor. 1. Choose either **Per query monitor** or **Per bucket monitor**. -Whereas per query monitors run your specifed query and then check whether the query's results triggers any alerts, per bucket monitors let you select fields to create buckets and categorize your results into those buckets. Doing so gives you finer control over which results should trigger alerts, and trigger conditions get evaluated per bucket. +Whereas per-query monitors run your specified query and then check whether the query's results triggers any alerts, per-bucket monitors let you select fields to create buckets and categorize your results into those buckets. Doing so gives you finer control over which results should trigger alerts, as the alerting plugin uses each bucket's results to see if they should trigger any alerts. 1. Define the monitor in one of three ways: visually, using a query, or using an anomaly detector. From dc69f8010b03c6081233c0434fbdcbdcb42231b0 Mon Sep 17 00:00:00 2001 From: keithhc2 Date: Mon, 27 Sep 2021 17:07:38 -0700 Subject: [PATCH 080/167] Added a setting to enable patch configuration --- _security-plugin/access-control/api.md | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/_security-plugin/access-control/api.md b/_security-plugin/access-control/api.md index dd5604a3..2f4a6652 100644 --- a/_security-plugin/access-control/api.md +++ b/_security-plugin/access-control/api.md @@ -1159,6 +1159,12 @@ Introduced 1.0 Updates the existing configuration using the REST API. This operation can easily break your existing configuration, so we recommend using `securityadmin.sh` instead, which is far safer. See [Access control for the API](#access-control-for-the-api) for how to enable this operation. +Before you can execute the operation, you must first add the following line to `opensearch.yml`: + +```yml +plugins.security.unsupported.restapi.allow_securityconfig_modification: true +``` + #### Request ```json From cbdefc2463a7ad7d79444c2d979175201678b724 Mon Sep 17 00:00:00 2001 From: aetter Date: Tue, 28 Sep 2021 10:54:04 -0700 Subject: [PATCH 081/167] Improve permissions introduction Also corrects some permissions names that still use `opendistro`, adds missing permissions, adds some short () description to unclear permissions. --- .../access-control/permissions.md | 179 +++++++++++++----- 1 file changed, 129 insertions(+), 50 deletions(-) diff --git a/_security-plugin/access-control/permissions.md b/_security-plugin/access-control/permissions.md index 6e222fbe..486745e9 100644 --- a/_security-plugin/access-control/permissions.md +++ b/_security-plugin/access-control/permissions.md @@ -7,58 +7,125 @@ nav_order: 50 # Permissions -This page is a complete list of available permissions in the security plugin. Each permission controls access to a data type or API. +Each permission in the security plugin controls access to some action that the OpenSearch cluster can perform, such as indexing a document or checking cluster health. -Rather than creating new action groups from individual permissions, you can often achieve your desired security posture using some combination of the default action groups. To learn more, see [Default Action Groups]({{site.url}}{{site.baseurl}}/security-plugin/access-control/default-action-groups/). +Most permissions are self-describing. For example, `cluster:admin/ingest/pipeline/get` lets you retrieve information about ingest pipelines. _In many cases_, a permission correlates to a specific REST API operation, such as `GET _ingest/pipeline`. + +Despite this correlation, permissions do **not** directly map to REST API operations. Operations such as `POST _bulk` and `GET _msearch` can access many indices and perform many actions in a single request. Even a simple request, such as `GET _cat/nodes`, performs several actions in order to generate its response. + +In short, controlling access to the REST API is insufficient. Instead, the security plugin controls access to the underlying OpenSearch actions. + +For example, consider the following `_bulk` request: + +```json +POST _bulk +{ "delete": { "_index": "test-index", "_id": "tt2229499" } } +{ "index": { "_index": "test-index", "_id": "tt1979320" } } +{ "title": "Rush", "year": 2013 } +{ "create": { "_index": "test-index", "_id": "tt1392214" } } +{ "title": "Prisoners", "year": 2013 } +{ "update": { "_index": "test-index", "_id": "tt0816711" } } +{ "doc" : { "title": "World War Z" } } + +``` + +For this request to succeed, you must have the following permissions for `test-index`: + +- indices:data/write/bulk* +- indices:data/write/delete +- indices:data/write/index +- indices:data/write/update + +These permissions also allow you add, update, or delete documents (e.g. `PUT test-index/_doc/tt0816711`), because they govern the underlying OpenSearch actions of indexing and deleting documents rather than a specific API path and HTTP method. + + +## Test permissions + +If you want a user to have the absolute minimum set of permissions necessary to perform some function---the [principle of least privilege](https://en.wikipedia.org/wiki/Principle_of_least_privilege)----the best way is to send representative requests to your cluster as a new test user. In the case of a permissions error, the security plugin is very explicit about which permissions are missing. Consider this request and response: + +```json +GET _cat/shards?v + +{ + "error": { + "root_cause": [{ + "type": "security_exception", + "reason": "no permissions for [indices:monitor/stats] and User [name=test-user, backend_roles=[], requestedTenant=null]" + }] + }, + "status": 403 +} +``` + +[Create a user and a role]({{site.url}}{{site.baseurl}}/security-plugin/access-control/users-roles/), map the role to the user, and start sending signed requests using curl, Postman, or any other client. Then gradually add permissions to the role as you encounter errors. Even after you resolve one permissions error, the same request might generate new errors; the plugin only returns the first error it encounters, so keep trying until the request succeeds. + +Rather than individual permissions, you can often achieve your desired security posture using a combination of the default action groups. See [Default action groups]({{site.url}}{{site.baseurl}}/security-plugin/access-control/default-action-groups/) for descriptions of the permissions that each group grants. {: .tip } -## Cluster +## Cluster permissions + +These permissions are for the cluster and can't be applied granularly. For example, you either have permissions to take snapshots (`cluster:admin/snapshot/create`) or you don't. You can't have permissions to take snapshots only for certain indices. - cluster:admin/ingest/pipeline/delete - cluster:admin/ingest/pipeline/get - cluster:admin/ingest/pipeline/put - cluster:admin/ingest/pipeline/simulate - cluster:admin/ingest/processor/grok/get -- cluster:admin/opensearch/ad/detector/delete -- cluster:admin/opensearch/ad/detector/jobmanagement -- cluster:admin/opensearch/ad/detector/run -- cluster:admin/opensearch/ad/detector/search -- cluster:admin/opensearch/ad/detector/stats -- cluster:admin/opensearch/ad/detector/write -- cluster:admin/opensearch/ad/detectors/get -- cluster:admin/opensearch/ad/result/search -- cluster:admin/opensearch/alerting/alerts/ack -- cluster:admin/opensearch/alerting/alerts/get -- cluster:admin/opensearch/alerting/destination/delete -- cluster:admin/opensearch/alerting/destination/email_account/delete -- cluster:admin/opensearch/alerting/destination/email_account/get -- cluster:admin/opensearch/alerting/destination/email_account/search -- cluster:admin/opensearch/alerting/destination/email_account/write -- cluster:admin/opensearch/alerting/destination/email_group/delete -- cluster:admin/opensearch/alerting/destination/email_group/get -- cluster:admin/opensearch/alerting/destination/email_group/search -- cluster:admin/opensearch/alerting/destination/email_group/write -- cluster:admin/opensearch/alerting/destination/get -- cluster:admin/opensearch/alerting/destination/write -- cluster:admin/opensearch/alerting/monitor/delete -- cluster:admin/opensearch/alerting/monitor/execute -- cluster:admin/opensearch/alerting/monitor/get -- cluster:admin/opensearch/alerting/monitor/search -- cluster:admin/opensearch/alerting/monitor/write -- cluster:admin/opensearch/asynchronous_search/stats -- cluster:admin/opensearch/asynchronous_search/delete -- cluster:admin/opensearch/asynchronous_search/get -- cluster:admin/opensearch/asynchronous_search/submit -- cluster:admin/opensearch/reports/definition/create -- cluster:admin/opensearch/reports/definition/delete -- cluster:admin/opensearch/reports/definition/get -- cluster:admin/opensearch/reports/definition/list -- cluster:admin/opensearch/reports/definition/on_demand -- cluster:admin/opensearch/reports/definition/update -- cluster:admin/opensearch/reports/instance/get -- cluster:admin/opensearch/reports/instance/list -- cluster:admin/opensearch/reports/menu/download +- cluster:admin/opendistro/ad/detector/delete +- cluster:admin/opendistro/ad/detector/info +- cluster:admin/opendistro/ad/detector/jobmanagement +- cluster:admin/opendistro/ad/detector/preview +- cluster:admin/opendistro/ad/detector/run +- cluster:admin/opendistro/ad/detector/search +- cluster:admin/opendistro/ad/detector/stats +- cluster:admin/opendistro/ad/detector/write +- cluster:admin/opendistro/ad/detectors/get +- cluster:admin/opendistro/ad/result/search +- cluster:admin/opendistro/ad/tasks/search +- cluster:admin/opendistro/alerting/alerts/ack (acknowledge) +- cluster:admin/opendistro/alerting/alerts/get +- cluster:admin/opendistro/alerting/destination/delete +- cluster:admin/opendistro/alerting/destination/email_account/delete +- cluster:admin/opendistro/alerting/destination/email_account/get +- cluster:admin/opendistro/alerting/destination/email_account/search +- cluster:admin/opendistro/alerting/destination/email_account/write +- cluster:admin/opendistro/alerting/destination/email_group/delete +- cluster:admin/opendistro/alerting/destination/email_group/get +- cluster:admin/opendistro/alerting/destination/email_group/search +- cluster:admin/opendistro/alerting/destination/email_group/write +- cluster:admin/opendistro/alerting/destination/get +- cluster:admin/opendistro/alerting/destination/write +- cluster:admin/opendistro/alerting/monitor/delete +- cluster:admin/opendistro/alerting/monitor/execute +- cluster:admin/opendistro/alerting/monitor/get +- cluster:admin/opendistro/alerting/monitor/search +- cluster:admin/opendistro/alerting/monitor/write +- cluster:admin/opendistro/ism/managedindex/add +- cluster:admin/opendistro/ism/managedindex/change +- cluster:admin/opendistro/ism/managedindex/remove +- cluster:admin/opendistro/ism/managedindex/explain +- cluster:admin/opendistro/ism/managedindex/retry +- cluster:admin/opendistro/ism/policy/write +- cluster:admin/opendistro/ism/policy/get +- cluster:admin/opendistro/ism/policy/search +- cluster:admin/opendistro/ism/policy/delete +- cluster:admin/opendistro/rollup/index +- cluster:admin/opendistro/rollup/get +- cluster:admin/opendistro/rollup/search +- cluster:admin/opendistro/rollup/delete +- cluster:admin/opendistro/rollup/start +- cluster:admin/opendistro/rollup/stop +- cluster:admin/opendistro/rollup/explain +- cluster:admin/opendistro/reports/definition/create +- cluster:admin/opendistro/reports/definition/update +- cluster:admin/opendistro/reports/definition/on_demand +- cluster:admin/opendistro/reports/definition/delete +- cluster:admin/opendistro/reports/definition/get +- cluster:admin/opendistro/reports/definition/list +- cluster:admin/opendistro/reports/instance/list +- cluster:admin/opendistro/reports/instance/get +- cluster:admin/opendistro/reports/menu/download - cluster:admin/reindex/rethrottle - cluster:admin/repository/delete - cluster:admin/repository/get @@ -94,7 +161,9 @@ Rather than creating new action groups from individual permissions, you can ofte - cluster:monitor/tasks/list -## Indices +## Index permissions + +These permissions apply to an index or index pattern. You might want a user to have read access to all indices (i.e. `*`), but write access to only a few (e.g. `web-logs` and `product-catalog`). - indices:admin/aliases - indices:admin/aliases/exists @@ -102,13 +171,22 @@ Rather than creating new action groups from individual permissions, you can ofte - indices:admin/analyze - indices:admin/cache/clear - indices:admin/close -- indices:admin/create -- indices:admin/delete +- indices:admin/close* +- indices:admin/create (create indices) +- indices:admin/data_stream/create +- indices:admin/data_stream/delete +- indices:admin/data_stream/get +- indices:admin/delete (delete indices) - indices:admin/exists - indices:admin/flush - indices:admin/flush* - indices:admin/forcemerge -- indices:admin/get +- indices:admin/get (retrieve index and mapping) +- indices:admin/index_template/delete +- indices:admin/index_template/get +- indices:admin/index_template/put +- indices:admin/index_template/simulate +- indices:admin/index_template/simulate_index - indices:admin/mapping/put - indices:admin/mappings/fields/get - indices:admin/mappings/fields/get* @@ -137,22 +215,23 @@ Rather than creating new action groups from individual permissions, you can ofte - indices:data/read/mget* - indices:data/read/msearch - indices:data/read/msearch/template -- indices:data/read/mtv +- indices:data/read/mtv (multi-term vectors) - indices:data/read/mtv* - indices:data/read/scroll - indices:data/read/scroll/clear - indices:data/read/search - indices:data/read/search* - indices:data/read/search/template -- indices:data/read/tv +- indices:data/read/tv (term vectors) - indices:data/write/bulk - indices:data/write/bulk* -- indices:data/write/delete +- indices:data/write/delete (delete documents) - indices:data/write/delete/byquery -- indices:data/write/index +- indices:data/write/index (add documents to existing indices) - indices:data/write/reindex - indices:data/write/update - indices:data/write/update/byquery +- indices:monitor/data_stream/stats - indices:monitor/recovery - indices:monitor/segments - indices:monitor/settings/get From 01a9fb6d6d087f5727438280bb8346536381cbad Mon Sep 17 00:00:00 2001 From: aetter Date: Tue, 28 Sep 2021 11:10:36 -0700 Subject: [PATCH 082/167] Adding async back in, just in case --- _security-plugin/access-control/permissions.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/_security-plugin/access-control/permissions.md b/_security-plugin/access-control/permissions.md index 486745e9..4a203e52 100644 --- a/_security-plugin/access-control/permissions.md +++ b/_security-plugin/access-control/permissions.md @@ -101,6 +101,10 @@ These permissions are for the cluster and can't be applied granularly. For examp - cluster:admin/opendistro/alerting/monitor/get - cluster:admin/opendistro/alerting/monitor/search - cluster:admin/opendistro/alerting/monitor/write +- cluster:admin/opendistro/asynchronous_search/stats +- cluster:admin/opendistro/asynchronous_search/delete +- cluster:admin/opendistro/asynchronous_search/get +- cluster:admin/opendistro/asynchronous_search/submit - cluster:admin/opendistro/ism/managedindex/add - cluster:admin/opendistro/ism/managedindex/change - cluster:admin/opendistro/ism/managedindex/remove From 9a5c8cd6ae639d8bc7fec68b4d35beeb0e258bc7 Mon Sep 17 00:00:00 2001 From: aetter Date: Tue, 28 Sep 2021 13:53:49 -0700 Subject: [PATCH 083/167] Wording change --- index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/index.md b/index.md index 602a8883..87301cf4 100755 --- a/index.md +++ b/index.md @@ -37,7 +37,7 @@ Component | Purpose [Anomaly Detection]({{site.url}}{{site.baseurl}}/monitoring-plugins/ad/) | Identify atypical data and receive automatic notifications [Asynchronous Search]({{site.url}}{{site.baseurl}}/search-plugins/async/) | Run search requests in the background -Most of OpenSearch plugins have a corresponding OpenSearch Dashboards plugin that provide a convenient, unified user interface. +Most OpenSearch plugins have corresponding OpenSearch Dashboards plugins that provide a convenient, unified user interface. For specifics around the project, see the [FAQ](https://opensearch.org/faq/). From d4c20f040250ab3e5fef6d43fe5f06af9ada504a Mon Sep 17 00:00:00 2001 From: aetter Date: Tue, 28 Sep 2021 15:33:48 -0700 Subject: [PATCH 084/167] Re-add LDAP Docker example Update Docker Compose file --- _security-plugin/configuration/ldap.md | 6 ++---- assets/examples/ldap-example.zip | Bin 4169 -> 5923 bytes 2 files changed, 2 insertions(+), 4 deletions(-) diff --git a/_security-plugin/configuration/ldap.md b/_security-plugin/configuration/ldap.md index 8a69ba2a..ff8da4eb 100755 --- a/_security-plugin/configuration/ldap.md +++ b/_security-plugin/configuration/ldap.md @@ -11,7 +11,6 @@ Active Directory and LDAP can be used for both authentication and authorization In most cases, you want to configure both authentication and authorization. You can also use authentication only and map the users retrieved from LDAP directly to security plugin roles. -{% comment %} ## Docker example @@ -38,7 +37,7 @@ We provide a fully functional example that can help you understand how to use an 1. Index a document as `psantos`: ```bash - curl -XPUT https://localhost:9200/new-index/_doc/1 -H 'Content-Type: application/json' -d '{"title": "Spirited Away"}' -u psantos:password -k + curl -XPUT 'https://localhost:9200/new-index/_doc/1' -H 'Content-Type: application/json' -d '{"title": "Spirited Away"}' -u 'psantos:password' -k ``` If you try the same request as `jroe`, it fails. The `Developers` group is mapped to the `readall`, `manage_snapshots`, and `kibana_user` roles and has no write permissions. @@ -46,14 +45,13 @@ We provide a fully functional example that can help you understand how to use an 1. Search for the document as `jroe`: ```bash - curl -XGET https://localhost:9200/new-index/_search?pretty -u jroe:password -k + curl -XGET 'https://localhost:9200/new-index/_search?pretty' -u 'jroe:password' -k ``` This request succeeds, because the `Developers` group is mapped to the `readall` role. 1. If you want to examine the contents of the various containers, run `docker ps` to find the container ID and then `docker exec -it /bin/bash`. -{% endcomment %} ## Connection settings diff --git a/assets/examples/ldap-example.zip b/assets/examples/ldap-example.zip index 29a2ee81eb2abae937945bedee0b8ae9c57be31f..acecc3e5c22266fc304efc68f20a275c6ac8f468 100644 GIT binary patch literal 5923 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 Qd@Q=>&JF^-gRwmO6GpYbl>h($ From 7ed1c64a3569abeb6be92b58344039bcf0a5c334 Mon Sep 17 00:00:00 2001 From: keithhc2 Date: Tue, 28 Sep 2021 16:06:54 -0700 Subject: [PATCH 085/167] Added and adjusted some more language to address comments --- _monitoring-plugins/alerting/api.md | 14 +++++++------- _monitoring-plugins/alerting/monitors.md | 16 +++++++--------- 2 files changed, 14 insertions(+), 16 deletions(-) diff --git a/_monitoring-plugins/alerting/api.md b/_monitoring-plugins/alerting/api.md index 265954ec..07bdc682 100644 --- a/_monitoring-plugins/alerting/api.md +++ b/_monitoring-plugins/alerting/api.md @@ -23,7 +23,7 @@ Use the alerting API to programmatically manage monitors and alerts. Introduced 1.0 {: .label .label-purple } -Query-level monitors run the query and check whether the results should trigger any alerts. For more information about query-level monitors versus bucket-level monitors, see [Create monitors]({{site.url}}{{site.baseurl}}/monitoring-plugins/alerting/monitors/#create-monitors). +Query-level monitors run the query and check whether the results should trigger any alerts. As such, query-level monitors can only trigger one alert at a time. For more information about query-level monitors versus bucket-level monitors, see [Create monitors]({{site.url}}{{site.baseurl}}/monitoring-plugins/alerting/monitors/#create-monitors). #### Request @@ -253,7 +253,7 @@ For a full list of timezone names, refer to [Wikipedia](https://en.wikipedia.org ## Create bucket-level monitor -Bucket-level monitors categorize results into buckets separated by fields. For more information about bucket-level monitors versus query-level monitors, see [Create monitors]({{site.url}}{{site.baseurl}}/monitoring-plugins/alerting/monitors/#create-monitors). +Bucket-level monitors categorize results into buckets separated by fields. The monitor then runs your script with each bucket's results and evaluates whether to trigger an alert. For more information about bucket-level monitors versus query-level monitors, see [Create monitors]({{site.url}}{{site.baseurl}}/monitoring-plugins/alerting/monitors/#create-monitors). ```json POST _plugins/_alerting/monitors @@ -344,11 +344,11 @@ POST _plugins/_alerting/monitors "lang": "mustache" }, "throttle_enabled": false, + "throttle": { + "value": 10, + "unit": "MINUTES" + }, "action_execution_policy": { - "throttle": { - "value": 10, - "unit": "MINUTES" - }, "action_execution_scope": { "per_alert": { "actionable_alerts": [ @@ -359,7 +359,7 @@ POST _plugins/_alerting/monitors } }, "subject_template": { - "source": "Sample subject", + "source": "The Subject", "lang": "mustache" } } diff --git a/_monitoring-plugins/alerting/monitors.md b/_monitoring-plugins/alerting/monitors.md index 7b6c999a..c7f4284d 100644 --- a/_monitoring-plugins/alerting/monitors.md +++ b/_monitoring-plugins/alerting/monitors.md @@ -103,7 +103,7 @@ POST _nodes/reload_secure_settings 1. Specify a name for the monitor. 1. Choose either **Per query monitor** or **Per bucket monitor**. -Whereas per-query monitors run your specified query and then check whether the query's results triggers any alerts, per-bucket monitors let you select fields to create buckets and categorize your results into those buckets. Doing so gives you finer control over which results should trigger alerts, as the alerting plugin uses each bucket's results to see if they should trigger any alerts. +Whereas per-query monitors run your specified query and then check whether the query's results triggers any alerts, per-bucket monitors let you select fields to create buckets and categorize your results into those buckets. The alerting plugin runs each bucket's unique results against a script you define later, so you have finer control over which results should trigger alerts. Each of those buckets can trigger an alert, but per-query monitors can only trigger one alert at a time. 1. Define the monitor in one of three ways: visually, using a query, or using an anomaly detector. @@ -156,17 +156,12 @@ Whereas per-query monitors run your specified query and then check whether the q } ``` - "Start" and "end" refer to the interval at which the monitor runs. See [Available variables](#available-variables). + "Start" and "end" refer to the interval at which the monitor runs. See [Available variables](#available-variables). - -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 one or more indices. You can also use `*` as a wildcard to specify an index pattern. + To define a monitor visually, choose **Visual editor**. Then choose a source index, a timeframe, an aggregation (for example, `count()` or `average()`), a data filter if you want to monitor a subset of your source index, and a group-by field if you want to include an aggregation field in your query. Visual definition works well for most monitors. 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/). - To define a monitor visually, choose **Visual editor**. Then choose an aggregation (for example, `count()` or `average()`), a set of documents, a timeframe, a data filter if you want to monitor a subset of your source index, and a group-by field if you want to categorize your query results into separate buckets, and trigger conditions get evaluated per bucket. At least one group-by field is required if you are creating a per bucket monitor. Visual definition works well for most monitors. - To use a query, choose **Extraction query editor**, add your query (using [the OpenSearch query DSL]({{site.url}}{{site.baseurl}}/opensearch/query-dsl/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. @@ -186,6 +181,8 @@ Whereas per-query monitors run your specified query and then check whether the q **Note**: Anomaly detection is available only if you are defining a per query monitor. {: .note} +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. Add a trigger to your monitor. --- @@ -196,6 +193,7 @@ Steps to create a trigger differ depending on whether you chose **Visual editor* You begin by specifying a name and severity level for the trigger. Severity levels help you manage alerts. A trigger with a high severity level (e.g. 1) might page a specific individual, whereas a trigger with a low severity level might message a chat room. +Remember that per-query monitors run your trigger's script just once against the query's results, but per-bucket monitors execute your trigger's script on each bucket, so you should create a trigger that best fits the monitor you chose. If you want to execute multiple scripts, you must create multiple triggers. ### Visual editor @@ -316,7 +314,7 @@ Variable | Data Type | Description `ctx.periodStart` | String | Unix timestamp for the beginning of the period during which the alert triggered. For example, if a monitor runs every ten minutes, a period might begin at 10:40 and end at 10:50. `ctx.periodEnd` | String | The end of the period during which the alert triggered. `ctx.error` | String | The error message if the trigger was unable to retrieve results or unable to evaluate the trigger, typically due to a compile error or null pointer exception. Null otherwise. -`ctx.alert` | Object | The current, active alert (if it exists). Includes `ctx.alert.id`, `ctx.alert.version`, and `ctx.alert.isAcknowledged`. Null if no alert is active. +`ctx.alert` | Object | The current, active alert (if it exists). Includes `ctx.alert.id`, `ctx.alert.version`, and `ctx.alert.isAcknowledged`. Null if no alert is active. Only available with per-query monitors. `ctx.dedupedAlerts` | Object | Alerts that have already been triggered. OpenSearch keeps the existing alert to prevent the plugin from creating endless amounts of the same alerts. Only available with bucket-level monitors. `ctx.newAlerts` | Object | Newly created alerts. Only available with bucket-level monitors. `ctx.completedAlerts` | Object | Alerts that are no longer ongoing. Only available with bucket-level monitors. From 65d2ef48600268d16372a15485f39e53e87eb04e Mon Sep 17 00:00:00 2001 From: aetter Date: Wed, 29 Sep 2021 09:29:41 -0700 Subject: [PATCH 086/167] Re-add SAML example --- _security-plugin/configuration/saml.md | 8 +++----- assets/examples/saml-example.zip | Bin 3388 -> 4580 bytes 2 files changed, 3 insertions(+), 5 deletions(-) diff --git a/_security-plugin/configuration/saml.md b/_security-plugin/configuration/saml.md index e2d71f0f..a2a789e7 100755 --- a/_security-plugin/configuration/saml.md +++ b/_security-plugin/configuration/saml.md @@ -11,7 +11,6 @@ The security plugin supports user authentication through SAML single sign-on. Th This profile is meant for use with web browsers. It is not a general-purpose way of authenticating users against the security plugin, so its primary use case is to support OpenSearch Dashboards single sign-on. -{% comment %} ## Docker example @@ -35,7 +34,6 @@ We provide a fully functional example that can help you understand how to use SA In particular, you might find it helpful to review the contents of the `/var/www/simplesamlphp/config/` and `/var/www/simplesamlphp/metadata/` directories. -{% endcomment %} ## Activating SAML @@ -300,13 +298,13 @@ authc: Because most of the SAML-specific configuration is done in the security plugin, just activate SAML in your `opensearch_dashboards.yml` by adding the following: -``` -plugins.security.auth.type: "saml" +```yml +opensearch_security.auth.type: "saml" ``` In addition, the OpenSearch Dashboards endpoint for validating the SAML assertions must be whitelisted: -``` +```yml server.xsrf.whitelist: ["/_plugins/_security/saml/acs"] ``` diff --git a/assets/examples/saml-example.zip b/assets/examples/saml-example.zip index fb0e026509185bfe051b240cfe89cca9fdee6c05..32c53c525b99791e634f2fc0d07ab84a322efe5b 100644 GIT binary patch literal 4580 zcmcIn2{hDg7ymPsk+GCLvSiQR*g_bg#Jpq}%UEU%Mz)a|TS>+;D8xjx*eTftA&DBL zC`-#*5^3|=B}(L#d^7cVlcTrOIp25ZJf8WVai06!`@g^6{aqVN5DP!RFjS-g;_H|H z{^0^70Rkq#U&SjN6Asf z9xDK-tUn4HLLlM;RPaGwfdns1FxE%K6GQOvz+-|v391nR{$E`QrrTje=!>zha}{sb z8aSX1X&F@lf2?InI{&fZd2<6QC1gC!Q|WjinEzZ&{9TItJ@}tg39pNAq;k0$xqCre zV$t)Yc~L9J`K#WOAx^Bi+m3w#AFRwhpLw-BA?=w<%!hms$(dUJaEGMDz7&#EF>hDe z10%E)yL?4R385~IwXVUKr@&;NXy%6i2a%iBbHzFFh+X8c&61(Av$pXWp# zjjKdO^ z_dCvU=&uH#$Zwn7Snfi>b^jy0#1wLQ?UOB)&LYZkypbnjr(MDi+NbaZ!P}Jb9Ewa1 z)Cb=anuA;ti|0tJ5uU;fTAn2`ZIkozWtzMT1Qw|gSkje#Cs#hG*FQ_^ z-TuS4wCycPk0e~(Y3hwT3*dA+yquLMfQg#0=ROnKEKt<{Z0Esm^PPOX0NCR8<@d z0s_%ycR3mXR)_qBhf@8UYx!+$WMd*IACbq89Tc+$`eqv4qal*5DNsX7pI}^-c8^pX zuSw!jY!&f&sHjQeww-xA@l`~EXdb&>D0Zjo*nXWWHSYP+Ib&8rO^>>}_jC#yCM${Z z9oL9=ESPklD!0813L0KqGQw!Ba7sl9pBM@eo8e~ZSZl8u&sE*vo^L(0`qiKBY1kAwp9>@bg96|p%8f|&2$%5ulkagmk-nL&JB}Y#useao$VPyfHjPdgG8>oJqsH%y z^fhjmkFStPZ)LKybcNFvZB#R*i>jx}*m;dbVRErV78a*K&$oKAC-BzRCutA%zo%1aohmbS4t_GRQeO88+vX3*|~t#MwM^77derxjRR*ccdaxy%wPZiy(Pf zOzcA_vFZ1K{(>wfWi-l(jYL>DRs?1@G-LXy2@)?0wEuScyLROxrfONmoTY%eq&}(j zd?16Cmryzi7&ktx?rzrb>dkYb#65e{65iD?t_`oKn4p*p$wVTPE?SVo@+J$(Jg-~# z>QhMaOPblz(e)1|?nL97$Hdt}0#tAJH9Z#VG(j!Ac#-=#o_qe9j^-5yq*WV{ZL0Lq zY*g5RkO$;HW8EoDwPLSiM9QvajgorL5qD)hs5WYIjVjcRefi}^laF_uM9cjzbFY>6 z9$TJRez7#S#UVUlq45q^RI5tVZT>9(+tYo!QJ1-nEW9hIt13FisOVNCkb0MnaYjvS zTrGdn>uCGGRP;{@=eJ6F)i=#SHHCOka7EBt(?N6P#>(7uI} zKHejReh1MQw6{l~_nRq?yWcR9>1|j{rpLvI?R(T`*T|#zO#mRV9wVN3te;n~3Kky_ zgeQ3YgO&I+J4^z7G4^#>d4fdY`_=iQMjgZsz>i9?_`qCc#2;O<9jIr`4D3gFQb4m? z2hO}T9;Z@sf;BYvRUmZU-tHTn{;;TzA=@5k1?d{@s#45=ZY|p63vAz8mDZvAksouW z-7F@c9LP_$(g;!xR*dqfSWc1g(Lr^G9^A%R#WAcP{YT&Fb9{|;riMkfL1dR3a?CT5 zJ)24nXjc-BJq^3$B0AvsNz)|aPcff*`rNd z+HdZ9G*+ta5#=v9*{Z`VBk5BO)r%CwBEuKCiBN`kpcqqA?QB!3HH=`zcC|HQ@O$rw z?64tFM$Ip$x=BFPrp<+3FK2a*>3tSAk9~cs^xZPLY+zbl{ha)@OXpm=T#^JJVC(4g zi^0d>-Ym8p&+PLjS$-ec>VNNR( z;QTgI_E+^!V=_A0HV0`Gh)nk{G!350tqgaPRqGQjf#XqJy=JYZ9kn=+^w!M5gqsEn z18+Rkklo&PvzZyyzM31&LmfDN^WNMZKCZP zYRrDCdsSQq&PtevC-VkVRC2T8hDt|G43X}G3JZ|*p1oY@J?Na9S3&}>AG>7^AyFpzBFKuEyJXs-Mq5qv2TS{YKR#RL*s7oYQL8jj=!RV zUNOpyZOd&g_iSXHDU>vjef+evZttn)Ew?g9zc_`8r>YiG9Y$Zf_Fd_Qwm|)5&g2-0 z8idiR^6Go&0Zyb&&CSVFTQ1X1=tY!eIcx8yKUWmaYI&BcuQM%4zAZKGt zF|@>ve_@he!0Y!I<$tNH-W@OZfE}Oiz2*}$W^xn+;@sm0-Gjhda(*!NTZwsGXzB+g z2ssEzL$R(1f{ueL9|*zcx)%x+a$Ir%# zjoocf?Q7jJ^xWFs&CqkJR!lNyTNlz#n)C+hZoQMWt&$-FR;`#s1phpypZNPlP>cq= zmPQy2c-4wYz8vd<`UPKX(2myz$8fe5j0|R4wPMnB$j^iOh2IT>WTn3m0N|j1#_2^r I%*A;659D54xX6c= z8RXTqu2j6s-Qa%x4fW$YV2js*XL1(>&+k-wq((f3`|n6DfXU^Y5pUvXHDd?3dSgXc z!=MU1c3Wd(;~Q|gP2pXM+`8h|C-CA%Dlx`!HwlhUn(uX4HU+8OJ>J1OP|@8-lRv9o z^r*qK8s3`Gv7d~DYPCjGNZmZGakJV=`m)7AW!JeX?uKE-6P-`)UDK9uTk2O zlIkdLu?x+aiQM6;=VHu9w_Z!+OijNF&Gt$=6f`JPU%9WM$LE1Vu66-}YC_)&ZIe;p z&cD^!BhGb09Z4c8oD*AXyL_Qz($ zu2L75irjgP`UBdw6p*(L1bS#CLo@oo1Br*z_R^*%D(UGgE1R7d;+5{V16igW#wm>m z9_EzRn10OO4@zB#f{NE;{fKnFM-ekV`F(zl9khDeHKrCUMKIMN{?k2(fn0#H_V^-R z5Bpp??bvxevU`o@1n=9451~JLE(Ob=d4MAeW`-}$sFL>2xhh)1y;41p_cK=>jvg2H z$JUhh?w-suPoA;uh?8!Ck!%)Xn&i0Jmfe+&Y!~_i3@?4OJM?6w#1EV?*0$r+gWhfh zl3RFq$M9ZSndLi`ECxHZ|F+?C>2H8I3>3EK#lmO|2mlb_`;U=dDI}7S5cytSSaVB9 z{2{$h*rer!NaD_#B3ZZQQMW$l27Ou2dX}?9MUn>`8u+ z_C4rJ%MbQ;M46wK?`Uo%xY>J<3})WEZ&xLkpUSvA9TR;aFed#Ar-^*2 zLg`-)B-%PFo=?m%DB5~?%v!fY-o8*i*n1{`zvx$$t9`XsHssQNeCFLtb2)i!)y76o zsWI_PP9c9-=HBM;NsViB3bV{q<#)**?-Hbl*X8S|M}yi7r|-w4boQyQd;|_ky8gy9 zAOIkO$8W&7zQz@LB>(``^}z9E_#B~zqI?*1CL@gcD}XKwePDI115g)XkkO|PKQ-$W zQjq;K2uw5gRR33}{FSmk*1^3qsGX0^%O6Ghnc#lzZg+S)4C$FD4(v;*n&p`c4jdiV zx4lw2WR{zEDGzZjY)j$1Bfu(+sFo4ZH?;k3bruk3<2NBj8FgneQjl3yL)o~roi9&s zcImQ~urMoeW+o8%x52anx$<^}L5J&jKGhrsQ_!}FHq~z-bJg3xwl+xnfx2CMXCTy* z3o|y!z&Y&EaDR}r&qiTEVXv&(%}&lJHo?A$dhX0p6_?6lN~+67L8PwYJCJPiLny?v z?D>mq2|sVAnu}-A36js)qqR?i?sP*a;mT1`1;Z0+(|dWly68uhF0^G1JZn{HRd0}l zoYrb+!q@UO!azvQR=Ma$#s|L=-({sfRfg>`)C3L)pm016lW7_k!t^3}`kr&D5ZtVI zNm2!#yAY_lWhQl-#?BBh(LNx-HHzE6Z?-qd&1s&E#q~|mBkpD+E=aly0%=whcP7HV zMnE4mBp0YzT6Q((3^i;}<#3&GS!eBBkU1&k}9rz~+HB|v8 ziWf`51;p#q0JHYw&1219SWAvrIM*)-aul`Fxbtk{!I=kds=g0=8`*1jg5a%yw>q<5 zQriG2WoQv_N@>`@q5)kUMM{;it%uKt#0YF^O+MuDRac&vq{WQ$H?I`>FV$=Pkgiqm zx?SrfeI^H<B1hYj9( zSE%|8>Br}vNsioV5l~xdFl`y0#N6e`D=HUj?mvEFOLOxhjmmb9A7OlW>?qP;emi&S zh0tb1g!yACiPTy9FKp&BtorATCCZH`FI6xrsH3rIALU`Q&UOItS6=~w9Ol!~Yn@ay60AlM%UTTZ zj|~WGPa$&cwX!U7?bRq^A%sHx$-njazdd|y5s|{L1*}NnSEGnUfvhX?8Dxqy|1bWl rsMuO0i8!ztMXYimU;b?H`b^zFU<3{$E<8K{01;lrLN>-qir)SUDuy(d From 973d967514c325f6a27a5da6599433ebea86057a Mon Sep 17 00:00:00 2001 From: aetter Date: Wed, 29 Sep 2021 14:57:46 -0700 Subject: [PATCH 087/167] Update impersonation.md --- _security-plugin/access-control/impersonation.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/_security-plugin/access-control/impersonation.md b/_security-plugin/access-control/impersonation.md index 82966389..100d1104 100644 --- a/_security-plugin/access-control/impersonation.md +++ b/_security-plugin/access-control/impersonation.md @@ -41,8 +41,8 @@ plugins.security.authcz.impersonation_dn: ## Impersonating Users -To impersonate another user, submit a request to the system with the HTTP header `opensearch_security_impersonate_as` set to the name of the user to be impersonated. A good test is to make a GET request to the `_plugins/_security/authinfo` URI: +To impersonate another user, submit a request to the system with the HTTP header `opendistro_security_impersonate_as` set to the name of the user to be impersonated. A good test is to make a GET request to the `_plugins/_security/authinfo` URI: ```bash -curl -XGET -u 'admin:admin' -k -H "opensearch_security_impersonate_as: user_1" https://localhost:9200/_plugins/_security/authinfo?pretty +curl -XGET -u 'admin:admin' -k -H "opendistro_security_impersonate_as: user_1" https://localhost:9200/_plugins/_security/authinfo?pretty ``` From a186b4630211f1e56b91366ad23e96cf8c3e80d6 Mon Sep 17 00:00:00 2001 From: keithhc2 Date: Thu, 30 Sep 2021 12:00:37 -0700 Subject: [PATCH 088/167] Added trigger instructions for bucket-level monitors --- _monitoring-plugins/alerting/monitors.md | 36 ++++++++++++++++++++---- 1 file changed, 30 insertions(+), 6 deletions(-) diff --git a/_monitoring-plugins/alerting/monitors.md b/_monitoring-plugins/alerting/monitors.md index c7f4284d..1b81fe99 100644 --- a/_monitoring-plugins/alerting/monitors.md +++ b/_monitoring-plugins/alerting/monitors.md @@ -103,7 +103,7 @@ POST _nodes/reload_secure_settings 1. Specify a name for the monitor. 1. Choose either **Per query monitor** or **Per bucket monitor**. -Whereas per-query monitors run your specified query and then check whether the query's results triggers any alerts, per-bucket monitors let you select fields to create buckets and categorize your results into those buckets. The alerting plugin runs each bucket's unique results against a script you define later, so you have finer control over which results should trigger alerts. Each of those buckets can trigger an alert, but per-query monitors can only trigger one alert at a time. +Whereas query-level monitors run your specified query and then check whether the query's results triggers any alerts, bucket-level monitors let you select fields to create buckets and categorize your results into those buckets. The alerting plugin runs each bucket's unique results against a script you define later, so you have finer control over which results should trigger alerts. Each of those buckets can trigger an alert, but query-level monitors can only trigger one alert at a time. 1. Define the monitor in one of three ways: visually, using a query, or using an anomaly detector. @@ -158,7 +158,7 @@ Whereas per-query monitors run your specified query and then check whether the q "Start" and "end" refer to the interval at which the monitor runs. See [Available variables](#available-variables). - To define a monitor visually, choose **Visual editor**. Then choose a source index, a timeframe, an aggregation (for example, `count()` or `average()`), a data filter if you want to monitor a subset of your source index, and a group-by field if you want to include an aggregation field in your query. Visual definition works well for most monitors. + To define a monitor visually, choose **Visual editor**. Then choose a source index, a timeframe, an aggregation (for example, `count()` or `average()`), a data filter if you want to monitor a subset of your source index, and a group-by field if you want to include an aggregation field in your query. At least one group-by field is required if you're defining a bucket-level monitor. Visual definition works well for most monitors. 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/). @@ -193,18 +193,20 @@ Steps to create a trigger differ depending on whether you chose **Visual editor* You begin by specifying a name and severity level for the trigger. Severity levels help you manage alerts. A trigger with a high severity level (e.g. 1) might page a specific individual, whereas a trigger with a low severity level might message a chat room. -Remember that per-query monitors run your trigger's script just once against the query's results, but per-bucket monitors execute your trigger's script on each bucket, so you should create a trigger that best fits the monitor you chose. If you want to execute multiple scripts, you must create multiple triggers. +Remember that query-level monitors run your trigger's script just once against the query's results, but bucket-level monitors execute your trigger's script on each bucket, so you should create a trigger that best fits the monitor you chose. If you want to execute multiple scripts, you must create multiple triggers. ### Visual editor -For **Trigger condition**, specify a threshold for the aggregation and timeframe you chose earlier, such as "is below 1,000" or "is exactly 10." +For a query-level monitor's **Trigger condition**, specify a threshold for the aggregation and timeframe you chose earlier, such as "is below 1,000" or "is exactly 10." The line moves up and down as you increase and decrease the threshold. Once this line is crossed, the trigger evaluates to true. +Bucket-level monitors also require you to specify a threshold and value for your aggregation and timeframe, but you can use a maximum of five conditions to better refine your trigger. Optionally, you can also use a keyword filter to filter for a specific field in your index. + ### Extraction query -For **Trigger condition**, specify a Painless script that returns true or false. Painless is the default OpenSearch scripting language and has a syntax similar to Groovy. +If you're using a query-level monitor, specify a Painless script that returns true or false. Painless is the default OpenSearch scripting language and has a syntax similar to Groovy. Trigger condition scripts revolve around the `ctx.results[0]` variable, which corresponds to the extraction query response. For example, your script might reference `ctx.results[0].hits.total.value` or `ctx.results[0].hits.hits[i]._source.error_code`. @@ -213,6 +215,27 @@ A return value of true means the trigger condition has been met, and the trigger The **Info** link next to **Trigger condition** contains a useful summary of the variables and results available to your query. {: .tip } +Bucket-level monitors require you to specify more information in your trigger condition. At a minimum, you must have the following fields: + +- `buckets_path`, which maps variable names to metrics to use in your script. +- `parent_bucket_path`, which is a path to a multi-bucket aggregation. The path can include single-bucket aggregations, but the last aggregation must be multi-bucket. For example, if you have a pipeline such as `agg1>agg2>agg3`, `agg1` and `agg2` are single-bucket aggregations, but `agg3` must be a multi-bucket aggregation. +- `script`, which is the script that OpenSearch runs to evaluate whether to trigger any alerts. + +For example, you might have a script that looks like the following: + +```json +{ + "buckets_path": { + "count_var": "_count" + }, + "parent_bucket_path": "composite_agg", + "script": { + "source": "params.count_var > 5" + } +} +``` + +After mapping the `count_var` variable to the `_count` metric, you can use `count_var` in your script and reference `_count` data. Finally, `composite_agg` is a path to a multi-bucket aggregation. ### Anomaly detector @@ -314,7 +337,7 @@ Variable | Data Type | Description `ctx.periodStart` | String | Unix timestamp for the beginning of the period during which the alert triggered. For example, if a monitor runs every ten minutes, a period might begin at 10:40 and end at 10:50. `ctx.periodEnd` | String | The end of the period during which the alert triggered. `ctx.error` | String | The error message if the trigger was unable to retrieve results or unable to evaluate the trigger, typically due to a compile error or null pointer exception. Null otherwise. -`ctx.alert` | Object | The current, active alert (if it exists). Includes `ctx.alert.id`, `ctx.alert.version`, and `ctx.alert.isAcknowledged`. Null if no alert is active. Only available with per-query monitors. +`ctx.alert` | Object | The current, active alert (if it exists). Includes `ctx.alert.id`, `ctx.alert.version`, and `ctx.alert.isAcknowledged`. Null if no alert is active. Only available with query-level monitors. `ctx.dedupedAlerts` | Object | Alerts that have already been triggered. OpenSearch keeps the existing alert to prevent the plugin from creating endless amounts of the same alerts. Only available with bucket-level monitors. `ctx.newAlerts` | Object | Newly created alerts. Only available with bucket-level monitors. `ctx.completedAlerts` | Object | Alerts that are no longer ongoing. Only available with bucket-level monitors. @@ -345,6 +368,7 @@ If you don't want to receive notifications for alerts, you don't have to add act ``` In this case, the message content must conform to the `Content-Type` header in the [custom webhook](#create-destinations). +1. If you're using a bucket-level monitor, you can choose whether the monitor should perform an action for each execution or for each alert. 1. (Optional) Use action throttling to limit the number of notifications you receive within a given span of time. From d4342aab59f119706f44ef88d0a8a5638331daa4 Mon Sep 17 00:00:00 2001 From: aetter Date: Thu, 30 Sep 2021 13:43:24 -0700 Subject: [PATCH 089/167] Initial 1.1.0 updates --- README.md | 8 ++++---- _config.yml | 6 +++--- _opensearch/install/plugins.md | 18 ++++++++++++++++++ _opensearch/install/tar.md | 5 +++-- 4 files changed, 28 insertions(+), 9 deletions(-) diff --git a/README.md b/README.md index 093941af..a9bd14e2 100644 --- a/README.md +++ b/README.md @@ -196,17 +196,17 @@ If you're making major changes to the documentation and need to see the rendered ## New releases 1. Branch. -1. Change the `opensearch_version` and `opensearch_major_minor_version` variables in `_config.yml`. +1. Change the `opensearch_version`, `opensearch_major_minor_version`, and `lucene_version` variables in `_config.yml`. 1. Start up a new cluster using the updated Docker Compose file in `docs/install/docker.md`. 1. Update the version table in `version-history.md`. - Use `curl -XGET https://localhost:9200 -u admin:admin -k` to verify the OpenSearch version. + Use `curl -XGET https://localhost:9200 -u admin:admin -k` to verify the OpenSearch and Lucene versions. -1. Update the plugin compatibility table in `docs/install/plugin.md`. +1. Update the plugin compatibility table in `_opensearch/install/plugin.md`. Use `curl -XGET https://localhost:9200/_cat/plugins -u admin:admin -k` to get the correct version strings. -1. Update the plugin compatibility table in `docs/opensearch-dashboards/plugins.md`. +1. Update the plugin compatibility table in `_dashboards/install/plugins.md`. Use `docker ps` to find the ID for the OpenSearch Dashboards node. Then use `docker exec -it /bin/bash` to get shell access. Finally, run `./bin/opensearch-dashboards-plugin list` to get the plugins and version strings. diff --git a/_config.yml b/_config.yml index ae992e6d..e22718a4 100644 --- a/_config.yml +++ b/_config.yml @@ -5,9 +5,9 @@ baseurl: "/docs" # the subpath of your site, e.g. /blog url: "https://opensearch.org" # the base hostname & protocol for your site, e.g. http://example.com permalink: /:path/ -opensearch_version: 1.0.1 -opensearch_major_minor_version: 1.0 -lucene_version: 8_8_2 +opensearch_version: 1.1.0 +opensearch_major_minor_version: 1.1 +lucene_version: 8_9_0 # Build settings markdown: kramdown diff --git a/_opensearch/install/plugins.md b/_opensearch/install/plugins.md index 40fdefc7..bd0d2d01 100644 --- a/_opensearch/install/plugins.md +++ b/_opensearch/install/plugins.md @@ -29,6 +29,24 @@ If you don't want to use the all-in-one OpenSearch installation options, you can + + 1.1.0 + +
opensearch-alerting                  1.1.0.0
+opensearch-anomaly-detection         1.1.0.0
+opensearch-asynchronous-search       1.1.0.0
+opensearch-cross-cluster-replication 1.1.0.0
+opensearch-index-management          1.1.0.0
+opensearch-job-scheduler             1.1.0.0
+opensearch-knn                       1.1.0.0
+opensearch-notebooks                 1.1.0.0
+opensearch-performance-analyzer      1.1.0.0
+opensearch-reports-scheduler         1.1.0.0
+opensearch-security                  1.1.0.0
+opensearch-sql                       1.1.0.0
+
+ + 1.0.1 diff --git a/_opensearch/install/tar.md b/_opensearch/install/tar.md index af45a3af..70151f5f 100644 --- a/_opensearch/install/tar.md +++ b/_opensearch/install/tar.md @@ -18,9 +18,10 @@ The tarball supports most Linux distributions, including CentOS 7, Amazon Linux ```bash # x64 tar -zxf opensearch-{{site.opensearch_version}}-linux-x64.tar.gz - cd opensearch-{{site.opensearch_version}}{% comment %}# ARM64 + cd opensearch-{{site.opensearch_version}} + # ARM64 tar -zxf opensearch-{{site.opensearch_version}}-linux-arm64.tar.gz - cd opensearch-{{site.opensearch_version}}{% endcomment %} + cd opensearch-{{site.opensearch_version}} ``` 1. Run OpenSearch: From ab00a055490e09d13d5b45c5a5e682e8465f1002 Mon Sep 17 00:00:00 2001 From: aetter Date: Thu, 30 Sep 2021 13:48:32 -0700 Subject: [PATCH 090/167] Comment out Java for now --- _clients/index.md | 2 ++ _clients/python.md | 2 +- 2 files changed, 3 insertions(+), 1 deletion(-) diff --git a/_clients/index.md b/_clients/index.md index d920e16a..2f3513dd 100644 --- a/_clients/index.md +++ b/_clients/index.md @@ -13,7 +13,9 @@ OpenSearch provides clients for several popular programming languages, with more For example, a 1.0.0 client works with an OpenSearch 1.1.0 cluster, but might not support any non-breaking API changes in OpenSearch 1.1.0. A 1.2.0 client works with the same cluster, but might allow you to pass unsupported options in certain functions. We recommend using the same version for both, but if your tests pass after a cluster upgrade, you don't necessarily need to upgrade your clients immediately. +{% comment %} * [OpenSearch Java client]({{site.url}}{{site.baseurl}}/clients/java/) +{% endcomment %} * [OpenSearch Python client]({{site.url}}{{site.baseurl}}/clients/python/) * [OpenSearch JavaScript (Node.js) client]({{site.url}}{{site.baseurl}}/clients/javascript/) * [OpenSearch Go client]({{site.url}}{{site.baseurl}}/clients/go/) diff --git a/_clients/python.md b/_clients/python.md index 9ce68bca..10a856a2 100644 --- a/_clients/python.md +++ b/_clients/python.md @@ -6,7 +6,7 @@ nav_order: 70 # Python client -The OpenSearch Python client provides a more natural syntax for interacting with your cluster. Rather than sending HTTP requests with raw JSON bodies to a given URL, you can create an OpenSearch client for your cluster and call the client's built-in functions. +The OpenSearch Python client provides a more natural syntax for interacting with your cluster. Rather than sending HTTP requests to a given URL, you can create an OpenSearch client for your cluster and call the client's built-in functions. {% comment %} `opensearch-py` is the lower-level of the two Python clients. If you want a general client for assorted operations, it's a great choice. If you want a higher-level client strictly for indexing and search operations, consider [opensearch-dsl-py]({{site.url}}{{site.baseurl}}/clients/python-dsl/). From 7cb714894fba8d1401dbab84824384b226cea616 Mon Sep 17 00:00:00 2001 From: aetter Date: Thu, 30 Sep 2021 13:52:34 -0700 Subject: [PATCH 091/167] Nitpicks --- _clients/javascript.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/_clients/javascript.md b/_clients/javascript.md index cb308a29..c670e4b8 100644 --- a/_clients/javascript.md +++ b/_clients/javascript.md @@ -1,18 +1,18 @@ --- layout: default -title: Javascript client +title: JavaScript client nav_order: 90 --- -# Javascript client +# JavaScript client -The OpenSearch Javascript client provides a safer and easier way to interact with your OpenSearch cluster. Rather than using OpenSearch from the browser and potentially exposing your data to the public, you can build an OpenSearch client that takes care of sending requests to your cluster. +The OpenSearch JavaScript client provides a safer and easier way to interact with your OpenSearch cluster. Rather than using OpenSearch from the browser and potentially exposing your data to the public, you can build an OpenSearch client that takes care of sending requests to your cluster. The client contains a library of APIs that let you perform different operations on your cluster and return a standard response body. The example here demonstrates some basic operations like creating an index, adding documents, and searching your data. ## Setup -To add the client to your project, install it from npm: +To add the client to your project, install it from [npm](https://www.npmjs.com): ```bash npm install @opensearch-project/opensearch From c378da8799fa3c10e85dc42905c859cf902e28f7 Mon Sep 17 00:00:00 2001 From: aetter Date: Thu, 30 Sep 2021 14:01:14 -0700 Subject: [PATCH 092/167] Make name more explicit --- _clients/java-rest-high-level.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/_clients/java-rest-high-level.md b/_clients/java-rest-high-level.md index def97086..892f7341 100644 --- a/_clients/java-rest-high-level.md +++ b/_clients/java-rest-high-level.md @@ -1,10 +1,10 @@ --- layout: default -title: Java high-level REST client +title: Elasticsearch OSS Java high-level REST client nav_order: 60 --- -# Java high-level REST client +# Elasticsearch OSS 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. @@ -22,7 +22,7 @@ To start using the Elasticsearch OSS Java high-level REST client, ensure that yo ``` -You can now start your OpenSearch cluster. The 7.10.2 high-level REST client works with the 1.x versions of OpenSearch. +You can now start your OpenSearch cluster. The 7.10.2 Elasticsearch OSS high-level REST client works with the 1.x versions of OpenSearch. ## Sample code From 5862b1b300fda22885b9fb89745330cd929e7ad6 Mon Sep 17 00:00:00 2001 From: Liz Snyder Date: Thu, 30 Sep 2021 16:10:28 -0700 Subject: [PATCH 093/167] First crack at CCR docs --- _config.yml | 6 + _replication-plugin/api.md | 243 ++++++++++++++++ _replication-plugin/auto-follow.md | 76 +++++ _replication-plugin/get-started.md | 271 ++++++++++++++++++ _replication-plugin/index.md | 19 ++ _replication-plugin/permissions.md | 78 +++++ _replication-plugin/settings.md | 32 +++ .../access-control/permissions.md | 11 + .../access-control/users-roles.md | 2 + 9 files changed, 738 insertions(+) create mode 100644 _replication-plugin/api.md create mode 100644 _replication-plugin/auto-follow.md create mode 100644 _replication-plugin/get-started.md create mode 100644 _replication-plugin/index.md create mode 100644 _replication-plugin/permissions.md create mode 100644 _replication-plugin/settings.md diff --git a/_config.yml b/_config.yml index ae992e6d..22daf67d 100644 --- a/_config.yml +++ b/_config.yml @@ -45,6 +45,9 @@ collections: im-plugin: permalink: /:collection/:path/ output: true + replication-plugin: + permalink: /:collection/:path/ + output: true monitoring-plugins: permalink: /:collection/:path/ output: true @@ -81,6 +84,9 @@ just_the_docs: im-plugin: name: Index management plugin nav_fold: true + replication-plugin: + name: Replication plugin + nav_fold: true monitoring-plugins: name: Monitoring plugins nav_fold: true diff --git a/_replication-plugin/api.md b/_replication-plugin/api.md new file mode 100644 index 00000000..a552d1c2 --- /dev/null +++ b/_replication-plugin/api.md @@ -0,0 +1,243 @@ +--- +layout: default +title: API +nav_order: 50 +--- + +# Cross-cluster replication API + +Use these replication operations to programmatically manage cross-cluster replication. + +#### Table of contents +- TOC +{:toc} + +## Start replication +Introduced 1.1 +{: .label .label-purple } + +Initiate replication of an index from the leader cluster to the follower cluster. Run this operation on the follower cluster. + + +#### Request + +```json +PUT /_plugins/_replication//_start +{ + "leader_alias":"", + "leader_index":"", + "use_roles":{ + "leader_cluster_role":"", + "follower_cluster_role":"" + } +} +``` + +Specify the following options: + +Options | Description | Type | Required +:--- | :--- |:--- |:--- | +`leader_alias` | The name of the leader cluster. | `string` | Yes +`leader_index` | The index on the leader cluster that you want to replicate. | `string` | Yes +`use_roles` | The roles to use for all subsequent backend replication tasks between the indices. Specify a `leader_cluster_role` and `follower_cluster_role`. See [Map the leader and follower cluster roles]({{site.url}}{{site.baseurl}}/replication-plugin/permissions/#map-the-leader-and-follower-cluster-roles). | `string` | If security plugin is enabled + +#### Sample response + +```json +{ + "acknowledged": true +} +``` + +## Stop replication +Introduced 1.1 +{: .label .label-purple } + +Terminates replication and converts the follower index to a standard index. + +#### Request + +```json +POST /_plugins/_replication//_stop +``` + +#### Sample response + +```json +{ + "acknowledged": true +} +``` + +## Pause replication +Introduced 1.1 +{: .label .label-purple } + +Pauses replication of the leader index. If you don't resume replication after 12 hours, it stops completely and the follower index is converted to a standard index. + +#### Request + +```json +PUT /_plugins/_replication//_pause +``` + +#### Sample response + +```json +{ + "acknowledged": true +} +``` + +## Resume replication +Introduced 1.1 +{: .label .label-purple } + +Resumes replication of the leader index. + +#### Request + +```json +PUT /_plugins/_replication//_resume +``` + +#### Sample response + +```json +{ + "acknowledged": true +} +``` + +## Get replication status +Introduced 1.1 +{: .label .label-purple } + +Gets the status of index replication. You can use this API to measure replication lag. Run this command from the leader cluster. + +#### Request + +```json +GET /_plugins/_replication//_status +``` + +#### Sample response + +```json +{ + "status":"SYNCING", + "reason":"User initiated", + "remote_cluster":"remote-cluster", + "leader_index":"leader-01", + "follower_index":"follower-01", + "syncing_details":{ + "remote_checkpoint": 19, + "local_checkpoint": 19, + "seq_no": 20 + } +} +``` + +To include shard replication details in the response, add `&verbose=true`. + +## Update settings +Introduced 1.1 +{: .label .label-purple } + +Updates settings on the follower index. + +#### Request + +```json +PUT /_plugins/_replication//_update +{ + "settings":{ + "index.number_of_shards": 4, + "index.number_of_replicas": 2 + } +} +``` + +#### Sample response + +```json +{ + "acknowledged": true +} +``` + +## Create replication rule +Introduced 1.1 +{: .label .label-purple } + +Automatically starts replication on indices matching a specified pattern. Newly created indices on the remote cluster that match one of the specified patterns will be automatically configured as follower indices. You can also use this API to update existing auto-follow patterns. + +Run this command on the follower cluster. + +Make sure to note the names of all auto-follow patterns after you create them. The replication plugin currently does not include an API operation to retrieve a list of existing patterns. +{: .tip } + +#### Request + +```json +POST /_plugins/_replication/_autofollow +{ + "leader_alias" : "", + "name": "", + "pattern": "", + "use_roles":{ + "leader_cluster_role": "", + "follower_cluster_role": "" + } +} +``` + +Specify the following options: + +Options | Description | Type | Required +:--- | :--- |:--- |:--- | +`leader_alias` | The name of the remote cluster to associate the pattern with. | `string` | Yes +`name` | A name for the auto-follow pattern. | `string` | Yes +`pattern` | An array of index patterns to match against indices in the specified leader cluster. Supports wildcard characters. For example, `leader-*`. | `string` | Yes +`use_roles` | The roles to use for all subsequent backend replication tasks between the indices. Specify a `leader_cluster_role` and `follower_cluster_role`. See [Map the leader and follower cluster roles]({{site.url}}{{site.baseurl}}/replication-plugin/permissions/#map-the-leader-and-follower-cluster-roles). | `string` | If security plugin is enabled + +#### Sample response + +```json +{ + "acknowledged": true +} +``` + +## Delete replication rule +Introduced 1.1 +{: .label .label-purple } + +Deletes the specified replication rule. This operation prevents any new indices from being replicated but does not stop existing replication that the rule has already initiated. + +Run this command on the follower cluster. + +#### Request + +```json +DELETE /_plugins/_replication/_autofollow +{ + "leader_alias" : "", + "name": "", +} +``` + +Specify the following options: + +Options | Description | Type | Required +:--- | :--- |:--- |:--- | +`leader_alias` | The name of the remote cluster that the pattern is associated with. | `string` | Yes +`name` | The name of the pattern. | `string` | Yes + +#### Sample response + +```json +{ + "acknowledged": true +} +``` diff --git a/_replication-plugin/auto-follow.md b/_replication-plugin/auto-follow.md new file mode 100644 index 00000000..2af9551c --- /dev/null +++ b/_replication-plugin/auto-follow.md @@ -0,0 +1,76 @@ +--- +layout: default +title: Auto-follow +nav_order: 20 +has_children: false + +--- + +# Auto-follow for cross-cluster replication + +Auto-follow lets you automatically replicate indices created on the leader cluster based on matching patterns. When you create an index on the leader cluster with a name that matches a specified pattern (for example, `index-01*`), a corresponding follower index is automatically created on the follower cluster. + +You can configure multiple replication rules for a single cluster. The patterns currently only support wildcard matching. + +## Prerequisites + +You need to [set up a cross-cluster connection]({{site.url}}{{site.baseurl}}/replication-plugin/get-started/#set-up-a-cross-cluster-connection) between two clusters before you can enable auto-follow. + +## Permissions + +If the security plugin is enabled, non-admin users need to be mapped to the appropriate permissions in order to perform replication actions. For index and cluster-level permissions requirements, see [Cross-cluster replication permissions]({{site.url}}{{site.baseurl}}/replication-plugin/permissions/). + +## Get started with auto-follow + +Replication rules are a collection of patterns that you create against a single remote cluster. When you create a replication rule, it automatically starts replicating any *new* indices that match the pattern, but does not replicate matching indices that were previously created. + +Make sure to note the names of all rules when you create them. The replication plugin currently does not include an API operation to retrieve a list of existing rules. +{: .tip } + +Create a replication rule on the follower cluster: + +```bash +curl -XPOST -k -H 'Content-Type: application/json' -u 'admin:admin' 'https://localhost:9200/_plugins/_replication/_autofollow?pretty' -d ' +{ + "leader_alias" : "leader-cluster", + "name": "my-replication-rule", + "pattern": "movies*", + "use_roles":{ + "leader_cluster_role": "all_access", + "follower_cluster_role": "all_access" + } +}' +``` + +If the security plugin is disabled, you can leave out the `use_roles` parameter. If it's enabled, however, you need to specify the leader and follower cluster roles that OpenSearch will use to authenticate the request. This example uses `all_access` for simplicity, but we recommend creating a replication user on each cluster and [mapping it accordingly]({{site.url}}{{site.baseurl}}/replication-plugin/permissions/#map-the-leader-and-follower-cluster-roles). +{: .tip } + +To test the rule, create a matching index on the leader cluster: + +```bash +curl -XPUT -k -H 'Content-Type: application/json' -u 'admin:admin' 'https://localhost:9201/movies-0001' +``` + +And confirm its replica shows up on the follower cluster: + +```bash +curl -XGET -u 'admin:admin' -k 'https://localhost:9200/_cat/indices?v' +``` + +```bash +health status index uuid pri rep docs.count docs.deleted store.size pri.store.size +yellow open movies-0001 kHOxYYHxRMeszLjTD9rvSQ 1 1 0 0 208b 208b +``` + +## Delete a replication rule + +When you delete a replication rule, OpenSearch stops replicating *new* indices that match the pattern, but replication of existing indices that the rule previously created will continue. If you need to stop existing replication activity, use the [stop replication API operation]({{site.url}}{{site.baseurl}}/replication-plugin/api/#stop-replication). + +```bash +curl -XDELETE -k -H 'Content-Type: application/json' -u 'admin:admin' 'https://localhost:9200/_plugins/_replication/_autofollow?pretty' -d ' +{ + "leader_alias" : "leader-cluster", + "name": "my-replication-rule" +}' +``` + diff --git a/_replication-plugin/get-started.md b/_replication-plugin/get-started.md new file mode 100644 index 00000000..00576fa4 --- /dev/null +++ b/_replication-plugin/get-started.md @@ -0,0 +1,271 @@ +--- +layout: default +title: Get started +nav_order: 10 +--- + +# Get started with cross-cluster replication + +With cross-cluster replication, you index data to a leader index and that data is replicated to one or more read-only follower indices. All subsequnt operations on the leader are replicated on the follower, such as creating, updating, or deleting documents. + +## Prerequisites + +Cross-cluster replication has the following prerequisites: +- Install the replication plugin on all nodes of both the leader and the follower cluster. +- If you've overridden `node.roles` in opensearch.yml on the remote cluster, make sure it also includes the `remote_cluster_client` role: + + ```yaml + node.roles: [, remote_cluster_client] + ``` + +## Permissions + +Make sure the security plugin is either enabled on both clusters or disabled on both clusters. If you disabled the security plugin, you can skip this section. + +If the security plugin is enabled, non-admin users need to be mapped to the appropriate permissions in order to perform replication actions. For index and cluster-level permissions requirements, see [Cross-cluster replication permissions]({{site.url}}{{site.baseurl}}/replication-plugin/permissions/). + +In addition, add the following setting to opensearch.yml on the leader cluster so it allows connections from the follower cluster: + +```yml +plugins.security.nodes_dn_dynamic_config_enabled: true +``` + +## Example setup + +Save this sample file as `docker-compose.yml` and run `docker-compose up` to start two single-node clusters on the same network: + +```yml +version: '3' +services: + replication-node1: + image: opensearchproject/opensearch:{{site.opensearch_version}} + container_name: replication-node1 + environment: + - cluster.name=leader-cluster + - discovery.type=single-node + - bootstrap.memory_lock=true + - "OPENSEARCH_JAVA_OPTS=-Xms512m -Xmx512m" + ulimits: + memlock: + soft: -1 + hard: -1 + volumes: + - opensearch-data2:/usr/share/opensearch/data + ports: + - 9201:9200 + - 9700:9600 # required for Performance Analyzer + networks: + - opensearch-net + replication-node2: + image: opensearchproject/opensearch:{{site.opensearch_version}} + container_name: replication-node2 + environment: + - cluster.name=follower-cluster + - discovery.type=single-node + - bootstrap.memory_lock=true + - "OPENSEARCH_JAVA_OPTS=-Xms512m -Xmx512m" + ulimits: + memlock: + soft: -1 + hard: -1 + volumes: + - opensearch-data1:/usr/share/opensearch/data + ports: + - 9200:9200 + - 9600:9600 # required for Performance Analyzer + networks: + - opensearch-net + +volumes: + opensearch-data1: + opensearch-data2: + +networks: + opensearch-net: +``` + +After the clusters start, verify the names of each: + +```bash +curl -XGET -u 'admin:admin' -k 'https://localhost:9201' +{ + "name" : "replication-node1", + "cluster_name" : "leader-cluster", + ... +} + +curl -XGET -u 'admin:admin' -k 'https://localhost:9200' +{ + "name" : "replication-node2", + "cluster_name" : "follower-cluster", + ... +} +``` + +For this example, use port 9201 (`replication-node1`) as the leader and port 9200 (`replication-node2`) as the follower cluster. + +To get the IP address for the leader cluster, first identify its container ID: + +```bash +docker ps +CONTAINER ID IMAGE PORTS NAMES +3b8cdc698be5 opensearchproject/opensearch:{{site.opensearch_version}} 0.0.0.0:9200->9200/tcp, 0.0.0.0:9600->9600/tcp, 9300/tcp replication-node1 +731f5e8b0f4b opensearchproject/opensearch:{{site.opensearch_version}} 9300/tcp, 0.0.0.0:9201->9200/tcp, 0.0.0.0:9700->9600/tcp replication-node2 +``` + +Then get that container's IP address: + +```bash +docker inspect --format='{% raw %}{{range .NetworkSettings.Networks}}{{.IPAddress}}{{end}}{% endraw %}' 731f5e8b0f4b +172.22.0.3 +``` + +## Set up a cross-cluster connection + +On the follower cluster, add the leader cluster name and the IP address (with port 9300) for each seed node. In this case, you only have one seed node: + +```bash +curl -XPUT -k -H 'Content-Type: application/json' -u 'admin:admin' 'https://localhost:9200/_cluster/settings?pretty' -d ' +{ + "persistent": { + "cluster": { + "remote": { + "leader-cluster": { + "seeds": ["172.22.0.3:9300"] + } + } + } + } +}' +``` + +## Start replication + +To get started, create an index called `leader-01` on the remote (leader) cluster: + +```bash +curl -XPUT -k -H 'Content-Type: application/json' -u 'admin:admin' 'https://localhost:9201/leader-01?pretty' +``` + +Start replication of that index from the follower cluster. Starting replication creates the provided follower index from scratch; you can't convert an existing index to a follower index. + +Provide the leader cluster and index that you want to replicate: + +```bash +curl -XPUT -k -H 'Content-Type: application/json' -u 'admin:admin' 'https://localhost:9200/_plugins/_replication/follower-01/_start?pretty' -d ' +{ + "leader_alias": "leader-cluster", + "leader_index": "leader-01", + "use_roles":{ + "leader_cluster_role": "all_access", + "follower_cluster_role": "all_access" + } +}' +``` + +If the security plugin is disabled, you can leave out the `use_roles` parameter. If it's enabled, however, you need to specify the leader and follower cluster roles that OpenSearch will use to authenticate the request. This example uses `all_access` for simplicity, but we recommend creating a replication user on each cluster and [mapping it accordingly]({{site.url}}{{site.baseurl}}/replication-plugin/permissions/#map-the-leader-and-follower-cluster-roles). +{: .tip } + +This command creates an identical read-only index named "follower-01" on the local cluster that continuously stays updated with changes to the "leader-01" index on the remote cluster. + +After replication starts, get the status: + +```bash +curl -XGET -k -u 'admin:admin' 'https://localhost:9200/_plugins/_replication/follower-01/_status?pretty' + +{ + "status" : "SYNCING", + "reason" : "User initiated", + "leader_alias" : "leader-cluster", + "leader_index" : "leader-01", + "follower_index" : "follower-01", + "syncing_details" : { + "leader_checkpoint" : -1, + "follower_checkpoint" : -1, + "seq_no" : 0 + } +} +``` + +## Confirm replication + +To confirm that replication is actually happening, add a document to the leader index: + +```bash +curl -XPUT -k -H 'Content-Type: application/json' -u 'admin:admin' 'https://localhost:9201/leader-01/_doc/1?pretty' -d '{"The Shining": "Stephen King"}' +``` + +Then validate the replicated content on the follower index: + +```bash +curl -XGET -k -u 'admin:admin' 'https://localhost:9200/follower-01/_search?pretty' + +{ + ... + "hits": [{ + "_index": "follower-01", + "_type": "_doc", + "_id": "1", + "_score": 1.0, + "_source": { + "The Shining": "Stephen King" + } + }] +} +``` + +## Pause and resume replication + +You can temporarily pause replication of an index if you need to remediate issues or reduce load on the leader cluster: + +```bash +curl -XPOST -k -H 'Content-Type: application/json' -u 'admin:admin' 'https://localhost:9200/_plugins/_replication/follower-01/_pause?pretty' -d '{}' +``` + +To confirm replication is paused, get the status: + +```bash +curl -XGET -k -u 'admin:admin' 'https://localhost:9200/_plugins/_replication/follower-01/_status?pretty' + +{ + "status" : "PAUSED", + "reason" : "User initiated", + "leader_alias" : "leader-cluster", + "leader_index" : "leader-01", + "follower_index" : "follower-01" +} +``` + +When you're done making changes, resume replication: + +```bash +curl -XPOST -k -H 'Content-Type: application/json' -u 'admin:admin' 'https://localhost:9200/_plugins/_replication/follower-01/_resume?pretty' -d '{}' +``` + +When replication resumes, the follower index picks up any changes that were made to the leader index while replication was paused. + +If you don't resume replication within 12 hours, replication stops completely and the follower index is converted to a standard index. + +## Stop replication + +Terminate replication of a specified index from the follower cluster: + +```bash +curl -XPOST -k -H 'Content-Type: application/json' -u 'admin:admin' 'https://localhost:9200/_plugins/_replication/follower-01/_stop' -d '{}' +``` + +When you stop replication, the follower index un-follows the leader and becomes a standard index that you can write to. You can't restart replication after it's been terminated. + +Get the status to confirm that the index is no longer being replicated: + +```bash +curl -XGET -k -u 'admin:admin' 'https://localhost:9200/_plugins/_replication/follower-01/_status?pretty' + +{ + "status" : "REPLICATION NOT IN PROGRESS" +} +``` + +You can further confirm that replication is stopped by making modifications to the leader index and confirming they don't show up on the follower index. + + diff --git a/_replication-plugin/index.md b/_replication-plugin/index.md new file mode 100644 index 00000000..1b9414f2 --- /dev/null +++ b/_replication-plugin/index.md @@ -0,0 +1,19 @@ +--- +layout: default +title: Cross-cluster replication +nav_order: 1 +has_children: false + +--- + +# Cross-cluster replication + +The cross-cluster replication plugin lets you replicate indices, mappings, and metadata from one OpenSearch cluster to another. It follows an active-passive replication model where the follower index (where the data is replicated) pulls data from the leader (source) index. + +The replication plugin supports replication of indices using wildcard pattern matching and provides commands to pause, resume, and stop replication. Once replication starts on an index, it initiates a persistent background task on the primary shard of the follower cluster that continuously polls corresponding shards from the leader cluster for updates. + +The replication plugin integrates with the security plugin so you can encrypt cross-cluster traffic with node-to-node encryption and control access to replication activities. + +To start, see [Get started with cross-cluster replication]({{site.url}}{{site.baseurl}}/replication-plugin/get-started/). + + diff --git a/_replication-plugin/permissions.md b/_replication-plugin/permissions.md new file mode 100644 index 00000000..6b3804ad --- /dev/null +++ b/_replication-plugin/permissions.md @@ -0,0 +1,78 @@ +--- +layout: default +title: Permissions +nav_order: 30 +--- + +# Cross-cluster replication permissions + +You can use the [security plugin]({{site.url}}{{site.baseurl}}/security-plugin/index/) with cross-cluster replication to limit users to certain actions. For example, you might want certain users to only perform replication activity on the leader or follower cluster. + +Because cross-cluster replication involves multiple clusters, it's possible that clusters might have different security configurations. The following configurations are supported: + +- Security plugin fully enabled on both clusters +- Security plugin enabled only for TLS on both clusters (`plugins.security.ssl_only`) +- Security plugin absent or disabled on both clusters (not recommended) + +You can enable node-to-node encryption on both the leader and the follower cluster to ensure that replication traffic between the clusters is encrypted. + +## Basic permissions + +In order for non-admin users to perform replication activities, they need to be mapped to the appropriate permissions. + +The security plugin has two built-in roles that cover most replication use cases: `cross_cluster_replication_leader_full_access` which provides replication permissions on the leader cluster, and `cross_cluster_replication_follower_full_access` which provides replication permissions on the follower cluster. For descriptions of each, see [Predefined roles]({{site.url}}{{site.baseurl}}/security-plugin/access-control/users-roles#predefined-roles). + +If you don't want to use the default roles, you can combine individual replication [permissions]({{site.url}}{{site.baseurl}}/replication-plugin/permissions/#replication-permissions) to meet your needs. Most permissions correspond to specific REST API operations. For example, the `indices:admin/plugins/replication/index/pause` permission lets you pause replication. + +## Map the leader and follower cluster roles + +The [start replication]({{site.url}}{{site.baseurl}}/replication-plugin/api/#start-replication) and [create replication rule]({{site.url}}{{site.baseurl}}/replication-plugin/api/#start-replication) are special cases because they involve background processes that require permissions on both the leader and the follower cluster. Therefore, when you perform one of these actions, you need to explicitly pass the `leader_cluster_role` and +`follower_cluster_role` in the request, which OpenSearch will then use in all backend replication tasks. + +To enable non-admins to start replication and create replication rules, create an identical user on each cluster (for example, `replication_user`) and map them to the `cross_cluster_replication_leader_full_access` role on the remote cluster and `cross_cluster_replication_follower_full_access` on the follower cluster. For instructions, see [Map users to roles]({{site.url}}{{site.baseurl}}/access-control/users-roles/#map-users-to-roles). + +You can then pass those roles into the request along with the appropriate credentials: + +```bash +curl -XPUT -k -H 'Content-Type: application/json' -u 'replication_user:password' 'https://localhost:9200/_plugins/_replication/follower-01/_start?pretty' -d ' +{ + "leader_alias": "leader-cluster", + "leader_index": "leader-01", + "use_roles":{ + "leader_cluster_role": "cross_cluster_replication_leader_full_access", + "follower_cluster_role": "cross_cluster_replication_follower_full_access" + } +}' +``` + +You can instead choose to create your own leader and follower cluster roles to meet your needs, but we recommend using the default roles. + +## Replication permissions + +The following sections list the available index and cluster-level permissions for cross-cluster replication. + +### Follower cluster + +Users can have the following permissions for the follower cluster: + +``` +indices:admin/plugins/replication/index/setup/validate +indices:admin/plugins/replication/index/start +indices:admin/plugins/replication/index/pause +indices:admin/plugins/replication/index/resume +indices:admin/plugins/replication/index/stop +indices:admin/plugins/replication/index/update +indices:admin/plugins/replication/index/status_check +indices:data/write/plugins/replication/changes +cluster:admin/plugins/replication/autofollow/update +``` + +### Leader cluster + +Users can have the following permissions for the leader cluster: + +``` +indices:admin/plugins/replication/validate +indices:data/read/plugins/replication/file_chunk +indices:data/read/plugins/replication/changes +``` diff --git a/_replication-plugin/settings.md b/_replication-plugin/settings.md new file mode 100644 index 00000000..66d16ec4 --- /dev/null +++ b/_replication-plugin/settings.md @@ -0,0 +1,32 @@ +--- +layout: default +title: Settings +nav_order: 40 +--- + +# Replication settings + +The replication 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 +{ + "persistent": { + "plugins.replication.indices.recovery.parallel_chunks": "8" + } +} +``` + +These settings manage the resources consumed by remote recoveries. We don’t recommend changing these settings; the defaults should work well for most use cases. + +Setting | Default | Description +:--- | :--- | :--- +`plugins.replication.indices.recovery.chunk_size` | 1MB | The chunk size requested by the follower cluster during file transfer. Specify the chunk size as a value and unit, for example, 10MB, 5KB. +`plugins.replication.indices.recovery.parallel_chunks` | 5 | The number of file chunk requests that can be sent in parallel for each recovery. +`plugins.replication.indices.recovery.request_timeout` | 60s | The amount of time to wait for individual network requests during the remote recovery process. A single action timeout can cause recovery to fail. +`plugins.replication.indices.recovery.activity_timeout` | 5m | The amount of time to wait for recovery activity. If the leader cluster doesn't receive recovery requests from the follower for this amount of time, it closes the in-memory resources needed to supply data to the follower during recovery. + diff --git a/_security-plugin/access-control/permissions.md b/_security-plugin/access-control/permissions.md index 192e8a7b..44db6825 100644 --- a/_security-plugin/access-control/permissions.md +++ b/_security-plugin/access-control/permissions.md @@ -59,6 +59,7 @@ Rather than creating new action groups from individual permissions, you can ofte - cluster:admin/opensearch/reports/instance/get - cluster:admin/opensearch/reports/instance/list - cluster:admin/opensearch/reports/menu/download +- cluster:admin/plugins/replication/autofollow/update - cluster:admin/reindex/rethrottle - cluster:admin/repository/delete - cluster:admin/repository/get @@ -114,6 +115,13 @@ Rather than creating new action groups from individual permissions, you can ofte - indices:admin/mappings/fields/get* - indices:admin/mappings/get - indices:admin/open +- indices:admin/plugins/replication/index/setup/validate +- indices:admin/plugins/replication/index/start +- indices:admin/plugins/replication/index/pause +- indices:admin/plugins/replication/index/resume +- indices:admin/plugins/replication/index/stop +- indices:admin/plugins/replication/index/update +- indices:admin/plugins/replication/index/status_check - indices:admin/refresh - indices:admin/refresh* - indices:admin/resolve/index @@ -139,6 +147,8 @@ Rather than creating new action groups from individual permissions, you can ofte - indices:data/read/msearch/template - indices:data/read/mtv - indices:data/read/mtv* +- indices:data/read/plugins/replication/file_chunk +- indices:data/read/plugins/replication/changes - indices:data/read/scroll - indices:data/read/scroll/clear - indices:data/read/search @@ -150,6 +160,7 @@ Rather than creating new action groups from individual permissions, you can ofte - indices:data/write/delete - indices:data/write/delete/byquery - indices:data/write/index +- indices:data/write/plugins/replication/changes - indices:data/write/reindex - indices:data/write/update - indices:data/write/update/byquery diff --git a/_security-plugin/access-control/users-roles.md b/_security-plugin/access-control/users-roles.md index 445e1e63..b69cae4c 100644 --- a/_security-plugin/access-control/users-roles.md +++ b/_security-plugin/access-control/users-roles.md @@ -109,6 +109,8 @@ Role | Description `anomaly_full_access` | Grants full permissions to all anomaly detection actions. `anomaly_read_access` | Grants permissions to view detectors, but not create, modify, or delete detectors. `all_access` | Grants full access to the cluster: all cluster-wide operations, write to all indices, write to all tenants. +`cross_cluster_replication_follower_full_access` | Grants full access to perform cross-cluster replication actions on the follower cluster. +`cross_cluster_replication_leader_full_access` | Grants full access to perform cross-cluster replication actions on the leader cluster. `kibana_read_only` | A special role that prevents users from making changes to visualizations, dashboards, and other OpenSearch Dashboards objects. See `plugins.security.readonly_mode.roles` in `opensearch_dashboards.yml`. Pair with the `kibana_user` role. `kibana_user` | Grants permissions to use OpenSearch Dashboards: cluster-wide searches, index monitoring, and write to various OpenSearch Dashboards indices. `logstash` | Grants permissions for Logstash to interact with the cluster: cluster-wide searches, cluster monitoring, and write to the various Logstash indices. From 8d3ae42f6af39169afb4c400bdb1b795587bed50 Mon Sep 17 00:00:00 2001 From: Liz Snyder Date: Thu, 30 Sep 2021 16:43:05 -0700 Subject: [PATCH 094/167] Typo --- _replication-plugin/get-started.md | 4 ++-- _replication-plugin/index.md | 2 +- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/_replication-plugin/get-started.md b/_replication-plugin/get-started.md index 00576fa4..34e2899a 100644 --- a/_replication-plugin/get-started.md +++ b/_replication-plugin/get-started.md @@ -6,7 +6,7 @@ nav_order: 10 # Get started with cross-cluster replication -With cross-cluster replication, you index data to a leader index and that data is replicated to one or more read-only follower indices. All subsequnt operations on the leader are replicated on the follower, such as creating, updating, or deleting documents. +With cross-cluster replication, you index data to a leader index and that data is replicated to one or more read-only follower indices. All subsequent operations on the leader are replicated on the follower, such as creating, updating, or deleting documents. ## Prerequisites @@ -147,7 +147,7 @@ To get started, create an index called `leader-01` on the remote (leader) cluste curl -XPUT -k -H 'Content-Type: application/json' -u 'admin:admin' 'https://localhost:9201/leader-01?pretty' ``` -Start replication of that index from the follower cluster. Starting replication creates the provided follower index from scratch; you can't convert an existing index to a follower index. +Start replication of that index from the follower cluster. Starting replication creates a follower index from scratch; you can't convert an existing index to a follower index. Provide the leader cluster and index that you want to replicate: diff --git a/_replication-plugin/index.md b/_replication-plugin/index.md index 1b9414f2..07ba256f 100644 --- a/_replication-plugin/index.md +++ b/_replication-plugin/index.md @@ -10,7 +10,7 @@ has_children: false The cross-cluster replication plugin lets you replicate indices, mappings, and metadata from one OpenSearch cluster to another. It follows an active-passive replication model where the follower index (where the data is replicated) pulls data from the leader (source) index. -The replication plugin supports replication of indices using wildcard pattern matching and provides commands to pause, resume, and stop replication. Once replication starts on an index, it initiates a persistent background task on the primary shard of the follower cluster that continuously polls corresponding shards from the leader cluster for updates. +The replication plugin supports replication of indices using wildcard pattern matching and provides commands to pause, resume, and stop replication. Once replication starts on an index, it initiates a persistent background task on the primary shard on the follower cluster that continuously polls corresponding shards from the leader cluster for updates. The replication plugin integrates with the security plugin so you can encrypt cross-cluster traffic with node-to-node encryption and control access to replication activities. From 25c4b70046dcd5016454678e3757390f3229e4d5 Mon Sep 17 00:00:00 2001 From: aetter Date: Thu, 30 Sep 2021 19:58:37 -0700 Subject: [PATCH 095/167] Adds plugin list and ARM tarball --- _dashboards/install/plugins.md | 15 +++++++++++++++ _dashboards/install/tar.md | 7 +++---- 2 files changed, 18 insertions(+), 4 deletions(-) diff --git a/_dashboards/install/plugins.md b/_dashboards/install/plugins.md index 06b3c4c9..e0fc9d29 100644 --- a/_dashboards/install/plugins.md +++ b/_dashboards/install/plugins.md @@ -28,6 +28,21 @@ If you don't want to use the all-in-one installation options, you can install th + + 1.1.0 + +
alertingDashboards          1.1.0.0
+anomalyDetectionDashboards  1.1.0.0
+ganttChartDashboards        1.1.0.0
+indexManagementDashboards   1.1.0.0
+notebooksDashboards         1.1.0.0
+queryWorkbenchDashboards    1.1.0.0
+reportsDashboards           1.1.0.0
+securityDashboards          1.1.0.0
+traceAnalyticsDashboards    1.1.0.0
+
+ + 1.0.1 diff --git a/_dashboards/install/tar.md b/_dashboards/install/tar.md index 1c7e6933..026f23f7 100644 --- a/_dashboards/install/tar.md +++ b/_dashboards/install/tar.md @@ -14,9 +14,10 @@ nav_order: 30 ```bash # x64 tar -zxf opensearch-dashboards-{{site.opensearch_version}}-linux-x64.tar.gz - cd opensearch-dashboards{% comment %}# ARM64 + cd opensearch-dashboards + # ARM64 tar -zxf opensearch-dashboards-{{site.opensearch_version}}-linux-arm64.tar.gz - cd opensearch-dashboards{% endcomment %} + cd opensearch-dashboards ``` 1. If desired, modify `config/opensearch_dashboards.yml`. @@ -26,5 +27,3 @@ nav_order: 30 ```bash ./bin/opensearch-dashboards ``` - -1. See the [OpenSearch Dashboards documentation]({{site.url}}{{site.baseurl}}/dashboards/index/). From 0686ae05b57bd6409289cba469eae58f42e2343f Mon Sep 17 00:00:00 2001 From: ashwinkumar12345 Date: Fri, 1 Oct 2021 01:21:16 -0700 Subject: [PATCH 096/167] Added upgrade tool docs --- _upgrade-to/upgrade-to.md | 94 +++++++++++++++++++++++++++++++++++++++ 1 file changed, 94 insertions(+) diff --git a/_upgrade-to/upgrade-to.md b/_upgrade-to/upgrade-to.md index a415b621..e852fa1c 100644 --- a/_upgrade-to/upgrade-to.md +++ b/_upgrade-to/upgrade-to.md @@ -179,3 +179,97 @@ If you are upgrading an Open Distro for Elasticsearch cluster, we recommend firs } } ``` + +## Upgrade tool + +The `opensearch-upgrade` tool lets you automate some of the steps in [Upgrade to OpenSearch]({{site.url}}{{site.baseurl}}/upgrade-to/upgrade-to/#upgrade-to-opensearch), eliminating the need for error-prone manual operations. + +The `opensearch-upgrade` tool performs the following functions: + +- Imports any existing configurations and applies it to the new installation of OpenSearch. +- Installs any existing core plugins. + +### Limitations + +The `opensearch-upgrade` tool doesn't perform an end-to-end upgrade: + +- You need to run the tool on each node of the cluster individually as part of the upgrade process. +- The tool doesn't provide a rollback option after you've upgraded a node, so make sure you follow best practices and take backups. +- You must install all community plugins (if available) manually. +- The tool only validates any keystore settings at service start-up time, so you must manually remove any unsupported settings for the service to start. + +### Using the upgrade tool + +To perform a rolling upgrade using the [OpenSearch tarball]({{site.url}}{{site.baseurl}}/opensearch/install/tar/) distribution: + +Check [Upgrade paths]({{site.url}}{{site.baseurl}}/upgrade-to/upgrade-to/#upgrade-paths) to make sure that the version you’re upgrading to is supported and whether you need to upgrade to a supported Elasticsearch OSS version first. +{: .note } + +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. On any one of the nodes, download and extract the OpenSearch tarball to a new directory. + +1. Make sure the following environment variables are set: + + - `ES_HOME` - Path to the existing Elasticsearch installation home. + - `ES_PATH_CONF` - Path to the existing Elasticsearch config directory. + - `OPENSEARCH_HOME` - Path to the OpenSearch installation home. + - `OPENSEARCH_PATH_CONF` - Path to the OpenSearch config directory. + +1. The `opensearch-upgrade` tool is in the `bin` directory of the distribution. Run the following command from the distribution home: + + Make sure you run this tool as the same user running the current Elasticsearch service. + {: .note } + + ```json + ./bin/opensearch-upgrade + ``` + +1. Stop Elasticsearch OSS on the node. + + 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 `). + +1. Start OpenSearch on the node: + + ```json + ./bin/opensearch -d. + ``` + +1. Repeat steps 2--6 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" + } + } + ``` + +### How it works + +Behind the scenes, the `opensearch-upgrade` tool performs the following tasks in sequence: + +1. Looks for a valid Elasticsearch installation on the current node. After it finds the installation, it reads the `elasticsearch.yml` file to get the endpoint details and connects to the locally running Elasticsearch service. If the tool can't find an Elasticsearch installation, it tries to get the path from the `ES_HOME` location. +1. Verifies if the existing version of Elasticsearch is compatible with the OpenSearch version. It prints a summary of the information gathered to the console and prompts you for a confirmation to proceed. +1. Imports the settings from the `elasticsearch.yml` config file into the `opensearch.yml` config file. +1. Copies across any custom JVM options from the `$ES_PATH_CONF/jvm.options.d` directory into the `$OPENSEARCH_PATH_CONF/jvm.options.d` directory . Similarly, it also imports the logging configurations from the `$ES_PATH_CONF/log4j2.properties` file into the `$OPENSEARCH_PATH_CONF/log4j2.properties` file. +1. Installs the core plugins that you’ve currently installed in the `$ES_HOME/plugins` directory. You must install all other third-party community plugins manually. +1. Imports the secure settings from the `elasticsearch.keystore` file (if any) into the `opensearch.keystore` file. If the keystore file is password protected, the `opensearch-upgrade` tool prompts you to enter the password. From 1f90f3ca523f57893ed30dac31db21cf5319ef4c Mon Sep 17 00:00:00 2001 From: aetter Date: Fri, 1 Oct 2021 09:46:47 -0700 Subject: [PATCH 097/167] Update Helm links --- _dashboards/install/helm.md | 2 +- _opensearch/install/helm.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/_dashboards/install/helm.md b/_dashboards/install/helm.md index 25936f1d..4d2e0c83 100644 --- a/_dashboards/install/helm.md +++ b/_dashboards/install/helm.md @@ -20,7 +20,7 @@ Resource | Description The specification in the default Helm chart supports many standard use cases and setups. You can modify the default chart to configure your desired specifications and set Transport Layer Security (TLS) and role-based access control (RBAC). For information about the default configuration, steps to configure security, and configurable parameters, see the -[README](https://github.com/opensearch-project/opensearch-devops/blob/main/Helm/README.md). +[README](https://github.com/opensearch-project/helm-charts/tree/main/charts). The instructions here assume you have a Kubernetes cluster with Helm preinstalled. See the [Kubernetes documentation](https://kubernetes.io/docs/setup/) for steps to configure a Kubernetes cluster and the [Helm documentation](https://helm.sh/docs/intro/install/) to install Helm. {: .note } diff --git a/_opensearch/install/helm.md b/_opensearch/install/helm.md index 55458626..33899cb0 100644 --- a/_opensearch/install/helm.md +++ b/_opensearch/install/helm.md @@ -20,7 +20,7 @@ Resource | Description The specification in the default Helm chart supports many standard use cases and setups. You can modify the default chart to configure your desired specifications and set Transport Layer Security (TLS) and role-based access control (RBAC). For information about the default configuration, steps to configure security, and configurable parameters, see the -[README](https://github.com/opensearch-project/opensearch-devops/blob/main/Helm/README.md). +[README](https://github.com/opensearch-project/helm-charts/tree/main/charts). The instructions here assume you have a Kubernetes cluster with Helm preinstalled. See the [Kubernetes documentation](https://kubernetes.io/docs/setup/) for steps to configure a Kubernetes cluster and the [Helm documentation](https://helm.sh/docs/intro/install/) to install Helm. {: .note } From 1fdf8b95179c8068b5c63fb4c5aa25d287d3b5e4 Mon Sep 17 00:00:00 2001 From: ashwinkumar12345 Date: Fri, 1 Oct 2021 11:22:47 -0700 Subject: [PATCH 098/167] ad 1.1 --- _monitoring-plugins/ad/api.md | 126 ++++++++++++++++---------------- _monitoring-plugins/ad/index.md | 83 ++++++++++----------- 2 files changed, 101 insertions(+), 108 deletions(-) diff --git a/_monitoring-plugins/ad/api.md b/_monitoring-plugins/ad/api.md index a46420a9..e78c9723 100644 --- a/_monitoring-plugins/ad/api.md +++ b/_monitoring-plugins/ad/api.md @@ -240,56 +240,6 @@ POST _plugins/_anomaly_detection/detectors } ``` -To create a historical detector: - -#### Request - -```json -POST _plugins/_anomaly_detection/detectors -{ - "name": "test1", - "description": "test historical detector", - "time_field": "timestamp", - "indices": [ - "host-cloudwatch" - ], - "filter_query": { - "match_all": { - "boost": 1 - } - }, - "detection_interval": { - "period": { - "interval": 1, - "unit": "Minutes" - } - }, - "window_delay": { - "period": { - "interval": 1, - "unit": "Minutes" - } - }, - "feature_attributes": [ - { - "feature_name": "F1", - "feature_enabled": true, - "aggregation_query": { - "f_1": { - "sum": { - "field": "value" - } - } - } - } - ], - "detection_date_range": { - "start_time": 1577840401000, - "end_time": 1606121925000 - } -} -``` - You can specify the following options. Options | Description | Type | Required @@ -303,7 +253,6 @@ Options | Description | Type | Required `detection_interval` | The time interval for your anomaly detector. | `object` | Yes `window_delay` | Add extra processing time for data collection. | `object` | No `category_field` | Categorizes or slices data with a dimension. Similar to `GROUP BY` in SQL. | `list` | No -`detection_date_range` | Specify the start time and end time for a historical detector. | `object` | No --- @@ -316,10 +265,44 @@ Passes a date range to the anomaly detector to return any anomalies within that #### Request ```json -POST _plugins/_anomaly_detection/detectors//_preview +POST _plugins/_anomaly_detection/detectors/_preview + { - "period_start": 1588838250000, - "period_end": 1589443050000 + "period_start": 1612982516000, + "period_end": 1614278539000, + "detector": { + "name": "test-detector", + "description": "test nab_art_daily_jumpsdown", + "time_field": "timestamp", + "indices": [ + "nab_art_daily_jumpsdown" + ], + "detection_interval": { + "period": { + "interval": 1, + "unit": "Minutes" + } + }, + "window_delay": { + "period": { + "interval": 1, + "unit": "Minutes" + } + }, + "feature_attributes": [ + { + "feature_name": "F1", + "feature_enabled": true, + "aggregation_query": { + "f_1": { + "sum": { + "field": "value" + } + } + } + } + ] + } } ``` @@ -446,6 +429,17 @@ If you specify a category field, each result is associated with an entity: ``` +Or, you can specify the detector ID: + +```json +POST _plugins/_anomaly_detection/detectors/_preview +{ + "detector_id": "sYkUvHcBiZv51f-Lv8QN", + "period_start": 1612982516000, + "period_end": 1614278539000 +} +``` + --- ## Start detector job @@ -472,6 +466,15 @@ POST _plugins/_anomaly_detection/detectors//_start } ``` +To start historical analysis: + +```json +POST _plugins/_anomaly_detection/detectors//_start +{ + "start_time": 1503168590000, + "end_time": 1617301324000 +} +``` --- @@ -493,6 +496,12 @@ POST _plugins/_anomaly_detection/detectors//_stop Stopped detector: m4ccEnIBTXsGi3mvMt9p ``` +To stop historical analysis: + +```jsom +POST _plugins/_anomaly_detection/detectors//_stop?historical=true +``` + --- ## Search detector result @@ -786,15 +795,6 @@ POST _plugins/_anomaly_detection/detectors/results/_search } ``` -In historical detectors, specify the `detector_id`. -To get the latest task: - -#### Request - -```json -GET _plugins/_anomaly_detection/detectors/?task=true -``` - To query the anomaly results with `task_id`: #### Request diff --git a/_monitoring-plugins/ad/index.md b/_monitoring-plugins/ad/index.md index 5cb67b7a..cdd8fc89 100644 --- a/_monitoring-plugins/ad/index.md +++ b/_monitoring-plugins/ad/index.md @@ -17,24 +17,22 @@ Anomaly detection automatically detects anomalies in your OpenSearch data in ne 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. -To use the anomaly detection plugin, your computer needs to have more than one CPU core. -{: .note } - ## Get started with Anomaly Detection To get started, choose **Anomaly Detection** in OpenSearch Dashboards. -To first test with sample streaming data, choose **Sample Detectors** and try out one of the preconfigured detectors. +To first test with sample streaming data, you can try out one of the preconfigured detectors with one of the sample datasets. -### Step 1: Create a detector +### Step 1: Define a detector -A detector is an individual anomaly detection task. You can create multiple detectors, and all the detectors can run simultaneously, with each analyzing data from different sources. +A detector is an individual anomaly detection task. You can define multiple detectors, and all the detectors can run simultaneously, with each analyzing data from different sources. 1. Choose **Create Detector**. 1. Enter a name and brief description. Make sure the name is unique and descriptive enough to help you to identify the purpose of the detector. 1. For **Data source**, choose the index you want to use as the data source. You can optionally use index patterns to choose multiple indices. +1. (Optional) For **Data filter**, filter the index you chose as the data source. From the **Data filter** menu, design your filter query by selecting **Field**, **Operator**, and **Value**, or choose **Use query DSL** and add your own JSON filter query. 1. Select the **Timestamp field** in your index. 1. (Optional) For **Data filter**, filter the index you chose as the data source. From the **Filter type** menu, choose **Visual filter**, and then design your filter query by selecting **Fields**, **Operator**, and **Value**, or choose **Custom Expression** and add your own JSON filter query. -1. For **Detector operation settings**, define the **Detector interval**, which is the time interval at which the detector collects data. +1. For **Operation settings**, define the **Detector interval**, which is the time interval at which the detector collects data. - The detector aggregates the data in this interval, then feeds the aggregated result into the anomaly detection model. The shorter you set this interval, the fewer data points the detector aggregates. The anomaly detection model uses a shingling process, a technique that uses consecutive data points to create a sample for the model. This process needs a certain number of aggregated data points from contiguous intervals. @@ -44,9 +42,9 @@ Set the window delay to shift the detector interval to account for this delay. - For example, say the detector interval is 10 minutes and data is ingested into your cluster with a general delay of 1 minute. Assume the detector runs at 2:00. The detector attempts to get the last 10 minutes of data from 1:50 to 2:00, but because of the 1-minute delay, it only gets 9 minutes of data and misses the data from 1:59 to 2:00. Setting the window delay to 1 minute shifts the interval window to 1:49 - 1:59, so the detector accounts for all 10 minutes of the detector interval time. -1. Choose **Create**. +1. Choose **Next**. -After you create the detector, the next step is to add features to it. +After you define the detector, the next step is to configure the model. ### Step 2: Add features to your detector @@ -54,24 +52,25 @@ 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. 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. {: .note } -1. On the **Model configuration** page, enter the **Feature name**. -1. For **Find anomalies based on**, choose the method to find anomalies. For **Field Value** menu, choose the **field** and the **aggregation method**. Or choose **Custom expression**, and add your own JSON aggregation query. +1. On the **Configure Model** page, enter the **Feature name** and check **Enabled feature name**. +1. For **Find anomalies based on**, choose the method to find anomalies. For **Field Value**, choose the **aggregation method**. Or choose **Custom expression**, and add your own JSON aggregation query. +1. Select a field. -#### (Optional) Set a category field for high cardinality +#### (Optional) Set category fields for high cardinality You can categorize anomalies based on a keyword or IP field type. The category field categorizes or slices the source time series with a dimension like IP addresses, product IDs, country codes, and so on. This helps to see a granular view of anomalies within each entity of the category field to isolate and debug issues. -To set a category field, choose **Enable a category field** and select a field. +To set a category field, choose **Enable a category field** and select a field. You can’t change the category fields after you create the detector. Only a certain number of unique entities are supported in the category field. Use the following equation to calculate the recommended total number of entities supported in a cluster: ``` -(data nodes * heap size * anomaly detection maximum memory percentage) / (entity size of a detector) +(data nodes * heap size * anomaly detection maximum memory percentage) / (entity model size of a detector) ``` This formula provides a good starting point, but make sure to test with a representative workload. @@ -79,7 +78,7 @@ This formula provides a good starting point, but make sure to test with a repres For example, for a cluster with 3 data nodes, each with 8G of JVM heap size, a maximum memory percentage of 10% (default), and the entity size of the detector as 1MB: the total number of unique entities supported is (8.096 * 10^9 * 0.1 / 1M ) * 3 = 2429. -#### Set a shingle size +#### (Advanced settings) Set a shingle size Set the number of aggregation intervals from your data stream to consider in a detection window. It’s best to choose this value based on your actual data to see which one leads to the best results for your use case. @@ -92,10 +91,25 @@ For sample previews, the anomaly detection plugin selects a small number of data Examine the sample preview and use it to fine-tune your feature configurations (for example, enable or disable features) to get more accurate results. -1. Choose **Save and start detector**. -1. Choose between automatically starting the detector (recommended) or manually starting the detector at a later time. +1. Choose **Preview sample anomalies**. + - If you don't see any sample anomaly result, check the detector interval and make sure you have more than 400 data points for some entities during the preview date range. +1. Choose **Next**. -### Step 3: Observe the results +### Step 3: Set up detector jobs + +To start a real-time detector to find anomalies in your data in near real-time, check **Start real-time detector automatically (recommended)**. + +Alternatively, if you want to perform historical analysis and find patterns in long historical data windows (weeks or months), check **Run historical analysis detection** and select a date range (at least 128 detection intervals). + +Analyzing historical data helps you get familiar with the anomaly detection plugin. You can also evaluate the performance of a detector with historical data to further fine-tune it. + +We recommend experimenting with historical analysis with different feature sets and checking the precision before moving on to real-time detectors. + +### Step 4: Review and create + +Review your model configuration and select **Create detector**. + +### Step 5: Observe the results 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. @@ -106,7 +120,7 @@ If you see the detector pending in "initialization" for longer than a day, aggre ![Anomaly detection results]({{site.url}}{{site.baseurl}}/images/ad.png) -Analize anomalies with the following visualizations: +Analyze anomalies with the following visualizations: - **Live anomalies** - displays live anomaly results for the last 60 intervals. For example, if the interval is 10, it shows results for the last 600 minutes. The chart refreshes every 30 seconds. - **Anomaly history** - plots the anomaly grade with the corresponding measure of confidence. @@ -135,31 +149,10 @@ To see all the configuration settings for a detector, choose the **Detector conf 1. To make any changes to the detector configuration, or fine tune the time interval to minimize any false positives, go to the **Detector configuration** section and choose **Edit**. - You need to stop the detector to change its configuration. Confirm that you want to stop the detector and proceed. 1. To enable or disable features, in the **Features** section, choose **Edit** and adjust the feature settings as needed. After you make your changes, choose **Save and start detector**. -- Choose between automatically starting the detector (recommended) or manually starting the detector at a later time. -### Step 6: Analyze historical data +### Step 8: Manage your detectors -Analyzing historical data helps you get familiar with the anomaly detection plugin. You can also evaluate the performance of a detector with historical data to further fine-tune it. +To start, stop, or delete a detector, go to the **Detectors** page. -To use a historical detector, you need to specify a date range that has data present in at least 1,000 detection intervals. -{: .note } - -1. Choose **Historical detectors** and **Create historical detector**. -1. Enter the **Name** of the detector and a brief **Description**. -1. For **Data source**, choose the index to use as the data source. You can optionally use index patterns to choose multiple indices. -1. For **Time range**, select a time range for historical analysis. -1. For **Detector settings**, choose to use the settings of an existing detector. Or choose the **Timestamp field** in your index, add individual features to the detector, and set the detector interval. -1. (Optional) Choose to run the historical detector automatically after creating it. -1. Choose **Create**. - - You can stop the historical detector even before it completes. - -### Step 7: Manage your detectors - -To change or delete a detector, go to the **Detector details** page. - -1. To make changes to your detector, choose the detector name. -1. Choose **Actions** and **Edit detector**. - - You need to stop the detector to change its configuration. Confirm that you want to stop the detector and proceed. -1. Make your changes and choose **Save changes**. - -To delete your detector, choose **Actions** and **Delete detector**. In the pop-up box, type `delete` to confirm and choose **Delete**. +1. Choose the detector name. +2. Choose **Actions** and select **Start real-time detectors**, **Stop real-time detectors**, or **Delete detectors**. From dda5e2a53526df8869de69f42f8e71cf85f5399d Mon Sep 17 00:00:00 2001 From: ashwinkumar12345 Date: Fri, 1 Oct 2021 11:26:24 -0700 Subject: [PATCH 099/167] fixed indendation feedback --- _upgrade-to/upgrade-to.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/_upgrade-to/upgrade-to.md b/_upgrade-to/upgrade-to.md index e852fa1c..0d554370 100644 --- a/_upgrade-to/upgrade-to.md +++ b/_upgrade-to/upgrade-to.md @@ -227,12 +227,12 @@ Check [Upgrade paths]({{site.url}}{{site.baseurl}}/upgrade-to/upgrade-to/#upgrad 1. The `opensearch-upgrade` tool is in the `bin` directory of the distribution. Run the following command from the distribution home: - Make sure you run this tool as the same user running the current Elasticsearch service. - {: .note } + Make sure you run this tool as the same user running the current Elasticsearch service. + {: .note } - ```json - ./bin/opensearch-upgrade - ``` + ```json + ./bin/opensearch-upgrade + ``` 1. Stop Elasticsearch OSS on the node. From cdff560cf6323894f560aae3a24f9caa0d8a8ad7 Mon Sep 17 00:00:00 2001 From: Liz Snyder Date: Fri, 1 Oct 2021 11:43:37 -0700 Subject: [PATCH 100/167] Incorporate feedback and random fixes --- _replication-plugin/api.md | 47 ++++++++++++++++-------------- _replication-plugin/auto-follow.md | 4 +-- _replication-plugin/get-started.md | 40 +++++++++++++++---------- _replication-plugin/index.md | 13 +++++---- _replication-plugin/permissions.md | 22 +++++++------- _replication-plugin/settings.md | 14 +++++---- 6 files changed, 79 insertions(+), 61 deletions(-) diff --git a/_replication-plugin/api.md b/_replication-plugin/api.md index a552d1c2..792aaecf 100644 --- a/_replication-plugin/api.md +++ b/_replication-plugin/api.md @@ -16,7 +16,7 @@ Use these replication operations to programmatically manage cross-cluster replic Introduced 1.1 {: .label .label-purple } -Initiate replication of an index from the leader cluster to the follower cluster. Run this operation on the follower cluster. +Initiate replication of an index from the leader cluster to the follower cluster. Send this request to the follower cluster. #### Request @@ -37,7 +37,7 @@ Specify the following options: Options | Description | Type | Required :--- | :--- |:--- |:--- | -`leader_alias` | The name of the leader cluster. | `string` | Yes +`leader_alias` | The name of the leader cluster. This alias is the same as the remote cluster name used to set up a cross-cluster connection. | `string` | Yes `leader_index` | The index on the leader cluster that you want to replicate. | `string` | Yes `use_roles` | The roles to use for all subsequent backend replication tasks between the indices. Specify a `leader_cluster_role` and `follower_cluster_role`. See [Map the leader and follower cluster roles]({{site.url}}{{site.baseurl}}/replication-plugin/permissions/#map-the-leader-and-follower-cluster-roles). | `string` | If security plugin is enabled @@ -53,12 +53,13 @@ Options | Description | Type | Required Introduced 1.1 {: .label .label-purple } -Terminates replication and converts the follower index to a standard index. +Terminates replication and converts the follower index to a standard index. Send this request to the follower cluster. #### Request ```json POST /_plugins/_replication//_stop +{} ``` #### Sample response @@ -73,12 +74,13 @@ POST /_plugins/_replication//_stop Introduced 1.1 {: .label .label-purple } -Pauses replication of the leader index. If you don't resume replication after 12 hours, it stops completely and the follower index is converted to a standard index. +Pauses replication of the leader index. Send this request to the follower cluster. #### Request ```json -PUT /_plugins/_replication//_pause +POST /_plugins/_replication//_pause +{} ``` #### Sample response @@ -93,12 +95,13 @@ PUT /_plugins/_replication//_pause Introduced 1.1 {: .label .label-purple } -Resumes replication of the leader index. +Resumes replication of the leader index. Send this request to the follower cluster. #### Request ```json -PUT /_plugins/_replication//_resume +POST /_plugins/_replication//_resume +{} ``` #### Sample response @@ -113,7 +116,7 @@ PUT /_plugins/_replication//_resume Introduced 1.1 {: .label .label-purple } -Gets the status of index replication. You can use this API to measure replication lag. Run this command from the leader cluster. +Gets the status of index replication. Possible statuses are `SYNCING`, `BOOTSTRAPING`, `PAUSED`, and `REPLICATION NOT IN PROGRESS`. Use the syncing details to measure replication lag. Send this request to the follower cluster. #### Request @@ -125,20 +128,20 @@ GET /_plugins/_replication//_status ```json { - "status":"SYNCING", - "reason":"User initiated", - "remote_cluster":"remote-cluster", - "leader_index":"leader-01", - "follower_index":"follower-01", - "syncing_details":{ - "remote_checkpoint": 19, - "local_checkpoint": 19, - "seq_no": 20 - } + "status" : "SYNCING", + "reason" : "User initiated", + "leader_alias" : "leader-cluster", + "leader_index" : "leader-01", + "follower_index" : "follower-01", + "syncing_details" : { + "leader_checkpoint" : 19, + "follower_checkpoint" : 19, + "seq_no" : 0 + } } ``` -To include shard replication details in the response, add `&verbose=true`. +To include shard replication details in the response, add the `&verbose=true` parameter. ## Update settings Introduced 1.1 @@ -170,9 +173,9 @@ PUT /_plugins/_replication//_update Introduced 1.1 {: .label .label-purple } -Automatically starts replication on indices matching a specified pattern. Newly created indices on the remote cluster that match one of the specified patterns will be automatically configured as follower indices. You can also use this API to update existing auto-follow patterns. +Automatically starts replication on indices matching a specified pattern. If a new index on the leader cluster matches the pattern, OpenSearch automatically creates a follower index and begins replication. You can also use this API to update existing replication rules. -Run this command on the follower cluster. +Send this request to the follower cluster. Make sure to note the names of all auto-follow patterns after you create them. The replication plugin currently does not include an API operation to retrieve a list of existing patterns. {: .tip } @@ -215,7 +218,7 @@ Introduced 1.1 Deletes the specified replication rule. This operation prevents any new indices from being replicated but does not stop existing replication that the rule has already initiated. -Run this command on the follower cluster. +Send this request to the follower cluster. #### Request diff --git a/_replication-plugin/auto-follow.md b/_replication-plugin/auto-follow.md index 2af9551c..2e06761e 100644 --- a/_replication-plugin/auto-follow.md +++ b/_replication-plugin/auto-follow.md @@ -42,7 +42,7 @@ curl -XPOST -k -H 'Content-Type: application/json' -u 'admin:admin' 'https://loc }' ``` -If the security plugin is disabled, you can leave out the `use_roles` parameter. If it's enabled, however, you need to specify the leader and follower cluster roles that OpenSearch will use to authenticate the request. This example uses `all_access` for simplicity, but we recommend creating a replication user on each cluster and [mapping it accordingly]({{site.url}}{{site.baseurl}}/replication-plugin/permissions/#map-the-leader-and-follower-cluster-roles). +If the security plugin is disabled, you can leave out the `use_roles` parameter. If it's enabled, however, you need to specify the leader and follower cluster roles that OpenSearch uses to authenticate requests. This example uses `all_access` for simplicity, but we recommend creating a replication user on each cluster and [mapping it accordingly]({{site.url}}{{site.baseurl}}/replication-plugin/permissions/#map-the-leader-and-follower-cluster-roles). {: .tip } To test the rule, create a matching index on the leader cluster: @@ -64,7 +64,7 @@ yellow open movies-0001 kHOxYYHxRMeszLjTD9rvSQ 1 1 0 ## Delete a replication rule -When you delete a replication rule, OpenSearch stops replicating *new* indices that match the pattern, but replication of existing indices that the rule previously created will continue. If you need to stop existing replication activity, use the [stop replication API operation]({{site.url}}{{site.baseurl}}/replication-plugin/api/#stop-replication). +When you delete a replication rule, OpenSearch stops replicating *new* indices that match the pattern, but existing indices that the rule previously created continue to replicate. If you need to stop existing replication activity, use the [stop replication API operation]({{site.url}}{{site.baseurl}}/replication-plugin/api/#stop-replication). ```bash curl -XDELETE -k -H 'Content-Type: application/json' -u 'admin:admin' 'https://localhost:9200/_plugins/_replication/_autofollow?pretty' -d ' diff --git a/_replication-plugin/get-started.md b/_replication-plugin/get-started.md index 34e2899a..30955b8c 100644 --- a/_replication-plugin/get-started.md +++ b/_replication-plugin/get-started.md @@ -6,13 +6,13 @@ nav_order: 10 # Get started with cross-cluster replication -With cross-cluster replication, you index data to a leader index and that data is replicated to one or more read-only follower indices. All subsequent operations on the leader are replicated on the follower, such as creating, updating, or deleting documents. +With cross-cluster replication, you index data to a leader index, and OpenSearch replicates that data to one or more read-only follower indices. All subsequent operations on the leader are replicated on the follower, such as creating, updating, or deleting documents. ## Prerequisites Cross-cluster replication has the following prerequisites: -- Install the replication plugin on all nodes of both the leader and the follower cluster. -- If you've overridden `node.roles` in opensearch.yml on the remote cluster, make sure it also includes the `remote_cluster_client` role: +- Both the leader and follower cluster must have the replication plugin installed. +- If you've overridden `node.roles` in `opensearch.yml` on the remote cluster, make sure it also includes the `remote_cluster_client` role: ```yaml node.roles: [, remote_cluster_client] @@ -20,11 +20,11 @@ Cross-cluster replication has the following prerequisites: ## Permissions -Make sure the security plugin is either enabled on both clusters or disabled on both clusters. If you disabled the security plugin, you can skip this section. +Make sure the security plugin is either enabled on both clusters or disabled on both clusters. If you disabled the security plugin, you can skip this section. However, we strongly recommend enabling the security plugin in production scenarios. If the security plugin is enabled, non-admin users need to be mapped to the appropriate permissions in order to perform replication actions. For index and cluster-level permissions requirements, see [Cross-cluster replication permissions]({{site.url}}{{site.baseurl}}/replication-plugin/permissions/). -In addition, add the following setting to opensearch.yml on the leader cluster so it allows connections from the follower cluster: +In addition, add the following setting to `opensearch.yml` on the leader cluster so it allows connections from the follower cluster: ```yml plugins.security.nodes_dn_dynamic_config_enabled: true @@ -32,6 +32,9 @@ plugins.security.nodes_dn_dynamic_config_enabled: true ## Example setup +The following example demonstrates how to replicate data between two single-node clusters: `leader-cluster` on port 9201, and `follower-cluster` on port 9200. +{% comment %} + Save this sample file as `docker-compose.yml` and run `docker-compose up` to start two single-node clusters on the same network: ```yml @@ -86,6 +89,8 @@ networks: After the clusters start, verify the names of each: +{% endcomment %} + ```bash curl -XGET -u 'admin:admin' -k 'https://localhost:9201' { @@ -102,6 +107,8 @@ curl -XGET -u 'admin:admin' -k 'https://localhost:9200' } ``` +{% comment %} + For this example, use port 9201 (`replication-node1`) as the leader and port 9200 (`replication-node2`) as the follower cluster. To get the IP address for the leader cluster, first identify its container ID: @@ -119,10 +126,13 @@ Then get that container's IP address: docker inspect --format='{% raw %}{{range .NetworkSettings.Networks}}{{.IPAddress}}{{end}}{% endraw %}' 731f5e8b0f4b 172.22.0.3 ``` +{% endcomment %} ## Set up a cross-cluster connection -On the follower cluster, add the leader cluster name and the IP address (with port 9300) for each seed node. In this case, you only have one seed node: +Cross-cluster replication follows a "pull" model, so most changes occur on the follower cluster, not the leader cluster. + +On the follower cluster, add the leader cluster name and the IP address (with port 9300) for each seed node. Because this is a single-node cluster, you only have one seed node: ```bash curl -XPUT -k -H 'Content-Type: application/json' -u 'admin:admin' 'https://localhost:9200/_cluster/settings?pretty' -d ' @@ -141,15 +151,13 @@ curl -XPUT -k -H 'Content-Type: application/json' -u 'admin:admin' 'https://loca ## Start replication -To get started, create an index called `leader-01` on the remote (leader) cluster: +To get started, create an index called `leader-01` on the leader cluster: ```bash curl -XPUT -k -H 'Content-Type: application/json' -u 'admin:admin' 'https://localhost:9201/leader-01?pretty' ``` -Start replication of that index from the follower cluster. Starting replication creates a follower index from scratch; you can't convert an existing index to a follower index. - -Provide the leader cluster and index that you want to replicate: +Then start replication of that index from the follower cluster. In the request body, provide the leader cluster and index, along with the security roles that you want to use: ```bash curl -XPUT -k -H 'Content-Type: application/json' -u 'admin:admin' 'https://localhost:9200/_plugins/_replication/follower-01/_start?pretty' -d ' @@ -163,10 +171,12 @@ curl -XPUT -k -H 'Content-Type: application/json' -u 'admin:admin' 'https://loca }' ``` -If the security plugin is disabled, you can leave out the `use_roles` parameter. If it's enabled, however, you need to specify the leader and follower cluster roles that OpenSearch will use to authenticate the request. This example uses `all_access` for simplicity, but we recommend creating a replication user on each cluster and [mapping it accordingly]({{site.url}}{{site.baseurl}}/replication-plugin/permissions/#map-the-leader-and-follower-cluster-roles). +If the security plugin is disabled, omit the `use_roles` parameter. If it's enabled, however, you must specify the leader and follower cluster roles that OpenSearch will use to authenticate the request. This example uses `all_access` for simplicity, but we recommend creating a replication user on each cluster and [mapping it accordingly]({{site.url}}{{site.baseurl}}/replication-plugin/permissions/#map-the-leader-and-follower-cluster-roles). {: .tip } -This command creates an identical read-only index named "follower-01" on the local cluster that continuously stays updated with changes to the "leader-01" index on the remote cluster. +This command creates an identical read-only index named `follower-01` on the local cluster that continuously stays updated with changes to the `leader-01` index on the remote cluster. Starting replication creates a follower index from scratch; you can't convert an existing index to a follower index. + +## Confirm replication After replication starts, get the status: @@ -187,7 +197,7 @@ curl -XGET -k -u 'admin:admin' 'https://localhost:9200/_plugins/_replication/fol } ``` -## Confirm replication +Possible statuses are `SYNCING`, `BOOTSTRAPING`, `PAUSED`, and `REPLICATION NOT IN PROGRESS`. The leader and follower checkpoint values increment with each change and illustrate how many updates the follower is behind the leader. If the indices are fully synced, the values are the same. To confirm that replication is actually happening, add a document to the leader index: @@ -244,8 +254,6 @@ curl -XPOST -k -H 'Content-Type: application/json' -u 'admin:admin' 'https://loc When replication resumes, the follower index picks up any changes that were made to the leader index while replication was paused. -If you don't resume replication within 12 hours, replication stops completely and the follower index is converted to a standard index. - ## Stop replication Terminate replication of a specified index from the follower cluster: @@ -254,7 +262,7 @@ Terminate replication of a specified index from the follower cluster: curl -XPOST -k -H 'Content-Type: application/json' -u 'admin:admin' 'https://localhost:9200/_plugins/_replication/follower-01/_stop' -d '{}' ``` -When you stop replication, the follower index un-follows the leader and becomes a standard index that you can write to. You can't restart replication after it's been terminated. +When you stop replication, the follower index un-follows the leader and becomes a standard index that you can write to. You can't restart replication after stopping it. Get the status to confirm that the index is no longer being replicated: diff --git a/_replication-plugin/index.md b/_replication-plugin/index.md index 07ba256f..f3a99d08 100644 --- a/_replication-plugin/index.md +++ b/_replication-plugin/index.md @@ -8,12 +8,15 @@ has_children: false # Cross-cluster replication -The cross-cluster replication plugin lets you replicate indices, mappings, and metadata from one OpenSearch cluster to another. It follows an active-passive replication model where the follower index (where the data is replicated) pulls data from the leader (source) index. +The cross-cluster replication plugin lets you replicate indices, mappings, and metadata from one OpenSearch cluster to another. Cross-cluster replication has the following benefits: +- By replicating your indices, you ensure that you can continue to handle search requests in the event of an outage. +- Replicating data across geographically distant data centers minimizes the distance between the data and the application server, reducing expensive latencies. +- You can replicate data from multiple smaller clusters to a centralized reporting cluster, which is useful when it's inefficient to query across a large network. -The replication plugin supports replication of indices using wildcard pattern matching and provides commands to pause, resume, and stop replication. Once replication starts on an index, it initiates a persistent background task on the primary shard on the follower cluster that continuously polls corresponding shards from the leader cluster for updates. +Replication follows an active-passive model where the follower index (where the data is replicated) pulls data from the leader (remote) index. -The replication plugin integrates with the security plugin so you can encrypt cross-cluster traffic with node-to-node encryption and control access to replication activities. - -To start, see [Get started with cross-cluster replication]({{site.url}}{{site.baseurl}}/replication-plugin/get-started/). +The replication plugin supports replication of indices using wildcard pattern matching and provides commands to pause, resume, and stop replication. Once replication starts on an index, it initiates persistent background tasks on all primary shards on the follower cluster, which continuously poll corresponding shards from the leader cluster for updates. +You can use the replication plugin with the security plugin to encrypt cross-cluster traffic with node-to-node encryption and control access to replication activities. +To start, see [Get started with cross-cluster replication]({{site.url}}{{site.baseurl}}/replication-plugin/get-started/). \ No newline at end of file diff --git a/_replication-plugin/permissions.md b/_replication-plugin/permissions.md index 6b3804ad..2204dba5 100644 --- a/_replication-plugin/permissions.md +++ b/_replication-plugin/permissions.md @@ -14,24 +14,26 @@ Because cross-cluster replication involves multiple clusters, it's possible that - Security plugin enabled only for TLS on both clusters (`plugins.security.ssl_only`) - Security plugin absent or disabled on both clusters (not recommended) -You can enable node-to-node encryption on both the leader and the follower cluster to ensure that replication traffic between the clusters is encrypted. +Enable node-to-node encryption on both the leader and the follower cluster to ensure that replication traffic between the clusters is encrypted. ## Basic permissions -In order for non-admin users to perform replication activities, they need to be mapped to the appropriate permissions. +In order for non-admin users to perform replication activities, they be mapped to the appropriate permissions. -The security plugin has two built-in roles that cover most replication use cases: `cross_cluster_replication_leader_full_access` which provides replication permissions on the leader cluster, and `cross_cluster_replication_follower_full_access` which provides replication permissions on the follower cluster. 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 replication use cases: `cross_cluster_replication_leader_full_access`, which provides replication permissions on the leader cluster, and `cross_cluster_replication_follower_full_access`, which provides replication permissions on the follower cluster. For descriptions of each, see [Predefined roles]({{site.url}}{{site.baseurl}}/security-plugin/access-control/users-roles#predefined-roles). If you don't want to use the default roles, you can combine individual replication [permissions]({{site.url}}{{site.baseurl}}/replication-plugin/permissions/#replication-permissions) to meet your needs. Most permissions correspond to specific REST API operations. For example, the `indices:admin/plugins/replication/index/pause` permission lets you pause replication. ## Map the leader and follower cluster roles -The [start replication]({{site.url}}{{site.baseurl}}/replication-plugin/api/#start-replication) and [create replication rule]({{site.url}}{{site.baseurl}}/replication-plugin/api/#start-replication) are special cases because they involve background processes that require permissions on both the leader and the follower cluster. Therefore, when you perform one of these actions, you need to explicitly pass the `leader_cluster_role` and -`follower_cluster_role` in the request, which OpenSearch will then use in all backend replication tasks. +associates roles passed in the request to these replication jobs to run in the background -To enable non-admins to start replication and create replication rules, create an identical user on each cluster (for example, `replication_user`) and map them to the `cross_cluster_replication_leader_full_access` role on the remote cluster and `cross_cluster_replication_follower_full_access` on the follower cluster. For instructions, see [Map users to roles]({{site.url}}{{site.baseurl}}/access-control/users-roles/#map-users-to-roles). +The [start replication]({{site.url}}{{site.baseurl}}/replication-plugin/api/#start-replication) and [create replication rule]({{site.url}}{{site.baseurl}}/replication-plugin/api/#create-replication-rule) operations are special cases. They involve background processes on the leader and follower clusters that must be associated with roles. When you perform one of these actions, you must explicitly pass the `leader_cluster_role` and +`follower_cluster_role` in the request, which OpenSearch then uses in all backend replication tasks. -You can then pass those roles into the request along with the appropriate credentials: +To enable non-admins to start replication and create replication rules, create an identical user on each cluster (for example, `replication_user`) and map them to the `cross_cluster_replication_leader_full_access` role on the remote cluster and `cross_cluster_replication_follower_full_access` on the follower cluster. For instructions, see [Map users to roles]({{site.url}}{{site.baseurl}}/security-plugin/access-control/users-roles/#map-users-to-roles). + +Then add those roles to the request, and sign it with the appropriate credentials: ```bash curl -XPUT -k -H 'Content-Type: application/json' -u 'replication_user:password' 'https://localhost:9200/_plugins/_replication/follower-01/_start?pretty' -d ' @@ -45,7 +47,7 @@ curl -XPUT -k -H 'Content-Type: application/json' -u 'replication_user:password' }' ``` -You can instead choose to create your own leader and follower cluster roles to meet your needs, but we recommend using the default roles. +You can create your own, custom leader and follower cluster roles using individual permissions, but we recommend using the default roles, which are a good fit for most use cases. ## Replication permissions @@ -53,7 +55,7 @@ The following sections list the available index and cluster-level permissions fo ### Follower cluster -Users can have the following permissions for the follower cluster: +The security plugin supports these permissions for the follower cluster: ``` indices:admin/plugins/replication/index/setup/validate @@ -69,7 +71,7 @@ cluster:admin/plugins/replication/autofollow/update ### Leader cluster -Users can have the following permissions for the leader cluster: +The security plugin supports these permissions for the leader cluster: ``` indices:admin/plugins/replication/validate diff --git a/_replication-plugin/settings.md b/_replication-plugin/settings.md index 66d16ec4..b4815b44 100644 --- a/_replication-plugin/settings.md +++ b/_replication-plugin/settings.md @@ -10,13 +10,13 @@ The replication plugin adds several settings to the standard OpenSearch cluster 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: +For example, to update how often the follower cluster polls the leader cluster for updates: ```json PUT _cluster/settings { "persistent": { - "plugins.replication.indices.recovery.parallel_chunks": "8" + "plugins.replication.follower.metadata_sync_interval": "30s" } } ``` @@ -25,8 +25,10 @@ These settings manage the resources consumed by remote recoveries. We don’t re Setting | Default | Description :--- | :--- | :--- -`plugins.replication.indices.recovery.chunk_size` | 1MB | The chunk size requested by the follower cluster during file transfer. Specify the chunk size as a value and unit, for example, 10MB, 5KB. -`plugins.replication.indices.recovery.parallel_chunks` | 5 | The number of file chunk requests that can be sent in parallel for each recovery. -`plugins.replication.indices.recovery.request_timeout` | 60s | The amount of time to wait for individual network requests during the remote recovery process. A single action timeout can cause recovery to fail. -`plugins.replication.indices.recovery.activity_timeout` | 5m | The amount of time to wait for recovery activity. If the leader cluster doesn't receive recovery requests from the follower for this amount of time, it closes the in-memory resources needed to supply data to the follower during recovery. +`plugins.replication.follower.index.recovery.chunk_size` | 10MB | The chunk size requested by the follower cluster during file transfer. Specify the chunk size as a value and unit, for example, 10MB, 5KB. See [Supported units]({{site.url}}{{site.baseurl}}/opensearch/units/). +`plugins.replication.follower.index.recovery.max_concurrent_file_chunks` | 4 | The number of file chunk requests that can be sent in parallel for each recovery. +`plugins.replication.follower.index.ops_batch_size` | 5000 | The number of operations that can be fetched at a time during the syncing phase of replication. +`plugins.replication.follower.concurrent_readers_per_shard` | 2 | The number of concurrent requests from the follower cluster per shard during the syncing phase of replication. +`plugins.replication.autofollow.fetch_poll_interval` | 30s | How often auto-follow tasks poll the leader cluster for new matching indices. +`plugins.replication.follower.metadata_sync_interval` | 60s | How often the follower cluster polls the leader cluster for updated index metadata. From bfadd04a182e24ebbbefde670703987f5a9b998f Mon Sep 17 00:00:00 2001 From: keithhc2 Date: Fri, 1 Oct 2021 16:41:31 -0700 Subject: [PATCH 101/167] Added a small section for the visual editor --- _im-plugin/ism/index.md | 17 ++++++++++++----- 1 file changed, 12 insertions(+), 5 deletions(-) diff --git a/_im-plugin/ism/index.md b/_im-plugin/ism/index.md index f27e2636..0104dc68 100644 --- a/_im-plugin/ism/index.md +++ b/_im-plugin/ism/index.md @@ -31,14 +31,21 @@ To get started, choose **Index Management** in OpenSearch Dashboards. 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/). +You can use the JSON editor or visual editor to create policies. Compared to the JSON editor, the visual editor offers a more structured way of defining policies by separating the process into creating error notifications, defining ISM templates, and adding states. We recommend using the visual editor if you want to see pre-defined fields such as which actions you can assign to a state or under what conditions a state can transition into a destination state. + +#### JSON editor + 1. Choose the **Index Policies** tab. 2. Choose **Create policy**. -3. In the **Name policy** section, enter a policy ID. -4. In the **Define policy** section, enter your policy. -5. Choose **Create**. +3. Choose **JSON editor**. +4. In the **Name policy** section, enter a policy ID. +5. In the **Define policy** section, enter your policy. +6. Choose **Create**. -After you create a policy, your next step is to attach this policy to an index or indices. -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: +After you create a policy, your next step is to attach it to an index or indices. +You can set up an `ism_template` in the policy so when an index that matches the ISM template pattern is created, the plugin automatically attaches the policy to the index. + +The following example demonstrates how to create a policy that automatically gets attached to all indices whose names start with `index_name-`. ```json PUT _plugins/_ism/policies/policy_id From 57d7ee0aaa40002b9f0a99878530f220144ada30 Mon Sep 17 00:00:00 2001 From: Omurbek Date: Sat, 2 Oct 2021 23:53:48 +0300 Subject: [PATCH 102/167] Added missed "template" settings --- _im-plugin/ism/policies.md | 14 +++++++++++--- 1 file changed, 11 insertions(+), 3 deletions(-) diff --git a/_im-plugin/ism/policies.md b/_im-plugin/ism/policies.md index ec4bf737..afad9396 100644 --- a/_im-plugin/ism/policies.md +++ b/_im-plugin/ism/policies.md @@ -558,9 +558,11 @@ The following sample template policy is for a rollover use case. PUT _index_template/ism_rollover { "index_patterns": ["log*"], - "settings": { - "plugins.index_state_management.rollover_alias": "log" - } + "template": { + "settings": { + "opendistro.index_state_management.rollover_alias": "log" + } + } } ``` @@ -586,6 +588,12 @@ The following sample template policy is for a rollover use case. } ``` +5. Verify if the policy is attached to the `log-000001` index: + + ```json + GET _opendistro/_ism/explain/log-000001?pretty + ``` + ## Example policy The following example policy implements a `hot`, `warm`, and `delete` workflow. You can use this policy as a template to prioritize resources to your indices based on their levels of activity. From 9f74fed5828cd50c945995fc442eb5b593269a91 Mon Sep 17 00:00:00 2001 From: ashwinkumar12345 Date: Sun, 3 Oct 2021 10:35:18 -0700 Subject: [PATCH 103/167] more updates --- _monitoring-plugins/ad/api.md | 2233 +++++++++++++++++++++++++--- _monitoring-plugins/ad/index.md | 19 +- _monitoring-plugins/ad/settings.md | 17 +- 3 files changed, 2049 insertions(+), 220 deletions(-) diff --git a/_monitoring-plugins/ad/api.md b/_monitoring-plugins/ad/api.md index e78c9723..2a8427e3 100644 --- a/_monitoring-plugins/ad/api.md +++ b/_monitoring-plugins/ad/api.md @@ -272,10 +272,10 @@ POST _plugins/_anomaly_detection/detectors/_preview "period_end": 1614278539000, "detector": { "name": "test-detector", - "description": "test nab_art_daily_jumpsdown", + "description": "test server_log", "time_field": "timestamp", "indices": [ - "nab_art_daily_jumpsdown" + "server_log" ], "detection_interval": { "period": { @@ -795,7 +795,7 @@ POST _plugins/_anomaly_detection/detectors/results/_search } ``` -To query the anomaly results with `task_id`: +You can query the anomaly results of a historical detector with the `task_id`: #### Request @@ -885,7 +885,7 @@ GET _plugins/_anomaly_detection/detectors/results/_search "time_field": "timestamp", "last_update_time": 1612126640448, "indices": [ - "nab_art_daily_jumpsdown" + "server_log" ], "window_delay": { "period": { @@ -939,6 +939,192 @@ GET _plugins/_anomaly_detection/detectors/results/_search } ``` +You can specify the following options. + +Options | Description | Type | Required +:--- | :--- |:--- |:--- | +`anomalyThreshold` | Filter out low anomaly grade results. Default is -1. The lowest possible anomaly grade is 0. -1 means that the detector returns all results. | `float` | No +`dateRangeFilter` | Specify the date range in:
- `startTime` (int): Start time to collect results. Recorded in milliseconds since the Unix Epoch.
- `endTime` (int): End time to collect results. Recorded in milliseconds since the Unix Epoch.
- `fieldName` (string): The field that you want to match the start and end time. | `object` | Yes +`entity` | If not empty, the parameter contains the entity name and value. Default is empty.
- `name` (string): Field name that you want to search in.
- `value` (string): Entity value that you want to search for. | `object` | No +`sort` | If not empty, sorts the result by a field in a certain order. Default is empty. Properties of `sort`:
- `direction` (string): Specify "desc" or "asc" for descending or ascending order.
- `field` (string): Order the results by a field. | `object` | No + +--- + +## Search detector tasks +Introduced 1.1 +{: .label .label-purple } + +Searches detector tasks. + +#### Request + +```json +POST _plugins/_anomaly_detection/detectors/tasks/_search +{ + "query": { + "bool": { + "filter": [ + { + "term": { + "detector_id": { + "value": "_6WPu3cBBnauGn7oxUAv" + } + } + }, + { + "term": { + "task_type": { + "value": "HISTORICAL_HC_DETECTOR" + } + } + } + ] + } + }, + "sort": [ + { + "execution_start_time": { + "order": "desc" + } + } + ] +} +``` + + +#### Sample response + +```json +{ + "took" : 5, + "timed_out" : false, + "_shards" : { + "total" : 1, + "successful" : 1, + "skipped" : 0, + "failed" : 0 + }, + "hits" : { + "total" : { + "value" : 1, + "relation" : "eq" + }, + "max_score" : null, + "hits" : [ + { + "_index" : ".opendistro-anomaly-detection-state", + "_type" : "_doc", + "_id" : "TM3tOHwBCi2h__AOXlyQ", + "_version" : 3, + "_seq_no" : 14, + "_primary_term" : 1, + "_score" : null, + "_source" : { + "detector_id" : "rlDtOHwBD5tpxlbyW7Nt", + "error" : "", + "detection_date_range" : { + "start_time" : 1632437852100, + "end_time" : 1633042652100 + }, + "task_progress" : 0.5, + "last_update_time" : 1633042667358, + "execution_start_time" : 1633042652810, + "state" : "RUNNING", + "coordinating_node" : "2hEGbUw6ShaiKe05n_xLdA", + "task_type" : "HISTORICAL_HC_DETECTOR", + "started_by" : "admin", + "init_progress" : 0.0, + "is_latest" : true, + "detector" : { + "category_field" : [ + "type" + ], + "description" : "test", + "ui_metadata" : { + "features" : { + "test-feature" : { + "aggregationBy" : "sum", + "aggregationOf" : "value", + "featureType" : "simple_aggs" + } + }, + "filters" : [ ] + }, + "feature_attributes" : [ + { + "feature_id" : "7VDtOHwBD5tpxlbyWqPs", + "feature_enabled" : true, + "feature_name" : "test-feature", + "aggregation_query" : { + "test_feature" : { + "sum" : { + "field" : "value" + } + } + } + } + ], + "schema_version" : 0, + "time_field" : "timestamp", + "last_update_time" : 1633042652012, + "indices" : [ + "server_log" + ], + "window_delay" : { + "period" : { + "unit" : "Minutes", + "interval" : 1 + } + }, + "detection_interval" : { + "period" : { + "unit" : "Minutes", + "interval" : 5 + } + }, + "name" : "test-detector", + "filter_query" : { + "match_all" : { + "boost" : 1.0 + } + }, + "shingle_size" : 8, + "user" : { + "backend_roles" : [ + "admin" + ], + "custom_attribute_names" : [ ], + "roles" : [ + "own_index", + "all_access" + ], + "name" : "admin", + "user_requested_tenant" : null + }, + "detector_type" : "MULTI_ENTITY" + }, + "user" : { + "backend_roles" : [ + "admin" + ], + "custom_attribute_names" : [ ], + "roles" : [ + "own_index", + "all_access" + ], + "name" : "admin", + "user_requested_tenant" : "__user__" + } + }, + "sort" : [ + 1633042652810 + ] + } + ] + } +} +``` + --- @@ -976,6 +1162,218 @@ DELETE _plugins/_anomaly_detection/detectors/ } ``` +--- + +## Delete detector results +Introduced 1.1 +{: .label .label-purple } + +Deletes a detector results based on a query. + +#### Request + +```json +DELETE _plugins/_anomaly_detection/detectors/results + +{ + "query": { + "bool": { + "filter": [ + { + "term": { + "detector_id": { + "value": "rlDtOHwBD5tpxlbyW7Nt" + } + } + }, + { + "term": { + "task_id": { + "value": "TM3tOHwBCi2h__AOXlyQ" + } + } + }, + { + "range": { + "data_start_time": { + "lte": 1632441600000 + } + } + } + ] + } + } +} +``` + + +#### Sample response + +```json +{ + "took" : 48, + "timed_out" : false, + "total" : 28, + "updated" : 0, + "created" : 0, + "deleted" : 28, + "batches" : 1, + "version_conflicts" : 0, + "noops" : 0, + "retries" : { + "bulk" : 0, + "search" : 0 + }, + "throttled_millis" : 0, + "requests_per_second" : -1.0, + "throttled_until_millis" : 0, + "failures" : [ ] +} +``` + +--- + +## Validate detector +Introduced 1.1 +{: .label .label-purple } + +Validates detector before creating. This API shows you any invalid fields in your configuration and also recommendations on how to fix it. + +#### Request + +```json +POST _plugins/_anomaly_detection/detectors/_validate/detector,model +{ + "name": "test-detector", + "description": "Test detector", + "time_field": "timestamp", + "indices": [ + "order*" + ], + "feature_attributes": [ + { + "feature_name": "total_order", + "feature_enabled": true, + "aggregation_query": { + "total_order": { + "sum": { + "field": "value" + } + } + } + } + ], + "filter_query": { + "bool": { + "filter": [ + { + "exists": { + "field": "value", + "boost": 1 + } + } + ], + "adjust_pure_negative": true, + "boost": 1 + } + }, + "detection_interval": { + "period": { + "interval": 1, + "unit": "Minutes" + } + }, + "window_delay": { + "period": { + "interval": 1, + "unit": "Minutes" + } + }, + "category_field": [ + "hc_field" + ], + "shingle_size": 8 +} +``` + + +#### Sample response + +```json +{ + "detector": { + "name": { + "message": "name should be set|duplicate" + }, + "time_field": { + "message": "time_field should be set missing|not_exist" + }, + "indices": { + "message": "should be set|not_exist|empty" + }, + "feature_attributes": { + // exist when message is "there exists non-numeric field" + [Optional]"problematic_feature_name1": { + "message": "{field} is invalid with {exceptionMessage}" + } + "problematic_feature_name2": { + "message": "{field} is invalid with {exceptionMessage}" + }, + "message": "there exists non-numeric field|duplicate feature names|over 5 features|duplicate feature aggregation query names" + }, + "detection_interval": { + "message": "detection_interval should be set|Interval should be non-negative|unit is not supported" + }, + "category_field": { + "message": "must only 1 field, and must be IP address or keyword type" + }, + "shingle_size": { + "message": "must be between 1 and 1000" + }, + }, + "model": { + "filter_query": { + "message": "data is too sparse after filter_query is applied" + }, + "detection_interval": { + // exists when suggested value can be found + [Optional]"suggested_value": { + "period": { + "interval": 1, + "unit": "Minutes" + } + } + "message": "use suggested value|no suggested value found, ingest more data" + }, + "category_field": { + "message": "data with {category_field} is too sparse, ingest more data" + }, + "feature_attributes": { + "problematic_feature_name1": { + "message": "data is too sparse, ingest more data with this {field}" + } + "problematic_feature_name2": { + "message": "data is too sparse, ingest more data with this {field}" + }, + "message": "data is too sparse, ingest more data" + }, + "memory": { + "message": "model size exceeds memory limit, please stop/delete unused detectors, or reduce shingle size or number of features" + }, + "window_delay": { + // exists when suggested value can be found + [Optional]"suggested_value": { + "period": { + "interval": 1, + "unit": "Minutes" + } + }, + "message": "use suggested value(if it exists), and ingest more data if possible" + } + } +} + +``` --- @@ -1100,56 +1498,6 @@ PUT _plugins/_anomaly_detection/detectors/ } ``` -To update a historical detector: - -#### Request - -```json -PUT _plugins/_anomaly_detection/detectors/ -{ - "name": "test1", - "description": "test historical detector", - "time_field": "timestamp", - "indices": [ - "nab_art_daily_jumpsdown" - ], - "filter_query": { - "match_all": { - "boost": 1 - } - }, - "detection_interval": { - "period": { - "interval": 1, - "unit": "Minutes" - } - }, - "window_delay": { - "period": { - "interval": 1, - "unit": "Minutes" - } - }, - "feature_attributes": [ - { - "feature_name": "F1", - "feature_enabled": true, - "aggregation_query": { - "f_1": { - "sum": { - "field": "value" - } - } - } - } - ], - "detection_date_range": { - "start_time": 1577840401000, - "end_time": 1606121925000 - } -} -``` - --- ## Get detector @@ -1238,80 +1586,133 @@ GET _plugins/_anomaly_detection/detectors/?job=true ```json { - "_id" : "m4ccEnIBTXsGi3mvMt9p", - "_version" : 1, - "_primary_term" : 1, - "_seq_no" : 3, - "anomaly_detector" : { - "name" : "test-detector", - "description" : "Test detector", - "time_field" : "timestamp", - "indices" : [ - "order*" - ], - "filter_query" : { - "bool" : { - "filter" : [ - { - "exists" : { - "field" : "value", - "boost" : 1.0 - } - } + "_id": "LJxGsXcBoDQA8W1Q--A1", + "_version": 1, + "_primary_term": 1, + "_seq_no": 0, + "anomaly_detector": { + "name": "test2", + "description": "test", + "time_field": "timestamp", + "indices": [ + "server_log" ], - "adjust_pure_negative" : true, - "boost" : 1.0 - } - }, - "detection_interval" : { - "period" : { - "interval" : 1, - "unit" : "Minutes" - } - }, - "window_delay" : { - "period" : { - "interval" : 1, - "unit" : "Minutes" - } - }, - "schema_version" : 0, - "feature_attributes" : [ - { - "feature_id" : "mYccEnIBTXsGi3mvMd8_", - "feature_name" : "total_order", - "feature_enabled" : true, - "aggregation_query" : { - "total_order" : { - "sum" : { - "field" : "value" + "filter_query": { + "match_all": { + "boost": 1.0 } - } + }, + "detection_interval": { + "period": { + "interval": 1, + "unit": "Minutes" + } + }, + "window_delay": { + "period": { + "interval": 1, + "unit": "Minutes" + } + }, + "shingle_size": 8, + "schema_version": 0, + "feature_attributes": [ + { + "feature_id": "K5xGsXcBoDQA8W1Q-uCF", + "feature_name": "F1", + "feature_enabled": *true*, + "aggregation_query": { + "f_1": { + "sum": { + "field": "value" + } + } + } + } + ], + "last_update_time": 1613586955060, + "detector_type": "MULTI_ENTITY" + }, + "anomaly_detector_job": { + "name": "LJxGsXcBoDQA8W1Q--A1", + "schedule": { + "interval": { + "start_time": 1613587220387, + "period": 1, + "unit": "Minutes" + } + }, + "window_delay": { + "period": { + "interval": 1, + "unit": "Minutes" + } + }, + "enabled": *false*, + "enabled_time": 1613587220387, + "last_update_time": 1613587289169, + "lock_duration_seconds": 60, + "disabled_time": 1613587289169 + }, + "anomaly_detection_task": { + "task_id": "WZ5LsXcBoDQA8W1QmUa3", + "last_update_time": 1613587349022, + "error": "Task cancelled by user", + "state": "STOPPED", + "detector_id": "LJxGsXcBoDQA8W1Q--A1", + "task_progress": 0.26321793, + "init_progress": 1.0, + "current_piece": 1611030900000, + "execution_start_time": 1613587257783, + "execution_end_time": 1613587349022, + "is_latest": *true*, + "task_type": "HISTORICAL", + "coordinating_node": "NSw5j-3YQeGkH8KESVKlzw", + "worker_node": "NSw5j-3YQeGkH8KESVKlzw", + "detector": { + "name": "test2", + "description": "test", + "time_field": "timestamp", + "indices": [ + "server_log" + ], + "filter_query": { + "match_all": { + "boost": 1.0 + } + }, + "detection_interval": { + "period": { + "interval": 1, + "unit": "Minutes" + } + }, + "window_delay": { + "period": { + "interval": 1, + "unit": "Minutes" + } + }, + "shingle_size": 8, + "schema_version": 0, + "feature_attributes": [ + { + "feature_id": "K5xGsXcBoDQA8W1Q-uCF", + "feature_name": "F1", + "feature_enabled": *true*, + "aggregation_query": { + "f_1": { + "sum": { + "field": "value" + } + } + } + } + ], + "last_update_time": 1613586955060, + "detector_type": "MULTI_ENTITY" } - } - ], - "last_update_time" : 1589441737319 - }, - "anomaly_detector_job" : { - "name" : "m4ccEnIBTXsGi3mvMt9p", - "schedule" : { - "interval" : { - "start_time" : 1589442051271, - "period" : 1, - "unit" : "Minutes" - } - }, - "window_delay" : { - "period" : { - "interval" : 1, - "unit" : "Minutes" - } - }, - "enabled" : true, - "enabled_time" : 1589442051271, - "last_update_time" : 1589442051271, - "lock_duration_seconds" : 60 - } + } } ``` @@ -1336,7 +1737,7 @@ GET _plugins/_anomaly_detection/detectors/?task=true "description": "test", "time_field": "timestamp", "indices": [ - "nab*" + "ser*" ], "filter_query": { "match_all": { @@ -1419,7 +1820,7 @@ GET _plugins/_anomaly_detection/detectors/?task=true "description": "test", "time_field": "timestamp", "indices": [ - "nab*" + "ser*" ], "filter_query": { "match_all": { @@ -1513,16 +1914,24 @@ GET _plugins/_anomaly_detection/detectors/_search POST _plugins/_anomaly_detection/detectors/_search Sample Input: + { "query": { - "match": { - "name": "test-detector" + "bool": { + "filter": [ + { + "terms": { + "indices": [ + "server_log" + ] + } + } + ] } } } ``` - #### Sample response ```json @@ -1627,82 +2036,864 @@ GET _plugins/_anomaly_detection/stats/ ```json { - "_nodes" : { - "total" : 3, - "successful" : 3, - "failed" : 0 - }, - "cluster_name" : "multi-node-run", - "anomaly_detectors_index_status" : "green", - "detector_count" : 1, - "models_checkpoint_index_status" : "green", - "anomaly_results_index_status" : "green", - "nodes" : { - "IgWDUfzFRzW0FWAXM5FGJw" : { - "ad_execute_request_count" : 8, - "ad_execute_failure_count" : 7, - "models" : [ + "anomaly_detectors_index_status": "yellow", + "anomaly_detection_state_status": "yellow", + "single_entity_detector_count": 0, + "detector_count": 1, + "multi_entity_detector_count": 0, + "anomaly_detection_job_index_status": "yellow", + "models_checkpoint_index_status": "yellow", + "anomaly_results_index_status": "yellow", + "nodes": { + "hhfW2ZNVTJCtbs8rO-nF4g": { + "ad_execute_request_count": 6, + "models": [ { - "detector_id" : "m4ccEnIBTXsGi3mvMt9p", - "model_type" : "rcf", - "model_id" : "m4ccEnIBTXsGi3mvMt9p_model_rcf_0" + "detector_id": "mmZFeXsB7JcKN0mdnMf4", + "model_type": "entity", + "last_used_time": 1629827578975, + "model_id": "mmZFeXsB7JcKN0mdnMf4_entity_ic43SHH11NWr32xXgjRFwg", + "last_checkpoint_time": 1629827339211, + "entity": [ + { + "name": "host", + "value": "server_2" + }, + { + "name": "service", + "value": "app_6" + } + ] }, { - "detector_id" : "m4ccEnIBTXsGi3mvMt9p", - "model_type" : "threshold", - "model_id" : "m4ccEnIBTXsGi3mvMt9p_model_threshold" - } - ] - }, - "y7YUQWukQEWOYbfdEq13hQ" : { - "ad_execute_request_count" : 0, - "ad_execute_failure_count" : 0, - "models" : [ ] - }, - "cDcGNsPoRAyRMlPP1m-vZw" : { - "ad_execute_request_count" : 0, - "ad_execute_failure_count" : 0, - "models" : [ - { - "detector_id" : "m4ccEnIBTXsGi3mvMt9p", - "model_type" : "rcf", - "model_id" : "m4ccEnIBTXsGi3mvMt9p_model_rcf_2" + "detector_id": "mmZFeXsB7JcKN0mdnMf4", + "model_type": "entity", + "last_used_time": 1629827578975, + "model_id": "mmZFeXsB7JcKN0mdnMf4_entity_k2gq2eRP0vTV2LNNyFdIqg", + "last_checkpoint_time": 1629827339733, + "entity": [ + { + "name": "host", + "value": "server_1" + }, + { + "name": "service", + "value": "app_0" + } + ] }, { - "detector_id" : "m4ccEnIBTXsGi3mvMt9p", - "model_type" : "rcf", - "model_id" : "m4ccEnIBTXsGi3mvMt9p_model_rcf_1" + "detector_id": "mmZFeXsB7JcKN0mdnMf4", + "model_type": "entity", + "last_used_time": 1629827578980, + "model_id": "mmZFeXsB7JcKN0mdnMf4_entity_DOze7d0HnK3K54g3Emk1XA", + "last_checkpoint_time": 1629827343186, + "entity": [ + { + "name": "host", + "value": "server_2" + }, + { + "name": "service", + "value": "app_3" + } + ] + }, + { + "detector_id": "mmZFeXsB7JcKN0mdnMf4", + "model_type": "entity", + "last_used_time": 1629827578977, + "model_id": "mmZFeXsB7JcKN0mdnMf4_entity_NgGmglQvOMQQciDdPxN_Ig", + "last_checkpoint_time": 1629827340961, + "entity": [ + { + "name": "host", + "value": "server_3" + }, + { + "name": "service", + "value": "app_5" + } + ] + }, + { + "detector_id": "mmZFeXsB7JcKN0mdnMf4", + "model_type": "entity", + "last_used_time": 1629827578977, + "model_id": "mmZFeXsB7JcKN0mdnMf4_entity_oTdcenY1L5bqa6chUxg7xw", + "last_checkpoint_time": 1629827340263, + "entity": [ + { + "name": "host", + "value": "server_1" + }, + { + "name": "service", + "value": "app_1" + } + ] + }, + { + "detector_id": "mmZFeXsB7JcKN0mdnMf4", + "model_type": "entity", + "last_used_time": 1629827578979, + "model_id": "mmZFeXsB7JcKN0mdnMf4_entity_zxSqAWv5Iz19v-Hnqhrwrw", + "last_checkpoint_time": 1629827342814, + "entity": [ + { + "name": "host", + "value": "server_1" + }, + { + "name": "service", + "value": "app_5" + } + ] + }, + { + "detector_id": "mmZFeXsB7JcKN0mdnMf4", + "model_type": "entity", + "last_used_time": 1629827578976, + "model_id": "mmZFeXsB7JcKN0mdnMf4_entity_Yu8X2rA39lhjYzqebjLxhQ", + "last_checkpoint_time": 1629827339992, + "entity": [ + { + "name": "host", + "value": "server_2" + }, + { + "name": "service", + "value": "app_1" + } + ] + }, + { + "detector_id": "mmZFeXsB7JcKN0mdnMf4", + "model_type": "entity", + "last_used_time": 1629827578978, + "model_id": "mmZFeXsB7JcKN0mdnMf4_entity_6SvF11RCqf7HYbY56BnFKA", + "last_checkpoint_time": 1629827341806, + "entity": [ + { + "name": "host", + "value": "server_3" + }, + { + "name": "service", + "value": "app_2" + } + ] + }, + { + "detector_id": "mmZFeXsB7JcKN0mdnMf4", + "model_type": "entity", + "last_used_time": 1629827578980, + "model_id": "mmZFeXsB7JcKN0mdnMf4_entity_3S8k6q_DLFhw3hboko3dfw", + "last_checkpoint_time": 1629827343371, + "entity": [ + { + "name": "host", + "value": "server_1" + }, + { + "name": "service", + "value": "app_3" + } + ] + }, + { + "detector_id": "mmZFeXsB7JcKN0mdnMf4", + "model_type": "entity", + "last_used_time": 1629827578978, + "model_id": "mmZFeXsB7JcKN0mdnMf4_entity_0uafBokvEYuncGbjP3D2qA", + "last_checkpoint_time": 1629827342302, + "entity": [ + { + "name": "host", + "value": "server_2" + }, + { + "name": "service", + "value": "app_5" + } + ] + }, + { + "detector_id": "mmZFeXsB7JcKN0mdnMf4", + "model_type": "entity", + "last_used_time": 1629827578977, + "model_id": "mmZFeXsB7JcKN0mdnMf4_entity_93DEK2PooWlHF6gkh-0hIA", + "last_checkpoint_time": 1629827340727, + "entity": [ + { + "name": "host", + "value": "server_2" + }, + { + "name": "service", + "value": "app_4" + } + ] + }, + { + "detector_id": "mmZFeXsB7JcKN0mdnMf4", + "model_type": "entity", + "last_used_time": 1629827578975, + "model_id": "mmZFeXsB7JcKN0mdnMf4_entity_FuqXh0HBXlPhKepOc6JADQ", + "last_checkpoint_time": 1629827338908, + "entity": [ + { + "name": "host", + "value": "server_3" + }, + { + "name": "service", + "value": "app_6" + } + ] + }, + { + "detector_id": "mmZFeXsB7JcKN0mdnMf4", + "model_type": "entity", + "last_used_time": 1629827578979, + "model_id": "mmZFeXsB7JcKN0mdnMf4_entity_B4zrbSQ1-pvdBLx0FzQxvw", + "last_checkpoint_time": 1629827342611, + "entity": [ + { + "name": "host", + "value": "server_3" + }, + { + "name": "service", + "value": "app_3" + } + ] + }, + { + "detector_id": "mmZFeXsB7JcKN0mdnMf4", + "model_type": "entity", + "last_used_time": 1629827578978, + "model_id": "mmZFeXsB7JcKN0mdnMf4_entity_xm_gKBMKlgymKcoqZyXT8A", + "last_checkpoint_time": 1629827341365, + "entity": [ + { + "name": "host", + "value": "server_2" + }, + { + "name": "service", + "value": "app_0" + } + ] + }, + { + "detector_id": "mmZFeXsB7JcKN0mdnMf4", + "model_type": "entity", + "last_used_time": 1629827578978, + "model_id": "mmZFeXsB7JcKN0mdnMf4_entity_OnZ4CP-yJF5llO57gUjM6w", + "last_checkpoint_time": 1629827341599, + "entity": [ + { + "name": "host", + "value": "server_3" + }, + { + "name": "service", + "value": "app_1" + } + ] + }, + { + "detector_id": "mmZFeXsB7JcKN0mdnMf4", + "model_type": "entity", + "last_used_time": 1629827578977, + "model_id": "mmZFeXsB7JcKN0mdnMf4_entity_E_uWreoeJpGrAMMaitg8BA", + "last_checkpoint_time": 1629827340418, + "entity": [ + { + "name": "host", + "value": "server_3" + }, + { + "name": "service", + "value": "app_4" + } + ] + }, + { + "detector_id": "mmZFeXsB7JcKN0mdnMf4", + "model_type": "entity", + "last_used_time": 1629827578979, + "model_id": "mmZFeXsB7JcKN0mdnMf4_entity_OIsxy2nXMVdngK6Vv3X0uw", + "last_checkpoint_time": 1629827342444, + "entity": [ + { + "name": "host", + "value": "server_2" + }, + { + "name": "service", + "value": "app_2" + } + ] + }, + { + "detector_id": "mmZFeXsB7JcKN0mdnMf4", + "model_type": "entity", + "last_used_time": 1629827578978, + "model_id": "mmZFeXsB7JcKN0mdnMf4_entity_I0L8K8ktyVnyL59CVFCLVQ", + "last_checkpoint_time": 1629827342068, + "entity": [ + { + "name": "host", + "value": "server_1" + }, + { + "name": "service", + "value": "app_4" + } + ] + }, + { + "detector_id": "mmZFeXsB7JcKN0mdnMf4", + "model_type": "entity", + "last_used_time": 1629827578975, + "model_id": "mmZFeXsB7JcKN0mdnMf4_entity_ZoNYVJsq5ry6e-SWXmAt1Q", + "last_checkpoint_time": 1629827339435, + "entity": [ + { + "name": "host", + "value": "server_1" + }, + { + "name": "service", + "value": "app_6" + } + ] + }, + { + "detector_id": "mmZFeXsB7JcKN0mdnMf4", + "model_type": "entity", + "last_used_time": 1629827578978, + "model_id": "mmZFeXsB7JcKN0mdnMf4_entity_qo2ANH_NS7Bg8iV4AJpHOw", + "last_checkpoint_time": 1629827341187, + "entity": [ + { + "name": "host", + "value": "server_3" + }, + { + "name": "service", + "value": "app_0" + } + ] + }, + { + "detector_id": "mmZFeXsB7JcKN0mdnMf4", + "model_type": "entity", + "last_used_time": 1629827578980, + "model_id": "mmZFeXsB7JcKN0mdnMf4_entity_412FoQwCykWTAhjVfDGQDg", + "last_checkpoint_time": 1629827342983, + "entity": [ + { + "name": "host", + "value": "server_1" + }, + { + "name": "service", + "value": "app_2" + } + ] } - ] + ], + "ad_canceled_batch_task_count": 0, + "ad_hc_execute_request_count": 6, + "ad_hc_execute_failure_count": 0, + "model_count": 21, + "ad_execute_failure_count": 0, + "ad_batch_task_failure_count": 0, + "ad_total_batch_task_execution_count": 0, + "ad_executing_batch_task_count": 0 } } } ``` +The `model_count` parameter shows the total number of models running on each node’s memory. Historical detectors contain additional fields: +- `ad_total_batch_task_execution_count` +- `ad_executing_batch_task_count` +- `ad_canceled_batch_task_count` +- `ad_batch_task_failure_count` + #### Sample response ```json { - "anomaly_detectors_index_status": "yellow", - "anomaly_detection_state_status": "yellow", - "historical_detector_count": 3, - "detector_count": 7, - "anomaly_detection_job_index_status": "yellow", - "models_checkpoint_index_status": "yellow", - "anomaly_results_index_status": "yellow", + "anomaly_detectors_index_status": "green", + "anomaly_detection_state_status": "green", + "single_entity_detector_count": 0, + "detector_count": 1, + "multi_entity_detector_count": 1, + "anomaly_detection_job_index_status": "green", + "models_checkpoint_index_status": "green", + "anomaly_results_index_status": "green", "nodes": { - "Mz9HDZnuQwSCw0UiisxwWg": { + "bCtWtxWPThq0BIn5P5I4Xw": { "ad_execute_request_count": 0, - "models": [], - "ad_canceled_batch_task_count": 2, + "models": [ + { + "detector_id": "rlDtOHwBD5tpxlbyW7Nt", + "model_type": "entity", + "last_used_time": 1633044152729, + "model_id": "rlDtOHwBD5tpxlbyW7Nt_entity_error20", + "last_checkpoint_time": 1633043556222, + "entity": [ + { + "name": "type", + "value": "error20" + } + ] + }, + { + "detector_id": "rlDtOHwBD5tpxlbyW7Nt", + "model_type": "entity", + "last_used_time": 1633044152767, + "model_id": "rlDtOHwBD5tpxlbyW7Nt_entity_error31", + "last_checkpoint_time": 1633043855146, + "entity": [ + { + "name": "type", + "value": "error31" + } + ] + }, + { + "detector_id": "rlDtOHwBD5tpxlbyW7Nt", + "model_type": "entity", + "last_used_time": 1633044152729, + "model_id": "rlDtOHwBD5tpxlbyW7Nt_entity_error21", + "last_checkpoint_time": 1633043555143, + "entity": [ + { + "name": "type", + "value": "error21" + } + ] + }, + { + "detector_id": "rlDtOHwBD5tpxlbyW7Nt", + "model_type": "entity", + "last_used_time": 1633044152727, + "model_id": "rlDtOHwBD5tpxlbyW7Nt_entity_error13", + "last_checkpoint_time": 1633043554046, + "entity": [ + { + "name": "type", + "value": "error13" + } + ] + }, + { + "detector_id": "rlDtOHwBD5tpxlbyW7Nt", + "model_type": "entity", + "last_used_time": 1633044152753, + "model_id": "rlDtOHwBD5tpxlbyW7Nt_entity_error24", + "last_checkpoint_time": 1633043853986, + "entity": [ + { + "name": "type", + "value": "error24" + } + ] + }, + { + "detector_id": "rlDtOHwBD5tpxlbyW7Nt", + "model_type": "entity", + "last_used_time": 1633044152792, + "model_id": "rlDtOHwBD5tpxlbyW7Nt_entity_error25", + "last_checkpoint_time": 1633043857320, + "entity": [ + { + "name": "type", + "value": "error25" + } + ] + }, + { + "detector_id": "rlDtOHwBD5tpxlbyW7Nt", + "model_type": "entity", + "last_used_time": 1633044152779, + "model_id": "rlDtOHwBD5tpxlbyW7Nt_entity_error28", + "last_checkpoint_time": 1633043856244, + "entity": [ + { + "name": "type", + "value": "error28" + } + ] + }, + { + "detector_id": "rlDtOHwBD5tpxlbyW7Nt", + "model_type": "entity", + "last_used_time": 1633044152732, + "model_id": "rlDtOHwBD5tpxlbyW7Nt_entity_error16", + "last_checkpoint_time": 1633043557253, + "entity": [ + { + "name": "type", + "value": "error16" + } + ] + } + ], + "ad_canceled_batch_task_count": 0, "ad_hc_execute_request_count": 0, "ad_hc_execute_failure_count": 0, + "model_count": 8, "ad_execute_failure_count": 0, "ad_batch_task_failure_count": 0, - "ad_executing_batch_task_count": 1, - "ad_total_batch_task_count": 8 + "ad_total_batch_task_execution_count": 15, + "ad_executing_batch_task_count": 3 + }, + "dIyavWhmSYWGz65b4u-lpQ": { + "ad_execute_request_count": 0, + "models": [ + { + "detector_id": "rlDtOHwBD5tpxlbyW7Nt", + "model_type": "entity", + "last_used_time": 1633044152729, + "model_id": "rlDtOHwBD5tpxlbyW7Nt_entity_error3", + "last_checkpoint_time": 1633043256013, + "entity": [ + { + "name": "type", + "value": "error3" + } + ] + }, + { + "detector_id": "rlDtOHwBD5tpxlbyW7Nt", + "model_type": "entity", + "last_used_time": 1633044152727, + "model_id": "rlDtOHwBD5tpxlbyW7Nt_entity_error1", + "last_checkpoint_time": 1633043254819, + "entity": [ + { + "name": "type", + "value": "error1" + } + ] + }, + { + "detector_id": "rlDtOHwBD5tpxlbyW7Nt", + "model_type": "entity", + "last_used_time": 1633044152735, + "model_id": "rlDtOHwBD5tpxlbyW7Nt_entity_error22", + "last_checkpoint_time": 1633043557023, + "entity": [ + { + "name": "type", + "value": "error22" + } + ] + }, + { + "detector_id": "rlDtOHwBD5tpxlbyW7Nt", + "model_type": "entity", + "last_used_time": 1633044152750, + "model_id": "rlDtOHwBD5tpxlbyW7Nt_entity_error32", + "last_checkpoint_time": 1633043854080, + "entity": [ + { + "name": "type", + "value": "error32" + } + ] + }, + { + "detector_id": "rlDtOHwBD5tpxlbyW7Nt", + "model_type": "entity", + "last_used_time": 1633044152784, + "model_id": "rlDtOHwBD5tpxlbyW7Nt_entity_error23", + "last_checkpoint_time": 1633043857463, + "entity": [ + { + "name": "type", + "value": "error23" + } + ] + }, + { + "detector_id": "rlDtOHwBD5tpxlbyW7Nt", + "model_type": "entity", + "last_used_time": 1633044152774, + "model_id": "rlDtOHwBD5tpxlbyW7Nt_entity_error26", + "last_checkpoint_time": 1633043856308, + "entity": [ + { + "name": "type", + "value": "error26" + } + ] + }, + { + "detector_id": "rlDtOHwBD5tpxlbyW7Nt", + "model_type": "entity", + "last_used_time": 1633044152734, + "model_id": "rlDtOHwBD5tpxlbyW7Nt_entity_error14", + "last_checkpoint_time": 1633043555939, + "entity": [ + { + "name": "type", + "value": "error14" + } + ] + }, + { + "detector_id": "rlDtOHwBD5tpxlbyW7Nt", + "model_type": "entity", + "last_used_time": 1633044152731, + "model_id": "rlDtOHwBD5tpxlbyW7Nt_entity_error9", + "last_checkpoint_time": 1633043257214, + "entity": [ + { + "name": "type", + "value": "error9" + } + ] + }, + { + "detector_id": "rlDtOHwBD5tpxlbyW7Nt", + "model_type": "entity", + "last_used_time": 1633044152730, + "model_id": "rlDtOHwBD5tpxlbyW7Nt_entity_error19", + "last_checkpoint_time": 1633043553882, + "entity": [ + { + "name": "type", + "value": "error19" + } + ] + }, + { + "detector_id": "rlDtOHwBD5tpxlbyW7Nt", + "model_type": "entity", + "last_used_time": 1633044152732, + "model_id": "rlDtOHwBD5tpxlbyW7Nt_entity_error18", + "last_checkpoint_time": 1633043554874, + "entity": [ + { + "name": "type", + "value": "error18" + } + ] + }, + { + "detector_id": "rlDtOHwBD5tpxlbyW7Nt", + "model_type": "entity", + "last_used_time": 1633044152763, + "model_id": "rlDtOHwBD5tpxlbyW7Nt_entity_error29", + "last_checkpoint_time": 1633043855226, + "entity": [ + { + "name": "type", + "value": "error29" + } + ] + } + ], + "ad_canceled_batch_task_count": 0, + "ad_hc_execute_request_count": 0, + "ad_hc_execute_failure_count": 0, + "model_count": 11, + "ad_execute_failure_count": 0, + "ad_batch_task_failure_count": 0, + "ad_total_batch_task_execution_count": 14, + "ad_executing_batch_task_count": 3 + }, + "2hEGbUw6ShaiKe05n_xLdA": { + "ad_execute_request_count": 5, + "models": [ + { + "detector_id": "rlDtOHwBD5tpxlbyW7Nt", + "model_type": "entity", + "last_used_time": 1633044152714, + "model_id": "rlDtOHwBD5tpxlbyW7Nt_entity_error5", + "last_checkpoint_time": 1633043256689, + "entity": [ + { + "name": "type", + "value": "error5" + } + ] + }, + { + "detector_id": "rlDtOHwBD5tpxlbyW7Nt", + "model_type": "entity", + "last_used_time": 1633044152711, + "model_id": "rlDtOHwBD5tpxlbyW7Nt_entity_error6", + "last_checkpoint_time": 1633043254281, + "entity": [ + { + "name": "type", + "value": "error6" + } + ] + }, + { + "detector_id": "rlDtOHwBD5tpxlbyW7Nt", + "model_type": "entity", + "last_used_time": 1633044152716, + "model_id": "rlDtOHwBD5tpxlbyW7Nt_entity_error4", + "last_checkpoint_time": 1633043257797, + "entity": [ + { + "name": "type", + "value": "error4" + } + ] + }, + { + "detector_id": "rlDtOHwBD5tpxlbyW7Nt", + "model_type": "entity", + "last_used_time": 1633044152709, + "model_id": "rlDtOHwBD5tpxlbyW7Nt_entity_error2", + "last_checkpoint_time": 1633043260938, + "entity": [ + { + "name": "type", + "value": "error2" + } + ] + }, + { + "detector_id": "rlDtOHwBD5tpxlbyW7Nt", + "model_type": "entity", + "last_used_time": 1633044152742, + "model_id": "rlDtOHwBD5tpxlbyW7Nt_entity_error30", + "last_checkpoint_time": 1633043853983, + "entity": [ + { + "name": "type", + "value": "error30" + } + ] + }, + { + "detector_id": "rlDtOHwBD5tpxlbyW7Nt", + "model_type": "entity", + "last_used_time": 1633044152725, + "model_id": "rlDtOHwBD5tpxlbyW7Nt_entity_error11", + "last_checkpoint_time": 1633043263038, + "entity": [ + { + "name": "type", + "value": "error11" + } + ] + }, + { + "detector_id": "rlDtOHwBD5tpxlbyW7Nt", + "model_type": "entity", + "last_used_time": 1633044152712, + "model_id": "rlDtOHwBD5tpxlbyW7Nt_entity_error10", + "last_checkpoint_time": 1633043255533, + "entity": [ + { + "name": "type", + "value": "error10" + } + ] + }, + { + "detector_id": "rlDtOHwBD5tpxlbyW7Nt", + "model_type": "entity", + "last_used_time": 1633044152719, + "model_id": "rlDtOHwBD5tpxlbyW7Nt_entity_error7", + "last_checkpoint_time": 1633043258826, + "entity": [ + { + "name": "type", + "value": "error7" + } + ] + }, + { + "detector_id": "rlDtOHwBD5tpxlbyW7Nt", + "model_type": "entity", + "last_used_time": 1633044152708, + "model_id": "rlDtOHwBD5tpxlbyW7Nt_entity_error8", + "last_checkpoint_time": 1633043259841, + "entity": [ + { + "name": "type", + "value": "error8" + } + ] + }, + { + "detector_id": "rlDtOHwBD5tpxlbyW7Nt", + "model_type": "entity", + "last_used_time": 1633044152721, + "model_id": "rlDtOHwBD5tpxlbyW7Nt_entity_error12", + "last_checkpoint_time": 1633043261989, + "entity": [ + { + "name": "type", + "value": "error12" + } + ] + }, + { + "detector_id": "rlDtOHwBD5tpxlbyW7Nt", + "model_type": "entity", + "last_used_time": 1633044152720, + "model_id": "rlDtOHwBD5tpxlbyW7Nt_entity_error15", + "last_checkpoint_time": 1633043553786, + "entity": [ + { + "name": "type", + "value": "error15" + } + ] + }, + { + "detector_id": "rlDtOHwBD5tpxlbyW7Nt", + "model_type": "entity", + "last_used_time": 1633044152724, + "model_id": "rlDtOHwBD5tpxlbyW7Nt_entity_error17", + "last_checkpoint_time": 1633043554909, + "entity": [ + { + "name": "type", + "value": "error17" + } + ] + }, + { + "detector_id": "rlDtOHwBD5tpxlbyW7Nt", + "model_type": "entity", + "last_used_time": 1633044152751, + "model_id": "rlDtOHwBD5tpxlbyW7Nt_entity_error27", + "last_checkpoint_time": 1633043855105, + "entity": [ + { + "name": "type", + "value": "error27" + } + ] + } + ], + "ad_canceled_batch_task_count": 0, + "ad_hc_execute_request_count": 5, + "ad_hc_execute_failure_count": 0, + "model_count": 13, + "ad_execute_failure_count": 0, + "ad_batch_task_failure_count": 0, + "ad_total_batch_task_execution_count": 14, + "ad_executing_batch_task_count": 3 } } } @@ -1946,7 +3137,7 @@ It also helps track the initialization percentage, the required shingles, and th GET _plugins/_anomaly_detection/detectors//_profile/ GET _plugins/_anomaly_detection/detectors//_profile?_all=true GET _plugins/_anomaly_detection/detectors//_profile/ -GET /_plugins/_anomaly_detection/detectors//_profile/, +GET _plugins/_anomaly_detection/detectors//_profile/, ``` #### Sample Responses @@ -1963,35 +3154,648 @@ GET _plugins/_anomaly_detection/detectors//_profile?_all=true&pretty { "state": "RUNNING", + "error": "", "models": [ { - "model_id": "cneh7HEBHPICjJIdXdrR_model_rcf_2", - "model_size_in_bytes": 4456448, - "node_id": "VS29z70PSzOdHiEw4SoV9Q" + "model_id": "rlDtOHwBD5tpxlbyW7Nt_entity_error20", + "entity": [ + { + "name": "type", + "value": "error20" + } + ], + "model_size_in_bytes": 403491, + "node_id": "bCtWtxWPThq0BIn5P5I4Xw" }, { - "model_id": "cneh7HEBHPICjJIdXdrR_model_rcf_1", - "model_size_in_bytes": 4456448, - "node_id": "VS29z70PSzOdHiEw4SoV9Q" + "model_id": "rlDtOHwBD5tpxlbyW7Nt_entity_error31", + "entity": [ + { + "name": "type", + "value": "error31" + } + ], + "model_size_in_bytes": 403491, + "node_id": "bCtWtxWPThq0BIn5P5I4Xw" }, { - "model_id": "cneh7HEBHPICjJIdXdrR_model_threshold", - "node_id": "Og23iUroTdKrkwS-y89zLw" + "model_id": "rlDtOHwBD5tpxlbyW7Nt_entity_error21", + "entity": [ + { + "name": "type", + "value": "error21" + } + ], + "model_size_in_bytes": 403491, + "node_id": "bCtWtxWPThq0BIn5P5I4Xw" }, { - "model_id": "cneh7HEBHPICjJIdXdrR_model_rcf_0", - "model_size_in_bytes": 4456448, - "node_id": "Og23iUroTdKrkwS-y89zLw" + "model_id": "rlDtOHwBD5tpxlbyW7Nt_entity_error13", + "entity": [ + { + "name": "type", + "value": "error13" + } + ], + "model_size_in_bytes": 403491, + "node_id": "bCtWtxWPThq0BIn5P5I4Xw" + }, + { + "model_id": "rlDtOHwBD5tpxlbyW7Nt_entity_error24", + "entity": [ + { + "name": "type", + "value": "error24" + } + ], + "model_size_in_bytes": 403491, + "node_id": "bCtWtxWPThq0BIn5P5I4Xw" + }, + { + "model_id": "rlDtOHwBD5tpxlbyW7Nt_entity_error25", + "entity": [ + { + "name": "type", + "value": "error25" + } + ], + "model_size_in_bytes": 403491, + "node_id": "bCtWtxWPThq0BIn5P5I4Xw" + }, + { + "model_id": "rlDtOHwBD5tpxlbyW7Nt_entity_error28", + "entity": [ + { + "name": "type", + "value": "error28" + } + ], + "model_size_in_bytes": 403491, + "node_id": "bCtWtxWPThq0BIn5P5I4Xw" + }, + { + "model_id": "rlDtOHwBD5tpxlbyW7Nt_entity_error16", + "entity": [ + { + "name": "type", + "value": "error16" + } + ], + "model_size_in_bytes": 403491, + "node_id": "bCtWtxWPThq0BIn5P5I4Xw" + }, + { + "model_id": "rlDtOHwBD5tpxlbyW7Nt_entity_error3", + "entity": [ + { + "name": "type", + "value": "error3" + } + ], + "model_size_in_bytes": 403491, + "node_id": "dIyavWhmSYWGz65b4u-lpQ" + }, + { + "model_id": "rlDtOHwBD5tpxlbyW7Nt_entity_error1", + "entity": [ + { + "name": "type", + "value": "error1" + } + ], + "model_size_in_bytes": 403491, + "node_id": "dIyavWhmSYWGz65b4u-lpQ" + }, + { + "model_id": "rlDtOHwBD5tpxlbyW7Nt_entity_error22", + "entity": [ + { + "name": "type", + "value": "error22" + } + ], + "model_size_in_bytes": 403491, + "node_id": "dIyavWhmSYWGz65b4u-lpQ" + }, + { + "model_id": "rlDtOHwBD5tpxlbyW7Nt_entity_error32", + "entity": [ + { + "name": "type", + "value": "error32" + } + ], + "model_size_in_bytes": 403491, + "node_id": "dIyavWhmSYWGz65b4u-lpQ" + }, + { + "model_id": "rlDtOHwBD5tpxlbyW7Nt_entity_error23", + "entity": [ + { + "name": "type", + "value": "error23" + } + ], + "model_size_in_bytes": 403491, + "node_id": "dIyavWhmSYWGz65b4u-lpQ" + }, + { + "model_id": "rlDtOHwBD5tpxlbyW7Nt_entity_error26", + "entity": [ + { + "name": "type", + "value": "error26" + } + ], + "model_size_in_bytes": 403491, + "node_id": "dIyavWhmSYWGz65b4u-lpQ" + }, + { + "model_id": "rlDtOHwBD5tpxlbyW7Nt_entity_error14", + "entity": [ + { + "name": "type", + "value": "error14" + } + ], + "model_size_in_bytes": 403491, + "node_id": "dIyavWhmSYWGz65b4u-lpQ" + }, + { + "model_id": "rlDtOHwBD5tpxlbyW7Nt_entity_error9", + "entity": [ + { + "name": "type", + "value": "error9" + } + ], + "model_size_in_bytes": 403491, + "node_id": "dIyavWhmSYWGz65b4u-lpQ" + }, + { + "model_id": "rlDtOHwBD5tpxlbyW7Nt_entity_error19", + "entity": [ + { + "name": "type", + "value": "error19" + } + ], + "model_size_in_bytes": 403491, + "node_id": "dIyavWhmSYWGz65b4u-lpQ" + }, + { + "model_id": "rlDtOHwBD5tpxlbyW7Nt_entity_error18", + "entity": [ + { + "name": "type", + "value": "error18" + } + ], + "model_size_in_bytes": 403491, + "node_id": "dIyavWhmSYWGz65b4u-lpQ" + }, + { + "model_id": "rlDtOHwBD5tpxlbyW7Nt_entity_error29", + "entity": [ + { + "name": "type", + "value": "error29" + } + ], + "model_size_in_bytes": 403491, + "node_id": "dIyavWhmSYWGz65b4u-lpQ" + }, + { + "model_id": "rlDtOHwBD5tpxlbyW7Nt_entity_error5", + "entity": [ + { + "name": "type", + "value": "error5" + } + ], + "model_size_in_bytes": 403491, + "node_id": "2hEGbUw6ShaiKe05n_xLdA" + }, + { + "model_id": "rlDtOHwBD5tpxlbyW7Nt_entity_error6", + "entity": [ + { + "name": "type", + "value": "error6" + } + ], + "model_size_in_bytes": 403491, + "node_id": "2hEGbUw6ShaiKe05n_xLdA" + }, + { + "model_id": "rlDtOHwBD5tpxlbyW7Nt_entity_error4", + "entity": [ + { + "name": "type", + "value": "error4" + } + ], + "model_size_in_bytes": 403491, + "node_id": "2hEGbUw6ShaiKe05n_xLdA" + }, + { + "model_id": "rlDtOHwBD5tpxlbyW7Nt_entity_error2", + "entity": [ + { + "name": "type", + "value": "error2" + } + ], + "model_size_in_bytes": 403491, + "node_id": "2hEGbUw6ShaiKe05n_xLdA" + }, + { + "model_id": "rlDtOHwBD5tpxlbyW7Nt_entity_error30", + "entity": [ + { + "name": "type", + "value": "error30" + } + ], + "model_size_in_bytes": 403491, + "node_id": "2hEGbUw6ShaiKe05n_xLdA" + }, + { + "model_id": "rlDtOHwBD5tpxlbyW7Nt_entity_error11", + "entity": [ + { + "name": "type", + "value": "error11" + } + ], + "model_size_in_bytes": 403491, + "node_id": "2hEGbUw6ShaiKe05n_xLdA" + }, + { + "model_id": "rlDtOHwBD5tpxlbyW7Nt_entity_error10", + "entity": [ + { + "name": "type", + "value": "error10" + } + ], + "model_size_in_bytes": 403491, + "node_id": "2hEGbUw6ShaiKe05n_xLdA" + }, + { + "model_id": "rlDtOHwBD5tpxlbyW7Nt_entity_error7", + "entity": [ + { + "name": "type", + "value": "error7" + } + ], + "model_size_in_bytes": 403491, + "node_id": "2hEGbUw6ShaiKe05n_xLdA" + }, + { + "model_id": "rlDtOHwBD5tpxlbyW7Nt_entity_error8", + "entity": [ + { + "name": "type", + "value": "error8" + } + ], + "model_size_in_bytes": 403491, + "node_id": "2hEGbUw6ShaiKe05n_xLdA" + }, + { + "model_id": "rlDtOHwBD5tpxlbyW7Nt_entity_error12", + "entity": [ + { + "name": "type", + "value": "error12" + } + ], + "model_size_in_bytes": 403491, + "node_id": "2hEGbUw6ShaiKe05n_xLdA" + }, + { + "model_id": "rlDtOHwBD5tpxlbyW7Nt_entity_error15", + "entity": [ + { + "name": "type", + "value": "error15" + } + ], + "model_size_in_bytes": 403491, + "node_id": "2hEGbUw6ShaiKe05n_xLdA" + }, + { + "model_id": "rlDtOHwBD5tpxlbyW7Nt_entity_error17", + "entity": [ + { + "name": "type", + "value": "error17" + } + ], + "model_size_in_bytes": 403491, + "node_id": "2hEGbUw6ShaiKe05n_xLdA" + }, + { + "model_id": "rlDtOHwBD5tpxlbyW7Nt_entity_error27", + "entity": [ + { + "name": "type", + "value": "error27" + } + ], + "model_size_in_bytes": 403491, + "node_id": "2hEGbUw6ShaiKe05n_xLdA" } ], - "shingle_size": 8, - "coordinating_node": "Og23iUroTdKrkwS-y89zLw", - "total_size_in_bytes": 13369344, + "total_size_in_bytes": 12911712, "init_progress": { - "percentage": "70%", - "estimated_minutes_left": 77, - "needed_shingles": 77 - } + "percentage": "100%" + }, + "total_entities": 33, + "active_entities": 32, + "ad_task": { + "ad_task": { + "task_id": "Os4HOXwBCi2h__AONgpc", + "last_update_time": 1633044347855, + "started_by": "admin", + "state": "RUNNING", + "detector_id": "rlDtOHwBD5tpxlbyW7Nt", + "task_progress": 0, + "init_progress": 0, + "execution_start_time": 1633044346460, + "is_latest": true, + "task_type": "HISTORICAL_HC_DETECTOR", + "coordinating_node": "2hEGbUw6ShaiKe05n_xLdA", + "detector": { + "name": "test-detector", + "description": "test", + "time_field": "timestamp", + "indices": [ + "server_log" + ], + "filter_query": { + "match_all": { + "boost": 1 + } + }, + "detection_interval": { + "period": { + "interval": 5, + "unit": "Minutes" + } + }, + "window_delay": { + "period": { + "interval": 1, + "unit": "Minutes" + } + }, + "shingle_size": 8, + "schema_version": 0, + "feature_attributes": [ + { + "feature_id": "7VDtOHwBD5tpxlbyWqPs", + "feature_name": "test-feature", + "feature_enabled": true, + "aggregation_query": { + "test_feature": { + "sum": { + "field": "value" + } + } + } + } + ], + "ui_metadata": { + "features": { + "test-feature": { + "aggregationBy": "sum", + "aggregationOf": "value", + "featureType": "simple_aggs" + } + }, + "filters": [] + }, + "last_update_time": 1633042652012, + "category_field": [ + "type" + ], + "user": { + "name": "admin", + "backend_roles": [ + "admin" + ], + "roles": [ + "own_index", + "all_access" + ], + "custom_attribute_names": [], + "user_requested_tenant": null + }, + "detector_type": "MULTI_ENTITY" + }, + "detection_date_range": { + "start_time": 1632437820000, + "end_time": 1633042620000 + }, + "user": { + "name": "admin", + "backend_roles": [ + "admin" + ], + "roles": [ + "own_index", + "all_access" + ], + "custom_attribute_names": [], + "user_requested_tenant": "__user__" + } + }, + "node_id": "2hEGbUw6ShaiKe05n_xLdA", + "task_id": "Os4HOXwBCi2h__AONgpc", + "task_type": "HISTORICAL_HC_DETECTOR", + "detector_task_slots": 10, + "total_entities_count": 32, + "pending_entities_count": 22, + "running_entities_count": 10, + "running_entities": [ + "error9", + "error8", + "error7", + "error6", + "error5", + "error4", + "error32", + "error31", + "error30", + "error3" + ], + "entity_task_profiles": [ + { + "shingle_size": 8, + "rcf_total_updates": 994, + "threshold_model_trained": true, + "threshold_model_training_data_size": 0, + "model_size_in_bytes": 1593240, + "node_id": "bCtWtxWPThq0BIn5P5I4Xw", + "entity": [ + { + "name": "type", + "value": "error6" + } + ], + "task_id": "P84HOXwBCi2h__AOOgrC", + "task_type": "HISTORICAL_HC_ENTITY" + }, + { + "shingle_size": 8, + "rcf_total_updates": 994, + "threshold_model_trained": true, + "threshold_model_training_data_size": 0, + "model_size_in_bytes": 1593240, + "node_id": "bCtWtxWPThq0BIn5P5I4Xw", + "entity": [ + { + "name": "type", + "value": "error5" + } + ], + "task_id": "QM4HOXwBCi2h__AOOgre", + "task_type": "HISTORICAL_HC_ENTITY" + }, + { + "shingle_size": 8, + "rcf_total_updates": 994, + "threshold_model_trained": true, + "threshold_model_training_data_size": 0, + "model_size_in_bytes": 1593240, + "node_id": "bCtWtxWPThq0BIn5P5I4Xw", + "entity": [ + { + "name": "type", + "value": "error9" + } + ], + "task_id": "PM4HOXwBCi2h__AOOgp3", + "task_type": "HISTORICAL_HC_ENTITY" + }, + { + "shingle_size": 8, + "rcf_total_updates": 994, + "threshold_model_trained": true, + "threshold_model_training_data_size": 0, + "model_size_in_bytes": 1593240, + "node_id": "dIyavWhmSYWGz65b4u-lpQ", + "entity": [ + { + "name": "type", + "value": "error31" + } + ], + "task_id": "LM4HOXwBCi2h__AOOw7v", + "task_type": "HISTORICAL_HC_ENTITY" + }, + { + "shingle_size": 8, + "rcf_total_updates": 994, + "threshold_model_trained": true, + "threshold_model_training_data_size": 0, + "model_size_in_bytes": 1593240, + "node_id": "dIyavWhmSYWGz65b4u-lpQ", + "entity": [ + { + "name": "type", + "value": "error4" + } + ], + "task_id": "Kc4HOXwBCi2h__AOOw6Y", + "task_type": "HISTORICAL_HC_ENTITY" + }, + { + "shingle_size": 8, + "rcf_total_updates": 994, + "threshold_model_trained": true, + "threshold_model_training_data_size": 0, + "model_size_in_bytes": 1593240, + "node_id": "dIyavWhmSYWGz65b4u-lpQ", + "entity": [ + { + "name": "type", + "value": "error30" + } + ], + "task_id": "Lc4HOXwBCi2h__AOPA4R", + "task_type": "HISTORICAL_HC_ENTITY" + }, + { + "shingle_size": 8, + "rcf_total_updates": 994, + "threshold_model_trained": true, + "threshold_model_training_data_size": 0, + "model_size_in_bytes": 1593240, + "node_id": "dIyavWhmSYWGz65b4u-lpQ", + "entity": [ + { + "name": "type", + "value": "error8" + } + ], + "task_id": "Pc4HOXwBCi2h__AOOgqJ", + "task_type": "HISTORICAL_HC_ENTITY" + }, + { + "shingle_size": 8, + "rcf_total_updates": 994, + "threshold_model_trained": true, + "threshold_model_training_data_size": 0, + "model_size_in_bytes": 1593240, + "node_id": "2hEGbUw6ShaiKe05n_xLdA", + "entity": [ + { + "name": "type", + "value": "error3" + } + ], + "task_id": "Fs4HOXwBCi2h__AOPBLH", + "task_type": "HISTORICAL_HC_ENTITY" + }, + { + "shingle_size": 8, + "rcf_total_updates": 994, + "threshold_model_trained": true, + "threshold_model_training_data_size": 0, + "model_size_in_bytes": 1593240, + "node_id": "2hEGbUw6ShaiKe05n_xLdA", + "entity": [ + { + "name": "type", + "value": "error32" + } + ], + "task_id": "Ks4HOXwBCi2h__AOOw7D", + "task_type": "HISTORICAL_HC_ENTITY" + }, + { + "shingle_size": 8, + "rcf_total_updates": 994, + "threshold_model_trained": true, + "threshold_model_training_data_size": 0, + "model_size_in_bytes": 1593240, + "node_id": "2hEGbUw6ShaiKe05n_xLdA", + "entity": [ + { + "name": "type", + "value": "error7" + } + ], + "task_id": "Ps4HOXwBCi2h__AOOgqh", + "task_type": "HISTORICAL_HC_ENTITY" + } + ] + }, + "model_count": 32 } GET _plugins/_anomaly_detection/detectors//_profile/total_size_in_bytes @@ -2001,6 +3805,8 @@ GET _plugins/_anomaly_detection/detectors//_profile/total_size_in_by } ``` +The `model_count` parameter shows the total number of models that a detector runs in memory. This is useful if you have several models running on your cluster and want to know the count. + If you configured the category field, you can see the number of unique values in the field and all active entities with models running in memory. You can use this data to estimate how much memory is required for anomaly detection so you can decide how to size your cluster. For example, if a detector has one million entities and only 10 of them are active in memory, you need to scale your cluster up or out. @@ -2008,7 +3814,7 @@ You can use this data to estimate how much memory is required for anomaly detect #### Request ```json -GET /_plugins/_anomaly_detection/detectors//_profile?_all=true&pretty +GET _plugins/_anomaly_detection/detectors//_profile?_all=true&pretty { "state": "RUNNING", @@ -2058,6 +3864,10 @@ GET /_plugins/_anomaly_detection/detectors//_profile?_all=true&prett } ``` +The `total_entities` parameter shows you the total number of entities including the number of category fields for a detector. + +Getting the total count of entities is an expensive operation for a detector with more than one category field. By default, a real-time detector counts the number of entities up to a value of 10,000 and a historical detector counts the number of entities up to a value of 1,000. + The `profile` operation also provides information about each entity, such as the entity’s `last_sample_timestamp` and `last_active_timestamp`. If there are no anomaly results for an entity, either the entity doesn't have any sample data or its model is removed from the model cache. @@ -2067,7 +3877,20 @@ If there are no anomaly results for an entity, either the entity doesn't have an #### Request ```json -GET /_plugins/_anomaly_detection/detectors//_profile?_all=true&entity=i-00f28ec1eb8997686 +GET _plugins/_anomaly_detection/detectors//_profile?_all=true +{ + "entity": [ + { + "name": "host", + "value": "i-00f28ec1eb8997686" + } + ] +} +``` + +#### Sample Responses + +```json { "category_field": "host", "value": "i-00f28ec1eb8997686", @@ -2116,7 +3939,7 @@ GET _plugins/_anomaly_detection/detectors//_profile/ad_task "description": "test", "time_field": "timestamp", "indices": [ - "nab_art_daily_jumpsdown" + "server_log" ], "filter_query": { "match_all": { diff --git a/_monitoring-plugins/ad/index.md b/_monitoring-plugins/ad/index.md index cdd8fc89..87417e0f 100644 --- a/_monitoring-plugins/ad/index.md +++ b/_monitoring-plugins/ad/index.md @@ -73,10 +73,14 @@ Only a certain number of unique entities are supported in the category field. Us (data nodes * heap size * anomaly detection maximum memory percentage) / (entity model size of a detector) ``` +To get the entity model size of a detector, use the [profile detector API]({{site.url}}{{site.baseurl}}/monitoring-plugins/ad/api/#profile-detector). You can adjust the maximum memory percentage with the `plugins.anomaly_detection.model_max_size_percent` setting. + This formula provides a good starting point, but make sure to test with a representative workload. {: .note } -For example, for a cluster with 3 data nodes, each with 8G of JVM heap size, a maximum memory percentage of 10% (default), and the entity size of the detector as 1MB: the total number of unique entities supported is (8.096 * 10^9 * 0.1 / 1M ) * 3 = 2429. +For example, for a cluster with 3 data nodes, each with 8G of JVM heap size, a maximum memory percentage of 10% (default), and the entity model size of the detector as 1MB: the total number of unique entities supported is (8.096 * 10^9 * 0.1 / 1M ) * 3 = 2429. + +If you set the total number of unique entities higher than this number that you calculate (in this case: 2429), the anomaly detector makes its best effort to model the extra entities. The detector prioritizes entities that occur more often and are more recent. #### (Advanced settings) Set a shingle size @@ -111,7 +115,7 @@ Review your model configuration and select **Create detector**. ### Step 5: Observe the results -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. +Choose the **Real-time results** or **Historical analysis** tab. For real-time results, 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. @@ -123,7 +127,7 @@ If you see the detector pending in "initialization" for longer than a day, aggre Analyze anomalies with the following visualizations: - **Live anomalies** - displays live anomaly results for the last 60 intervals. For example, if the interval is 10, it shows results for the last 600 minutes. The chart refreshes every 30 seconds. -- **Anomaly history** - plots the anomaly grade with the corresponding measure of confidence. +- **Anomaly history** (for historical analysis) / **Anomaly overview** (for real-time results) - plots the anomaly grade with the corresponding measure of confidence. - **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. @@ -133,12 +137,13 @@ Analyze anomalies with the following visualizations: If you set the category field, you see an additional **Heat map** chart. The heat map correlates results for anomalous entities. This chart is empty until you select an anomalous entity. You also see the anomaly and feature line chart for the time period of the anomaly (`anomaly_grade` > 0). -Choose a filled rectangle to see a more detailed view of the anomaly. +Choose and drag over the anomaly line chart to zoom in and see a more detailed view of an anomaly. {: .note } + ### 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/). +Under **Real-time results**, 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/). If you stop or delete a detector, make sure to delete any monitors associated with it. @@ -147,7 +152,7 @@ If you stop or delete a detector, make sure to delete any monitors associated wi To see all the configuration settings for a detector, choose the **Detector configuration** tab. 1. To make any changes to the detector configuration, or fine tune the time interval to minimize any false positives, go to the **Detector configuration** section and choose **Edit**. -- You need to stop the detector to change its configuration. Confirm that you want to stop the detector and proceed. +- You need to stop a real-time or historical detector to change its configuration. Confirm that you want to stop the detector and proceed. 1. To enable or disable features, in the **Features** section, choose **Edit** and adjust the feature settings as needed. After you make your changes, choose **Save and start detector**. ### Step 8: Manage your detectors @@ -155,4 +160,4 @@ To see all the configuration settings for a detector, choose the **Detector conf To start, stop, or delete a detector, go to the **Detectors** page. 1. Choose the detector name. -2. Choose **Actions** and select **Start real-time detectors**, **Stop real-time detectors**, or **Delete detectors**. +2. Choose **Actions** and select **Start real-time detectors**, **Stop real-time detectors**, or **Delete detectors**. diff --git a/_monitoring-plugins/ad/settings.md b/_monitoring-plugins/ad/settings.md index 430bc5a0..8d3cc5b1 100644 --- a/_monitoring-plugins/ad/settings.md +++ b/_monitoring-plugins/ad/settings.md @@ -29,14 +29,15 @@ Setting | Default | Description `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.ad_result_history_max_docs` | 250,000,000 | 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_max_docs_per_shard` | 1,350,000,000 | The maximum number of documents in a single shard of the result index. The anomaly detection plugin only counts the refreshed documents in the primary shards. +`plugins.anomaly_detection.max_entities_per_query` | 1,000,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` | 5 | 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.max_batch_task_per_node` | 10 | 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` | 1 | 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` | 1,000 | 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. +`plugins.anomaly_detection.max_top_entities_for_historical_analysis` | 1,000 | The maximum number of top entities that you run for a high-cardinality detector historical analysis. +`plugins.anomaly_detection.max_running_entities_per_detector_for_historical_analysis` | 10 | How many entity tasks you can run in parallel for one HC detector. The cluster availble task slots will impact how many entities can run in parallel as well. For example, the cluster has 3 data nodes, each data node has 10 task slots by default. But if we have already started 2 HC detectors and each HC running 10 entities, and start a single-flow detector which takes 1 task slot, then the availabe task slots will be 10 * 3 - 10 * 2 - 1 = 9. Then, if we start a new HC detector, it can only run 9 entities in parallel, not 10. From c2f1018b3685c6ce7f41135f8b237cd08fa0ffe4 Mon Sep 17 00:00:00 2001 From: ashwinkumar12345 Date: Sun, 3 Oct 2021 10:50:46 -0700 Subject: [PATCH 104/167] incorporated feedback --- _upgrade-to/upgrade-to.md | 31 +++++++++++++++++++++++++------ 1 file changed, 25 insertions(+), 6 deletions(-) diff --git a/_upgrade-to/upgrade-to.md b/_upgrade-to/upgrade-to.md index 0d554370..cd403f7e 100644 --- a/_upgrade-to/upgrade-to.md +++ b/_upgrade-to/upgrade-to.md @@ -221,18 +221,37 @@ Check [Upgrade paths]({{site.url}}{{site.baseurl}}/upgrade-to/upgrade-to/#upgrad 1. Make sure the following environment variables are set: - `ES_HOME` - Path to the existing Elasticsearch installation home. + + ```bash + export ES_HOME = /home/workspace/upgrade-demo/node1/elasticsearch-7.10.2 + ``` + - `ES_PATH_CONF` - Path to the existing Elasticsearch config directory. + + ```bash + export ES_PATH_CONF = /home/workspace/upgrade-demo/node1/os-config + ``` + - `OPENSEARCH_HOME` - Path to the OpenSearch installation home. + + ```bash + export OPENSEARCH_HOME = /home/workspace/upgrade-demo/node1/opensearch-1.0.0 + ``` + - `OPENSEARCH_PATH_CONF` - Path to the OpenSearch config directory. + ```bash + export OPENSEARCH_PATH_CONF = /home/workspace/upgrade-demo/node1/opensearch-config + ``` + 1. The `opensearch-upgrade` tool is in the `bin` directory of the distribution. Run the following command from the distribution home: - Make sure you run this tool as the same user running the current Elasticsearch service. - {: .note } + Make sure you run this tool as the same user running the current Elasticsearch service. + {: .note } - ```json - ./bin/opensearch-upgrade - ``` + ```json + ./bin/opensearch-upgrade + ``` 1. Stop Elasticsearch OSS on the node. @@ -270,6 +289,6 @@ Behind the scenes, the `opensearch-upgrade` tool performs the following tasks in 1. Looks for a valid Elasticsearch installation on the current node. After it finds the installation, it reads the `elasticsearch.yml` file to get the endpoint details and connects to the locally running Elasticsearch service. If the tool can't find an Elasticsearch installation, it tries to get the path from the `ES_HOME` location. 1. Verifies if the existing version of Elasticsearch is compatible with the OpenSearch version. It prints a summary of the information gathered to the console and prompts you for a confirmation to proceed. 1. Imports the settings from the `elasticsearch.yml` config file into the `opensearch.yml` config file. -1. Copies across any custom JVM options from the `$ES_PATH_CONF/jvm.options.d` directory into the `$OPENSEARCH_PATH_CONF/jvm.options.d` directory . Similarly, it also imports the logging configurations from the `$ES_PATH_CONF/log4j2.properties` file into the `$OPENSEARCH_PATH_CONF/log4j2.properties` file. +1. Copies across any custom JVM options from the `$ES_PATH_CONF/jvm.options.d` directory into the `$OPENSEARCH_PATH_CONF/jvm.options.d` directory. Similarly, it also imports the logging configurations from the `$ES_PATH_CONF/log4j2.properties` file into the `$OPENSEARCH_PATH_CONF/log4j2.properties` file. 1. Installs the core plugins that you’ve currently installed in the `$ES_HOME/plugins` directory. You must install all other third-party community plugins manually. 1. Imports the secure settings from the `elasticsearch.keystore` file (if any) into the `opensearch.keystore` file. If the keystore file is password protected, the `opensearch-upgrade` tool prompts you to enter the password. From 370ff0fc57475e4cd255039efffef90f8afbf2c4 Mon Sep 17 00:00:00 2001 From: ashwinkumar12345 Date: Sun, 3 Oct 2021 10:57:58 -0700 Subject: [PATCH 105/167] spacing --- _upgrade-to/upgrade-to.md | 20 ++++++++++---------- 1 file changed, 10 insertions(+), 10 deletions(-) diff --git a/_upgrade-to/upgrade-to.md b/_upgrade-to/upgrade-to.md index cd403f7e..b21ec89c 100644 --- a/_upgrade-to/upgrade-to.md +++ b/_upgrade-to/upgrade-to.md @@ -265,22 +265,22 @@ Check [Upgrade paths]({{site.url}}{{site.baseurl}}/upgrade-to/upgrade-to/#upgrad 1. Start OpenSearch on the node: - ```json - ./bin/opensearch -d. - ``` + ```json + ./bin/opensearch -d. + ``` 1. Repeat steps 2--6 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" - } + ```json + PUT _cluster/settings + { + "persistent": { + "cluster.routing.allocation.enable": "all" } - ``` + } + ``` ### How it works From 19fb0d0948ac3c7960c8bf7540419b13484e2b39 Mon Sep 17 00:00:00 2001 From: Omurbek Date: Mon, 4 Oct 2021 12:30:23 +0300 Subject: [PATCH 106/167] Update policies.md --- _im-plugin/ism/policies.md | 8 +------- 1 file changed, 1 insertion(+), 7 deletions(-) diff --git a/_im-plugin/ism/policies.md b/_im-plugin/ism/policies.md index afad9396..29ac228b 100644 --- a/_im-plugin/ism/policies.md +++ b/_im-plugin/ism/policies.md @@ -560,7 +560,7 @@ The following sample template policy is for a rollover use case. "index_patterns": ["log*"], "template": { "settings": { - "opendistro.index_state_management.rollover_alias": "log" + "plugins.index_state_management.rollover_alias": "log" } } } @@ -588,12 +588,6 @@ The following sample template policy is for a rollover use case. } ``` -5. Verify if the policy is attached to the `log-000001` index: - - ```json - GET _opendistro/_ism/explain/log-000001?pretty - ``` - ## Example policy The following example policy implements a `hot`, `warm`, and `delete` workflow. You can use this policy as a template to prioritize resources to your indices based on their levels of activity. From 164ead7dbd88dea24b6753307ed85ecfca93a3ea Mon Sep 17 00:00:00 2001 From: Omurbek Date: Mon, 4 Oct 2021 12:39:06 +0300 Subject: [PATCH 107/167] Update policies.md --- _im-plugin/ism/policies.md | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/_im-plugin/ism/policies.md b/_im-plugin/ism/policies.md index 29ac228b..cc09eab1 100644 --- a/_im-plugin/ism/policies.md +++ b/_im-plugin/ism/policies.md @@ -588,6 +588,12 @@ The following sample template policy is for a rollover use case. } ``` +5. Verify if the policy is attached to the `log-000001` index: + + ```json + GET _plugins/_ism/explain/log-000001?pretty + ``` + ## Example policy The following example policy implements a `hot`, `warm`, and `delete` workflow. You can use this policy as a template to prioritize resources to your indices based on their levels of activity. From a3a1795ab5ff183067f9c1c34d599fbc1521b8b4 Mon Sep 17 00:00:00 2001 From: Maarten-Jan <31125767+maartenjanvangool@users.noreply.github.com> Date: Mon, 4 Oct 2021 17:00:43 +0200 Subject: [PATCH 108/167] Update java-rest-high-level.md The file has a compile error, I think ); is missing --- _clients/java-rest-high-level.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/_clients/java-rest-high-level.md b/_clients/java-rest-high-level.md index 892f7341..314725f4 100644 --- a/_clients/java-rest-high-level.md +++ b/_clients/java-rest-high-level.md @@ -93,7 +93,7 @@ public class RESTClientSample { HashMap mapping = new HashMap(); mapping.put("properties", ageMapping); createIndexRequest.mapping(mapping); - CreateIndexResponse createIndexResponse = client.indices().create(createIndexRequest, RequestOptions.DEFAULT + 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. From 790459778cafd87ea854f5b1c96e855acfb914f3 Mon Sep 17 00:00:00 2001 From: keithhc2 Date: Mon, 4 Oct 2021 10:03:32 -0700 Subject: [PATCH 109/167] A comma --- _im-plugin/ism/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/_im-plugin/ism/index.md b/_im-plugin/ism/index.md index 0104dc68..4202b849 100644 --- a/_im-plugin/ism/index.md +++ b/_im-plugin/ism/index.md @@ -31,7 +31,7 @@ To get started, choose **Index Management** in OpenSearch Dashboards. 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/). -You can use the JSON editor or visual editor to create policies. Compared to the JSON editor, the visual editor offers a more structured way of defining policies by separating the process into creating error notifications, defining ISM templates, and adding states. We recommend using the visual editor if you want to see pre-defined fields such as which actions you can assign to a state or under what conditions a state can transition into a destination state. +You can use the JSON editor or visual editor to create policies. Compared to the JSON editor, the visual editor offers a more structured way of defining policies by separating the process into creating error notifications, defining ISM templates, and adding states. We recommend using the visual editor if you want to see pre-defined fields, such as which actions you can assign to a state or under what conditions a state can transition into a destination state. #### JSON editor From e6403d89a40eff7436a800288b0887b53e2fe25e Mon Sep 17 00:00:00 2001 From: ashwinkumar12345 Date: Mon, 4 Oct 2021 12:08:00 -0700 Subject: [PATCH 110/167] ad changes for 1.1 --- _monitoring-plugins/ad/api.md | 1807 ++++++++++------------------ _monitoring-plugins/ad/index.md | 13 +- _monitoring-plugins/ad/settings.md | 23 +- 3 files changed, 657 insertions(+), 1186 deletions(-) diff --git a/_monitoring-plugins/ad/api.md b/_monitoring-plugins/ad/api.md index 2a8427e3..e3db5aac 100644 --- a/_monitoring-plugins/ad/api.md +++ b/_monitoring-plugins/ad/api.md @@ -24,7 +24,7 @@ Introduced 1.0 Creates an anomaly detector. -This command creates a detector named `http_requests` that finds anomalies based on the sum and average number of failed HTTP requests: +This command creates a detector named `test-detector` that finds anomalies based on the sum of the `value` field: #### Request @@ -266,7 +266,6 @@ Passes a date range to the anomaly detector to return any anomalies within that ```json POST _plugins/_anomaly_detection/detectors/_preview - { "period_start": 1612982516000, "period_end": 1614278539000, @@ -426,7 +425,6 @@ If you specify a category field, each result is associated with an entity: ] } ... - ``` Or, you can specify the detector ID: @@ -434,9 +432,9 @@ Or, you can specify the detector ID: ```json POST _plugins/_anomaly_detection/detectors/_preview { - "detector_id": "sYkUvHcBiZv51f-Lv8QN", - "period_start": 1612982516000, - "period_end": 1614278539000 + "detector_id": "sYkUvHcBiZv51f-Lv8QN", + "period_start": 1612982516000, + "period_end": 1614278539000 } ``` @@ -471,8 +469,8 @@ To start historical analysis: ```json POST _plugins/_anomaly_detection/detectors//_start { - "start_time": 1503168590000, - "end_time": 1617301324000 + "start_time": 1503168590000, + "end_time": 1617301324000 } ``` @@ -498,10 +496,11 @@ Stopped detector: m4ccEnIBTXsGi3mvMt9p To stop historical analysis: -```jsom +```json POST _plugins/_anomaly_detection/detectors//_stop?historical=true ``` + --- ## Search detector result @@ -515,7 +514,6 @@ Returns all results for a search query. ```json GET _plugins/_anomaly_detection/detectors/results/_search POST _plugins/_anomaly_detection/detectors/results/_search - { "query": { "bool": { @@ -552,7 +550,7 @@ POST _plugins/_anomaly_detection/detectors/results/_search "max_score": 1, "hits": [ { - "_index": ".opendistro-anomaly-results-history-2020.04.30-1", + "_index": ".opensearch-anomaly-results-history-2020.04.30-1", "_type": "_doc", "_id": "_KBrzXEBbpoKkFM5mStm", "_version": 1, @@ -578,7 +576,7 @@ POST _plugins/_anomaly_detection/detectors/results/_search } }, { - "_index": ".opendistro-anomaly-results-history-2020.04.30-1", + "_index": ".opensearch-anomaly-results-history-2020.04.30-1", "_type": "_doc", "_id": "EqB1zXEBbpoKkFM5qyyE", "_version": 1, @@ -683,7 +681,7 @@ POST _plugins/_anomaly_detection/detectors/results/_search "max_score": null, "hits": [ { - "_index": ".opendistro-anomaly-results-history-2020.11.07-1", + "_index": ".opensearch-anomaly-results-history-2020.11.07-1", "_type": "_doc", "_id": "BiItoHUBTpMGN-4KARY5", "_version": 1, @@ -719,7 +717,7 @@ POST _plugins/_anomaly_detection/detectors/results/_search ] }, { - "_index": ".opendistro-anomaly-results-history-2020.11.07-1", + "_index": ".opensearch-anomaly-results-history-2020.11.07-1", "_type": "_doc", "_id": "wiImoHUBTpMGN-4KlhXs", "_version": 1, @@ -755,7 +753,7 @@ POST _plugins/_anomaly_detection/detectors/results/_search ] }, { - "_index": ".opendistro-anomaly-results-history-2020.11.07-1", + "_index": ".opensearch-anomaly-results-history-2020.11.07-1", "_type": "_doc", "_id": "ZiIcoHUBTpMGN-4KhhVA", "_version": 1, @@ -832,7 +830,7 @@ GET _plugins/_anomaly_detection/detectors/results/_search "max_score": 2.1366, "hits": [ { - "_index": ".opendistro-anomaly-detection-state", + "_index": ".opensearch-anomaly-detection-state", "_type": "_doc", "_id": "CoM8WncBtt2qvI-LZO7_", "_version": 8, @@ -943,10 +941,10 @@ You can specify the following options. Options | Description | Type | Required :--- | :--- |:--- |:--- | -`anomalyThreshold` | Filter out low anomaly grade results. Default is -1. The lowest possible anomaly grade is 0. -1 means that the detector returns all results. | `float` | No -`dateRangeFilter` | Specify the date range in:
- `startTime` (int): Start time to collect results. Recorded in milliseconds since the Unix Epoch.
- `endTime` (int): End time to collect results. Recorded in milliseconds since the Unix Epoch.
- `fieldName` (string): The field that you want to match the start and end time. | `object` | Yes -`entity` | If not empty, the parameter contains the entity name and value. Default is empty.
- `name` (string): Field name that you want to search in.
- `value` (string): Entity value that you want to search for. | `object` | No -`sort` | If not empty, sorts the result by a field in a certain order. Default is empty. Properties of `sort`:
- `direction` (string): Specify "desc" or "asc" for descending or ascending order.
- `field` (string): Order the results by a field. | `object` | No +`anomalyThreshold` | Specify a threshold to filter out low anomaly grade results. Default is -1. Because the lowest possible anomaly grade is 0, -1 means that the detector returns all results. | `float` | No +`dateRangeFilter` | Specify the date range in:
- `startTime` (int): Start time to collect results. Add in milliseconds since the Unix Epoch.
- `endTime` (int): End time to collect results. Add in milliseconds since the Unix Epoch.
- `fieldName` (string): The field that you want to match the start and end time. | `object` | Yes +`entity` | Specify the entity name and value. Default is empty.
- `name` (string): Field name that you want to search in.
- `value` (string): Entity value that you want to search for. | `object` | No +`sort` | Sort the result by a field in a certain order. Default is empty. Properties of `sort`:
- `direction` (string): Specify "desc" or "asc" for descending or ascending order.
- `field` (string): Order the results by a field. | `object` | No --- @@ -996,127 +994,127 @@ POST _plugins/_anomaly_detection/detectors/tasks/_search ```json { - "took" : 5, - "timed_out" : false, - "_shards" : { - "total" : 1, - "successful" : 1, - "skipped" : 0, - "failed" : 0 + "took": 5, + "timed_out": false, + "_shards": { + "total": 1, + "successful": 1, + "skipped": 0, + "failed": 0 }, - "hits" : { - "total" : { - "value" : 1, - "relation" : "eq" + "hits": { + "total": { + "value": 1, + "relation": "eq" }, - "max_score" : null, - "hits" : [ + "max_score": null, + "hits": [ { - "_index" : ".opendistro-anomaly-detection-state", - "_type" : "_doc", - "_id" : "TM3tOHwBCi2h__AOXlyQ", - "_version" : 3, - "_seq_no" : 14, - "_primary_term" : 1, - "_score" : null, - "_source" : { - "detector_id" : "rlDtOHwBD5tpxlbyW7Nt", - "error" : "", - "detection_date_range" : { - "start_time" : 1632437852100, - "end_time" : 1633042652100 + "_index": ".opensearch-anomaly-detection-state", + "_type": "_doc", + "_id": "TM3tOHwBCi2h__AOXlyQ", + "_version": 3, + "_seq_no": 14, + "_primary_term": 1, + "_score": null, + "_source": { + "detector_id": "rlDtOHwBD5tpxlbyW7Nt", + "error": "", + "detection_date_range": { + "start_time": 1632437852100, + "end_time": 1633042652100 }, - "task_progress" : 0.5, - "last_update_time" : 1633042667358, - "execution_start_time" : 1633042652810, - "state" : "RUNNING", - "coordinating_node" : "2hEGbUw6ShaiKe05n_xLdA", - "task_type" : "HISTORICAL_HC_DETECTOR", - "started_by" : "admin", - "init_progress" : 0.0, - "is_latest" : true, - "detector" : { - "category_field" : [ + "task_progress": 0.5, + "last_update_time": 1633042667358, + "execution_start_time": 1633042652810, + "state": "RUNNING", + "coordinating_node": "2hEGbUw6ShaiKe05n_xLdA", + "task_type": "HISTORICAL_HC_DETECTOR", + "started_by": "admin", + "init_progress": 0, + "is_latest": true, + "detector": { + "category_field": [ "type" ], - "description" : "test", - "ui_metadata" : { - "features" : { - "test-feature" : { - "aggregationBy" : "sum", - "aggregationOf" : "value", - "featureType" : "simple_aggs" + "description": "test", + "ui_metadata": { + "features": { + "test-feature": { + "aggregationBy": "sum", + "aggregationOf": "value", + "featureType": "simple_aggs" } }, - "filters" : [ ] + "filters": [] }, - "feature_attributes" : [ + "feature_attributes": [ { - "feature_id" : "7VDtOHwBD5tpxlbyWqPs", - "feature_enabled" : true, - "feature_name" : "test-feature", - "aggregation_query" : { - "test_feature" : { - "sum" : { - "field" : "value" + "feature_id": "7VDtOHwBD5tpxlbyWqPs", + "feature_enabled": true, + "feature_name": "test-feature", + "aggregation_query": { + "test_feature": { + "sum": { + "field": "value" } } } } ], - "schema_version" : 0, - "time_field" : "timestamp", - "last_update_time" : 1633042652012, - "indices" : [ + "schema_version": 0, + "time_field": "timestamp", + "last_update_time": 1633042652012, + "indices": [ "server_log" ], - "window_delay" : { - "period" : { - "unit" : "Minutes", - "interval" : 1 + "window_delay": { + "period": { + "unit": "Minutes", + "interval": 1 } }, - "detection_interval" : { - "period" : { - "unit" : "Minutes", - "interval" : 5 + "detection_interval": { + "period": { + "unit": "Minutes", + "interval": 5 } }, - "name" : "test-detector", - "filter_query" : { - "match_all" : { - "boost" : 1.0 + "name": "test-detector", + "filter_query": { + "match_all": { + "boost": 1 } }, - "shingle_size" : 8, - "user" : { - "backend_roles" : [ + "shingle_size": 8, + "user": { + "backend_roles": [ "admin" ], - "custom_attribute_names" : [ ], - "roles" : [ + "custom_attribute_names": [], + "roles": [ "own_index", "all_access" ], - "name" : "admin", - "user_requested_tenant" : null + "name": "admin", + "user_requested_tenant": null }, - "detector_type" : "MULTI_ENTITY" + "detector_type": "MULTI_ENTITY" }, - "user" : { - "backend_roles" : [ + "user": { + "backend_roles": [ "admin" ], - "custom_attribute_names" : [ ], - "roles" : [ + "custom_attribute_names": [], + "roles": [ "own_index", "all_access" ], - "name" : "admin", - "user_requested_tenant" : "__user__" + "name": "admin", + "user_requested_tenant": "__user__" } }, - "sort" : [ + "sort": [ 1633042652810 ] } @@ -1146,19 +1144,19 @@ DELETE _plugins/_anomaly_detection/detectors/ ```json { - "_index" : ".opendistro-anomaly-detectors", - "_type" : "_doc", - "_id" : "m4ccEnIBTXsGi3mvMt9p", - "_version" : 2, - "result" : "deleted", - "forced_refresh" : true, - "_shards" : { - "total" : 2, - "successful" : 2, - "failed" : 0 + "_index": ".opensearch-anomaly-detectors", + "_type": "_doc", + "_id": "m4ccEnIBTXsGi3mvMt9p", + "_version": 2, + "result": "deleted", + "forced_refresh": true, + "_shards": { + "total": 2, + "successful": 2, + "failed": 0 }, - "_seq_no" : 6, - "_primary_term" : 1 + "_seq_no": 6, + "_primary_term": 1 } ``` @@ -1168,13 +1166,12 @@ DELETE _plugins/_anomaly_detection/detectors/ Introduced 1.1 {: .label .label-purple } -Deletes a detector results based on a query. +Deletes the results of a detector based on a query. #### Request ```json DELETE _plugins/_anomaly_detection/detectors/results - { "query": { "bool": { @@ -1211,23 +1208,23 @@ DELETE _plugins/_anomaly_detection/detectors/results ```json { - "took" : 48, - "timed_out" : false, - "total" : 28, - "updated" : 0, - "created" : 0, - "deleted" : 28, - "batches" : 1, - "version_conflicts" : 0, - "noops" : 0, - "retries" : { - "bulk" : 0, - "search" : 0 + "took": 48, + "timed_out": false, + "total": 28, + "updated": 0, + "created": 0, + "deleted": 28, + "batches": 1, + "version_conflicts": 0, + "noops": 0, + "retries": { + "bulk": 0, + "search": 0 }, - "throttled_millis" : 0, - "requests_per_second" : -1.0, - "throttled_until_millis" : 0, - "failures" : [ ] + "throttled_millis": 0, + "requests_per_second": -1, + "throttled_until_millis": 0, + "failures": [] } ``` @@ -1237,7 +1234,7 @@ DELETE _plugins/_anomaly_detection/detectors/results Introduced 1.1 {: .label .label-purple } -Validates detector before creating. This API shows you any invalid fields in your configuration and also recommendations on how to fix it. +Validates detector before creating. Lists any invalid fields in your configuration and recommends ways to fix these invalid fields. #### Request @@ -1312,8 +1309,7 @@ POST _plugins/_anomaly_detection/detectors/_validate/detector,model "message": "should be set|not_exist|empty" }, "feature_attributes": { - // exist when message is "there exists non-numeric field" - [Optional]"problematic_feature_name1": { + "problematic_feature_name1": { "message": "{field} is invalid with {exceptionMessage}" } "problematic_feature_name2": { @@ -1336,8 +1332,7 @@ POST _plugins/_anomaly_detection/detectors/_validate/detector,model "message": "data is too sparse after filter_query is applied" }, "detection_interval": { - // exists when suggested value can be found - [Optional]"suggested_value": { + "suggested_value": { "period": { "interval": 1, "unit": "Minutes" @@ -1361,8 +1356,7 @@ POST _plugins/_anomaly_detection/detectors/_validate/detector,model "message": "model size exceeds memory limit, please stop/delete unused detectors, or reduce shingle size or number of features" }, "window_delay": { - // exists when suggested value can be found - [Optional]"suggested_value": { + "suggested_value": { "period": { "interval": 1, "unit": "Minutes" @@ -1372,7 +1366,6 @@ POST _plugins/_anomaly_detection/detectors/_validate/detector,model } } } - ``` --- @@ -1586,133 +1579,133 @@ GET _plugins/_anomaly_detection/detectors/?job=true ```json { - "_id": "LJxGsXcBoDQA8W1Q--A1", - "_version": 1, - "_primary_term": 1, - "_seq_no": 0, - "anomaly_detector": { - "name": "test2", - "description": "test", - "time_field": "timestamp", - "indices": [ - "server_log" - ], - "filter_query": { - "match_all": { - "boost": 1.0 - } - }, - "detection_interval": { - "period": { - "interval": 1, - "unit": "Minutes" - } - }, - "window_delay": { - "period": { - "interval": 1, - "unit": "Minutes" - } - }, - "shingle_size": 8, - "schema_version": 0, - "feature_attributes": [ - { - "feature_id": "K5xGsXcBoDQA8W1Q-uCF", - "feature_name": "F1", - "feature_enabled": *true*, - "aggregation_query": { - "f_1": { - "sum": { - "field": "value" - } - } - } - } - ], - "last_update_time": 1613586955060, - "detector_type": "MULTI_ENTITY" + "_id": "LJxGsXcBoDQA8W1Q--A1", + "_version": 1, + "_primary_term": 1, + "_seq_no": 0, + "anomaly_detector": { + "name": "test2", + "description": "test", + "time_field": "timestamp", + "indices": [ + "server_log" + ], + "filter_query": { + "match_all": { + "boost": 1 + } }, - "anomaly_detector_job": { - "name": "LJxGsXcBoDQA8W1Q--A1", - "schedule": { - "interval": { - "start_time": 1613587220387, - "period": 1, - "unit": "Minutes" - } - }, - "window_delay": { - "period": { - "interval": 1, - "unit": "Minutes" - } - }, - "enabled": *false*, - "enabled_time": 1613587220387, - "last_update_time": 1613587289169, - "lock_duration_seconds": 60, - "disabled_time": 1613587289169 + "detection_interval": { + "period": { + "interval": 1, + "unit": "Minutes" + } }, - "anomaly_detection_task": { - "task_id": "WZ5LsXcBoDQA8W1QmUa3", - "last_update_time": 1613587349022, - "error": "Task cancelled by user", - "state": "STOPPED", - "detector_id": "LJxGsXcBoDQA8W1Q--A1", - "task_progress": 0.26321793, - "init_progress": 1.0, - "current_piece": 1611030900000, - "execution_start_time": 1613587257783, - "execution_end_time": 1613587349022, - "is_latest": *true*, - "task_type": "HISTORICAL", - "coordinating_node": "NSw5j-3YQeGkH8KESVKlzw", - "worker_node": "NSw5j-3YQeGkH8KESVKlzw", - "detector": { - "name": "test2", - "description": "test", - "time_field": "timestamp", - "indices": [ - "server_log" - ], - "filter_query": { - "match_all": { - "boost": 1.0 - } - }, - "detection_interval": { - "period": { - "interval": 1, - "unit": "Minutes" - } - }, - "window_delay": { - "period": { - "interval": 1, - "unit": "Minutes" - } - }, - "shingle_size": 8, - "schema_version": 0, - "feature_attributes": [ - { - "feature_id": "K5xGsXcBoDQA8W1Q-uCF", - "feature_name": "F1", - "feature_enabled": *true*, - "aggregation_query": { - "f_1": { - "sum": { - "field": "value" - } - } - } - } - ], - "last_update_time": 1613586955060, - "detector_type": "MULTI_ENTITY" + "window_delay": { + "period": { + "interval": 1, + "unit": "Minutes" + } + }, + "shingle_size": 8, + "schema_version": 0, + "feature_attributes": [ + { + "feature_id": "K5xGsXcBoDQA8W1Q-uCF", + "feature_name": "F1", + "feature_enabled": "true", + "aggregation_query": { + "f_1": { + "sum": { + "field": "value" + } + } } + } + ], + "last_update_time": 1613586955060, + "detector_type": "MULTI_ENTITY" + }, + "anomaly_detector_job": { + "name": "LJxGsXcBoDQA8W1Q--A1", + "schedule": { + "interval": { + "start_time": 1613587220387, + "period": 1, + "unit": "Minutes" + } + }, + "window_delay": { + "period": { + "interval": 1, + "unit": "Minutes" + } + }, + "enabled": "false", + "enabled_time": 1613587220387, + "last_update_time": 1613587289169, + "lock_duration_seconds": 60, + "disabled_time": 1613587289169 + }, + "anomaly_detection_task": { + "task_id": "WZ5LsXcBoDQA8W1QmUa3", + "last_update_time": 1613587349022, + "error": "Task cancelled by user", + "state": "STOPPED", + "detector_id": "LJxGsXcBoDQA8W1Q--A1", + "task_progress": 0.26321793, + "init_progress": 1, + "current_piece": 1611030900000, + "execution_start_time": 1613587257783, + "execution_end_time": 1613587349022, + "is_latest": "true", + "task_type": "HISTORICAL", + "coordinating_node": "NSw5j-3YQeGkH8KESVKlzw", + "worker_node": "NSw5j-3YQeGkH8KESVKlzw", + "detector": { + "name": "test2", + "description": "test", + "time_field": "timestamp", + "indices": [ + "server_log" + ], + "filter_query": { + "match_all": { + "boost": 1 + } + }, + "detection_interval": { + "period": { + "interval": 1, + "unit": "Minutes" + } + }, + "window_delay": { + "period": { + "interval": 1, + "unit": "Minutes" + } + }, + "shingle_size": 8, + "schema_version": 0, + "feature_attributes": [ + { + "feature_id": "K5xGsXcBoDQA8W1Q-uCF", + "feature_name": "F1", + "feature_enabled": "true", + "aggregation_query": { + "f_1": { + "sum": { + "field": "value" + } + } + } + } + ], + "last_update_time": 1613586955060, + "detector_type": "MULTI_ENTITY" } + } } ``` @@ -1912,9 +1905,6 @@ Returns all anomaly detectors for a search query. ```json GET _plugins/_anomaly_detection/detectors/_search POST _plugins/_anomaly_detection/detectors/_search - -Sample Input: - { "query": { "bool": { @@ -1936,70 +1926,62 @@ Sample Input: ```json { - "took": 13, + "took": 2, "timed_out": false, "_shards": { - "total": 5, - "successful": 5, + "total": 1, + "successful": 1, "skipped": 0, "failed": 0 }, "hits": { "total": { - "value": 994, + "value": 1, "relation": "eq" }, - "max_score": 3.5410638, + "max_score": 0, "hits": [ { - "_index": ".opendistro-anomaly-detectors", + "_index": ".opensearch-anomaly-detectors", "_type": "_doc", - "_id": "m4ccEnIBTXsGi3mvMt9p", - "_version": 2, - "_seq_no": 221, + "_id": "rlDtOHwBD5tpxlbyW7Nt", + "_version": 1, + "_seq_no": 0, "_primary_term": 1, - "_score": 3.5410638, + "_score": 0, "_source": { "name": "test-detector", - "description": "Test detector", + "description": "test", "time_field": "timestamp", "indices": [ - "order*" + "server_log" ], "filter_query": { - "bool": { - "filter": [ - { - "exists": { - "field": "value", - "boost": 1 - } - } - ], - "adjust_pure_negative": true, + "match_all": { "boost": 1 } }, "detection_interval": { "period": { - "interval": 10, - "unit": "MINUTES" + "interval": 5, + "unit": "Minutes" } }, "window_delay": { "period": { "interval": 1, - "unit": "MINUTES" + "unit": "Minutes" } }, + "shingle_size": 8, "schema_version": 0, "feature_attributes": [ { - "feature_id": "xxokEnIBcpeWMD987A1X", - "feature_name": "total_order", + "feature_id": "7VDtOHwBD5tpxlbyWqPs", + "feature_name": "test-feature", "feature_enabled": true, "aggregation_query": { - "total_order": { + "test_feature": { "sum": { "field": "value" } @@ -2007,7 +1989,23 @@ Sample Input: } } ], - "last_update_time": 1589442309241 + "last_update_time": 1633042652012, + "category_field": [ + "type" + ], + "user": { + "name": "admin", + "backend_roles": [ + "admin" + ], + "roles": [ + "own_index", + "all_access" + ], + "custom_attribute_names": [], + "user_requested_tenant": null + }, + "detector_type": "MULTI_ENTITY" } } ] @@ -2065,261 +2063,6 @@ GET _plugins/_anomaly_detection/stats/ } ] }, - { - "detector_id": "mmZFeXsB7JcKN0mdnMf4", - "model_type": "entity", - "last_used_time": 1629827578975, - "model_id": "mmZFeXsB7JcKN0mdnMf4_entity_k2gq2eRP0vTV2LNNyFdIqg", - "last_checkpoint_time": 1629827339733, - "entity": [ - { - "name": "host", - "value": "server_1" - }, - { - "name": "service", - "value": "app_0" - } - ] - }, - { - "detector_id": "mmZFeXsB7JcKN0mdnMf4", - "model_type": "entity", - "last_used_time": 1629827578980, - "model_id": "mmZFeXsB7JcKN0mdnMf4_entity_DOze7d0HnK3K54g3Emk1XA", - "last_checkpoint_time": 1629827343186, - "entity": [ - { - "name": "host", - "value": "server_2" - }, - { - "name": "service", - "value": "app_3" - } - ] - }, - { - "detector_id": "mmZFeXsB7JcKN0mdnMf4", - "model_type": "entity", - "last_used_time": 1629827578977, - "model_id": "mmZFeXsB7JcKN0mdnMf4_entity_NgGmglQvOMQQciDdPxN_Ig", - "last_checkpoint_time": 1629827340961, - "entity": [ - { - "name": "host", - "value": "server_3" - }, - { - "name": "service", - "value": "app_5" - } - ] - }, - { - "detector_id": "mmZFeXsB7JcKN0mdnMf4", - "model_type": "entity", - "last_used_time": 1629827578977, - "model_id": "mmZFeXsB7JcKN0mdnMf4_entity_oTdcenY1L5bqa6chUxg7xw", - "last_checkpoint_time": 1629827340263, - "entity": [ - { - "name": "host", - "value": "server_1" - }, - { - "name": "service", - "value": "app_1" - } - ] - }, - { - "detector_id": "mmZFeXsB7JcKN0mdnMf4", - "model_type": "entity", - "last_used_time": 1629827578979, - "model_id": "mmZFeXsB7JcKN0mdnMf4_entity_zxSqAWv5Iz19v-Hnqhrwrw", - "last_checkpoint_time": 1629827342814, - "entity": [ - { - "name": "host", - "value": "server_1" - }, - { - "name": "service", - "value": "app_5" - } - ] - }, - { - "detector_id": "mmZFeXsB7JcKN0mdnMf4", - "model_type": "entity", - "last_used_time": 1629827578976, - "model_id": "mmZFeXsB7JcKN0mdnMf4_entity_Yu8X2rA39lhjYzqebjLxhQ", - "last_checkpoint_time": 1629827339992, - "entity": [ - { - "name": "host", - "value": "server_2" - }, - { - "name": "service", - "value": "app_1" - } - ] - }, - { - "detector_id": "mmZFeXsB7JcKN0mdnMf4", - "model_type": "entity", - "last_used_time": 1629827578978, - "model_id": "mmZFeXsB7JcKN0mdnMf4_entity_6SvF11RCqf7HYbY56BnFKA", - "last_checkpoint_time": 1629827341806, - "entity": [ - { - "name": "host", - "value": "server_3" - }, - { - "name": "service", - "value": "app_2" - } - ] - }, - { - "detector_id": "mmZFeXsB7JcKN0mdnMf4", - "model_type": "entity", - "last_used_time": 1629827578980, - "model_id": "mmZFeXsB7JcKN0mdnMf4_entity_3S8k6q_DLFhw3hboko3dfw", - "last_checkpoint_time": 1629827343371, - "entity": [ - { - "name": "host", - "value": "server_1" - }, - { - "name": "service", - "value": "app_3" - } - ] - }, - { - "detector_id": "mmZFeXsB7JcKN0mdnMf4", - "model_type": "entity", - "last_used_time": 1629827578978, - "model_id": "mmZFeXsB7JcKN0mdnMf4_entity_0uafBokvEYuncGbjP3D2qA", - "last_checkpoint_time": 1629827342302, - "entity": [ - { - "name": "host", - "value": "server_2" - }, - { - "name": "service", - "value": "app_5" - } - ] - }, - { - "detector_id": "mmZFeXsB7JcKN0mdnMf4", - "model_type": "entity", - "last_used_time": 1629827578977, - "model_id": "mmZFeXsB7JcKN0mdnMf4_entity_93DEK2PooWlHF6gkh-0hIA", - "last_checkpoint_time": 1629827340727, - "entity": [ - { - "name": "host", - "value": "server_2" - }, - { - "name": "service", - "value": "app_4" - } - ] - }, - { - "detector_id": "mmZFeXsB7JcKN0mdnMf4", - "model_type": "entity", - "last_used_time": 1629827578975, - "model_id": "mmZFeXsB7JcKN0mdnMf4_entity_FuqXh0HBXlPhKepOc6JADQ", - "last_checkpoint_time": 1629827338908, - "entity": [ - { - "name": "host", - "value": "server_3" - }, - { - "name": "service", - "value": "app_6" - } - ] - }, - { - "detector_id": "mmZFeXsB7JcKN0mdnMf4", - "model_type": "entity", - "last_used_time": 1629827578979, - "model_id": "mmZFeXsB7JcKN0mdnMf4_entity_B4zrbSQ1-pvdBLx0FzQxvw", - "last_checkpoint_time": 1629827342611, - "entity": [ - { - "name": "host", - "value": "server_3" - }, - { - "name": "service", - "value": "app_3" - } - ] - }, - { - "detector_id": "mmZFeXsB7JcKN0mdnMf4", - "model_type": "entity", - "last_used_time": 1629827578978, - "model_id": "mmZFeXsB7JcKN0mdnMf4_entity_xm_gKBMKlgymKcoqZyXT8A", - "last_checkpoint_time": 1629827341365, - "entity": [ - { - "name": "host", - "value": "server_2" - }, - { - "name": "service", - "value": "app_0" - } - ] - }, - { - "detector_id": "mmZFeXsB7JcKN0mdnMf4", - "model_type": "entity", - "last_used_time": 1629827578978, - "model_id": "mmZFeXsB7JcKN0mdnMf4_entity_OnZ4CP-yJF5llO57gUjM6w", - "last_checkpoint_time": 1629827341599, - "entity": [ - { - "name": "host", - "value": "server_3" - }, - { - "name": "service", - "value": "app_1" - } - ] - }, - { - "detector_id": "mmZFeXsB7JcKN0mdnMf4", - "model_type": "entity", - "last_used_time": 1629827578977, - "model_id": "mmZFeXsB7JcKN0mdnMf4_entity_E_uWreoeJpGrAMMaitg8BA", - "last_checkpoint_time": 1629827340418, - "entity": [ - { - "name": "host", - "value": "server_3" - }, - { - "name": "service", - "value": "app_4" - } - ] - }, { "detector_id": "mmZFeXsB7JcKN0mdnMf4", "model_type": "entity", @@ -2420,7 +2163,7 @@ GET _plugins/_anomaly_detection/stats/ ``` The `model_count` parameter shows the total number of models running on each node’s memory. -Historical detectors contain additional fields: +Historical detectors contain the following additional fields: - `ad_total_batch_task_execution_count` - `ad_executing_batch_task_count` @@ -2469,71 +2212,6 @@ Historical detectors contain additional fields: } ] }, - { - "detector_id": "rlDtOHwBD5tpxlbyW7Nt", - "model_type": "entity", - "last_used_time": 1633044152729, - "model_id": "rlDtOHwBD5tpxlbyW7Nt_entity_error21", - "last_checkpoint_time": 1633043555143, - "entity": [ - { - "name": "type", - "value": "error21" - } - ] - }, - { - "detector_id": "rlDtOHwBD5tpxlbyW7Nt", - "model_type": "entity", - "last_used_time": 1633044152727, - "model_id": "rlDtOHwBD5tpxlbyW7Nt_entity_error13", - "last_checkpoint_time": 1633043554046, - "entity": [ - { - "name": "type", - "value": "error13" - } - ] - }, - { - "detector_id": "rlDtOHwBD5tpxlbyW7Nt", - "model_type": "entity", - "last_used_time": 1633044152753, - "model_id": "rlDtOHwBD5tpxlbyW7Nt_entity_error24", - "last_checkpoint_time": 1633043853986, - "entity": [ - { - "name": "type", - "value": "error24" - } - ] - }, - { - "detector_id": "rlDtOHwBD5tpxlbyW7Nt", - "model_type": "entity", - "last_used_time": 1633044152792, - "model_id": "rlDtOHwBD5tpxlbyW7Nt_entity_error25", - "last_checkpoint_time": 1633043857320, - "entity": [ - { - "name": "type", - "value": "error25" - } - ] - }, - { - "detector_id": "rlDtOHwBD5tpxlbyW7Nt", - "model_type": "entity", - "last_used_time": 1633044152779, - "model_id": "rlDtOHwBD5tpxlbyW7Nt_entity_error28", - "last_checkpoint_time": 1633043856244, - "entity": [ - { - "name": "type", - "value": "error28" - } - ] - }, { "detector_id": "rlDtOHwBD5tpxlbyW7Nt", "model_type": "entity", @@ -2599,97 +2277,6 @@ Historical detectors contain additional fields: } ] }, - { - "detector_id": "rlDtOHwBD5tpxlbyW7Nt", - "model_type": "entity", - "last_used_time": 1633044152750, - "model_id": "rlDtOHwBD5tpxlbyW7Nt_entity_error32", - "last_checkpoint_time": 1633043854080, - "entity": [ - { - "name": "type", - "value": "error32" - } - ] - }, - { - "detector_id": "rlDtOHwBD5tpxlbyW7Nt", - "model_type": "entity", - "last_used_time": 1633044152784, - "model_id": "rlDtOHwBD5tpxlbyW7Nt_entity_error23", - "last_checkpoint_time": 1633043857463, - "entity": [ - { - "name": "type", - "value": "error23" - } - ] - }, - { - "detector_id": "rlDtOHwBD5tpxlbyW7Nt", - "model_type": "entity", - "last_used_time": 1633044152774, - "model_id": "rlDtOHwBD5tpxlbyW7Nt_entity_error26", - "last_checkpoint_time": 1633043856308, - "entity": [ - { - "name": "type", - "value": "error26" - } - ] - }, - { - "detector_id": "rlDtOHwBD5tpxlbyW7Nt", - "model_type": "entity", - "last_used_time": 1633044152734, - "model_id": "rlDtOHwBD5tpxlbyW7Nt_entity_error14", - "last_checkpoint_time": 1633043555939, - "entity": [ - { - "name": "type", - "value": "error14" - } - ] - }, - { - "detector_id": "rlDtOHwBD5tpxlbyW7Nt", - "model_type": "entity", - "last_used_time": 1633044152731, - "model_id": "rlDtOHwBD5tpxlbyW7Nt_entity_error9", - "last_checkpoint_time": 1633043257214, - "entity": [ - { - "name": "type", - "value": "error9" - } - ] - }, - { - "detector_id": "rlDtOHwBD5tpxlbyW7Nt", - "model_type": "entity", - "last_used_time": 1633044152730, - "model_id": "rlDtOHwBD5tpxlbyW7Nt_entity_error19", - "last_checkpoint_time": 1633043553882, - "entity": [ - { - "name": "type", - "value": "error19" - } - ] - }, - { - "detector_id": "rlDtOHwBD5tpxlbyW7Nt", - "model_type": "entity", - "last_used_time": 1633044152732, - "model_id": "rlDtOHwBD5tpxlbyW7Nt_entity_error18", - "last_checkpoint_time": 1633043554874, - "entity": [ - { - "name": "type", - "value": "error18" - } - ] - }, { "detector_id": "rlDtOHwBD5tpxlbyW7Nt", "model_type": "entity", @@ -2729,123 +2316,6 @@ Historical detectors contain additional fields: } ] }, - { - "detector_id": "rlDtOHwBD5tpxlbyW7Nt", - "model_type": "entity", - "last_used_time": 1633044152711, - "model_id": "rlDtOHwBD5tpxlbyW7Nt_entity_error6", - "last_checkpoint_time": 1633043254281, - "entity": [ - { - "name": "type", - "value": "error6" - } - ] - }, - { - "detector_id": "rlDtOHwBD5tpxlbyW7Nt", - "model_type": "entity", - "last_used_time": 1633044152716, - "model_id": "rlDtOHwBD5tpxlbyW7Nt_entity_error4", - "last_checkpoint_time": 1633043257797, - "entity": [ - { - "name": "type", - "value": "error4" - } - ] - }, - { - "detector_id": "rlDtOHwBD5tpxlbyW7Nt", - "model_type": "entity", - "last_used_time": 1633044152709, - "model_id": "rlDtOHwBD5tpxlbyW7Nt_entity_error2", - "last_checkpoint_time": 1633043260938, - "entity": [ - { - "name": "type", - "value": "error2" - } - ] - }, - { - "detector_id": "rlDtOHwBD5tpxlbyW7Nt", - "model_type": "entity", - "last_used_time": 1633044152742, - "model_id": "rlDtOHwBD5tpxlbyW7Nt_entity_error30", - "last_checkpoint_time": 1633043853983, - "entity": [ - { - "name": "type", - "value": "error30" - } - ] - }, - { - "detector_id": "rlDtOHwBD5tpxlbyW7Nt", - "model_type": "entity", - "last_used_time": 1633044152725, - "model_id": "rlDtOHwBD5tpxlbyW7Nt_entity_error11", - "last_checkpoint_time": 1633043263038, - "entity": [ - { - "name": "type", - "value": "error11" - } - ] - }, - { - "detector_id": "rlDtOHwBD5tpxlbyW7Nt", - "model_type": "entity", - "last_used_time": 1633044152712, - "model_id": "rlDtOHwBD5tpxlbyW7Nt_entity_error10", - "last_checkpoint_time": 1633043255533, - "entity": [ - { - "name": "type", - "value": "error10" - } - ] - }, - { - "detector_id": "rlDtOHwBD5tpxlbyW7Nt", - "model_type": "entity", - "last_used_time": 1633044152719, - "model_id": "rlDtOHwBD5tpxlbyW7Nt_entity_error7", - "last_checkpoint_time": 1633043258826, - "entity": [ - { - "name": "type", - "value": "error7" - } - ] - }, - { - "detector_id": "rlDtOHwBD5tpxlbyW7Nt", - "model_type": "entity", - "last_used_time": 1633044152708, - "model_id": "rlDtOHwBD5tpxlbyW7Nt_entity_error8", - "last_checkpoint_time": 1633043259841, - "entity": [ - { - "name": "type", - "value": "error8" - } - ] - }, - { - "detector_id": "rlDtOHwBD5tpxlbyW7Nt", - "model_type": "entity", - "last_used_time": 1633044152721, - "model_id": "rlDtOHwBD5tpxlbyW7Nt_entity_error12", - "last_checkpoint_time": 1633043261989, - "entity": [ - { - "name": "type", - "value": "error12" - } - ] - }, { "detector_id": "rlDtOHwBD5tpxlbyW7Nt", "model_type": "entity", @@ -2925,7 +2395,7 @@ POST _plugins/_alerting/monitors { "search": { "indices": [ - ".opendistro-anomaly-results*" + ".opensearch-anomaly-results*" ], "query": { "size": 1, @@ -3031,7 +2501,7 @@ POST _plugins/_alerting/monitors { "search": { "indices": [ - ".opendistro-anomaly-results*" + ".opensearch-anomaly-results*" ], "query": { "size": 1, @@ -3144,14 +2614,12 @@ GET _plugins/_anomaly_detection/detectors//_profile/, ```json GET _plugins/_anomaly_detection/detectors//_profile - { - "state":"DISABLED", - "error":"Stopped detector: AD models memory usage exceeds our limit." + "state": "DISABLED", + "error": "Stopped detector: AD models memory usage exceeds our limit." } GET _plugins/_anomaly_detection/detectors//_profile?_all=true&pretty - { "state": "RUNNING", "error": "", @@ -3256,246 +2724,253 @@ GET _plugins/_anomaly_detection/detectors//_profile?_all=true&pretty "node_id": "dIyavWhmSYWGz65b4u-lpQ" }, { - "model_id": "rlDtOHwBD5tpxlbyW7Nt_entity_error1", + "model_id": "rlDtOHwBD5tpxlbyW7Nt_entity_error27", "entity": [ { "name": "type", - "value": "error1" - } - ], - "model_size_in_bytes": 403491, - "node_id": "dIyavWhmSYWGz65b4u-lpQ" - }, - { - "model_id": "rlDtOHwBD5tpxlbyW7Nt_entity_error22", - "entity": [ - { - "name": "type", - "value": "error22" - } - ], - "model_size_in_bytes": 403491, - "node_id": "dIyavWhmSYWGz65b4u-lpQ" - }, - { - "model_id": "rlDtOHwBD5tpxlbyW7Nt_entity_error32", - "entity": [ - { - "name": "type", - "value": "error32" - } - ], - "model_size_in_bytes": 403491, - "node_id": "dIyavWhmSYWGz65b4u-lpQ" - }, - { - "model_id": "rlDtOHwBD5tpxlbyW7Nt_entity_error23", - "entity": [ - { - "name": "type", - "value": "error23" - } - ], - "model_size_in_bytes": 403491, - "node_id": "dIyavWhmSYWGz65b4u-lpQ" - }, - { - "model_id": "rlDtOHwBD5tpxlbyW7Nt_entity_error26", - "entity": [ - { - "name": "type", - "value": "error26" - } - ], - "model_size_in_bytes": 403491, - "node_id": "dIyavWhmSYWGz65b4u-lpQ" - }, - { - "model_id": "rlDtOHwBD5tpxlbyW7Nt_entity_error14", - "entity": [ - { - "name": "type", - "value": "error14" - } - ], - "model_size_in_bytes": 403491, - "node_id": "dIyavWhmSYWGz65b4u-lpQ" - }, - { - "model_id": "rlDtOHwBD5tpxlbyW7Nt_entity_error9", - "entity": [ - { - "name": "type", - "value": "error9" - } - ], - "model_size_in_bytes": 403491, - "node_id": "dIyavWhmSYWGz65b4u-lpQ" - }, - { - "model_id": "rlDtOHwBD5tpxlbyW7Nt_entity_error19", - "entity": [ - { - "name": "type", - "value": "error19" - } - ], - "model_size_in_bytes": 403491, - "node_id": "dIyavWhmSYWGz65b4u-lpQ" - }, - { - "model_id": "rlDtOHwBD5tpxlbyW7Nt_entity_error18", - "entity": [ - { - "name": "type", - "value": "error18" - } - ], - "model_size_in_bytes": 403491, - "node_id": "dIyavWhmSYWGz65b4u-lpQ" - }, - { - "model_id": "rlDtOHwBD5tpxlbyW7Nt_entity_error29", - "entity": [ - { - "name": "type", - "value": "error29" - } - ], - "model_size_in_bytes": 403491, - "node_id": "dIyavWhmSYWGz65b4u-lpQ" - }, - { - "model_id": "rlDtOHwBD5tpxlbyW7Nt_entity_error5", - "entity": [ - { - "name": "type", - "value": "error5" + "value": "error27" } ], "model_size_in_bytes": 403491, "node_id": "2hEGbUw6ShaiKe05n_xLdA" + } + ], + "total_size_in_bytes": 12911712, + "init_progress": { + "percentage": "100%" + }, + "total_entities": 33, + "active_entities": 32, + "ad_task": { + "ad_task": { + "task_id": "Os4HOXwBCi2h__AONgpc", + "last_update_time": 1633044347855, + "started_by": "admin", + "state": "RUNNING", + "detector_id": "rlDtOHwBD5tpxlbyW7Nt", + "task_progress": 0, + "init_progress": 0, + "execution_start_time": 1633044346460, + "is_latest": true, + "task_type": "HISTORICAL_HC_DETECTOR", + "coordinating_node": "2hEGbUw6ShaiKe05n_xLdA", + "detector": { + "name": "test-detector", + "description": "test", + "time_field": "timestamp", + "indices": [ + "server_log" + ], + "filter_query": { + "match_all": { + "boost": 1 + } + }, + "detection_interval": { + "period": { + "interval": 5, + "unit": "Minutes" + } + }, + "window_delay": { + "period": { + "interval": 1, + "unit": "Minutes" + } + }, + "shingle_size": 8, + "schema_version": 0, + "feature_attributes": [ + { + "feature_id": "7VDtOHwBD5tpxlbyWqPs", + "feature_name": "test-feature", + "feature_enabled": true, + "aggregation_query": { + "test_feature": { + "sum": { + "field": "value" + } + } + } + } + ], + "ui_metadata": { + "features": { + "test-feature": { + "aggregationBy": "sum", + "aggregationOf": "value", + "featureType": "simple_aggs" + } + }, + "filters": [] + }, + "last_update_time": 1633042652012, + "category_field": [ + "type" + ], + "user": { + "name": "admin", + "backend_roles": [ + "admin" + ], + "roles": [ + "own_index", + "all_access" + ], + "custom_attribute_names": [], + "user_requested_tenant": null + }, + "detector_type": "MULTI_ENTITY" + }, + "detection_date_range": { + "start_time": 1632437820000, + "end_time": 1633042620000 + }, + "user": { + "name": "admin", + "backend_roles": [ + "admin" + ], + "roles": [ + "own_index", + "all_access" + ], + "custom_attribute_names": [], + "user_requested_tenant": "__user__" + } }, + "node_id": "2hEGbUw6ShaiKe05n_xLdA", + "task_id": "Os4HOXwBCi2h__AONgpc", + "task_type": "HISTORICAL_HC_DETECTOR", + "detector_task_slots": 10, + "total_entities_count": 32, + "pending_entities_count": 22, + "running_entities_count": 10, + "running_entities": [ + "error9", + "error8", + "error7", + "error6", + "error5", + "error4", + "error32", + "error31", + "error30", + "error3" + ], + "entity_task_profiles": [ + { + "shingle_size": 8, + "rcf_total_updates": 994, + "threshold_model_trained": true, + "threshold_model_training_data_size": 0, + "model_size_in_bytes": 1593240, + "node_id": "bCtWtxWPThq0BIn5P5I4Xw", + "entity": [ + { + "name": "type", + "value": "error6" + } + ], + "task_id": "P84HOXwBCi2h__AOOgrC", + "task_type": "HISTORICAL_HC_ENTITY" + }, + { + "shingle_size": 8, + "rcf_total_updates": 994, + "threshold_model_trained": true, + "threshold_model_training_data_size": 0, + "model_size_in_bytes": 1593240, + "node_id": "dIyavWhmSYWGz65b4u-lpQ", + "entity": [ + { + "name": "type", + "value": "error4" + } + ], + "task_id": "Kc4HOXwBCi2h__AOOw6Y", + "task_type": "HISTORICAL_HC_ENTITY" + }, + { + "shingle_size": 8, + "rcf_total_updates": 994, + "threshold_model_trained": true, + "threshold_model_training_data_size": 0, + "model_size_in_bytes": 1593240, + "node_id": "dIyavWhmSYWGz65b4u-lpQ", + "entity": [ + { + "name": "type", + "value": "error8" + } + ], + "task_id": "Pc4HOXwBCi2h__AOOgqJ", + "task_type": "HISTORICAL_HC_ENTITY" + }, + { + "shingle_size": 8, + "rcf_total_updates": 994, + "threshold_model_trained": true, + "threshold_model_training_data_size": 0, + "model_size_in_bytes": 1593240, + "node_id": "2hEGbUw6ShaiKe05n_xLdA", + "entity": [ + { + "name": "type", + "value": "error7" + } + ], + "task_id": "Ps4HOXwBCi2h__AOOgqh", + "task_type": "HISTORICAL_HC_ENTITY" + } + ] + }, + "model_count": 32 +} + +GET _plugins/_anomaly_detection/detectors//_profile/total_size_in_bytes +{ + "total_size_in_bytes": 13369344 +} +``` + +You can see the `ad_task` field only for a historical detector. + +The `model_count` parameter shows the total number of models that a detector runs in memory. This is useful if you have several models running on your cluster and want to know the count. + +If you configured the category field, you can see the number of unique values in the field and all active entities with models running in memory. + +You can use this data to estimate how much memory is required for anomaly detection so you can decide how to size your cluster. For example, if a detector has one million entities and only 10 of them are active in memory, you need to scale your cluster up or out. + +#### Request + +```json +GET _plugins/_anomaly_detection/detectors//_profile?_all=true&pretty +{ + "state": "RUNNING", + "error": "", + "models": [ { - "model_id": "rlDtOHwBD5tpxlbyW7Nt_entity_error6", + "model_id": "rlDtOHwBD5tpxlbyW7Nt_entity_error20", "entity": [ { "name": "type", - "value": "error6" + "value": "error20" } ], "model_size_in_bytes": 403491, - "node_id": "2hEGbUw6ShaiKe05n_xLdA" + "node_id": "bCtWtxWPThq0BIn5P5I4Xw" }, { - "model_id": "rlDtOHwBD5tpxlbyW7Nt_entity_error4", + "model_id": "rlDtOHwBD5tpxlbyW7Nt_entity_error13", "entity": [ { "name": "type", - "value": "error4" + "value": "error13" } ], "model_size_in_bytes": 403491, - "node_id": "2hEGbUw6ShaiKe05n_xLdA" - }, - { - "model_id": "rlDtOHwBD5tpxlbyW7Nt_entity_error2", - "entity": [ - { - "name": "type", - "value": "error2" - } - ], - "model_size_in_bytes": 403491, - "node_id": "2hEGbUw6ShaiKe05n_xLdA" - }, - { - "model_id": "rlDtOHwBD5tpxlbyW7Nt_entity_error30", - "entity": [ - { - "name": "type", - "value": "error30" - } - ], - "model_size_in_bytes": 403491, - "node_id": "2hEGbUw6ShaiKe05n_xLdA" - }, - { - "model_id": "rlDtOHwBD5tpxlbyW7Nt_entity_error11", - "entity": [ - { - "name": "type", - "value": "error11" - } - ], - "model_size_in_bytes": 403491, - "node_id": "2hEGbUw6ShaiKe05n_xLdA" - }, - { - "model_id": "rlDtOHwBD5tpxlbyW7Nt_entity_error10", - "entity": [ - { - "name": "type", - "value": "error10" - } - ], - "model_size_in_bytes": 403491, - "node_id": "2hEGbUw6ShaiKe05n_xLdA" - }, - { - "model_id": "rlDtOHwBD5tpxlbyW7Nt_entity_error7", - "entity": [ - { - "name": "type", - "value": "error7" - } - ], - "model_size_in_bytes": 403491, - "node_id": "2hEGbUw6ShaiKe05n_xLdA" - }, - { - "model_id": "rlDtOHwBD5tpxlbyW7Nt_entity_error8", - "entity": [ - { - "name": "type", - "value": "error8" - } - ], - "model_size_in_bytes": 403491, - "node_id": "2hEGbUw6ShaiKe05n_xLdA" - }, - { - "model_id": "rlDtOHwBD5tpxlbyW7Nt_entity_error12", - "entity": [ - { - "name": "type", - "value": "error12" - } - ], - "model_size_in_bytes": 403491, - "node_id": "2hEGbUw6ShaiKe05n_xLdA" - }, - { - "model_id": "rlDtOHwBD5tpxlbyW7Nt_entity_error15", - "entity": [ - { - "name": "type", - "value": "error15" - } - ], - "model_size_in_bytes": 403491, - "node_id": "2hEGbUw6ShaiKe05n_xLdA" - }, - { - "model_id": "rlDtOHwBD5tpxlbyW7Nt_entity_error17", - "entity": [ - { - "name": "type", - "value": "error17" - } - ], - "model_size_in_bytes": 403491, - "node_id": "2hEGbUw6ShaiKe05n_xLdA" + "node_id": "bCtWtxWPThq0BIn5P5I4Xw" }, { "model_id": "rlDtOHwBD5tpxlbyW7Nt_entity_error27", @@ -3681,70 +3156,6 @@ GET _plugins/_anomaly_detection/detectors//_profile?_all=true&pretty "task_id": "PM4HOXwBCi2h__AOOgp3", "task_type": "HISTORICAL_HC_ENTITY" }, - { - "shingle_size": 8, - "rcf_total_updates": 994, - "threshold_model_trained": true, - "threshold_model_training_data_size": 0, - "model_size_in_bytes": 1593240, - "node_id": "dIyavWhmSYWGz65b4u-lpQ", - "entity": [ - { - "name": "type", - "value": "error31" - } - ], - "task_id": "LM4HOXwBCi2h__AOOw7v", - "task_type": "HISTORICAL_HC_ENTITY" - }, - { - "shingle_size": 8, - "rcf_total_updates": 994, - "threshold_model_trained": true, - "threshold_model_training_data_size": 0, - "model_size_in_bytes": 1593240, - "node_id": "dIyavWhmSYWGz65b4u-lpQ", - "entity": [ - { - "name": "type", - "value": "error4" - } - ], - "task_id": "Kc4HOXwBCi2h__AOOw6Y", - "task_type": "HISTORICAL_HC_ENTITY" - }, - { - "shingle_size": 8, - "rcf_total_updates": 994, - "threshold_model_trained": true, - "threshold_model_training_data_size": 0, - "model_size_in_bytes": 1593240, - "node_id": "dIyavWhmSYWGz65b4u-lpQ", - "entity": [ - { - "name": "type", - "value": "error30" - } - ], - "task_id": "Lc4HOXwBCi2h__AOPA4R", - "task_type": "HISTORICAL_HC_ENTITY" - }, - { - "shingle_size": 8, - "rcf_total_updates": 994, - "threshold_model_trained": true, - "threshold_model_training_data_size": 0, - "model_size_in_bytes": 1593240, - "node_id": "dIyavWhmSYWGz65b4u-lpQ", - "entity": [ - { - "name": "type", - "value": "error8" - } - ], - "task_id": "Pc4HOXwBCi2h__AOOgqJ", - "task_type": "HISTORICAL_HC_ENTITY" - }, { "shingle_size": 8, "rcf_total_updates": 994, @@ -3797,70 +3208,125 @@ GET _plugins/_anomaly_detection/detectors//_profile?_all=true&pretty }, "model_count": 32 } - -GET _plugins/_anomaly_detection/detectors//_profile/total_size_in_bytes - -{ - "total_size_in_bytes" : 13369344 -} ``` -The `model_count` parameter shows the total number of models that a detector runs in memory. This is useful if you have several models running on your cluster and want to know the count. +For a single-entity detector: -If you configured the category field, you can see the number of unique values in the field and all active entities with models running in memory. - -You can use this data to estimate how much memory is required for anomaly detection so you can decide how to size your cluster. For example, if a detector has one million entities and only 10 of them are active in memory, you need to scale your cluster up or out. - -#### Request +#### Sample response ```json -GET _plugins/_anomaly_detection/detectors//_profile?_all=true&pretty - { - "state": "RUNNING", - "models": [ - { - "model_id": "T4c3dXUBj-2IZN7itix__entity_i-00f28ec1eb8997684", - "model_size_in_bytes": 712480, - "node_id": "g6pmr547QR-CfpEvO67M4g" - }, - { - "model_id": "T4c3dXUBj-2IZN7itix__entity_i-00f28ec1eb8997685", - "model_size_in_bytes": 712480, - "node_id": "g6pmr547QR-CfpEvO67M4g" - }, - { - "model_id": "T4c3dXUBj-2IZN7itix__entity_i-00f28ec1eb8997686", - "model_size_in_bytes": 712480, - "node_id": "g6pmr547QR-CfpEvO67M4g" - }, - { - "model_id": "T4c3dXUBj-2IZN7itix__entity_i-00f28ec1eb8997680", - "model_size_in_bytes": 712480, - "node_id": "g6pmr547QR-CfpEvO67M4g" - }, - { - "model_id": "T4c3dXUBj-2IZN7itix__entity_i-00f28ec1eb8997681", - "model_size_in_bytes": 712480, - "node_id": "g6pmr547QR-CfpEvO67M4g" - }, - { - "model_id": "T4c3dXUBj-2IZN7itix__entity_i-00f28ec1eb8997682", - "model_size_in_bytes": 712480, - "node_id": "g6pmr547QR-CfpEvO67M4g" - }, - { - "model_id": "T4c3dXUBj-2IZN7itix__entity_i-00f28ec1eb8997683", - "model_size_in_bytes": 712480, - "node_id": "g6pmr547QR-CfpEvO67M4g" - } - ], - "total_size_in_bytes": 4987360, + "state": "INIT", + "total_size_in_bytes": 0, "init_progress": { - "percentage": "100%" + "percentage": "0%", + "needed_shingles": 128 }, - "total_entities": 7, - "active_entities": 7 + "ad_task": { + "ad_task": { + "task_id": "cfUNOXwBFLNqSEcxAlde", + "last_update_time": 1633044731640, + "started_by": "admin", + "state": "RUNNING", + "detector_id": "qL4NOXwB__6eNorTAKtJ", + "task_progress": 0.49603173, + "init_progress": 1, + "current_piece": 1632739800000, + "execution_start_time": 1633044726365, + "is_latest": true, + "task_type": "HISTORICAL_SINGLE_ENTITY", + "coordinating_node": "bCtWtxWPThq0BIn5P5I4Xw", + "worker_node": "dIyavWhmSYWGz65b4u-lpQ", + "detector": { + "name": "detector1", + "description": "test", + "time_field": "timestamp", + "indices": [ + "server_log" + ], + "filter_query": { + "match_all": { + "boost": 1 + } + }, + "detection_interval": { + "period": { + "interval": 5, + "unit": "Minutes" + } + }, + "window_delay": { + "period": { + "interval": 1, + "unit": "Minutes" + } + }, + "shingle_size": 8, + "schema_version": 0, + "feature_attributes": [ + { + "feature_id": "p74NOXwB__6eNorTAKss", + "feature_name": "test-feature", + "feature_enabled": true, + "aggregation_query": { + "test_feature": { + "sum": { + "field": "value" + } + } + } + } + ], + "ui_metadata": { + "features": { + "test-feature": { + "aggregationBy": "sum", + "aggregationOf": "value", + "featureType": "simple_aggs" + } + }, + "filters": [] + }, + "last_update_time": 1633044725832, + "user": { + "name": "admin", + "backend_roles": [ + "admin" + ], + "roles": [ + "own_index", + "all_access" + ], + "custom_attribute_names": [], + "user_requested_tenant": "__user__" + }, + "detector_type": "SINGLE_ENTITY" + }, + "detection_date_range": { + "start_time": 1632439925885, + "end_time": 1633044725885 + }, + "user": { + "name": "admin", + "backend_roles": [ + "admin" + ], + "roles": [ + "own_index", + "all_access" + ], + "custom_attribute_names": [], + "user_requested_tenant": "__user__" + } + }, + "shingle_size": 8, + "rcf_total_updates": 1994, + "threshold_model_trained": true, + "threshold_model_training_data_size": 0, + "model_size_in_bytes": 1593240, + "node_id": "dIyavWhmSYWGz65b4u-lpQ", + "detector_task_slots": 1 + } } ``` @@ -3868,11 +3334,10 @@ The `total_entities` parameter shows you the total number of entities including Getting the total count of entities is an expensive operation for a detector with more than one category field. By default, a real-time detector counts the number of entities up to a value of 10,000 and a historical detector counts the number of entities up to a value of 1,000. -The `profile` operation also provides information about each entity, such as the entity’s `last_sample_timestamp` and `last_active_timestamp`. +The `profile` operation also provides information about each entity, such as the entity’s `last_sample_timestamp` and `last_active_timestamp`. `last_sample_timestamp` shows the last document in the input data source index containing the entity, while `last_active_timestamp` shows the timestamp when the entity’s model was last seen in the model cache. If there are no anomaly results for an entity, either the entity doesn't have any sample data or its model is removed from the model cache. - `last_sample_timestamp` shows the last document in the input data source index containing the entity, while `last_active_timestamp` shows the timestamp when the entity’s model was last seen in the model cache. #### Request diff --git a/_monitoring-plugins/ad/index.md b/_monitoring-plugins/ad/index.md index 87417e0f..b02f14a0 100644 --- a/_monitoring-plugins/ad/index.md +++ b/_monitoring-plugins/ad/index.md @@ -26,12 +26,11 @@ To first test with sample streaming data, you can try out one of the preconfigur A detector is an individual anomaly detection task. You can define multiple detectors, and all the detectors can run simultaneously, with each analyzing data from different sources. -1. Choose **Create Detector**. +1. Choose **Create detector**. 1. Enter a name and brief description. Make sure the name is unique and descriptive enough to help you to identify the purpose of the detector. 1. For **Data source**, choose the index you want to use as the data source. You can optionally use index patterns to choose multiple indices. -1. (Optional) For **Data filter**, filter the index you chose as the data source. From the **Data filter** menu, design your filter query by selecting **Field**, **Operator**, and **Value**, or choose **Use query DSL** and add your own JSON filter query. +1. (Optional) For **Data filter**, filter the index you chose as the data source. From the **Data filter** menu, choose **Add data filter**, and then design your filter query by selecting **Field**, **Operator**, and **Value**, or choose **Use query DSL** and add your own JSON filter query. 1. Select the **Timestamp field** in your index. -1. (Optional) For **Data filter**, filter the index you chose as the data source. From the **Filter type** menu, choose **Visual filter**, and then design your filter query by selecting **Fields**, **Operator**, and **Value**, or choose **Custom Expression** and add your own JSON filter query. 1. For **Operation settings**, define the **Detector interval**, which is the time interval at which the detector collects data. - The detector aggregates the data in this interval, then feeds the aggregated result into the anomaly detection model. The shorter you set this interval, the fewer data points the detector aggregates. @@ -46,7 +45,9 @@ Setting the window delay to 1 minute shifts the interval window to 1:49 - 1:59, After you define the detector, the next step is to configure the model. -### Step 2: Add features to your detector +### Step 2: Configure the model + +#### Add features to your detector A feature is the field in your index that you want to check for anomalies. A detector can discover anomalies across one or more features. You must choose an aggregation method for each feature: `average()`, `count()`, `sum()`, `min()`, or `max()`. The aggregation method determines what constitutes an anomaly. @@ -55,7 +56,7 @@ For example, if you choose `min()`, the detector focuses on finding anomalies ba 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. 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. {: .note } -1. On the **Configure Model** page, enter the **Feature name** and check **Enabled feature name**. +1. On the **Configure Model** page, enter the **Feature name** and check **Enable feature**. 1. For **Find anomalies based on**, choose the method to find anomalies. For **Field Value**, choose the **aggregation method**. Or choose **Custom expression**, and add your own JSON aggregation query. 1. Select a field. @@ -128,8 +129,8 @@ Analyze anomalies with the following visualizations: - **Live anomalies** - displays live anomaly results for the last 60 intervals. For example, if the interval is 10, it shows results for the last 600 minutes. The chart refreshes every 30 seconds. - **Anomaly history** (for historical analysis) / **Anomaly overview** (for real-time results) - plots the anomaly grade with the corresponding measure of confidence. -- **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. +- **Feature breakdown** - plots the features based on the aggregation method. You can vary the date-time range of the detector. `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. diff --git a/_monitoring-plugins/ad/settings.md b/_monitoring-plugins/ad/settings.md index 8d3cc5b1..eaebdee2 100644 --- a/_monitoring-plugins/ad/settings.md +++ b/_monitoring-plugins/ad/settings.md @@ -28,16 +28,21 @@ Setting | Default | Description `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` | 250,000,000 | 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_rollover_period` | 12h | How often the rollover condition is checked. If `true`, the anomaly detection plugin rolls over the result index to a new index. +`plugins.anomaly_detection.ad_result_history_max_docs` | 250,000,000 | The maximum number of documents in one result index. The anomaly detection plugin only counts refreshed documents in the primary shards. `plugins.anomaly_detection.ad_result_history_max_docs_per_shard` | 1,350,000,000 | The maximum number of documents in a single shard of the result index. The anomaly detection plugin only counts the refreshed documents in the primary shards. -`plugins.anomaly_detection.max_entities_per_query` | 1,000,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` | 5 | 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_entities_per_query` | 1,000,000 | The maximum unique values per detection interval for high cardinality detectors. By default, if the category field(s) have more than the configured unique values in a detector interval, the anomaly detection plugin orders them by the natural ordering of categorical values (for example, entity `ab` comes before `bc`) and then selects the top values. +`plugins.anomaly_detection.max_entities_for_preview` | 5 | The maximum unique category field values displayed with the preview operation for high cardinality detectors. By default, if the category field(s) have more than the configured unique values in a detector interval, the anomaly detection plugin orders them by the natural ordering of categorical values (for example, entity `ab` comes before `bc`) and then selects the top values. `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_batch_task_per_node` | 10 | 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.filter_by_backend_roles` | False | When you enable the security plugin and set this to `true`, the anomaly detection plugin filters results based on the user's backend role(s). +`plugins.anomaly_detection.max_batch_task_per_node` | 10 | 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 1,000. 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` | 1 | 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` | 1,000 | 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_size` | 1,000 | 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 1,000 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. -`plugins.anomaly_detection.max_top_entities_for_historical_analysis` | 1,000 | The maximum number of top entities that you run for a high-cardinality detector historical analysis. -`plugins.anomaly_detection.max_running_entities_per_detector_for_historical_analysis` | 10 | How many entity tasks you can run in parallel for one HC detector. The cluster availble task slots will impact how many entities can run in parallel as well. For example, the cluster has 3 data nodes, each data node has 10 task slots by default. But if we have already started 2 HC detectors and each HC running 10 entities, and start a single-flow detector which takes 1 task slot, then the availabe task slots will be 10 * 3 - 10 * 2 - 1 = 9. Then, if we start a new HC detector, it can only run 9 entities in parallel, not 10. +`plugins.anomaly_detection.max_top_entities_for_historical_analysis` | 1,000 | The maximum number of top entities that you run for a high cardinality detector historical analysis. +`plugins.anomaly_detection.max_running_entities_per_detector_for_historical_analysis` | 10 | The number of entity tasks that you can run in parallel for a single high cardinality detector. The task slots available on your cluster also impact how many entities run in parallel. If a cluster has 3 data nodes, each data node has 10 task slots by default. Say you already have two high cardinality detectors and each of them run 10 entities. If you start a single-flow detector that takes 1 task slot, the number of task slots available is 10 * 3 - 10 * 2 - 1 = 9. if you now start a new high cardinality detector, the detector can only run 9 entities in parallel and not 10. +`plugins.anomaly_detection.max_cached_deleted_tasks` | 1,000 | You can rerun historical analysis for a single detector as many times as you like. The anomaly detection plugin only keeps a limited number of old tasks, by default 1 old task. If you run historical analysis three times for a detector, the oldest task is deleted. Because historical analysis generates a number of anomaly results in a short span of time, it's necessary to clean up anomaly results for a deleted task. With this field, you can configure how many deleted tasks you can cache at most. The plugin cleans up a task's results when it's deleted. If the plugin fails to do this cleanup, it adds the task's results into a cache and an hourly cron job performs the cleanup. After an hour, if still you find an old task result in the cache, use the [delete detector results API]({{site.url}}{{site.baseurl}}/monitoring-plugins/ad/api/#delete-detector-results) to delete the task result manually. +`plugins.anomaly_detection.delete_anomaly_result_when_delete_detector` | False | Whether the anomaly detection plugin deletes the anomaly result when you delete a detector. If you want to save some disk space, especially if you've high cardinality detectors generating a lot of results, set this field to true. Alternatively, you can use the [delete detector results API]({{site.url}}{{site.baseurl}}/monitoring-plugins/ad/api/#delete-detector-results) to manually delete the results. +`plugins.anomaly_detection.dedicated_cache_size` | 10 | If the real-time analysis of a high cardinality detector starts successfully, the anomaly detection plugin guarantees keeping 10 (dynamically adjustable via this setting) entities' models in memory per node. If the number of entities exceeds this limit, the plugin puts the extra entities' models in a memory space shared by all detectors. The actual number of entities varies based on the memory that you've available and the frequencies of the entities. If you'd like the plugin to guarantee keeping more entities' models in memory and if you're cluster has sufficient memory, you can increase this setting value. +`plugins.anomaly_detection.max_concurrent_preview` | 2 | The maximum number of concurrent previews. You can use this setting to limit resource usage. +`plugins.anomaly_detection.model_max_size_percent` | 0.1 | The upper bound of the memory percentage for a model. From f12f4efc02cff58961ddf627878e7defdbe11cca Mon Sep 17 00:00:00 2001 From: ashwinkumar12345 Date: Mon, 4 Oct 2021 12:13:31 -0700 Subject: [PATCH 111/167] minor fix --- _monitoring-plugins/ad/api.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/_monitoring-plugins/ad/api.md b/_monitoring-plugins/ad/api.md index e3db5aac..ab12a8f8 100644 --- a/_monitoring-plugins/ad/api.md +++ b/_monitoring-plugins/ad/api.md @@ -265,7 +265,7 @@ Passes a date range to the anomaly detector to return any anomalies within that #### Request ```json -POST _plugins/_anomaly_detection/detectors/_preview +POST _plugins/_anomaly_detection/detectors//_preview { "period_start": 1612982516000, "period_end": 1614278539000, From f0f770bfad04f4792c5c264b2957c28d14677865 Mon Sep 17 00:00:00 2001 From: ashwinkumar12345 Date: Mon, 4 Oct 2021 12:32:08 -0700 Subject: [PATCH 112/167] removed validate API --- _monitoring-plugins/ad/api.md | 139 ---------------------------------- 1 file changed, 139 deletions(-) diff --git a/_monitoring-plugins/ad/api.md b/_monitoring-plugins/ad/api.md index ab12a8f8..f0d8e4c5 100644 --- a/_monitoring-plugins/ad/api.md +++ b/_monitoring-plugins/ad/api.md @@ -1230,145 +1230,6 @@ DELETE _plugins/_anomaly_detection/detectors/results --- -## Validate detector -Introduced 1.1 -{: .label .label-purple } - -Validates detector before creating. Lists any invalid fields in your configuration and recommends ways to fix these invalid fields. - -#### Request - -```json -POST _plugins/_anomaly_detection/detectors/_validate/detector,model -{ - "name": "test-detector", - "description": "Test detector", - "time_field": "timestamp", - "indices": [ - "order*" - ], - "feature_attributes": [ - { - "feature_name": "total_order", - "feature_enabled": true, - "aggregation_query": { - "total_order": { - "sum": { - "field": "value" - } - } - } - } - ], - "filter_query": { - "bool": { - "filter": [ - { - "exists": { - "field": "value", - "boost": 1 - } - } - ], - "adjust_pure_negative": true, - "boost": 1 - } - }, - "detection_interval": { - "period": { - "interval": 1, - "unit": "Minutes" - } - }, - "window_delay": { - "period": { - "interval": 1, - "unit": "Minutes" - } - }, - "category_field": [ - "hc_field" - ], - "shingle_size": 8 -} -``` - - -#### Sample response - -```json -{ - "detector": { - "name": { - "message": "name should be set|duplicate" - }, - "time_field": { - "message": "time_field should be set missing|not_exist" - }, - "indices": { - "message": "should be set|not_exist|empty" - }, - "feature_attributes": { - "problematic_feature_name1": { - "message": "{field} is invalid with {exceptionMessage}" - } - "problematic_feature_name2": { - "message": "{field} is invalid with {exceptionMessage}" - }, - "message": "there exists non-numeric field|duplicate feature names|over 5 features|duplicate feature aggregation query names" - }, - "detection_interval": { - "message": "detection_interval should be set|Interval should be non-negative|unit is not supported" - }, - "category_field": { - "message": "must only 1 field, and must be IP address or keyword type" - }, - "shingle_size": { - "message": "must be between 1 and 1000" - }, - }, - "model": { - "filter_query": { - "message": "data is too sparse after filter_query is applied" - }, - "detection_interval": { - "suggested_value": { - "period": { - "interval": 1, - "unit": "Minutes" - } - } - "message": "use suggested value|no suggested value found, ingest more data" - }, - "category_field": { - "message": "data with {category_field} is too sparse, ingest more data" - }, - "feature_attributes": { - "problematic_feature_name1": { - "message": "data is too sparse, ingest more data with this {field}" - } - "problematic_feature_name2": { - "message": "data is too sparse, ingest more data with this {field}" - }, - "message": "data is too sparse, ingest more data" - }, - "memory": { - "message": "model size exceeds memory limit, please stop/delete unused detectors, or reduce shingle size or number of features" - }, - "window_delay": { - "suggested_value": { - "period": { - "interval": 1, - "unit": "Minutes" - } - }, - "message": "use suggested value(if it exists), and ingest more data if possible" - } - } -} -``` - ---- ## Update detector Introduced 1.0 From 72c710d5a3a80818e1aee0edf9f1dfa632af7906 Mon Sep 17 00:00:00 2001 From: ashwinkumar12345 Date: Mon, 4 Oct 2021 12:38:02 -0700 Subject: [PATCH 113/167] historical detector to historical analysis --- _monitoring-plugins/ad/api.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/_monitoring-plugins/ad/api.md b/_monitoring-plugins/ad/api.md index f0d8e4c5..c6bd39e6 100644 --- a/_monitoring-plugins/ad/api.md +++ b/_monitoring-plugins/ad/api.md @@ -2024,13 +2024,15 @@ GET _plugins/_anomaly_detection/stats/ ``` The `model_count` parameter shows the total number of models running on each node’s memory. -Historical detectors contain the following additional fields: +For historical analysis, you see the values for the following fields: - `ad_total_batch_task_execution_count` - `ad_executing_batch_task_count` - `ad_canceled_batch_task_count` - `ad_batch_task_failure_count` +For real-time analysis, these values are 0. + #### Sample response ```json @@ -2795,7 +2797,7 @@ GET _plugins/_anomaly_detection/detectors//_profile/total_size_in_by } ``` -You can see the `ad_task` field only for a historical detector. +You can see the `ad_task` field only for historical analysis. The `model_count` parameter shows the total number of models that a detector runs in memory. This is useful if you have several models running on your cluster and want to know the count. From 1c10355a795d206bc8918e9fbfdb5816c6f99a11 Mon Sep 17 00:00:00 2001 From: ashwinkumar12345 Date: Mon, 4 Oct 2021 12:41:37 -0700 Subject: [PATCH 114/167] minor fixes --- _monitoring-plugins/ad/api.md | 8 ++++---- _monitoring-plugins/ad/index.md | 2 +- 2 files changed, 5 insertions(+), 5 deletions(-) diff --git a/_monitoring-plugins/ad/api.md b/_monitoring-plugins/ad/api.md index c6bd39e6..d434ec7d 100644 --- a/_monitoring-plugins/ad/api.md +++ b/_monitoring-plugins/ad/api.md @@ -793,7 +793,7 @@ POST _plugins/_anomaly_detection/detectors/results/_search } ``` -You can query the anomaly results of a historical detector with the `task_id`: +You can query the anomaly results for historical analysis with the `task_id`: #### Request @@ -1570,7 +1570,7 @@ GET _plugins/_anomaly_detection/detectors/?job=true } ``` -Use `task=true` to get historical detector task information. +Use `task=true` to get historical analysis task information. #### Request @@ -3195,7 +3195,7 @@ For a single-entity detector: The `total_entities` parameter shows you the total number of entities including the number of category fields for a detector. -Getting the total count of entities is an expensive operation for a detector with more than one category field. By default, a real-time detector counts the number of entities up to a value of 10,000 and a historical detector counts the number of entities up to a value of 1,000. +Getting the total count of entities is an expensive operation for a detector with more than one category field. By default, a real-time detector counts the number of entities up to a value of 10,000 and historical analysis counts the number of entities up to a value of 1,000. The `profile` operation also provides information about each entity, such as the entity’s `last_sample_timestamp` and `last_active_timestamp`. `last_sample_timestamp` shows the last document in the input data source index containing the entity, while `last_active_timestamp` shows the timestamp when the entity’s model was last seen in the model cache. @@ -3237,7 +3237,7 @@ GET _plugins/_anomaly_detection/detectors//_profile?_all=true } ``` -For a historical detector, specify `_all` or `ad_task` to see information about its latest task: +For historical analysis, specify `_all` or `ad_task` to see information about its latest task: #### Request diff --git a/_monitoring-plugins/ad/index.md b/_monitoring-plugins/ad/index.md index b02f14a0..d41f6455 100644 --- a/_monitoring-plugins/ad/index.md +++ b/_monitoring-plugins/ad/index.md @@ -153,7 +153,7 @@ If you stop or delete a detector, make sure to delete any monitors associated wi To see all the configuration settings for a detector, choose the **Detector configuration** tab. 1. To make any changes to the detector configuration, or fine tune the time interval to minimize any false positives, go to the **Detector configuration** section and choose **Edit**. -- You need to stop a real-time or historical detector to change its configuration. Confirm that you want to stop the detector and proceed. +- You need to stop real-time or historical analysis to change its configuration. Confirm that you want to stop the detector and proceed. 1. To enable or disable features, in the **Features** section, choose **Edit** and adjust the feature settings as needed. After you make your changes, choose **Save and start detector**. ### Step 8: Manage your detectors From 16e8e1bbc47021588b6453791c047cbc3f109287 Mon Sep 17 00:00:00 2001 From: Liz Snyder Date: Mon, 4 Oct 2021 13:47:22 -0700 Subject: [PATCH 115/167] Clarify connection alias --- _replication-plugin/api.md | 17 +++++++++-------- _replication-plugin/auto-follow.md | 4 ++-- _replication-plugin/get-started.md | 16 +++++++++------- _replication-plugin/permissions.md | 6 ++---- 4 files changed, 22 insertions(+), 21 deletions(-) diff --git a/_replication-plugin/api.md b/_replication-plugin/api.md index 792aaecf..58457c84 100644 --- a/_replication-plugin/api.md +++ b/_replication-plugin/api.md @@ -24,7 +24,7 @@ Initiate replication of an index from the leader cluster to the follower cluster ```json PUT /_plugins/_replication//_start { - "leader_alias":"", + "leader_alias":"", "leader_index":"", "use_roles":{ "leader_cluster_role":"", @@ -37,7 +37,7 @@ Specify the following options: Options | Description | Type | Required :--- | :--- |:--- |:--- | -`leader_alias` | The name of the leader cluster. This alias is the same as the remote cluster name used to set up a cross-cluster connection. | `string` | Yes +`leader_alias` | The name of the cross-cluster connection. You define this alias when you [set up a cross-cluster connection]({{site.url}}{{site.baseurl}}/replication-plugin/get-started/#set-up-a-cross-cluster-connection). | `string` | Yes `leader_index` | The index on the leader cluster that you want to replicate. | `string` | Yes `use_roles` | The roles to use for all subsequent backend replication tasks between the indices. Specify a `leader_cluster_role` and `follower_cluster_role`. See [Map the leader and follower cluster roles]({{site.url}}{{site.baseurl}}/replication-plugin/permissions/#map-the-leader-and-follower-cluster-roles). | `string` | If security plugin is enabled @@ -130,7 +130,7 @@ GET /_plugins/_replication//_status { "status" : "SYNCING", "reason" : "User initiated", - "leader_alias" : "leader-cluster", + "leader_alias" : "my-connection-name", "leader_index" : "leader-01", "follower_index" : "follower-01", "syncing_details" : { @@ -140,9 +140,10 @@ GET /_plugins/_replication//_status } } ``` - To include shard replication details in the response, add the `&verbose=true` parameter. +The leader and follower checkpoint values begin as negative integers and reflect the number of shards you have (-1 for one shard, -5 for five shards, and so on). The values increment to positive integers with each change that you make. For example, when you make a change on the leader index, the `leader_checkpoint` becomes `0`. The `follower_checkpoint` is initially still `-1` until the follower index pulls the change from the leader, at which point it increments to `0`. If the values are the same, it means the indices are fully synced. + ## Update settings Introduced 1.1 {: .label .label-purple } @@ -185,7 +186,7 @@ Make sure to note the names of all auto-follow patterns after you create them. T ```json POST /_plugins/_replication/_autofollow { - "leader_alias" : "", + "leader_alias" : "", "name": "", "pattern": "", "use_roles":{ @@ -199,7 +200,7 @@ Specify the following options: Options | Description | Type | Required :--- | :--- |:--- |:--- | -`leader_alias` | The name of the remote cluster to associate the pattern with. | `string` | Yes +`leader_alias` | The name of the cross-cluster connection. You define this alias when you [set up a cross-cluster connection]({{site.url}}{{site.baseurl}}/replication-plugin/get-started/#set-up-a-cross-cluster-connection). | `string` | Yes `name` | A name for the auto-follow pattern. | `string` | Yes `pattern` | An array of index patterns to match against indices in the specified leader cluster. Supports wildcard characters. For example, `leader-*`. | `string` | Yes `use_roles` | The roles to use for all subsequent backend replication tasks between the indices. Specify a `leader_cluster_role` and `follower_cluster_role`. See [Map the leader and follower cluster roles]({{site.url}}{{site.baseurl}}/replication-plugin/permissions/#map-the-leader-and-follower-cluster-roles). | `string` | If security plugin is enabled @@ -225,7 +226,7 @@ Send this request to the follower cluster. ```json DELETE /_plugins/_replication/_autofollow { - "leader_alias" : "", + "leader_alias" : "", "name": "", } ``` @@ -234,7 +235,7 @@ Specify the following options: Options | Description | Type | Required :--- | :--- |:--- |:--- | -`leader_alias` | The name of the remote cluster that the pattern is associated with. | `string` | Yes +`leader_alias` | The name of the cross-cluster connection. You define this alias when you [set up a cross-cluster connection]({{site.url}}{{site.baseurl}}/replication-plugin/get-started/#set-up-a-cross-cluster-connection). | `string` | Yes `name` | The name of the pattern. | `string` | Yes #### Sample response diff --git a/_replication-plugin/auto-follow.md b/_replication-plugin/auto-follow.md index 2e06761e..4af6c61f 100644 --- a/_replication-plugin/auto-follow.md +++ b/_replication-plugin/auto-follow.md @@ -32,7 +32,7 @@ Create a replication rule on the follower cluster: ```bash curl -XPOST -k -H 'Content-Type: application/json' -u 'admin:admin' 'https://localhost:9200/_plugins/_replication/_autofollow?pretty' -d ' { - "leader_alias" : "leader-cluster", + "leader_alias" : "my-connection-alias", "name": "my-replication-rule", "pattern": "movies*", "use_roles":{ @@ -69,7 +69,7 @@ When you delete a replication rule, OpenSearch stops replicating *new* indices t ```bash curl -XDELETE -k -H 'Content-Type: application/json' -u 'admin:admin' 'https://localhost:9200/_plugins/_replication/_autofollow?pretty' -d ' { - "leader_alias" : "leader-cluster", + "leader_alias" : "my-conection-alias", "name": "my-replication-rule" }' ``` diff --git a/_replication-plugin/get-started.md b/_replication-plugin/get-started.md index 30955b8c..e6b3c36a 100644 --- a/_replication-plugin/get-started.md +++ b/_replication-plugin/get-started.md @@ -132,7 +132,7 @@ docker inspect --format='{% raw %}{{range .NetworkSettings.Networks}}{{.IPAddres Cross-cluster replication follows a "pull" model, so most changes occur on the follower cluster, not the leader cluster. -On the follower cluster, add the leader cluster name and the IP address (with port 9300) for each seed node. Because this is a single-node cluster, you only have one seed node: +On the follower cluster, add the IP address (with port 9300) for each seed node. Because this is a single-node cluster, you only have one seed node. Provide a descriptive name for the connection, which you'll use in the request to start replication: ```bash curl -XPUT -k -H 'Content-Type: application/json' -u 'admin:admin' 'https://localhost:9200/_cluster/settings?pretty' -d ' @@ -140,7 +140,7 @@ curl -XPUT -k -H 'Content-Type: application/json' -u 'admin:admin' 'https://loca "persistent": { "cluster": { "remote": { - "leader-cluster": { + "my-connection-alias": { "seeds": ["172.22.0.3:9300"] } } @@ -157,12 +157,12 @@ To get started, create an index called `leader-01` on the leader cluster: curl -XPUT -k -H 'Content-Type: application/json' -u 'admin:admin' 'https://localhost:9201/leader-01?pretty' ``` -Then start replication of that index from the follower cluster. In the request body, provide the leader cluster and index, along with the security roles that you want to use: +Then start replication from the follower cluster. In the request body, provide the connection name and leader index that you want to replicate, along with the security roles you want to use: ```bash curl -XPUT -k -H 'Content-Type: application/json' -u 'admin:admin' 'https://localhost:9200/_plugins/_replication/follower-01/_start?pretty' -d ' { - "leader_alias": "leader-cluster", + "leader_alias": "my-connection-alias", "leader_index": "leader-01", "use_roles":{ "leader_cluster_role": "all_access", @@ -186,7 +186,7 @@ curl -XGET -k -u 'admin:admin' 'https://localhost:9200/_plugins/_replication/fol { "status" : "SYNCING", "reason" : "User initiated", - "leader_alias" : "leader-cluster", + "leader_alias" : "my-connection-alias", "leader_index" : "leader-01", "follower_index" : "follower-01", "syncing_details" : { @@ -197,7 +197,9 @@ curl -XGET -k -u 'admin:admin' 'https://localhost:9200/_plugins/_replication/fol } ``` -Possible statuses are `SYNCING`, `BOOTSTRAPING`, `PAUSED`, and `REPLICATION NOT IN PROGRESS`. The leader and follower checkpoint values increment with each change and illustrate how many updates the follower is behind the leader. If the indices are fully synced, the values are the same. +Possible statuses are `SYNCING`, `BOOTSTRAPING`, `PAUSED`, and `REPLICATION NOT IN PROGRESS`. + +The leader and follower checkpoint values begin as negative numbers and reflect the number of shards you have (-1 for one shard, -5 for five shards, and so on). The values increment with each change and illustrate how many updates the follower is behind the leader. If the indices are fully synced, the values are the same. To confirm that replication is actually happening, add a document to the leader index: @@ -240,7 +242,7 @@ curl -XGET -k -u 'admin:admin' 'https://localhost:9200/_plugins/_replication/fol { "status" : "PAUSED", "reason" : "User initiated", - "leader_alias" : "leader-cluster", + "leader_alias" : "my-connection-alias", "leader_index" : "leader-01", "follower_index" : "follower-01" } diff --git a/_replication-plugin/permissions.md b/_replication-plugin/permissions.md index 2204dba5..e4b3152c 100644 --- a/_replication-plugin/permissions.md +++ b/_replication-plugin/permissions.md @@ -18,7 +18,7 @@ Enable node-to-node encryption on both the leader and the follower cluster to en ## Basic permissions -In order for non-admin users to perform replication activities, they be mapped to the appropriate permissions. +In order for non-admin users to perform replication activities, they must be mapped to the appropriate permissions. The security plugin has two built-in roles that cover most replication use cases: `cross_cluster_replication_leader_full_access`, which provides replication permissions on the leader cluster, and `cross_cluster_replication_follower_full_access`, which provides replication permissions on the follower cluster. For descriptions of each, see [Predefined roles]({{site.url}}{{site.baseurl}}/security-plugin/access-control/users-roles#predefined-roles). @@ -26,9 +26,7 @@ If you don't want to use the default roles, you can combine individual replicati ## Map the leader and follower cluster roles -associates roles passed in the request to these replication jobs to run in the background - -The [start replication]({{site.url}}{{site.baseurl}}/replication-plugin/api/#start-replication) and [create replication rule]({{site.url}}{{site.baseurl}}/replication-plugin/api/#create-replication-rule) operations are special cases. They involve background processes on the leader and follower clusters that must be associated with roles. When you perform one of these actions, you must explicitly pass the `leader_cluster_role` and +The [start replication]({{site.url}}{{site.baseurl}}/replication-plugin/api/#start-replication) and [create replication rule]({{site.url}}{{site.baseurl}}/replication-plugin/api/#create-replication-rule) operations are special cases. They involve background processes on the leader and follower clusters that must be associated with roles. When you perform one of these actions, you must explicitly pass the `leader_cluster_role` and `follower_cluster_role` in the request, which OpenSearch then uses in all backend replication tasks. To enable non-admins to start replication and create replication rules, create an identical user on each cluster (for example, `replication_user`) and map them to the `cross_cluster_replication_leader_full_access` role on the remote cluster and `cross_cluster_replication_follower_full_access` on the follower cluster. For instructions, see [Map users to roles]({{site.url}}{{site.baseurl}}/security-plugin/access-control/users-roles/#map-users-to-roles). From 4b23a1a36ec8210efbfbe77d526b7bf383ff31d7 Mon Sep 17 00:00:00 2001 From: ashwinkumar12345 Date: Mon, 4 Oct 2021 14:11:45 -0700 Subject: [PATCH 116/167] incorporated feedback --- _monitoring-plugins/ad/api.md | 1061 ++++++++++++++-------------- _monitoring-plugins/ad/settings.md | 12 +- 2 files changed, 532 insertions(+), 541 deletions(-) diff --git a/_monitoring-plugins/ad/api.md b/_monitoring-plugins/ad/api.md index d434ec7d..b6aaefe5 100644 --- a/_monitoring-plugins/ad/api.md +++ b/_monitoring-plugins/ad/api.md @@ -256,6 +256,530 @@ Options | Description | Type | Required --- +## Get detector +Introduced 1.0 +{: .label .label-purple } + +Returns all information about a detector based on the `detector_id`. + +#### Request + +```json +GET _plugins/_anomaly_detection/detectors/ +``` + +#### Sample response + +```json +{ + "_id" : "m4ccEnIBTXsGi3mvMt9p", + "_version" : 1, + "_primary_term" : 1, + "_seq_no" : 3, + "anomaly_detector" : { + "name" : "test-detector", + "description" : "Test detector", + "time_field" : "timestamp", + "indices" : [ + "order*" + ], + "filter_query" : { + "bool" : { + "filter" : [ + { + "exists" : { + "field" : "value", + "boost" : 1.0 + } + } + ], + "adjust_pure_negative" : true, + "boost" : 1.0 + } + }, + "detection_interval" : { + "period" : { + "interval" : 1, + "unit" : "Minutes" + } + }, + "window_delay" : { + "period" : { + "interval" : 1, + "unit" : "Minutes" + } + }, + "schema_version" : 0, + "feature_attributes" : [ + { + "feature_id" : "mYccEnIBTXsGi3mvMd8_", + "feature_name" : "total_order", + "feature_enabled" : true, + "aggregation_query" : { + "total_order" : { + "sum" : { + "field" : "value" + } + } + } + } + ], + "last_update_time" : 1589441737319 + } +} +``` + + +Use `job=true` to get anomaly detection job information. + +#### Request + +```json +GET _plugins/_anomaly_detection/detectors/?job=true +``` + +#### Sample response + +```json +{ + "_id": "LJxGsXcBoDQA8W1Q--A1", + "_version": 1, + "_primary_term": 1, + "_seq_no": 0, + "anomaly_detector": { + "name": "test2", + "description": "test", + "time_field": "timestamp", + "indices": [ + "server_log" + ], + "filter_query": { + "match_all": { + "boost": 1 + } + }, + "detection_interval": { + "period": { + "interval": 1, + "unit": "Minutes" + } + }, + "window_delay": { + "period": { + "interval": 1, + "unit": "Minutes" + } + }, + "shingle_size": 8, + "schema_version": 0, + "feature_attributes": [ + { + "feature_id": "K5xGsXcBoDQA8W1Q-uCF", + "feature_name": "F1", + "feature_enabled": "true", + "aggregation_query": { + "f_1": { + "sum": { + "field": "value" + } + } + } + } + ], + "last_update_time": 1613586955060, + "detector_type": "MULTI_ENTITY" + }, + "anomaly_detector_job": { + "name": "LJxGsXcBoDQA8W1Q--A1", + "schedule": { + "interval": { + "start_time": 1613587220387, + "period": 1, + "unit": "Minutes" + } + }, + "window_delay": { + "period": { + "interval": 1, + "unit": "Minutes" + } + }, + "enabled": "false", + "enabled_time": 1613587220387, + "last_update_time": 1613587289169, + "lock_duration_seconds": 60, + "disabled_time": 1613587289169 + }, + "anomaly_detection_task": { + "task_id": "WZ5LsXcBoDQA8W1QmUa3", + "last_update_time": 1613587349022, + "error": "Task cancelled by user", + "state": "STOPPED", + "detector_id": "LJxGsXcBoDQA8W1Q--A1", + "task_progress": 0.26321793, + "init_progress": 1, + "current_piece": 1611030900000, + "execution_start_time": 1613587257783, + "execution_end_time": 1613587349022, + "is_latest": "true", + "task_type": "HISTORICAL", + "coordinating_node": "NSw5j-3YQeGkH8KESVKlzw", + "worker_node": "NSw5j-3YQeGkH8KESVKlzw", + "detector": { + "name": "test2", + "description": "test", + "time_field": "timestamp", + "indices": [ + "server_log" + ], + "filter_query": { + "match_all": { + "boost": 1 + } + }, + "detection_interval": { + "period": { + "interval": 1, + "unit": "Minutes" + } + }, + "window_delay": { + "period": { + "interval": 1, + "unit": "Minutes" + } + }, + "shingle_size": 8, + "schema_version": 0, + "feature_attributes": [ + { + "feature_id": "K5xGsXcBoDQA8W1Q-uCF", + "feature_name": "F1", + "feature_enabled": "true", + "aggregation_query": { + "f_1": { + "sum": { + "field": "value" + } + } + } + } + ], + "last_update_time": 1613586955060, + "detector_type": "MULTI_ENTITY" + } + } +} +``` + +Use `task=true` to get historical analysis task information. + +#### Request + +```json +GET _plugins/_anomaly_detection/detectors/?task=true +``` + +#### Sample response + +```json +{ + "_id": "BwzKQXcB89DLS7G9rg7Y", + "_version": 1, + "_primary_term": 2, + "_seq_no": 10, + "anomaly_detector": { + "name": "test-ylwu1", + "description": "test", + "time_field": "timestamp", + "indices": [ + "ser*" + ], + "filter_query": { + "match_all": { + "boost": 1 + } + }, + "detection_interval": { + "period": { + "interval": 10, + "unit": "Minutes" + } + }, + "window_delay": { + "period": { + "interval": 1, + "unit": "Minutes" + } + }, + "shingle_size": 8, + "schema_version": 0, + "feature_attributes": [ + { + "feature_id": "BgzKQXcB89DLS7G9rg7G", + "feature_name": "F1", + "feature_enabled": true, + "aggregation_query": { + "f_1": { + "sum": { + "field": "value" + } + } + } + } + ], + "ui_metadata": { + "features": { + "F1": { + "aggregationBy": "sum", + "aggregationOf": "value", + "featureType": "simple_aggs" + } + } + }, + "last_update_time": 1611716538071, + "user": { + "name": "admin", + "backend_roles": [ + "admin" + ], + "roles": [ + "all_access", + "own_index" + ], + "custom_attribute_names": [], + "user_requested_tenant": "__user__" + }, + "detector_type": "HISTORICAL_SINGLE_ENTITY", + "detection_date_range": { + "start_time": 1580094137997, + "end_time": 1611716537997 + } + }, + "anomaly_detection_task": { + "task_id": "sgxaRXcB89DLS7G9RfIO", + "last_update_time": 1611776648699, + "started_by": "admin", + "state": "FINISHED", + "detector_id": "BwzKQXcB89DLS7G9rg7Y", + "task_progress": 1, + "init_progress": 1, + "current_piece": 1611716400000, + "execution_start_time": 1611776279822, + "execution_end_time": 1611776648679, + "is_latest": true, + "task_type": "HISTORICAL", + "coordinating_node": "gs213KqjS4q7H4Bmn_ZuLA", + "worker_node": "PgfR3JhbT7yJMx7bwQ6E3w", + "detector": { + "name": "test-ylwu1", + "description": "test", + "time_field": "timestamp", + "indices": [ + "ser*" + ], + "filter_query": { + "match_all": { + "boost": 1 + } + }, + "detection_interval": { + "period": { + "interval": 10, + "unit": "Minutes" + } + }, + "window_delay": { + "period": { + "interval": 1, + "unit": "Minutes" + } + }, + "shingle_size": 8, + "schema_version": 0, + "feature_attributes": [ + { + "feature_id": "BgzKQXcB89DLS7G9rg7G", + "feature_name": "F1", + "feature_enabled": true, + "aggregation_query": { + "f_1": { + "sum": { + "field": "value" + } + } + } + } + ], + "ui_metadata": { + "features": { + "F1": { + "aggregationBy": "sum", + "aggregationOf": "value", + "featureType": "simple_aggs" + } + } + }, + "last_update_time": 1611716538071, + "user": { + "name": "admin", + "backend_roles": [ + "admin" + ], + "roles": [ + "all_access", + "own_index" + ], + "custom_attribute_names": [], + "user_requested_tenant": "__user__" + }, + "detector_type": "HISTORICAL_SINGLE_ENTITY", + "detection_date_range": { + "start_time": 1580094137997, + "end_time": 1611716537997 + } + }, + "user": { + "name": "admin", + "backend_roles": [ + "admin" + ], + "roles": [ + "all_access", + "own_index" + ], + "custom_attribute_names": [], + "user_requested_tenant": "__user__" + } + } +} +``` + +--- + +## Update detector +Introduced 1.0 +{: .label .label-purple } + +Updates a detector with any changes, including the description or adding or removing of features. +To update a detector, you need to first stop the detector. + +#### Request + +```json +PUT _plugins/_anomaly_detection/detectors/ +{ + "name": "test-detector", + "description": "Test detector", + "time_field": "timestamp", + "indices": [ + "order*" + ], + "feature_attributes": [ + { + "feature_name": "total_order", + "feature_enabled": true, + "aggregation_query": { + "total_order": { + "sum": { + "field": "value" + } + } + } + } + ], + "filter_query": { + "bool": { + "filter": [ + { + "exists": { + "field": "value", + "boost": 1 + } + } + ], + "adjust_pure_negative": true, + "boost": 1 + } + }, + "detection_interval": { + "period": { + "interval": 10, + "unit": "MINUTES" + } + }, + "window_delay": { + "period": { + "interval": 1, + "unit": "MINUTES" + } + } +} +``` + + +#### Sample response + +```json +{ + "_id" : "m4ccEnIBTXsGi3mvMt9p", + "_version" : 2, + "_seq_no" : 4, + "_primary_term" : 1, + "anomaly_detector" : { + "name" : "test-detector", + "description" : "Test detector", + "time_field" : "timestamp", + "indices" : [ + "order*" + ], + "filter_query" : { + "bool" : { + "filter" : [ + { + "exists" : { + "field" : "value", + "boost" : 1.0 + } + } + ], + "adjust_pure_negative" : true, + "boost" : 1.0 + } + }, + "detection_interval" : { + "period" : { + "interval" : 10, + "unit" : "Minutes" + } + }, + "window_delay" : { + "period" : { + "interval" : 1, + "unit" : "Minutes" + } + }, + "schema_version" : 0, + "feature_attributes" : [ + { + "feature_id" : "xxokEnIBcpeWMD987A1X", + "feature_name" : "total_order", + "feature_enabled" : true, + "aggregation_query" : { + "total_order" : { + "sum" : { + "field" : "value" + } + } + } + } + ] + } +} +``` + +--- + ## Preview detector Introduced 1.0 {: .label .label-purple } @@ -937,15 +1461,6 @@ GET _plugins/_anomaly_detection/detectors/results/_search } ``` -You can specify the following options. - -Options | Description | Type | Required -:--- | :--- |:--- |:--- | -`anomalyThreshold` | Specify a threshold to filter out low anomaly grade results. Default is -1. Because the lowest possible anomaly grade is 0, -1 means that the detector returns all results. | `float` | No -`dateRangeFilter` | Specify the date range in:
- `startTime` (int): Start time to collect results. Add in milliseconds since the Unix Epoch.
- `endTime` (int): End time to collect results. Add in milliseconds since the Unix Epoch.
- `fieldName` (string): The field that you want to match the start and end time. | `object` | Yes -`entity` | Specify the entity name and value. Default is empty.
- `name` (string): Field name that you want to search in.
- `value` (string): Entity value that you want to search for. | `object` | No -`sort` | Sort the result by a field in a certain order. Default is empty. Properties of `sort`:
- `direction` (string): Specify "desc" or "asc" for descending or ascending order.
- `field` (string): Order the results by a field. | `object` | No - --- ## Search detector tasks @@ -1228,530 +1743,6 @@ DELETE _plugins/_anomaly_detection/detectors/results } ``` ---- - - -## Update detector -Introduced 1.0 -{: .label .label-purple } - -Updates a detector with any changes, including the description or adding or removing of features. -To update a detector, you need to first stop the detector. - -#### Request - -```json -PUT _plugins/_anomaly_detection/detectors/ -{ - "name": "test-detector", - "description": "Test detector", - "time_field": "timestamp", - "indices": [ - "order*" - ], - "feature_attributes": [ - { - "feature_name": "total_order", - "feature_enabled": true, - "aggregation_query": { - "total_order": { - "sum": { - "field": "value" - } - } - } - } - ], - "filter_query": { - "bool": { - "filter": [ - { - "exists": { - "field": "value", - "boost": 1 - } - } - ], - "adjust_pure_negative": true, - "boost": 1 - } - }, - "detection_interval": { - "period": { - "interval": 10, - "unit": "MINUTES" - } - }, - "window_delay": { - "period": { - "interval": 1, - "unit": "MINUTES" - } - } -} -``` - - -#### Sample response - -```json -{ - "_id" : "m4ccEnIBTXsGi3mvMt9p", - "_version" : 2, - "_seq_no" : 4, - "_primary_term" : 1, - "anomaly_detector" : { - "name" : "test-detector", - "description" : "Test detector", - "time_field" : "timestamp", - "indices" : [ - "order*" - ], - "filter_query" : { - "bool" : { - "filter" : [ - { - "exists" : { - "field" : "value", - "boost" : 1.0 - } - } - ], - "adjust_pure_negative" : true, - "boost" : 1.0 - } - }, - "detection_interval" : { - "period" : { - "interval" : 10, - "unit" : "Minutes" - } - }, - "window_delay" : { - "period" : { - "interval" : 1, - "unit" : "Minutes" - } - }, - "schema_version" : 0, - "feature_attributes" : [ - { - "feature_id" : "xxokEnIBcpeWMD987A1X", - "feature_name" : "total_order", - "feature_enabled" : true, - "aggregation_query" : { - "total_order" : { - "sum" : { - "field" : "value" - } - } - } - } - ] - } -} -``` - ---- - -## Get detector -Introduced 1.0 -{: .label .label-purple } - -Returns all information about a detector based on the `detector_id`. - -#### Request - -```json -GET _plugins/_anomaly_detection/detectors/ -``` - -#### Sample response - -```json -{ - "_id" : "m4ccEnIBTXsGi3mvMt9p", - "_version" : 1, - "_primary_term" : 1, - "_seq_no" : 3, - "anomaly_detector" : { - "name" : "test-detector", - "description" : "Test detector", - "time_field" : "timestamp", - "indices" : [ - "order*" - ], - "filter_query" : { - "bool" : { - "filter" : [ - { - "exists" : { - "field" : "value", - "boost" : 1.0 - } - } - ], - "adjust_pure_negative" : true, - "boost" : 1.0 - } - }, - "detection_interval" : { - "period" : { - "interval" : 1, - "unit" : "Minutes" - } - }, - "window_delay" : { - "period" : { - "interval" : 1, - "unit" : "Minutes" - } - }, - "schema_version" : 0, - "feature_attributes" : [ - { - "feature_id" : "mYccEnIBTXsGi3mvMd8_", - "feature_name" : "total_order", - "feature_enabled" : true, - "aggregation_query" : { - "total_order" : { - "sum" : { - "field" : "value" - } - } - } - } - ], - "last_update_time" : 1589441737319 - } -} -``` - - -Use `job=true` to get anomaly detection job information. - -#### Request - -```json -GET _plugins/_anomaly_detection/detectors/?job=true -``` - -#### Sample response - -```json -{ - "_id": "LJxGsXcBoDQA8W1Q--A1", - "_version": 1, - "_primary_term": 1, - "_seq_no": 0, - "anomaly_detector": { - "name": "test2", - "description": "test", - "time_field": "timestamp", - "indices": [ - "server_log" - ], - "filter_query": { - "match_all": { - "boost": 1 - } - }, - "detection_interval": { - "period": { - "interval": 1, - "unit": "Minutes" - } - }, - "window_delay": { - "period": { - "interval": 1, - "unit": "Minutes" - } - }, - "shingle_size": 8, - "schema_version": 0, - "feature_attributes": [ - { - "feature_id": "K5xGsXcBoDQA8W1Q-uCF", - "feature_name": "F1", - "feature_enabled": "true", - "aggregation_query": { - "f_1": { - "sum": { - "field": "value" - } - } - } - } - ], - "last_update_time": 1613586955060, - "detector_type": "MULTI_ENTITY" - }, - "anomaly_detector_job": { - "name": "LJxGsXcBoDQA8W1Q--A1", - "schedule": { - "interval": { - "start_time": 1613587220387, - "period": 1, - "unit": "Minutes" - } - }, - "window_delay": { - "period": { - "interval": 1, - "unit": "Minutes" - } - }, - "enabled": "false", - "enabled_time": 1613587220387, - "last_update_time": 1613587289169, - "lock_duration_seconds": 60, - "disabled_time": 1613587289169 - }, - "anomaly_detection_task": { - "task_id": "WZ5LsXcBoDQA8W1QmUa3", - "last_update_time": 1613587349022, - "error": "Task cancelled by user", - "state": "STOPPED", - "detector_id": "LJxGsXcBoDQA8W1Q--A1", - "task_progress": 0.26321793, - "init_progress": 1, - "current_piece": 1611030900000, - "execution_start_time": 1613587257783, - "execution_end_time": 1613587349022, - "is_latest": "true", - "task_type": "HISTORICAL", - "coordinating_node": "NSw5j-3YQeGkH8KESVKlzw", - "worker_node": "NSw5j-3YQeGkH8KESVKlzw", - "detector": { - "name": "test2", - "description": "test", - "time_field": "timestamp", - "indices": [ - "server_log" - ], - "filter_query": { - "match_all": { - "boost": 1 - } - }, - "detection_interval": { - "period": { - "interval": 1, - "unit": "Minutes" - } - }, - "window_delay": { - "period": { - "interval": 1, - "unit": "Minutes" - } - }, - "shingle_size": 8, - "schema_version": 0, - "feature_attributes": [ - { - "feature_id": "K5xGsXcBoDQA8W1Q-uCF", - "feature_name": "F1", - "feature_enabled": "true", - "aggregation_query": { - "f_1": { - "sum": { - "field": "value" - } - } - } - } - ], - "last_update_time": 1613586955060, - "detector_type": "MULTI_ENTITY" - } - } -} -``` - -Use `task=true` to get historical analysis task information. - -#### Request - -```json -GET _plugins/_anomaly_detection/detectors/?task=true -``` - -#### Sample response - -```json -{ - "_id": "BwzKQXcB89DLS7G9rg7Y", - "_version": 1, - "_primary_term": 2, - "_seq_no": 10, - "anomaly_detector": { - "name": "test-ylwu1", - "description": "test", - "time_field": "timestamp", - "indices": [ - "ser*" - ], - "filter_query": { - "match_all": { - "boost": 1 - } - }, - "detection_interval": { - "period": { - "interval": 10, - "unit": "Minutes" - } - }, - "window_delay": { - "period": { - "interval": 1, - "unit": "Minutes" - } - }, - "shingle_size": 8, - "schema_version": 0, - "feature_attributes": [ - { - "feature_id": "BgzKQXcB89DLS7G9rg7G", - "feature_name": "F1", - "feature_enabled": true, - "aggregation_query": { - "f_1": { - "sum": { - "field": "value" - } - } - } - } - ], - "ui_metadata": { - "features": { - "F1": { - "aggregationBy": "sum", - "aggregationOf": "value", - "featureType": "simple_aggs" - } - } - }, - "last_update_time": 1611716538071, - "user": { - "name": "admin", - "backend_roles": [ - "admin" - ], - "roles": [ - "all_access", - "own_index" - ], - "custom_attribute_names": [], - "user_requested_tenant": "__user__" - }, - "detector_type": "HISTORICAL_SINGLE_ENTITY", - "detection_date_range": { - "start_time": 1580094137997, - "end_time": 1611716537997 - } - }, - "anomaly_detection_task": { - "task_id": "sgxaRXcB89DLS7G9RfIO", - "last_update_time": 1611776648699, - "started_by": "admin", - "state": "FINISHED", - "detector_id": "BwzKQXcB89DLS7G9rg7Y", - "task_progress": 1, - "init_progress": 1, - "current_piece": 1611716400000, - "execution_start_time": 1611776279822, - "execution_end_time": 1611776648679, - "is_latest": true, - "task_type": "HISTORICAL", - "coordinating_node": "gs213KqjS4q7H4Bmn_ZuLA", - "worker_node": "PgfR3JhbT7yJMx7bwQ6E3w", - "detector": { - "name": "test-ylwu1", - "description": "test", - "time_field": "timestamp", - "indices": [ - "ser*" - ], - "filter_query": { - "match_all": { - "boost": 1 - } - }, - "detection_interval": { - "period": { - "interval": 10, - "unit": "Minutes" - } - }, - "window_delay": { - "period": { - "interval": 1, - "unit": "Minutes" - } - }, - "shingle_size": 8, - "schema_version": 0, - "feature_attributes": [ - { - "feature_id": "BgzKQXcB89DLS7G9rg7G", - "feature_name": "F1", - "feature_enabled": true, - "aggregation_query": { - "f_1": { - "sum": { - "field": "value" - } - } - } - } - ], - "ui_metadata": { - "features": { - "F1": { - "aggregationBy": "sum", - "aggregationOf": "value", - "featureType": "simple_aggs" - } - } - }, - "last_update_time": 1611716538071, - "user": { - "name": "admin", - "backend_roles": [ - "admin" - ], - "roles": [ - "all_access", - "own_index" - ], - "custom_attribute_names": [], - "user_requested_tenant": "__user__" - }, - "detector_type": "HISTORICAL_SINGLE_ENTITY", - "detection_date_range": { - "start_time": 1580094137997, - "end_time": 1611716537997 - } - }, - "user": { - "name": "admin", - "backend_roles": [ - "admin" - ], - "roles": [ - "all_access", - "own_index" - ], - "custom_attribute_names": [], - "user_requested_tenant": "__user__" - } - } -} -``` --- @@ -2031,7 +2022,7 @@ For historical analysis, you see the values for the following fields: - `ad_canceled_batch_task_count` - `ad_batch_task_failure_count` -For real-time analysis, these values are 0. +If haven't run any historical analysis, these values show up as 0. #### Sample response @@ -3237,7 +3228,7 @@ GET _plugins/_anomaly_detection/detectors//_profile?_all=true } ``` -For historical analysis, specify `_all` or `ad_task` to see information about its latest task: +To get profile information for only historical analysis, specify `ad_task`: #### Request diff --git a/_monitoring-plugins/ad/settings.md b/_monitoring-plugins/ad/settings.md index eaebdee2..5aa73dc4 100644 --- a/_monitoring-plugins/ad/settings.md +++ b/_monitoring-plugins/ad/settings.md @@ -35,13 +35,13 @@ Setting | Default | Description `plugins.anomaly_detection.max_entities_for_preview` | 5 | The maximum unique category field values displayed with the preview operation for high cardinality detectors. By default, if the category field(s) have more than the configured unique values in a detector interval, the anomaly detection plugin orders them by the natural ordering of categorical values (for example, entity `ab` comes before `bc`) and then selects the top values. `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 anomaly detection plugin filters results based on the user's backend role(s). -`plugins.anomaly_detection.max_batch_task_per_node` | 10 | 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 1,000. 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` | 1 | 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.max_batch_task_per_node` | 10 | Starting a historical analysis 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 1,000. 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 analysis, add more data nodes instead of changing this setting to a higher value. Increasing this value might bring more load on each data node. +`plugins.anomaly_detection.max_old_ad_task_docs_per_detector` | 1 | You can run historical analysis for the same 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` | 1,000 | 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 1,000 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. -`plugins.anomaly_detection.max_top_entities_for_historical_analysis` | 1,000 | The maximum number of top entities that you run for a high cardinality detector historical analysis. -`plugins.anomaly_detection.max_running_entities_per_detector_for_historical_analysis` | 10 | The number of entity tasks that you can run in parallel for a single high cardinality detector. The task slots available on your cluster also impact how many entities run in parallel. If a cluster has 3 data nodes, each data node has 10 task slots by default. Say you already have two high cardinality detectors and each of them run 10 entities. If you start a single-flow detector that takes 1 task slot, the number of task slots available is 10 * 3 - 10 * 2 - 1 = 9. if you now start a new high cardinality detector, the detector can only run 9 entities in parallel and not 10. -`plugins.anomaly_detection.max_cached_deleted_tasks` | 1,000 | You can rerun historical analysis for a single detector as many times as you like. The anomaly detection plugin only keeps a limited number of old tasks, by default 1 old task. If you run historical analysis three times for a detector, the oldest task is deleted. Because historical analysis generates a number of anomaly results in a short span of time, it's necessary to clean up anomaly results for a deleted task. With this field, you can configure how many deleted tasks you can cache at most. The plugin cleans up a task's results when it's deleted. If the plugin fails to do this cleanup, it adds the task's results into a cache and an hourly cron job performs the cleanup. After an hour, if still you find an old task result in the cache, use the [delete detector results API]({{site.url}}{{site.baseurl}}/monitoring-plugins/ad/api/#delete-detector-results) to delete the task result manually. +`plugins.anomaly_detection.batch_task_piece_interval_seconds` | 5 | Add a time interval between two pieces of the same historical analysis task. 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. +`plugins.anomaly_detection.max_top_entities_for_historical_analysis` | 1,000 | The maximum number of top entities that you run for a high cardinality detector historical analysis. The range is from 1 to 10,000. +`plugins.anomaly_detection.max_running_entities_per_detector_for_historical_analysis` | 10 | The number of entity tasks that you can run in parallel for a single high cardinality detector. The task slots available on your cluster also impact how many entities run in parallel. If a cluster has 3 data nodes, each data node has 10 task slots by default. Say you already have two high cardinality detectors and each of them run 10 entities. If you start a single-flow detector that takes 1 task slot, the number of task slots available is 10 * 3 - 10 * 2 - 1 = 9. if you now start a new high cardinality detector, the detector can only run 9 entities in parallel and not 10. You can tune this value from 1 to 1,000 based on your cluster's capability. If you set a higher value, the anomaly detection plugin runs historical analysis faster but also consumes more resources. +`plugins.anomaly_detection.max_cached_deleted_tasks` | 1,000 | You can rerun historical analysis for a single detector as many times as you like. The anomaly detection plugin only keeps a limited number of old tasks, by default 1 old task. If you run historical analysis three times for a detector, the oldest task is deleted. Because historical analysis generates a number of anomaly results in a short span of time, it's necessary to clean up anomaly results for a deleted task. With this field, you can configure how many deleted tasks you can cache at most. The plugin cleans up a task's results when it's deleted. If the plugin fails to do this cleanup, it adds the task's results into a cache and an hourly cron job performs the cleanup. You can use this setting to limit how many old tasks are put into cache to avoid a DDoS attack. After an hour, if still you find an old task result in the cache, use the [delete detector results API]({{site.url}}{{site.baseurl}}/monitoring-plugins/ad/api/#delete-detector-results) to delete the task result manually. You can tune this setting from 1 to 10,000. `plugins.anomaly_detection.delete_anomaly_result_when_delete_detector` | False | Whether the anomaly detection plugin deletes the anomaly result when you delete a detector. If you want to save some disk space, especially if you've high cardinality detectors generating a lot of results, set this field to true. Alternatively, you can use the [delete detector results API]({{site.url}}{{site.baseurl}}/monitoring-plugins/ad/api/#delete-detector-results) to manually delete the results. `plugins.anomaly_detection.dedicated_cache_size` | 10 | If the real-time analysis of a high cardinality detector starts successfully, the anomaly detection plugin guarantees keeping 10 (dynamically adjustable via this setting) entities' models in memory per node. If the number of entities exceeds this limit, the plugin puts the extra entities' models in a memory space shared by all detectors. The actual number of entities varies based on the memory that you've available and the frequencies of the entities. If you'd like the plugin to guarantee keeping more entities' models in memory and if you're cluster has sufficient memory, you can increase this setting value. `plugins.anomaly_detection.max_concurrent_preview` | 2 | The maximum number of concurrent previews. You can use this setting to limit resource usage. From f3897b621cde2bc812f55d4eab3bdf739fe92339 Mon Sep 17 00:00:00 2001 From: ashwinkumar12345 Date: Mon, 4 Oct 2021 14:18:04 -0700 Subject: [PATCH 117/167] minor change --- _monitoring-plugins/ad/api.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/_monitoring-plugins/ad/api.md b/_monitoring-plugins/ad/api.md index b6aaefe5..57dadd6f 100644 --- a/_monitoring-plugins/ad/api.md +++ b/_monitoring-plugins/ad/api.md @@ -3186,7 +3186,7 @@ For a single-entity detector: The `total_entities` parameter shows you the total number of entities including the number of category fields for a detector. -Getting the total count of entities is an expensive operation for a detector with more than one category field. By default, a real-time detector counts the number of entities up to a value of 10,000 and historical analysis counts the number of entities up to a value of 1,000. +Getting the total count of entities is an expensive operation for real-time analysis of a detector with more than one category field. By default, for a real-time detection profile, a detector counts the number of entities up to a value of 10,000 and historical analysis counts the number of entities up to a value of 1,000. The `profile` operation also provides information about each entity, such as the entity’s `last_sample_timestamp` and `last_active_timestamp`. `last_sample_timestamp` shows the last document in the input data source index containing the entity, while `last_active_timestamp` shows the timestamp when the entity’s model was last seen in the model cache. @@ -3228,7 +3228,8 @@ GET _plugins/_anomaly_detection/detectors//_profile?_all=true } ``` -To get profile information for only historical analysis, specify `ad_task`: +To get profile information for only historical analysis, specify `ad_task`. +Specifying `_all` is an expensive operation for multi-category high cardinality detectors. #### Request From 074f1601978aced7cca9669045aa81adbe02cc2c Mon Sep 17 00:00:00 2001 From: ashwinkumar12345 Date: Mon, 4 Oct 2021 14:21:36 -0700 Subject: [PATCH 118/167] minor fix --- _monitoring-plugins/ad/api.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/_monitoring-plugins/ad/api.md b/_monitoring-plugins/ad/api.md index 57dadd6f..f99825fd 100644 --- a/_monitoring-plugins/ad/api.md +++ b/_monitoring-plugins/ad/api.md @@ -2790,7 +2790,7 @@ GET _plugins/_anomaly_detection/detectors//_profile/total_size_in_by You can see the `ad_task` field only for historical analysis. -The `model_count` parameter shows the total number of models that a detector runs in memory. This is useful if you have several models running on your cluster and want to know the count. +The `model_count` parameter shows the total number of models that a detector runs on each node’s memory. This is useful if you have several models running on your cluster and want to know the count. If you configured the category field, you can see the number of unique values in the field and all active entities with models running in memory. @@ -3186,7 +3186,7 @@ For a single-entity detector: The `total_entities` parameter shows you the total number of entities including the number of category fields for a detector. -Getting the total count of entities is an expensive operation for real-time analysis of a detector with more than one category field. By default, for a real-time detection profile, a detector counts the number of entities up to a value of 10,000 and historical analysis counts the number of entities up to a value of 1,000. +Getting the total count of entities is an expensive operation for real-time analysis of a detector with more than one category field. By default, for a real-time detection profile, a detector counts the number of entities up to a value of 10,000. For historical analysis, the anomaly detection plugin only detects the top 1,000 entities by default and caches the top entities in memory to reduce the cost of getting the total count of entities for historical analysis. The `profile` operation also provides information about each entity, such as the entity’s `last_sample_timestamp` and `last_active_timestamp`. `last_sample_timestamp` shows the last document in the input data source index containing the entity, while `last_active_timestamp` shows the timestamp when the entity’s model was last seen in the model cache. From f57469e0f79284bc6de4dd6e0e62ff58d3b0b06f Mon Sep 17 00:00:00 2001 From: Liz Snyder Date: Mon, 4 Oct 2021 17:08:58 -0700 Subject: [PATCH 119/167] Add back Docker sample --- _replication-plugin/auto-follow.md | 2 +- _replication-plugin/get-started.md | 16 +++------------- 2 files changed, 4 insertions(+), 14 deletions(-) diff --git a/_replication-plugin/auto-follow.md b/_replication-plugin/auto-follow.md index 4af6c61f..fd2e69b4 100644 --- a/_replication-plugin/auto-follow.md +++ b/_replication-plugin/auto-follow.md @@ -48,7 +48,7 @@ If the security plugin is disabled, you can leave out the `use_roles` parameter. To test the rule, create a matching index on the leader cluster: ```bash -curl -XPUT -k -H 'Content-Type: application/json' -u 'admin:admin' 'https://localhost:9201/movies-0001' +curl -XPUT -k -H 'Content-Type: application/json' -u 'admin:admin' 'https://localhost:9201/movies-0001?pretty' ``` And confirm its replica shows up on the follower cluster: diff --git a/_replication-plugin/get-started.md b/_replication-plugin/get-started.md index e6b3c36a..2ab9d755 100644 --- a/_replication-plugin/get-started.md +++ b/_replication-plugin/get-started.md @@ -32,9 +32,6 @@ plugins.security.nodes_dn_dynamic_config_enabled: true ## Example setup -The following example demonstrates how to replicate data between two single-node clusters: `leader-cluster` on port 9201, and `follower-cluster` on port 9200. -{% comment %} - Save this sample file as `docker-compose.yml` and run `docker-compose up` to start two single-node clusters on the same network: ```yml @@ -89,26 +86,20 @@ networks: After the clusters start, verify the names of each: -{% endcomment %} - ```bash curl -XGET -u 'admin:admin' -k 'https://localhost:9201' { - "name" : "replication-node1", "cluster_name" : "leader-cluster", ... } curl -XGET -u 'admin:admin' -k 'https://localhost:9200' { - "name" : "replication-node2", "cluster_name" : "follower-cluster", ... } ``` -{% comment %} - For this example, use port 9201 (`replication-node1`) as the leader and port 9200 (`replication-node2`) as the follower cluster. To get the IP address for the leader cluster, first identify its container ID: @@ -116,8 +107,8 @@ To get the IP address for the leader cluster, first identify its container ID: ```bash docker ps CONTAINER ID IMAGE PORTS NAMES -3b8cdc698be5 opensearchproject/opensearch:{{site.opensearch_version}} 0.0.0.0:9200->9200/tcp, 0.0.0.0:9600->9600/tcp, 9300/tcp replication-node1 -731f5e8b0f4b opensearchproject/opensearch:{{site.opensearch_version}} 9300/tcp, 0.0.0.0:9201->9200/tcp, 0.0.0.0:9700->9600/tcp replication-node2 +3b8cdc698be5 opensearchproject/opensearch:{{site.opensearch_version}} 0.0.0.0:9200->9200/tcp, 0.0.0.0:9600->9600/tcp, 9300/tcp replication-node2 +731f5e8b0f4b opensearchproject/opensearch:{{site.opensearch_version}} 9300/tcp, 0.0.0.0:9201->9200/tcp, 0.0.0.0:9700->9600/tcp replication-node1 ``` Then get that container's IP address: @@ -126,7 +117,6 @@ Then get that container's IP address: docker inspect --format='{% raw %}{{range .NetworkSettings.Networks}}{{.IPAddress}}{{end}}{% endraw %}' 731f5e8b0f4b 172.22.0.3 ``` -{% endcomment %} ## Set up a cross-cluster connection @@ -261,7 +251,7 @@ When replication resumes, the follower index picks up any changes that were made Terminate replication of a specified index from the follower cluster: ```bash -curl -XPOST -k -H 'Content-Type: application/json' -u 'admin:admin' 'https://localhost:9200/_plugins/_replication/follower-01/_stop' -d '{}' +curl -XPOST -k -H 'Content-Type: application/json' -u 'admin:admin' 'https://localhost:9200/_plugins/_replication/follower-01/_stop?pretty' -d '{}' ``` When you stop replication, the follower index un-follows the leader and becomes a standard index that you can write to. You can't restart replication after stopping it. From a23cdb91aeced6df567216c70143b8c880e48c6e Mon Sep 17 00:00:00 2001 From: ashwinkumar12345 Date: Tue, 5 Oct 2021 02:36:58 -0700 Subject: [PATCH 120/167] updated requests and responses --- _monitoring-plugins/ad/api.md | 4237 +++++++++++++--------------- _monitoring-plugins/ad/index.md | 2 +- _monitoring-plugins/ad/settings.md | 2 +- 3 files changed, 2032 insertions(+), 2209 deletions(-) diff --git a/_monitoring-plugins/ad/api.md b/_monitoring-plugins/ad/api.md index f99825fd..46c12c28 100644 --- a/_monitoring-plugins/ad/api.md +++ b/_monitoring-plugins/ad/api.md @@ -24,8 +24,7 @@ Introduced 1.0 Creates an anomaly detector. -This command creates a detector named `test-detector` that finds anomalies based on the sum of the `value` field: - +This command creates a single-flow detector named `test-detector` that finds anomalies based on the sum of the `value` field: #### Request @@ -36,14 +35,14 @@ POST _plugins/_anomaly_detection/detectors "description": "Test detector", "time_field": "timestamp", "indices": [ - "order*" + "server_log*" ], "feature_attributes": [ { - "feature_name": "total_order", + "feature_name": "test", "feature_enabled": true, "aggregation_query": { - "total_order": { + "test": { "sum": { "field": "value" } @@ -55,9 +54,10 @@ POST _plugins/_anomaly_detection/detectors "bool": { "filter": [ { - "exists": { - "field": "value", - "boost": 1 + "range": { + "value": { + "gt": 1 + } } } ], @@ -84,24 +84,28 @@ POST _plugins/_anomaly_detection/detectors ```json { - "_id": "m4ccEnIBTXsGi3mvMt9p", + "_id": "VEHKTXwBwf_U8gjUXY2s", "_version": 1, - "_seq_no": 3, - "_primary_term": 1, + "_seq_no": 5, "anomaly_detector": { "name": "test-detector", "description": "Test detector", "time_field": "timestamp", "indices": [ - "order*" + "server_log*" ], "filter_query": { "bool": { "filter": [ { - "exists": { - "field": "value", - "boost": 1 + "range": { + "value": { + "from": 1, + "to": null, + "include_lower": false, + "include_upper": true, + "boost": 1 + } } } ], @@ -121,66 +125,97 @@ POST _plugins/_anomaly_detection/detectors "unit": "Minutes" } }, + "shingle_size": 8, "schema_version": 0, "feature_attributes": [ { - "feature_id": "mYccEnIBTXsGi3mvMd8_", - "feature_name": "total_order", + "feature_id": "U0HKTXwBwf_U8gjUXY2m", + "feature_name": "test", "feature_enabled": true, "aggregation_query": { - "total_order": { + "test": { "sum": { "field": "value" } } } } - ] - } + ], + "last_update_time": 1633392680364, + "user": { + "name": "admin", + "backend_roles": [ + "admin" + ], + "roles": [ + "own_index", + "all_access" + ], + "custom_attribute_names": [], + "user_requested_tenant": "__user__" + }, + "detector_type": "SINGLE_ENTITY" + }, + "_primary_term": 1 } ``` -To set a category field for high cardinality: +To create high cardinality detector by specifying a category field: #### Request ```json POST _plugins/_anomaly_detection/detectors { - "name": "Host OK Rate Detector", - "description": "ok rate", - "time_field": "@timestamp", + "name": "test-hc-detector", + "description": "Test detector", + "time_field": "timestamp", "indices": [ - "host-cloudwatch" - ], - "category_field": [ - "host" + "server_log*" ], "feature_attributes": [ { - "feature_name": "latency_max", + "feature_name": "test", "feature_enabled": true, "aggregation_query": { - "latency_max": { - "max": { - "field": "latency" + "test": { + "sum": { + "field": "value" } } } } ], - "window_delay": { - "period": { - "interval": 10, - "unit": "MINUTES" + "filter_query": { + "bool": { + "filter": [ + { + "range": { + "value": { + "gt": 1 + } + } + } + ], + "adjust_pure_negative": true, + "boost": 1 } }, "detection_interval": { "period": { "interval": 1, - "unit": "MINUTES" + "unit": "Minutes" } - } + }, + "window_delay": { + "period": { + "interval": 1, + "unit": "Minutes" + } + }, + "category_field": [ + "ip" + ] } ``` @@ -188,18 +223,32 @@ POST _plugins/_anomaly_detection/detectors ```json { - "_id": "4CIGoHUBTpMGN-4KzBQg", + "_id": "b0HRTXwBwf_U8gjUw43R", "_version": 1, - "_seq_no": 0, + "_seq_no": 6, "anomaly_detector": { - "name": "Host OK Rate Detector", - "description": "ok rate", - "time_field": "@timestamp", + "name": "test-hc-detector", + "description": "Test detector", + "time_field": "timestamp", "indices": [ - "server-metrics" + "server_log*" ], "filter_query": { - "match_all": { + "bool": { + "filter": [ + { + "range": { + "value": { + "from": 1, + "to": null, + "include_lower": false, + "include_upper": true, + "boost": 1 + } + } + } + ], + "adjust_pure_negative": true, "boost": 1 } }, @@ -211,35 +260,62 @@ POST _plugins/_anomaly_detection/detectors }, "window_delay": { "period": { - "interval": 10, - "unit": "MINUTES" + "interval": 1, + "unit": "Minutes" } }, - "shingle_size": 1, - "schema_version": 2, + "shingle_size": 8, + "schema_version": 0, "feature_attributes": [ { - "feature_id": "0Kld3HUBhpHMyt2e_UHn", - "feature_name": "latency_max", + "feature_id": "bkHRTXwBwf_U8gjUw43K", + "feature_name": "test", "feature_enabled": true, "aggregation_query": { - "latency_max": { - "max": { - "field": "latency" + "test": { + "sum": { + "field": "value" } } } } ], - "last_update_time": 1604707601438, + "last_update_time": 1633393165265, "category_field": [ - "host" - ] + "ip" + ], + "user": { + "name": "admin", + "backend_roles": [ + "admin" + ], + "roles": [ + "own_index", + "all_access" + ], + "custom_attribute_names": [], + "user_requested_tenant": "__user__" + }, + "detector_type": "MULTI_ENTITY" }, "_primary_term": 1 } ``` +You can specify a maximum of two category fields: + +```json +"category_field": [ + "ip" +] +``` + +```json +"category_field": [ + "ip", "error_type" +] +``` + You can specify the following options. Options | Description | Type | Required @@ -272,65 +348,83 @@ GET _plugins/_anomaly_detection/detectors/ ```json { - "_id" : "m4ccEnIBTXsGi3mvMt9p", - "_version" : 1, - "_primary_term" : 1, - "_seq_no" : 3, - "anomaly_detector" : { - "name" : "test-detector", - "description" : "Test detector", - "time_field" : "timestamp", - "indices" : [ - "order*" + "_id": "VEHKTXwBwf_U8gjUXY2s", + "_version": 1, + "_primary_term": 1, + "_seq_no": 5, + "anomaly_detector": { + "name": "test-detector", + "description": "Test detector", + "time_field": "timestamp", + "indices": [ + "server_log*" ], - "filter_query" : { - "bool" : { - "filter" : [ + "filter_query": { + "bool": { + "filter": [ { - "exists" : { - "field" : "value", - "boost" : 1.0 + "range": { + "value": { + "from": 1, + "to": null, + "include_lower": false, + "include_upper": true, + "boost": 1 + } } } ], - "adjust_pure_negative" : true, - "boost" : 1.0 + "adjust_pure_negative": true, + "boost": 1 } }, - "detection_interval" : { - "period" : { - "interval" : 1, - "unit" : "Minutes" + "detection_interval": { + "period": { + "interval": 1, + "unit": "Minutes" } }, - "window_delay" : { - "period" : { - "interval" : 1, - "unit" : "Minutes" + "window_delay": { + "period": { + "interval": 1, + "unit": "Minutes" } }, - "schema_version" : 0, - "feature_attributes" : [ + "shingle_size": 8, + "schema_version": 0, + "feature_attributes": [ { - "feature_id" : "mYccEnIBTXsGi3mvMd8_", - "feature_name" : "total_order", - "feature_enabled" : true, - "aggregation_query" : { - "total_order" : { - "sum" : { - "field" : "value" + "feature_id": "U0HKTXwBwf_U8gjUXY2m", + "feature_name": "test", + "feature_enabled": true, + "aggregation_query": { + "test": { + "sum": { + "field": "value" } } } } ], - "last_update_time" : 1589441737319 + "last_update_time": 1633392680364, + "user": { + "name": "admin", + "backend_roles": [ + "admin" + ], + "roles": [ + "own_index", + "all_access" + ], + "custom_attribute_names": [], + "user_requested_tenant": "__user__" + }, + "detector_type": "SINGLE_ENTITY" } } ``` - -Use `job=true` to get anomaly detection job information. +Use `task=true` to get real-time analysis task information. #### Request @@ -342,19 +436,33 @@ GET _plugins/_anomaly_detection/detectors/?job=true ```json { - "_id": "LJxGsXcBoDQA8W1Q--A1", + "_id": "VEHKTXwBwf_U8gjUXY2s", "_version": 1, "_primary_term": 1, - "_seq_no": 0, + "_seq_no": 5, "anomaly_detector": { - "name": "test2", - "description": "test", + "name": "test-detector", + "description": "Test detector", "time_field": "timestamp", "indices": [ - "server_log" + "server_log*" ], "filter_query": { - "match_all": { + "bool": { + "filter": [ + { + "range": { + "value": { + "from": 1, + "to": null, + "include_lower": false, + "include_upper": true, + "boost": 1 + } + } + } + ], + "adjust_pure_negative": true, "boost": 1 } }, @@ -374,11 +482,11 @@ GET _plugins/_anomaly_detection/detectors/?job=true "schema_version": 0, "feature_attributes": [ { - "feature_id": "K5xGsXcBoDQA8W1Q-uCF", - "feature_name": "F1", - "feature_enabled": "true", + "feature_id": "U0HKTXwBwf_U8gjUXY2m", + "feature_name": "test", + "feature_enabled": true, "aggregation_query": { - "f_1": { + "test": { "sum": { "field": "value" } @@ -386,14 +494,26 @@ GET _plugins/_anomaly_detection/detectors/?job=true } } ], - "last_update_time": 1613586955060, - "detector_type": "MULTI_ENTITY" + "last_update_time": 1633392680364, + "user": { + "name": "admin", + "backend_roles": [ + "admin" + ], + "roles": [ + "own_index", + "all_access" + ], + "custom_attribute_names": [], + "user_requested_tenant": "__user__" + }, + "detector_type": "SINGLE_ENTITY" }, "anomaly_detector_job": { - "name": "LJxGsXcBoDQA8W1Q--A1", + "name": "VEHKTXwBwf_U8gjUXY2s", "schedule": { "interval": { - "start_time": 1613587220387, + "start_time": 1633393656357, "period": 1, "unit": "Minutes" } @@ -404,75 +524,28 @@ GET _plugins/_anomaly_detection/detectors/?job=true "unit": "Minutes" } }, - "enabled": "false", - "enabled_time": 1613587220387, - "last_update_time": 1613587289169, + "enabled": true, + "enabled_time": 1633393656357, + "last_update_time": 1633393656357, "lock_duration_seconds": 60, - "disabled_time": 1613587289169 - }, - "anomaly_detection_task": { - "task_id": "WZ5LsXcBoDQA8W1QmUa3", - "last_update_time": 1613587349022, - "error": "Task cancelled by user", - "state": "STOPPED", - "detector_id": "LJxGsXcBoDQA8W1Q--A1", - "task_progress": 0.26321793, - "init_progress": 1, - "current_piece": 1611030900000, - "execution_start_time": 1613587257783, - "execution_end_time": 1613587349022, - "is_latest": "true", - "task_type": "HISTORICAL", - "coordinating_node": "NSw5j-3YQeGkH8KESVKlzw", - "worker_node": "NSw5j-3YQeGkH8KESVKlzw", - "detector": { - "name": "test2", - "description": "test", - "time_field": "timestamp", - "indices": [ - "server_log" + "user": { + "name": "admin", + "backend_roles": [ + "admin" ], - "filter_query": { - "match_all": { - "boost": 1 - } - }, - "detection_interval": { - "period": { - "interval": 1, - "unit": "Minutes" - } - }, - "window_delay": { - "period": { - "interval": 1, - "unit": "Minutes" - } - }, - "shingle_size": 8, - "schema_version": 0, - "feature_attributes": [ - { - "feature_id": "K5xGsXcBoDQA8W1Q-uCF", - "feature_name": "F1", - "feature_enabled": "true", - "aggregation_query": { - "f_1": { - "sum": { - "field": "value" - } - } - } - } + "roles": [ + "own_index", + "all_access" ], - "last_update_time": 1613586955060, - "detector_type": "MULTI_ENTITY" + "custom_attribute_names": [], + "user_requested_tenant": "__user__" } } } ``` Use `task=true` to get historical analysis task information. +You can set both `job=true` and `task=true` to get information for both real-time and historical analysis tasks. #### Request @@ -484,25 +557,39 @@ GET _plugins/_anomaly_detection/detectors/?task=true ```json { - "_id": "BwzKQXcB89DLS7G9rg7Y", + "_id": "VEHKTXwBwf_U8gjUXY2s", "_version": 1, - "_primary_term": 2, - "_seq_no": 10, + "_primary_term": 1, + "_seq_no": 5, "anomaly_detector": { - "name": "test-ylwu1", - "description": "test", + "name": "test-detector", + "description": "Test detector", "time_field": "timestamp", "indices": [ - "ser*" + "server_log*" ], "filter_query": { - "match_all": { + "bool": { + "filter": [ + { + "range": { + "value": { + "from": 1, + "to": null, + "include_lower": false, + "include_upper": true, + "boost": 1 + } + } + } + ], + "adjust_pure_negative": true, "boost": 1 } }, "detection_interval": { "period": { - "interval": 10, + "interval": 1, "unit": "Minutes" } }, @@ -516,11 +603,11 @@ GET _plugins/_anomaly_detection/detectors/?task=true "schema_version": 0, "feature_attributes": [ { - "feature_id": "BgzKQXcB89DLS7G9rg7G", - "feature_name": "F1", + "feature_id": "U0HKTXwBwf_U8gjUXY2m", + "feature_name": "test", "feature_enabled": true, "aggregation_query": { - "f_1": { + "test": { "sum": { "field": "value" } @@ -528,64 +615,63 @@ GET _plugins/_anomaly_detection/detectors/?task=true } } ], - "ui_metadata": { - "features": { - "F1": { - "aggregationBy": "sum", - "aggregationOf": "value", - "featureType": "simple_aggs" - } - } - }, - "last_update_time": 1611716538071, + "last_update_time": 1633392680364, "user": { "name": "admin", "backend_roles": [ "admin" ], "roles": [ - "all_access", - "own_index" + "own_index", + "all_access" ], "custom_attribute_names": [], "user_requested_tenant": "__user__" }, - "detector_type": "HISTORICAL_SINGLE_ENTITY", - "detection_date_range": { - "start_time": 1580094137997, - "end_time": 1611716537997 - } + "detector_type": "SINGLE_ENTITY" }, - "anomaly_detection_task": { - "task_id": "sgxaRXcB89DLS7G9RfIO", - "last_update_time": 1611776648699, + "realtime_detection_task": { + "task_id": "nkTZTXwBjd8s6RK4QlMq", + "last_update_time": 1633393776375, "started_by": "admin", - "state": "FINISHED", - "detector_id": "BwzKQXcB89DLS7G9rg7Y", - "task_progress": 1, + "error": "", + "state": "RUNNING", + "detector_id": "VEHKTXwBwf_U8gjUXY2s", + "task_progress": 0, "init_progress": 1, - "current_piece": 1611716400000, - "execution_start_time": 1611776279822, - "execution_end_time": 1611776648679, + "execution_start_time": 1633393656362, "is_latest": true, - "task_type": "HISTORICAL", - "coordinating_node": "gs213KqjS4q7H4Bmn_ZuLA", - "worker_node": "PgfR3JhbT7yJMx7bwQ6E3w", + "task_type": "REALTIME_SINGLE_ENTITY", + "coordinating_node": "SWD7ihu9TaaW1zKwFZNVNg", "detector": { - "name": "test-ylwu1", - "description": "test", + "name": "test-detector", + "description": "Test detector", "time_field": "timestamp", "indices": [ - "ser*" + "server_log*" ], "filter_query": { - "match_all": { + "bool": { + "filter": [ + { + "range": { + "value": { + "from": 1, + "to": null, + "include_lower": false, + "include_upper": true, + "boost": 1 + } + } + } + ], + "adjust_pure_negative": true, "boost": 1 } }, "detection_interval": { "period": { - "interval": 10, + "interval": 1, "unit": "Minutes" } }, @@ -599,11 +685,11 @@ GET _plugins/_anomaly_detection/detectors/?task=true "schema_version": 0, "feature_attributes": [ { - "feature_id": "BgzKQXcB89DLS7G9rg7G", - "feature_name": "F1", + "feature_id": "U0HKTXwBwf_U8gjUXY2m", + "feature_name": "test", "feature_enabled": true, "aggregation_query": { - "f_1": { + "test": { "sum": { "field": "value" } @@ -611,33 +697,121 @@ GET _plugins/_anomaly_detection/detectors/?task=true } } ], - "ui_metadata": { - "features": { - "F1": { - "aggregationBy": "sum", - "aggregationOf": "value", - "featureType": "simple_aggs" - } - } - }, - "last_update_time": 1611716538071, + "last_update_time": 1633392680364, "user": { "name": "admin", "backend_roles": [ "admin" ], "roles": [ - "all_access", - "own_index" + "own_index", + "all_access" ], "custom_attribute_names": [], "user_requested_tenant": "__user__" }, - "detector_type": "HISTORICAL_SINGLE_ENTITY", - "detection_date_range": { - "start_time": 1580094137997, - "end_time": 1611716537997 - } + "detector_type": "SINGLE_ENTITY" + }, + "estimated_minutes_left": 0, + "user": { + "name": "admin", + "backend_roles": [ + "admin" + ], + "roles": [ + "own_index", + "all_access" + ], + "custom_attribute_names": [], + "user_requested_tenant": "__user__" + } + }, + "historical_analysis_task": { + "task_id": "99DaTXwB6HknB84StRN1", + "last_update_time": 1633393797040, + "started_by": "admin", + "state": "RUNNING", + "detector_id": "VEHKTXwBwf_U8gjUXY2s", + "task_progress": 0.89285713, + "init_progress": 1, + "current_piece": 1633328940000, + "execution_start_time": 1633393751412, + "is_latest": true, + "task_type": "HISTORICAL_SINGLE_ENTITY", + "coordinating_node": "SWD7ihu9TaaW1zKwFZNVNg", + "worker_node": "2Z4q22BySEyzakYt_A0A2A", + "detector": { + "name": "test-detector", + "description": "Test detector", + "time_field": "timestamp", + "indices": [ + "server_log*" + ], + "filter_query": { + "bool": { + "filter": [ + { + "range": { + "value": { + "from": 1, + "to": null, + "include_lower": false, + "include_upper": true, + "boost": 1 + } + } + } + ], + "adjust_pure_negative": true, + "boost": 1 + } + }, + "detection_interval": { + "period": { + "interval": 1, + "unit": "Minutes" + } + }, + "window_delay": { + "period": { + "interval": 1, + "unit": "Minutes" + } + }, + "shingle_size": 8, + "schema_version": 0, + "feature_attributes": [ + { + "feature_id": "U0HKTXwBwf_U8gjUXY2m", + "feature_name": "test", + "feature_enabled": true, + "aggregation_query": { + "test": { + "sum": { + "field": "value" + } + } + } + } + ], + "last_update_time": 1633392680364, + "user": { + "name": "admin", + "backend_roles": [ + "admin" + ], + "roles": [ + "own_index", + "all_access" + ], + "custom_attribute_names": [], + "user_requested_tenant": "__user__" + }, + "detector_type": "SINGLE_ENTITY" + }, + "detection_date_range": { + "start_time": 1632788951329, + "end_time": 1633393751329 }, "user": { "name": "admin", @@ -645,8 +819,8 @@ GET _plugins/_anomaly_detection/detectors/?task=true "admin" ], "roles": [ - "all_access", - "own_index" + "own_index", + "all_access" ], "custom_attribute_names": [], "user_requested_tenant": "__user__" @@ -662,7 +836,10 @@ Introduced 1.0 {: .label .label-purple } Updates a detector with any changes, including the description or adding or removing of features. -To update a detector, you need to first stop the detector. +To update a detector, you need to first stop both real-time detection and historical analysis. + +You can't update a category field. +{: .note } #### Request @@ -670,17 +847,17 @@ To update a detector, you need to first stop the detector. PUT _plugins/_anomaly_detection/detectors/ { "name": "test-detector", - "description": "Test detector", + "description": "Test update detector", "time_field": "timestamp", "indices": [ - "order*" + "server_log*" ], "feature_attributes": [ { - "feature_name": "total_order", + "feature_name": "test", "feature_enabled": true, "aggregation_query": { - "total_order": { + "test": { "sum": { "field": "value" } @@ -692,9 +869,10 @@ PUT _plugins/_anomaly_detection/detectors/ "bool": { "filter": [ { - "exists": { - "field": "value", - "boost": 1 + "range": { + "value": { + "gt": 1 + } } } ], @@ -704,14 +882,14 @@ PUT _plugins/_anomaly_detection/detectors/ }, "detection_interval": { "period": { - "interval": 10, - "unit": "MINUTES" + "interval": 1, + "unit": "Minutes" } }, "window_delay": { "period": { "interval": 1, - "unit": "MINUTES" + "unit": "Minutes" } } } @@ -722,59 +900,114 @@ PUT _plugins/_anomaly_detection/detectors/ ```json { - "_id" : "m4ccEnIBTXsGi3mvMt9p", - "_version" : 2, - "_seq_no" : 4, - "_primary_term" : 1, - "anomaly_detector" : { - "name" : "test-detector", - "description" : "Test detector", - "time_field" : "timestamp", - "indices" : [ - "order*" + "_id": "VEHKTXwBwf_U8gjUXY2s", + "_version": 2, + "_seq_no": 7, + "anomaly_detector": { + "name": "test-detector", + "description": "Test update detector", + "time_field": "timestamp", + "indices": [ + "server_log*" ], - "filter_query" : { - "bool" : { - "filter" : [ + "filter_query": { + "bool": { + "filter": [ { - "exists" : { - "field" : "value", - "boost" : 1.0 + "range": { + "value": { + "from": 1, + "to": null, + "include_lower": false, + "include_upper": true, + "boost": 1 + } } } ], - "adjust_pure_negative" : true, - "boost" : 1.0 + "adjust_pure_negative": true, + "boost": 1 } }, - "detection_interval" : { - "period" : { - "interval" : 10, - "unit" : "Minutes" + "detection_interval": { + "period": { + "interval": 1, + "unit": "Minutes" } }, - "window_delay" : { - "period" : { - "interval" : 1, - "unit" : "Minutes" + "window_delay": { + "period": { + "interval": 1, + "unit": "Minutes" } }, - "schema_version" : 0, - "feature_attributes" : [ + "shingle_size": 8, + "schema_version": 0, + "feature_attributes": [ { - "feature_id" : "xxokEnIBcpeWMD987A1X", - "feature_name" : "total_order", - "feature_enabled" : true, - "aggregation_query" : { - "total_order" : { - "sum" : { - "field" : "value" + "feature_id": "3kHiTXwBwf_U8gjUlY15", + "feature_name": "test", + "feature_enabled": true, + "aggregation_query": { + "test": { + "sum": { + "field": "value" } } } } - ] - } + ], + "last_update_time": 1633394267522, + "user": { + "name": "admin", + "backend_roles": [ + "admin" + ], + "roles": [ + "own_index", + "all_access" + ], + "custom_attribute_names": [], + "user_requested_tenant": "__user__" + }, + "detector_type": "SINGLE_ENTITY" + }, + "_primary_term": 1 +} +``` + +--- + +## Delete detector +Introduced 1.0 +{: .label .label-purple } + +Deletes a detector based on the `detector_id`. +To delete a detector, you need to first stop both real-time detection and historical analysis. + +#### Request + +```json +DELETE _plugins/_anomaly_detection/detectors/ +``` + +#### Sample response + +```json +{ + "_index": ".opendistro-anomaly-detectors", + "_type": "_doc", + "_id": "70TxTXwBjd8s6RK4j1Pj", + "_version": 2, + "result": "deleted", + "forced_refresh": true, + "_shards": { + "total": 2, + "successful": 2, + "failed": 0 + }, + "_seq_no": 9, + "_primary_term": 1 } ``` @@ -786,20 +1019,114 @@ Introduced 1.0 Passes a date range to the anomaly detector to return any anomalies within that date range. +To preview a single-flow detector: + #### Request ```json POST _plugins/_anomaly_detection/detectors//_preview { - "period_start": 1612982516000, - "period_end": 1614278539000, + "period_start": 1633048868000, + "period_end": 1633394468000, "detector": { "name": "test-detector", - "description": "test server_log", + "description": "Test update detector", "time_field": "timestamp", "indices": [ - "server_log" + "server_log*" ], + "feature_attributes": [ + { + "feature_name": "test", + "feature_enabled": true, + "aggregation_query": { + "test": { + "sum": { + "field": "value" + } + } + } + } + ], + "filter_query": { + "bool": { + "filter": [ + { + "range": { + "value": { + "gt": 1 + } + } + } + ], + "adjust_pure_negative": true, + "boost": 1 + } + }, + "detection_interval": { + "period": { + "interval": 1, + "unit": "Minutes" + } + }, + "window_delay": { + "period": { + "interval": 1, + "unit": "Minutes" + } + } + } +} +``` + +#### Sample response + +```json +{ + "anomaly_result": [ + { + "detector_id": null, + "data_start_time": 1633049280000, + "data_end_time": 1633049340000, + "schema_version": 0, + "feature_data": [ + { + "feature_id": "8EHmTXwBwf_U8gjU0Y0u", + "feature_name": "test", + "data": 0 + } + ], + "anomaly_grade": 0, + "confidence": 0 + }, + ... + ], + "anomaly_detector": { + "name": "test-detector", + "description": "Test update detector", + "time_field": "timestamp", + "indices": [ + "server_log*" + ], + "filter_query": { + "bool": { + "filter": [ + { + "range": { + "value": { + "from": 1, + "to": null, + "include_lower": false, + "include_upper": true, + "boost": 1 + } + } + } + ], + "adjust_pure_negative": true, + "boost": 1 + } + }, "detection_interval": { "period": { "interval": 1, @@ -812,18 +1139,85 @@ POST _plugins/_anomaly_detection/detectors//_preview "unit": "Minutes" } }, + "shingle_size": 8, + "schema_version": 0, "feature_attributes": [ { - "feature_name": "F1", + "feature_id": "8EHmTXwBwf_U8gjU0Y0u", + "feature_name": "test", "feature_enabled": true, "aggregation_query": { - "f_1": { + "test": { "sum": { "field": "value" } } } } + ], + "detector_type": "SINGLE_ENTITY" + } +} +``` + +If you specify a category field, each result is associated with an entity: + +#### Request + +```json +POST _plugins/_anomaly_detection/detectors//_preview +{ + "period_start": 1633048868000, + "period_end": 1633394468000, + "detector": { + "name": "test-detector", + "description": "Test update detector", + "time_field": "timestamp", + "indices": [ + "server_log*" + ], + "feature_attributes": [ + { + "feature_name": "test", + "feature_enabled": true, + "aggregation_query": { + "test": { + "sum": { + "field": "value" + } + } + } + } + ], + "filter_query": { + "bool": { + "filter": [ + { + "range": { + "value": { + "gt": 1 + } + } + } + ], + "adjust_pure_negative": true, + "boost": 1 + } + }, + "detection_interval": { + "period": { + "interval": 1, + "unit": "Minutes" + } + }, + "window_delay": { + "period": { + "interval": 1, + "unit": "Minutes" + } + }, + "category_field": [ + "error_type" ] } } @@ -834,37 +1228,48 @@ POST _plugins/_anomaly_detection/detectors//_preview ```json { "anomaly_result": [ - ... { - "detector_id": "m4ccEnIBTXsGi3mvMt9p", - "data_start_time": 1588843020000, - "data_end_time": 1588843620000, + "detector_id": null, + "data_start_time": 1633049280000, + "data_end_time": 1633049340000, + "schema_version": 0, "feature_data": [ { - "feature_id": "xxokEnIBcpeWMD987A1X", - "feature_name": "total_order", - "data": 489.9929131106 + "feature_id": "tkTpTXwBjd8s6RK4DlOZ", + "feature_name": "test", + "data": 0 } ], "anomaly_grade": 0, - "confidence": 0.99 - } + "confidence": 0, + "entity": [ + { + "name": "error_type", + "value": "error1" + } + ] + }, ... ], "anomaly_detector": { "name": "test-detector", - "description": "Test detector", + "description": "Test update detector", "time_field": "timestamp", "indices": [ - "order*" + "server_log*" ], "filter_query": { "bool": { "filter": [ { - "exists": { - "field": "value", - "boost": 1 + "range": { + "value": { + "from": 1, + "to": null, + "include_lower": false, + "include_upper": true, + "boost": 1 + } } } ], @@ -874,24 +1279,25 @@ POST _plugins/_anomaly_detection/detectors//_preview }, "detection_interval": { "period": { - "interval": 10, - "unit": "MINUTES" + "interval": 1, + "unit": "Minutes" } }, "window_delay": { "period": { "interval": 1, - "unit": "MINUTES" + "unit": "Minutes" } }, + "shingle_size": 8, "schema_version": 0, "feature_attributes": [ { - "feature_id": "xxokEnIBcpeWMD987A1X", - "feature_name": "total_order", + "feature_id": "tkTpTXwBjd8s6RK4DlOZ", + "feature_name": "test", "feature_enabled": true, "aggregation_query": { - "total_order": { + "test": { "sum": { "field": "value" } @@ -899,12 +1305,34 @@ POST _plugins/_anomaly_detection/detectors//_preview } } ], - "last_update_time": 1589442309241 + "category_field": [ + "error_type" + ], + "detector_type": "MULTI_ENTITY" } } ``` -If you specify a category field, each result is associated with an entity: +You can preview a detector with the detector ID: + +```json +POST _plugins/_anomaly_detection/detectors/_preview +{ + "detector_id": "VEHKTXwBwf_U8gjUXY2s", + "period_start": 1633048868000, + "period_end": 1633394468000 +} +``` + +Or: + +```json +POST _opendistro/_anomaly_detection/detectors/VEHKTXwBwf_U8gjUXY2s/_preview +{ + "period_start": 1633048868000, + "period_end": 1633394468000 +} +``` #### Sample response @@ -912,53 +1340,103 @@ If you specify a category field, each result is associated with an entity: { "anomaly_result": [ { - "detector_id": "4CIGoHUBTpMGN-4KzBQg", - "data_start_time": 1604277960000, - "data_end_time": 1604278020000, + "detector_id": "VEHKTXwBwf_U8gjUXY2s", + "data_start_time": 1633049280000, + "data_end_time": 1633049340000, "schema_version": 0, + "feature_data": [ + { + "feature_id": "3kHiTXwBwf_U8gjUlY15", + "feature_name": "test", + "data": 0 + } + ], "anomaly_grade": 0, - "confidence": 0.99 - } + "confidence": 0, + "user": { + "name": "admin", + "backend_roles": [ + "admin" + ], + "roles": [ + "own_index", + "all_access" + ], + "custom_attribute_names": [], + "user_requested_tenant": "__user__" + } + }, + ... ], - "entity": [ - { - "name": "host", - "value": "i-00f28ec1eb8997686" - } - ] -}, -{ - "detector_id": "4CIGoHUBTpMGN-4KzBQg", - "data_start_time": 1604278020000, - "data_end_time": 1604278080000, - "schema_version": 0, - "feature_data": [ - { - "feature_id": "0Kld3HUBhpHMyt2e_UHn", - "feature_name": "latency_max", - "data": -17 - } - ], - "anomaly_grade": 0, - "confidence": 0.99, - "entity": [ - { - "name": "host", - "value": "i-00f28ec1eb8997686" - } - ] -} -... -``` - -Or, you can specify the detector ID: - -```json -POST _plugins/_anomaly_detection/detectors/_preview -{ - "detector_id": "sYkUvHcBiZv51f-Lv8QN", - "period_start": 1612982516000, - "period_end": 1614278539000 + "anomaly_detector": { + "name": "test-detector", + "description": "Test update detector", + "time_field": "timestamp", + "indices": [ + "server_log*" + ], + "filter_query": { + "bool": { + "filter": [ + { + "range": { + "value": { + "from": 1, + "to": null, + "include_lower": false, + "include_upper": true, + "boost": 1 + } + } + } + ], + "adjust_pure_negative": true, + "boost": 1 + } + }, + "detection_interval": { + "period": { + "interval": 1, + "unit": "Minutes" + } + }, + "window_delay": { + "period": { + "interval": 1, + "unit": "Minutes" + } + }, + "shingle_size": 8, + "schema_version": 0, + "feature_attributes": [ + { + "feature_id": "3kHiTXwBwf_U8gjUlY15", + "feature_name": "test", + "feature_enabled": true, + "aggregation_query": { + "test": { + "sum": { + "field": "value" + } + } + } + } + ], + "last_update_time": 1633394267522, + "user": { + "name": "admin", + "backend_roles": [ + "admin" + ], + "roles": [ + "own_index", + "all_access" + ], + "custom_attribute_names": [], + "user_requested_tenant": "__user__" + }, + "detector_type": "SINGLE_ENTITY" + } } ``` @@ -970,6 +1448,7 @@ Introduced 1.0 Starts a real-time or historical anomaly detector job. +To start a real-time detector job: #### Request @@ -981,23 +1460,38 @@ POST _plugins/_anomaly_detection/detectors//_start ```json { - "_id" : "m4ccEnIBTXsGi3mvMt9p", - "_version" : 1, - "_seq_no" : 6, - "_primary_term" : 1 + "_id": "VEHKTXwBwf_U8gjUXY2s", + "_version": 3, + "_seq_no": 6, + "_primary_term": 1 } ``` +The `_id` represents the real-time job ID, which is the same as the detector ID. + To start historical analysis: ```json POST _plugins/_anomaly_detection/detectors//_start { - "start_time": 1503168590000, - "end_time": 1617301324000 + "start_time": 1633048868000, + "end_time": 1633394468000 } ``` +#### Sample response + +```json +{ + "_id": "f9DsTXwB6HknB84SoRTY", + "_version": 1, + "_seq_no": 958, + "_primary_term": 1 +} +``` + +The `_id` represents the historical batch task ID, which is a random universally unique identifier (UUID). + --- ## Stop detector job @@ -1006,6 +1500,8 @@ Introduced 1.0 Stops a real-time or historical anomaly detector job. +To stop a real-time detector job: + #### Request ```json @@ -1015,7 +1511,12 @@ POST _plugins/_anomaly_detection/detectors//_stop #### Sample response ```json -Stopped detector: m4ccEnIBTXsGi3mvMt9p +{ + "_id": "VEHKTXwBwf_U8gjUXY2s", + "_version": 0, + "_seq_no": 0, + "_primary_term": 0 +} ``` To stop historical analysis: @@ -1024,30 +1525,37 @@ To stop historical analysis: POST _plugins/_anomaly_detection/detectors//_stop?historical=true ``` +#### Sample response + +```json +{ + "_id": "f9DsTXwB6HknB84SoRTY", + "_version": 0, + "_seq_no": 0, + "_primary_term": 0 +} +``` --- -## Search detector result +## Search detector Introduced 1.0 {: .label .label-purple } -Returns all results for a search query. +Returns all anomaly detectors for a search query. + +To search detectors using the `server_log*` index: #### Request ```json -GET _plugins/_anomaly_detection/detectors/results/_search -POST _plugins/_anomaly_detection/detectors/results/_search +GET _plugins/_anomaly_detection/detectors/_search +POST _plugins/_anomaly_detection/detectors/_search { "query": { - "bool": { - "must": { - "range": { - "anomaly_score": { - "gte": 0.6, - "lte": 1 - } - } + "wildcard": { + "indices": { + "value": "server_log*" } } } @@ -1058,138 +1566,7 @@ POST _plugins/_anomaly_detection/detectors/results/_search ```json { - "took": 9, - "timed_out": false, - "_shards": { - "total": 25, - "successful": 25, - "skipped": 0, - "failed": 0 - }, - "hits": { - "total": { - "value": 2, - "relation": "eq" - }, - "max_score": 1, - "hits": [ - { - "_index": ".opensearch-anomaly-results-history-2020.04.30-1", - "_type": "_doc", - "_id": "_KBrzXEBbpoKkFM5mStm", - "_version": 1, - "_seq_no": 58, - "_primary_term": 1, - "_score": 1, - "_source": { - "detector_id": "2KDozHEBbpoKkFM58yr6", - "anomaly_score": 0.8995068350366767, - "execution_start_time": 1588289313114, - "data_end_time": 1588289313114, - "confidence": 0.84214852704501, - "data_start_time": 1588289253114, - "feature_data": [ - { - "feature_id": "X0fpzHEB5NGZmIRkXKcy", - "feature_name": "total_error", - "data": 20 - } - ], - "execution_end_time": 1588289313126, - "anomaly_grade": 0 - } - }, - { - "_index": ".opensearch-anomaly-results-history-2020.04.30-1", - "_type": "_doc", - "_id": "EqB1zXEBbpoKkFM5qyyE", - "_version": 1, - "_seq_no": 61, - "_primary_term": 1, - "_score": 1, - "_source": { - "detector_id": "2KDozHEBbpoKkFM58yr6", - "anomaly_score": 0.7086834513354907, - "execution_start_time": 1588289973113, - "data_end_time": 1588289973113, - "confidence": 0.42162017029510446, - "data_start_time": 1588289913113, - "feature_data": [ - { - "feature_id": "X0fpzHEB5NGZmIRkXKcy", - "feature_name": "memory_usage", - "data": 20.0347333108 - } - ], - "execution_end_time": 1588289973124, - "anomaly_grade": 0 - } - } - ] - } -} -``` - -In high cardinality detectors, the result contains entity information. - -To see an ordered set of anomaly records for an entity with an anomaly within a certain time range for a specific feature value: - -#### Request - -```json -POST _plugins/_anomaly_detection/detectors/results/_search -{ - "query": { - "bool": { - "filter": [ - { - "term": { - "detector_id": "4CIGoHUBTpMGN-4KzBQg" - } - }, - { - "range": { - "anomaly_grade": { - "gt": 0 - } - } - }, - { - "nested": { - "path": "entity", - "query": { - "bool": { - "must": [ - { - "term": { - "entity.value": "i-00f28ec1eb8997685" - } - } - ] - } - } - } - } - ] - } - }, - "size": 8, - "sort": [ - { - "execution_end_time": { - "order": "desc" - } - } - ], - "track_total_hits": true -} -``` - -#### Sample response - -```json -{ - "took": 443, + "took": 2, "timed_out": false, "_shards": { "total": 1, @@ -1199,136 +1576,119 @@ POST _plugins/_anomaly_detection/detectors/results/_search }, "hits": { "total": { - "value": 7, + "value": 4, "relation": "eq" }, - "max_score": null, + "max_score": 1, "hits": [ { - "_index": ".opensearch-anomaly-results-history-2020.11.07-1", + "_index": ".opendistro-anomaly-detectors", "_type": "_doc", - "_id": "BiItoHUBTpMGN-4KARY5", + "_id": "Zi5zTXwBwf_U8gjUTfJG", "_version": 1, - "_seq_no": 206, + "_seq_no": 1, "_primary_term": 1, - "_score": null, + "_score": 1, "_source": { - "detector_id": "4CIGoHUBTpMGN-4KzBQg", - "schema_version": 2, - "anomaly_score": 2.462550517055763, - "execution_start_time": 1604710105400, - "data_end_time": 1604710094516, - "confidence": 0.8246254862573076, - "data_start_time": 1604710034516, - "feature_data": [ + "name": "test", + "description": "test", + "time_field": "timestamp", + "indices": [ + "server_log" + ], + "filter_query": { + "match_all": { + "boost": 1 + } + }, + "detection_interval": { + "period": { + "interval": 5, + "unit": "Minutes" + } + }, + "window_delay": { + "period": { + "interval": 1, + "unit": "Minutes" + } + }, + "shingle_size": 8, + "schema_version": 0, + "feature_attributes": [ { - "feature_id": "0Kld3HUBhpHMyt2e_UHn", - "feature_name": "latency_max", - "data": 3526 + "feature_id": "ZS5zTXwBwf_U8gjUTfIn", + "feature_name": "test_feature", + "feature_enabled": true, + "aggregation_query": { + "test_feature": { + "sum": { + "field": "value" + } + } + } } ], - "execution_end_time": 1604710105401, - "anomaly_grade": 0.08045977011494891, - "entity": [ - { - "name": "host", - "value": "i-00f28ec1eb8997685" - } - ] - }, - "sort": [ - 1604710105401 - ] + "last_update_time": 1633386974533, + "category_field": [ + "error_type" + ], + "user": { + "name": "admin", + "backend_roles": [ + "admin" + ], + "roles": [ + "own_index", + "all_access" + ], + "custom_attribute_names": [], + "user_requested_tenant": "__user__" + }, + "detector_type": "MULTI_ENTITY" + } }, - { - "_index": ".opensearch-anomaly-results-history-2020.11.07-1", - "_type": "_doc", - "_id": "wiImoHUBTpMGN-4KlhXs", - "_version": 1, - "_seq_no": 156, - "_primary_term": 1, - "_score": null, - "_source": { - "detector_id": "4CIGoHUBTpMGN-4KzBQg", - "schema_version": 2, - "anomaly_score": 4.892453213261217, - "execution_start_time": 1604709684971, - "data_end_time": 1604709674522, - "confidence": 0.8313735633713821, - "data_start_time": 1604709614522, - "feature_data": [ - { - "feature_id": "0Kld3HUBhpHMyt2e_UHn", - "feature_name": "latency_max", - "data": 5709 - } - ], - "execution_end_time": 1604709684971, - "anomaly_grade": 0.06542056074767538, - "entity": [ - { - "name": "host", - "value": "i-00f28ec1eb8997685" - } - ] - }, - "sort": [ - 1604709684971 - ] - }, - { - "_index": ".opensearch-anomaly-results-history-2020.11.07-1", - "_type": "_doc", - "_id": "ZiIcoHUBTpMGN-4KhhVA", - "_version": 1, - "_seq_no": 79, - "_primary_term": 1, - "_score": null, - "_source": { - "detector_id": "4CIGoHUBTpMGN-4KzBQg", - "schema_version": 2, - "anomaly_score": 3.187717536855158, - "execution_start_time": 1604709025343, - "data_end_time": 1604709014520, - "confidence": 0.8301116064308817, - "data_start_time": 1604708954520, - "feature_data": [ - { - "feature_id": "0Kld3HUBhpHMyt2e_UHn", - "feature_name": "latency_max", - "data": 441 - } - ], - "execution_end_time": 1604709025344, - "anomaly_grade": 0.040767386091133916, - "entity": [ - { - "name": "host", - "value": "i-00f28ec1eb8997685" - } - ] - }, - "sort": [ - 1604709025344 - ] - } + ... ] } } ``` -You can query the anomaly results for historical analysis with the `task_id`: +--- + +## Search detector tasks +Introduced 1.1 +{: .label .label-purple } + +Searches detector tasks. + +To search for the latest detector task for a high cardinality detector: #### Request ```json -GET _plugins/_anomaly_detection/detectors/results/_search +GET _plugins/_anomaly_detection/detectors/tasks/_search +POST _plugins/_anomaly_detection/detectors/tasks/_search { "query": { - "term": { - "task_id": { - "value": "NnlV9HUBQxqfQ7vBJNzy" - } + "bool": { + "filter": [ + { + "term": { + "detector_id": "Zi5zTXwBwf_U8gjUTfJG" + } + }, + { + "term": { + "task_type": "HISTORICAL_HC_DETECTOR" + } + }, + { + "term": { + "is_latest": "true" + } + } + ] } } } @@ -1351,211 +1711,41 @@ GET _plugins/_anomaly_detection/detectors/results/_search "value": 1, "relation": "eq" }, - "max_score": 2.1366, + "max_score": 0, "hits": [ { - "_index": ".opensearch-anomaly-detection-state", + "_index": ".opendistro-anomaly-detection-state", "_type": "_doc", - "_id": "CoM8WncBtt2qvI-LZO7_", - "_version": 8, - "_seq_no": 1351, - "_primary_term": 3, - "_score": 2.1366, - "_source": { - "detector_id": "dZc8WncBgO2zoQoFWVBA", - "worker_node": "dk6-HuKQRMKm2fi8TSDHsg", - "task_progress": 0.09486946, - "last_update_time": 1612126667008, - "execution_start_time": 1612126643455, - "state": "RUNNING", - "coordinating_node": "gs213KqjS4q7H4Bmn_ZuLA", - "current_piece": 1583503800000, - "task_type": "HISTORICAL", - "started_by": "admin", - "init_progress": 1, - "is_latest": true, - "detector": { - "description": "test", - "ui_metadata": { - "features": { - "F1": { - "aggregationBy": "sum", - "aggregationOf": "value", - "featureType": "simple_aggs" - } - } - }, - "detection_date_range": { - "start_time": 1580504240308, - "end_time": 1612126640308 - }, - "feature_attributes": [ - { - "feature_id": "dJc8WncBgO2zoQoFWVAt", - "feature_enabled": true, - "feature_name": "F1", - "aggregation_query": { - "f_1": { - "sum": { - "field": "value" - } - } - } - } - ], - "schema_version": 0, - "time_field": "timestamp", - "last_update_time": 1612126640448, - "indices": [ - "server_log" - ], - "window_delay": { - "period": { - "unit": "Minutes", - "interval": 1 - } - }, - "detection_interval": { - "period": { - "unit": "Minutes", - "interval": 10 - } - }, - "name": "test-historical-detector", - "filter_query": { - "match_all": { - "boost": 1 - } - }, - "shingle_size": 8, - "user": { - "backend_roles": [ - "admin" - ], - "custom_attribute_names": [], - "roles": [ - "all_access", - "own_index" - ], - "name": "admin", - "user_requested_tenant": "__user__" - }, - "detector_type": "HISTORICAL_SINGLE_ENTITY" - }, - "user": { - "backend_roles": [ - "admin" - ], - "custom_attribute_names": [], - "roles": [ - "all_access", - "own_index" - ], - "name": "admin", - "user_requested_tenant": "__user__" - } - } - } - ] - } -} -``` - ---- - -## Search detector tasks -Introduced 1.1 -{: .label .label-purple } - -Searches detector tasks. - -#### Request - -```json -POST _plugins/_anomaly_detection/detectors/tasks/_search -{ - "query": { - "bool": { - "filter": [ - { - "term": { - "detector_id": { - "value": "_6WPu3cBBnauGn7oxUAv" - } - } - }, - { - "term": { - "task_type": { - "value": "HISTORICAL_HC_DETECTOR" - } - } - } - ] - } - }, - "sort": [ - { - "execution_start_time": { - "order": "desc" - } - } - ] -} -``` - - -#### Sample response - -```json -{ - "took": 5, - "timed_out": false, - "_shards": { - "total": 1, - "successful": 1, - "skipped": 0, - "failed": 0 - }, - "hits": { - "total": { - "value": 1, - "relation": "eq" - }, - "max_score": null, - "hits": [ - { - "_index": ".opensearch-anomaly-detection-state", - "_type": "_doc", - "_id": "TM3tOHwBCi2h__AOXlyQ", - "_version": 3, - "_seq_no": 14, + "_id": "fm-RTXwBYwCbWecgB753", + "_version": 34, + "_seq_no": 928, "_primary_term": 1, - "_score": null, + "_score": 0, "_source": { - "detector_id": "rlDtOHwBD5tpxlbyW7Nt", + "detector_id": "Zi5zTXwBwf_U8gjUTfJG", "error": "", "detection_date_range": { - "start_time": 1632437852100, - "end_time": 1633042652100 + "start_time": 1630794960000, + "end_time": 1633386960000 }, - "task_progress": 0.5, - "last_update_time": 1633042667358, - "execution_start_time": 1633042652810, - "state": "RUNNING", - "coordinating_node": "2hEGbUw6ShaiKe05n_xLdA", + "task_progress": 1, + "last_update_time": 1633389090738, + "execution_start_time": 1633388922742, + "state": "FINISHED", + "coordinating_node": "2Z4q22BySEyzakYt_A0A2A", "task_type": "HISTORICAL_HC_DETECTOR", + "execution_end_time": 1633389090738, "started_by": "admin", "init_progress": 0, "is_latest": true, "detector": { "category_field": [ - "type" + "error_type" ], "description": "test", "ui_metadata": { "features": { - "test-feature": { + "test_feature": { "aggregationBy": "sum", "aggregationOf": "value", "featureType": "simple_aggs" @@ -1565,9 +1755,9 @@ POST _plugins/_anomaly_detection/detectors/tasks/_search }, "feature_attributes": [ { - "feature_id": "7VDtOHwBD5tpxlbyWqPs", + "feature_id": "ZS5zTXwBwf_U8gjUTfIn", "feature_enabled": true, - "feature_name": "test-feature", + "feature_name": "test_feature", "aggregation_query": { "test_feature": { "sum": { @@ -1579,7 +1769,7 @@ POST _plugins/_anomaly_detection/detectors/tasks/_search ], "schema_version": 0, "time_field": "timestamp", - "last_update_time": 1633042652012, + "last_update_time": 1633386974533, "indices": [ "server_log" ], @@ -1595,7 +1785,7 @@ POST _plugins/_anomaly_detection/detectors/tasks/_search "interval": 5 } }, - "name": "test-detector", + "name": "testhc", "filter_query": { "match_all": { "boost": 1 @@ -1612,7 +1802,7 @@ POST _plugins/_anomaly_detection/detectors/tasks/_search "all_access" ], "name": "admin", - "user_requested_tenant": null + "user_requested_tenant": "__user__" }, "detector_type": "MULTI_ENTITY" }, @@ -1628,50 +1818,1060 @@ POST _plugins/_anomaly_detection/detectors/tasks/_search "name": "admin", "user_requested_tenant": "__user__" } - }, - "sort": [ - 1633042652810 - ] + } } ] } } ``` - ---- - -## Delete detector -Introduced 1.0 -{: .label .label-purple } - -Deletes a detector based on the `detector_id`. -To delete a detector, you need to first stop the detector. +To search for the latest entity-level task for a high cardinality detector: #### Request ```json -DELETE _plugins/_anomaly_detection/detectors/ +GET _plugins/_anomaly_detection/detectors/tasks/_search +POST _plugins/_anomaly_detection/detectors/tasks/_search +{ + "query": { + "bool": { + "filter": [ + { + "term": { + "detector_id": "Zi5zTXwBwf_U8gjUTfJG" + } + }, + { + "term": { + "task_type": "HISTORICAL_HC_ENTITY" + } + }, + { + "term": { + "is_latest": "true" + } + } + ] + } + }, + "sort": [ + { + "execution_start_time": { + "order": "desc" + } + } + ], + "size": 100 +} ``` +To search for all entity-level batch task stats: + +#### Request + +```json +GET _plugins/_anomaly_detection/detectors/tasks/_search +POST _plugins/_anomaly_detection/detectors/tasks/_search +{ + "size": 0, + "query": { + "bool": { + "filter": [ + { + "term": { + "detector_id": { + "value": "Zi5zTXwBwf_U8gjUTfJG", + "boost": 1 + } + } + }, + { + "term": { + "parent_task_id": { + "value": "fm-RTXwBYwCbWecgB753", + "boost": 1 + } + } + }, + { + "terms": { + "task_type": [ + "HISTORICAL_HC_ENTITY" + ], + "boost": 1 + } + } + ] + } + }, + "aggs": { + "test": { + "terms": { + "field": "state", + "size": 100 + } + } + } +} +``` #### Sample response ```json { - "_index": ".opensearch-anomaly-detectors", - "_type": "_doc", - "_id": "m4ccEnIBTXsGi3mvMt9p", - "_version": 2, - "result": "deleted", - "forced_refresh": true, + "took": 2, + "timed_out": false, "_shards": { - "total": 2, - "successful": 2, + "total": 1, + "successful": 1, + "skipped": 0, "failed": 0 }, - "_seq_no": 6, - "_primary_term": 1 + "hits": { + "total": { + "value": 32, + "relation": "eq" + }, + "max_score": null, + "hits": [] + }, + "aggregations": { + "test": { + "doc_count_error_upper_bound": 0, + "sum_other_doc_count": 0, + "buckets": [ + { + "key": "FINISHED", + "doc_count": 32 + } + ] + } + } +} +``` + +--- + +## Search detector result +Introduced 1.0 +{: .label .label-purple } + +Returns all results for a search query. + +To search anomaly results for `grade` greater than 0 for real-time analysis: + +#### Request + +```json +GET _plugins/_anomaly_detection/detectors/results/_search +POST _plugins/_anomaly_detection/detectors/results/_search +{ + "query": { + "bool": { + "filter": [ + { + "term": { + "detector_id": "Zi5zTXwBwf_U8gjUTfJG" + } + }, + { + "range": { + "anomaly_grade": { + "gt": 0 + } + } + } + ], + "must_not": [ + { + "exists": { + "field": "task_id" + } + } + ] + } + } +} +``` + +Because real-time analysis doesn't have a batch task, the task ID in the anomaly result is null. + +#### Sample response + +```json +{ + "took": 4, + "timed_out": false, + "_shards": { + "total": 3, + "successful": 3, + "skipped": 0, + "failed": 0 + }, + "hits": { + "total": { + "value": 90, + "relation": "eq" + }, + "max_score": 0, + "hits": [ + { + "_index": ".opendistro-anomaly-results-history-2021.10.04-1", + "_type": "_doc", + "_id": "686KTXwB6HknB84SMr6G", + "_version": 1, + "_seq_no": 103622, + "_primary_term": 1, + "_score": 0, + "_source": { + "detector_id": "Zi5zTXwBwf_U8gjUTfJG", + "confidence": 0.918886275269358, + "model_id": "Zi5zTXwBwf_U8gjUTfJG_entity_error16", + "schema_version": 4, + "anomaly_score": 1.1093755891885446, + "execution_start_time": 1633388475001, + "data_end_time": 1633388414989, + "data_start_time": 1633388114989, + "feature_data": [ + { + "feature_id": "ZS5zTXwBwf_U8gjUTfIn", + "feature_name": "test_feature", + "data": 0.532 + } + ], + "execution_end_time": 1633388475014, + "user": { + "backend_roles": [ + "admin" + ], + "custom_attribute_names": [], + "roles": [ + "own_index", + "all_access" + ], + "name": "admin", + "user_requested_tenant": "__user__" + }, + "anomaly_grade": 0.031023547546561225, + "entity": [ + { + "name": "error_type", + "value": "error16" + } + ] + } + }, + ... + ] + } +} +``` + +You can run historical analysis as many times as you like. So, multiple tasks might exist for the same detector. + +You can search for the latest historical batch task first and then search the historical batch task results. + +To search anomaly results for `grade` greater than 0 for historical analysis with the `task_id`: + +#### Request + +```json +GET _plugins/_anomaly_detection/detectors/results/_search +POST _plugins/_anomaly_detection/detectors/results/_search +{ + "query": { + "bool": { + "filter": [ + { + "term": { + "detector_id": "Zi5zTXwBwf_U8gjUTfJG" + } + }, + { + "range": { + "anomaly_grade": { + "gt": 0 + } + } + }, + { + "term": { + "task_id": "fm-RTXwBYwCbWecgB753" + } + } + ] + } + } +} +``` + +#### Sample response + +```json +{ + "took": 915, + "timed_out": false, + "_shards": { + "total": 3, + "successful": 3, + "skipped": 0, + "failed": 0 + }, + "hits": { + "total": { + "value": 4115, + "relation": "eq" + }, + "max_score": 0, + "hits": [ + { + "_index": ".opendistro-anomaly-results-history-2021.10.04-1", + "_type": "_doc", + "_id": "VRyRTXwBDx7vzPBV8jYC", + "_version": 1, + "_seq_no": 149657, + "_primary_term": 1, + "_score": 0, + "_source": { + "detector_id": "Zi5zTXwBwf_U8gjUTfJG", + "confidence": 0.9642989263957601, + "task_id": "fm-RTXwBYwCbWecgB753", + "model_id": "Zi5zTXwBwf_U8gjUTfJG_entity_error24", + "schema_version": 4, + "anomaly_score": 1.2260712437521946, + "execution_start_time": 1633388982692, + "data_end_time": 1631721300000, + "data_start_time": 1631721000000, + "feature_data": [ + { + "feature_id": "ZS5zTXwBwf_U8gjUTfIn", + "feature_name": "test_feature", + "data": 10 + } + ], + "execution_end_time": 1633388982709, + "user": { + "backend_roles": [ + "admin" + ], + "custom_attribute_names": [], + "roles": [ + "own_index", + "all_access" + ], + "name": "admin", + "user_requested_tenant": "__user__" + }, + "anomaly_grade": 0.14249628345655782, + "entity": [ + { + "name": "error_type", + "value": "error1" + } + ] + } + }, + ... + ] + } +} +``` + +--- + +## Get detector stats +Introduced 1.0 +{: .label .label-purple } + +Provides information about how the plugin is performing. + +To get all stats: + +#### Request + +```json +GET _plugins/_anomaly_detection/stats +``` + +#### Sample response + +```json +{ + "anomaly_detectors_index_status": "green", + "anomaly_detection_state_status": "green", + "single_entity_detector_count": 2, + "detector_count": 5, + "multi_entity_detector_count": 3, + "anomaly_detection_job_index_status": "green", + "models_checkpoint_index_status": "green", + "anomaly_results_index_status": "green", + "nodes": { + "2Z4q22BySEyzakYt_A0A2A": { + "ad_execute_request_count": 95, + "models": [ + { + "detector_id": "WTBnTXwBjd8s6RK4b1Sz", + "model_type": "rcf", + "last_used_time": 1633398197185, + "model_id": "WTBnTXwBjd8s6RK4b1Sz_model_rcf_0", + "last_checkpoint_time": 1633396573679 + }, + ... + ], + "ad_canceled_batch_task_count": 0, + "ad_hc_execute_request_count": 75, + "ad_hc_execute_failure_count": 0, + "model_count": 28, + "ad_execute_failure_count": 1, + "ad_batch_task_failure_count": 0, + "ad_total_batch_task_execution_count": 27, + "ad_executing_batch_task_count": 3 + }, + "SWD7ihu9TaaW1zKwFZNVNg": { + "ad_execute_request_count": 12, + "models": [ + { + "detector_id": "Zi5zTXwBwf_U8gjUTfJG", + "model_type": "entity", + "last_used_time": 1633398375008, + "model_id": "Zi5zTXwBwf_U8gjUTfJG_entity_error13", + "last_checkpoint_time": 1633392973682, + "entity": [ + { + "name": "error_type", + "value": "error13" + } + ] + }, + ... + ], + "ad_canceled_batch_task_count": 1, + "ad_hc_execute_request_count": 0, + "ad_hc_execute_failure_count": 0, + "model_count": 15, + "ad_execute_failure_count": 2, + "ad_batch_task_failure_count": 0, + "ad_total_batch_task_execution_count": 27, + "ad_executing_batch_task_count": 4 + }, + "TQDUXEzyTJyV0H6_T4hYUw": { + "ad_execute_request_count": 0, + "models": [ + { + "detector_id": "Zi5zTXwBwf_U8gjUTfJG", + "model_type": "entity", + "last_used_time": 1633398375004, + "model_id": "Zi5zTXwBwf_U8gjUTfJG_entity_error24", + "last_checkpoint_time": 1633388177359, + "entity": [ + { + "name": "error_type", + "value": "error24" + } + ] + }, + ... + ], + "ad_canceled_batch_task_count": 0, + "ad_hc_execute_request_count": 0, + "ad_hc_execute_failure_count": 0, + "model_count": 22, + "ad_execute_failure_count": 0, + "ad_batch_task_failure_count": 0, + "ad_total_batch_task_execution_count": 28, + "ad_executing_batch_task_count": 3 + } + } +} +``` + +The `model_count` parameter shows the total number of models running on each node’s memory. +For historical analysis, you see the values for the following fields: + +- `ad_total_batch_task_execution_count` +- `ad_executing_batch_task_count` +- `ad_canceled_batch_task_count` +- `ad_batch_task_failure_count` + +If haven't run any historical analysis, these values show up as 0. + +To get all stats for a specific node: + +#### Request + +```json +GET _plugins/_anomaly_detection//stats +``` + +To get specific stats for a node: + +#### Request + +```json +GET _plugins/_anomaly_detection//stats/ +GET _plugins/_anomaly_detection//stats/ad_execute_request_count +``` + +#### Sample response + +```json +{ + "nodes": { + "SWD7ihu9TaaW1zKwFZNVNg": { + "ad_execute_request_count": 12 + } + } +} +``` + +To get a specific type of stats: + +#### Request + +```json +GET _plugins/_anomaly_detection/stats/ +GET _plugins/_anomaly_detection/stats/ad_executing_batch_task_count +``` + +#### Sample response + +```json +{ + "nodes": { + "2Z4q22BySEyzakYt_A0A2A": { + "ad_executing_batch_task_count": 3 + }, + "SWD7ihu9TaaW1zKwFZNVNg": { + "ad_executing_batch_task_count": 3 + }, + "TQDUXEzyTJyV0H6_T4hYUw": { + "ad_executing_batch_task_count": 4 + } + } +} +``` + +--- + +## Profile detector +Introduced 1.0 +{: .label .label-purple } + +Returns information related to the current state of the detector and memory usage, including current errors and shingle size, to help troubleshoot the detector. + +This command helps locate logs by identifying the nodes that run the anomaly detector job for each detector. + +It also helps track the initialization percentage, the required shingles, and the estimated time left. + +#### Request + +```json +GET _plugins/_anomaly_detection/detectors//_profile/ +GET _plugins/_anomaly_detection/detectors//_profile?_all=true +GET _plugins/_anomaly_detection/detectors//_profile/ +GET _plugins/_anomaly_detection/detectors//_profile/, +``` + +#### Sample Responses + +```json +GET _plugins/_anomaly_detection/detectors//_profile + +{ + "state": "DISABLED", + "error": "Stopped detector: AD models memory usage exceeds our limit." +} + +GET _plugins/_anomaly_detection/detectors//_profile?_all=true&pretty + +{ + "state": "RUNNING", + "error": "", + "models": [ + { + "model_id": "3Dh6TXwBwf_U8gjURE0F_entity_KSLSh0Wv05RQXiBAQHTEZg", + "entity": [ + { + "name": "ip", + "value": "192.168.1.1" + }, + { + "name": "error_type", + "value": "error8" + } + ], + "model_size_in_bytes": 403491, + "node_id": "2Z4q22BySEyzakYt_A0A2A" + }, + ... + ], + "total_size_in_bytes": 12911712, + "init_progress": { + "percentage": "100%" + }, + "total_entities": 33, + "active_entities": 32, + "ad_task": { + "ad_task": { + "task_id": "D3I5TnwBYwCbWecg7lN9", + "last_update_time": 1633399993685, + "started_by": "admin", + "state": "RUNNING", + "detector_id": "3Dh6TXwBwf_U8gjURE0F", + "task_progress": 0, + "init_progress": 0, + "execution_start_time": 1633399991933, + "is_latest": true, + "task_type": "HISTORICAL_HC_DETECTOR", + "coordinating_node": "2Z4q22BySEyzakYt_A0A2A", + "detector": { + "name": "testhc-mc", + "description": "test", + "time_field": "timestamp", + "indices": [ + "server_log" + ], + "filter_query": { + "match_all": { + "boost": 1 + } + }, + "detection_interval": { + "period": { + "interval": 5, + "unit": "Minutes" + } + }, + "window_delay": { + "period": { + "interval": 1, + "unit": "Minutes" + } + }, + "shingle_size": 8, + "schema_version": 0, + "feature_attributes": [ + { + "feature_id": "2zh6TXwBwf_U8gjUQ039", + "feature_name": "test", + "feature_enabled": true, + "aggregation_query": { + "test": { + "sum": { + "field": "value" + } + } + } + } + ], + "ui_metadata": { + "features": { + "test": { + "aggregationBy": "sum", + "aggregationOf": "value", + "featureType": "simple_aggs" + } + }, + "filters": [] + }, + "last_update_time": 1633387430916, + "category_field": [ + "ip", + "error_type" + ], + "user": { + "name": "admin", + "backend_roles": [ + "admin" + ], + "roles": [ + "own_index", + "all_access" + ], + "custom_attribute_names": [], + "user_requested_tenant": "__user__" + }, + "detector_type": "MULTI_ENTITY" + }, + "detection_date_range": { + "start_time": 1632793800000, + "end_time": 1633398600000 + }, + "user": { + "name": "admin", + "backend_roles": [ + "admin" + ], + "roles": [ + "own_index", + "all_access" + ], + "custom_attribute_names": [], + "user_requested_tenant": "__user__" + } + }, + "node_id": "2Z4q22BySEyzakYt_A0A2A", + "task_id": "D3I5TnwBYwCbWecg7lN9", + "task_type": "HISTORICAL_HC_DETECTOR", + "detector_task_slots": 10, + "total_entities_count": 32, + "pending_entities_count": 22, + "running_entities_count": 10, + "running_entities": [ """[{"name":"ip","value":"192.168.1.1"},{"name":"error_type","value":"error9"}]""", + ...], + "entity_task_profiles": [ + { + "shingle_size": 8, + "rcf_total_updates": 1994, + "threshold_model_trained": true, + "threshold_model_training_data_size": 0, + "model_size_in_bytes": 1593240, + "node_id": "2Z4q22BySEyzakYt_A0A2A", + "entity": [ + { + "name": "ip", + "value": "192.168.1.1" + }, + { + "name": "error_type", + "value": "error7" + } + ], + "task_id": "E3I5TnwBYwCbWecg9FMm", + "task_type": "HISTORICAL_HC_ENTITY" + }, + ... + ] + }, + "model_count": 32 +} + +GET _plugins/_anomaly_detection/detectors//_profile/total_size_in_bytes + +{ + "total_size_in_bytes": 13369344 +} +``` + +You can see the `ad_task` field only for historical analysis. + +The `model_count` parameter shows the total number of models that a detector runs on each node’s memory. This is useful if you have several models running on your cluster and want to know the count. + +If you configured the category field, you can see the number of unique values in the field and all active entities with models running in memory. + +You can use this data to estimate how much memory is required for anomaly detection so you can decide how to size your cluster. For example, if a detector has one million entities and only 10 of them are active in memory, you need to scale your cluster up or out. + +For a single-entity detector: + +#### Sample response + +```json +{ + "state": "INIT", + "total_size_in_bytes": 0, + "init_progress": { + "percentage": "0%", + "needed_shingles": 128 + }, + "ad_task": { + "ad_task": { + "task_id": "cfUNOXwBFLNqSEcxAlde", + "last_update_time": 1633044731640, + "started_by": "admin", + "state": "RUNNING", + "detector_id": "qL4NOXwB__6eNorTAKtJ", + "task_progress": 0.49603173, + "init_progress": 1, + "current_piece": 1632739800000, + "execution_start_time": 1633044726365, + "is_latest": true, + "task_type": "HISTORICAL_SINGLE_ENTITY", + "coordinating_node": "bCtWtxWPThq0BIn5P5I4Xw", + "worker_node": "dIyavWhmSYWGz65b4u-lpQ", + "detector": { + "name": "detector1", + "description": "test", + "time_field": "timestamp", + "indices": [ + "server_log" + ], + "filter_query": { + "match_all": { + "boost": 1 + } + }, + "detection_interval": { + "period": { + "interval": 5, + "unit": "Minutes" + } + }, + "window_delay": { + "period": { + "interval": 1, + "unit": "Minutes" + } + }, + "shingle_size": 8, + "schema_version": 0, + "feature_attributes": [ + { + "feature_id": "p74NOXwB__6eNorTAKss", + "feature_name": "test-feature", + "feature_enabled": true, + "aggregation_query": { + "test_feature": { + "sum": { + "field": "value" + } + } + } + } + ], + "ui_metadata": { + "features": { + "test-feature": { + "aggregationBy": "sum", + "aggregationOf": "value", + "featureType": "simple_aggs" + } + }, + "filters": [] + }, + "last_update_time": 1633044725832, + "user": { + "name": "admin", + "backend_roles": [ + "admin" + ], + "roles": [ + "own_index", + "all_access" + ], + "custom_attribute_names": [], + "user_requested_tenant": "__user__" + }, + "detector_type": "SINGLE_ENTITY" + }, + "detection_date_range": { + "start_time": 1632439925885, + "end_time": 1633044725885 + }, + "user": { + "name": "admin", + "backend_roles": [ + "admin" + ], + "roles": [ + "own_index", + "all_access" + ], + "custom_attribute_names": [], + "user_requested_tenant": "__user__" + } + }, + "shingle_size": 8, + "rcf_total_updates": 1994, + "threshold_model_trained": true, + "threshold_model_training_data_size": 0, + "model_size_in_bytes": 1593240, + "node_id": "dIyavWhmSYWGz65b4u-lpQ", + "detector_task_slots": 1 + } +} +``` + +The `total_entities` parameter shows you the total number of entities including the number of category fields for a detector. + +Getting the total count of entities is an expensive operation for real-time analysis of a detector with more than one category field. By default, for a real-time detection profile, a detector counts the number of entities up to a value of 10,000. For historical analysis, the anomaly detection plugin only detects the top 1,000 entities by default and caches the top entities in memory, so it doesn't cost much to get the total count of entities for historical analysis. + +The `profile` operation also provides information about each entity, such as the entity’s `last_sample_timestamp` and `last_active_timestamp`. `last_sample_timestamp` shows the last document in the input data source index containing the entity, while `last_active_timestamp` shows the timestamp when the entity’s model was last seen in the model cache. + +If there are no anomaly results for an entity, either the entity doesn't have any sample data or its model is removed from the model cache. + +#### Request + +```json +GET _plugins/_anomaly_detection/detectors//_profile?_all=true +{ + "entity": [ + { + "name": "host", + "value": "i-00f28ec1eb8997686" + } + ] +} +``` + +#### Sample Responses + +```json +{ + "category_field": "host", + "value": "i-00f28ec1eb8997686", + "is_active": true, + "last_active_timestamp": 1604026394879, + "last_sample_timestamp": 1604026394879, + "init_progress": { + "percentage": "100%" + }, + "model": { + "model_id": "TFUdd3UBBwIAGQeRh5IS_entity_i-00f28ec1eb8997686", + "model_size_in_bytes": 712480, + "node_id": "MQ-bTBW3Q2uU_2zX3pyEQg" + }, + "state": "RUNNING" +} +``` + +To get profile information for only historical analysis, specify `ad_task`. +Specifying `_all` is an expensive operation for multi-category high cardinality detectors. + +#### Request + +```json +GET _plugins/_anomaly_detection/detectors//_profile?_all +GET _plugins/_anomaly_detection/detectors//_profile/ad_task +``` + +#### Sample Responses + +```json +{ + "ad_task": { + "ad_task": { + "task_id": "CHI0TnwBYwCbWecgqgRA", + "last_update_time": 1633399648413, + "started_by": "admin", + "state": "RUNNING", + "detector_id": "3Dh6TXwBwf_U8gjURE0F", + "task_progress": 0, + "init_progress": 0, + "execution_start_time": 1633399646784, + "is_latest": true, + "task_type": "HISTORICAL_HC_DETECTOR", + "coordinating_node": "2Z4q22BySEyzakYt_A0A2A", + "detector": { + "name": "testhc-mc", + "description": "test", + "time_field": "timestamp", + "indices": [ + "server_log" + ], + "filter_query": { + "match_all": { + "boost": 1 + } + }, + "detection_interval": { + "period": { + "interval": 5, + "unit": "Minutes" + } + }, + "window_delay": { + "period": { + "interval": 1, + "unit": "Minutes" + } + }, + "shingle_size": 8, + "schema_version": 0, + "feature_attributes": [ + { + "feature_id": "2zh6TXwBwf_U8gjUQ039", + "feature_name": "test", + "feature_enabled": true, + "aggregation_query": { + "test": { + "sum": { + "field": "value" + } + } + } + } + ], + "ui_metadata": { + "features": { + "test": { + "aggregationBy": "sum", + "aggregationOf": "value", + "featureType": "simple_aggs" + } + }, + "filters": [] + }, + "last_update_time": 1633387430916, + "category_field": [ + "ip", + "error_type" + ], + "user": { + "name": "admin", + "backend_roles": [ + "admin" + ], + "roles": [ + "own_index", + "all_access" + ], + "custom_attribute_names": [], + "user_requested_tenant": "__user__" + }, + "detector_type": "MULTI_ENTITY" + }, + "detection_date_range": { + "start_time": 1632793800000, + "end_time": 1633398600000 + }, + "user": { + "name": "admin", + "backend_roles": [ + "admin" + ], + "roles": [ + "own_index", + "all_access" + ], + "custom_attribute_names": [], + "user_requested_tenant": "__user__" + } + }, + "node_id": "2Z4q22BySEyzakYt_A0A2A", + "task_id": "CHI0TnwBYwCbWecgqgRA", + "task_type": "HISTORICAL_HC_DETECTOR", + "detector_task_slots": 10, + "total_entities_count": 32, + "pending_entities_count": 22, + "running_entities_count": 10, + "running_entities" : [ + """[{"name":"ip","value":"192.168.1.1"},{"name":"error_type","value":"error9"}]""", + ... + ], + "entity_task_profiles": [ + { + "shingle_size": 8, + "rcf_total_updates": 994, + "threshold_model_trained": true, + "threshold_model_training_data_size": 0, + "model_size_in_bytes": 1593240, + "node_id": "2Z4q22BySEyzakYt_A0A2A", + "entity": [ + { + "name": "ip", + "value": "192.168.1.1" + }, + { + "name": "error_type", + "value": "error6" + } + ], + "task_id": "9XI0TnwBYwCbWecgsAd6", + "task_type": "HISTORICAL_HC_ENTITY" + }, + ... + ] + } } ``` @@ -1718,7 +2918,6 @@ DELETE _plugins/_anomaly_detection/detectors/results } ``` - #### Sample response ```json @@ -1743,486 +2942,6 @@ DELETE _plugins/_anomaly_detection/detectors/results } ``` - ---- - -## Search detector -Introduced 1.0 -{: .label .label-purple } - -Returns all anomaly detectors for a search query. - -#### Request - -```json -GET _plugins/_anomaly_detection/detectors/_search -POST _plugins/_anomaly_detection/detectors/_search -{ - "query": { - "bool": { - "filter": [ - { - "terms": { - "indices": [ - "server_log" - ] - } - } - ] - } - } -} -``` - -#### Sample response - -```json -{ - "took": 2, - "timed_out": false, - "_shards": { - "total": 1, - "successful": 1, - "skipped": 0, - "failed": 0 - }, - "hits": { - "total": { - "value": 1, - "relation": "eq" - }, - "max_score": 0, - "hits": [ - { - "_index": ".opensearch-anomaly-detectors", - "_type": "_doc", - "_id": "rlDtOHwBD5tpxlbyW7Nt", - "_version": 1, - "_seq_no": 0, - "_primary_term": 1, - "_score": 0, - "_source": { - "name": "test-detector", - "description": "test", - "time_field": "timestamp", - "indices": [ - "server_log" - ], - "filter_query": { - "match_all": { - "boost": 1 - } - }, - "detection_interval": { - "period": { - "interval": 5, - "unit": "Minutes" - } - }, - "window_delay": { - "period": { - "interval": 1, - "unit": "Minutes" - } - }, - "shingle_size": 8, - "schema_version": 0, - "feature_attributes": [ - { - "feature_id": "7VDtOHwBD5tpxlbyWqPs", - "feature_name": "test-feature", - "feature_enabled": true, - "aggregation_query": { - "test_feature": { - "sum": { - "field": "value" - } - } - } - } - ], - "last_update_time": 1633042652012, - "category_field": [ - "type" - ], - "user": { - "name": "admin", - "backend_roles": [ - "admin" - ], - "roles": [ - "own_index", - "all_access" - ], - "custom_attribute_names": [], - "user_requested_tenant": null - }, - "detector_type": "MULTI_ENTITY" - } - } - ] - } -} -``` - ---- - -## Get detector stats -Introduced 1.0 -{: .label .label-purple } - -Provides information about how the plugin is performing. - -#### Request - -```json -GET _plugins/_anomaly_detection/stats -GET _plugins/_anomaly_detection//stats -GET _plugins/_anomaly_detection//stats/ -GET _plugins/_anomaly_detection/stats/ -``` - -#### Sample response - -```json -{ - "anomaly_detectors_index_status": "yellow", - "anomaly_detection_state_status": "yellow", - "single_entity_detector_count": 0, - "detector_count": 1, - "multi_entity_detector_count": 0, - "anomaly_detection_job_index_status": "yellow", - "models_checkpoint_index_status": "yellow", - "anomaly_results_index_status": "yellow", - "nodes": { - "hhfW2ZNVTJCtbs8rO-nF4g": { - "ad_execute_request_count": 6, - "models": [ - { - "detector_id": "mmZFeXsB7JcKN0mdnMf4", - "model_type": "entity", - "last_used_time": 1629827578975, - "model_id": "mmZFeXsB7JcKN0mdnMf4_entity_ic43SHH11NWr32xXgjRFwg", - "last_checkpoint_time": 1629827339211, - "entity": [ - { - "name": "host", - "value": "server_2" - }, - { - "name": "service", - "value": "app_6" - } - ] - }, - { - "detector_id": "mmZFeXsB7JcKN0mdnMf4", - "model_type": "entity", - "last_used_time": 1629827578979, - "model_id": "mmZFeXsB7JcKN0mdnMf4_entity_OIsxy2nXMVdngK6Vv3X0uw", - "last_checkpoint_time": 1629827342444, - "entity": [ - { - "name": "host", - "value": "server_2" - }, - { - "name": "service", - "value": "app_2" - } - ] - }, - { - "detector_id": "mmZFeXsB7JcKN0mdnMf4", - "model_type": "entity", - "last_used_time": 1629827578978, - "model_id": "mmZFeXsB7JcKN0mdnMf4_entity_I0L8K8ktyVnyL59CVFCLVQ", - "last_checkpoint_time": 1629827342068, - "entity": [ - { - "name": "host", - "value": "server_1" - }, - { - "name": "service", - "value": "app_4" - } - ] - }, - { - "detector_id": "mmZFeXsB7JcKN0mdnMf4", - "model_type": "entity", - "last_used_time": 1629827578975, - "model_id": "mmZFeXsB7JcKN0mdnMf4_entity_ZoNYVJsq5ry6e-SWXmAt1Q", - "last_checkpoint_time": 1629827339435, - "entity": [ - { - "name": "host", - "value": "server_1" - }, - { - "name": "service", - "value": "app_6" - } - ] - }, - { - "detector_id": "mmZFeXsB7JcKN0mdnMf4", - "model_type": "entity", - "last_used_time": 1629827578978, - "model_id": "mmZFeXsB7JcKN0mdnMf4_entity_qo2ANH_NS7Bg8iV4AJpHOw", - "last_checkpoint_time": 1629827341187, - "entity": [ - { - "name": "host", - "value": "server_3" - }, - { - "name": "service", - "value": "app_0" - } - ] - }, - { - "detector_id": "mmZFeXsB7JcKN0mdnMf4", - "model_type": "entity", - "last_used_time": 1629827578980, - "model_id": "mmZFeXsB7JcKN0mdnMf4_entity_412FoQwCykWTAhjVfDGQDg", - "last_checkpoint_time": 1629827342983, - "entity": [ - { - "name": "host", - "value": "server_1" - }, - { - "name": "service", - "value": "app_2" - } - ] - } - ], - "ad_canceled_batch_task_count": 0, - "ad_hc_execute_request_count": 6, - "ad_hc_execute_failure_count": 0, - "model_count": 21, - "ad_execute_failure_count": 0, - "ad_batch_task_failure_count": 0, - "ad_total_batch_task_execution_count": 0, - "ad_executing_batch_task_count": 0 - } - } -} -``` - -The `model_count` parameter shows the total number of models running on each node’s memory. -For historical analysis, you see the values for the following fields: - -- `ad_total_batch_task_execution_count` -- `ad_executing_batch_task_count` -- `ad_canceled_batch_task_count` -- `ad_batch_task_failure_count` - -If haven't run any historical analysis, these values show up as 0. - -#### Sample response - -```json -{ - "anomaly_detectors_index_status": "green", - "anomaly_detection_state_status": "green", - "single_entity_detector_count": 0, - "detector_count": 1, - "multi_entity_detector_count": 1, - "anomaly_detection_job_index_status": "green", - "models_checkpoint_index_status": "green", - "anomaly_results_index_status": "green", - "nodes": { - "bCtWtxWPThq0BIn5P5I4Xw": { - "ad_execute_request_count": 0, - "models": [ - { - "detector_id": "rlDtOHwBD5tpxlbyW7Nt", - "model_type": "entity", - "last_used_time": 1633044152729, - "model_id": "rlDtOHwBD5tpxlbyW7Nt_entity_error20", - "last_checkpoint_time": 1633043556222, - "entity": [ - { - "name": "type", - "value": "error20" - } - ] - }, - { - "detector_id": "rlDtOHwBD5tpxlbyW7Nt", - "model_type": "entity", - "last_used_time": 1633044152767, - "model_id": "rlDtOHwBD5tpxlbyW7Nt_entity_error31", - "last_checkpoint_time": 1633043855146, - "entity": [ - { - "name": "type", - "value": "error31" - } - ] - }, - { - "detector_id": "rlDtOHwBD5tpxlbyW7Nt", - "model_type": "entity", - "last_used_time": 1633044152732, - "model_id": "rlDtOHwBD5tpxlbyW7Nt_entity_error16", - "last_checkpoint_time": 1633043557253, - "entity": [ - { - "name": "type", - "value": "error16" - } - ] - } - ], - "ad_canceled_batch_task_count": 0, - "ad_hc_execute_request_count": 0, - "ad_hc_execute_failure_count": 0, - "model_count": 8, - "ad_execute_failure_count": 0, - "ad_batch_task_failure_count": 0, - "ad_total_batch_task_execution_count": 15, - "ad_executing_batch_task_count": 3 - }, - "dIyavWhmSYWGz65b4u-lpQ": { - "ad_execute_request_count": 0, - "models": [ - { - "detector_id": "rlDtOHwBD5tpxlbyW7Nt", - "model_type": "entity", - "last_used_time": 1633044152729, - "model_id": "rlDtOHwBD5tpxlbyW7Nt_entity_error3", - "last_checkpoint_time": 1633043256013, - "entity": [ - { - "name": "type", - "value": "error3" - } - ] - }, - { - "detector_id": "rlDtOHwBD5tpxlbyW7Nt", - "model_type": "entity", - "last_used_time": 1633044152727, - "model_id": "rlDtOHwBD5tpxlbyW7Nt_entity_error1", - "last_checkpoint_time": 1633043254819, - "entity": [ - { - "name": "type", - "value": "error1" - } - ] - }, - { - "detector_id": "rlDtOHwBD5tpxlbyW7Nt", - "model_type": "entity", - "last_used_time": 1633044152735, - "model_id": "rlDtOHwBD5tpxlbyW7Nt_entity_error22", - "last_checkpoint_time": 1633043557023, - "entity": [ - { - "name": "type", - "value": "error22" - } - ] - }, - { - "detector_id": "rlDtOHwBD5tpxlbyW7Nt", - "model_type": "entity", - "last_used_time": 1633044152763, - "model_id": "rlDtOHwBD5tpxlbyW7Nt_entity_error29", - "last_checkpoint_time": 1633043855226, - "entity": [ - { - "name": "type", - "value": "error29" - } - ] - } - ], - "ad_canceled_batch_task_count": 0, - "ad_hc_execute_request_count": 0, - "ad_hc_execute_failure_count": 0, - "model_count": 11, - "ad_execute_failure_count": 0, - "ad_batch_task_failure_count": 0, - "ad_total_batch_task_execution_count": 14, - "ad_executing_batch_task_count": 3 - }, - "2hEGbUw6ShaiKe05n_xLdA": { - "ad_execute_request_count": 5, - "models": [ - { - "detector_id": "rlDtOHwBD5tpxlbyW7Nt", - "model_type": "entity", - "last_used_time": 1633044152714, - "model_id": "rlDtOHwBD5tpxlbyW7Nt_entity_error5", - "last_checkpoint_time": 1633043256689, - "entity": [ - { - "name": "type", - "value": "error5" - } - ] - }, - { - "detector_id": "rlDtOHwBD5tpxlbyW7Nt", - "model_type": "entity", - "last_used_time": 1633044152720, - "model_id": "rlDtOHwBD5tpxlbyW7Nt_entity_error15", - "last_checkpoint_time": 1633043553786, - "entity": [ - { - "name": "type", - "value": "error15" - } - ] - }, - { - "detector_id": "rlDtOHwBD5tpxlbyW7Nt", - "model_type": "entity", - "last_used_time": 1633044152724, - "model_id": "rlDtOHwBD5tpxlbyW7Nt_entity_error17", - "last_checkpoint_time": 1633043554909, - "entity": [ - { - "name": "type", - "value": "error17" - } - ] - }, - { - "detector_id": "rlDtOHwBD5tpxlbyW7Nt", - "model_type": "entity", - "last_used_time": 1633044152751, - "model_id": "rlDtOHwBD5tpxlbyW7Nt_entity_error27", - "last_checkpoint_time": 1633043855105, - "entity": [ - { - "name": "type", - "value": "error27" - } - ] - } - ], - "ad_canceled_batch_task_count": 0, - "ad_hc_execute_request_count": 5, - "ad_hc_execute_failure_count": 0, - "model_count": 13, - "ad_execute_failure_count": 0, - "ad_batch_task_failure_count": 0, - "ad_total_batch_task_execution_count": 14, - "ad_executing_batch_task_count": 3 - } - } -} -``` - --- ## Create monitor @@ -2444,899 +3163,3 @@ POST _plugins/_alerting/monitors ``` --- - -## Profile detector -Introduced 1.0 -{: .label .label-purple } - -Returns information related to the current state of the detector and memory usage, including current errors and shingle size, to help troubleshoot the detector. - -This command helps locate logs by identifying the nodes that run the anomaly detector job for each detector. - -It also helps track the initialization percentage, the required shingles, and the estimated time left. - -#### Request - -```json -GET _plugins/_anomaly_detection/detectors//_profile/ -GET _plugins/_anomaly_detection/detectors//_profile?_all=true -GET _plugins/_anomaly_detection/detectors//_profile/ -GET _plugins/_anomaly_detection/detectors//_profile/, -``` - -#### Sample Responses - -```json -GET _plugins/_anomaly_detection/detectors//_profile -{ - "state": "DISABLED", - "error": "Stopped detector: AD models memory usage exceeds our limit." -} - -GET _plugins/_anomaly_detection/detectors//_profile?_all=true&pretty -{ - "state": "RUNNING", - "error": "", - "models": [ - { - "model_id": "rlDtOHwBD5tpxlbyW7Nt_entity_error20", - "entity": [ - { - "name": "type", - "value": "error20" - } - ], - "model_size_in_bytes": 403491, - "node_id": "bCtWtxWPThq0BIn5P5I4Xw" - }, - { - "model_id": "rlDtOHwBD5tpxlbyW7Nt_entity_error31", - "entity": [ - { - "name": "type", - "value": "error31" - } - ], - "model_size_in_bytes": 403491, - "node_id": "bCtWtxWPThq0BIn5P5I4Xw" - }, - { - "model_id": "rlDtOHwBD5tpxlbyW7Nt_entity_error21", - "entity": [ - { - "name": "type", - "value": "error21" - } - ], - "model_size_in_bytes": 403491, - "node_id": "bCtWtxWPThq0BIn5P5I4Xw" - }, - { - "model_id": "rlDtOHwBD5tpxlbyW7Nt_entity_error13", - "entity": [ - { - "name": "type", - "value": "error13" - } - ], - "model_size_in_bytes": 403491, - "node_id": "bCtWtxWPThq0BIn5P5I4Xw" - }, - { - "model_id": "rlDtOHwBD5tpxlbyW7Nt_entity_error24", - "entity": [ - { - "name": "type", - "value": "error24" - } - ], - "model_size_in_bytes": 403491, - "node_id": "bCtWtxWPThq0BIn5P5I4Xw" - }, - { - "model_id": "rlDtOHwBD5tpxlbyW7Nt_entity_error25", - "entity": [ - { - "name": "type", - "value": "error25" - } - ], - "model_size_in_bytes": 403491, - "node_id": "bCtWtxWPThq0BIn5P5I4Xw" - }, - { - "model_id": "rlDtOHwBD5tpxlbyW7Nt_entity_error28", - "entity": [ - { - "name": "type", - "value": "error28" - } - ], - "model_size_in_bytes": 403491, - "node_id": "bCtWtxWPThq0BIn5P5I4Xw" - }, - { - "model_id": "rlDtOHwBD5tpxlbyW7Nt_entity_error16", - "entity": [ - { - "name": "type", - "value": "error16" - } - ], - "model_size_in_bytes": 403491, - "node_id": "bCtWtxWPThq0BIn5P5I4Xw" - }, - { - "model_id": "rlDtOHwBD5tpxlbyW7Nt_entity_error3", - "entity": [ - { - "name": "type", - "value": "error3" - } - ], - "model_size_in_bytes": 403491, - "node_id": "dIyavWhmSYWGz65b4u-lpQ" - }, - { - "model_id": "rlDtOHwBD5tpxlbyW7Nt_entity_error27", - "entity": [ - { - "name": "type", - "value": "error27" - } - ], - "model_size_in_bytes": 403491, - "node_id": "2hEGbUw6ShaiKe05n_xLdA" - } - ], - "total_size_in_bytes": 12911712, - "init_progress": { - "percentage": "100%" - }, - "total_entities": 33, - "active_entities": 32, - "ad_task": { - "ad_task": { - "task_id": "Os4HOXwBCi2h__AONgpc", - "last_update_time": 1633044347855, - "started_by": "admin", - "state": "RUNNING", - "detector_id": "rlDtOHwBD5tpxlbyW7Nt", - "task_progress": 0, - "init_progress": 0, - "execution_start_time": 1633044346460, - "is_latest": true, - "task_type": "HISTORICAL_HC_DETECTOR", - "coordinating_node": "2hEGbUw6ShaiKe05n_xLdA", - "detector": { - "name": "test-detector", - "description": "test", - "time_field": "timestamp", - "indices": [ - "server_log" - ], - "filter_query": { - "match_all": { - "boost": 1 - } - }, - "detection_interval": { - "period": { - "interval": 5, - "unit": "Minutes" - } - }, - "window_delay": { - "period": { - "interval": 1, - "unit": "Minutes" - } - }, - "shingle_size": 8, - "schema_version": 0, - "feature_attributes": [ - { - "feature_id": "7VDtOHwBD5tpxlbyWqPs", - "feature_name": "test-feature", - "feature_enabled": true, - "aggregation_query": { - "test_feature": { - "sum": { - "field": "value" - } - } - } - } - ], - "ui_metadata": { - "features": { - "test-feature": { - "aggregationBy": "sum", - "aggregationOf": "value", - "featureType": "simple_aggs" - } - }, - "filters": [] - }, - "last_update_time": 1633042652012, - "category_field": [ - "type" - ], - "user": { - "name": "admin", - "backend_roles": [ - "admin" - ], - "roles": [ - "own_index", - "all_access" - ], - "custom_attribute_names": [], - "user_requested_tenant": null - }, - "detector_type": "MULTI_ENTITY" - }, - "detection_date_range": { - "start_time": 1632437820000, - "end_time": 1633042620000 - }, - "user": { - "name": "admin", - "backend_roles": [ - "admin" - ], - "roles": [ - "own_index", - "all_access" - ], - "custom_attribute_names": [], - "user_requested_tenant": "__user__" - } - }, - "node_id": "2hEGbUw6ShaiKe05n_xLdA", - "task_id": "Os4HOXwBCi2h__AONgpc", - "task_type": "HISTORICAL_HC_DETECTOR", - "detector_task_slots": 10, - "total_entities_count": 32, - "pending_entities_count": 22, - "running_entities_count": 10, - "running_entities": [ - "error9", - "error8", - "error7", - "error6", - "error5", - "error4", - "error32", - "error31", - "error30", - "error3" - ], - "entity_task_profiles": [ - { - "shingle_size": 8, - "rcf_total_updates": 994, - "threshold_model_trained": true, - "threshold_model_training_data_size": 0, - "model_size_in_bytes": 1593240, - "node_id": "bCtWtxWPThq0BIn5P5I4Xw", - "entity": [ - { - "name": "type", - "value": "error6" - } - ], - "task_id": "P84HOXwBCi2h__AOOgrC", - "task_type": "HISTORICAL_HC_ENTITY" - }, - { - "shingle_size": 8, - "rcf_total_updates": 994, - "threshold_model_trained": true, - "threshold_model_training_data_size": 0, - "model_size_in_bytes": 1593240, - "node_id": "dIyavWhmSYWGz65b4u-lpQ", - "entity": [ - { - "name": "type", - "value": "error4" - } - ], - "task_id": "Kc4HOXwBCi2h__AOOw6Y", - "task_type": "HISTORICAL_HC_ENTITY" - }, - { - "shingle_size": 8, - "rcf_total_updates": 994, - "threshold_model_trained": true, - "threshold_model_training_data_size": 0, - "model_size_in_bytes": 1593240, - "node_id": "dIyavWhmSYWGz65b4u-lpQ", - "entity": [ - { - "name": "type", - "value": "error8" - } - ], - "task_id": "Pc4HOXwBCi2h__AOOgqJ", - "task_type": "HISTORICAL_HC_ENTITY" - }, - { - "shingle_size": 8, - "rcf_total_updates": 994, - "threshold_model_trained": true, - "threshold_model_training_data_size": 0, - "model_size_in_bytes": 1593240, - "node_id": "2hEGbUw6ShaiKe05n_xLdA", - "entity": [ - { - "name": "type", - "value": "error7" - } - ], - "task_id": "Ps4HOXwBCi2h__AOOgqh", - "task_type": "HISTORICAL_HC_ENTITY" - } - ] - }, - "model_count": 32 -} - -GET _plugins/_anomaly_detection/detectors//_profile/total_size_in_bytes -{ - "total_size_in_bytes": 13369344 -} -``` - -You can see the `ad_task` field only for historical analysis. - -The `model_count` parameter shows the total number of models that a detector runs on each node’s memory. This is useful if you have several models running on your cluster and want to know the count. - -If you configured the category field, you can see the number of unique values in the field and all active entities with models running in memory. - -You can use this data to estimate how much memory is required for anomaly detection so you can decide how to size your cluster. For example, if a detector has one million entities and only 10 of them are active in memory, you need to scale your cluster up or out. - -#### Request - -```json -GET _plugins/_anomaly_detection/detectors//_profile?_all=true&pretty -{ - "state": "RUNNING", - "error": "", - "models": [ - { - "model_id": "rlDtOHwBD5tpxlbyW7Nt_entity_error20", - "entity": [ - { - "name": "type", - "value": "error20" - } - ], - "model_size_in_bytes": 403491, - "node_id": "bCtWtxWPThq0BIn5P5I4Xw" - }, - { - "model_id": "rlDtOHwBD5tpxlbyW7Nt_entity_error13", - "entity": [ - { - "name": "type", - "value": "error13" - } - ], - "model_size_in_bytes": 403491, - "node_id": "bCtWtxWPThq0BIn5P5I4Xw" - }, - { - "model_id": "rlDtOHwBD5tpxlbyW7Nt_entity_error27", - "entity": [ - { - "name": "type", - "value": "error27" - } - ], - "model_size_in_bytes": 403491, - "node_id": "2hEGbUw6ShaiKe05n_xLdA" - } - ], - "total_size_in_bytes": 12911712, - "init_progress": { - "percentage": "100%" - }, - "total_entities": 33, - "active_entities": 32, - "ad_task": { - "ad_task": { - "task_id": "Os4HOXwBCi2h__AONgpc", - "last_update_time": 1633044347855, - "started_by": "admin", - "state": "RUNNING", - "detector_id": "rlDtOHwBD5tpxlbyW7Nt", - "task_progress": 0, - "init_progress": 0, - "execution_start_time": 1633044346460, - "is_latest": true, - "task_type": "HISTORICAL_HC_DETECTOR", - "coordinating_node": "2hEGbUw6ShaiKe05n_xLdA", - "detector": { - "name": "test-detector", - "description": "test", - "time_field": "timestamp", - "indices": [ - "server_log" - ], - "filter_query": { - "match_all": { - "boost": 1 - } - }, - "detection_interval": { - "period": { - "interval": 5, - "unit": "Minutes" - } - }, - "window_delay": { - "period": { - "interval": 1, - "unit": "Minutes" - } - }, - "shingle_size": 8, - "schema_version": 0, - "feature_attributes": [ - { - "feature_id": "7VDtOHwBD5tpxlbyWqPs", - "feature_name": "test-feature", - "feature_enabled": true, - "aggregation_query": { - "test_feature": { - "sum": { - "field": "value" - } - } - } - } - ], - "ui_metadata": { - "features": { - "test-feature": { - "aggregationBy": "sum", - "aggregationOf": "value", - "featureType": "simple_aggs" - } - }, - "filters": [] - }, - "last_update_time": 1633042652012, - "category_field": [ - "type" - ], - "user": { - "name": "admin", - "backend_roles": [ - "admin" - ], - "roles": [ - "own_index", - "all_access" - ], - "custom_attribute_names": [], - "user_requested_tenant": null - }, - "detector_type": "MULTI_ENTITY" - }, - "detection_date_range": { - "start_time": 1632437820000, - "end_time": 1633042620000 - }, - "user": { - "name": "admin", - "backend_roles": [ - "admin" - ], - "roles": [ - "own_index", - "all_access" - ], - "custom_attribute_names": [], - "user_requested_tenant": "__user__" - } - }, - "node_id": "2hEGbUw6ShaiKe05n_xLdA", - "task_id": "Os4HOXwBCi2h__AONgpc", - "task_type": "HISTORICAL_HC_DETECTOR", - "detector_task_slots": 10, - "total_entities_count": 32, - "pending_entities_count": 22, - "running_entities_count": 10, - "running_entities": [ - "error9", - "error8", - "error7", - "error6", - "error5", - "error4", - "error32", - "error31", - "error30", - "error3" - ], - "entity_task_profiles": [ - { - "shingle_size": 8, - "rcf_total_updates": 994, - "threshold_model_trained": true, - "threshold_model_training_data_size": 0, - "model_size_in_bytes": 1593240, - "node_id": "bCtWtxWPThq0BIn5P5I4Xw", - "entity": [ - { - "name": "type", - "value": "error6" - } - ], - "task_id": "P84HOXwBCi2h__AOOgrC", - "task_type": "HISTORICAL_HC_ENTITY" - }, - { - "shingle_size": 8, - "rcf_total_updates": 994, - "threshold_model_trained": true, - "threshold_model_training_data_size": 0, - "model_size_in_bytes": 1593240, - "node_id": "bCtWtxWPThq0BIn5P5I4Xw", - "entity": [ - { - "name": "type", - "value": "error5" - } - ], - "task_id": "QM4HOXwBCi2h__AOOgre", - "task_type": "HISTORICAL_HC_ENTITY" - }, - { - "shingle_size": 8, - "rcf_total_updates": 994, - "threshold_model_trained": true, - "threshold_model_training_data_size": 0, - "model_size_in_bytes": 1593240, - "node_id": "bCtWtxWPThq0BIn5P5I4Xw", - "entity": [ - { - "name": "type", - "value": "error9" - } - ], - "task_id": "PM4HOXwBCi2h__AOOgp3", - "task_type": "HISTORICAL_HC_ENTITY" - }, - { - "shingle_size": 8, - "rcf_total_updates": 994, - "threshold_model_trained": true, - "threshold_model_training_data_size": 0, - "model_size_in_bytes": 1593240, - "node_id": "2hEGbUw6ShaiKe05n_xLdA", - "entity": [ - { - "name": "type", - "value": "error3" - } - ], - "task_id": "Fs4HOXwBCi2h__AOPBLH", - "task_type": "HISTORICAL_HC_ENTITY" - }, - { - "shingle_size": 8, - "rcf_total_updates": 994, - "threshold_model_trained": true, - "threshold_model_training_data_size": 0, - "model_size_in_bytes": 1593240, - "node_id": "2hEGbUw6ShaiKe05n_xLdA", - "entity": [ - { - "name": "type", - "value": "error32" - } - ], - "task_id": "Ks4HOXwBCi2h__AOOw7D", - "task_type": "HISTORICAL_HC_ENTITY" - }, - { - "shingle_size": 8, - "rcf_total_updates": 994, - "threshold_model_trained": true, - "threshold_model_training_data_size": 0, - "model_size_in_bytes": 1593240, - "node_id": "2hEGbUw6ShaiKe05n_xLdA", - "entity": [ - { - "name": "type", - "value": "error7" - } - ], - "task_id": "Ps4HOXwBCi2h__AOOgqh", - "task_type": "HISTORICAL_HC_ENTITY" - } - ] - }, - "model_count": 32 -} -``` - -For a single-entity detector: - -#### Sample response - -```json -{ - "state": "INIT", - "total_size_in_bytes": 0, - "init_progress": { - "percentage": "0%", - "needed_shingles": 128 - }, - "ad_task": { - "ad_task": { - "task_id": "cfUNOXwBFLNqSEcxAlde", - "last_update_time": 1633044731640, - "started_by": "admin", - "state": "RUNNING", - "detector_id": "qL4NOXwB__6eNorTAKtJ", - "task_progress": 0.49603173, - "init_progress": 1, - "current_piece": 1632739800000, - "execution_start_time": 1633044726365, - "is_latest": true, - "task_type": "HISTORICAL_SINGLE_ENTITY", - "coordinating_node": "bCtWtxWPThq0BIn5P5I4Xw", - "worker_node": "dIyavWhmSYWGz65b4u-lpQ", - "detector": { - "name": "detector1", - "description": "test", - "time_field": "timestamp", - "indices": [ - "server_log" - ], - "filter_query": { - "match_all": { - "boost": 1 - } - }, - "detection_interval": { - "period": { - "interval": 5, - "unit": "Minutes" - } - }, - "window_delay": { - "period": { - "interval": 1, - "unit": "Minutes" - } - }, - "shingle_size": 8, - "schema_version": 0, - "feature_attributes": [ - { - "feature_id": "p74NOXwB__6eNorTAKss", - "feature_name": "test-feature", - "feature_enabled": true, - "aggregation_query": { - "test_feature": { - "sum": { - "field": "value" - } - } - } - } - ], - "ui_metadata": { - "features": { - "test-feature": { - "aggregationBy": "sum", - "aggregationOf": "value", - "featureType": "simple_aggs" - } - }, - "filters": [] - }, - "last_update_time": 1633044725832, - "user": { - "name": "admin", - "backend_roles": [ - "admin" - ], - "roles": [ - "own_index", - "all_access" - ], - "custom_attribute_names": [], - "user_requested_tenant": "__user__" - }, - "detector_type": "SINGLE_ENTITY" - }, - "detection_date_range": { - "start_time": 1632439925885, - "end_time": 1633044725885 - }, - "user": { - "name": "admin", - "backend_roles": [ - "admin" - ], - "roles": [ - "own_index", - "all_access" - ], - "custom_attribute_names": [], - "user_requested_tenant": "__user__" - } - }, - "shingle_size": 8, - "rcf_total_updates": 1994, - "threshold_model_trained": true, - "threshold_model_training_data_size": 0, - "model_size_in_bytes": 1593240, - "node_id": "dIyavWhmSYWGz65b4u-lpQ", - "detector_task_slots": 1 - } -} -``` - -The `total_entities` parameter shows you the total number of entities including the number of category fields for a detector. - -Getting the total count of entities is an expensive operation for real-time analysis of a detector with more than one category field. By default, for a real-time detection profile, a detector counts the number of entities up to a value of 10,000. For historical analysis, the anomaly detection plugin only detects the top 1,000 entities by default and caches the top entities in memory to reduce the cost of getting the total count of entities for historical analysis. - -The `profile` operation also provides information about each entity, such as the entity’s `last_sample_timestamp` and `last_active_timestamp`. `last_sample_timestamp` shows the last document in the input data source index containing the entity, while `last_active_timestamp` shows the timestamp when the entity’s model was last seen in the model cache. - -If there are no anomaly results for an entity, either the entity doesn't have any sample data or its model is removed from the model cache. - - -#### Request - -```json -GET _plugins/_anomaly_detection/detectors//_profile?_all=true -{ - "entity": [ - { - "name": "host", - "value": "i-00f28ec1eb8997686" - } - ] -} -``` - -#### Sample Responses - -```json -{ - "category_field": "host", - "value": "i-00f28ec1eb8997686", - "is_active": true, - "last_active_timestamp": 1604026394879, - "last_sample_timestamp": 1604026394879, - "init_progress": { - "percentage": "100%" - }, - "model": { - "model_id": "TFUdd3UBBwIAGQeRh5IS_entity_i-00f28ec1eb8997686", - "model_size_in_bytes": 712480, - "node_id": "MQ-bTBW3Q2uU_2zX3pyEQg" - }, - "state": "RUNNING" -} -``` - -To get profile information for only historical analysis, specify `ad_task`. -Specifying `_all` is an expensive operation for multi-category high cardinality detectors. - -#### Request - -```json -GET _plugins/_anomaly_detection/detectors//_profile?_all -GET _plugins/_anomaly_detection/detectors//_profile/ad_task -``` - -#### Sample Responses - -```json -{ - "ad_task": { - "ad_task": { - "task_id": "JXxyG3YBv5IHYYfMlFS2", - "last_update_time": 1606778263543, - "state": "STOPPED", - "detector_id": "SwvxCHYBPhugfWD9QAL6", - "task_progress": 0.010480972, - "init_progress": 1, - "current_piece": 1578140400000, - "execution_start_time": 1606778262709, - "is_latest": true, - "task_type": "HISTORICAL", - "detector": { - "name": "historical_test1", - "description": "test", - "time_field": "timestamp", - "indices": [ - "server_log" - ], - "filter_query": { - "match_all": { - "boost": 1 - } - }, - "detection_interval": { - "period": { - "interval": 5, - "unit": "Minutes" - } - }, - "window_delay": { - "period": { - "interval": 1, - "unit": "Minutes" - } - }, - "shingle_size": 8, - "schema_version": 0, - "feature_attributes": [ - { - "feature_id": "zgvyCHYBPhugfWD9Ap_F", - "feature_name": "sum", - "feature_enabled": true, - "aggregation_query": { - "sum": { - "sum": { - "field": "value" - } - } - } - }, - { - "feature_id": "zwvyCHYBPhugfWD9Ap_G", - "feature_name": "max", - "feature_enabled": true, - "aggregation_query": { - "max": { - "max": { - "field": "value" - } - } - } - } - ], - "ui_metadata": { - "features": { - "max": { - "aggregationBy": "max", - "aggregationOf": "value", - "featureType": "simple_aggs" - }, - "sum": { - "aggregationBy": "sum", - "aggregationOf": "value", - "featureType": "simple_aggs" - } - }, - "filters": [], - "filterType": "simple_filter" - }, - "last_update_time": 1606467935713, - "detector_type": "HISTORICAL_SIGLE_ENTITY", - "detection_date_range": { - "start_time": 1577840400000, - "end_time": 1606463775000 - } - } - }, - "shingle_size": 8, - "rcf_total_updates": 1994, - "threshold_model_trained": true, - "threshold_model_training_data_size": 0, - "node_id": "Q9yznwxvTz-yJxtz7rJlLg" - } -} -``` - ---- diff --git a/_monitoring-plugins/ad/index.md b/_monitoring-plugins/ad/index.md index d41f6455..6abfe5ac 100644 --- a/_monitoring-plugins/ad/index.md +++ b/_monitoring-plugins/ad/index.md @@ -79,7 +79,7 @@ To get the entity model size of a detector, use the [profile detector API]({{sit This formula provides a good starting point, but make sure to test with a representative workload. {: .note } -For example, for a cluster with 3 data nodes, each with 8G of JVM heap size, a maximum memory percentage of 10% (default), and the entity model size of the detector as 1MB: the total number of unique entities supported is (8.096 * 10^9 * 0.1 / 1M ) * 3 = 2429. +For example, for a cluster with three data nodes, each with 8 GB of JVM heap size, a maximum memory percentage of 10% (default), and the entity model size of the detector as 1MB: the total number of unique entities supported is (8.096 * 10^9 * 0.1 / 1 MB ) * 3 = 2429. If you set the total number of unique entities higher than this number that you calculate (in this case: 2429), the anomaly detector makes its best effort to model the extra entities. The detector prioritizes entities that occur more often and are more recent. diff --git a/_monitoring-plugins/ad/settings.md b/_monitoring-plugins/ad/settings.md index 5aa73dc4..e63ab922 100644 --- a/_monitoring-plugins/ad/settings.md +++ b/_monitoring-plugins/ad/settings.md @@ -40,7 +40,7 @@ Setting | Default | Description `plugins.anomaly_detection.batch_task_piece_size` | 1,000 | 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 1,000 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 two pieces of the same historical analysis task. 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. `plugins.anomaly_detection.max_top_entities_for_historical_analysis` | 1,000 | The maximum number of top entities that you run for a high cardinality detector historical analysis. The range is from 1 to 10,000. -`plugins.anomaly_detection.max_running_entities_per_detector_for_historical_analysis` | 10 | The number of entity tasks that you can run in parallel for a single high cardinality detector. The task slots available on your cluster also impact how many entities run in parallel. If a cluster has 3 data nodes, each data node has 10 task slots by default. Say you already have two high cardinality detectors and each of them run 10 entities. If you start a single-flow detector that takes 1 task slot, the number of task slots available is 10 * 3 - 10 * 2 - 1 = 9. if you now start a new high cardinality detector, the detector can only run 9 entities in parallel and not 10. You can tune this value from 1 to 1,000 based on your cluster's capability. If you set a higher value, the anomaly detection plugin runs historical analysis faster but also consumes more resources. +`plugins.anomaly_detection.max_running_entities_per_detector_for_historical_analysis` | 10 | The number of entity tasks that you can run in parallel for a single high cardinality detector. The task slots available on your cluster also impact how many entities run in parallel. If a cluster has 3 data nodes, each data node has 10 task slots by default. Say you already have two high cardinality detectors and each of them run 10 entities. If you start a single-flow detector that takes 1 task slot, the number of task slots available is 10 * 3 - 10 * 2 - 1 = 9. If you now start a new high cardinality detector, the detector can only run 9 entities in parallel and not 10. You can tune this value from 1 to 1,000 based on your cluster's capability. If you set a higher value, the anomaly detection plugin runs historical analysis faster but also consumes more resources. `plugins.anomaly_detection.max_cached_deleted_tasks` | 1,000 | You can rerun historical analysis for a single detector as many times as you like. The anomaly detection plugin only keeps a limited number of old tasks, by default 1 old task. If you run historical analysis three times for a detector, the oldest task is deleted. Because historical analysis generates a number of anomaly results in a short span of time, it's necessary to clean up anomaly results for a deleted task. With this field, you can configure how many deleted tasks you can cache at most. The plugin cleans up a task's results when it's deleted. If the plugin fails to do this cleanup, it adds the task's results into a cache and an hourly cron job performs the cleanup. You can use this setting to limit how many old tasks are put into cache to avoid a DDoS attack. After an hour, if still you find an old task result in the cache, use the [delete detector results API]({{site.url}}{{site.baseurl}}/monitoring-plugins/ad/api/#delete-detector-results) to delete the task result manually. You can tune this setting from 1 to 10,000. `plugins.anomaly_detection.delete_anomaly_result_when_delete_detector` | False | Whether the anomaly detection plugin deletes the anomaly result when you delete a detector. If you want to save some disk space, especially if you've high cardinality detectors generating a lot of results, set this field to true. Alternatively, you can use the [delete detector results API]({{site.url}}{{site.baseurl}}/monitoring-plugins/ad/api/#delete-detector-results) to manually delete the results. `plugins.anomaly_detection.dedicated_cache_size` | 10 | If the real-time analysis of a high cardinality detector starts successfully, the anomaly detection plugin guarantees keeping 10 (dynamically adjustable via this setting) entities' models in memory per node. If the number of entities exceeds this limit, the plugin puts the extra entities' models in a memory space shared by all detectors. The actual number of entities varies based on the memory that you've available and the frequencies of the entities. If you'd like the plugin to guarantee keeping more entities' models in memory and if you're cluster has sufficient memory, you can increase this setting value. From 79737566a993993cf5f29ebd90000635debe804e Mon Sep 17 00:00:00 2001 From: Liz Snyder Date: Tue, 5 Oct 2021 08:37:21 -0700 Subject: [PATCH 121/167] Add stats APIs --- _replication-plugin/api.md | 146 ++++++++++++++++++++++++++++- _replication-plugin/auto-follow.md | 34 ++++++- _replication-plugin/get-started.md | 4 +- 3 files changed, 179 insertions(+), 5 deletions(-) diff --git a/_replication-plugin/api.md b/_replication-plugin/api.md index 58457c84..df4a34b3 100644 --- a/_replication-plugin/api.md +++ b/_replication-plugin/api.md @@ -83,6 +83,8 @@ POST /_plugins/_replication//_pause {} ``` +You can't resume replication after it's been paused for more than 12 hours. You must [stop replication]({{site.url}}{{site.baseurl}}/replication-plugin/api/#stop-replication), delete the follower index, and restart replication of the leader. + #### Sample response ```json @@ -142,7 +144,149 @@ GET /_plugins/_replication//_status ``` To include shard replication details in the response, add the `&verbose=true` parameter. -The leader and follower checkpoint values begin as negative integers and reflect the number of shards you have (-1 for one shard, -5 for five shards, and so on). The values increment to positive integers with each change that you make. For example, when you make a change on the leader index, the `leader_checkpoint` becomes `0`. The `follower_checkpoint` is initially still `-1` until the follower index pulls the change from the leader, at which point it increments to `0`. If the values are the same, it means the indices are fully synced. +The leader and follower checkpoint values begin as negative integers and reflect the shard count (-1 for one shard, -5 for five shards, and so on). The values increment toward positive integers with each change that you make. For example, when you make a change on the leader index, the `leader_checkpoint` becomes `0`. The `follower_checkpoint` is initially still `-1` until the follower index pulls the change from the leader, at which point it increments to `0`. If the values are the same, it means the indices are fully synced. + +## Get leader cluster stats +Introduced 1.1 +{: .label .label-purple } + +Gets information about replicated leader indices on a specified cluster. + +#### Request + +```json +GET /_plugins/_replication/leader_stats +``` + +#### Sample response + +```json +{ + "num_replicated_indices": 2, + "operations_read": 15, + "translog_size_bytes": 1355, + "operations_read_lucene": 0, + "operations_read_translog": 15, + "total_read_time_lucene_millis": 0, + "total_read_time_translog_millis": 659, + "bytes_read": 1000, + "index_stats":{ + "leader-index-1":{ + "operations_read": 7, + "translog_size_bytes": 639, + "operations_read_lucene": 0, + "operations_read_translog": 7, + "total_read_time_lucene_millis": 0, + "total_read_time_translog_millis": 353, + "bytes_read":466 + }, + "leader-index-2":{ + "operations_read": 8, + "translog_size_bytes": 716, + "operations_read_lucene": 0, + "operations_read_translog": 8, + "total_read_time_lucene_millis": 0, + "total_read_time_translog_millis": 306, + "bytes_read": 534 + } + } +} +``` + +## Get follower cluster stats +Introduced 1.1 +{: .label .label-purple } + +Gets information about follower (syncing) indices on a specified cluster. + +#### Request + +```json +GET /_plugins/_replication/follower_stats +``` + +#### Sample response + +```json +{ + "num_syncing_indices": 2, + "num_bootstrapping_indices": 0, + "num_paused_indices": 0, + "num_failed_indices": 0, + "num_shard_tasks": 2, + "num_index_tasks": 2, + "operations_written": 3, + "operations_read": 3, + "failed_read_requests": 0, + "throttled_read_requests": 0, + "failed_write_requests": 0, + "throttled_write_requests": 0, + "follower_checkpoint": 1, + "leader_checkpoint": 1, + "total_write_time_millis": 2290, + "index_stats":{ + "follower-index-1":{ + "operations_written": 2, + "operations_read": 2, + "failed_read_requests": 0, + "throttled_read_requests": 0, + "failed_write_requests": 0, + "throttled_write_requests": 0, + "follower_checkpoint": 1, + "leader_checkpoint": 1, + "total_write_time_millis": 1355 + }, + "follower-index-2":{ + "operations_written": 1, + "operations_read": 1, + "failed_read_requests": 0, + "throttled_read_requests": 0, + "failed_write_requests": 0, + "throttled_write_requests": 0, + "follower_checkpoint": 0, + "leader_checkpoint": 0, + "total_write_time_millis": 935 + } + } +} +``` + +## Get auto-follow stats +Introduced 1.1 +{: .label .label-purple } + +Gets information about auto-follow activity and any replication rules configured on the specified cluster. + +#### Request + +```json +GET /_plugins/_replication/autofollow_stats +``` + +#### Sample response + +```json +{ + "num_success_start_replication": 2, + "num_failed_start_replication": 0, + "num_failed_leader_calls": 0, + "failed_indices":[ + + ], + "autofollow_stats":[ + { + "name":"my-replication-rule", + "pattern":"movies*", + "num_success_start_replication": 2, + "num_failed_start_replication": 0, + "num_failed_leader_calls": 0, + "failed_indices":[ + + ] + } + ] +} +``` ## Update settings Introduced 1.1 diff --git a/_replication-plugin/auto-follow.md b/_replication-plugin/auto-follow.md index fd2e69b4..0098d4e4 100644 --- a/_replication-plugin/auto-follow.md +++ b/_replication-plugin/auto-follow.md @@ -24,9 +24,6 @@ If the security plugin is enabled, non-admin users need to be mapped to the appr Replication rules are a collection of patterns that you create against a single remote cluster. When you create a replication rule, it automatically starts replicating any *new* indices that match the pattern, but does not replicate matching indices that were previously created. -Make sure to note the names of all rules when you create them. The replication plugin currently does not include an API operation to retrieve a list of existing rules. -{: .tip } - Create a replication rule on the follower cluster: ```bash @@ -57,11 +54,42 @@ And confirm its replica shows up on the follower cluster: curl -XGET -u 'admin:admin' -k 'https://localhost:9200/_cat/indices?v' ``` +It might take several seconds for the index to appear. + ```bash health status index uuid pri rep docs.count docs.deleted store.size pri.store.size yellow open movies-0001 kHOxYYHxRMeszLjTD9rvSQ 1 1 0 0 208b 208b ``` +## Retrieve replication rules + +To retrieve a list of existing replication rules configured on a cluster, send the following request: + +```bash +curl -XGET -u 'admin:admin' -k 'https://localhost:9200/_plugins/_replication/autofollow_stats' + +{ + "num_success_start_replication": 1, + "num_failed_start_replication": 0, + "num_failed_leader_calls": 0, + "failed_indices":[ + + ], + "autofollow_stats":[ + { + "name":"my-replication-rule", + "pattern":"movies*", + "num_success_start_replication": 1, + "num_failed_start_replication": 0, + "num_failed_leader_calls": 0, + "failed_indices":[ + + ] + } + ] +} +``` + ## Delete a replication rule When you delete a replication rule, OpenSearch stops replicating *new* indices that match the pattern, but existing indices that the rule previously created continue to replicate. If you need to stop existing replication activity, use the [stop replication API operation]({{site.url}}{{site.baseurl}}/replication-plugin/api/#stop-replication). diff --git a/_replication-plugin/get-started.md b/_replication-plugin/get-started.md index 2ab9d755..5b0daace 100644 --- a/_replication-plugin/get-started.md +++ b/_replication-plugin/get-started.md @@ -189,7 +189,7 @@ curl -XGET -k -u 'admin:admin' 'https://localhost:9200/_plugins/_replication/fol Possible statuses are `SYNCING`, `BOOTSTRAPING`, `PAUSED`, and `REPLICATION NOT IN PROGRESS`. -The leader and follower checkpoint values begin as negative numbers and reflect the number of shards you have (-1 for one shard, -5 for five shards, and so on). The values increment with each change and illustrate how many updates the follower is behind the leader. If the indices are fully synced, the values are the same. +The leader and follower checkpoint values begin as negative numbers and reflect the shard count (-1 for one shard, -5 for five shards, and so on). The values increment with each change and illustrate how many updates the follower is behind the leader. If the indices are fully synced, the values are the same. To confirm that replication is actually happening, add a document to the leader index: @@ -246,6 +246,8 @@ curl -XPOST -k -H 'Content-Type: application/json' -u 'admin:admin' 'https://loc When replication resumes, the follower index picks up any changes that were made to the leader index while replication was paused. +Note that you can't resume replication after it's been paused for more than 12 hours. You must [stop replication]({{site.url}}{{site.baseurl}}/replication-plugin/api/#stop-replication), delete the follower index, and restart replication of the leader. + ## Stop replication Terminate replication of a specified index from the follower cluster: From c91b99037b5876b0c7bbddeafc9c4e7f0ec9d211 Mon Sep 17 00:00:00 2001 From: aetter Date: Tue, 5 Oct 2021 09:49:15 -0700 Subject: [PATCH 122/167] Add release highlights. --- version-history.md | 1 + 1 file changed, 1 insertion(+) diff --git a/version-history.md b/version-history.md index bb67d8b9..f5d8f3de 100644 --- a/version-history.md +++ b/version-history.md @@ -9,6 +9,7 @@ permalink: /version-history/ OpenSearch version | Release highlights | Release date :--- | :--- | :--- | :--- +[1.1.0](https://github.com/opensearch-project/opensearch-build/tree/main/release-notes/opensearch-release-notes-1.1.0.md) | Adds cross-cluster replication, security for Index Management, ARM support, bucket-level alerting, a CLI to help with upgrading from Elasticsearch OSS to OpenSearch, and enhancements to high cardinality data in the anomaly detection plugin. | 5 October 2021 [1.0.1](https://github.com/opensearch-project/opensearch-build/tree/main/release-notes/opensearch-release-notes-1.0.1.md) | Bug fixes. | 1 September 2021 [1.0.0](https://github.com/opensearch-project/opensearch-build/tree/main/release-notes/opensearch-release-notes-1.0.0.md) | General availability release. Adds compatibility setting for clients that require a version check before connecting. | 12 July 2021 [1.0.0-rc1](https://github.com/opensearch-project/opensearch-build/tree/main/release-notes/opensearch-release-notes-1.0.0-rc1.md) | First release candidate. | 7 June 2021 From 31003b1523e77e0972a453d49cfdb0559021b475 Mon Sep 17 00:00:00 2001 From: Miki Date: Tue, 17 Aug 2021 14:19:08 -0700 Subject: [PATCH 123/167] Add versioned documentation Reduce font size and expand width Signed-off-by: Miki --- _data/versions.json | 3 + _includes/head_custom.html | 6 + _layouts/default.html | 4 + _sass/color_schemes/opensearch.scss | 2 + _sass/custom/custom.scss | 20 +++- assets/js/_version-selector.js | 176 ++++++++++++++++++++++++++++ assets/js/version-selector.tpl | 9 ++ 7 files changed, 218 insertions(+), 2 deletions(-) create mode 100644 _data/versions.json create mode 100644 assets/js/_version-selector.js create mode 100644 assets/js/version-selector.tpl diff --git a/_data/versions.json b/_data/versions.json new file mode 100644 index 00000000..9e5f8d81 --- /dev/null +++ b/_data/versions.json @@ -0,0 +1,3 @@ +{ + "current": "1.0" +} \ No newline at end of file diff --git a/_includes/head_custom.html b/_includes/head_custom.html index 91ee8a17..1a18be03 100755 --- a/_includes/head_custom.html +++ b/_includes/head_custom.html @@ -6,3 +6,9 @@ {% endif %} + +{% if jekyll.environment == "development" %} + +{% else %} + +{% endif %} diff --git a/_layouts/default.html b/_layouts/default.html index d433719d..c5408662 100755 --- a/_layouts/default.html +++ b/_layouts/default.html @@ -57,6 +57,10 @@ layout: table_wrappers