Add forecasting section #10133

Naarcha-AWS · 2025-06-24T04:48:16Z

Description

Update #10123 with writer edits.

Break up index page intro three different pages, an Introduction, a Getting Started page, and a management page.
Security page edits.
Make API page fit template as much as possible

Issues Resolved

Closes #10069

Version

List the OpenSearch version to which this PR applies, e.g. 2.14, 2.12--2.14, or all.

Frontend features

If you're submitting documentation for an OpenSearch Dashboards feature, add a video that shows how a user will interact with the UI step by step. A voiceover is optional.

Checklist

By submitting this pull request, I confirm that my contribution is made under the terms of the Apache 2.0 license and subject to the Developers Certificate of Origin.
For more information on following Developer Certificate of Origin and signing off your commits, please check here.

Signed-off-by: Kaituo Li <[email protected]>

Signed-off-by: Archer <[email protected]>

github-actions · 2025-06-24T04:48:24Z

Thank you for submitting your PR. The PR states are In progress (or Draft) -> Tech review -> Doc review -> Editorial review -> Merged.

Before you submit your PR for doc review, make sure the content is technically accurate. If you need help finding a tech reviewer, tag a maintainer.

When you're ready for doc review, tag the assignee of this PR. The doc reviewer may push edits to the PR directly or leave comments and editorial suggestions for you to address (let us know in a comment if you have a preference). The doc reviewer will arrange for an editorial review.

Naarcha-AWS · 2025-06-24T04:49:18Z

@kaituo: I couldn't add my edits to your original PR. Can you take a look at this updated PR before I pass this to editorial?

Signed-off-by: Naarcha-AWS <[email protected]>

_observing-your-data/forecast/getting-started.md

_observing-your-data/forecast/managing-forecasters.md

_observing-your-data/forecast/security.md

natebower · 2025-06-24T18:31:02Z

@natebower: This is ready for your review.

Thanks @Naarcha-AWS. I'll aim to review tomorrow (6/25).

natebower

@Naarcha-AWS Editorial review complete. Please see my comments and changes. Thanks!

_observing-your-data/ad/index.md

_observing-your-data/forecast/api.md

_observing-your-data/forecast/security.md

natebower · 2025-06-25T13:51:40Z

_observing-your-data/forecast/security.md

+
+You can specify a custom index for forecast results instead of using the default result index. If the custom index does not already exist, it will be created automatically when you create a forecaster and start a real-time analysis or test run.
+
+If the custom index already exists, the Forecasting plugin checks that the index mapping matches the expected forecast result structure. To ensure compatibility, the index must conform to the schema defined in the [`forecast-results.json`](https://github.com/opensearch-project/anomaly-detection/blob/main/src/main/resources/mappings/forecast-results.json) file.


Suggested change

If the custom index already exists, the Forecasting plugin checks that the index mapping matches the expected forecast result structure. To ensure compatibility, the index must conform to the schema defined in the [`forecast-results.json`](https://github.com/opensearch-project/anomaly-detection/blob/main/src/main/resources/mappings/forecast-results.json) file.

If the custom index already exists, the Forecasting API checks that the index mapping matches the expected forecast result structure. To ensure compatibility, the index must conform to the schema defined in the [`forecast-results.json`](https://github.com/opensearch-project/anomaly-detection/blob/main/src/main/resources/mappings/forecast-results.json) file.

natebower · 2025-06-25T13:52:09Z

_observing-your-data/forecast/security.md

+
+If the custom index already exists, the Forecasting plugin checks that the index mapping matches the expected forecast result structure. To ensure compatibility, the index must conform to the schema defined in the [`forecast-results.json`](https://github.com/opensearch-project/anomaly-detection/blob/main/src/main/resources/mappings/forecast-results.json) file.
+
+When a user creates a forecaster—either in OpenSearch Dashboards or by calling the Forecasting API—the system verifies that the user has the following index-level permissions on the custom index:


Suggested change

When a user creates a forecaster—either in OpenSearch Dashboards or by calling the Forecasting API—the system verifies that the user has the following index-level permissions on the custom index:

When a user creates a forecaster—either in OpenSearch Dashboards or by calling the Forecasting API—the system verifies that the user has the following index-level permissions for the custom index:

natebower · 2025-06-25T13:53:38Z

_observing-your-data/forecast/security.md

+
+- `indices:admin/create` – Required to create and roll over the custom result index.
+- `indices:admin/aliases` – Required to create and manage the index alias.
+- `indices:data/write/index` – Required to write forecast results into the index (single-stream forecasters).


Suggested change

- `indices:data/write/index` – Required to write forecast results into the index (single-stream forecasters).

- `indices:data/write/index` – Required to write forecast results to the index (single-stream forecasters).

natebower · 2025-06-25T13:55:17Z

_observing-your-data/forecast/security.md

+
+## Next step
+
+For additional guidance on Transport Layer Security (TLS), authentication backends, tenant isolation, and audit logging, refer to the [Security plugin documentation]({{site.url}}{{site.baseurl}}/security/).


Suggested change

For additional guidance on Transport Layer Security (TLS), authentication backends, tenant isolation, and audit logging, refer to the [Security plugin documentation]({{site.url}}{{site.baseurl}}/security/).

For more information about TLS, authentication backends, tenant isolation, and audit logging, see the [Security plugin documentation]({{site.url}}{{site.baseurl}}/security/).

natebower

@Naarcha-AWS Editorial review complete. Please see my comments and changes. Thanks!

Naarcha-AWS · 2025-06-25T18:08:14Z

_observing-your-data/forecast/api.md

+
+### Example request: Built-in query with distance under a threshold
+
+The following request returns the top entities whose forecast values fall farthest under a specified threshold, based on the `DISTANCE_TO_THRESHOLD_VALUE` metric:


Suggested change

The following request returns the top entities whose forecast values fall farthest under a specified threshold, based on the `DISTANCE_TO_THRESHOLD_VALUE` metric:

The following request returns the top entities whose forecast values fall farthest from a specified threshold, based on the `DISTANCE_TO_THRESHOLD_VALUE` metric:

Naarcha-AWS · 2025-06-25T18:08:42Z

_observing-your-data/forecast/api.md

+The `DISTANCE_TO_THRESHOLD_VALUE` metric calculates `forecast_value – threshold`. Because `relation_to_threshold` is `LESS_THAN`, the API returns negative distances only and sorts them in ascending order (most negative first). Each bucket includes the following values:
+
+- `doc_count`: The number of forecast points that matched.
+- `DISTANCE_TO_THRESHOLD_VALUE`: The worst (most negative) distance within the forecast horizon.


Suggested change

- `DISTANCE_TO_THRESHOLD_VALUE`: The worst (most negative) distance within the forecast horizon.

- `DISTANCE_TO_THRESHOLD_VALUE`: The largest distance within the forecast horizon from the threshold value.

Naarcha-AWS · 2025-06-25T18:09:00Z

_observing-your-data/forecast/api.md

+**Introduced 3.1**  
+{: .label .label-purple }
+
+Returns execution-time state such as initialization progress, per-entity model metadata, and errors. This API is useful for inspecting forecaster internals during runtime.


Suggested change

Returns execution-time state such as initialization progress, per-entity model metadata, and errors. This API is useful for inspecting forecaster internals during runtime.

Returns execution-time state such as initialization progress, per-entity model metadata, and errors. This API is useful for inspecting forecaster intervals during runtime.

Naarcha-AWS · 2025-06-25T18:10:07Z

_observing-your-data/forecast/getting-started.md

+    ```
+
+
+4. Under **Timestamp field**, select the field that stores event time.


Suggested change

4. Under **Timestamp field**, select the field that stores event time.

4. Under **Timestamp field**, select the field that stores the timestamps.

Naarcha-AWS · 2025-06-25T18:13:10Z

_observing-your-data/forecast/getting-started.md

+|----------|-------------|------|------|---------|----------|
+| `result_index_min_size` | The minimum total primary shard size before rollover. | Integer | MB | `51200` (50 GB) | No |
+| `result_index_min_age` | The minimum index age to trigger rollover. | Integer | Days | `7` | No |
+| `result_index_ttl` | The minimum age before deletion. | Integer | Days | `60` | No |


Co-authored-by: Nathan Bower <[email protected]> Signed-off-by: Naarcha-AWS <[email protected]>

Signed-off-by: Naarcha-AWS <[email protected]>

_observing-your-data/forecast/api.md

_observing-your-data/forecast/managing-forecasters.md

Co-authored-by: Nathan Bower <[email protected]> Signed-off-by: Naarcha-AWS <[email protected]>

_observing-your-data/forecast/security.md

Naarcha-AWS · 2025-06-26T18:26:42Z

_observing-your-data/forecast/security.md

+
+To isolate results for another team, such as `human-resources`, create a separate role (for example, `forecast_human_resources_result_access`) and update the term value to match the appropriate backend role.
+
+### Define data-source read access


Suggested change

### Define data-source read access

### Define `data-source` read access

_observing-your-data/forecast/security.md

Co-authored-by: Nathan Bower <[email protected]> Signed-off-by: Naarcha-AWS <[email protected]>

_observing-your-data/forecast/security.md

Co-authored-by: Nathan Bower <[email protected]> Signed-off-by: Naarcha-AWS <[email protected]>

Signed-off-by: Naarcha-AWS <[email protected]>

Co-authored-by: Nathan Bower <[email protected]> Signed-off-by: Naarcha-AWS <[email protected]>

_observing-your-data/forecast/getting-started.md

Signed-off-by: Naarcha-AWS <[email protected]>

natebower · 2025-06-26T19:39:03Z

@Naarcha-AWS Just this one comment outstanding, and then we can merge.

_observing-your-data/forecast/security.md

Signed-off-by: Naarcha-AWS <[email protected]>

kaituo and others added 4 commits June 23, 2025 08:11

Forecasting doc

5b22f53

Signed-off-by: Kaituo Li <[email protected]>

Merge branch 'main' into forecasting

ebce30c

Break up intro page and getting started into seperate sections

f5dcb8f

Signed-off-by: Archer <[email protected]>

Writer edits for forecasting section

845957d

Signed-off-by: Archer <[email protected]>

Naarcha-AWS requested review from kolchfa-aws, AMoo-Miki, natebower, dlvenable and epugh as code owners June 24, 2025 04:48

github-actions bot assigned Naarcha-AWS Jun 24, 2025

Naarcha-AWS added v3.1.0 release-notes PR: Include this PR in the automated release notes labels Jun 24, 2025

Merge branch 'main' into kaituo-forecasting

dd2ddb0

Naarcha-AWS added the 4 - Doc review PR: Doc review in progress label Jun 24, 2025

Naarcha-AWS changed the title ~~Kaituo forecasting~~ Add forecasting section Jun 24, 2025

Naarcha-AWS added 2 commits June 23, 2025 23:55

Update index.md

0324d54

Signed-off-by: Naarcha-AWS <[email protected]>

Update index.md

b514f94

Signed-off-by: Naarcha-AWS <[email protected]>

Naarcha-AWS commented Jun 24, 2025

View reviewed changes

_observing-your-data/forecast/getting-started.md Outdated Show resolved Hide resolved

Naarcha-AWS commented Jun 24, 2025

View reviewed changes

_observing-your-data/forecast/getting-started.md Outdated Show resolved Hide resolved

Naarcha-AWS commented Jun 24, 2025

View reviewed changes

_observing-your-data/forecast/managing-forecasters.md Outdated Show resolved Hide resolved

Naarcha-AWS commented Jun 24, 2025

View reviewed changes

_observing-your-data/forecast/managing-forecasters.md Outdated Show resolved Hide resolved

Naarcha-AWS commented Jun 24, 2025

View reviewed changes

_observing-your-data/forecast/security.md Outdated Show resolved Hide resolved