# Puppeteer를 사용하여 Node.js 카나리 스크립트에 사용할 수 있는 라이브러리 함수
이 섹션에서는 Node.js 카나리 스크립트에 사용할 수 있는 라이브러리 함수를 설명합니다.
**Topics**
+ [모든 canary에 적용되는 Node.js 라이브러리 클래스 및 함수](#CloudWatch_Synthetics_Library_allcanaries)
+ [UI canary에만 적용되는 Node.js 라이브러리 클래스 및 함수](#CloudWatch_Synthetics_Library_UIcanaries)
+ [API canary에만 적용되는 Node.js 라이브러리 클래스 및 함수](#CloudWatch_Synthetics_Library_APIcanaries)
## 모든 canary에 적용되는 Node.js 라이브러리 클래스 및 함수
다음 Node.js용 CloudWatch Synthetics 라이브러리 함수는 모든 canary에 사용할 수 있습니다.
**Topics**
+ [Synthetics 클래스](#CloudWatch_Synthetics_Library_Synthetics_Class_all)
+ [SyntheticsConfiguration 클래스](#CloudWatch_Synthetics_Library_SyntheticsConfiguration)
+ [Synthetics Logger](#CloudWatch_Synthetics_Library_SyntheticsLogger)
+ [SyntheticsLogHelper 클래스](#CloudWatch_Synthetics_Library_SyntheticsLogHelper)
### Synthetics 클래스
모든 canary에 사용할 수 있는 다음 함수는 Synthetics 클래스에 있습니다.
**Topics**
+ [addExecutionError(errorMessage, ex);](#CloudWatch_Synthetics_Library_addExecutionError)
+ [getCanaryName();](#CloudWatch_Synthetics_Library_getCanaryName)
+ [getCanaryArn();](#CloudWatch_Synthetics_Library_getCanaryARN)
+ [getCanaryUserAgentString();](#CloudWatch_Synthetics_Library_getCanaryUserAgentString)
+ [getRuntimeVersion();](#CloudWatch_Synthetics_Library_getRuntimeVersion)
+ [getLogLevel()](#CloudWatch_Synthetics_Library_getLogLevel)
+ [setLogLevel()](#CloudWatch_Synthetics_Library_setLogLevel)
#### addExecutionError(errorMessage, ex);
`errorMessage`는 오류를 설명하며, `ex`는 발생한 예외입니다.
`addExecutionError`를 사용하여 canary에 대한 실행 오류를 설정할 수 있습니다. 이 함수는 스크립트 실행을 중단하지 않고 canary에 실패합니다. 또한 `successPercent` 지표에 영향을 주지 않습니다.
오류가 canary 스크립트의 성공 또는 실패를 나타내는 데 중요하지 않은 경우에만 오류를 실행 오류로 추적해야 합니다.
`addExecutionError`의 사용 예는 다음과 같습니다. 엔드포인트의 가용성을 모니터링하고 페이지가 로드된 후에 스크린샷을 생성합니다. 스크린샷 캡처 실패가 엔드포인트의 가용성을 결정하지 않기 때문에 스크린샷을 생성하는 동안 발생한 오류를 포착하여 실행 오류로 추가할 수 있습니다. 가용성 지표는 여전히 엔드포인트가 실행 중임을 나타내지만 canary 상태는 실패로 표시됩니다. 다음 샘플 코드 블록은 이러한 오류를 포착하여 실행 오류로 추가합니다.
```
try {
await synthetics.takeScreenshot(stepName, "loaded");
} catch(ex) {
synthetics.addExecutionError('Unable to take screenshot ', ex);
}
```
#### getCanaryName();
canary의 이름을 반환합니다.
#### getCanaryArn();
canary의 ARN을 반환합니다.
#### getCanaryUserAgentString();
canary의 사용자 지정 사용자 에이전트를 반환합니다.
#### getRuntimeVersion();
이 함수는 런타임 버전 `syn-nodejs-puppeteer-3.0` 이상에서 사용할 수 있습니다. 이 함수는 canary의 Synthetics 런타임 버전을 반환합니다. 예를 들어 반환 값이 `syn-nodejs-puppeteer-3.0`일 수 있습니다.
#### getLogLevel()
Synthetics 라이브러리에 대한 현재 로그 수준을 검색합니다. 가능한 값은 다음과 같습니다.
+ `0` – 디버그
+ `1` – 정보
+ `2` – 경고
+ `3` – 오류
예제:
```
let logLevel = synthetics.getLogLevel();
```
#### setLogLevel()
Synthetics 라이브러리의 로그 수준을 설정합니다. 가능한 값은 다음과 같습니다.
+ `0` – 디버그
+ `1` – 정보
+ `2` – 경고
+ `3` – 오류
예제:
```
synthetics.setLogLevel(0);
```
### SyntheticsConfiguration 클래스
이 클래스는 `syn-nodejs-2.1` 런타임 버전 이상에서만 사용할 수 있습니다.
`SyntheticsConfiguration` 클래스를 사용하여 Synthetics 라이브러리 함수의 동작을 구성할 수 있습니다. 예를 들어 이 클래스를 사용하여 스크린샷을 캡처하지 않도록 `executeStep()` 함수를 구성할 수 있습니다.
canary의 모든 단계에 적용되는 글로벌 수준에서 CloudWatch Synthetics 구성을 설정할 수 있습니다. 또한 구성 키-값 페어를 전달하여 단계 수준에서 이러한 구성을 재정의할 수도 있습니다.
단계 수준에서 옵션을 전달할 수 있습니다. 예를 보려면 [async executeStep(stepName, functionToExecute, [stepConfig]);](#CloudWatch_Synthetics_Library_executeStep) 및 [executeHttpStep(stepName, requestOptions, [callback], [stepConfig])](#CloudWatch_Synthetics_Library_executeHttpStep) 단원을 참조하세요.
**Topics**
+ [setConfig(options)](#CloudWatch_Synthetics_Library_setConfig)
+ [시각적 모니터링](#CloudWatch_Synthetics_Library_SyntheticsLogger_VisualTesting)
#### setConfig(options)
` options `는 canary에 대해 구성 가능한 옵션의 집합인 객체입니다. 다음 단원에서는 ` options `의 가능한 필드를 설명합니다.
##### 모든 canary에 대한 setConfig(options)
`syn-nodejs-puppeteer-3.2` 이상을 사용하는 카나리의 경우 **setConfig**의 **(options)**에 다음 파라미터가 포함될 수 있습니다.
+ `includeRequestHeaders`(boolean) - 보고서에 요청 헤더를 포함할지 여부입니다. 기본값은 `false`입니다.
+ `includeResponseHeaders`(boolean) - 보고서에 응답 헤더를 포함할지 여부입니다. 기본값은 `false`입니다.
+ `restrictedHeaders`(array) - 헤더가 포함된 경우 무시할 헤더 값 목록입니다. 이는 요청 헤더와 응답 헤더 모두에 적용됩니다. 예를 들어 **includeRequestHeaders**를 `true`로, **restrictedHeaders**를 `['Authorization']`으로 전달하여 자격 증명을 숨길 수 있습니다.
+ `includeRequestBody`(boolean) - 보고서에 요청 본문을 포함할지 여부입니다. 기본값은 `false`입니다.
+ `includeResponseBody`(boolean) - 보고서에 응답 본문을 포함할지 여부입니다. 기본값은 `false`입니다.
**중요**
`includeResponseBody` 또는 ` logResponseBody`를 활성화하는 경우 aws-sdk v3 클라이언트와 같은 일부 API의 응답에서 데이터 객체가 반환되지 않습니다. 이는 Node.js 제한 및 사용된 응답 객체 유형 때문입니다.
**CloudWatch 지표에 관한 setConfig(options)**
`syn-nodejs-puppeteer-3.1` 이상을 사용하는 카나리의 경우 **setConfig**의 **(options)**에는 카나리에서 게시하는 지표를 결정하는 다음 부울 파라미터가 포함될 수 있습니다. 이러한 각 옵션의 기본값은 `true`입니다. `aggregated`로 시작하는 옵션은 ` CanaryName` 측정기준 없이 지표를 내보낼지 여부를 결정합니다. 이러한 지표를 사용하여 모든 canary에 대한 집계 결과를 확인할 수 있습니다. 다른 옵션은 `CanaryName` 측정기준과 함께 지표를 내보낼지 여부를 결정합니다. 이러한 지표를 사용하여 각 개별 canary의 결과를 확인할 수 있습니다.
canary에서 내보내는 CloudWatch 지표 목록은 [canary가 게시한 CloudWatch 지표](CloudWatch_Synthetics_Canaries_metrics.md) 단원을 참조하세요.
+ `failedCanaryMetric`(boolean) - 이 canary에 대한 ` Failed` 지표를 (`CanaryName` 측정기준과 함께) 내보낼지 여부입니다. 기본값은 `true`입니다.
+ `failedRequestsMetric`(boolean) - 이 canary에 대한 `Failed requests` 지표를 (`CanaryName` 측정기준과 함께) 내보낼지 여부입니다. 기본값은 `true`입니다.
+ `_2xxMetric`(boolean) - 이 canary에 대한 `2xx` 지표를 (`CanaryName` 측정기준과 함께) 내보낼지 여부입니다. 기본값은 `true`입니다.
+ `_4xxMetric`(boolean) - 이 canary에 대한 `4xx` 지표를 (`CanaryName` 측정기준과 함께) 내보낼지 여부입니다. 기본값은 `true`입니다.
+ `_5xxMetric`(boolean) - 이 canary에 대한 `5xx` 지표를 (`CanaryName` 측정기준과 함께) 내보낼지 여부입니다. 기본값은 `true`입니다.
+ `stepDurationMetric`(boolean) - 이 canary에 대한 `Step duration` 지표를 (`CanaryName` `StepName` 측정기준과 함께) 내보낼지 여부입니다. 기본값은 `true`입니다.
+ `stepSuccessMetric`(boolean) - 이 canary에 대한 `Step success` 지표를 (`CanaryName` `StepName` 측정기준과 함께) 내보낼지 여부입니다. 기본값은 `true`입니다.
+ `aggregatedFailedCanaryMetric`(boolean) - 이 canary에 대한 `Failed` 지표를 (`CanaryName` 측정기준 없이) 내보낼지 여부입니다. 기본값은 `true`입니다.
+ `aggregatedFailedRequestsMetric`(boolean) - 이 canary에 대한 `Failed Requests` 지표를 (`CanaryName` 측정기준 없이) 내보낼지 여부입니다. 기본값은 `true`입니다.
+ `aggregated2xxMetric`(boolean) - 이 canary에 대한 ` 2xx` 지표를 (`CanaryName` 측정기준 없이) 내보낼지 여부입니다. 기본값은 `true`입니다.
+ `aggregated4xxMetric`(boolean) - 이 canary에 대한 ` 4xx` 지표를 (`CanaryName` 측정기준 없이) 내보낼지 여부입니다. 기본값은 `true`입니다.
+ `aggregated5xxMetric`(boolean) - 이 canary에 대한 ` 5xx` 지표를 (`CanaryName` 측정기준 없이) 내보낼지 여부입니다. 기본값은 `true`입니다.
+ `visualMonitoringSuccessPercentMetric`(boolean) - 이 canary에 대한 `visualMonitoringSuccessPercent` 지표를 내보낼지 여부입니다. 기본값은 `true`입니다.
+ `visualMonitoringTotalComparisonsMetric`(boolean) - 이 canary에 대한 `visualMonitoringTotalComparisons` 지표를 내보낼지 여부입니다. 기본값은 `false`입니다.
+ `includeUrlPassword`(boolean) - URL에 표시되는 암호를 포함할지 여부입니다. 기본적으로 URL에 표시되는 암호를 로그 및 보고서에서 삭제하여 민감한 데이터가 노출되는 것을 방지합니다. 기본값은 `false`입니다.
+ `restrictedUrlParameters`(array) - 수정할 URL 경로 또는 쿼리 파라미터의 목록입니다. 이는 로그, 보고서, 오류에 표시되는 URL에 적용됩니다. 파라미터는 대소문자를 구분하지 않습니다. 별표(\$1)를 값으로 전달하여 모든 URL 경로 및 쿼리 파라미터 값을 수정할 수 있습니다. 기본값은 빈 배열입니다.
+ `logRequest`(boolean) - canary 로그에 모든 요청을 로그할지 여부입니다. UI canary의 경우에는 브라우저에서 보낸 각 요청을 로그합니다. 기본값은 `true`입니다.
+ `logResponse`(boolean) - canary 로그에 모든 응답을 로그할지 여부입니다. UI canary의 경우에는 브라우저에서 수신한 모든 응답을 로그합니다. 기본값은 `true`입니다.
+ `logRequestBody`(boolean) - canary 로그에 요청과 함께 요청 본문을 로그할지 여부입니다. 이 구성은 `logRequest`가 `true`인 경우에만 적용됩니다. 기본값은 `false`입니다.
+ `logResponseBody`(boolean) - canary 로그에 응답과 함께 응답 본문을 로그할지 여부입니다. 이 구성은 `logResponse`가 `true`인 경우에만 적용됩니다. 기본값은 ` false`입니다.
**중요**
`includeResponseBody` 또는 ` logResponseBody`를 활성화하는 경우 aws-sdk v3 클라이언트와 같은 일부 API의 응답에서 데이터 객체가 반환되지 않습니다. 이는 Node.js 제한 및 사용된 응답 객체 유형 때문입니다.
+ `logRequestHeaders`(boolean) - canary 로그에 요청과 함께 요청 헤더를 로그할지 여부입니다. 이 구성은 `logRequest`가 `true`인 경우에만 적용됩니다. 기본값은 ` false`입니다.
`includeRequestHeaders`가 아티팩트의 헤더를 사용 설정한다는 점에 유의하세요.
+ `logResponseHeaders`(boolean) - canary 로그에 응답과 함께 응답 헤더를 로그할지 여부입니다. 이 구성은 `logResponse`가 `true`인 경우에만 적용됩니다. 기본값은 ` false`입니다.
`includeResponseHeaders`가 아티팩트의 헤더를 사용 설정한다는 점에 유의하세요.
**참고**
각 canary에 대한 `Duration` 및 `SuccessPercent` 지표를 항상(`CanaryName` 지표가 있거나 없거나 모두) 내보냅니다.
##### 지표를 사용 또는 사용 중지하는 메서드
**disableAggregatedRequestMetrics()**
canary가 `CanaryName` 측정기준 없이 내보내지는 모든 요청 지표를 내보내지 못하도록 합니다.
**disableRequestMetrics()**
canary별 지표와 모든 canary에서 집계된 지표를 모두 포함하여 모든 요청 지표를 사용 중지합니다.
**disableStepMetrics()**
단계 성공 지표 및 단계 지속 시간 지표 모두를 포함하여 모든 단계 지표를 사용 중지합니다.
**enableAggregatedRequestMetrics()**
canary가 ` CanaryName` 측정기준 없이 내보내지는 모든 요청 지표를 내보낼 수 있도록 합니다.
**enableRequestMetrics()**
canary별 지표와 모든 canary에서 집계된 지표를 모두 포함하여 모든 요청 지표를 사용하도록 설정합니다.
**enableStepMetrics()**
단계 성공 지표 및 단계 지속 시간 지표 모두를 포함하여 모든 단계 지표를 사용 설정합니다.
**get2xxMetric()**
canary가 ` CanaryName` 측정기준과 함께 `2xx` 지표를 내보낼지 여부를 반환합니다.
**get4xxMetric()**
canary가 ` CanaryName` 측정기준과 함께 `4xx` 지표를 내보낼지 여부를 반환합니다.
**get5xxMetric()**
canary가 ` CanaryName` 측정기준과 함께 `5xx` 지표를 내보낼지 여부를 반환합니다.
**getAggregated2xxMetric()**
canary가 측정기준 없이 `2xx` 지표를 내보낼지 여부를 반환합니다.
**getAggregated4xxMetric()**
canary가 측정기준 없이 `4xx` 지표를 내보낼지 여부를 반환합니다.
**getAggregatedFailedCanaryMetric()**
canary가 측정기준 없이 `Failed` 지표를 내보낼지 여부를 반환합니다.
**getAggregatedFailedRequestsMetric()**
canary가 측정기준 없이 `Failed requests` 지표를 내보낼지 여부를 반환합니다.
**getAggregated5xxMetric()**
canary가 측정기준 없이 `5xx` 지표를 내보낼지 여부를 반환합니다.
**getFailedCanaryMetric()**
canary가 ` CanaryName` 측정기준과 함께 `Failed` 지표를 내보낼지 여부를 반환합니다.
**getFailedRequestsMetric()**
canary가 `CanaryName` 측정기준과 함께 `Failed requests` 지표를 내보낼지 여부를 반환합니다.
**getStepDurationMetric()**
canary가 이 canary에 대한 ` CanaryName` 측정기준과 함께 `Duration` 지표를 내보낼지 여부를 반환합니다.
**getStepSuccessMetric()**
canary가 이 canary에 대한 ` CanaryName` 측정기준과 함께 `StepSuccess` 지표를 내보낼지 여부를 반환합니다.
**with2xxMetric(\$12xxMetric)**
이 canary에 대한 `CanaryName` 측정기준과 함께 `2xx` 지표를 내보낼지 여부를 지정하는 부울 인수를 허용합니다.
**with4xxMetric(\$14xxMetric)**
이 canary에 대한 `CanaryName` 측정기준과 함께 `4xx` 지표를 내보낼지 여부를 지정하는 부울 인수를 허용합니다.
**with5xxMetric(\$15xxMetric)**
이 canary에 대한 `CanaryName` 측정기준과 함께 `5xx` 지표를 내보낼지 여부를 지정하는 부울 인수를 허용합니다.
**withAggregated2xxMetric(aggregated2xxMetric)**
이 canary에 대한 측정기준 없이 `2xx` 지표를 내보낼지 여부를 지정하는 부울 인수를 허용합니다.
**withAggregated4xxMetric(aggregated4xxMetric)**
이 canary에 대한 측정기준 없이 `4xx` 지표를 내보낼지 여부를 지정하는 부울 인수를 허용합니다.
**withAggregated5xxMetric(aggregated5xxMetric)**
이 canary에 대한 측정기준 없이 `5xx` 지표를 내보낼지 여부를 지정하는 부울 인수를 허용합니다.
** withAggregatedFailedCanaryMetric(aggregatedFailedCanaryMetric)**
이 canary에 대한 측정기준 없이 `Failed` 지표를 내보낼지 여부를 지정하는 부울 인수를 허용합니다.
** withAggregatedFailedRequestsMetric(aggregatedFailedRequestsMetric)**
이 canary에 대한 측정기준 없이 `Failed requests` 지표를 내보낼지 여부를 지정하는 부울 인수를 허용합니다.
**withFailedCanaryMetric(failedCanaryMetric)**
이 canary에 대한 `CanaryName` 측정기준과 함께 `Failed` 지표를 내보낼지 여부를 지정하는 부울 인수를 허용합니다.
**withFailedRequestsMetric(failedRequestsMetric)**
이 canary에 대한 `CanaryName` 측정기준과 함께 `Failed requests` 지표를 내보낼지 여부를 지정하는 부울 인수를 허용합니다.
**withStepDurationMetric(stepDurationMetric)**
이 canary에 대한 `CanaryName` 측정기준과 함께 `Duration` 지표를 내보낼지 여부를 지정하는 부울 인수를 허용합니다.
**withStepSuccessMetric(stepSuccessMetric)**
이 canary에 대한 `CanaryName` 측정기준과 함께 ` StepSuccess` 지표를 내보낼지 여부를 지정하는 부울 인수를 허용합니다.
##### 다른 기능을 사용 또는 사용 중지하는 메서드
**withHarFile()**
이 canary에 대한 HAR 파일을 생성할지 여부를 지정하는 부울 인수를 허용합니다.
**withStepsReport()**
이 canary에 대한 단계 실행 요약을 보고할지 여부를 지정하는 부울 인수를 허용합니다.
**withIncludeUrlPassword()**
URL에 표시되는 암호를 로그 및 보고서에 포함할지 여부를 지정하는 부울 인수를 허용합니다.
**withRestrictedUrlParameters()**
수정할 URL 경로 또는 쿼리 파라미터의 배열을 허용합니다. 이는 로그, 보고서, 오류에 표시되는 URL에 적용됩니다. 별표(\$1)를 값으로 전달하여 모든 URL 경로 및 쿼리 파라미터 값을 수정할 수 있습니다.
**withLogRequest()**
canary의 로그에 모든 요청을 로그할지 여부를 지정하는 부울 인수를 허용합니다.
**withLogResponse()**
canary의 로그에 모든 응답을 로그할지 여부를 지정하는 부울 인수를 허용합니다.
**withLogRequestBody()**
canary의 로그에 모든 요청 본문을 로그할지 여부를 지정하는 부울 인수를 허용합니다.
**withLogResponseBody()**
canary의 로그에 모든 응답 본문을 로그할지 여부를 지정하는 부울 인수를 허용합니다.
**withLogRequestHeaders()**
canary의 로그에 모든 요청 헤더를 로그할지 여부를 지정하는 부울 인수를 허용합니다.
**withLogResponseHeaders()**
canary의 로그에 모든 응답 헤더를 로그할지 여부를 지정하는 부울 인수를 허용합니다.
**getHarFile()**
canary가 HAR 파일을 생성할지 여부를 반환합니다.
**getStepsReport()**
canary가 단계 실행 요약을 보고할지 여부를 반환합니다.
**getIncludeUrlPassword()**
canary가 URL에 표시되는 암호를 로그 및 보고서에 포함할지 여부를 반환합니다.
**getRestrictedUrlParameters()**
canary가 URL 경로 또는 쿼리 파라미터를 수정할지 여부를 반환합니다.
**getLogRequest()**
canary가 canary의 로그에 모든 요청을 로그할지 여부를 반환합니다.
**getLogResponse()**
canary가 canary의 로그에 모든 응답을 로그할지 여부를 반환합니다.
**getLogRequestBody()**
canary가 canary의 로그에 모든 요청 본문을 로그할지 여부를 반환합니다.
**getLogResponseBody()**
canary가 canary의 로그에 모든 응답 본문을 로그할지 여부를 반환합니다.
**getLogRequestHeaders()**
canary가 canary의 로그에 모든 요청 헤더를 로그할지 여부를 반환합니다.
**getLogResponseHeaders()**
canary가 canary의 로그에 모든 응답 헤더를 로그할지 여부를 반환합니다.
**모든 canary에 대한 함수**
+ `withIncludeRequestHeaders`(includeRequestHeaders)
+ `withIncludeResponseHeaders`(includeResponseHeaders)
+ `withRestrictedHeaders`(restrictedHeaders)
+ `withIncludeRequestBody`(includeRequestBody)
+ `withIncludeResponseBody`(includeResponseBody)
+ `enableReportingOptions`() - 모든 보고 활성화-- **includeRequestHeaders**, **includeResponseHeaders**, **includeRequestBody**, **includeResponseBody**
+ `disableReportingOptions`() - 모든 보고 옵션 비활성화-- **includeRequestHeaders**, **includeResponseHeaders**, **includeRequestBody**, **includeResponseBody**
##### UI canary에 대한 setConfig(options)
UI canary의 경우 **setConfig**에는 다음 부울 파라미터가 포함될 수 있습니다.
+ `continueOnStepFailure`(부울) - 단계가 실패한 후 카나리 스크립트를 계속 실행할지 여부입니다(단계 실패에 대해서는 **executeStep** 함수 참조). 단계가 실패한 경우 canary 실행은 여전히 실패로 표시됩니다. 기본값은 `false`입니다.
+ `harFile`(boolean) - HAR 파일을 생성할지 여부입니다. 기본값은 `True`입니다.
+ `screenshotOnStepStart`(boolean) - 단계를 시작하기 전에 스크린샷을 생성할지 여부입니다.
+ `screenshotOnStepSuccess`(boolean) - 성공적인 단계를 완료한 후 스크린샷을 생성할지 여부입니다.
+ `screenshotOnStepFailure`(boolean) - 단계가 실패한 후 스크린샷을 생성할지 여부입니다.
##### 스크린샷을 사용 또는 사용 중지하는 메서드
**disableStepScreenshots()**
모든 스크린샷 옵션(screenshotOnStepStart, screenshotOnStepSuccess, screenshotOnStepFailure)을 사용 중지합니다.
**enableStepScreenshots()**
모든 스크린샷 옵션(screenshotOnStepStart, screenshotOnStepSuccess, screenshotOnStepFailure)을 사용하도록 설정합니다. 기본적으로 이러한 메서드는 모두 사용 설정되어 있습니다.
**getScreenshotOnStepFailure()**
단계가 실패한 후 canary가 스크린샷을 생성할지 여부를 반환합니다.
**getScreenshotOnStepStart()**
단계를 시작하기 전에 canary가 스크린샷을 생성할지 여부를 반환합니다.
**getScreenshotOnStepSuccess()**
단계를 성공적으로 완료한 후 canary가 스크린샷을 생성할지 여부를 반환합니다.
**withScreenshotOnStepStart(screenshotOnStepStart)**
단계를 시작하기 전에 스크린샷을 생성할지 여부를 나타내는 부울 인수를 허용합니다.
**withScreenshotOnStepSuccess(screenshotOnStepSuccess)**
단계를 성공적으로 완료한 후 스크린샷을 생성할지 여부를 나타내는 부울 인수를 허용합니다.
**withScreenshotOnStepFailure(screenshotOnStepFailure)**
단계가 실패한 후 스크린샷을 생성할지 여부를 나타내는 부울 인수를 허용합니다.
**UI canary의 사용**
먼저, Synthetics 종속 항목을 가져오고 구성을 가져옵니다.
```
// Import Synthetics dependency
const synthetics = require('@aws/synthetics-puppeteer');
// Get Synthetics configuration
const synConfig = synthetics.getConfiguration();
```
다음으로, 다음 옵션 중 하나를 사용하여 setConfig 메서드를 호출함으로써 각 옵션의 구성을 설정합니다.
```
// Set configuration values
synConfig.setConfig({
screenshotOnStepStart: true,
screenshotOnStepSuccess: false,
screenshotOnStepFailure: false
});
```
또는
```
synConfig.withScreenshotOnStepStart(false).withScreenshotOnStepSuccess(true).withScreenshotOnStepFailure(true)
```
모든 스크린샷을 사용 중지하려면 이 예와 같이 `disableStepScreenshots()` 함수를 사용합니다.
```
synConfig.disableStepScreenshots();
```
코드의 어느 지점에서든 스크린샷을 사용 및 사용 중지할 수 있습니다. 예를 들어 한 단계에 대해서만 스크린샷을 사용 중지하려면 해당 단계를 실행하기 전에 스크린샷을 사용 중지한 다음, 이 단계가 끝나면 스크린샷을 사용하도록 설정합니다.
##### API canary에 대한 setConfig(options)
API canary의 경우 **setConfig**에는 다음 부울 파라미터가 포함될 수 있습니다.
+ `continueOnHttpStepFailure`(boolean) - HTTP 단계가 실패한 후 canary 스크립트를 계속 실행할지 여부입니다(단계 실패에 대해서는 **executeHttpStep** 함수 참조). 단계가 실패한 경우 canary 실행은 여전히 실패로 표시됩니다. 기본값은 `true`입니다.
#### 시각적 모니터링
시각적 모니터링에서는 canary 실행 중에 생성한 스크린샷과 기준 canary 실행 중에 생성한 스크린샷을 비교합니다. 두 스크린샷 간의 불일치가 임계 백분율을 초과하면 canary가 실패하며, canary 실행 보고서에서 색상으로 강조 표시된 차이가 있는 영역을 확인할 수 있습니다. 시각적 모니터링은 **syn-puppeteer-node-3.2** 이상을 실행하는 canary에서 지원됩니다. 현재 Python 및 Selenium을 실행하는 canary에서는 지원되지 않습니다.
시각적 모니터링을 사용하려면 canary 스크립트에 다음 코드 줄을 추가합니다. 자세한 내용은 [SyntheticsConfiguration 클래스](#CloudWatch_Synthetics_Library_SyntheticsConfiguration)을(를) 참조하세요.
```
syntheticsConfiguration.withVisualCompareWithBaseRun(true);
```
이 줄을 스크립트에 추가한 후 canary가 처음 성공적으로 실행되면 해당 실행 중에 생성한 스크린샷을 비교를 위한 기준으로 사용합니다. 성공한 첫 번째 canary 실행 후 CloudWatch 콘솔을 사용하여 다음 중 하나를 수행하도록 canary를 편집할 수 있습니다.
+ canary의 다음 실행을 새 기준으로 설정합니다.
+ 현재 기준 스크린샷에 경계선을 그려서 시각적 비교 중에 무시할 스크린샷 영역을 지정합니다.
+ 스크린샷을 제거하여 시각적 모니터링에 사용되지 않도록 합니다.
CloudWatch 콘솔을 사용하여 canary를 편집하는 방법에 대한 자세한 내용은 [canary 편집 또는 삭제](synthetics_canaries_deletion.md) 단원을 참조하세요.
**시각적 모니터링을 위한 기타 옵션**
** syntheticsConfiguration.withVisualVarianceThresholdPercentage(desiredPercentage)**
시각적 비교에서 스크린샷 불일치에 대해 허용 가능한 백분율을 설정합니다.
** syntheticsConfiguration.withVisualVarianceHighlightHexColor("\$1fafa00")**
시각적 모니터링을 사용하는 canary 실행 보고서를 검토할 때 불일치 영역을 지정하는 강조 표시 색상을 설정합니다.
** syntheticsConfiguration.withFailCanaryRunOnVisualVariance(failCanary)**
임곗값보다 큰 시각적 차이가 있는 경우 canary 실패 여부를 설정합니다. 기본값은 canary 실패입니다.
### Synthetics Logger
SyntheticsLogger는 동일한 로그 수준으로 콘솔과 로컬 로그 파일에 모두 로그를 기록합니다. 이 로그 파일은 로그 수준이 호출된 로그 함수의 원하는 로깅 수준 이하인 경우에만 두 위치에 기록됩니다.
로컬 로그 파일의 로깅 문 앞에는 호출된 함수의 로그 수준과 일치하도록 “DEBUG: “, “INFO: “등이 추가됩니다.
Synthetics canary 로깅과 동일한 로그 수준에서 Synthetics 라이브러리를 실행하려는 경우 SyntheticsLogger를 사용할 수 있습니다.
S3 결과 위치에 업로드되는 로그 파일을 생성할 때는 SyntheticsLogger를 사용할 필요가 없습니다. 대신 ` /tmp` 폴더에 다른 로그 파일을 생성할 수 있습니다. `/tmp` 폴더 아래에 생성된 모든 파일은 S3의 결과 위치에 아티팩트로 업로드됩니다.
Synthetics Library Logger를 사용하려면 다음을 실행합니다.
```
const log = require('@aws/synthetics-logger');
```
유용한 함수 정의:
**log.debug(*message*, *ex* );**
파라미터: *message*는 로깅할 메시지이며, *ex*는 기록할 예외입니다(있는 경우).
예제:
```
log.debug("Starting step - login.");
```
**log.error(*message*, *ex* );**
파라미터: *message*는 로깅할 메시지이며, *ex*는 기록할 예외입니다(있는 경우).
예제:
```
try {
await login();
catch (ex) {
log.error("Error encountered in step - login.", ex);
}
```
**log.info(*message*, *ex* );**
파라미터: *message*는 로깅할 메시지이며, *ex*는 기록할 예외입니다(있는 경우).
예제:
```
log.info("Successfully completed step - login.");
```
**log.log(*message*, *ex* );**
`log.info`에 대한 별칭입니다.
파라미터: *message*는 로깅할 메시지이며, *ex*는 기록할 예외입니다(있는 경우).
예제:
```
log.log("Successfully completed step - login.");
```
**log.warn(*message*, *ex* );**
파라미터: *message*는 로깅할 메시지이며, *ex*는 기록할 예외입니다(있는 경우).
예제:
```
log.warn("Exception encountered trying to publish CloudWatch Metric.", ex);
```
### SyntheticsLogHelper 클래스
`SyntheticsLogHelper` 클래스는 런타임 ` syn-nodejs-puppeteer-3.2` 이상 런타임에서 사용할 수 있습니다. 이 클래스는 CloudWatch Synthetics 라이브러리에 이미 초기화되어 있으며 Synthetics 구성으로 구성되어 있습니다. 스크립트에서 이 클래스를 종속 항목으로 추가할 수 있습니다. 이 클래스를 사용하면 URL, 헤더, 오류 메시지를 제거하여 민감한 정보를 수정할 수 있습니다.
**참고**
Synthetics는 로그하는 모든 URL과 오류 메시지를 Synthetics 구성 설정인 `restrictedUrlParameters`에 따라 로그, 보고서, HAR 파일, canary 실행 오류에 포함하기 전에 제거합니다. 스크립트에서 URL 또는 오류를 로그하는 경우에만 ` getSanitizedUrl` 또는 `getSanitizedErrorMessage`를 사용해야 합니다. Synthetics는 스크립트에서 발생시킨 canary 오류를 제외하고는 어떠한 canary 아티팩트도 저장하지 않습니다. canary 실행 아티팩트는 고객 계정에 저장됩니다. 자세한 내용은 [Synthetics canary에 대한 보안 고려 사항](servicelens_canaries_security.md) 단원을 참조하세요.
**Topics**
+ [getSanitizedUrl(url, stepConfig = null)](#CloudWatch_Synthetics_Library_getSanitizedUrl)
+ [getSanitizedErrorMessage](#CloudWatch_Synthetics_Library_getSanitizedErrorMessage)
+ [getSanitizedHeaders(headers, stepConfig=null)](#CloudWatch_Synthetics_Library_getSanitizedHeaders)
#### getSanitizedUrl(url, stepConfig = null)
이 함수는 `syn-nodejs-puppeteer-3.2` 이상에서 사용할 수 있습니다. 이 함수는 구성에 따라 제거된 URL 문자열을 반환합니다. `restrictedUrlParameters` 속성을 설정하여 암호 및 access\$1token과 같은 민감한 URL 파라미터를 수정하도록 선택할 수 있습니다. 기본적으로 URL의 암호는 수정됩니다. 필요한 경우 `includeUrlPassword`를 true로 설정하여 URL 암호를 사용하도록 설정할 수 있습니다.
전달된 URL이 유효한 URL이 아닌 경우 이 함수는 오류를 발생시킵니다.
**파라미터**
+ *url*은 문자열이며 제거할 URL입니다.
+ *stepConfig*(선택 사항)는 이 함수의 글로벌 Synthetics 구성을 재정의합니다. `stepConfig`가 전달되지 않으면 글로벌 구성이 URL을 제거하는 데 사용됩니다.
**예**
이 예에서는 샘플 URL ` https://example.com/learn/home?access_token=12345&token_type=Bearer&expires_in=1200`을 사용합니다. 이 예에서 `access_token`은 로그되어서는 안 되는 민감한 정보를 포함합니다. Synthetics 서비스는 어떠한 canary 실행 아티팩트도 저장하지 않습니다. 로그, 스크린샷, 보고서와 같은 아티팩트는 모두 고객 계정의 Amazon S3 버킷에 저장됩니다.
첫 번째 단계는 Synthetics 구성을 설정하는 것입니다.
```
// Import Synthetics dependency
const synthetics = require('@aws/synthetics-puppeteer');
// Import Synthetics logger for logging url
const log = require('@aws/synthetics-logger');
// Get Synthetics configuration
const synConfig = synthetics.getConfiguration();
// Set restricted parameters
synConfig.setConfig({
restrictedUrlParameters: ['access_token'];
});
// Import SyntheticsLogHelper dependency
const syntheticsLogHelper = require('@aws/synthetics-log-helper');
const sanitizedUrl = syntheticsLogHelper.getSanitizedUrl('URL');
const urlConfig = {
restrictedUrlParameters = ['*']
};
const sanitizedUrl = syntheticsLogHelper.getSanitizedUrl('URL', urlConfig);
logger.info('My example url is: ' + sanitizedUrl);
```
다음으로, URL을 제거하고 로그합니다.
```
// Import SyntheticsLogHelper dependency
const syntheticsLogHelper = require('@aws/synthetics-log-helper');
const sanitizedUrl = syntheticsLogHelper.getSanitizedUrl('https://example.com/learn/home?access_token=12345&token_type=Bearer&expires_in=1200');
```
그러면 canary 로그에 다음이 로그됩니다.
```
My example url is: https://example.com/learn/home?access_token=REDACTED&token_type=Bearer&expires_in=1200
```
다음 예와 같이 Synthetics 구성 옵션이 포함된 선택적 파라미터를 전달하여 URL에 대한 Synthetics 구성을 재정의할 수 있습니다.
```
const urlConfig = {
restrictedUrlParameters = ['*']
};
const sanitizedUrl = syntheticsLogHelper.getSanitizedUrl('https://example.com/learn/home?access_token=12345&token_type=Bearer&expires_in=1200', urlConfig);
logger.info('My example url is: ' + sanitizedUrl);
```
앞의 예는 모든 쿼리 파라미터를 수정하며 다음과 같이 로그됩니다.
```
My example url is: https://example.com/learn/home?access_token=REDACTED&token_type=REDACTED&expires_in=REDACTED
```
#### getSanitizedErrorMessage
이 함수는 `syn-nodejs-puppeteer-3.2` 이상에서 사용할 수 있습니다. 이 함수는 Synthetics 구성에 따라 존재하는 URL을 제거하여 제거된 오류 문자열을 반환합니다. 선택적 `stepConfig` 파라미터를 전달하여 이 함수를 호출할 때 글로벌 Synthetics 구성을 재정의하도록 선택할 수 있습니다.
**파라미터**
+ *error*는 제거할 오류이며, Error 객체 또는 문자열일 수 있습니다.
+ *stepConfig*(선택 사항)는 이 함수의 글로벌 Synthetics 구성을 재정의합니다. `stepConfig`가 전달되지 않으면 글로벌 구성이 URL을 제거하는 데 사용됩니다.
**예**
이 예에서는 ` Failed to load url: https://example.com/learn/home?access_token=12345&token_type=Bearer&expires_in=1200` 오류를 사용합니다.
첫 번째 단계는 Synthetics 구성을 설정하는 것입니다.
```
// Import Synthetics dependency
const synthetics = require('@aws/synthetics-puppeteer');
// Import Synthetics logger for logging url
const log = require('@aws/synthetics-logger');
// Get Synthetics configuration
const synConfig = synthetics.getConfiguration();
// Set restricted parameters
synConfig.setConfig({
restrictedUrlParameters: ['access_token'];
});
```
다음으로, 오류 메시지를 제거하고 로그합니다.
```
// Import SyntheticsLogHelper dependency
const syntheticsLogHelper = require('@aws/synthetics-log-helper');
try {
// Your code which can throw an error containing url which your script logs
} catch (error) {
const sanitizedErrorMessage = syntheticsLogHelper.getSanitizedErrorMessage(errorMessage);
logger.info(sanitizedErrorMessage);
}
```
그러면 canary 로그에 다음이 로그됩니다.
```
Failed to load url: https://example.com/learn/home?access_token=REDACTED&token_type=Bearer&expires_in=1200
```
#### getSanitizedHeaders(headers, stepConfig=null)
이 함수는 `syn-nodejs-puppeteer-3.2` 이상에서 사용할 수 있습니다. 이 함수는 ` syntheticsConfiguration`의 `restrictedHeaders` 속성에 따라 제거된 헤더를 반환합니다. `restrictedHeaders` 속성에 지정된 헤더는 로그, HAR 파일, 보고서에서 수정됩니다.
**파라미터**
+ *headers*는 제거할 헤더가 포함된 객체입니다.
+ *stepConfig*(선택 사항)는 이 함수의 글로벌 Synthetics 구성을 재정의합니다. `stepConfig`가 전달되지 않으면 글로벌 구성이 헤더를 제거하는 데 사용됩니다.
## UI canary에만 적용되는 Node.js 라이브러리 클래스 및 함수
다음 Node.js용 CloudWatch Synthetics 라이브러리 함수는 UI canary에만 사용할 수 있습니다.
**Topics**
+ [Synthetics 클래스](#CloudWatch_Synthetics_Library_Synthetics_Class)
+ [BrokenLinkCheckerReport 클래스](#CloudWatch_Synthetics_Library_BrokenLinkCheckerReport)
+ [SyntheticsLink 클래스](#CloudWatch_Synthetics_Library_SyntheticsLink)
### Synthetics 클래스
다음 함수는 Synthetics 클래스에 있습니다.
**Topics**
+ [async addUserAgent(page, userAgentString);](#CloudWatch_Synthetics_Library_addUserAgent)
+ [async executeStep(stepName, functionToExecute, [stepConfig]);](#CloudWatch_Synthetics_Library_executeStep)
+ [getDefaultLaunchOptions();](#CloudWatch_Synthetics_Library_getDefaultLaunchOptions)
+ [getPage();](#CloudWatch_Synthetics_Library_getPage)
+ [getRequestResponseLogHelper();](#CloudWatch_Synthetics_Library_getRequestResponseLogHelper)
+ [launch(options)](#CloudWatch_Synthetics_Library_LaunchOptions)
+ [RequestResponseLogHelper 클래스](#CloudWatch_Synthetics_Library_RequestResponseLogHelper)
+ [setRequestResponseLogHelper();](#CloudWatch_Synthetics_Library_setRequestResponseLogHelper)
+ [async takeScreenshot(name, suffix);](#CloudWatch_Synthetics_Library_takeScreenshot)
#### async addUserAgent(page, userAgentString);
이 함수는 지정된 페이지의 사용자 에이전트 헤더에 *userAgentString*을 추가합니다.
예제:
```
await synthetics.addUserAgent(page, "MyApp-1.0");
```
페이지의 사용자 에이전트 헤더가 ` browsers-user-agent-header-valueMyApp-1.0`으로 설정됩니다.
#### async executeStep(stepName, functionToExecute, [stepConfig]);
제공된 단계를 실행하며 시작/성공/실패 로깅, 시작/성공/실패 스크린샷, 성공/실패 및 기간 지표로 래핑합니다.
**참고**
`syn-nodejs-2.1` 이상 런타임을 사용하는 경우 스크린샷을 생성할지 여부 및 시기를 구성할 수 있습니다. 자세한 내용은 [SyntheticsConfiguration 클래스](#CloudWatch_Synthetics_Library_SyntheticsConfiguration) 섹션을 참조하세요.
`executeStep` 함수는 다음 작업도 수행합니다.
+ 단계가 시작되었음을 기록합니다.
+ 이름이 `-starting`인 스크린샷을 캡처합니다.
+ 타이머를 시작합니다.
+ 제공된 함수를 실행합니다.
+ 함수가 값을 정상적으로 반환하면 성공한 것으로 간주됩니다. 함수가 오류를 생성하면 실패한 것으로 간주됩니다.
+ 타이머를 종료합니다.
+ 단계 성공 또는 실패 여부를 기록합니다.
+ 이름이 `-succeeded` 또는 ` -failed`인 스크린샷을 캡처합니다.
+ `stepName` `SuccessPercent` 지표(성공 시 100, 실패 시 0)를 내보냅니다.
+ 단계 시작 및 종료 시간 기준의 값을 사용하여 `stepName` `Duration` 지표를 내보냅니다.
+ 마지막으로, `functionToExecute`에서 반환된 값을 반환하고 `functionToExecute`에서 생성된 오류를 다시 생성합니다.
canary가 `syn-nodejs-2.0` 런타임 이상을 사용하는 경우 이 함수는 canary의 보고서에 단계 실행 요약도 추가합니다. 요약에는 시작 시간, 종료 시간, 상태(PASSED/FAILED), 실패 원인(실패한 경우), 각 단계를 실행하는 동안 캡처된 스크린샷과 같은 각 단계에 관한 세부 정보가 포함됩니다.
예제:
```
await synthetics.executeStep('navigateToUrl', async function (timeoutInMillis = 30000) {
await page.goto(url, {waitUntil: ['load', 'networkidle0'], timeout: timeoutInMillis});});
```
응답:
`functionToExecute`에서 반환된 값을 반환합니다.
**syn-nodejs-2.2로 업데이트**
`syn-nodejs-2.2`부터 선택적으로 단계 구성을 전달하여 단계 수준에서 CloudWatch Synthetics 구성을 재정의할 수 있습니다. `executeStep`에 전달할 수 있는 옵션 목록은 [SyntheticsConfiguration 클래스](#CloudWatch_Synthetics_Library_SyntheticsConfiguration) 단원을 참조하세요.
다음 예에서는 ` continueOnStepFailure`에 대한 기본 `false` 구성을 `true`로 재정의하고 스크린샷을 생성할 시기를 지정합니다.
```
var stepConfig = {
'continueOnStepFailure': true,
'screenshotOnStepStart': false,
'screenshotOnStepSuccess': true,
'screenshotOnStepFailure': false
}
await executeStep('Navigate to amazon', async function (timeoutInMillis = 30000) {
await page.goto(url, {waitUntil: ['load', 'networkidle0'], timeout: timeoutInMillis});
}, stepConfig);
```
#### getDefaultLaunchOptions();
`getDefaultLaunchOptions()` 함수는 CloudWatch Synthetics에서 사용하는 브라우저 시작 옵션을 반환합니다. 자세한 내용은 [Launch options type](https://pptr.dev/browsers-api/browsers.launchoptions/) 섹션을 참조하세요.
```
// This function returns default launch options used by Synthetics.
const defaultOptions = await synthetics.getDefaultLaunchOptions();
```
#### getPage();
현재 열린 페이지를 Puppeteer 객체로 반환합니다. 자세한 내용은 [Puppeteer API v1.14.0](https://github.com/puppeteer/puppeteer/blob/v1.14.0/docs/api.md)을 참조하세요.
예제:
```
let page = await synthetics.getPage();
```
응답:
현재 브라우저 세션에서 현재 열려 있는 페이지(Puppeteer 객체)입니다.
#### getRequestResponseLogHelper();
**중요**
`syn-nodejs-puppeteer-3.2` 런타임 이상을 사용하는 canary에서는 `RequestResponseLogHelper` 클래스와 함께 이 함수가 더 이상 사용되지 않습니다. 이 함수를 사용하면 canary 로그에 경고가 표시됩니다. 이 함수는 향후 런타임 버전에서 제거됩니다. 이 함수를 사용할 경우 대신 [RequestResponseLogHelper 클래스](#CloudWatch_Synthetics_Library_RequestResponseLogHelper) 클래스를 사용하세요.
이 함수는 요청 및 응답 로깅 플래그를 수정하기 위한 빌더 패턴으로 사용됩니다.
예제:
```
synthetics.setRequestResponseLogHelper(getRequestResponseLogHelper().withLogRequestHeaders(false));;
```
응답:
```
{RequestResponseLogHelper}
```
#### launch(options)
이 함수의 옵션은 `syn-nodejs-2.1` 런타임 버전 이상에서만 사용할 수 있습니다.
이 함수는 UI canary에만 사용됩니다. 이 함수는 기존 브라우저를 닫고 새 브라우저를 시작합니다.
**참고**
CloudWatch Synthetics는 스크립트 실행을 시작하기 전에 항상 브라우저를 시작합니다. 사용자 지정 옵션으로 새 브라우저를 시작하려는 경우 외에는 launch()를 호출할 필요가 없습니다.
(options)는 브라우저에 설정할 수 있는 구성 가능한 옵션 집합입니다. 자세한 내용은 [실행 옵션 유형](https://pptr.dev/browsers-api/browsers.launchoptions/) 섹션을 참조하세요.
옵션 없이 이 함수를 호출하면 Synthetics는 기본 인수인 `executablePath` 및 `defaultViewport`를 사용하여 브라우저를 시작합니다. CloudWatch Synthetics의 기본 뷰포트는 1920 x 1080입니다.
CloudWatch Synthetics에서 사용하는 시작 파라미터를 재정의할 수 있으며 브라우저를 시작할 때 추가 파라미터를 전달할 수 있습니다. 예를 들어 다음 코드 조각에서는 기본 인수와 기본 실행 경로를 사용하여 브라우저를 시작하지만 뷰포트는 800 x 600입니다.
```
await synthetics.launch({
defaultViewport: {
"deviceScaleFactor": 1,
"width": 800,
"height": 600
}});
```
다음 샘플 코드에서는 CloudWatch Synthetics 시작 파라미터에 새로운 `ignoreHTTPSErrors` 파라미터를 추가합니다.
```
await synthetics.launch({
ignoreHTTPSErrors: true
});
```
다음과 같이 CloudWatch Synthetics 시작 파라미터의 인수에 `--disable-web-security` 플래그를 추가하여 웹 보안을 사용 중지할 수 있습니다.
```
// This function adds the --disable-web-security flag to the launch parameters
const defaultOptions = await synthetics.getDefaultLaunchOptions();
const launchArgs = [...defaultOptions.args, '--disable-web-security'];
await synthetics.launch({
args: launchArgs
});
```
#### RequestResponseLogHelper 클래스
**중요**
`syn-nodejs-puppeteer-3.2` 런타임 이상을 사용하는 canary에서는 이 클래스가 더 이상 사용되지 않습니다. 이 클래스를 사용하면 canary 로그에 경고가 표시됩니다. 이 함수는 향후 런타임 버전에서 제거됩니다. 이 함수를 사용할 경우 대신 [RequestResponseLogHelper 클래스](#CloudWatch_Synthetics_Library_RequestResponseLogHelper) 클래스를 사용하세요.
요청 및 응답 페이로드의 세분화된 구성 및 문자열 표현 생성을 처리합니다.
```
class RequestResponseLogHelper {
constructor () {
this.request = {url: true, resourceType: false, method: false, headers: false, postData: false};
this.response = {status: true, statusText: true, url: true, remoteAddress: false, headers: false};
}
withLogRequestUrl(logRequestUrl);
withLogRequestResourceType(logRequestResourceType);
withLogRequestMethod(logRequestMethod);
withLogRequestHeaders(logRequestHeaders);
withLogRequestPostData(logRequestPostData);
withLogResponseStatus(logResponseStatus);
withLogResponseStatusText(logResponseStatusText);
withLogResponseUrl(logResponseUrl);
withLogResponseRemoteAddress(logResponseRemoteAddress);
withLogResponseHeaders(logResponseHeaders);
```
예제:
```
synthetics.setRequestResponseLogHelper(getRequestResponseLogHelper()
.withLogRequestPostData(true)
.withLogRequestHeaders(true)
.withLogResponseHeaders(true));
```
응답:
```
{RequestResponseLogHelper}
```
#### setRequestResponseLogHelper();
**중요**
`syn-nodejs-puppeteer-3.2` 런타임 이상을 사용하는 canary에서는 `RequestResponseLogHelper` 클래스와 함께 이 함수가 더 이상 사용되지 않습니다. 이 함수를 사용하면 canary 로그에 경고가 표시됩니다. 이 함수는 향후 런타임 버전에서 제거됩니다. 이 함수를 사용할 경우 대신 [RequestResponseLogHelper 클래스](#CloudWatch_Synthetics_Library_RequestResponseLogHelper) 클래스를 사용하세요.
이 함수는 요청 및 응답 로깅 플래그를 설정하기 위한 빌더 패턴으로 사용됩니다.
예제:
```
synthetics.setRequestResponseLogHelper().withLogRequestHeaders(true).withLogResponseHeaders(true);
```
응답:
```
{RequestResponseLogHelper}
```
#### async takeScreenshot(name, suffix);
이름 및 접미사를 사용하여 현재 페이지의 스크린샷(.PNG)을 생성합니다(선택 사항).
예제:
```
await synthetics.takeScreenshot("navigateToUrl", "loaded")
```
이 예에서는 ` 01-navigateToUrl-loaded.png`라는 스크린샷을 캡처하여 canary의 S3 버킷에 업로드합니다.
` stepName`을 첫 번째 파라미터로 전달하여 특정 canary 단계에 대한 스크린샷을 생성할 수 있습니다. 스크린샷은 보고서의 canary 단계에 연결되어 디버깅하는 동안 각 단계를 추적하는 데 도움이 됩니다.
CloudWatch Synthetics canary는 단계 시작 전(`executeStep` 함수)과 단계 완료 후에 자동으로 스크린샷을 생성합니다(스크린샷을 사용 중지하도록 canary를 구성하지 않은 경우). `takeScreenshot` 함수에서 단계 이름을 전달하면 더 많은 스크린샷을 생성할 수 있습니다.
다음 예에서는 `stepName`의 값으로 `signupForm`을 사용하여 스크린샷을 생성합니다. 스크린샷은 이름이 ` 02-signupForm-address`가 되며 canary 보고서의 ` signupForm`이라는 단계에 연결됩니다.
```
await synthetics.takeScreenshot('signupForm', 'address')
```
### BrokenLinkCheckerReport 클래스
이 클래스는 Synthetics 링크를 추가하는 메서드를 제공합니다. `syn-nodejs-2.0-beta` 런타임 버전 이상을 사용하는 canary에서만 지원됩니다.
`BrokenLinkCheckerReport`를 사용하려면 스크립트에 다음 줄을 포함합니다.
```
const BrokenLinkCheckerReport = require('@aws/synthetics-broken-link-checker-report');
const brokenLinkCheckerReport = new BrokenLinkCheckerReport();
```
유용한 함수 정의:
**addLink(*syntheticsLink*, isBroken)**
` syntheticsLink `는 링크를 나타내는 ` SyntheticsLink` 객체입니다. 이 함수는 상태 코드에 따라 링크를 추가합니다. 기본적으로 상태 코드를 사용할 수 없거나 상태 코드가 400 이상인 경우 이 함수는 링크가 잘못된 것으로 간주합니다. 선택적 파라미터 `isBrokenLink`를 `true` 또는 `false` 값과 함께 전달하여 이 기본 동작을 재정의할 수 있습니다.
이 함수에는 반환 값이 없습니다.
**getLinks()**
이 함수는 잘못된 링크 검사기 보고서에 포함된 `SyntheticsLink` 객체의 배열을 반환합니다.
**getTotalBrokenLinks()**
이 함수는 잘못된 링크의 총수를 나타내는 숫자를 반환합니다.
**getTotalLinksChecked()**
이 함수는 보고서에 포함된 링크의 총수를 나타내는 숫자를 반환합니다.
**BrokenLinkCheckerReport 사용 방법**
다음 canary 스크립트 코드 조각은 링크를 탐색하여 잘못된 링크 검사기 보고서에 추가하는 예를 보여 줍니다.
1. `SyntheticsLink`, `BrokenLinkCheckerReport`, ` Synthetics`를 가져옵니다.
```
const BrokenLinkCheckerReport = require('@aws/synthetics-broken-link-checker-report');
const SyntheticsLink = require('@aws/synthetics-link');
// Synthetics dependency
const synthetics = require('@aws/synthetics-puppeteer');
```
1. 보고서에 대한 링크를 추가하려면 ` BrokenLinkCheckerReport`의 인스턴스를 생성합니다.
```
let brokenLinkCheckerReport = new BrokenLinkCheckerReport();
```
1. URL을 탐색하여 잘못된 링크 검사기 보고서에 추가합니다.
```
let url = "https://amazon.com";
let syntheticsLink = new SyntheticsLink(url);
// Navigate to the url.
let page = await synthetics.getPage();
// Create a new instance of Synthetics Link
let link = new SyntheticsLink(url)
try {
const response = await page.goto(url, {waitUntil: 'domcontentloaded', timeout: 30000});
} catch (ex) {
// Add failure reason if navigation fails.
link.withFailureReason(ex);
}
if (response) {
// Capture screenshot of destination page
let screenshotResult = await synthetics.takeScreenshot('amazon-home', 'loaded');
// Add screenshot result to synthetics link
link.addScreenshotResult(screenshotResult);
// Add status code and status description to the link
link.withStatusCode(response.status()).withStatusText(response.statusText())
}
// Add link to broken link checker report.
brokenLinkCheckerReport.addLink(link);
```
1. 보고서를 Synthetics에 추가합니다. 그러면 각 canary 실행에 대해 ` BrokenLinkCheckerReport.json`이라는 JSON 파일이 S3 버킷에 생성됩니다. 스크린샷, 로그, HAR 파일과 함께 각 canary 실행에 대한 링크 보고서를 콘솔에서 확인할 수 있습니다.
```
await synthetics.addReport(brokenLinkCheckerReport);
```
### SyntheticsLink 클래스
이 클래스는 정보를 래핑하는 메서드를 제공합니다. `syn-nodejs-2.0-beta` 런타임 버전 이상을 사용하는 canary에서만 지원됩니다.
`SyntheticsLink`를 사용하려면 스크립트에 다음 줄을 포함합니다.
```
const SyntheticsLink = require('@aws/synthetics-link');
const syntheticsLink = new SyntheticsLink("https://www.amazon.com");
```
이 함수는 `syntheticsLinkObject`를 반환합니다.
유용한 함수 정의:
**withUrl(*url*)**
` url `은 URL 문자열입니다. 이 함수는 `syntheticsLinkObject`를 반환합니다.
**withText(*text*)**
` text `는 앵커 텍스트를 나타내는 문자열입니다. 이 함수는 `syntheticsLinkObject`를 반환합니다. 이 함수는 링크에 해당하는 앵커 텍스트를 추가합니다.
**withParentUrl(*parentUrl*)**
` parentUrl `은 상위(소스 페이지) URL을 나타내는 문자열입니다. 이 함수는 `syntheticsLink Object`를 반환합니다.
**withStatusCode(*statusCode*)**
` statusCode `는 상태 코드를 나타내는 문자열입니다. 이 함수는 `syntheticsLinkObject`를 반환합니다.
**withFailureReason(*failureReason*)**
` failureReason `은 실패 원인을 나타내는 문자열입니다. 이 함수는 `syntheticsLink Object`를 반환합니다.
**addScreenshotResult(*screenshotResult*)**
` screenshotResult `는 객체이며, Synthetics 함수 `takeScreenshot`에 의해 반환된 `ScreenshotResult`의 인스턴스입니다. 객체에는 다음이 포함됩니다.
+ `fileName` - ` screenshotFileName`을 나타내는 문자열
+ `pageUrl` (선택 사항)
+ `error` (선택 사항)
## API canary에만 적용되는 Node.js 라이브러리 클래스 및 함수
다음 Node.js용 CloudWatch Synthetics 라이브러리 함수는 API canary에만 사용할 수 있습니다.
**Topics**
+ [executeHttpStep(stepName, requestOptions, [callback], [stepConfig])](#CloudWatch_Synthetics_Library_executeHttpStep)
### executeHttpStep(stepName, requestOptions, [callback], [stepConfig])
제공된 HTTP 요청을 단계로 실행하고 `SuccessPercent`(통과 또는 실패) 및 `Duration` 지표를 게시합니다.
**executeHttpStep**은 요청에 지정된 프로토콜에 따라 내부적으로 HTTP 또는 HTTPS 네이티브 함수를 사용합니다.
이 함수는 canary의 보고서에 단계 실행 요약도 추가합니다. 요약에는 다음과 같은 각 HTTP 요청에 관한 세부 정보가 포함됩니다.
+ 시작 시간
+ 종료 시간
+ 상태(PASSED/FAILED)
+ 실패 원인(실패한 경우)
+ 요청 또는 응답 헤더, 본문, 상태 코드, 상태 메시지, 성능 타이밍과 같은 HTTP 호출 세부 정보
**Topics**
+ [파라미터](#CloudWatch_Synthetics_Library_executeHttpStep_parameters)
+ [executeHttpStep 사용 예](#CloudWatch_Synthetics_Library_executeHttpStep_examples)
#### 파라미터
**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\$1299(포함)인지 확인합니다.
```
// 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) 단원을 참조하세요.