# Node.js 카나리에 사용할 수 있는 라이브러리 함수
이 섹션에서는 Node.js 런타임을 사용하여 카나리 스크립트에 사용할 수 있는 라이브러리 함수에 대해 설명합니다.
**Topics**
+ [addExecutionError(errorMessage, ex);](#Library_function_Nodejs_addExecutionError_Nodecanary)
+ [getCanaryName();](#Library_function_Nodejs_getCanaryName)
+ [getCanaryArn();](#Library_function_Nodejs_Nodecanary)
+ [getCanaryUserAgentString();](#Library_function_Nodejs_getCanaryUserAgentString_Nodecanary)
+ [getRuntimeVersion();](#Library_function_Nodejs_getRuntimeVersion_Nodecanary)
+ [getLogLevel()](#Library_function_Nodejs_getLogLevel_Nodecanary)
+ [setLogLevel()](#Library_function_Nodejs_setLogLevel_Nodecanary)
+ [executeStep(stepName, functionToExecute, [stepConfig])](#Library_function_Nodejs_executestep_Nodecanary)
+ [executeHttpStep(stepName, requestOptions, [callback], [stepConfig])](#Library_function_Nodejs_executeHttpStep)
## addExecutionError(errorMessage, ex);
`errorMessage`는 오류를 설명하며, `ex`는 발생한 예외입니다.
`addExecutionError`를 사용하여 canary에 대한 실행 오류를 설정할 수 있습니다. 이 함수는 스크립트 실행을 중단하지 않고 canary에 실패합니다. 또한 `successPercent` 지표에 영향을 주지 않습니다.
오류가 canary 스크립트의 성공 또는 실패를 나타내는 데 중요하지 않은 경우에만 오류를 실행 오류로 추적해야 합니다.
`addExecutionError`의 사용 예는 다음과 같습니다. 엔드포인트의 가용성을 모니터링하고 페이지가 로드된 후에 스크린샷을 생성합니다. 스크린샷 캡처 실패가 엔드포인트의 가용성을 결정하지 않기 때문에 스크린샷을 생성하는 동안 발생한 오류를 포착하여 실행 오류로 추가할 수 있습니다. 가용성 지표는 여전히 엔드포인트가 실행 중임을 나타내지만 canary 상태는 실패로 표시됩니다. 다음 샘플 코드 블록은 이러한 오류를 포착하여 실행 오류로 추가합니다.
```
try {await synthetics.executeStep(stepName, callbackFunc);} catch(ex) {synthetics.addExecutionError('Unable to take screenshot ', ex);}
```
## getCanaryName();
canary의 이름을 반환합니다.
## getCanaryArn();
canary의 ARN을 반환합니다.
## getCanaryUserAgentString();
canary의 사용자 지정 사용자 에이전트를 반환합니다.
## getRuntimeVersion();
이 함수는 런타임 버전 `syn-nodejs-3.0` 이상에서 사용할 수 있습니다. 이 함수는 canary의 Synthetics 런타임 버전을 반환합니다. 예를 들어 반환 값이 `syn-nodejs-3.0`일 수 있습니다.
## getLogLevel()
Synthetics 라이브러리에 대한 현재 로그 수준을 검색합니다. 가능한 값은 다음과 같습니다.
+ `0` – 디버그
+ `1` – 정보
+ `2` – 경고
+ `3` – 오류
예제:
```
let logLevel = synthetics.getLogLevel();
```
## setLogLevel()
Synthetics 라이브러리의 로그 수준을 설정합니다. 가능한 값은 다음과 같습니다.
+ `0` – 디버그
+ `1` – 정보
+ `2` – 경고
+ `3` – 오류
예제:
```
synthetics.setLogLevel(0);
```
## executeStep(stepName, functionToExecute, [stepConfig])
제공된 단계를 실행하며 시작/성공/실패 로깅, 성공/실패, 기간 지표로 래핑합니다.
`executeStep` 함수는 다음 작업도 수행합니다.
+ 단계가 시작되었음을 기록합니다.
+ 타이머를 시작합니다.
+ 제공된 함수를 실행합니다.
+ 함수가 값을 정상적으로 반환하면 성공한 것으로 간주됩니다. 함수가 오류를 생성하면 실패한 것으로 간주됩니다.
+ 타이머를 종료합니다.
+ 단계 성공 또는 실패 여부를 기록합니다.
+ `stepName SuccessPercent` 지표(성공 시 100, 실패 시 0)를 내보냅니다.
+ 단계 시작 및 종료 시간 기준의 값을 사용하여 `stepName Duration metric`을 내보냅니다.
+ functionToExecute가 반환한 값을 반환하거나, ` functionToExecute`가 반환한 내용을 다시 생성합니다.
+ 카나리의 보고서에 단계 실행 요약을 추가합니다.
**예제**
```
await synthetics.executeStep(stepName, async function () {
return new Promise((resolve, reject) => {
const req = https.request(url, (res) => {
console.log(`Status: ${res.statusCode}`);
if (res.statusCode >= 400) {
reject(new Error(`Request failed with status ${res.statusCode} for ${url}`));
} else {
resolve();
}
});
req.on('error', (err) => {
reject(new Error(`Request failed for ${url}: ${err.message}`));
});
req.end();
});
});
```
## executeHttpStep(stepName, requestOptions, [callback], [stepConfig])
제공된 HTTP 요청을 단계로 실행하고 `SuccessPercent`(통과 또는 실패) 및 `Duration` 지표를 게시합니다.
**executeHttpStep**은 요청에 지정된 프로토콜에 따라 내부적으로 HTTP 또는 HTTPS 네이티브 함수를 사용합니다.
이 함수는 canary의 보고서에 단계 실행 요약도 추가합니다. 요약에는 다음과 같은 각 HTTP 요청에 관한 세부 정보가 포함됩니다.
+ 시작 시간
+ 종료 시간
+ 상태(PASSED/FAILED)
+ 실패 원인(실패한 경우)
+ 요청 또는 응답 헤더, 본문, 상태 코드, 상태 메시지, 성능 타이밍과 같은 HTTP 호출 세부 정보
**Topics**
+ [파라미터](#Library_function_Nodejs_executeHttpStep_parameters_Nodecanary)
+ [executeHttpStep 사용 예](#Library_function_Nodejs_executeHttpStep_examples_Nodecanary)
### 파라미터
**stepName({{String}})**
단계 이름을 지정합니다. 이 이름은 이 단계의 CloudWatch 지표 게시에도 사용됩니다.
**requestOptions({{Object 또는 String}})**
이 파라미터의 값은 URL, URL 문자열 또는 객체일 수 있습니다. 객체인 경우 HTTP 요청을 수행하기 위해 구성 가능한 옵션 집합이어야 합니다. Node.js 설명서에 있는 [http.request(options[, callback])](https://nodejs.org/api/http.html#http_http_request_options_callback)의 모든 옵션을 지원합니다.
이러한 Node.js 옵션 외에도 **requestOptions**는 추가 파라미터인 `body`를 지원합니다. `body` 파라미터를 사용하면 데이터를 요청 본문으로 전달할 수 있습니다.
**callback({{response}})**
(선택 사항) HTTP 응답을 사용하여 호출되는 사용자 함수입니다. 응답은 [클래스: http.IncomingMessage](https://nodejs.org/api/http.html#http_class_http_incomingmessage) 유형입니다.
**stepConfig({{object}})**
(선택 사항) 이 파라미터를 사용하여 이 단계의 다른 구성으로 글로벌 Synthetics 구성을 재정의할 수 있습니다.
### executeHttpStep 사용 예
다음 일련의 예는 서로를 기반으로 하여 이 옵션의 다양한 사용을 보여 줍니다.
이 첫 번째 예에서는 요청 파라미터를 구성합니다. URL을 **requestOptions**로 전달할 수 있습니다.
```
let requestOptions = 'https://www.amazon.com';
```
또는 다음과 같은 옵션 집합을 전달할 수 있습니다.
```
let requestOptions = {
'hostname': 'myproductsEndpoint.com',
'method': 'GET',
'path': '/test/product/validProductName',
'port': 443,
'protocol': 'https:'
};
```
다음 예에서는 응답을 수락하는 콜백 함수를 생성합니다. 기본적으로 [**콜백(callback)**]을 지정하지 않으면 CloudWatch Synthetics는 상태가 200\~299(포함)인지 확인합니다.
```
// Handle validation for positive scenario
const callback = async function(res) {
return new Promise((resolve, reject) => {
if (res.statusCode < 200 || res.statusCode > 299) {
throw res.statusCode + ' ' + res.statusMessage;
}
let responseBody = '';
res.on('data', (d) => {
responseBody += d;
});
res.on('end', () => {
// Add validation on 'responseBody' here if required. For ex, your status code is 200 but data might be empty
resolve();
});
});
};
```
다음 예에서는 글로벌 CloudWatch Synthetics 구성을 재정의하는 이 단계의 구성을 생성합니다. 이 예에서 단계 구성은 보고서의 요청 헤더, 응답 헤더, 요청 본문(게시물 데이터), 응답 본문을 허용하고 X-Amz-Security-Token' 및 'Authorization' 헤더 값을 제한합니다. 기본적으로 이러한 값은 보안상의 이유로 보고서에 포함되지 않습니다. 이러한 값을 포함하도록 선택하는 경우 데이터는 S3 버킷에만 저장됩니다.
```
// By default headers, post data, and response body are not included in the report for security reasons.
// Change the configuration at global level or add as step configuration for individual steps
let stepConfig = {
includeRequestHeaders: true,
includeResponseHeaders: true,
restrictedHeaders: ['X-Amz-Security-Token', 'Authorization'], // Restricted header values do not appear in report generated.
includeRequestBody: true,
includeResponseBody: true
};
```
이 마지막 예에서는 요청을 **executeHttpStep**에 전달하고 단계의 이름을 지정합니다.
```
await synthetics.executeHttpStep('Verify GET products API', requestOptions, callback, stepConfig);
```
이 일련의 예를 통해 CloudWatch Synthetics는 보고서의 각 단계에서 세부 정보를 추가하고 **stepName**을 사용하여 각 단계의 지표를 생성합니다.
`Verify GET products API` 단계의 `successPercent` 및 `duration` 지표를 확인할 수 있습니다. API 호출 단계의 지표를 모니터링하여 API 성능을 모니터링할 수 있습니다.
이러한 함수를 사용하는 완전한 스크립트 샘플은 [다단계 API canary](CloudWatch_Synthetics_Canaries_Samples.md#CloudWatch_Synthetics_Canaries_Samples_APIsteps) 단원을 참조하세요.