From 530a00f2ed6a810377370fe3fca7c1d392512157 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E5=90=B4=E6=99=9F=20Wu=20Sheng?= Date: Tue, 18 Feb 2025 21:31:47 +0800 Subject: [PATCH] Add baseline doc and point to SkyPredictor project (#13040) --- docs/en/api/metrics-query-expression.md | 2 +- docs/en/setup/ai-pipeline/introduction.md | 19 ++++++++++------ .../metrics-baseline-integration.md | 22 +++++++++++++++++++ docs/en/setup/backend/backend-alarm.md | 3 +++ docs/menu.yml | 2 ++ 5 files changed, 40 insertions(+), 8 deletions(-) create mode 100644 docs/en/setup/ai-pipeline/metrics-baseline-integration.md diff --git a/docs/en/api/metrics-query-expression.md b/docs/en/api/metrics-query-expression.md index 74550e0934..e96e0f2c14 100644 --- a/docs/en/api/metrics-query-expression.md +++ b/docs/en/api/metrics-query-expression.md @@ -511,7 +511,7 @@ baseline(service_resp_time, upper) ``` **Notice**: -- This feature is required to enable the `baseline module` and deploy a baseline service. And the baseline service should implement the protocol of the [baseline.proto](../../../oap-server/ai-pipeline/src/main/proto/baseline.proto). +- This feature is required to enable the [Metrics Baseline Calculation](../setup/ai-pipeline/metrics-baseline-integration.md) and deploy a remote service. Otherwise, the result will be empty. - The baseline operation requires the relative metrics declared through baseline service. Otherwise, the result will be empty, which means there is no baseline or predicated value. diff --git a/docs/en/setup/ai-pipeline/introduction.md b/docs/en/setup/ai-pipeline/introduction.md index 9f960e5bd9..a2f62710e4 100644 --- a/docs/en/setup/ai-pipeline/introduction.md +++ b/docs/en/setup/ai-pipeline/introduction.md @@ -2,23 +2,28 @@ **Warning, this module is still in the ALPHA stage. This is not stable.** -Pattern Recognition, Machine Learning(ML) and Artificial Intelligence(AI) are common technology to identify patterns in data. -This module provides a way to integrate these technologies in a standardized way about shipping the data from OAP kernel -to 3rd party. - -From the industry practice, Pattern Recognition, Machine Learning(ML) and Artificial Intelligence(AI) are always overestimated, +Pattern Recognition, Machine Learning(ML) and Artificial Intelligence(AI) are common technology to identify patterns in data. +From the industry practice, these three are always overestimated for the marketing interests, they are good at many things but have to run in a clear context. +Hence, SkyWalking OAP AI pipeline features are designed for very specific solutions and scenarios with at +least one recommended (remote) implementations for the integration。 -The ai-pipeline module is activated by default. +The ai-pipeline module is activated by default for the latest release. Make sure you have these configurations when upgrade +from a previous version. ```yaml ai-pipeline: selector: ${SW_AI_PIPELINE:default} default: + # HTTP Restful URI recognition service address configurations uriRecognitionServerAddr: ${SW_AI_PIPELINE_URI_RECOGNITION_SERVER_ADDR:} uriRecognitionServerPort: ${SW_AI_PIPELINE_URI_RECOGNITION_SERVER_PORT:17128} + # Metrics Baseline Calculation service address configurations + baselineServerAddr: ${SW_API_PIPELINE_BASELINE_SERVICE_HOST:} + baselineServerPort: ${SW_API_PIPELINE_BASELINE_SERVICE_PORT:18080} ``` -## Supported Scenarios +We supported the following AI features: * [**HTTP Restful URI recognition**](./http-restful-uri-pattern.md). +* [**Metrics Baseline Calculation and Alerting**](./metrics-baseline-integration.md). diff --git a/docs/en/setup/ai-pipeline/metrics-baseline-integration.md b/docs/en/setup/ai-pipeline/metrics-baseline-integration.md new file mode 100644 index 0000000000..785c204e8f --- /dev/null +++ b/docs/en/setup/ai-pipeline/metrics-baseline-integration.md @@ -0,0 +1,22 @@ +# Metrics Baseline Calculation and Alerting + +Metrics baseline calculation and alerting is a feature that calculates the baseline of metrics data and feed for the +alarm engine as additional metrics to setup rules for alerting. +[Alarm docs](../backend/backend-alarm.md#use-the-baseline-predicted-value-to-trigger-the-alarm) has more details about +how to use the baseline, and further about MQE usages of the baseline values. + +SkyAPM community provides a default implementation [SkyAPM/SkyPredictor](https://github.com/SkyAPM/SkyPredictor). +It has complete support for the baseline calculation by following SkyWalking's metrics data model through GraphQL, and +feed baseline data back to the OAP server through the following gRPC service per SkyWalking requirement.. + +```protobuf +service AlarmBaselineService { + // Query the supported metrics names. + rpc querySupportedMetricsNames(google.protobuf.Empty) returns (AlarmBaselineMetricsNames); + // Query the predicted metrics of the given service. + rpc queryPredictedMetrics(AlarmBaselineRequest) returns (AlarmBaselineResponse); +} +``` + +You could find the protocol definition +in [AlarmBaseline.proto](../../../../oap-server/ai-pipeline/src/main/proto/baseline.proto). \ No newline at end of file diff --git a/docs/en/setup/backend/backend-alarm.md b/docs/en/setup/backend/backend-alarm.md index 91f623b93a..5347da270a 100644 --- a/docs/en/setup/backend/backend-alarm.md +++ b/docs/en/setup/backend/backend-alarm.md @@ -140,6 +140,9 @@ rules: message: Service {name} response time is higher than the baseline predicted value in 3 minutes of last 10 minutes. ``` +Note, the baseline predicted value is calculated based on the historical data of the same time window in the past, which +is through [AI powered baseline calculation](../ai-pipeline/metrics-baseline-integration.md). + ## Hooks Hooks are a way to send alarm messages to the outside world. SkyWalking supports multiple hooks of the same type, each hook can support different configurations. For example, you can configure two Slack hooks, one named `default` and set `is-default: true` means this hook will apply on all `Alarm Rules` **without config** `hooks`. diff --git a/docs/menu.yml b/docs/menu.yml index a48b34322e..d04cc79653 100644 --- a/docs/menu.yml +++ b/docs/menu.yml @@ -276,6 +276,8 @@ catalog: path: "/en/setup/ai-pipeline/introduction" - name: "HTTP Restful URI recognition" path: "/en/setup/ai-pipeline/http-restful-uri-pattern" + - name: "Metrics Baseline Calculation and Alerting" + path: "/en/setup/ai-pipeline/metrics-baseline-integration" - name: "UI Setup" catalog: - name: "Native UI"