# canary 블루프린트 사용
이 섹션에서는 각 canary 블루프린트 및 각 블루프린트가 가장 적합한 작업에 대해 자세히 설명합니다. 다음과 같은 canary 유형에 대해 블루프린트가 제공됩니다.
**Topics**
+ [하트비트 모니터링](#CloudWatch_Synthetics_Canaries_Blueprints_Heartbeat)
+ [API canary](#CloudWatch_Synthetics_Canaries_Blueprints_API)
+ [잘못된 링크 검사기](#CloudWatch_Synthetics_Canaries_Blueprints_Broken_Links)
+ [시각적 모니터링 블루프린트](#CloudWatch_Synthetics_Canaries_Blueprints_VisualTesting)
+ [canary 레코더](#CloudWatch_Synthetics_Canaries_Blueprints_Recorder)
+ [GUI 워크플로 빌더](#CloudWatch_Synthetics_Canaries_Blueprints_GUI_Workflow)
+ [다중 검사 블루프린트](#CloudWatch_Synthetics_Canaries_Blueprints_Multichecks_Blueprint)
+ [다중 검사 블루프린트 카나리 생성](CloudWatch_Synthetics_Canaries_MultiCheck_Blueprint.md)
블루프린트를 사용하여 canary를 생성할 때 CloudWatch 콘솔에서 필드를 작성하면 페이지의 [**스크립트 편집기(Script editor)**] 영역에 생성 중인 canary가 Node.js 스크립트로 표시됩니다. 이 영역에서 canary를 편집하여 추가로 사용자 지정할 수도 있습니다.
## 하트비트 모니터링
하트비트 스크립트는 지정된 URL을 로드하고 페이지의 스크린샷과 HTTP 아카이브 파일(HAR 파일)을 저장합니다. 또한 액세스한 URL의 로그도 저장합니다.
HAR 파일을 사용하여 웹페이지에 대한 자세한 성능 데이터를 볼 수 있습니다. 웹 요청 목록을 분석하고 항목에 대한 로드 시간과 같은 성능 문제를 파악할 수 있습니다.
canary에서 `syn-nodejs-puppeteer-3.1` 이상의 런타임 버전을 사용하는 경우 하트비트 모니터링 블루프린트를 사용하여 여러 URL을 모니터링하고 canary 실행 보고서의 단계 요약에서 각 URL의 상태, 지속 시간, 관련 스크린샷, 실패 원인을 확인할 수 있습니다.
## API canary
API canary는 REST API의 기본 읽기 및 쓰기 기능을 테스트할 수 있습니다. REST는 *representational state transfer*의 약어로 개발자가 API를 생성할 때 따르는 일련의 규칙입니다. 이러한 규칙 중 하나에는 특정 URL에 대한 링크가 데이터 조각을 반환해야 한다고 명시되어 있습니다.
canary는 어느 API와도 함께 작동하며 모든 유형의 기능을 테스트할 수 있습니다. 각 canary는 여러 API를 호출할 수 있습니다.
런타임 버전 `syn-nodejs-2.2` 이상을 사용하는 canary에서 API canary 블루프린트는 API를 HTTP 단계로 모니터링하는 다단계 canary를 지원합니다. 단일 canary에서 여러 API를 테스트할 수 있습니다. 각 단계는 서로 다른 URL에 액세스하고 서로 다른 헤더를 사용하며 헤더 및 응답 본문을 캡처할지 여부에 대해 서로 다른 규칙을 사용할 수 있는 별도의 요청입니다. 헤더 및 응답 본문을 캡처하지 않음으로써 민감한 데이터가 기록되지 않도록 방지할 수 있습니다.
API canary의 각 요청은 다음 정보로 구성됩니다.
+ *엔드포인트*: 사용자가 요청하는 URL입니다.
+ *메서드*: 서버로 전송되는 요청의 유형입니다. REST API는 GET(읽기), POST(쓰기), PUT(업데이트), PATCH(업데이트) 및 DELETE(삭제) 작업을 지원합니다.
+ *헤더*: 클라이언트와 서버 모두에 정보를 제공합니다. 이는 인증 및 본문 내용에 대한 정보를 제공하는 데 사용됩니다. 유효한 헤더 목록은 [HTTP 헤더](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers)를 참조하세요.
+ *데이터*(또는 *본문*): 서버에 전송할 정보가 포함되어 있습니다. 이는 POST, PUT, PATCH 또는 DELETE 요청에만 사용됩니다.
**참고**
API 카나리 블루프린트는 Playwright 런타임에서 지원되지 않습니다.
API canary 블루프린트는 GET 및 POST 메서드를 지원합니다. 이 블루프린트를 사용할 때는 헤더를 지정해야 합니다. 예를 들어 **Authorization**을 **키**로 지정하고 필요한 인증 데이터를 해당 키의 **값**으로 지정할 수 있습니다.
POST 요청을 테스트하는 경우 **데이터** 필드에 게시할 콘텐츠도 지정합니다.
**API Gateway와의 통합**
API 블루프린트는 Amazon API Gateway와 통합됩니다. 이를 통해 API Gateway API를 선택하고 canary와 동일한 AWS 계정 및 리전에서 스테이징하거나 교차 계정 및 교차 리전 API 모니터링을 위해 API Gateway에서 Swagger 템플릿을 업로드할 수 있습니다. 그런 다음, Scratch에서 나머지 세부 정보를 입력하는 대신 콘솔에서 선택하여 canary를 생성할 수 있습니다. API Gateway에 대한 자세한 내용은 [Amazon API Gateway란?](https://docs.aws.amazon.com/apigateway/latest/developerguide/welcome.html) 단원을 참조하세요.
**프라이빗 API 사용**
Amazon API Gateway에서 프라이빗 API를 사용하는 canary를 생성할 수 있습니다. 자세한 내용은 [Amazon API Gateway에서 프라이빗 API 생성](https://docs.aws.amazon.com/apigateway/latest/developerguide/apigateway-private-apis.html)을 참조하세요.
## 잘못된 링크 검사기
잘못된 링크 검사기는 `document.getElementsByTagName('a')`을 사용하여 테스트 중인 URL 내부의 모든 링크를 수집합니다. 지정한 링크 수까지만 테스트하며, URL 자체가 첫 번째 링크로 계산됩니다. 예를 들어 5개의 링크가 포함된 페이지의 모든 링크를 검사하려면 canary가 6개의 링크를 따르도록 지정해야 합니다.
`syn-nodejs-2.0-beta` 런타임 이상을 사용하여 생성된 잘못된 링크 검사기 canary는 다음과 같은 추가 기능을 지원합니다.
+ 확인된 링크, 상태 코드, 실패 원인(있는 경우), 소스 및 대상 페이지 스크린샷이 포함된 보고서를 제공합니다.
+ canary 결과를 살펴볼 때 잘못된 링크만 표시하도록 필터링한 다음, 실패 원인을 기반으로 링크를 수정할 수 있습니다.
+ 이 버전은 각 링크에 대해 주석이 달린 소스 페이지 스크린샷을 캡처하고 링크가 발견된 앵커를 강조 표시합니다. 숨겨진 구성 요소에는 주석이 달려 있지 않습니다.
+ 소스 페이지와 대상 페이지 모두, 소스 페이지만 또는 대상 페이지만 스크린샷을 캡처하도록 이 버전을 구성할 수 있습니다.
+ 이 버전은 첫 페이지에서 더 많은 링크를 스크레이프한 경우에도 첫 번째 잘못된 링크 이후에 canary 스크립트가 중지되는 이전 버전의 문제를 수정합니다.
**참고**
끊어진 링크 검사기 블루프린트는 Playwright 런타임에서 지원되지 않습니다.
`syn-1.0`을 사용하는 기존 카나리를 업데이트하여 새 런타임을 사용하려면 카나리를 삭제하고 다시 생성해야 합니다. 기존 canary를 새 런타임으로 업데이트해도 이러한 기능을 사용할 수는 없습니다.
잘못된 링크 검사기 canary는 다음과 같은 유형의 링크 오류를 감지합니다.
+ 404 페이지를 찾을 수 없음
+ 잘못된 호스트 이름
+ 잘못된 URL. 예를 들어 URL에 대괄호가 없거나 여분의 슬래시가 있거나 잘못된 프로토콜을 사용합니다.
+ 잘못된 HTTP 응답 코드
+ 호스트 서버가 콘텐츠가 없고 응답 코드가 없는 빈 응답을 반환합니다.
+ HTTP 요청은 canary 실행 중에 지속적으로 시간 초과됩니다.
+ 호스트가 잘못 구성되었거나 사용 중이므로 계속 연결이 끊어집니다.
## 시각적 모니터링 블루프린트
시각적 모니터링 블루프린트에는 canary 실행 중에 생성한 스크린샷과 기준 canary 실행 중에 생성한 스크린샷을 비교하는 코드가 포함되어 있습니다. 두 스크린샷 간의 불일치가 임계 백분율을 초과하면 canary가 실패합니다. 시각적 모니터링은 **syn-puppeteer-node-3.2** 이상을 실행하는 canary에서 지원됩니다. 현재 Python 및 Selenium을 실행하거나, Playwright 런타임을 사용하는 카나리에서는 지원되지 않습니다.
시각적 모니터링 블루프린트에는 시각적 모니터링을 사용 설정하는 기본 블루프린트 canary 스크립트에 다음 코드 줄이 포함되어 있습니다.
```
syntheticsConfiguration.withVisualCompareWithBaseRun(true);
```
이 줄을 스크립트에 추가한 후 canary가 처음 성공적으로 실행되면 해당 실행 중에 생성한 스크린샷을 비교를 위한 기준으로 사용합니다. 성공한 첫 번째 canary 실행 후 CloudWatch 콘솔을 사용하여 다음 중 하나를 수행하도록 canary를 편집할 수 있습니다.
+ canary의 다음 실행을 새 기준으로 설정합니다.
+ 현재 기준 스크린샷에 경계선을 그려서 시각적 비교 중에 무시할 스크린샷 영역을 지정합니다.
+ 스크린샷을 제거하여 시각적 모니터링에 사용되지 않도록 합니다.
CloudWatch 콘솔을 사용하여 canary를 편집하는 방법에 대한 자세한 내용은 [canary 편집 또는 삭제](synthetics_canaries_deletion.md) 단원을 참조하세요.
또한 ` nextrun` 또는 `lastrun` 파라미터를 사용하거나 [UpdateCanary](https://docs.aws.amazon.com/AmazonSynthetics/latest/APIReference/API_UpdateCanary.html) API에서 canary 실행 ID를 지정하여 기준으로 사용되는 canary 실행을 변경할 수도 있습니다.
시각적 모니터링 청사진을 사용할 때 스크린샷을 생성할 URL을 입력하고 차이 임곗값을 백분율로 지정합니다. 기준 실행 후 해당 임곗값보다 큰 시각적 차이를 감지하는 canary의 향후 실행은 canary 실패를 트리거합니다. 기준 실행 후 canary를 편집하여 시각적 모니터링 중에 무시하려는 경계선을 기준 스크린샷에 ‘그릴’ 수도 있습니다.
시각적 모니터링 기능은 ImageMagick 오픈 소스 소프트웨어 도구 키트를 통해 제공됩니다. 자세한 내용은 [ImageMagick](https://imagemagick.org/index.php)을 참조하세요.
## canary 레코더
canary 레코더 블루프린트를 통해 CloudWatch Synthetics Recorder를 사용하여 웹 사이트에서의 클릭 및 입력 작업을 기록하고 동일한 단계를 따르는 canary를 생성하는 데 사용할 수 있는 Node.js 스크립트를 자동으로 생성할 수 있습니다. CloudWatch Synthetics Recorder는 Amazon에서 제공하는 Google Chrome 확장 프로그램입니다. 카나리 Recorder는 Playwright 런타임을 사용하는 카나리에서는 지원되지 않습니다.
**크레딧**: CloudWatch Synthetics Recorder는 [헤드리스 레코더](https://github.com/checkly/headless-recorder)를 기반으로 합니다.
자세한 내용은 [Google Chrome용 CloudWatch Synthetics Recorder 사용](CloudWatch_Synthetics_Canaries_Recorder.md) 단원을 참조하세요.
## GUI 워크플로 빌더
GUI 워크플로 빌더 블루프린트는 웹 페이지에서 작업을 수행할 수 있는지 확인합니다. 예를 들어 웹 페이지에 로그인 양식이 있는 경우 canary는 사용자 및 암호 필드를 채우고 양식을 제출하여 웹 페이지가 올바르게 작동하는지 확인할 수 있습니다.
블루프린트를 사용하여 이 유형의 canary를 생성할 때 웹 페이지에서 canary가 수행할 작업을 지정합니다. 사용할 수 있는 작업은 다음과 같습니다.
+ **클릭** - 지정된 요소를 선택하고, 요소를 클릭하거나 선택하는 사용자를 시뮬레이션합니다.
Node.js 스크립트에서 요소를 지정하려면 `[id=]` 또는 ` a[class=]`를 사용합니다.
Python 스크립트에서 요소를 지정하려면 `xpath //*[@id=]` 또는 ` //*[@class=]`를 사용합니다.
+ **선택기 확인** - 지정된 요소가 웹 페이지에 있는지 확인합니다. 이 테스트는 이전 작업으로 인해 올바른 요소가 페이지를 채우는지 확인하는 데 유용합니다.
Node.js 스크립트에서 확인할 요소를 지정하려면 `[id=]` 또는 ` a[class=]`를 사용합니다.
Python 스크립트에서 확인할 요소를 지정하려면 `xpath //*[@id=]` 또는 `//*[class=]`를 사용합니다.
+ **텍스트 확인** - 지정된 문자열이 대상 요소 내에 포함되어 있는지 확인합니다. 이 테스트는 이전 작업으로 인해 올바른 텍스트가 표시되는지 확인하는 데 유용합니다.
Node.js 스크립트에서 요소를 지정하려면 ` div[@id=]//h1`과 같은 형식을 사용합니다. 이 작업은 Puppeteer의 `waitForXPath` 함수를 사용하기 때문입니다.
Python 스크립트에서 요소를 지정하려면 ` //*[@id=] ` 또는 //\*[@class=] 같은 xpath 형식을 사용합니다. 이 작업은 Selenium의 `implicitly_wait` 함수를 사용하기 때문입니다.
+ **텍스트 입력** - 대상 요소에 지정된 텍스트를 작성합니다.
Node.js 스크립트에서 확인할 요소를 지정하려면 `[id=]` 또는 ` a[class=]`를 사용합니다.
Python 스크립트에서 확인할 요소를 지정하려면 `xpath //*[@id=]` 또는 `//*[@class=]`를 사용합니다.
+ **탐색과 함께 클릭** - 지정된 요소를 선택한 후 전체 페이지가 로드될 때까지 기다립니다. 이는 페이지를 다시 로드해야 할 때 가장 유용합니다.
Node.js 스크립트에서 요소를 지정하려면 `[id=]` 또는 ` a[class=]`를 사용합니다.
Python 스크립트에서 요소를 지정하려면 `xpath //*[@id=]` 또는 ` //*[@class=]`를 사용합니다.
예를 들어 다음 블루프린트는 Node.js를 사용합니다. 지정된 URL의 **firstButton**을 클릭하고, 예상 텍스트가 있는 예상 선택기가 나타나는지 확인하고, **이름(Name)** 필드에 `Test_Customer`라고 이름을 입력합니다. **로그인(Login)** 버튼을 클릭한 후 다음 페이지에서 **시작(Welcome)** 텍스트가 표시되는지 확인하여 로그인이 성공했는지 확인합니다.
다음 런타임을 사용하는 GUI 워크플로 canary는 각 canary 실행에 대해 실행된 단계의 요약도 제공합니다. 각 단계와 관련된 스크린샷 및 오류 메시지를 사용하여 실패의 근본 원인을 찾을 수 있습니다.
+ `syn-nodejs-2.0` 이상
+ `syn-python-selenium-1.0` 이상
## 다중 검사 블루프린트
다중 검사 블루프린트는 카나리 생성을 간소화합니다. HTTP, DNS, SSL, TCP 검사 수행에 즉시 사용 가능한 기능을 제공하는 간단한 JSON 구성을 사용하여 비용을 절감합니다. 최대 10가지 검사를 구성할 수 있습니다. 각 검사를 순차적으로 실행되는 숫자 단계로 구성하여 카나리 흐름을 명확하게 이해할 수 있도록 합니다.
다중 검사 블루프린트는 다음을 지원합니다.
+ 기본 HTTP 요청, TCP 요청, DNS 레코드 검증, SSL 인증서 모니터링
+ Secrets Manager와 통합된 Basic, API 키, OAuth, Sigv4 같은 HTTP 인증 방법
+ 각 검사에 대한 어설션
자세한 내용은 [canary 생성](CloudWatch_Synthetics_Canaries_Create.md) 섹션을 참조하세요.