Node.js canary 스크립트에 사용할 수 있는 라이브러리 함수

이 단원에서는 Node.js canary 스크립트에 사용할 수 있는 라이브러리 함수를 설명합니다.

모든 canary에 적용되는 Node.js 라이브러리 클래스 및 함수

다음 Node.js용 CloudWatch Synthetics 라이브러리 함수는 모든 canary에 사용할 수 있습니다.

Synthetics 클래스

모든 canary에 사용할 수 있는 다음 함수는 Synthetics 클래스에 있습니다.

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 라이브러리에 대한 현재 로그 수준을 검색합니다. 가능한 값은 다음과 같습니다.

예시

let logLevel = synthetics.getLogLevel();

setLogLevel()

Synthetics 라이브러리의 로그 수준을 설정합니다. 가능한 값은 다음과 같습니다.

예시

synthetics.setLogLevel(0);

SyntheticsConfiguration 클래스

이 클래스는 syn-nodejs-2.1 런타임 버전 이상에서만 사용할 수 있습니다.

SyntheticsConfiguration 클래스를 사용하여 Synthetics 라이브러리 함수의 동작을 구성할 수 있습니다. 예를 들어 이 클래스를 사용하여 스크린샷을 캡처하지 않도록 executeStep() 함수를 구성할 수 있습니다.

canary의 모든 단계에 적용되는 글로벌 수준에서 CloudWatch Synthetics 구성을 설정할 수 있습니다. 또한 구성 키-값 페어를 전달하여 단계 수준에서 이러한 구성을 재정의할 수도 있습니다.

단계 수준에서 옵션을 전달할 수 있습니다. 예를 보려면 async executeStep(stepName, functionToExecute, [stepConfig]); 및 executeHttpStep(stepName, requestOptions, [callback], [stepConfig]) 단원을 참조하세요.

함수 정의:

setConfig(options)

options는 canary에 대해 구성 가능한 옵션의 집합인 객체입니다. 다음 단원에서는 options의 가능한 필드를 설명합니다.

모든 canary에 대한 setConfig(options)

syn-nodejs-puppeteer-3.2 이상을 사용하는 canary의 경우 setConfig의 (options)에는 다음 파라미터가 포함될 수 있습니다.

CloudWatch 지표에 관한 setConfig(options)

syn-nodejs-puppeteer-3.1 이상을 사용하는 canary의 경우 setConfig의 (options)에는 canary에서 게시하는 지표를 결정하는 다음 부울 파라미터가 포함될 수 있습니다. 이러한 각 옵션의 기본값은 true입니다. aggregated로 시작하는 옵션은 CanaryName 측정기준 없이 지표를 내보낼지 여부를 결정합니다. 이러한 지표를 사용하여 모든 canary에 대한 집계 결과를 확인할 수 있습니다. 다른 옵션은 CanaryName 측정기준과 함께 지표를 내보낼지 여부를 결정합니다. 이러한 지표를 사용하여 각 개별 canary의 결과를 확인할 수 있습니다.

지표를 사용 또는 사용 중지하는 메서드

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(_2xxMetric)

이 canary에 대한 CanaryName 측정기준과 함께 2xx 지표를 내보낼지 여부를 지정하는 부울 인수를 허용합니다.

with4xxMetric(_4xxMetric)

이 canary에 대한 CanaryName 측정기준과 함께 4xx 지표를 내보낼지 여부를 지정하는 부울 인수를 허용합니다.

with5xxMetric(_5xxMetric)

이 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에 적용됩니다. 별표(*)를 값으로 전달하여 모든 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에 대한 함수

UI canary에 대한 setConfig(options)

UI canary의 경우 setConfig에는 다음 부울 파라미터가 포함될 수 있습니다.

스크린샷을 사용 또는 사용 중지하는 메서드

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('Synthetics');

// Get Synthetics configuration
const synConfig = synthetics.getConfiguration();

다음으로, 다음 옵션 중 하나를 사용하여 setConfig 메서드를 호출함으로써 각 옵션의 구성을 설정합니다.

// Set configuration values
    synConfig.setConfig({
        screenshotOnStepStart: true, 
        screenshotOnStepSuccess: false,
        screenshotOnStepFailure: false
    });

Or

synConfig.withScreenshotOnStepStart(false).withScreenshotOnStepSuccess(true).withScreenshotOnStepFailure(true)

모든 스크린샷을 사용 중지하려면 이 예와 같이 disableStepScreenshots() 함수를 사용합니다.

synConfig.disableStepScreenshots();

코드의 어느 지점에서든 스크린샷을 사용 및 사용 중지할 수 있습니다. 예를 들어 한 단계에 대해서만 스크린샷을 사용 중지하려면 해당 단계를 실행하기 전에 스크린샷을 사용 중지한 다음, 이 단계가 끝나면 스크린샷을 사용하도록 설정합니다.

API canary에 대한 setConfig(options)

API canary의 경우 setConfig에는 다음 부울 파라미터가 포함될 수 있습니다.

시각적 모니터링

시각적 모니터링에서는 canary 실행 중에 생성한 스크린샷과 기준 canary 실행 중에 생성한 스크린샷을 비교합니다. 두 스크린샷 간의 불일치가 임계 백분율을 초과하면 canary가 실패하며, canary 실행 보고서에서 색상으로 강조 표시된 차이가 있는 영역을 확인할 수 있습니다. 시각적 모니터링은 syn-puppeteer-node-3.2 이상을 실행하는 canary에서 지원됩니다. 현재 Python 및 Selenium을 실행하는 canary에서는 지원되지 않습니다.

시각적 모니터링을 사용하려면 canary 스크립트에 다음 코드 줄을 추가합니다. 자세한 내용은 SyntheticsConfiguration 클래스을(를) 참조하세요.

syntheticsConfiguration.withVisualCompareWithBaseRun(true);

이 줄을 스크립트에 추가한 후 canary가 처음 성공적으로 실행되면 해당 실행 중에 생성한 스크린샷을 비교를 위한 기준으로 사용합니다. 성공한 첫 번째 canary 실행 후 CloudWatch 콘솔을 사용하여 다음 중 하나를 수행하도록 canary를 편집할 수 있습니다.

CloudWatch 콘솔을 사용하여 canary를 편집하는 방법에 대한 자세한 내용은 canary 편집 또는 삭제 단원을 참조하세요.

시각적 모니터링을 위한 기타 옵션

syntheticsConfiguration.withVisualVarianceThresholdPercentage(desiredPercentage)

시각적 비교에서 스크린샷 불일치에 대해 허용 가능한 백분율을 설정합니다.

syntheticsConfiguration.withVisualVarianceHighlightHexColor("#fafa00")

시각적 모니터링을 사용하는 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('SyntheticsLogger');

유용한 함수 정의:

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, 헤더, 오류 메시지를 제거하여 민감한 정보를 수정할 수 있습니다.

getSanitizedUrl(url, stepConfig = null)

이 함수는 syn-nodejs-puppeteer-3.2 이상에서 사용할 수 있습니다. 이 함수는 구성에 따라 제거된 URL 문자열을 반환합니다. restrictedUrlParameters 속성을 설정하여 암호 및 access_token과 같은 민감한 URL 파라미터를 수정하도록 선택할 수 있습니다. 기본적으로 URL의 암호는 수정됩니다. 필요한 경우 includeUrlPassword를 true로 설정하여 URL 암호를 사용하도록 설정할 수 있습니다.

전달된 URL이 유효한 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('Synthetics');

// Import Synthetics logger for logging url
const log = require('SyntheticsLogger');

// Get Synthetics configuration
const synConfig = synthetics.getConfiguration();

// Set restricted parameters
synConfig.setConfig({
   restrictedUrlParameters: ['access_token'];
});

다음으로, URL을 제거하고 로그합니다.

// Import SyntheticsLogHelper dependency
const syntheticsLogHelper = require('SyntheticsLogHelper');

const sanitizedUrl = synthetics.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 = synthetics.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 구성을 재정의하도록 선택할 수 있습니다.

파라미터

예

이 예에서는 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('Synthetics');

// Import Synthetics logger for logging url
const log = require('SyntheticsLogger');

// Get Synthetics configuration
const synConfig = synthetics.getConfiguration();

// Set restricted parameters
synConfig.setConfig({
   restrictedUrlParameters: ['access_token'];
});

다음으로, 오류 메시지를 제거하고 로그합니다.

// Import SyntheticsLogHelper dependency
const syntheticsLogHelper = require('SyntheticsLogHelper');

try {
   // Your code which can throw an error containing url which your script logs
} catch (error) {
    const sanitizedErrorMessage = synthetics.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 파일, 보고서에서 수정됩니다.

파라미터

UI canary에만 적용되는 Node.js 라이브러리 클래스 및 함수

다음 Node.js용 CloudWatch Synthetics 라이브러리 함수는 UI canary에만 사용할 수 있습니다.

Synthetics 클래스

다음 함수는 Synthetics 클래스에 있습니다.

async addUserAgent(page, userAgentString);

이 함수는 지정된 페이지의 사용자 에이전트 헤더에 userAgentString을 추가합니다.

예시

await synthetics.addUserAgent(page, "MyApp-1.0");

페이지의 사용자 에이전트 헤더가 browsers-user-agent-header-valueMyApp-1.0으로 설정됩니다.

async executeStep(stepName, functionToExecute, [stepConfig]);

제공된 단계를 실행하며 시작/성공/실패 로깅, 시작/성공/실패 스크린샷, 성공/실패 및 기간 지표로 래핑합니다.

executeStep 함수는 다음 작업도 수행합니다.

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 클래스 단원을 참조하세요.

다음 예에서는 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 섹션을 참조하세요.

// This function returns default launch options used by Synthetics.
const defaultOptions = await synthetics.getDefaultLaunchOptions();

getPage();

현재 열린 페이지를 Puppeteer 객체로 반환합니다. 자세한 내용은 Puppeteer API v1.14.0을 참조하세요.

예시

let page = synthetics.getPage();

응답:

현재 브라우저 세션에서 현재 열려 있는 페이지(Puppeteer 객체)입니다.

getRequestResponseLogHelper();

이 함수는 요청 및 응답 로깅 플래그를 수정하기 위한 빌더 패턴으로 사용됩니다.

예시

synthetics.setRequestResponseLogHelper(getRequestResponseLogHelper().withLogRequestHeaders(false));;

응답:

{RequestResponseLogHelper}

launch(options)

이 함수의 옵션은 syn-nodejs-2.1 런타임 버전 이상에서만 사용할 수 있습니다.

이 함수는 UI canary에만 사용됩니다. 이 함수는 기존 브라우저를 닫고 새 브라우저를 시작합니다.

(options)는 브라우저에 설정할 수 있는 구성 가능한 옵션 집합입니다. 자세한 내용은 Launch options type 섹션을 참조하세요.

옵션 없이 이 함수를 호출하면 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 클래스

요청 및 응답 페이로드의 세분화된 구성 및 문자열 표현 생성을 처리합니다.

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();

이 함수는 요청 및 응답 로깅 플래그를 설정하기 위한 빌더 패턴으로 사용됩니다.

예시

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('BrokenLinkCheckerReport');
            
const brokenLinkCheckerReport = new BrokenLinkCheckerReport();

유용한 함수 정의:

addLink(syntheticsLink, isBroken)

syntheticsLink는 링크를 나타내는 SyntheticsLink 객체입니다. 이 함수는 상태 코드에 따라 링크를 추가합니다. 기본적으로 상태 코드를 사용할 수 없거나 상태 코드가 400 이상인 경우 이 함수는 링크가 잘못된 것으로 간주합니다. 선택적 파라미터 isBrokenLink를 true 또는 false 값과 함께 전달하여 이 기본 동작을 재정의할 수 있습니다.

이 함수에는 반환 값이 없습니다.

getLinks()

이 함수는 잘못된 링크 검사기 보고서에 포함된 SyntheticsLink 객체의 배열을 반환합니다.

getTotalBrokenLinks()

이 함수는 잘못된 링크의 총수를 나타내는 숫자를 반환합니다.

getTotalLinksChecked()

이 함수는 보고서에 포함된 링크의 총수를 나타내는 숫자를 반환합니다.

BrokenLinkCheckerReport 사용 방법

다음 canary 스크립트 코드 조각은 링크를 탐색하여 잘못된 링크 검사기 보고서에 추가하는 예를 보여 줍니다.

SyntheticsLink 클래스

이 클래스는 정보를 래핑하는 메서드를 제공합니다. syn-nodejs-2.0-beta 런타임 버전 이상을 사용하는 canary에서만 지원됩니다.

SyntheticsLink를 사용하려면 스크립트에 다음 줄을 포함합니다.

const SyntheticsLink = require('SyntheticsLink');

const syntheticsLink = new SyntheticsLink("https://www.amazon.com");

이 함수는 syntheticsLinkObject를 반환합니다.

유용한 함수 정의:

withUrl(url)

url은 URL 문자열입니다. 이 함수는 syntheticsLinkObject를 반환합니다.

withText(text)

text는 앵커 텍스트를 나타내는 문자열입니다. 이 함수는 syntheticsLinkObject를 반환합니다. 이 함수는 링크에 해당하는 앵커 텍스트를 추가합니다.

withParentUrl(parentUrl)

parentUrl은 상위(소스 페이지) URL을 나타내는 문자열입니다. 이 함수는 syntheticsLinkObject를 반환합니다.

withStatusCode(statusCode)

statusCode는 상태 코드를 나타내는 문자열입니다. 이 함수는 syntheticsLinkObject를 반환합니다.

withFailureReason(failureReason)

failureReason은 실패 원인을 나타내는 문자열입니다. 이 함수는 syntheticsLinkObject를 반환합니다.

addScreenshotResult(screenshotResult)

screenshotResult는 객체이며, Synthetics 함수 takeScreenshot에 의해 반환된 ScreenshotResult의 인스턴스입니다. 객체에는 다음이 포함됩니다.

API canary에만 적용되는 Node.js 라이브러리 클래스 및 함수

다음 Node.js용 CloudWatch Synthetics 라이브러리 함수는 API canary에만 사용할 수 있습니다.

executeHttpStep(stepName, requestOptions, [callback], [stepConfig])

제공된 HTTP 요청을 단계로 실행하고 SuccessPercent(통과 또는 실패) 및 Duration 지표를 게시합니다.

executeHttpStep은 요청에 지정된 프로토콜에 따라 내부적으로 HTTP 또는 HTTPS 네이티브 함수를 사용합니다.

이 함수는 canary의 보고서에 단계 실행 요약도 추가합니다. 요약에는 다음과 같은 각 HTTP 요청에 관한 세부 정보가 포함됩니다.

파라미터

stepName(String)

단계 이름을 지정합니다. 이 이름은 이 단계의 CloudWatch 지표 게시에도 사용됩니다.

requestOptions(Object 또는 String)

이 파라미터의 값은 URL, URL 문자열 또는 객체일 수 있습니다. 객체인 경우 HTTP 요청을 수행하기 위해 구성 가능한 옵션 집합이어야 합니다. Node.js 설명서에 있는 http.request(options[, callback])의 모든 옵션을 지원합니다.

이러한 Node.js 옵션 외에도 requestOptions는 추가 파라미터인 body를 지원합니다. body 파라미터를 사용하면 데이터를 요청 본문으로 전달할 수 있습니다.

callback(response)

(선택 사항) HTTP 응답을 사용하여 호출되는 사용자 함수입니다. 응답은 클래스: 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 단원을 참조하세요.