Node.js 카나리에 사용할 수 있는 라이브러리 함수 - Amazon CloudWatch
addExecutionError(errorMessage, ex);getCanaryName();getCanaryArn();getCanaryUserAgentString();getRuntimeVersion();getLogLevel()setLogLevel()executeStep(stepName, functionToExecute, [stepConfig])executeHttpStep(stepName, requestOptions, [callback], [stepConfig])

Node.js 카나리에 사용할 수 있는 라이브러리 함수

이 섹션에서는 Node.js 런타임을 사용하여 카나리 스크립트에 사용할 수 있는 라이브러리 함수에 대해 설명합니다.

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 호출 세부 정보

파라미터

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