Skip to content

Commit e13e146

Browse files
jr-MSjr-MS
authored
Update README.md (Azure#24594)
1 parent c3ef55c commit e13e146

File tree

1 file changed

+243
-14
lines changed
  • sdk/anomalydetector/ai-anomaly-detector-rest

1 file changed

+243
-14
lines changed

‎sdk/anomalydetector/ai-anomaly-detector-rest/README.md

Lines changed: 243 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -1,25 +1,16 @@
11
# Azure AnomalyDetectorRest REST client library for JavaScript
22

3-
AnomalyDetector Rest Client
3+
[Anomaly Detector](https://learn.microsoft.com/azure/cognitive-services/Anomaly-Detector/overview) is an AI service with a set of APIs, which enables you to monitor and detect anomalies in your time series data with little machine learning (ML) knowledge, either batch validation or real-time inference.
44

5-
**Please rely heavily on our [REST client docs](https://github.com/Azure/azure-sdk-for-js/blob/main/documentation/rest-clients.md) to use this library**
6-
7-
Key links:
8-
9-
- [Source code](https://github.com/Azure/azure-sdk-for-js/tree/main/sdk/anomalydetector/ai-anomaly-detector-rest)
10-
- [Package (NPM)](https://www.npmjs.com/package/@azure-rest/ai-anomaly-detector)
11-
- [API reference documentation](https://docs.microsoft.com/javascript/api/@azure-rest/ai-anomaly-detector?view=azure-node-preview)
12-
- [Samples](https://github.com/Azure/azure-sdk-for-js/tree/main/sdk/anomalydetector/ai-anomaly-detector-rest/samples)
5+
Please refer to our [REST client docs](https://github.com/Azure/azure-sdk-for-js/blob/main/documentation/rest-clients.md) to use this library.
136

147
## Getting started
158

16-
### Currently supported environments
17-
18-
- LTS versions of Node.js
19-
209
### Prerequisites
2110

22-
- You must have an [Azure subscription](https://azure.microsoft.com/free/) to use this package.
11+
- LTS versions of Node.js
12+
- You need an [Azure subscription][azure_sub] to use this package.
13+
- An existing Cognitive Services Anomaly Detector instance.
2314

2415
### Install the `@azure-rest/ai-anomaly-detector` package
2516

@@ -29,6 +20,10 @@ Install the Azure AnomalyDetectorRest REST client REST client library for JavaSc
2920
npm install @azure-rest/ai-anomaly-detector
3021
```
3122

23+
|SDK version|Supported API version of service |
24+
|-------------|---------------|
25+
|1.0.0-beta.1| 1.1|
26+
3227
### Create and authenticate a `AnomalyDetectorRestClient`
3328

3429
To use an [Azure Active Directory (AAD) token credential](https://github.com/Azure/azure-sdk-for-js/blob/main/sdk/identity/identity/samples/AzureIdentityExamples.md#authenticating-with-a-pre-fetched-access-token),
@@ -44,8 +39,208 @@ can be used to authenticate the client.
4439
Set the values of the client ID, tenant ID, and client secret of the AAD application as environment variables:
4540
AZURE_CLIENT_ID, AZURE_TENANT_ID, AZURE_CLIENT_SECRET
4641

42+
## Key concepts
43+
44+
With the Anomaly Detector, you can either detect anomalies in one variable using **Univariate Anomaly Detection**, or detect anomalies in multiple variables with **Multivariate Anomaly Detection**.
45+
46+
|Feature |Description |
47+
|---------|---------|
48+
|Univariate Anomaly Detection | Detect anomalies in one variable, like revenue, cost, etc. The model was selected automatically based on your data pattern. |
49+
|Multivariate Anomaly Detection| Detect anomalies in multiple variables with correlations, which are usually gathered from equipment or other complex system. The underlying model used is Graph attention network.|
50+
51+
### Univariate Anomaly Detection
52+
53+
The Univariate Anomaly Detection API enables you to monitor and detect abnormalities in your time series data without having to know machine learning. The algorithms adapt by automatically identifying and applying the best-fitting models to your data, regardless of industry, scenario, or data volume. Using your time series data, the API determines boundaries for anomaly detection, expected values, and which data points are anomalies.
54+
55+
Using the Anomaly Detector doesn't require any prior experience in machine learning, and the REST API enables you to easily integrate the service into your applications and processes.
56+
57+
With the Univariate Anomaly Detection, you can automatically detect anomalies throughout your time series data, or as they occur in real-time.
58+
59+
|Feature |Description |
60+
|---------|---------|
61+
| Streaming detection| Detect anomalies in your streaming data by using previously seen data points to determine if your latest one is an anomaly. This operation generates a model using the data points you send, and determines if the target point is an anomaly. By calling the API with each new data point you generate, you can monitor your data as it's created. |
62+
| Batch detection | Use your time series to detect any anomalies that might exist throughout your data. This operation generates a model using your entire time series data, with each point analyzed with the same model. |
63+
| Change points detection | Use your time series to detect any trend change points that exist in your data. This operation generates a model using your entire time series data, with each point analyzed with the same model. |
64+
65+
### Multivariate Anomaly Detection
66+
67+
The **Multivariate Anomaly Detection** APIs further enable developers by easily integrating advanced AI for detecting anomalies from groups of metrics, without the need for machine learning knowledge or labeled data. Dependencies and inter-correlations between up to 300 different signals are now automatically counted as key factors. This new capability helps you to proactively protect your complex systems such as software applications, servers, factory machines, spacecraft, or even your business, from failures.
68+
69+
With the Multivariate Anomaly Detection, you can automatically detect anomalies throughout your time series data, or as they occur in real-time. There are three processes to use Multivariate Anomaly Detection.
70+
71+
- **Training**: Use Train Model API to create and train a model, then use Get Model Status API to get the status and model metadata.
72+
- **Inference**:
73+
- Use Async Inference API to trigger an asynchronous inference process and use Get Inference results API to get detection results on a batch of data.
74+
- You could also use Sync Inference API to trigger a detection on one timestamp every time.
75+
- **Other operations**: List Model API and Delete Model API are supported in Multivariate Anomaly Detection model for model management.
76+
77+
### Thread safety
78+
79+
We guarantee that all client instance methods are thread-safe and independent of each other ([guideline](https://azure.github.io/azure-sdk/dotnet_introduction.html#dotnet-service-methods-thread-safety)). This ensures that the recommendation of reusing client instances is always safe, even across threads.
80+
81+
## Examples
82+
83+
The following section provides several code snippets covering some of the most common Anomaly Detector service tasks, including:
84+
85+
- [Univariate Anomaly Detection - Batch detection](#batch-detection)
86+
- [Univariate Anomaly Detection - Streaming detection](#streaming-detection)
87+
- [Univariate Anomaly Detection - Detect change points](#detect-change-points)
88+
- [Multivariate Anomaly Detection](#multivariate-anomaly-detection-sample)
89+
90+
### Batch detection
91+
92+
```typescript
93+
const apiKey = process.env["ANOMALY_DETECTOR_API_KEY"] || "";
94+
const endpoint = process.env["ANOMALY_DETECTOR_ENDPOINT"] || "";
95+
const timeSeriesDataPath = "./samples-dev/example-data/request-data.csv";
96+
97+
function read_series_from_file(path: string): Array<TimeSeriesPoint> {
98+
let result = Array<TimeSeriesPoint>();
99+
let input = fs.readFileSync(path).toString();
100+
let parsed = parse(input, { skip_empty_lines: true });
101+
parsed.forEach(function (e: Array<string>) {
102+
result.push({ timestamp: new Date(e[0]), value: Number(e[1]) });
103+
});
104+
return result;
105+
}
106+
107+
export async function main() {
108+
// create client
109+
const credential = new AzureKeyCredential(apiKey);
110+
const client = AnomalyDetector(endpoint, credential);
111+
112+
// construct request
113+
const options: DetectUnivariateEntireSeriesParameters = {
114+
body: {
115+
granularity: "daily",
116+
imputeMode: "auto",
117+
maxAnomalyRatio: 0.25,
118+
sensitivity: 95,
119+
series: read_series_from_file(timeSeriesDataPath),
120+
},
121+
headers: { "Content-Type": "application/json" },
122+
};
123+
124+
// get last detect result
125+
const result = await client.path("/timeseries/entire/detect").post(options);
126+
if (isUnexpected(result)) {
127+
throw result;
128+
}
129+
130+
if (result.body.isAnomaly) {
131+
result.body.isAnomaly.forEach(function (anomaly, index) {
132+
if (anomaly === true) {
133+
console.log(index);
134+
}
135+
});
136+
} else {
137+
console.log("There is no anomaly detected from the series.");
138+
}
139+
```
140+
141+
### Streaming Detection
142+
143+
```typescript
144+
const apiKey = process.env["ANOMALY_DETECTOR_API_KEY"] || "";
145+
const endpoint = process.env["ANOMALY_DETECTOR_ENDPOINT"] || "";
146+
const timeSeriesDataPath = "./samples-dev/example-data/request-data.csv";
147+
148+
function read_series_from_file(path: string): Array<TimeSeriesPoint> {
149+
let result = Array<TimeSeriesPoint>();
150+
let input = fs.readFileSync(path).toString();
151+
let parsed = parse(input, { skip_empty_lines: true });
152+
parsed.forEach(function (e: Array<string>) {
153+
result.push({ timestamp: new Date(e[0]), value: Number(e[1]) });
154+
});
155+
return result;
156+
}
157+
158+
export async function main() {
159+
// create client
160+
const credential = new AzureKeyCredential(apiKey);
161+
const client = AnomalyDetector(endpoint, credential);
162+
163+
// construct request
164+
const options: DetectUnivariateLastPointParameters = {
165+
body: {
166+
granularity: "daily",
167+
imputeFixedValue: 800,
168+
imputeMode: "fixed",
169+
maxAnomalyRatio: 0.25,
170+
sensitivity: 95,
171+
series: read_series_from_file(timeSeriesDataPath),
172+
},
173+
headers: { "Content-Type": "application/json" },
174+
};
175+
176+
// get last detect result
177+
const result = await client.path("/timeseries/last/detect").post(options);
178+
if (isUnexpected(result)) {
179+
throw result;
180+
}
181+
182+
if (result.body.isAnomaly) {
183+
console.log("The latest point is detected as anomaly.");
184+
} else {
185+
console.log("The latest point is not detected as anomaly.");
186+
}
187+
```
188+
189+
### Detect change points
190+
191+
```typescript
192+
const apiKey = process.env["ANOMALY_DETECTOR_API_KEY"] || "";
193+
const endpoint = process.env["ANOMALY_DETECTOR_ENDPOINT"] || "";
194+
const timeSeriesDataPath = "./samples-dev/example-data/request-data.csv";
195+
196+
function read_series_from_file(path: string): Array<TimeSeriesPoint> {
197+
let result = Array<TimeSeriesPoint>();
198+
let input = fs.readFileSync(path).toString();
199+
let parsed = parse(input, { skip_empty_lines: true });
200+
parsed.forEach(function (e: Array<string>) {
201+
result.push({ timestamp: new Date(e[0]), value: Number(e[1]) });
202+
});
203+
return result;
204+
}
205+
206+
export async function main() {
207+
const credential = new AzureKeyCredential(apiKey);
208+
const client = AnomalyDetector(endpoint, credential);
209+
const options: DetectUnivariateChangePointParameters = {
210+
body: {
211+
granularity: "daily",
212+
series: read_series_from_file(timeSeriesDataPath),
213+
},
214+
headers: { "Content-Type": "application/json" },
215+
};
216+
const result = await client.path("/timeseries/changepoint/detect").post(options);
217+
if (isUnexpected(result)) {
218+
throw result;
219+
}
220+
221+
if (result.body.isChangePoint === undefined) throw new Error("Empty isChangePoint");
222+
if (
223+
result.body.isChangePoint.some(function (changePoint) {
224+
return changePoint === true;
225+
})
226+
) {
227+
console.log("Change points were detected from the series at index:");
228+
result.body.isChangePoint.forEach(function (changePoint, index) {
229+
if (changePoint === true) console.log(index);
230+
});
231+
} else {
232+
console.log("There is no change point detected from the series.");
233+
}
234+
```
235+
236+
### Multivariate Anomaly Detection Sample
237+
238+
To see how to use Anomaly Detector library to conduct Multivariate Anomaly Detection, see this [sample](https://github.com/Azure/azure-sdk-for-js/blob/main/sdk/anomalydetector/ai-anomaly-detector-rest/samples/v1-beta/typescript/src/sample_multivariate_detection.ts).
239+
47240
## Troubleshooting
48241
242+
### General
243+
49244
### Logging
50245
51246
Enabling logging may help uncover useful information about failures. In order to see a log of HTTP requests and responses, set the `AZURE_LOG_LEVEL` environment variable to `info`. Alternatively, logging can be enabled at runtime by calling `setLogLevel` in the `@azure/logger`:
@@ -57,3 +252,37 @@ setLogLevel("info");
57252
```
58253
59254
For more detailed instructions on how to enable logs, you can look at the [@azure/logger package docs](https://github.com/Azure/azure-sdk-for-js/tree/main/sdk/core/logger).
255+
256+
## Next steps
257+
258+
These code samples show common scenario operations with the Azure Anomaly Detector library. More samples can be found under the [samples](https://github.com/Azure/azure-sdk-for-net/blob/main/sdk/anomalydetector/Azure.AI.AnomalyDetector/tests/samples/) directory.
259+
260+
- Univariate Anomaly Detection - Batch Detection: [sample_detect_entire_series_anomaly.ts](https://github.com/Azure/azure-sdk-for-js/blob/main/sdk/anomalydetector/ai-anomaly-detector-rest/samples/v1-beta/typescript/src/sample_detect_entire_series_anomaly.ts)
261+
262+
- Univariate Anomaly Detection - Streaming Detection: [ample_detect_last_point_anomaly.ts](https://github.com/Azure/azure-sdk-for-js/blob/main/sdk/anomalydetector/ai-anomaly-detector-rest/samples/v1-beta/typescript/src/sample_detect_last_point_anomaly.ts)
263+
264+
- Univariate Anomaly Detection - Change Point Detection: [sample_detect_change_point.ts](https://github.com/Azure/azure-sdk-for-js/blob/main/sdk/anomalydetector/ai-anomaly-detector-rest/samples/v1-beta/typescript/src/sample_detect_change_point.ts)
265+
266+
- Multivariate Anomaly Detection: [sample_multivariate_detection.ts](https://github.com/Azure/azure-sdk-for-js/blob/main/sdk/anomalydetector/ai-anomaly-detector-rest/samples/v1-beta/typescript/src/sample_multivariate_detection.ts)
267+
268+
### Additional documentation
269+
270+
For more extensive documentation on Azure Anomaly Detector, see the [Anomaly Detector documentation](https://learn.microsoft.com/azure/cognitive-services/anomaly-detector/overview) on docs.microsoft.com.
271+
272+
## Contributing
273+
274+
This project welcomes contributions and suggestions. Most contributions require you to agree to a Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us the rights to use your contribution. For details, visit [cla.microsoft.com][cla].
275+
276+
When you submit a pull request, a CLA-bot will automatically determine whether you need to provide a CLA and decorate the PR appropriately (e.g., label, comment). Simply follow the instructions provided by the bot. You will only need to do this once across all repos using our CLA.
277+
278+
This project has adopted the [Microsoft Open Source Code of Conduct][code_of_conduct]. For more information see the [Code of Conduct FAQ][coc_faq] or contact [[email protected]][coc_contact] with any additional questions or comments.
279+
280+
<!-- LINKS -->
281+
[cla]: https://cla.microsoft.com
282+
[code_of_conduct]: https://opensource.microsoft.com/codeofconduct/
283+
[coc_faq]: https://opensource.microsoft.com/codeofconduct/faq/
284+
[coc_contact]: mailto:[email protected]
285+
- [Source code](https://github.com/Azure/azure-sdk-for-js/tree/main/sdk/anomalydetector/ai-anomaly-detector-rest)
286+
- [Package (NPM)](https://www.npmjs.com/package/@azure-rest/ai-anomaly-detector)
287+
- [API reference documentation](https://docs.microsoft.com/javascript/api/@azure-rest/ai-anomaly-detector?view=azure-node-preview)
288+
- [Samples](https://github.com/Azure/azure-sdk-for-js/tree/main/sdk/anomalydetector/ai-anomaly-detector-rest/samples)

0 commit comments

Comments
 (0)