본문 바로가기
WIKI 기술 지식 베이스

Forecasting API

원문 보기 위키 갱신

출처: 문서

본문

예측 API

이러한 작업을 사용하여 프로그래밍 방식으로 시계열 데이터에 대한 예측을 생성하는 예측기를 생성하고 관리할 수 있어요.

목차

  • TOC {:toc}

예측기 생성

3.1에서 도입됨 {: .label .label-purple }

시계열 예측을 생성하기 위한 예측기를 생성해요. 예측기는 단일 스트림(카테고리 필드 없음) 또는 고카디널리티(하나 이상의 카테고리 필드 있음)일 수 있어요.

예측기를 생성할 때 소스 인덱스, 예측 간격 및 예측 기간, 예측할 특성, 그리고 카테고리 필드 및 사용자 지정 결과 인덱스와 같은 선택적 매개변수를 정의해요.

엔드포인트

POST _plugins/_forecast/forecasters

요청 본문 필드

이 API는 다음 요청 본문 필드를 지원해요.

필드 데이터 유형 필수 설명
name String 필수 예측기 이름.
description String 선택 사항 예측기에 대한 자유 형식 설명.
time_field String 필수 소스 문서의 타임스탬프 필드.
indices String 또는 string[] 필수 하나 이상의 소스 인덱스 또는 인덱스 별칭.
feature_attributes Array of objects 필수 예측할 특성. 하나의 특성만 지원됨. 각 객체는 feature_name과 aggregation_query를 포함해야 함.
forecast_interval Object 필수 예측이 생성되는 간격.
horizon Integer 선택 사항 예측할 미래 간격 수.
window_delay Object 선택 사항 수집 지연을 고려하기 위해 추가된 지연.
category_field String 선택 사항 엔터티별로 예측을 그룹화하는 데 사용되는 하나 또는 두 개의 필드.
result_index String 선택 사항 예측 결과를 저장하기 위한 사용자 지정 인덱스 별칭. opensearch-forecast-result-로 시작해야 함. 기본값은 opensearch-forecast-results.
suggested_seasonality Integer 선택 사항 간격 단위의 계절 패턴 길이. 예상 범위: 8–256.
recency_emphasis Integer 선택 사항 최근 데이터가 예측에 영향을 미치는 정도를 제어함. 기본값은 2560.
history Integer 선택 사항 모델 훈련에 사용되는 과거 간격 수.
result_index_min_size Integer 선택 사항 인덱스 롤오버를 트리거하는 데 필요한 최소 기본 샤드 크기(MB).
result_index_min_age Integer 선택 사항 인덱스 롤오버를 트리거하는 데 필요한 최소 인덱스 기간(일).
result_index_ttl Integer 선택 사항 롤오버된 인덱스가 삭제되기 전 최소 시간(일).
flatten_custom_result_index Boolean 선택 사항 true인 경우 사용자 지정 결과 인덱스의 중첩 필드를 평면화하여 집계를 더 쉽게 함.
shingle_size Integer 선택 사항 예측에 영향을 미치는 데 사용되는 과거 간격 수. 기본값은 8. 권장 범위: 4–128.

예제 요청: 단일 스트림 예측기

다음 예제는 network-requests 인덱스에 대한 단일 스트림 예측기를 생성해요. 예측기는 이전 300개 간격을 훈련에 사용하여 3분마다 deny 필드의 최대값을 예측해요. window_delay 설정은 예측 창을 3분 지연시켜 수집 지연을 처리해요.

POST _plugins/_forecast/forecasters
{
    "name": "Second-Test-Forecaster-7",
    "description": "ok rate",
    "time_field": "@timestamp",
    "indices": [
        "network-requests"
    ],
    "feature_attributes": [
        {
            "feature_id": "deny_max",
            "feature_name": "deny max",
            "feature_enabled": true,
            "importance": 1,
            "aggregation_query": {
                "deny_max": {
                    "max": {
                        "field": "deny"
                    }
                }
            }
        }
    ],
    "window_delay": {
        "period": {
            "interval": 3,
            "unit": "MINUTES"
        }
    },
    "forecast_interval": {
        "period": {
            "interval": 3,
            "unit": "MINUTES"
        }
    },
    "schema_version": 2,
    "horizon": 3,
    "history": 300
}

{% include copy-curl.html %}

예제 응답

{
  "_id": "4WnXAYoBU2pVBal92lXD",
  "_version": 1,
  "forecaster": {
    "...": "Configuration (omitted)"
  }
}

예제 요청: 고카디널리티 예측기

다음 예제는 host_nest.host2 필드로 예측을 그룹화하는 고카디널리티 예측기를 생성해요. 단일 스트림 예제와 마찬가지로 기록 데이터를 사용하여 3분 간격으로 deny 필드의 최대값을 예측해요. 이 설정은 여러 호스트에 걸쳐 엔터티별 예측을 가능하게 해요.

POST _plugins/_forecast/forecasters
{
    "name": "Second-Test-Forecaster-7",
    "description": "ok rate",
    "time_field": "@timestamp",
    "indices": [
        "network-requests"
    ],
    "feature_attributes": [
        {
            "feature_id": "deny_max",
            "feature_name": "deny max",
            "feature_enabled": true,
            "importance": 1,
            "aggregation_query": {
                "deny_max": {
                    "max": {
                        "field": "deny"
                    }
                }
            }
        }
    ],
    "window_delay": {
        "period": {
            "interval": 3,
            "unit": "MINUTES"
        }
    },
    "forecast_interval": {
        "period": {
            "interval": 3,
            "unit": "MINUTES"
        }
    },
    "schema_version": 2,
    "horizon": 3,
    "history": 300,
    "category_field": ["host_nest.host2"],
}

{% include copy-curl.html %}

예제 응답

{
  "_id": "4WnXAYoBU2pVBal92lXD",
  "_version": 1,
  "forecaster": {
    "...": "Configuration (omitted)"
  }
}

예측기 검증

3.1에서 도입됨 {: .label .label-purple }

이 API를 사용하여 예측기 구성이 유효한지 확인할 수 있어요. 두 가지 유형의 검증을 수행할 수 있어요.

  • 구성 전용 검증: 구성이 구문적으로 올바르고 기존 필드를 참조하는지 확인해요.
  • 훈련 가능성 검증: 지정된 구성으로 예측기를 훈련할 수 있는지 포괄적으로 검증해요.

엔드포인트

예측기 검증에 사용할 수 있는 엔드포인트는 다음과 같아요.

구성 전용 검증:

POST _plugins/_forecast/forecasters/_validate

훈련 가능성 검증:

POST _plugins/_forecast/forecasters/_validate/model

요청 본문

요청 본문은 예측기를 생성할 때 사용하는 요청 본문과 동일해요. 최소한 다음 필수 필드(name, time_field, indices, feature_attributes, forecast_interval)를 포함해야 해요.

구성이 유효하면 응답은 빈 객체({})를 반환해요. 구성이 유효하지 않으면 응답에 자세한 오류 메시지가 포함돼요.

예제 요청: forecast_interval 누락

다음 요청은 forecast_interval이 누락된 유효하지 않은 예측기 구성을 보여줘요.

POST _plugins/_forecast/forecasters/_validate
{
  "name": "invalid-forecaster",
  "time_field": "@timestamp",
  "indices": ["network-requests"],
  "feature_attributes": [
    {
      "feature_id": "deny_max",
      "feature_name": "deny max",
      "feature_enabled": true,
      "aggregation_query": {
        "deny_max": {
          "max": {
            "field": "deny"
          }
        }
      }
    }
  ]
}

{% include copy-curl.html %}

예제 응답

{
  "forecaster": {
    "forecast_interval": {
      "message": "Forecast interval should be set"
    }
  }
}

구성 제안

3.1에서 도입됨 {: .label .label-purple }

데이터의 주기와 밀도를 기반으로 하나 이상의 예측기 매개변수(forecast_interval, horizon, history, window_delay)에 대한 적절한 값을 반환해요.

엔드포인트

POST _plugins/_forecast/forecasters/_suggest/<comma‑separated-types>

types는 forecast_interval, horizon, history, window_delay 중 하나 이상이어야 해요.

예제 요청: 간격 제안

다음 요청은 소스 데이터를 분석하고 평균 이벤트 빈도를 기반으로 예측기에 적절한 forecast_interval 값을 제안해요.

POST _plugins/_forecast/forecasters/_suggest/forecast_interval
{
  "name": "interval‑suggest",
  "time_field": "@timestamp",
  "indices": ["network-requests"],
  ...
}

{% include copy-curl.html %}

예제 응답

{
  "interval": {
    "period": { "interval": 1, "unit": "Minutes" }
  }
}

예측기 조회

3.1에서 도입됨 {: .label .label-purple }

예측기와 (선택적으로) 가장 최근 작업을 검색해요.

엔드포인트

GET _plugins/_forecast/forecasters/{forecaster_id}[?task=(true|false)]

예제 요청: 작업 포함

다음 요청은 예측기에 대한 메타데이터와, 지정된 경우 관련 작업에 대한 세부 정보를 반환해요.

GET _plugins/_forecast/forecasters/d7-r1YkB_Z-sgDOKo3Z5?task=true

{% include copy-curl.html %}

응답에는 forecaster, realtime_task, run_once_task 섹션이 포함돼요.

예측기 업데이트

3.1에서 도입됨 {: .label .label-purple }

기존 예측기의 구성을 업데이트해요. 업데이트를 수행하기 전에 실행 중인 예측 작업을 중지해야 해요.

category_field, result_index 또는 feature_attributes를 수정하는 등 모델에 영향을 주는 변경 사항은 OpenSearch Dashboards에 표시된 이전 결과를 무효화해요.

엔드포인트

PUT _plugins/_forecast/forecasters/{forecaster_id}

예제 요청: 이름, 결과 인덱스 및 카테고리 필드 업데이트

다음은 forecaster-i1nwqooBLXq6T-gGbXI- 예측기의 정의를 보여줘요.

{
    "_index": ".opensearch-forecasters",
    "_id": "forecaster-i1nwqooBLXq6T-gGbXI-",
    "_version": 1,
    "_seq_no": 0,
    "_primary_term": 1,
    "_score": 1.0,
    "_source": {
        "category_field": [
            "service"
        ],
        "description": "ok rate",
        "feature_attributes": [{
            "feature_id": "deny_max",
            "feature_enabled": true,
            "feature_name": "deny max",
            "aggregation_query": {
                "deny_max": {
                    "max": {
                        "field": "deny"
                    }
                }
            }
        }],
        "forecast_interval": {
            "period": {
                "unit": "Minutes",
                "interval": 1
            }
        },
        "schema_version": 2,
        "time_field": "@timestamp",
        "last_update_time": 1695084997949,
        "horizon": 24,
        "indices": [
            "network-requests"
        ],
        "window_delay": {
            "period": {
                "unit": "Seconds",
                "interval": 20
            }
        },
        "transform_decay": 1.0E-4,
        "name": "Second-Test-Forecaster-3",
        "filter_query": {
            "match_all": {
                "boost": 1.0
            }
        },
        "shingle_size": 8,
        "result_index": "opensearch-forecast-result-a"
    }
}

다음 요청은 예측기의 name, result_index, category_field 속성을 업데이트해요.

PUT localhost:9200/_plugins/_forecast/forecasters/forecast-i1nwqooBLXq6T-gGbXI-
{
    "name": "Second-Test-Forecaster-1",
    "description": "ok rate",
    "time_field": "@timestamp",
    "indices": [
        "network-requests"
    ],
    "feature_attributes": [
        {
            "feature_id": "deny_max",
            "feature_name": "deny max",
            "feature_enabled": true,
            "importance": 1,
            "aggregation_query": {
                "deny_max": {
                    "max": {
                        "field": "deny"
                    }
                }
            }
        }
    ],
    "window_delay": {
        "period": {
            "interval": 20,
            "unit": "SECONDS"
        }
    },
    "forecast_interval": {
        "period": {
            "interval": 1,
            "unit": "MINUTES"
        }
    },
    "ui_metadata": {
        "aabb": {
            "ab": "bb"
        }
    },
    "schema_version": 2,
    "horizon": 24,
    "category_field": ["service", "host"]
}

{% include copy-curl.html %}

예측기 삭제

3.1에서 도입됨 {: .label .label-purple }

예측기 구성을 삭제해요. 삭제 전에 관련된 실시간 또는 일회 실행 예측 작업을 중지해야 해요. 작업이 여전히 실행 중이면 API가 400 오류를 반환해요.

엔드포인트

DELETE _plugins/_forecast/forecasters/{forecaster_id}

예제 요청: 예측기 삭제

다음 요청은 고유 ID를 사용하여 예측기 구성을 삭제해요.

DELETE _plugins/_forecast/forecasters/forecast-i1nwqooBLXq6T-gGbXI-

{% include copy-curl.html %}

예측기 작업 시작

3.1에서 도입됨 {: .label .label-purple }

예측기에 대한 실시간 예측을 시작해요.

엔드포인트

POST _plugins/_forecast/forecasters/{forecaster_id}/_start

예제 요청: 예측기 작업 시작

다음 요청은 지정된 예측기에 대한 실시간 예측을 시작해요.

POST _plugins/_forecast/forecasters/4WnXAYoBU2pVBal92lXD/_start

{% include copy-curl.html %}

예제 응답

{ "_id": "4WnXAYoBU2pVBal92lXD" }

예측기 작업 중지

3.1에서 도입됨 {: .label .label-purple }

예측기에 대한 실시간 예측을 중지해요.

엔드포인트

POST _plugins/_forecast/forecasters/{forecaster_id}/_stop

예제 요청: 예측기 작업 중지

다음 요청은 지정된 예측기에 대한 실시간 예측 작업을 중지해요.

POST _plugins/_forecast/forecasters/4WnXAYoBU2pVBal92lXD/_stop

{% include copy-curl.html %}

일회 분석 실행

3.1에서 도입됨 {: .label .label-purple }

백테스팅(기록) 예측을 실행해요. 실시간 작업이 활성화된 동안에는 실행할 수 없어요.

엔드포인트

POST _plugins/_forecast/forecasters/{forecaster_id}/_run_once

예제 요청: 백테스팅 예측 실행

다음 요청은 지정된 예측기에 대한 일회 실행 예측 분석을 시작해요.

POST _plugins/_forecast/forecasters/{forecaster_id}/_run_once

{% include copy-curl.html %}

예제 응답

응답은 일회 실행 작업에 할당된 작업 ID를 반환해요.

{ "taskId": "vXZG85UBAlM4LplcKI0f" }

예제 요청: 작업 ID로 예측 결과 검색

반환된 taskId를 사용하여 opensearch-forecast-results* 인덱스를 쿼리하여 기록 예측 출력을 확인해요.

GET opensearch-forecast-results*/_search?pretty
{
  "sort": {
    "data_end_time": "desc"
  },
  "size": 10,
  "query": {
    "bool": {
      "filter": [
        { "term": { "task_id": "vXZG85UBAlM4LplcKI0f" } },
        {
          "range": {
            "data_end_time": {
              "format": "epoch_millis",
              "gte": 1742585746033
            }
          }
        }
      ]
    }
  },
  "track_total_hits": true
}

{% include copy-curl.html %}

이 쿼리는 지정된 작업 ID와 일치하는 가장 최근 예측 결과 10개를 반환해요.

예측기 검색

3.1에서 도입됨 {: .label .label-purple }

예측기 구성을 저장하는 .opensearch-forecasters 시스템 인덱스에 대해 표준 _search 기능을 제공해요. 이 인덱스는 시스템 인덱스이므로 일반 OpenSearch 쿼리로는 접근할 수 없기 때문에 이 API를 사용하여 .opensearch-forecasters를 직접 쿼리해야 해요.

엔드포인트

GET _plugins/_forecast/forecasters/_search

예제 요청: 인덱스 와일드카드 검색

다음 요청은 선행 고정 와일드카드를 사용하여 소스 인덱스 이름이 network로 시작하는 예측기를 검색해요.

GET _plugins/_forecast/forecasters/_search
{
  "query": {
    "wildcard": {
      "indices": {
        "value": "network*"
      }
    }
  }
}

{% include copy-curl.html %}

network*는 network, network-metrics, network_2025-06 및 유사한 인덱스 이름과 일치해요.

예제 응답

{
  "took": 5,
  "timed_out": false,
  "_shards": {
    "total": 1,
    "successful": 1,
    "skipped": 0,
    "failed": 0
  },
  "hits": {
    "total": {
      "value": 1,
      "relation": "eq"
    },
    "max_score": 1.0,
    "hits": [{
      "_index": ".opensearch-forecasters",
      "_id": "forecast-i1nwqooBLXq6T-gGbXI-",
      "_version": 1,
      "_seq_no": 0,
      "_primary_term": 1,
      "_score": 1.0,
      "_source": {
        "category_field": ["server"],
        "description": "ok rate",
        "feature_attributes": [{
          "feature_id": "deny_max",
          "feature_enabled": true,
          "feature_name": "deny max",
          "aggregation_query": {
            "deny_max": {
              "max": {
                "field": "deny"
              }
            }
          }
        }],
        "forecast_interval": {
          "period": {
            "unit": "Minutes",
            "interval": 1
          }
        },
        "schema_version": 2,
        "time_field": "@timestamp",
        "last_update_time": 1695084997949,
        "horizon": 24,
        "indices": ["network-requests"],
        "window_delay": {
          "period": {
            "unit": "Seconds",
            "interval": 20
          }
        },
        "transform_decay": 1.0E-4,
        "name": "Second-Test-Forecaster-3",
        "filter_query": {
          "match_all": {
            "boost": 1.0
          }
        },
        "shingle_size": 8
      }
    }]
  }
}

작업 검색

3.1에서 도입됨 {: .label .label-purple }

.opensearch-forecast-state 인덱스에서 작업을 쿼리해요.

엔드포인트

GET _plugins/_forecast/forecasters/tasks/_search

예제 요청: 이전 일회 실행 작업 검색

다음 요청은 특정 예측기에 대한 이전 일회 실행 작업(가장 최근 작업 제외)을 검색하고 execution_start_time 기준 내림차순으로 정렬해요.

GET _plugins/_forecast/forecasters/tasks/_search
{
  "from": 0,
  "size": 1000,
  "query": {
    "bool": {
      "filter": [
        { "term": { "forecaster_id": { "value": "m5apnooBHh7Wss2wewfW", "boost": 1.0 }}},
        { "term": { "is_latest": { "value": false, "boost": 1.0 }}},
        { "terms": {
            "task_type": [
              "RUN_ONCE_FORECAST_SINGLE_STREAM",
              "RUN_ONCE_FORECAST_HC_FORECASTER"
            ],
            "boost": 1.0
        }}
      ],
      "adjust_pure_negative": true,
      "boost": 1.0
    }
  },
  "sort": [
    { "execution_start_time": { "order": "desc" }}
  ]
}

{% include copy-curl.html %}

예제 응답

{
  "took": 3,
  "timed_out": false,
  "_shards": {
    "total": 1,
    "successful": 1,
    "skipped": 0,
    "failed": 0
  },
  "hits": {
    "total": { "value": 1, "relation": "eq" },
    "max_score": null,
    "hits": [
      {
        "_index": ".opensearch-forecast-state",
        "_id": "4JaunooBHh7Wss2wOwcw",
        "_version": 3,
        "_seq_no": 5,
        "_primary_term": 1,
        "_score": null,
        "_source": {
          "last_update_time": 1694879344264,
          "execution_start_time": 1694879333168,
          "forecaster_id": "m5apnooBHh7Wss2wewfW",
          "state": "TEST_COMPLETE",
          "task_type": "RUN_ONCE_FORECAST_SINGLE_STREAM",
          "is_latest": false,
          "forecaster": {
            "description": "ok rate",
            "ui_metadata": { "aabb": { "ab": "bb" }},
            "feature_attributes": [
              {
                "feature_id": "deny_max",
                "feature_enabled": true,
                "feature_name": "deny max",
                "aggregation_query": {
                  "deny_max": {
                    "max": { "field": "deny" }
                  }
                }
              }
            ],
            "forecast_interval": {
              "period": {
                "unit": "Minutes",
                "interval": 1
              }
            },
            "schema_version": 2,
            "time_field": "@timestamp",
            "last_update_time": 1694879022036,
            "horizon": 24,
            "indices": [ "network-requests" ],
            "window_delay": {
              "period": {
                "unit": "Seconds",
                "interval": 20
              }
            },
            "transform_decay": 1.0E-4,
            "name": "Second-Test-Forecaster-5",
            "filter_query": { "match_all": { "boost": 1.0 }},
            "shingle_size": 8
          }
        },
        "sort": [ 1694879333168 ]
      }
    ]
  }
}

상위 예측자

Introduced 3.1 {: .label .label-purple }

주어진 타임스탬프 범위에 대해 내장 또는 사용자 정의 메트릭을 기반으로 top‑k 엔티티를 반환합니다.

Endpoint

POST _plugins/_forecast/forecasters/{forecaster_id}/results/_topForecasts

Query parameters

다음 쿼리 매개변수가 지원됩니다.

Name Type Required Description
split_by String Required 그룹화할 필드입니다(예: service).
forecast_from Epoch‑ms Required 평가 창에 있는 첫 번째 예측의 data_end_time입니다.
size Integer Optional 반환할 버킷 수입니다. 기본값은 5입니다.
filter_by Enum Required 내장 쿼리 또는 사용자 정의 쿼리를 사용할지 지정합니다. BUILD_IN_QUERY 또는 CUSTOM_QUERY여야 합니다.
build_in_query Enum Optional 다음 내장 순위 기준 중 하나가 필요합니다:
MIN_CONFIDENCE_INTERVAL_WIDTH -- 가장 좁은 예측 신뢰 구간(가장 정밀)으로 정렬합니다.
MAX_CONFIDENCE_INTERVAL_WIDTH -- 가장 넓은 예측 신뢰 구간(가장 덜 정밀)으로 정렬합니다.
MIN_VALUE_WITHIN_THE_HORIZON -- 예측 창 내에서 관찰된 가장 낮은 예측 값으로 정렬합니다.
MAX_VALUE_WITHIN_THE_HORIZON -- 예측 창 내에서 관찰된 가장 높은 예측 값으로 정렬합니다.
DISTANCE_TO_THRESHOLD_VALUE -- 예측 값과 사용자 정의 임계값 간의 차이로 정렬합니다.
threshold, relation_to_threshold Mixed Conditional build_in_query가 DISTANCE_TO_THRESHOLD_VALUE인 경우에만 필요합니다.
filter_query Query DSL Optional filter_by=CUSTOM_QUERY일 때 사용되는 사용자 정의 쿼리입니다.
subaggregations Array Optional 각 버킷 내에서 추가 메트릭을 계산하는 데 사용되는 중첩 집계 및 정렬 옵션 목록입니다.

Example request: Built-in query for narrow confidence intervals

다음 요청은 가장 좁은 신뢰 구간을 기준으로 정렬된 상위 예측 엔티티를 반환합니다.

POST _plugins/_forecast/forecasters/AG_3t4kBkYqqimCe86bP/results/_topForecasts
{
  "split_by": "service",
  "filter_by": "BUILD_IN_QUERY",
  "build_in_query": "MIN_CONFIDENCE_INTERVAL_WIDTH",
  "forecast_from": 1691008679297
}

{% include copy-curl.html %}

Example response

{
  "buckets": [
    {
      "key": { "service": "service_6" },
      "doc_count": 1,
      "bucket_index": 0,
      "MIN_CONFIDENCE_INTERVAL_WIDTH": 27.655361
    },
    ...
  ]
}

Example request: Built-in query with the narrowest confidence interval

다음 요청은 예측 값의 신뢰 구간이 가장 좁은 엔티티의 정렬된 목록을 반환합니다. 결과는 MIN_CONFIDENCE_INTERVAL_WIDTH 메트릭을 기준으로 오름차순으로 정렬됩니다.

POST _plugins/_forecast/forecasters/AG_3t4kBkYqqimCe86bP/results/_topForecasts
{
  "split_by": "service",
  "filter_by": "BUILD_IN_QUERY",
  "build_in_query": "MIN_CONFIDENCE_INTERVAL_WIDTH",
  "forecast_from": 1691008679297
}

{% include copy-curl.html %}

Example response

{
    "buckets": [
        {
            "key": {
                "service": "service_6"
            },
            "doc_count": 1,
            "bucket_index": 0,
            "MIN_CONFIDENCE_INTERVAL_WIDTH": 27.655361
        },
        {
            "key": {
                "service": "service_4"
            },
            "doc_count": 1,
            "bucket_index": 1,
            "MIN_CONFIDENCE_INTERVAL_WIDTH": 1324.7734
        },
        {
            "key": {
                "service": "service_0"
            },
            "doc_count": 1,
            "bucket_index": 2,
            "MIN_CONFIDENCE_INTERVAL_WIDTH": 2211.0781
        },
        {
            "key": {
                "service": "service_2"
            },
            "doc_count": 1,
            "bucket_index": 3,
            "MIN_CONFIDENCE_INTERVAL_WIDTH": 3372.0469
        },
        {
            "key": {
                "service": "service_3"
            },
            "doc_count": 1,
            "bucket_index": 4,
            "MIN_CONFIDENCE_INTERVAL_WIDTH": 3980.2812
        }
    ]
}

Example request: Built-in query with distance under a threshold

다음 요청은 DISTANCE_TO_THRESHOLD_VALUE 메트릭을 기준으로 예측 값이 지정된 임계값에서 가장 멀리 떨어진 상위 엔티티를 반환합니다.

POST _plugins/_forecast/AG_3t4kBkYqqimCe86bP/results/_topForecasts
{
  "split_by": "service",                      // group forecasts by the "service" entity field
  "filter_by": "BUILD_IN_QUERY",              // use a built-in ranking metric
  "build_in_query": "DISTANCE_TO_THRESHOLD_VALUE",
  "forecast_from": 1691008679297,             // data_end_time of the first forecast in scope
  "threshold": -82561.8,                      // user-supplied threshold
  "relation_to_threshold": "LESS_THAN"        // keep only forecasts below the threshold
}

Example response

DISTANCE_TO_THRESHOLD_VALUE 메트릭은 forecast_value – threshold를 계산합니다. relation_to_threshold가 LESS_THAN이므로 API는 음수 거리만 반환하고 오름차순(가장 음수 먼저)으로 정렬합니다. 각 버킷에는 다음 값이 포함됩니다:

  • doc_count: 일치한 예측 지점의 수입니다.
  • DISTANCE_TO_THRESHOLD_VALUE: 예측 범위 내에서 임계값으로부터의 가장 큰 거리입니다.

다음 응답은 DISTANCE_TO_THRESHOLD_VALUE를 반환합니다.

{
  "buckets": [
    {
      "key": { "service": "service_5" },
      "doc_count": 18,
      "bucket_index": 0,
      "DISTANCE_TO_THRESHOLD_VALUE": -330387.12
    },
    ...
    {
      "key": { "service": "service_0" },
      "doc_count": 1,
      "bucket_index": 4,
      "DISTANCE_TO_THRESHOLD_VALUE": -83561.8
    }
  ]
}

Example request: Custom query and nested aggregations

다음 요청은 사용자 정의 쿼리를 사용하여 서비스를 이름으로 일치시키고 가장 높은 예측 값으로 순위를 매깁니다.

POST _plugins/_forecast/AG_3t4kBkYqqimCe86bP/results/_topForecasts
{
  "split_by": "service",
  "forecast_from": 1691018993776,
  "filter_by": "CUSTOM_QUERY",
  "filter_query": {
    "nested": {
      "path": "entity",
      "query": {
        "bool": {
          "must": [
            { "term": { "entity.name": "service" } },
            { "wildcard": { "entity.value": "User*" } }
          ]
        }
      }
    }
  },
  "subaggregations": [
    {
      "aggregation_query": {
        "forecast_value_max": {
          "max": { "field": "forecast_value" }
        }
      },
      "order": "DESC"
    }
  ]
}

{% include copy-curl.html %}

Example response

{
  "buckets": [
    {
      "key": { "service": "UserAuthService" },
      "doc_count": 24,
      "bucket_index": 0,
      "forecast_value_max": 269190.38
    },
    ...
  ]
}

프로필 예측자

Introduced 3.1
{: .label .label-purple }

초기화 진행 상황, 엔티티별 모델 메타데이터, 오류와 같은 실행 시간 상태를 반환합니다. 이 API는 런타임 중 예측자 간격을 검사하는 데 유용합니다.

Endpoints

GET _plugins/_forecast/forecasters/{forecaster_id}/_profile[/{type1},{type2}][?_all=true]

_all 쿼리 매개변수를 사용하여 특정 프로필 유형을 검색하거나 사용 가능한 모든 유형을 요청할 수 있습니다.

다음 프로필 유형이 지원됩니다:

  • state
  • error
  • coordinating_node
  • total_size_in_bytes
  • init_progress
  • models
  • total_entities
  • active_entities
  • forecast_task

요청 본문에 entity 배열을 포함하면 프로필이 해당 엔티티로만 범위가 지정됩니다.

Example request: Default profile with an entity filter

다음 요청은 지정된 엔티티에 대한 기본 프로필 유형(state 및 error)을 반환합니다.

GET _plugins/_forecast/forecasters/tLch1okBCBjX5EchixQ8/_profile
{
  "entity": [
    {
      "name": "service",
      "value": "app_1"
    },
    {
      "name": "host",
      "value": "server_2"
    }
  ]
}

{% include copy-curl.html %}

Example response

{
  "state": "RUNNING"
}

Example request: Multiple profile types

다음 요청은 init_progress, error, total_entities, state 프로필 유형을 검색합니다.

GET _plugins/_forecast/forecasters/mZ6P0okBTUNS6IWgvpwo/_profile/init_progress,error,total_entities,state

{% include copy-curl.html %}

Example request: All profile types

다음 요청은 사용 가능한 모든 프로필 유형을 반환합니다.

GET _plugins/_forecast/forecasters/d7-r1YkB_Z-sgDOKo3Z5/_profile?_all=true&pretty

{% include copy-curl.html %}

예측자 통계

Introduced 3.1
{: .label .label-purple }

예측자 수, 모델 수, 요청 카운터, 내부 예측 인덱스 상태 등 클러스터 수준 또는 노드 수준 통계를 반환합니다.

Endpoints

GET _plugins/_forecast/stats
GET _plugins/_forecast/{node_id}/stats
GET _plugins/_forecast/stats/{stat_name}

Example request: Retrieve all statistics

다음 요청은 모든 예측자에 대한 클러스터 수준 통계(개수, 모델 정보, 인덱스 상태 포함)를 검색합니다.

GET _plugins/_forecast/stats

{% include copy-curl.html %}

Example response

{
  "hc_forecaster_count": 1,
  "forecast_results_index_status": "yellow",
  "forecast_models_checkpoint_index_status": "yellow",
  "single_stream_forecaster_count": 1,
  "forecastn_state_status": "yellow",
  "forecaster_count": 2,
  "job_index_status": "yellow",
  "config_index_status": "yellow",
  "nodes": {
    "8B2S4ClnRFK3GTjO45bwrw": {
      "models": [
        {
          "model_type": "rcf_caster",
          "last_used_time": 1692245336895,
          "model_id": "Doj0AIoBEU5Xd2ccoe_9_entity_SO2kPi_PAMsvThWyE-zYHg",
          "last_checkpoint_time": 1692233157256,
          "entity": [
            { "name": "host_nest.host2", "value": "server_2" }
          ]
        }
      ],
      "forecast_hc_execute_request_count": 204,
      "forecast_model_corruption_count": 0,
      "forecast_execute_failure_count": 0,
      "model_count": 4,
      "forecast_execute_request_count": 409,
      "forecast_hc_execute_failure_count": 0
    }
  }
}

Example request: Retrieve statistics for a specific node

다음 요청은 노드 ID로 식별된 특정 노드의 예측자 통계를 검색합니다.

GET _plugins/_forecast/8B2S4ClnRFK3GTjO45bwrw/stats

{% include copy-curl.html %}

Example request: Retrieve the total number of high-cardinality requests

다음 요청은 모든 노드에서 높은 카디널리티 예측자 요청의 총 개수를 검색합니다.

GET _plugins/_forecast/stats/forecast_hc_execute_request_count

{% include copy-curl.html %}

Example request: Retrieve the high-cardinality request count for a specific node

다음 요청은 특정 노드에서 실행된 높은 카디널리티 예측자 요청의 개수를 검색합니다.

GET _plugins/_forecast/0ZpL8WEYShy-qx7hLJQREQ/stats/forecast_hc_execute_request_count/

{% include copy-curl.html %}

예측자 정보

Introduced 3.1 {: .label .label-purple }

클러스터의 예측자 구성 총 개수를 나타내는 단일 정수를 반환하거나 주어진 검색 조건을 충족하는 예측자가 존재하는지 확인합니다.

Endpoints

GET _plugins/_forecast/forecasters/count
GET _plugins/_forecast/forecasters/match?name={forecaster_name}

Example request: Count forecasters

다음 요청은 클러스터에 현재 저장된 예측자 구성의 개수를 반환합니다.

GET _plugins/_forecast/forecasters/count

{% include copy-curl.html %}

Example response

{
  "count": 2,
  "match": false
}

Example request: Match forecaster name

다음 요청은 Second-Test-Forecaster-3이라는 이름의 예측자를 찾습니다.

GET _plugins/_forecast/forecasters/match?name=Second-Test-Forecaster-3

{% include copy-curl.html %}

Example response: Match found

{
  "count": 0,
  "match": true
}

Example response: No match found

{
  "count": 0,
  "match": false
}

더 알아보기 (Learn more)

함께 읽는 실무 이야기

우리 조직에도 적용하고 싶다면, AI 시스템 구축 서비스를 살펴보세요.