# Criar um canário
**Importante**
Use canaries do Synthetics para monitorar somente endpoints e APIs nos quais você tem propriedade ou permissões. Dependendo das configurações de frequência do canário, esses endpoints podem sofrer aumento do tráfego.
Ao usar o console do CloudWatch para criar um canário, é possível usar um esquema fornecido pelo CloudWatch para criar o canário ou escrever seu próprio script. Para obter mais informações, consulte [Usar esquemas de canaries](CloudWatch_Synthetics_Canaries_Blueprints.md).
Também é possível criar um canay usando o CloudFormation, se você estiver usando seu próprio script para o canário. Para obter mais informações, consulte [AWS::Synthetics::Canary](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-synthetics-canary.html) no *Manual do usuário do AWS CloudFormation*.
Se você estiver escrevendo seu próprio script, poderá usar várias funções que o CloudWatch Synthetics incorporou a uma biblioteca. Para obter mais informações, consulte [Versões do runtime do Synthetics](CloudWatch_Synthetics_Canaries_Library.md).
**nota**
Ao criar um canário, uma das camadas criadas é a Synthetics prefixada com ` Synthetics`. Essa camada pertence à conta de serviço Synthetics e contém o código de runtime.
**Como criar um canário**
1. Abra o console do CloudWatch, em [https://console.aws.amazon.com/cloudwatch/](https://console.aws.amazon.com/cloudwatch/).
1. No painel de navegação, escolha **Application Signals**, **Canários do Synthetics**.
1. Selecione **Create Canary** (Criar canário).
1. Escolha uma das seguintes opções:
+ Para basear o canário no script de um esquema, escolha **Usar um blueprint (Usar um esquema)** e selecione o tipo de canário que deseja criar. Para obter mais informações sobre o que faz cada tipo de esquema, consulte [Usar esquemas de canaries](CloudWatch_Synthetics_Canaries_Blueprints.md).
+ Para fazer upload de seu próprio script Node.js a fim de criar um canário personalizado, selecione **Upload a script (Fazer upload de um script)**.
Depois, é possível arrastar o script para a área **Script** ou selecionar **Browse files (Pesquisar arquivos)** para navegar até o script no sistema de arquivos.
+ Para importar o script de um bucket do S3, selecione **Import from S3 (Importar do S3)**. Em **Source location (Local de origem)**, digite o caminho completo do canário ou selecione **Browse S3 (Pesquisar no S3)**.
É necessário ter as permissões `s3:GetObject` e `s3:GetObjectVersion` para o bucket do S3 usado. O bucket deve estar na mesma região da AWS onde o canário está sendo criado.
1. Em **Name (Nome)**, insira um nome para o canário. O nome é usado em várias páginas, portanto, recomendamos que você forneça a ele um nome descritivo para distingui-lo de outros canaries.
1. Em **Application or endpoint URL (URL do aplicativo ou endpoint)**, digite o URL que você deseja que o canário teste. Esse URL deve incluir o protocolo (como https://).
Se você quiser que o canário teste um endpoint em uma VPC, insira as informações sobre a VPC posteriormente neste procedimento.
1. Se estiver usando seu próprio script para o canário, em **Lambda handler (Manipulador do Lambda)**, insira o ponto de entrada onde deseja que o canário se inicie. Para obter mais informações sobre o formato do manipulador do Lambda, consulte [Versões do runtime do Synthetics](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/CloudWatch_Synthetics_Canaries_Library.html).
1. Em **Editor de scripts**, **Versão do runtime**, selecione uma versão do runtime do Synthetics para executar o canário. Para obter informações sobre as versões do runtime do Synthetics, consulte [Versões do runtime do Synthetics](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/CloudWatch_Synthetics_Canaries_Library.html).
Em **Configuração do navegador**, você pode habilitar o navegador para testar o canário. É necessário selecionar pelo menos um navegador.
1. Se você estiver usando variáveis de ambiente em seu script, escolha **Environment variables** (Variáveis de ambiente) e especifique um valor para cada variável de ambiente definida no script. Para obter mais informações, consulte [Variáveis de ambiente](CloudWatch_Synthetics_Canaries_WritingCanary_Nodejs_Pup.md#CloudWatch_Synthetics_Environment_Variables).
1. Em **Schedule** (Programar), escolha se deseja executar esse canário uma vez, continuamente usando uma expressão rate ou usando uma expressão cron.
+ Ao usar o console do CloudWatch para criar um canário que é executado continuamente, você pode escolher uma taxa em qualquer lugar entre uma vez por minuto e uma vez por hora.
+ Para obter mais informações sobre como escrever uma expressão cron para programação do canário, consulte [Agendamento de execuções do canário usando cron](CloudWatch_Synthetics_Canaries_cron.md).
1. (Opcional) Para definir um valor de tempo limite para o canário, escolha **Additional configuration** (Configuração adicional) e, depois, especifique o valor do tempo limite. Especifique um tempo limite de pelo menos 15 segundos para permitir que o Lambda seja iniciado a frio e que a instrumentação do canário seja inicializada.
1. Em **Data retention (Retenção de dados)**, especifique por quanto tempo as informações sobre as execuções bem-sucedidas e com falha de canaries devem ser mantidas. O intervalo é de 1 a 455 dias.
Essa configuração afeta o intervalo de informações retornadas por operações [GetCanaryRuns](https://docs.aws.amazon.com/AmazonSynthetics/latest/APIReference/API_GetCanaryRuns.html), bem como o intervalo de informações exibidas no console do Synthetics.
Ela não tem efeito sobre os dados armazenados nos seus buckets do Amazon S3, nem em logs ou métricas que são publicados pelo canário.
Independentemente do período de retenção de dados do canário, o intervalo de informações exibidas no console apresenta certos limites. Na visualização inicial do console do Synthetics, o intervalo de tempo relativo e absoluto está limitado a sete dias. Na visualização do console do Synthetics de um canário específico, o intervalo de tempo relativo está limitado a sete dias, e o intervalo de tempo absoluto, a 30 dias.
1. Em **Armazenamento de dados**, selecione o bucket do Amazon S3 que será usado para armazenar os dados das execuções do canário. O nome do bucket não pode conter um ponto (.). Caso você não preencha este campo, um bucket padrão do Amazon S3 será usado ou criado automaticamente.
1. (Opcional) Por padrão, os canaries armazenam seus artefatos no Amazon S3 e os artefatos são criptografados em repouso usando uma chave do AWS KMS gerenciada pela AWS. É possível usar uma opção de criptografia diferente escolhendo **Additional configuration** (Configuração adicional) na seção **Data Storage** (Armazenamento de dados). Em seguida, escolha o tipo de chave a ser usada para a criptografia. Para obter mais informações, consulte [Criptografar artefatos do canário](CloudWatch_Synthetics_artifact_encryption.md).
1. Em **Access permissions** (Permissões de acesso), escolha se deseja criar uma função do IAM para executar o canário ou usar uma existente.
Se você usar o CloudWatch Synthetics para criar a função, ele incluirá automaticamente todas as permissões necessárias. Se desejar criar a função por conta própria, consulte [Funções e permissões necessárias para canaries](CloudWatch_Synthetics_Canaries_CanaryPermissions.md) para obter informações sobre as permissões necessárias.
Se o console do CloudWatch for usado para criar uma função para um canário ao criá-lo, não será possível reutilizar a função para outros canários, porque essas funções são específicas de apenas um canário. Se você tiver criado manualmente uma função que funcione para vários canaries, poderá usá-la.
Para usar uma função existente, é necessário ter a permissão `iam:PassRole` para transmitir essa função para o Synthetics e o Lambda. Também é necessário ter a permissão `iam:GetRole`.
1. (Opcional) Em **Alarms** (Alarmes), escolha se deseja que sejam criados alarmes padrão do CloudWatch para esse canário. Se optar por criar alarmes, eles serão criados com esta convenção de nomes: :`Synthetics-Alarm-canaryName -index `
`index` é um número que representa cada alarme diferente criado para este canário. O primeiro alarme tem um índice de 1, o segundo alarme tem um índice de 2 e assim por diante.
1. (Opcional) Para que esse canário teste um endpoint em uma VPC, escolha **VPC settings (Configurações da VPC)** e faça o seguinte:
1. Selecione a VPC que hospeda o endpoint.
1. Selecione uma ou mais sub-redes na sua VPC. É necessário selecionar uma sub-rede privada, porque a instância do Lambda não pode ser configurada para ser executada em uma sub-rede pública quando um endereço IP não pode ser atribuído à instância do Lambda durante a execução. Para obter mais informações, consulte [Configurar uma função Lambda para acessar recursos em uma VPC](https://docs.aws.amazon.com/lambda/latest/dg/configuration-vpc.html).
1. Selecione um ou mais grupos de segurança na sua VPC.
1. Para permitir tráfego IPv6 de saída para este canário, selecione **Permitir tráfego IPv6 para sub-redes de pilha dupla**. Isso permite que o canário monitore endpoints somente IPv6 e habilitados para pilha dupla via IPv6.
É possível monitorar endpoints externos à sua VPC fornecendo ao canário acesso à internet e configurando as sub-redes da VPC adequadamente. Para obter mais informações, consulte [Execução de um canário em uma VPC](CloudWatch_Synthetics_Canaries_VPC.md).
Se o endpoint estiver em uma VPC, habilite seu canário para enviar informações ao CloudWatch e ao Amazon S3. Para obter mais informações, consulte [Execução de um canário em uma VPC](CloudWatch_Synthetics_Canaries_VPC.md).
1. (Opcional) Em **Tags**, adicione um ou mais pares de chave/valor como tags para esse canário. As tags podem ajudar a identificar e organizar seus recursos da AWS e acompanhar seus custos da AWS. Para obter mais informações, consulte [Etiquetar recursos do Amazon CloudWatch](CloudWatch-Tagging.md).
Se você desejar que as etiquetas aplicadas ao canário também sejam aplicadas à função do Lambda que o canário usa, escolha **Função do Lambda** em **Replicação de etiquetas**. Se você escolher essa opção, o CloudWatch Synthetics manterá as etiquetas do canário e da função do Lambda sincronizadas:
+ O Synthetics aplicará as mesmas etiquetas que você especificar aqui ao canário e à função do Lambda.
+ Se você atualizar posteriormente as etiquetas do canário e mantiver esta opção selecionada, o Synthetics modificará as etiquetas na função do Lambda para permanecerem sincronizadas com o canário.
1. (Opcional) Em **Active tracing** (Rastreamento ativo), escolha se deseja ativar o rastreamento ativo do X-Ray para esse canário. O recurso de rastreamento ativo é compatível somente com os runtimes Puppeteer e Java. Para obter mais informações, consulte [Canaries e rastreamento do X-Ray](CloudWatch_Synthetics_Canaries_tracing.md).
## Recursos que são criados para canaries
Ao criar um canário, os seguintes recursos são criados:
+ Uma função do IAM com o nome `CloudWatchSyntheticsRole-canary-name -uuid` (se você usar o console do CloudWatch para criar o canário e especificar que deve ser criada uma função para ele)
+ Uma política do IAM com o nome `CloudWatchSyntheticsPolicy- canary-name-uuid`.
+ Um bucket do S3 com o nome `cw-syn-results-accountID -region`.
+ Alarmes com o nome `Synthetics-Alarm-MyCanaryName`, se você desejar que alarmes sejam criados para o canário.
+ Camadas e funções do Lambda, caso você use um esquema para criar o canário. Esses recursos têm o prefixo `cwsyn-MyCanaryName`.
+ Grupos de logs do CloudWatch Logs com o nome `/aws/lambda/cwsyn-MyCanaryName -randomId`.
# Usar esquemas de canaries
Esta seção fornece detalhes sobre cada um dos esquemas de canaries e as tarefas para as quais cada um é mais adequado. Os esquemas são fornecidos pelos seguintes tipos de canaries:
**Topics**
+ [
## Monitorar pulsação
](#CloudWatch_Synthetics_Canaries_Blueprints_Heartbeat)
+ [
## Canário da API
](#CloudWatch_Synthetics_Canaries_Blueprints_API)
+ [
## Verificador de link quebrado
](#CloudWatch_Synthetics_Canaries_Blueprints_Broken_Links)
+ [
## Esquema de monitoramento visual
](#CloudWatch_Synthetics_Canaries_Blueprints_VisualTesting)
+ [
## Gravador do canário
](#CloudWatch_Synthetics_Canaries_Blueprints_Recorder)
+ [
## Criador de fluxos de trabalho da GUI
](#CloudWatch_Synthetics_Canaries_Blueprints_GUI_Workflow)
+ [
## Esquema de múltiplas verificações
](#CloudWatch_Synthetics_Canaries_Blueprints_Multichecks_Blueprint)
+ [
# Criar um canário com esquema de múltiplas verificações
](CloudWatch_Synthetics_Canaries_MultiCheck_Blueprint.md)
Ao usar um esquema para criar um canário, conforme você preenche os campos no console do CloudWatch, a área **Script editor** (Editor de scripts) da página exibe o canário que você está criando como um script Node.js. Também é possível editar o canário nessa área para personalizá-lo ainda mais.
## Monitorar pulsação
Os scripts de pulsação carregam a URL especificada e armazenam uma captura de tela da página e um arquivo HTTP (arquivo HAR). Eles também armazenam logs de URLs acessados.
É possível usar os arquivos HAR para visualizar dados de performance detalhados sobre as páginas da web. Você pode analisar a lista de solicitações da web e detectar problemas de performance, como tempo de carregamento de um item.
Se o canário usar a versão de runtime `syn-nodejs-puppeteer-3.1` ou posterior, você poderá usar o esquema de monitoramento de pulsação para monitorar várias URLs e ver o status, a duração, as capturas de telas associadas e o motivo da falha de cada URL no resumo de etapas do relatório de execução do canário.
## Canário da API
Canaries de API podem testar as funções básicas de leitura e gravação de uma API REST. REST significa *representational state transfer* (transferência de estado representacional) e é um conjunto de regras que os desenvolvedores seguem ao criar uma API. Uma dessas regras determina que um link para um URL específico deve retornar uma parte dos dados.
O canaries podem trabalhar com qualquer APIs e testar todos os tipos de funcionalidade. Cada canário pode fazer várias chamadas de API.
Em canários que usam a versão de runtime `syn-nodejs-2.2` ou posterior, o esquema do canário da API é compatível com canários de várias etapas que monitoram suas APIs como etapas HTTP. É possível testar várias APIs em um único canário. Cada etapa é uma solicitação separada que pode acessar uma URL diferente, usar cabeçalhos diferentes e usar regras diferentes para definir se os cabeçalhos e os corpos das respostas serão capturados. Não capturarando cabeçalhos e corpo de resposta, você pode impedir que dados sigilosos sejam registrados.
Cada solicitação de um canário da API consiste nas seguintes informações:
+ O *endpoint*, que é o URL solicitado.
+ O *método*, que é o tipo da solicitação enviada para o servidor. APIs REST oferecem suporte a operações GET (leitura), POST (gravação), PUT (atualização), PATCH (atualização) e DELETE (exclusão).
+ Os *cabeçalhos*, que fornecem informações para o cliente e o servidor. Eles são usados para autenticação e para fornecer informações sobre o conteúdo do corpo. Para obter uma lista de cabeçalhos válidos, consulte [Cabeçalhos HTTP](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers).
+ Os *dados* (ou o *corpo*) que contêm informações a serem enviadas para o servidor. Isso é usado somente para solicitações POST, PUT, PATCH ou DELETE.
**nota**
Os esquemas canários da API não são compatíveis com os runtimes do Playwright.
O esquema do canário de API é compatível com os métodos GET e POST. Ao usar esse esquema, é necessário especificar cabeçalhos. Por exemplo, você pode especificar **Authorization** como uma **Chave** e os dados de autorização necessários como o **Valor** para essa chave.
Se você estiver testando uma solicitação POST, especifique também o conteúdo a ser publicado no campo **Dados**.
**Integração com o API Gateway**
O esquema de API é integrado ao Amazon API Gateway. Isso permite selecionar uma API do API Gateway e um estágio da mesma conta e região da AWS como o canário ou carregar um modelo do Swagger do API Gateway para monitoramento de API entre contas e regiões. Então é possível escolher os detalhes restantes no console para criar o canário, em vez de inseri-los do zero. Para obter mais informações sobre o API Gateway, consulte [O que é o Amazon API Gateway?](https://docs.aws.amazon.com/apigateway/latest/developerguide/welcome.html)
**Usar uma API privada**
Você pode criar um canário que use uma API privada no Amazon API Gateway. Para obter mais informações, consulte [Como criar uma API privada no Amazon API Gateway?](https://docs.aws.amazon.com/apigateway/latest/developerguide/apigateway-private-apis.html)
## Verificador de link quebrado
O verificador de links quebrados coleta todos os links dentro da URL que você está testando usando `document.getElementsByTagName('a')`. Ele testa apenas até o número de links especificado, e a URL em si é considerada o primeiro link. Por exemplo, se você quiser verificar todos os links em uma página que contenha cinco links, deverá especificar para o canário seguir seis links.
Os canários que verificam links quebrados criados usando o runtime `syn-nodejs-2.0-beta` ou posterior oferecem suporte aos seguintes recursos adicionais:
+ Fornece um relatório contendo os links verificados, o código de status, o motivo da falha (se houver) e as capturas de tela da página de origem e de destino.
+ Ao visualizar os resultados do canário, é possível filtrar para ver apenas os links quebrados e corrigir o link de acordo com o motivo da falha.
+ Essa versão obtém capturas de tela da página de origem anotada para cada link e destaca a âncora onde o link foi encontrado. Os componentes ocultos não são anotados.
+ É possível configurar essa versão para obter capturas de tela de páginas de origem e de destino, apenas páginas de origem ou apenas páginas de destino.
+ Essa versão corrige um problema na versão anterior em que o script do canário é interrompido após o primeiro link quebrado mesmo quando mais links são extraídos da primeira página.
**nota**
Os esquemas do verificador de links quebrados não são compatíveis com os runtimes do Playwright.
Para atualizar um canário existente com `syn-1.0` para usar o novo runtime, é necessário excluir e recriar o canário. Atualizar um canário existente para o novo runtime não disponibiliza esses recursos.
Um canário do verificador de links quebrados detecta os seguintes tipos de erros de link:
+ 404 Page Not Found (404 Página não encontrada)
+ Invalid Host Name (Nome de host inválido)
+ Bad URL (URL incorreto). Por exemplo, a URL não contém um colchete, tem barras extras ou usa um protocolo incorreto.
+ Invalid HTTP response code (Código de resposta HTTP inválido).
+ O servidor host gera respostas vazias sem conteúdo e sem código de resposta.
+ As solicitações HTTP constantemente atingem o tempo limite durante a execução do canário.
+ O host elimina conexões consistentemente porque ele está configurado incorretamente ou está muito ocupado.
## Esquema de monitoramento visual
O esquema de monitoramento visual inclui código para comparar capturas de tela feitas durante uma execução do canário com capturas de tela feitas durante uma execução do canário de linha de base. Se a discrepância entre as duas capturas de tela estiver além de uma porcentagem limite, o canário falhará. O monitoramento visual é compatível com canaries que executam **syn-puppeteer-node-3.2** e posterior. Atualmente, não é compatível com canários que executam Python e Selenium, ou que usam runtimes do Playwright.
O esquema de monitoramento visual inclui a seguinte linha de código no script do canário do esquema padrão, que permite o monitoramento visual.
```
syntheticsConfiguration.withVisualCompareWithBaseRun(true);
```
A primeira vez que o canário é executado corretamente após essa linha ser adicionada ao script, ele usa as capturas de tela obtidas durante a execução como linha de base para comparação. Após a primeira execução do canário, é possível usar o console do CloudWatch para editar o canário para fazer qualquer um destes procedimentos:
+ Defina a próxima execução do canário como a nova linha de base.
+ Estabeleça limites na captura de tela de linha de base atual para designar as áreas da captura de tela que deverão ser ignoradas durante comparações visuais.
+ Remova uma captura de tela que não será usada para monitoramento visual.
Para obter mais informações sobre como usar o console do CloudWatch para editar um canário, consulte [Editar ou excluir um canário](synthetics_canaries_deletion.md).
Também é possível alterar a execução do canário que é usada como linha de base usando os parâmetros ` nextrun` ou `lastrun` ou especificando um ID de execução do canário na API [UpdateCanary](https://docs.aws.amazon.com/AmazonSynthetics/latest/APIReference/API_UpdateCanary.html).
Ao usar o esquema de monitoramento visual, insira a URL onde deseja que a captura de tela seja feita e especifique um limite de diferença em porcentagem. Após a execução da linha de base, as execuções futuras do canário que detectam uma diferença visual maior do que esse limite desencadeiam uma falha do canário. Após a execução da linha de base, também é possível editar o canário para “traçar” limites na captura de tela da linha de base que deseja ignorar durante o monitoramento visual.
O recurso de monitoramento visual é desenvolvido pelo toolkit de software de código aberto ImageMagick. Para obter mais informações, consulte [ImageMagick](https://imagemagick.org/index.php).
## Gravador do canário
Com o esquema do gravador do canário, é possível usar o CloudWatch Synthetics Recorder para registrar suas ações de clicar e digitar em um site e gerar automaticamente um script Node.js que pode ser usado para criar um canário que segue as mesmas etapas. O CloudWatch Synthetics Recorder é uma extensão do Google Chrome fornecida pela Amazon. O gravador de canários não é compatível com canários que usam o runtime do Playwright.
**Créditos**: o CloudWatch Synthetics Recorder é baseado no [ Headless recorder ](https://github.com/checkly/headless-recorder).
Para obter mais informações, consulte [Usar o CloudWatch Synthetics Recorder para Google Chrome](CloudWatch_Synthetics_Canaries_Recorder.md).
## Criador de fluxos de trabalho da GUI
O esquema criador de fluxos de trabalho da GUI verifica se as ações podem ser executadas em sua página da Web. Por exemplo, se você tiver uma página da Web com um formulário de login, o canário poderá preencher os campos de usuário e senha e enviá-lo para verificar se a página da Web está funcionando corretamente.
Ao usar um esquema para criar esse tipo de canário, especifique as ações a serem executadas pelo canário na página da Web. As ações que podem ser utilizadas são as seguintes:
+ **Clicar**: seleciona o elemento especificado e simula um usuário clicando ou escolhendo o elemento.
Para especificar o elemento em um script Node.js, use `[id=]` ou ` a[class=]`.
Para especificar o elemento em um script Python .js, use `xpath //*[@id=]` ou ` //*[@class=]`.
+ **Verificar seletor**: verifica se o elemento especificado existe na página da Web. Esse teste é útil para verificar se uma ação anterior faz com que os elementos corretos preencham a página.
Para especificar o elemento a ser verificado em um script Node.js, use `[id=]` ou ` a[class=]`.
Para especificar o elemento a ser verificado em um script Python .js, use `xpath //*[@id=]` ou `//*[class=]`.
+ **Verificar texto**: verifica se a string especificada está contida no elemento de destino. Esse teste é útil para verificar se uma ação anterior fez o texto correto ser exibido.
Para especificar o elemento em um script do Node.js, use um formato como ` div[@id=]//h1` porque essa ação usa a função `waitForXPath` no Puppeteer.
Para especificar o elemento em um script Python, use o formato xpath como ` //*[@id=] ` ou //\$1[@class=] porque esta ação usa a função `implicitly_wait` no Selenium.
+ **Texto de entrada**: grava o texto especificado no elemento de destino.
Para especificar o elemento a ser verificado em um script Node.js, use `[id=]` ou ` a[class=]`.
Para especificar o elemento a ser verificado em um script Python .js, use `xpath //*[@id=]` ou `//*[@class=]`.
+ **Clicar com a navegação**: aguarda a página inteira ser carregada depois de escolher o elemento especificado. Isso é mais útil quando é necessário recarregar a página.
Para especificar o elemento em um script Node.js, use `[id=]` ou ` a[class=]`.
Para especificar o elemento em um script Python .js, use `xpath //*[@id=]` ou ` //*[@class=]`.
Por exemplo, o esquema a seguir usa Node.js. Ele clica em **firstButton** no URL especificado, verifica se o seletor esperado com o texto esperado é exibido, insere o nome `Test_Customer` no campo **Nome**, clica no botão **Login** e confirma se o login foi bem-sucedido verificando o texto de **Boas-vindas** na página seguinte.
![\[A página de criação do canário no console, com campos preenchidos para o esquema de fluxo de trabalho da GUI.\]](http://docs.aws.amazon.com/pt_br/AmazonCloudWatch/latest/monitoring/images/canary_create_gui_workflow.PNG)
Os canários de fluxo de trabalho GUI que usam os tempos de execução a seguir também fornecem um resumo das etapas executadas para cada execução do canário. É possível usar as capturas de tela e a mensagem de erro associadas a cada etapa para encontrar a causa raiz da falha.
+ `syn-nodejs-2.0` ou posterior
+ `syn-python-selenium-1.0` ou posterior
## Esquema de múltiplas verificações
O esquema de múltiplas verificações simplifica a criação de canários. Ele reduz custos porque usa uma configuração JSON simples que fornece funcionalidade imediata para a execução de verificações HTTP, DNS, SSL e TCP. Você pode configurar até 10 verificações. Configure cada verificação como uma etapa numerada, executada em sequência, o que permite uma compreensão clara do fluxo canário.
Compatível com esquemas de múltiplas verificações:
+ Solicitações Basic HTTP, solicitações TCP, validação de registros DNS e monitoramento de certificados SSL
+ Métodos de autenticação HTTP, como Basic, API Key, OAuth e Sigv4 integrados ao Secrets Manager
+ Asserções para cada verificação
Para obter mais informações, consulte [Criar um canário](CloudWatch_Synthetics_Canaries_Create.md).
# Criar um canário com esquema de múltiplas verificações
O esquema de múltiplas verificações do Amazon CloudWatch Synthetics ajuda a criar um canário do Synthetics por meio de uma configuração JSON simples. Você pode economizar custos empacotando até 10 tipos diferentes de verificações HTTP/DNS/SSL/TCP feitas em etapas sequenciais. Cada verificação inclui asserções que fornecem uma validação básica em relação ao resultado da verificação.
Os canários de múltiplas verificações são projetados para casos de uso simples que exigem apenas verificações básicas sem usar um navegador sem periféricos/sem interface gráfica. Para casos de uso mais complexos, revise os outros tipos de canários que o Amazon CloudWatch Synthetics oferece.
**Topics**
+ [
## Pré-requisitos
](#CloudWatch_Synthetics_MultiCheck_Prerequisites)
+ [
## Limitações
](#CloudWatch_Synthetics_MultiCheck_Limitations)
+ [
## Estrutura de empacotamento, esquema JSON e definições de configuração
](#CloudWatch_Synthetics_MultiCheck_Packaging)
+ [
## Criar um canário de múltiplas verificações no Console de gerenciamento da AWS
](#CloudWatch_Synthetics_MultiCheck_Console)
+ [
## Criar um canário de múltiplas verificações usando as APIs do AWS Synthetics
](#CloudWatch_Synthetics_MultiCheck_API)
+ [
## Criar um canário de múltiplas verificações no CloudFormation
](#CloudWatch_Synthetics_MultiCheck_CloudFormation)
+ [
## Configuração da autenticação
](#CloudWatch_Synthetics_MultiCheck_Authentication)
+ [
## Solução de problemas
](#CloudWatch_Synthetics_MultiCheck_Troubleshooting)
## Pré-requisitos
+ É necessário usar o syn-nodejs-3.0\$1 para criar um canários de múltiplas verificações
+ Ao usar a configuração do Authentication e do Secrets Manager, você deve garantir que o canário [ExecutionRoleArn](https://docs.aws.amazon.com/AmazonSynthetics/latest/APIReference/API_CreateCanary.html) tenha as permissões de acesso a esses segredos
+ Ao usar o Authentication para Sigv4, você deve garantir que o canário [ExecutionRoleArn](https://docs.aws.amazon.com/AmazonSynthetics/latest/APIReference/API_CreateCanary.html) tenha as permissões de acesso ao perfil correspondente
## Limitações
+ As respostas HTTP não podem ter mais de 1 MB
+ Máximo de 10 variáveis definidas.
+ Ao usar o JSON RFC, o Checks JSON pode ter campos duplicados, porém apenas o último campo sequencial será usado
+ No Console de gerenciamento da AWS, um canário de múltiplas verificações exibirá, por padrão, métricas de etapa de múltiplas verificações para identificar prontamente a disponibilidade de cada verificação. Quando as verificações são removidas, elas podem continuar a ser mostradas no gráfico de disponibilidade até estarem inativas por, pelo menos, 3 horas
## Estrutura de empacotamento, esquema JSON e definições de configuração
A configuração do JSON Checks que será usada para o canário deve será denominada ` blueprint-config.json`. A configuração deve seguir o [esquema](https://github.com/aws-samples/synthetics-canary-local-debugging-sample/tree/main) e as instruções em [Escrever uma configuração JSON para o esquema de múltiplas verificações do Node.js](CloudWatch_Synthetics_WritingCanary_Multichecks.md).
Compacte o `blueprint-config.json` em um arquivo ZIP e forneça-o em um dos seguintes fluxos de trabalho de criação. Quando existe uma configuração `synthetics.json`, ela também é compactada no mesmo arquivo ZIP. O exemplo a seguir é de arquivo denominado `multi-checks.zip`.
```
multi-checks.zip
├── blueprint-config.json
└── synthetics.json
```
## Criar um canário de múltiplas verificações no Console de gerenciamento da AWS
1. Abra o console do Amazon CloudWatch Synthetics.
1. Selecione **Create Canary** (Criar canário).
1. Em **Usar um esquema**, escolha **múltiplas verificações**.
Em **Configurar verificações**, você verá duas guias: **Verificações** e **Configuração do canário**.
1. Selecione a versão do runtime **syn-nodejs-3.0** ou posterior.
1. Siga o procedimento em [Escrever uma configuração JSON para o esquema de múltiplas verificações do Node.js](CloudWatch_Synthetics_WritingCanary_Multichecks.md) para descrever a verificação que você deseja realizar. Como alternativa, o console fornece uma configuração JSON padrão que pode servir de base.
1. Selecione **Create Canary** (Criar canário).
## Criar um canário de múltiplas verificações usando as APIs do AWS Synthetics
Use a API `CreateCanary` e, no parâmetro `Code`, forneça o campo/valor `BlueprintTypes="multi-checks"` em vez de ` Handler`. Quando ambos `BlueprintTypes` e `Handler` são especificados, uma `ValidationException` é exibida. A versão do runtime fornecido deve ser `syn-nodejs-3.0` ou posterior.
```
aws synthetics create-canary \
--name my-multi-check-canary \
--code ZipFile="ZIP_BLOB",BlueprintTypes="multi-checks" \
--runtime-version syn-nodejs-3.0 \
...
// Or if you wanted to use S3 to provide your code.
aws synthetics create-canary \
--name my-multi-check-canary \
--code S3Bucket="my-code-bucket",S3Key="my-zip-code-key",BlueprintTypes="multi-checks" \
...
```
## Criar um canário de múltiplas verificações no CloudFormation
No modelo CloudFormation de um canário de múltiplas verificações, no `Code` parâmetro, forneça o campo/valor `BlueprintTypes="multi-checks"` em vez de ` Handler`. Quando ambos `BlueprintTypes` e `Handler` são especificados, uma `ValidationException` é exibida. A versão do runtime deve ser `syn-nodejs-3.0 or later`.
Um exemplo de modelo:
```
SyntheticsCanary:
Type: 'AWS::Synthetics::Canary'
Properties:
Name: MyCanary
RuntimeVersion: syn-nodejs-3.0
Schedule: {Expression: 'rate(5 minutes)', DurationInSeconds: 3600}
...
Code:
S3Bucket: "my-code-bucket"
S3Key: "my-zip-code-key"
BlueprintTypes: ["multi-checks"]
...
```
## Configuração da autenticação
Quando o canário faz solicitações HTTP a um endpoint autenticado, você pode configurar as etapas do canário do esquema para usar um dos quatro tipos de autenticação: Basic, API Key, OAuth Client Credentials e SigV4. Em vez de configurar você mesmo os cabeçalhos de solicitação, é possível especificar um tipo de autenticação na definição do esquema, e o Synthetics seguirá o tipo de autenticação especificado para preencher os componentes da solicitação HTTP com as informações de autenticação fornecidas.
Você especifica um tipo de autenticação na etapa do esquema com a seção Autenticação. Você especifica o esquema de autenticação que quer usar, as propriedades requeridas para o esquema de autenticação escolhido, e o Synthetics usa as informações fornecidas para criar um cabeçalho de autenticação para a solicitação HTTP.
Como manter segredos (como senhas ou chaves de API) armazenados em texto simples é um problema de segurança, o Synthetics é compatível com a integração com o AWS Secrets Manager. Quando quiser autenticar uma solicitação HTTP em um canário de esquema do Synthetics, consulte o segredo que contém suas informações de autenticação, e o Synthetics recuperará o segredo e o colocará em cache no canário. Essa abordagem fornece segredos ao Synthetics e, ao mesmo tempo, os mantém armazenados com segurança, sem especificá-los em texto simples na configuração do esquema.
Para obter mais informações sobre o AWS Secrets Manager, consulte [O que é AWS Secrets Manager?](https://docs.aws.amazon.com/secretsmanager/latest/userguide/intro.html)
### Autenticação básica
O Synthetics implementa o esquema de autenticação Basic HTTP definido na RFC 7617. O processo funciona da seguinte maneira:
+ Um par nome de usuário e senha é fornecido a partir da configuração do esquema.
+ A senha de usuário é criada concatenando o nome de usuário, um único caractere dois pontos (“:”) e a senha.
+ O par usuário/senha é em uma string codificada em UTF-8, depois convertida em base64.
+ Esse usuário/senha codificado em base64 é fornecido no cabeçalho “Autorização” com o seguinte formato: Autorização: Basic \$1base64-encoded-user-pass\$1
Por exemplo, se o agente do usuário quiser enviar o ID de usuário “Aladin” e a senha “abra-te sésamo”, ele usará o seguinte campo de cabeçalho: Autorização: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==
Exemplo de configuração:
```
"Authentication": {
"type": "BASIC",
"username": MY_USERNAME, // Required
"password": MY_PASSWORD // Required
}
```
### Autenticação de chave de API
Você pode fornecer uma chave de API para autenticar as solicitações HTTP. Quando você usa a autenticação de chave de API, a chave de API fornecida é colocada no cabeçalho HTTP “X-API-Key”. Se você tiver um recurso personalizado que procura cabeçalhos de chave de API em outro cabeçalho, terá a opção de especificar outro nome de cabeçalho no qual o Synthetics deverá colocar a chave de API.
Exemplo de configuração:
```
"Authentication": {
"type": "API_KEY",
"apiKey": S0A1M2P3L4E5, // Required
"header": X-Specific-Header // Optional, defaults to "X-API-Key"
}
```
### Autenticação SigV4
AWS SigV4 (Signature Version 4) é o protocolo de assinatura da AWS para adição de informações de autenticação às solicitações de API da AWS. Para fazer uma solicitação autenticada por SigV4, especifique a região e o serviço aos quais as solicitações são feitas, bem como um ARN (nome do recurso da AWS) do perfil do IAM que você deseja que o canário assuma ao fazer essa solicitação do SigV4. O Synthetics assume o perfil do IAM fornecido no roleArn e usa-o para autenticar a solicitação de API da AWS.
Exemplo de configuração:
```
"Authentication": {
"type": "SIGV4",
"region": us-west-2, // Required
"service": s3, // Required
"roleArn": arn:AWS:iam:12345678912:role/SampleRole // Required
}
```
#### Considerações sobre a autenticação SigV4
Para que o Synthetics assuma o perfil fornecido na seção de autenticação do SigV4, a política de confiança anexada a esse perfil deve ser configurada para permitir que o canário assuma o roleArn fornecido. A entidade principal da AWS em que você precisa confiar é o perfil que o canário assumiu por meio do AWS STS. O formato utilizado é o do ARN ` aws:sts::{account_running_the_canary}:assumed-role//`:
Por exemplo, se você tiver um canário em execução na conta 0123456789012, denominado test-canary, e o perfil que ele assumiu for denominado canary-assume-role, a política de confiança precisará incluir essa instrução para que o canário assuma corretamente o roleArn para a autenticação SigV4:
```
{
"Effect": "Allow",
"Principal": {
"AWS": "arn:AWS:sts::123456789012:assumed-role/test-canary/"
},
"Action": "sts:AssumeRole"
}
```
### Credenciais de cliente OAuth
O Synthetics implementa o tipo de concessão OAuth Client Credentials conforme definido na seção 4.4 da RFC 6479. Se quiser fazer uma solicitação HTTP a um endpoint autenticado com um token ao portador emitido por um endpoint de token OAuth, o Synthetics pode solicitar e gerenciar um token de portador para você. Quando você usa o esquema OAuth, o Synthetics executa as seguintes etapas:
+ Usa o esquema de autenticação Basic com clientId e clientSecret para autenticar uma solicitação à tokenUrl, o endpoint que emite tokens ao portador
+ Se você fornecer os parâmetros opcionais de escopo, público e recurso, eles serão incluídos na solicitação de token
+ Usa o token de acesso retornado pela tokenUrl para autenticar a solicitação HTTP
+ Armazena com segurança o token de atualização retornado da tokenUrl para futuras solicitações de token
Exemplo de configuração:
```
"Authentication": {
"type": "OAUTH_CLIENT_CREDENTIALS",
"tokenUrl": ..., // Required
"clientId": ..., // Required
"clientSecret": ..., // Required
"scope": ..., // Optional
"audience": ..., // Optional
"resource": ..., // Optional
}
```
#### Considerações sobre o OAuth
O Synthetics atualiza os tokens OAuth quando uma resposta 401 ou 407 é retornada.
### AWS Secrets ManagerIntegração do
Para evitar o armazenamento de valores secretos (como senhas ou chaves de API) em texto simples, o Synthetics fornece uma integração com o AWS Secrets Manager. Você pode referenciar um valor secreto inteiro na configuração do esquema com o formato ` ${aws_SECRET:}` ou referenciar uma chave ` ${aws_SECRET::}` específica.
Por exemplo, se você tiver um segredo denominado login/basic-auth-credentials, o armazenamento de um nome de usuário e senha com a seguinte estrutura JSON:
```
{
"username": "Aladdin",
"password": "open sesame"
}
```
Você pode referenciar o nome de usuário e senha na configuração do esquema do seguinte modo, e o Synthetics recuperará o valor do segredo e usará suas chaves para autenticar a solicitação:
```
"Authentication": {
"type": "BASIC",
"username": ${AWS_SECRET:login/basic-auth-credentials:username},
"password": ${AWS_SECRET:login/basic-auth-credentials:password}
}
```
Para permitir que o Synthetics recupere o segredo especificado, o ARN do perfil assumido pelo canário precisa ter as permissões secretsManager:GetSecretValue. Se o segredo for criptografado com uma chave gerenciada pelo cliente em vez da chave gerenciada pela AWS AWS/secretsmanager, o perfil também precisará das permissões kms:Decrypt para essa chave.
Exemplo de permissões:
```
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": "secretsmanager:GetSecretValue",
"Resource": "arn:AWS:secretsmanager:us-east-1:123456789012:secret:secretName-AbCdEf"
},
{
"Effect": "Allow",
"Action": "kms:Decrypt",
"Resource": "arn:AWS:kms:us-east-1:123456789012:key/key-id"
}
]
}
```
## Solução de problemas
### Falhas comuns da solução de problemas
O código subjacente do esquema de múltiplas verificações é escrito em Typescript. Consulte a página de solução de problemas do canário para ver as falhas comuns: [Solução de problemas de um canário com falha](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/CloudWatch_Synthetics_Canaries_Troubleshoot.html).
### Erros de sintaxe de configuração de verificação JSON
Quando houver algum erro de sintaxe relacionado à configuração da verificação JSON do canário, o Console de gerenciamento da AWS apresentará um motivo de falha quando você tentar criar o canário. Se você criar um canário usando uma API ou o CloudFormation, verá a falha quando o canário for executado a primeira vez. Para um canário de múltiplas verificações, é recomendável usar o fluxo de trabalho de atualizações seguras do canário. Para saber mais, consulte [Execução de atualizações seguras para o canário](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/performing-safe-canary-upgrades.html).
### Falhas de rede ou de tempo limite esgotado
Para falhas intermitentes ou consistentes relacionadas a tempos limite esgotados, falhas de conexão de rede (por exemplo, ENOTFOUND, ECONNRESET), considere ativar os logs ` DEBUG` para que a próxima execução forneça mais detalhes sobre por que as verificações estão apresentando falhas. Para isso, forneça a variável de ambiente CW\$1SYNTHETICS\$1LOG\$1LEVEL: “DEBUG”.
Se ainda houver falhas que você não consegue depurar, considere entrar em contato com o AWS Support ou verificar se algum dos outros tipos de canário fornecidos pelo CloudWatch Synthetics é mais adequado ao seu caso de uso.
# Usar o CloudWatch Synthetics Recorder para Google Chrome
A Amazon fornece um CloudWatch Synthetics Recorder para ajudar você a criar canaries com mais facilidade. O gravador é uma extensão do Google Chrome.
O gravador registra suas ações de clicar e digitar em um site e gera automaticamente um script Node.js que pode ser usado para criar um canário que segue as mesmas etapas.
Depois de iniciar a gravação, o CloudWatch Synthetics Recorder detecta suas ações no navegador e as converte em script. É possível pausar e retomar a gravação conforme necessário. Quando você interrompe a gravação, o gravador produz um script Node.js de suas ações, que pode facilmente ser copiado com o botão **Copy to Clipboard** (Copiar para a área de transferência). Em seguida, é ossível usar esse script para criar um canário no CloudWatch Synthetics.
**Créditos**: o CloudWatch Synthetics Recorder é baseado no [ Headless recorder ](https://github.com/checkly/headless-recorder).
## Instalar a extensão do CloudWatch Synthetics Recorder para Google Chrome
Para usar o CloudWatch Synthetics Recorder, você pode começar a criar um canário e escolher o esquema **Canary Recorder** (Gravador do canário). Se você fizer isso quando ainda não tiver baixado o gravador, o console do CloudWatch Synthetics fornecerá um link para baixá-lo.
Se preferir, você pode seguir estas etapas para baixar e instalar o gravador diretamente.
**Para instalar o CloudWatch Synthetics Recorder**
1. Usando o Google Chrome, acesse este site: [https://chrome.google.com/webstore/detail/cloudwatch-synthetics-rec/bhdnlmmgiplmbcdmkkdfplenecpegfno](https://chrome.google.com/webstore/detail/cloudwatch-synthetics-rec/bhdnlmmgiplmbcdmkkdfplenecpegfno)
1. Selecione **Add to Chrome** (Adicionar ao Chrome) e escolha**Add extension** (Adicionar extensão).
## Usar o CloudWatch Synthetics Recorder para Google Chrome
Para usar o CloudWatch Synthetics Recorder para facilitar a criação de um canário, escolha **Create canary** (Criar canário) no console do CloudWatch e escolha **Use a blueprint** (Usar um esquema), **Canary Recorder** (Gravador do canário). Para obter mais informações, consulte [Criar um canário](CloudWatch_Synthetics_Canaries_Create.md).
Se preferor, você pode usar o gravador para gravar etapas sem usá-las imediatamente para criar um canário.
**Para usar o CloudWatch Synthetics Recorder para registrar suas ações em um site**
1. Navegue até a página que você deseja monitorar.
1. Escolha o ícone de extensões do Chrome e escolha **CloudWatch Synthetics Recorder**.
1. Escolha **Start Recording** (Iniciar gravação).
1. Execute as etapas que você deseja registrar. Para pausar a gravação, escolha **Pausar**.
1. Quando terminar de gravar o fluxo de trabalho, selecione **Stop recording** (Interromper a gravação).
1. Selecione **Copy to clipboard** (Copiar para a área de transferência) para copiar o script gerado para a área de transferência. Ou, se quiser recomeçar, escolha **New recording** (Nova gravação).
1. Para criar um canário com o script copiado, é possível colar seu script copiado no editor embutido do esquema do gravador ou salvá-lo em um bucket do Amazon S3 e importá-lo de lá.
1. Se não criar um canário imediatamente, você poderá salvar seu script gravado em um arquivo.
## Limitações conhecidas do CloudWatch Synthetics Recorder
Os CloudWatch Synthetics Recorder atualmente para Google Chrome apresenta as limitações a seguir.
+ Elementos HTML que não têm IDs usarão seletores CSS. Isso pode quebrar canaries, se a estrutura da página da Web for alterada posteriormente. Planejamos fornecer algumas opções de configuração (como usar data-id) sobre isso em uma versão futura do gravador.
+ O gravador não oferece suporte a ações como clique duplo ou copiar/colar e não oferece suporte a combinações de teclas como CMD\$10.
+ Para verificar a presença de um elemento ou texto na página, os usuários deverão adicionar asserções após o script ser gerado. O gravador não é compatível com a verificação de um elemento sem executar qualquer ação nesse elemento. Isso é semelhante às opções “Verify text” (“Verificar texto”) ou “Verify element” (“Verificar elemento”) no criador de fluxo de trabalho do canário. Pretendemos adicionar algumas afirmações de suporte em uma versão futura do gravador.
+ O gravador registra todas as ações na guia onde a gravação é iniciada. Não registra pop-ups (por exemplo, para permitir o rastreamento de localização) ou navegação para páginas diferentes de pop-ups.
# Versões do runtime do Synthetics
Quando você cria ou atualiza um canário, você escolhe uma versão de runtime Synthetics para o canário. Um runtime do Synthetics é uma combinação do código Synthetics que chama seu manipulador de scripts e as camadas do Lambda de dependências agrupadas.
Atualmente, o CloudWatch Synthetics é compatível com runtimes baseados nas linguagens Node.js, Python ou Java. Os frameworks com suporte incluem Puppeteer, Playwright e Selenium.
Recomendamos usar sempre a versão de runtime mais recente para seus canaries, para poder utilizar os últimos recursos e atualizações feitas na biblioteca Synthetics.
**Observe**: sempre que você executar um canário para usar uma nova versão do runtime do Synthetics, todas as funções da biblioteca do Synthetics que seu canário utiliza também serão automaticamente movidas para a mesma versão do Node.js com suporte no runtime do Synthetics.
**Topics**
+ [
# Versões do runtime que usam Java
](CloudWatch_Synthetics_Library_Java.md)
+ [
# Versões de runtime que usam Node.js e Playwright
](CloudWatch_Synthetics_Library_nodejs_playwright.md)
+ [
# Versões de runtime que usam Node.js e Tuppeteer
](CloudWatch_Synthetics_Library_nodejs_puppeteer.md)
+ [
# Versões de runtime usando Python e Selenium Webdriver
](CloudWatch_Synthetics_Library_python_selenium.md)
+ [
# Versões de runtime que usam o Node.js
](CloudWatch_Synthetics_Library_Nodejs.md)
+ [
# Política de suporte a versões de runtimes
](CloudWatch_Synthetics_Runtime_Support_Policy.md)
+ [
# Atualizações de versão de runtimes
](CloudWatch_Synthetics_Runtime_Version_Update.md)
# Versões do runtime que usam Java
A seção apresentada a seguir contém informações sobre as versões do runtime do CloudWatch Synthetics para Java. Nenhum navegador ou framework está incluído neste runtime.
A convenção de nomenclatura para essas versões do runtime é `syn-language -majorversion.minorversion`.
## syn-java-1.0
**Principais dependências**:
+ Runtime do AWS Lambda na versão Java 21
**Recursos**
+ *Integração com o CloudWatch Logs*: você pode consultar e filtrar logs por meio do console do CloudWatch Synthetics. Cada mensagem de log contém um ` canaryRunId` exclusivo, facilitando a busca por logs de uma execução específica de canário.
+ *Métricas*: você pode monitorar a porcentagem de êxito e a duração das execuções do canário por meio das métricas do CloudWatch. Além disso, é possível configurar alarmes para receber notificações quando os canários detectarem problemas.
+ *Artefatos do canário*: cada execução do canário envia um relatório detalhado correspondente à execução e às etapas realizadas, que pode ser acessado por meio do Amazon S3.
+ *Suporte para rastreamentos*: é possível emitir rastreamentos para todas as solicitações realizadas pelo canário por meio do X-Ray. Cada execução do canário está associada a um único ID de rastreamento.
# Versões de runtime que usam Node.js e Playwright
As seções a seguir contêm informações sobre as versões do runtime do CloudWatch Synthetics para Node.js e Playwright. O Playwright é uma biblioteca de automação de código aberto para testes de navegador. Para obter mais informações sobre o Playwright, consulte [https://playwright.dev/](https://playwright.dev)
A convenção de nomenclatura para essas versões do runtime é `syn-language -framework-majorversion. minorversion`.
## syn-nodejs-playwright-6.0
**Importante**
A partir do Synthetics `syn-nodejs-playwright-5.1` e nas versões posteriores, o runtime do Synthetics usa o novo namespace. Migre o script do canário para usar o novo namespace. O namespace legado será descontinuado em uma versão futura.
@amzn/synthetics-playwright → @aws/synthetics-playwright
**Principais dependências**:
+ Runtime Node.js 22.x do AWS Lambda
+ Playwright versão 1.58.2
+ Playwright/versão de teste 1.58.2
+ Chromium versão 145.0.7632.77
+ Firefox versão 146.0.1
**Alterações na versão syn-nodejs-playwright-6.0**
+ Patches de segurança aplicados e versões do Playwright e do navegador atualizadas.
Para saber mais, consulte:
+ [Log de alterações do Playwright ](https://playwright.dev/docs/release-notes)
+ [Referência da API do Playwright](https://playwright.dev/docs/api/class-playwright)
## Versões anteriores de runtime para Node.js e Playwright
As versões anteriores a seguir de runtime para Node.js e Playwright ainda são compatíveis.
### syn-nodejs-playwright-5.1
**Principais dependências**:
+ Runtime Node.js 22.x do AWS Lambda
+ Playwright versão 1.57.0
+ Playwright/versão de teste 1.57.0
+ Chromium versão 143.0.7499.169
+ Firefox versão 142.0.1
**Alterações na versão syn-nodejs-playwright-5.1**
+ Migração do namespace do runtime do Synthetics.
+ A definição de tipo está disponível no [Registro do npm](https://www.npmjs.com/package/@aws/synthetics-playwright). Certifique-se de que a versão do pacote de definição de tipo corresponda à versão do runtime do seu canário.
Para saber mais, consulte:
+ [Log de alterações do Playwright ](https://playwright.dev/docs/release-notes)
+ [Referência da API do Playwright](https://playwright.dev/docs/api/class-playwright)
### syn-nodejs-playwright-5.0
**Principais dependências**:
+ Runtime Node.js 22.x do AWS Lambda
+ Playwright versão 1.57.0
+ Playwright/versão de teste 1.57.0
+ Chromium versão 143.0.7499.4
+ Firefox versão 142.0.1
**Alterações na versão syn-nodejs-playwright-5.0**
+ Patches de segurança aplicados e versões do Playwright e do navegador atualizadas.
Para saber mais, consulte:
+ [Log de alterações do Playwright ](https://playwright.dev/docs/release-notes)
+ [Referência da API do Playwright](https://playwright.dev/docs/api/class-playwright)
### syn-nodejs-playwright-4.0
**Principais dependências**:
+ Runtime Node.js 22.x do AWS Lambda
+ Playwright versão 1.55.0
+ Playwright/versão de teste 1.55.0
+ Chromium versão 140.0.7339.16
+ Firefox versão 141.0
**Alterações na versão syn-nodejs-playwright-4.0**
+ Patches de segurança aplicados e versões do Playwright e do navegador atualizadas.
Para saber mais, consulte:
+ [Log de alterações do Playwright ](https://playwright.dev/docs/release-notes)
+ [Referência da API do Playwright](https://playwright.dev/docs/api/class-playwright)
### syn-nodejs-playwright-3.0
**Principais dependências**:
+ Runtime Node.js 20.x do AWS Lambda
+ Playwright versão 1.53.0
+ Playwright/versão de teste 1.53.0
+ Chromium versão 138.0.7204.168
**Alterações na versão syn-nodejs-playwright-3.0**
+ Suporte para vários navegadores: agora você pode executar seus canários Node.js e Puppeteer no Firefox ou no Chrome
+ Suporte para monitoramento visual
Para saber mais, consulte:
+ [Log de alterações do Playwright ](https://playwright.dev/docs/release-notes)
+ [Referência da API do Playwright](https://playwright.dev/docs/api/class-playwright)
### syn-nodejs-playwright-2.0
**Principais dependências**:
+ Runtime Node.js 20.x do AWS Lambda
+ Playwright versão 1.49.1
+ Playwright/versão de teste 1.49.1
+ Chromium versão 131.0.6778.264
**Alterações na versão syn-nodejs-playwright-2.0**
+ A incompatibilidade entre a duração total e a soma dos tempos de uma determinada solicitação em arquivos HAR foi corrigida.
+ É compatível com simulações para o canário, permitindo execuções ad hoc ou a realização de atualizações seguras para o canário.
Para saber mais, consulte:
+ [Log de alterações do Playwright ](https://playwright.dev/docs/release-notes)
+ [Referência da API do Playwright](https://playwright.dev/docs/api/class-playwright)
### syn-nodejs-playwright-1.0
**Principais dependências**:
+ Runtime Node.js 20.x do AWS Lambda
+ Playwright versão 1.44.1
+ Playwright/versão de teste 1.44.1
+ Chromium versão 126.0.6478.126
**Recursos**:
+ **Compatibilidade com o Playwright**: você pode escrever scripts de canários usando o framework de automação do Playwright. Você pode usar os scripts existentes do Playwright para serem executados como canários e aprimorá-los com recursos de monitoramento da AWS.
+ **Integração com o CloudWatch Logs**: você pode consultar e filtrar logs por meio do console do CloudWatch Synthetics. Cada mensagem de log contém um `canaryRunId` exclusivo, facilitando a busca por logs de uma execução específica de canário.
+ **Métricas e artefatos de canários**: você pode monitorar a taxa de aprovação de execução de canário por meio das métricas do CloudWatch e configurar alarmes para alertar quando os canários detectarem problemas.
+ **Capturas de tela e associação de etapas**: você pode obter capturas de tela usando a funcionalidade nativa do Playwright para visualizar os estágios de um script de canário em cada execução. As capturas de tela são automaticamente associadas às etapas dos canários e são carregadas nos buckets do Amazon S3.
+ **Várias guias**: você pode criar canários que abrem várias guias do navegador e acessar capturas de tela de cada guia. Você pode criar fluxos de trabalho de usuário com várias guias e várias etapas no Synthetics.
# Versões de runtime que usam Node.js e Tuppeteer
A primeira versão de runtime para Node.js e Puppeteer foi nomeada `syn-1.0`. As versões de runtime posteriores têm a convenção de nomenclatura `syn-language -majorversion.minorversion`. Começando com `syn-nodejs-puppeteer-3.0`, a convenção de nomenclatura é `syn- language-framework-majorversion .minorversion`
Um sufixo adicional `-beta` mostra que a versão do runtime está atualmente em uma versão de pré-visualização beta.
As versões de runtime com o mesmo número de versão principal são compatíveis com versões anteriores.
O código do Lambda em um canário é configurado para ter no máximo 1 GB de memória. Cada execução de um canário expirará após um valor de tempo limite configurado. Se nenhum valor de tempo limite for especificado para um canário, o CloudWatch escolherá um valor de tempo limite com base na frequência do canário. Se você configurar um valor de tempo limite, ele não deverá ser inferior a 15 segundos para permitir que o Lambda seja iniciado a frio e que a instrumentação do canário seja inicializada.
## syn-nodejs-puppeteer-15.0
`syn-nodejs-puppeteer-15.0` é o runtime Synthetics mais recente para Node.js e Puppeteer.
**Importante**
A partir do Synthetics `syn-nodejs-puppeteer-13.1` e nas versões posteriores, o runtime do Synthetics usa o novo namespace. Migre o script do canário para usar os novos namespaces. Os namespaces legados serão descontinuados em uma versão futura.
Synthetics → @aws/synthetics-puppeteer
SyntheticsLink → @aws/synthetics-link
SyntheticsLogger → @aws/synthetics-logger
SyntheticsLogHelper → @aws/synthetics-log-helper
BrokenLinkCheckerReport → @aws/synthetics-broken-link-checker-report
**Importante**
O runtime `syn-nodejs-puppeteer-11.0` do Synthetics e as versões posteriores são compatíveis somente com as seguintes substituições de configuração em nível de etapa:
`screenshotOnStepStart`
`screenshotOnStepSuccess`
`screenshotOnStepFailure`
`stepSuccessMetric`
`stepDurationMetric`
`continueOnStepFailure/continueOnHttpStepFailure`
`stepsReport`
Para saber mais, consulte:
+ [Log de alterações do Puppeteer](https://pptr.dev/CHANGELOG#24375-2026-02-19)
+ [Referência da API do Puppeteer](https://github.com/puppeteer/puppeteer/blob/puppeteer-v24.37.5/docs/api/index.md)
**Principais dependências**:
+ Runtime Node.js 22.x do Lambda
+ Puppeteer-core versão 24.37.5
+ Chromium versão 145.0.7632.77
+ Firefox versão 147.0.4
**Alterações na versão syn-nodejs-puppeteer-15.0**
+ Patches de segurança aplicados e versões do Puppeteer e do navegador atualizadas.
+ Foi corrigido o erro em que continueOnHttpStepFailure não estava sendo respeitado, fazendo com que as execuções dos canários fossem marcadas incorretamente como bem-sucedidas, apesar da ocorrência de falhas na etapa HTTP.
## Versões anteriores de runtime para Node.js e Puppeteer
As versões anteriores a seguir de runtime para Node.js e Puppeteer ainda são compatíveis.
### syn-nodejs-puppeteer-14.0
Para saber mais, consulte:
+ [Log de alterações do Puppeteer](https://pptr.dev/CHANGELOG#24340-2025-12-19)
+ [Referência da API do Puppeteer](https://github.com/puppeteer/puppeteer/blob/puppeteer-v24.34.0/docs/api/index.md)
**Principais dependências**:
+ Runtime Node.js 22.x do Lambda
+ Puppeteer-core versão 24.34.0
+ Chromium versão 143.0.7499.169
+ Firefox versão 146.x
**Alterações na versão syn-nodejs-puppeteer-14.0**
+ Patches de segurança aplicados e versões do Puppeteer e do navegador atualizadas.
### syn-nodejs-puppeteer-13.1
`syn-nodejs-puppeteer-13.1` é o runtime Synthetics mais recente para Node.js e Puppeteer.
Para saber mais, consulte:
+ [Log de alterações do Puppeteer](https://pptr.dev/CHANGELOG#24250-2025-10-15)
+ [Referência da API do Puppeteer](https://github.com/puppeteer/puppeteer/blob/puppeteer-v24.2.0/docs/api/index.md)
**Principais dependências**:
+ Runtime Node.js 22.x do Lambda
+ Puppeteer-core versão 24.25.0
+ Chromium versão 142.0.7444.175
+ Firefox versão 145.x
**Alterações na versão syn-nodejs-puppeteer-13.1**
+ Migração do namespace do runtime do Synthetics.
+ As definições de tipo estão disponíveis no Registro do npm. Certifique-se de que a versão do pacote de definição de tipo corresponda à versão do runtime do seu canário.
+ [ @aws/synthetics-puppeteer](https://www.npmjs.com/package/@aws/synthetics-puppeteer)
+ [ @aws/synthetics-link](https://www.npmjs.com/package/@aws/synthetics-link)
+ [ @aws/synthetics-broken-link-checker-report](https://www.npmjs.com/package/@aws/synthetics-broken-link-checker-report)
+ [ @aws/synthetics-log-helper](https://www.npmjs.com/package/@aws/synthetics-log-helper)
+ [ @aws/synthetics-logger](https://www.npmjs.com/package/@aws/synthetics-logger)
### syn-nodejs-puppeteer-13.0
Para saber mais, consulte:
+ [Log de alterações do Puppeteer](https://pptr.dev/CHANGELOG#24250-2025-10-15)
+ [Referência da API do Puppeteer](https://github.com/puppeteer/puppeteer/blob/puppeteer-v24.2.0/docs/api/index.md)
**Principais dependências**:
+ Runtime Node.js 22.x do Lambda
+ Puppeteer-core versão 24.25.0
+ Chromium versão 142.0.7444.175
+ Firefox versão 145.x
**Alterações na versão syn-nodejs-puppeteer-13.0**
+ Patches de segurança aplicados e versões do Puppeteer e do navegador atualizadas.
+ Correção de bug: corrigido um problema intermitente de pane da extensão de runtime causado por acesso simultâneo ao mapa
### syn-nodejs-puppeteer-12.0
Para saber mais, consulte:
+ [Log de alterações do Puppeteer](https://pptr.dev/CHANGELOG#24221-2025-09-23)
+ [Referência da API do Puppeteer](https://github.com/puppeteer/puppeteer/blob/puppeteer-v24.22.1/docs/api/index.md)
**Principais dependências**:
+ Runtime Node.js 22.x do Lambda
+ Puppeteer-core versão 24.22.1
+ Chromium versão 140.0.7339.185
+ Firefox versão 143.0.1
**Alterações na versão syn-nodejs-puppeteer-12.0**
+ Patches de segurança aplicados e versões do Puppeteer e do navegador atualizadas.
+ Correção de bug para ocultação de cabeçalhos restritos: corrigido um problema no qual, em algumas situações, cabeçalhos restritos não eram ocultados em executeHttpaStep(). O comportamento agora é consistente com o Puppeteer 10.0.
+ Correção de bug na configuração includeResponseBody: corrigido um problema no qual a geração de arquivos HAR pode aplicar incorretamente a configuração includeResponseBody em determinadas situações. O HAR agora garante que os corpos das respostas sejam excluídos quando a definição está configurada.
+ Ciclo de vida de captura de solicitações corrigido: corrigido um problema no qual, em algumas situações, o capturador de solicitações HTTP pode causar agregação contínua de solicitações. O registro agora termina corretamente após a execução de cada etapa.
### syn-nodejs-puppeteer-11.0
Para saber mais, consulte:
+ [Log de alterações do Puppeteer](https://pptr.dev/CHANGELOG)
+ [Referência da API do Puppeteer](https://github.com/puppeteer/puppeteer/blob/puppeteer-v24.2.0/docs/api/index.md)
**Principais dependências**:
+ Runtime Node.js 20.x do Lambda
+ Puppeteer-core versão 24.15.0
+ Chromium versão 138.0.7204.168
**Alterações na versão syn-nodejs-puppeteer-11.0**
+ Suporte para vários navegadores: agora você pode executar os canários Node.js Puppeteer no Firefox ou no Chrome
+ Empacotamento simplificado: empacote scripts diretamente na raiz sem usar a estrutura de diretório Node.js/node\$1modules
+ Integração de captura de tela: faça captura de telas usando funções nativas do Puppeteer para visualizar os estágios do script do canário. O Synthetics associa automaticamente as capturas de tela às etapas do canário e as carrega no Amazon S3.
+ Consulta de logs aprimorada: consulte e filtre logs pelo console do CloudWatch Insights. Cada mensagem de log inclui um `canaryRunId` exclusivo para facilitar a pesquisa
+ Suporte ao arquivo de configuração: defina e atualize as configurações do Synthetics usando um arquivo synthetics.json. Essa separação da configuração da lógica do script melhora a manutenção e a reutilização.
+ Suporte para várias guias: crie canários que abrem várias guias do navegador e acesse as capturas de tela de cada guia. Criar fluxos de trabalho de usuário com várias guias e etapas no Synthetics
+ Correções de segurança
+ Correções de bugs de monitoramento visual
+ Suporte adicionado para registro em log JSON estruturado com níveis de log configuráveis: os logs agora são emitidos no formato JSON para facilitar a análise e a consulta no CloudWatch. O nível de log é configurável (por exemplo, DEBUG, INFO, TRACE) por meio de variáveis de ambiente, permitindo que os usuários controlem a verbosidade com base em suas necessidades.
+ Suporte para a sintaxe ES
### syn-nodejs-puppeteer-10.0
Para saber mais, consulte:
+ [Log de alterações do Puppeteer](https://pptr.dev/CHANGELOG)
+ [Referência da API do Puppeteer](https://github.com/puppeteer/puppeteer/blob/puppeteer-v24.2.0/docs/api/index.md)
**Principais dependências**:
+ Runtime Node.js 20.x do Lambda
+ Puppeteer-core versão 24.2.0
+ Chromium versão 131.0.6778.264
**Alterações na versão syn-nodejs-puppeteer-10.0**
+ O problema que causava demora excessiva no fechamento do navegador foi corrigido.
+ É compatível com simulações para o canário, permitindo execuções ad hoc ou a realização de atualizações seguras para o canário.
### syn-nodejs-puppeteer-9.1
**Principais dependências**:
+ Runtime Node.js 20.x do Lambda
+ Puppeteer-core versão 22.12.1
+ Chromium versão 126.0.6478.126
**Alterações no syn-nodejs-puppeteer-9.1**: bugs relacionados a intervalos de datas e solicitações pendentes em arquivos HAR foram corrigidos.
### syn-nodejs-puppeteer-9.0
**Principais dependências**:
+ Runtime Node.js 20.x do Lambda
+ Puppeteer-core versão 22.12.1
+ Chromium versão 126.0.6478.126
**Alterações no syn-nodejs-puppeteer-9.0**: o bug para habilitar recursos de monitoramento visual foi corrigido.
### syn-nodejs-puppeteer-8.0
**Atenção**
Por causa de um bug, o runtime `syn-nodejs-puppeteer-8.0` não é compatível com o monitoramento visual em canários. Atualize para [syn-nodejs-puppeteer-9.0](#CloudWatch_Synthetics_runtimeversion-nodejs-puppeteer-9.0) para obter a correção de bugs do monitoramento visual.
**Importante**
Os runtimes do Node.js 18 e de versões posteriores do Lambda usam o AWS SDK para JavaScript v3. Se precisar migrar um canário de um runtime anterior, siga o [workshop de migração aws-sdk-js-v3](https://github.com/aws-samples/aws-sdk-js-v3-workshop) no GitHub. Para obter mais informações sobre o AWS SDK para a versão 3 do JavaScript, consulte [esta postagem no blog](https://aws.amazon.com/blogs/developer/modular-aws-sdk-for-javascript-is-now-generally-available/).
**Principais dependências**:
+ Runtime Node.js 20.x do Lambda
+ Puppeteer-core versão 22.10.0
+ Chromium versão 125.0.6422.112
**Atualizações no syn-nodejs-puppeteer-8.0**:
+ **Compatibilidade com a autenticação de dois fatores**
+ **Correções de bugs** para situações em que alguns clientes de serviços estavam perdendo dados nas respostas do Node.js SDK V3 foram implementadas.
## Versões de runtimes descontinuados para Node.js e Puppeteer
Os seguintes runtimes para Node.js e Puppeteer foram descontinuados. Para obter informações sobre datas de descontinuação de runtimes, consulte [Datas de descontinuação do runtime do CloudWatch Synthetics](CloudWatch_Synthetics_Runtime_Support_Policy.md#runtime_deprecation_dates).
### syn-nodejs-puppeteer-7.0
**Principais dependências**:
+ Runtime Node.js 18.x do Lambda
+ Puppeteer-core versão 21.9.0
+ Chromium versão 121.0.6167.139
**Tamanho do código**:
O tamanho do código e das dependências que você pode empacotar nesse runtime é de 80 MB.
**Atualizações no syn-nodejs-puppeteer-7.0**:
+ **Versões atualizadas das bibliotecas empacotadas no Puppeteer e no Chromium**: as dependências do Puppeteer e do Chromium foram atualizadas para novas versões.
**Importante**
A mudança do Puppeteer 19.7.0 para o Puppeteer 21.9.0 promove mudanças significativas em relação a testes e filtros. Para obter mais informações, consulte as seções **PRINCIPAIS ALTERAÇÕES** em [puppeteer: v20.0.0](https://github.com/puppeteer/puppeteer/releases/tag/puppeteer-v20.0.0) e [puppeteer-core: v21.0.0](https://github.com/puppeteer/puppeteer/releases/tag/puppeteer-core-v21.0.0).
**Atualização recomendada para o AWS SDK v3**
O runtime do Lambda nodejs18.x não é compatível com o AWS SDK v2. É altamente recomendável migrar para o AWS SDK v3.
### syn-nodejs-puppeteer-6.2
**Principais dependências**:
+ Runtime Node.js 18.x do Lambda
+ Puppeteer-core versão 19.7.0
+ Chromium versão 111.0.5563.146
**Alterações no syn-nodejs-puppeteer-6.2**:
+ **Versões atualizadas das bibliotecas agrupadas no Chromium**
+ **Monitoramento de armazenamento efêmero** — Este runtime adiciona monitoramento de armazenamento efêmero às contas dos clientes.
+ **Correções de bugs**
### syn-nodejs-puppeteer-6.1
**Principais dependências**:
+ Runtime Node.js 18.x do Lambda
+ Puppeteer-core versão 19.7.0
+ Chromium versão 111.0.5563.146
**Atualizações no syn-nodejs-puppeteer-6.1**:
+ **Melhorias na estabilidade**: adicionada uma lógica de repetição automática para lidar com erros intermitentes de execução do Puppeteer.
+ **Upgrades de dependências**: atualiza alguns pacotes de dependências de terceiros.
+ **Canários sem permissões do Amazon S3**: correções de bugs para que os canários que não têm qualquer permissão do Amazon S3 ainda possam ser executados. Esses canários sem permissões do Amazon S3 não poderão carregar capturas de tela ou outros artefatos para o Amazon S3. Para obter mais informações sobre permissões para canários, consulte [Funções e permissões necessárias para canaries](CloudWatch_Synthetics_Canaries_CanaryPermissions.md).
**Importante**
IMPORTANTE: a dependência incluída do AWS SDK para JavaScript v2 será removida e atualizada para uso do AWS SDK para JavaScript v3 em uma versão futura do runtime. Quando isso acontecer, será possível atualizar suas referências de código canário. Como alternativa, é possível continuar referenciando e usando a dependência incluída do AWS SDK para JavaScript v2 adicionando-a como uma dependência ao arquivo zip do código-fonte.
### syn-nodejs-puppeteer-6.0
**Principais dependências**:
+ Runtime Node.js 18.x do Lambda
+ Puppeteer-core versão 19.7.0
+ Chromium versão 111.0.5563.146
**Atualizações no syn-nodejs-puppeteer-6.0**:
+ **Atualização de dependência**: a dependência do Node.js foi atualizada para 18.x.
+ **Suporte ao modo de interceptação**: o suporte ao modo de interceptação cooperativa do Puppeteer foi adicionado à biblioteca de runtime de um canário do Synthetics.
+ **Alteração do comportamento de rastreamento**: o comportamento de rastreamento padrão foi alterado para rastrear somente as solicitações fetch e xhr, e não rastrear as solicitações de recursos. Você pode ativar o rastreamento de solicitações de recursos configurando a opção `traceResourceRequests`.
+ **Métrica de duração refinada**: a métrica ` Duration` agora exclui o tempo de operação que o canário usa para carregar artefatos, fazer capturas de tela e gerar métricas do CloudWatch. Os valores da métrica `Duration` são relatados ao CloudWatch, e você também pode visualizá-los no console do Synthetics.
+ **Correção de erro:** limpa o core dump gerado quando o Chromium trava durante uma execução de canário.
**Importante**
IMPORTANTE: a dependência incluída do AWS SDK para JavaScript v2 será removida e atualizada para uso do AWS SDK para JavaScript v3 em uma versão futura do runtime. Quando isso acontecer, será possível atualizar suas referências de código canário. Como alternativa, é possível continuar referenciando e usando a dependência incluída do AWS SDK para JavaScript v2 adicionando-a como uma dependência ao arquivo zip do código-fonte.
### syn-nodejs-puppeteer-5.2
**Principais dependências**:
+ Runtime Node.js 16.x do Lambda
+ Puppeteer-core versão 19.7.0
+ Chromium versão 111.0.5563.146
**Atualizações no syn-nodejs-puppeteer-5.2**:
+ **Versões atualizadas das bibliotecas agrupadas no Chromium**
+ **Correções de bugs**
### syn-nodejs-puppeteer-5.1
**Principais dependências**:
+ Runtime Node.js 16.x do Lambda
+ Puppeteer-core versão 19.7.0
+ Chromium versão 111.0.5563.146
**Correções de erros no syn-nodejs-puppeteer-5.1**:
+ **Correção de erros**: este runtime corrige um bug no ` syn-nodejs-puppeteer-5.0` em que os arquivos HAR criados pelos canários não tinham cabeçalhos de solicitação.
### syn-nodejs-puppeteer-5.0
**Principais dependências**:
+ Runtime Node.js 16.x do Lambda
+ Puppeteer-core versão 19.7.0
+ Chromium versão 111.0.5563.146
**Atualizações no syn-nodejs-puppeteer-5.0**:
+ **Atualização de dependência**: a versão Puppeteer-core foi atualizada para 19.7.0. A versão do Chromium foi atualizada para 111.0.5563.146.
**Importante**
A nova versão do Puppeteer-core não é totalmente compatível com as versões anteriores do Puppeteer. Algumas das mudanças nesta versão podem fazer com que os canários existentes que usam funções obsoletas do Puppeteer falhem. Para obter mais informações, consulte as alterações mais importantes nos logs de alterações das versões 19.7.0 até 6.0 do Puppeteer Core, nos [Logs de alterações do Puppeteer](https://github.com/puppeteer/puppeteer/releases?q=breaking&expanded=true).
### syn-nodejs-puppeteer-4.0
**Principais dependências**:
+ Runtime Node.js 16.x do Lambda
+ Puppeteer-core versão 5.5.0
+ Chromium versão 92.0.4512
**Atualizações no syn-nodejs-puppeteer-4.0**:
+ **Atualização de dependência**: a dependência do Node.js foi atualizada para 16.x.
### syn-nodejs-puppeteer-3.9
**Importante**
Esta versão de runtime foi defasada em 8 de janeiro de 2024. Para obter mais informações, consulte [Política de suporte a versões de runtimes](CloudWatch_Synthetics_Runtime_Support_Policy.md).
**Principais dependências**:
+ Runtime Node.js 14.x do Lambda
+ Puppeteer-core versão 5.5.0
+ Chromium versão 92.0.4512
**Atualizações no syn-nodejs-puppeteer-3.9**:
+ **Upgrades de dependências**: atualiza alguns pacotes de dependências de terceiros.
### syn-nodejs-puppeteer-3.8
**Importante**
Esta versão de runtime foi defasada em 8 de janeiro de 2024. Para obter mais informações, consulte [Política de suporte a versões de runtimes](CloudWatch_Synthetics_Runtime_Support_Policy.md).
**Principais dependências**:
+ Runtime Node.js 14.x do Lambda
+ Puppeteer-core versão 5.5.0
+ Chromium versão 92.0.4512
**Atualizações no syn-nodejs-puppeteer-3.8**:
+ **Limpeza de perfis**: os perfis do Chromium agora são limpos após cada execução de canário.
**Correções de erros no syn-nodejs-puppeteer-3.8**:
+ **Correções de erros**: antes, os canários de monitoramento visual, às vezes, paravam de funcionar bem após uma execução, sem capturas de tela. Esse problema já foi corrigido.
### syn-nodejs-puppeteer-3.7
**Importante**
Esta versão de runtime foi defasada em 8 de janeiro de 2024. Para obter mais informações, consulte [Política de suporte a versões de runtimes](CloudWatch_Synthetics_Runtime_Support_Policy.md).
**Principais dependências**:
+ Runtime Node.js 14.x do Lambda
+ Puppeteer-core versão 5.5.0
+ Chromium versão 92.0.4512
**Atualizações no syn-nodejs-puppeteer-3.7**:
+ **Aperfeiçoamento de registros em log**: o canário carregará os logs para o Amazon S3 mesmo se o tempo limite expirar ou o canário falhar.
+ **Redução do tamanho da camada do Lambda**: o tamanho da camada do Lambda usada para canários é reduzido em 34%.
**Correções de bugs em syn-nodejs-puppeteer-3.7**:
+ **Correções de erros**: as fontes em japonês, chinês simplificado e chinês tradicional serão renderizadas corretamente.
### syn-nodejs-puppeteer-3.6
**Importante**
Esta versão de runtime foi defasada em 8 de janeiro de 2024. Para obter mais informações, consulte [Política de suporte a versões de runtimes](CloudWatch_Synthetics_Runtime_Support_Policy.md).
**Principais dependências**:
+ Runtime Node.js 14.x do Lambda
+ Puppeteer-core versão 5.5.0
+ Chromium versão 92.0.4512
**Atualizações no syn-nodejs-puppeteer-3.6**:
+ **Carimbos de data/hora mais precisos**: as horas de início e de parada das execuções de canários agora têm precisão de milissegundos.
### syn-nodejs-puppeteer-3.5
**Importante**
Esta versão de runtime foi defasada em 8 de janeiro de 2024. Para obter mais informações, consulte [Política de suporte a versões de runtimes](CloudWatch_Synthetics_Runtime_Support_Policy.md).
**Principais dependências**:
+ Runtime Node.js 14.x do Lambda
+ Puppeteer-core versão 5.5.0
+ Chromium versão 92.0.4512
**Atualizações no syn-nodejs-puppeteer-3.5**:
+ **Dependências atualizadas**: os únicos novos recursos neste runtime são as dependências atualizadas.
### syn-nodejs-puppeteer-3.4
**Importante**
Esta versão do runtime tornou-se obsoleta em 13 de novembro de 2022. Para obter mais informações, consulte [Política de suporte a versões de runtimes](CloudWatch_Synthetics_Runtime_Support_Policy.md).
**Principais dependências**:
+ Runtime Node.js 12.x do Lambda
+ Puppeteer-core versão 5.5.0
+ Chromium versão 88.0.4298.0
**Atualizações no syn-nodejs-puppeteer-3.4**:
+ **Função de manipulador personalizado**: agora você pode usar uma função de manipulador personalizado para seus scripts do canário. Os tempos de execução anteriores exigiam que o ponto de entrada do script incluísse `.handler`.
Você também pode colocar scripts do canário em qualquer pasta e passar o nome da pasta como parte do manipulador. Por exemplo, `MyFolder/MyScriptFile.functionname` pode ser usado como um ponto de entrada.
+ **Informações sobre o arquivo HAR expandido**: agora você pode ver solicitações ruins, pendentes e incompletas nos arquivos HAR produzidos por canaries.
### syn-nodejs-puppeteer-3.3
**Importante**
Esta versão do runtime tornou-se obsoleta em 13 de novembro de 2022. Para obter mais informações, consulte [Política de suporte a versões de runtimes](CloudWatch_Synthetics_Runtime_Support_Policy.md).
**Principais dependências**:
+ Runtime Node.js 12.x do Lambda
+ Puppeteer-core versão 5.5.0
+ Chromium versão 88.0.4298.0
**Atualizações no syn-nodejs-puppeteer-3.3**:
+ **Mais opções para a criptografia de artefatos**: em canários que usam esse runtime ou uma versão posterior, é possível optar por usar uma chave do AWS KMS gerenciada pelo cliente ou uma chave gerenciada pelo Amazon S3 em vez de usar uma chave gerenciada da AWS para criptografar artefatos que o canário armazena no Amazon S3. Para obter mais informações, consulte [Criptografar artefatos do canário](CloudWatch_Synthetics_artifact_encryption.md).
### syn-nodejs-puppeteer-3.2
**Importante**
Esta versão do runtime tornou-se obsoleta em 13 de novembro de 2022. Para obter mais informações, consulte [Política de suporte a versões de runtimes](CloudWatch_Synthetics_Runtime_Support_Policy.md).
**Principais dependências**:
+ Runtime Node.js 12.x do Lambda
+ Puppeteer-core versão 5.5.0
+ Chromium versão 88.0.4298.0
**Atualizações no syn-nodejs-puppeteer-3.2**:
+ **Monitoramento visual com capturas de tela**: canaries que usam esse runtime ou posteriores podem comparar uma captura de tela feita durante uma execução a uma versão de linha de base da mesma captura de tela. Se as capturas de tela forem mais diferentes do que um limite de porcentagem especificado, o canário falhará. Para ter mais informações, consulte [Monitoramento visual](CloudWatch_Synthetics_Canaries_Library_Nodejs.md#CloudWatch_Synthetics_Library_SyntheticsLogger_VisualTesting) ou [Esquema de monitoramento visual](CloudWatch_Synthetics_Canaries_Blueprints.md#CloudWatch_Synthetics_Canaries_Blueprints_VisualTesting).
+ **Novas funções relativas a dados confidenciais**: você pode impedir que dados sigilosos sejam exibidos em logs e relatórios do canário. Para obter mais informações, consulte [SyntheticsLogHelper class](CloudWatch_Synthetics_Canaries_Library_Nodejs.md#CloudWatch_Synthetics_Library_SyntheticsLogHelper).
+ **Função desafada**: a classe ` RequestResponseLogHelper` está defasada em favor de outras opções de configuração. Para obter mais informações, consulte [RequestResponseLogHelper class](CloudWatch_Synthetics_Canaries_Library_Nodejs.md#CloudWatch_Synthetics_Library_RequestResponseLogHelper).
### syn-nodejs-puppeteer-3.1
**Importante**
Esta versão do runtime tornou-se obsoleta em 13 de novembro de 2022. Para obter mais informações, consulte [Política de suporte a versões de runtimes](CloudWatch_Synthetics_Runtime_Support_Policy.md).
**Principais dependências**:
+ Runtime Node.js 12.x do Lambda
+ Puppeteer-core versão 5.5.0
+ Chromium versão 88.0.4298.0
**Atualizações no syn-nodejs-puppeteer-3.1**:
+ **Capacidade de configurar métricas do CloudWatch**: com esse runtime, é possível desabilitar as métricas que não são necessárias. Caso contrário, os canários publicam várias métricas do CloudWatch para cada execução do canário.
+ **Vinculação de captura de tela**: é possível vincular uma captura de tela a uma etapa do canário após a conclusão da etapa. Para fazer isso, faça a captura de tela pelo método **takeScreenshot**, usando o nome da etapa à qual você deseja associar a captura de tela. Por exemplo, convém executar uma etapa, adicionar um tempo de espera e depois fazer a captura de tela.
+ **O esquema do monitor de heartbit pode monitorar várias URLs**: é possível usar o esquema de monitoramento de pulsação no console do CloudWatch para monitorar várias URLs e ver o status, a duração, as capturas de tela associadas e o motivo da falha de cada URL no resumo da etapa do relatório de execução do canário.
### syn-nodejs-puppeteer-3.0
**Importante**
Esta versão do runtime tornou-se obsoleta em 13 de novembro de 2022. Para obter mais informações, consulte [Política de suporte a versões de runtimes](CloudWatch_Synthetics_Runtime_Support_Policy.md).
**Principais dependências**:
+ Runtime Node.js 12.x do Lambda
+ Puppeteer-core versão 5.5.0
+ Chromium versão 88.0.4298.0
**Atualizações no syn-nodejs-puppeteer-3.0**:
+ **Dependências atualizadas**: essa versão usa o Puppeteer versão 5.5.0, Node.js 12.x e Chromium 88.0.4298.0.
+ **Acesso entre regiões**: agora é possível especificar um bucket do S3 em outra região como o bucket onde o canário armazena seus arquivos de log, capturas de tela e arquivos HAR.
+ **Novas funções disponíveis**: essa versão adiciona funções de biblioteca para recuperar o nome do canário e a versão do runtime do Synthetics.
Para obter mais informações, consulte [Classe Synthetics](CloudWatch_Synthetics_Canaries_Library_Nodejs.md#CloudWatch_Synthetics_Library_Synthetics_Class_all).
### syn-nodejs-2.2
Esta seção contém informações sobre a versão de runtime `syn-nodejs-2.2`.
**Importante**
Esta versão de runtime foi defasada em 28 de maio de 2021. Para obter mais informações, consulte [Política de suporte a versões de runtimes](CloudWatch_Synthetics_Runtime_Support_Policy.md).
**Principais dependências**:
+ Runtime Node.js 10.x do Lambda
+ Puppeteer-core versão 3.3.0
+ Chromium versão 83.0.4103.0
**Alterações no syn-nodejs-2.2**:
+ **Monitore seus canários como etapas HTTP**: agora você pode testar várias APIs em um único canário. Cada API é testada como uma etapa HTTP separada, e o CloudWatch Synthetics monitora o status de cada etapa usando métricas de etapas e o relatório de etapas do CloudWatch Synthetics. O CloudWatch Synthetics cria as métricas ` SuccessPercent` e `Duration` para cada etapa HTTP.
Essa funcionalidade é implementada pela função **executeHttpStep(stepName, requestOptions, callback, stepConfig)**. Para obter mais informações, consulte [executeHttpStep(stepName, requestOptions, [callback], [stepConfig])](CloudWatch_Synthetics_Canaries_Library_Nodejs.md#CloudWatch_Synthetics_Library_executeHttpStep).
O esquema do canário da API é atualizado para usar esse novo recurso.
+ **Relatórios de solicitações HTTP**: agora é possível exibir relatórios detalhados de solicitações HTTP que capturam detalhes como cabeçalhos de solicitação/resposta, corpo de resposta, código de status, tempos de erro e performance, tempo de conexão TCP, tempo de handshake TLS, tempo de primeiro byte e tempo de transferência de conteúdo. Todas as solicitações HTTP que usam o módulo HTTP/HTTPS nos bastidores são capturadas aqui. Cabeçalhos e corpo de resposta não são capturados por padrão, mas podem ser habilitados definindo opções de configuração.
+ **Configuração global e no nível da etapa**: é possível definir as configurações do CloudWatch Synthetics no nível global, que são aplicadas a todas as etapas dos canaries. Também é possível substituir essas configurações no nível de etapa aprovando pares de chave-valor de configuração para habilitar ou desabilitar determinadas opções.
Para obter mais informações, consulte [Classe SyntheticsConfiguration](CloudWatch_Synthetics_Canaries_Library_Nodejs.md#CloudWatch_Synthetics_Library_SyntheticsConfiguration).
+ **Continuar na configuração de falha da etapa**: é possível escolher continuar a execução do canário quando uma etapa falhar. Para a função ` executeHttpStep`, isso é ativado por padrão. Você pode definir essa opção uma vez no nível global ou configurá-la de modo diferente por etapa.
### syn-nodejs-2.1
**Importante**
Esta versão de runtime foi defasada em 28 de maio de 2021. Para obter mais informações, consulte [Política de suporte a versões de runtimes](CloudWatch_Synthetics_Runtime_Support_Policy.md).
**Principais dependências**:
+ Runtime Node.js 10.x do Lambda
+ Puppeteer-core versão 3.3.0
+ Chromium versão 83.0.4103.0
**Atualizações no syn-nodejs-2.1**:
+ **Comportamento de tela configurável**: fornece a capacidade de desativar a obtenção de capturas de tela por canaries de interface do usuário. Em canaries que usam versões anteriores dos tempos de execução, os canaries de interface do usuário sempre obtêm capturas de tela antes e depois de cada etapa. Com `syn-nodejs-2.1`, isso é configurável. A desativação de capturas de tela pode reduzir os custos de armazenamento do Amazon S3 e ajudar você a cumprir as normas da HIPAA. Para obter mais informações, consulte [Classe SyntheticsConfiguration](CloudWatch_Synthetics_Canaries_Library_Nodejs.md#CloudWatch_Synthetics_Library_SyntheticsConfiguration).
+ **Personalizar os parâmetros de inicialização do Google Chrome**: agora é possível configurar os argumentos usados quando um canário inicia uma janela do navegador Google Chrome. Para obter mais informações, consulte [launch(options)](CloudWatch_Synthetics_Canaries_Library_Nodejs.md#CloudWatch_Synthetics_Library_LaunchOptions).
Pode haver um pequeno aumento na duração do canário ao usar syn-nodejs-2.0 ou posterior, comparado a versões anteriores dos tempos de execução do canário.
### syn-nodejs-2.0
**Importante**
Esta versão de runtime foi defasada em 28 de maio de 2021. Para obter mais informações, consulte [Política de suporte a versões de runtimes](CloudWatch_Synthetics_Runtime_Support_Policy.md).
**Principais dependências**:
+ Runtime Node.js 10.x do Lambda
+ Puppeteer-core versão 3.3.0
+ Chromium versão 83.0.4103.0
**Atualizações no syn-nodejs-2.0**:
+ **Dependências atualizadas**: essa versão de runtime usa o Puppeteer-core versão 3.3.0 e Chromium versão 83.0.4103.0
+ **Compatibilidade com rastreamento ativo do X-Ray.** Quando um canário tem o rastreamento habilitado, os rastreamentos de X-Ray são enviados a todas as chamadas realizadas pelo canário que usam o navegador, o AWS SDK ou módulos HTTP ou HTTPS. Canários com rastreamento habilitado aparecem no mapa de rastreamento do X-Ray, mesmo quando não enviam solicitações a outros serviços ou aplicações que tenham rastreamento habilitado. Para obter mais informações, consulte [Canaries e rastreamento do X-Ray](CloudWatch_Synthetics_Canaries_tracing.md).
+ **Relatórios do Synthetics**: para cada execução do canário, o CloudWatch Synthetics cria um relatório chamado ` SyntheticsReport-PASSED.json` ou ` SyntheticsReport-FAILED.json` que registra dados como hora de início, hora de término, status e falhas. Ele também registra o status PASSAD/FAILED de cada etapa do script do canário e falhas e capturas de tela obtidas em cada etapa.
+ **Relatório do verificador de link quebrado**: a nova versão do verificador de link quebrado incluído neste runtime cria um relatório contendo os links verificados, o código de status, o motivo da falha (se houver) e as capturas de tela da página de origem e de destino.
+ **Novas métricas do CloudWatch**: o Synthetics publica métricas denominadas `2xx`, `4xx`, `5xx` e `RequestFailed` no namespace `CloudWatchSynthetics`. Essas métricas mostram o número de 200s, 400s, 500s e falhas de solicitação nas execuções do canário. Com essa versão de runtime, essas métricas são relatadas apenas para canaries de interface do usuário e não são relatadas para canaries de API. Também são relatadas para canaries de API que começam com a versão de runtime ` syn-nodejs-puppeteeer-2.2`.
+ **Arquivos HAR classificáveis**: agora é possível classificar seus arquivos HAR por código de status, tamanho da solicitação e duração.
+ **Métricas de carimbo de data/hora**: as métricas do CloudWatch agora são relatadas com base no tempo de invocação do Lambda em vez do horário de término da execução do canário.
**Correções de bugs em syn-nodejs-2.0**:
+ Corrigiu-se o problema em que os erros de carregamento de artefatos do canário não eram relatados. Esses erros são agora apresentados como erros de execução.
+ Corrigiu-se o problema em que solicitações redirecionadas (3xx) eram registradas incorretamente como erros.
+ Corrigiu-se o problema das capturas de tela numeradas a partir de 0. Agora elas devem começar a partir de 1.
+ Corrigiu-se o problema de capturas de tela ilegíveis para fontes chinesas e japonesas.
Pode haver um pequeno aumento na duração do canário ao usar syn-nodejs-2.0 ou posterior, comparado a versões anteriores dos tempos de execução do canário.
### syn-nodejs-2.0-beta
**Importante**
Esta versão de runtime foi defasada em 8 de fevereiro de 2021. Para obter mais informações, consulte [Política de suporte a versões de runtimes](CloudWatch_Synthetics_Runtime_Support_Policy.md).
**Principais dependências**:
+ Runtime Node.js 10.x do Lambda
+ Puppeteer-core versão 3.3.0
+ Chromium versão 83.0.4103.0
**Alterações no syn-nodejs-2.0-beta**:
+ **Dependências atualizadas**: essa versão de runtime usa o Puppeteer-core versão 3.3.0 e Chromium versão 83.0.4103.0
+ **Relatórios do Synthetics**: para cada execução do canário, o CloudWatch Synthetics cria um relatório chamado ` SyntheticsReport-PASSED.json` ou ` SyntheticsReport-FAILED.json` que registra dados como hora de início, hora de término, status e falhas. Ele também registra o status PASSAD/FAILED de cada etapa do script do canário e falhas e capturas de tela obtidas em cada etapa.
+ **Relatório do verificador de link quebrado**: a nova versão do verificador de link quebrado incluído neste runtime cria um relatório contendo os links verificados, o código de status, o motivo da falha (se houver) e as capturas de tela da página de origem e de destino.
+ **Novas métricas do CloudWatch**: o Synthetics publica métricas denominadas `2xx`, `4xx`, `5xx` e `RequestFailed` no namespace `CloudWatchSynthetics`. Essas métricas mostram o número de 200s, 400s, 500s e falhas de solicitação nas execuções do canário. Essas métricas são relatadas apenas para canaries de interface do usuário e não são relatadas para canaries de API.
+ **Arquivos HAR classificáveis**: agora é possível classificar seus arquivos HAR por código de status, tamanho da solicitação e duração.
+ **Métricas de carimbo de data/hora**: as métricas do CloudWatch agora são relatadas com base no tempo de invocação do Lambda em vez do horário de término da execução do canário.
**Correções de bugs no syn-nodejs-2.0-beta**:
+ Corrigiu-se o problema em que os erros de carregamento de artefatos do canário não eram relatados. Esses erros são agora apresentados como erros de execução.
+ Corrigiu-se o problema em que solicitações redirecionadas (3xx) eram registradas incorretamente como erros.
+ Corrigiu-se o problema das capturas de tela numeradas a partir de 0. Agora elas devem começar a partir de 1.
+ Corrigiu-se o problema de capturas de tela ilegíveis para fontes chinesas e japonesas.
### syn-1.0
A primeira versão de runtime do Synthetics é `syn-1.0`.
**Principais dependências**:
+ Runtime Node.js 10.x do Lambda
+ Puppeteer-core versão 1.14.0
+ A versão do Chromium que corresponde ao Puppeteer-core 1.14.0
# Versões de runtime usando Python e Selenium Webdriver
As seções a seguir contêm informações sobre as versões do runtime do CloudWatch Synthetics para Python e Selenium Webdriver. O Selenium é uma ferramenta de automação de navegador de código aberto. Para obter mais informações sobre o Selenium, consulte [www.selenium.dev/](https://www.selenium.dev)
Para recursos e métodos compatíveis com o runtime do Synthetics na estrutura Selenium, consulte [Classes e funções da biblioteca Python e Selenium que se aplicam somente a canários de interface do usuário ](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/CloudWatch_Synthetics_Canaries_Library_Python.html#CloudWatch_Synthetics_Library_Python_UIcanaries) e [Referência da API do Selenium](https://www.selenium.dev/selenium/docs/api/py/api.html).
A convenção de nomenclatura para essas versões do runtime é `syn-language -framework-majorversion. minorversion`.
## syn-python-selenium-10.0
A versão 10.0 é o runtime mais recente do CloudWatch Synthetics para Python e Selenium.
**Principais dependências**:
+ Python 3.11
+ Selenium 4.32.0
+ Chromium versão 145.0.7632.77
**Alterações no syn-python-selenium-10.0 **
+ Patches de segurança aplicados e versões do navegador atualizadas.
Para saber mais, consulte:
+ [Log de alterações do Selenium](https://www.selenium.dev/blog/2025/selenium-4-32-released)
+ [Documentação do Selenium](https://www.selenium.dev/selenium/docs/api/py/api.html)
## Versões anteriores runtimes para Python e Selenium
As versões anteriores a seguir de runtimes para Python e Selenium ainda são compatíveis.
### syn-python-selenium-9.0
**Principais dependências**:
+ Python 3.11
+ Selenium 4.32.0
+ Chromium versão 143.0.7499.169
**Alterações no syn-python-selenium-9.0 **
+ Patches de segurança aplicados e versões do navegador atualizadas.
Para saber mais, consulte:
+ [Log de alterações do Selenium](https://www.selenium.dev/blog/2025/selenium-4-32-released)
+ [Documentação do Selenium](https://www.selenium.dev/selenium/docs/api/py/api.html)
### syn-python-selenium-8.0
A versão 8.0 é o runtime mais recente do CloudWatch Synthetics para Python e Selenium.
**Principais dependências**:
+ Python 3.11
+ Selenium 4.32.0
+ Chromium versão 142.0.7444.175
**Alterações no syn-python-selenium-8.0 **
+ Patches de segurança aplicados e versões do Selenium e do navegador atualizadas.
+ Modificado o nível de log de solicitações da rede HAR com falha de ERROR para INFO.
Para saber mais, consulte:
+ [Log de alterações do Selenium](https://www.selenium.dev/blog/2025/selenium-4-32-released)
+ [Documentação do Selenium](https://www.selenium.dev/selenium/docs/api/py/api.html)
### syn-python-selenium-7.0
**Principais dependências**:
+ Python 3.11
+ Selenium 4.32.0
+ Chromium versão 138.0.7204.168
**Alterações no syn-python-selenium-7.0 **
+ Patches de segurança aplicados e versões do Selenium e do navegador atualizadas.
Para saber mais, consulte:
+ [Log de alterações do Selenium](https://www.selenium.dev/blog/2025/selenium-4-32-released)
+ [Documentação do Selenium](https://www.selenium.dev/selenium/docs/api/py/api.html)
### syn-python-selenium-6.0
**Principais dependências**:
+ Python 3.11
+ Selenium 4.21.0
+ Chromium versão 131.0.6778.264
**Alterações na versão syn-python-selenium-6.0**
+ Atualização do Python 3.9 para o Python 3.11.
Para saber mais, consulte:
+ [Log de alterações do Selenium](https://www.selenium.dev/blog/2024/selenium-4-21-released/)
+ [Documentação do Selenium](https://www.selenium.dev/selenium/docs/api/py/api.html)
### syn-python-selenium-5.1
**Principais dependências**:
+ Python 3.9
+ Selenium 4.21.0
+ Chromium versão 131.0.6778.264
**Alterações na versão syn-python-selenium-5.1**
+ Pequenas atualizações na emissão de métricas.
+ É compatível com simulações para o canário, permitindo execuções ad hoc ou a realização de atualizações seguras para o canário.
### syn-python-selenium-5.0
**Principais dependências**:
+ Python 3.9
+ Selenium 4.21.0
+ Chromium versão 131.0.6778.264
**Alterações no syn-python-selenium-5.0**:
+ Nova tentativa automática se o navegador falhar ao iniciar.
### syn-python-selenium-4.1
**Principais dependências**:
+ Python 3.9
+ Selenium 4.15.1
+ Chromium versão 126.0.6478.126
**Alterações no syn-python-selenium-4.1**:
+ **Soluciona vulnerabilidades de segurança**: este runtime tem uma atualização para solucionar a vulnerabilidade [CVE-2024-39689](https://nvd.nist.gov/vuln/detail/CVE-2024-39689).
### syn-python-selenium-4.0
**Principais dependências**:
+ Python 3.9
+ Selenium 4.15.1
+ Chromium versão 126.0.6478.126
**Alterações no syn-python-selenium-4.0**:
+ **Correções de bugs** no registro em log do analisador HAR.
## Versões descontinuadas de runtimes para Python e Selenium
As versões anteriores a seguir de runtimes para Python e Selenium foram descontinuadas. Para obter informações sobre datas de descontinuação de runtimes, consulte [Datas de descontinuação do runtime do CloudWatch Synthetics](CloudWatch_Synthetics_Runtime_Support_Policy.md#runtime_deprecation_dates).
### syn-python-selenium-3.0
**Principais dependências**:
+ Python 3.8
+ Selenium 4.15.1
+ Chromium versão 121.0.6167.139
**Alterações no syn-python-selenium-3.0**:
+ **Versões atualizadas das bibliotecas empacotadas no Chromium**: a dependência do Chromium está atualizada para uma nova versão.
### syn-python-selenium-2.1
**Principais dependências**:
+ Python 3.8
+ Selenium 4.15.1
+ Chromium versão 111.0.5563.146
**Alterações no syn-python-selenium-2.1**:
+ **Versões atualizadas das bibliotecas empacotadas no Chromium**: as dependências do Chromium e do Selenium foram atualizadas para novas versões.
### syn-python-selenium-2.0
**Principais dependências**:
+ Python 3.8
+ Selenium 4.10.0
+ Chromium versão 111.0.5563.146
**Alterações no syn-python-selenium-2.0**:
+ **Dependências atualizadas**: as dependências do Chromium e do Selenium foram atualizadas para novas versões.
**Correções de erros no syn-python-selenium-2.0**:
+ **Carimbo de data/hora adicionado**: um carimbo de data/hora foi adicionado aos logs do canário.
+ **Reutilização de sessão**: um bug foi corrigido para que os canários agora sejam impedidos de reutilizar a sessão da execução anterior do canário.
### syn-python-selenium-1.3
**Principais dependências**:
+ Python 3.8
+ Selenium 3.141.0
+ Chromium versão 92.0.4512.0
**Alterações no syn-python-selenium-1.3**:
+ **Carimbos de data/hora mais precisos**: as horas de início e de parada das execuções de canários agora têm precisão de milissegundos.
### syn-python-selenium-1.2
**Principais dependências**:
+ Python 3.8
+ Selenium 3.141.0
+ Chromium versão 92.0.4512.0
+ **Dependências atualizadas**: os únicos novos recursos neste runtime são as dependências atualizadas.
### syn-python-selenium-1.1
**Principais dependências**:
+ Python 3.8
+ Selenium 3.141.0
+ Chromium versão 83.0.4103.0
**Recursos**:
+ **Função de manipulador personalizado**: agora você pode usar uma função de manipulador personalizado para seus scripts do canário. Os tempos de execução anteriores exigiam que o ponto de entrada do script incluísse `.handler`.
Você também pode colocar scripts do canário em qualquer pasta e passar o nome da pasta como parte do manipulador. Por exemplo, `MyFolder/MyScriptFile.functionname` pode ser usado como um ponto de entrada.
+ **Opções de configuração para adicionar métricas e configurações de falha de etapas**: essas opções já estavam disponíveis em tempos de execução para canaries Node.js. Para ter mais informações, consulte [Classe SyntheticsConfiguration](CloudWatch_Synthetics_Canaries_Library_Python.md#CloudWatch_Synthetics_Library_SyntheticsConfiguration_Python) .
+ **Argumentos personalizados no Chrome**: agora você pode abrir um navegador no modo anônimo ou passar a configuração do servidor de proxy. Para obter mais informações, consulte [Chrome()](CloudWatch_Synthetics_Canaries_Library_Python.md#CloudWatch_Synthetics_Library_Python_Chrome).
+ **Buckets de artefatos entre regiões**: um canário pode armazenar artefatos em um bucket do Amazon S3 em uma região diferente.
+ **Correções de erros, incluindo uma correção para o problema `index.py`**: com os tempos de execução anteriores, um arquivo canário chamado ` index.py` causava exceções, porque entrava em conflito com o nome do arquivo da biblioteca. Esse problema já foi corrigido.
### syn-python-selenium-1.0
**Principais dependências**:
+ Python 3.8
+ Selenium 3.141.0
+ Chromium versão 83.0.4103.0
**Recursos**:
+ **Suporte ao Selenium**: é possível escrever scripts do canário usando o framework de teste do Selenium. Você pode levar seus scripts Selenium de outro lugar ao CloudWatch Synthetics com alterações mínimas, e eles funcionarão com produtos da AWS.
# Versões de runtime que usam o Node.js
A seção a seguir contém informações sobre as versões do runtime do CloudWatch Synthetics para o Node.js. Nenhum navegador ou framework está incluído neste runtime.
A convenção de nomenclatura para essas versões do runtime é `syn-language -majorversion.minorversion`.
## syn-nodejs-4.1
**Importante**
A partir do Synthetics `syn-nodejs-3.1` e nas versões posteriores, o runtime do Synthetics usa o novo namespace. Migre o script do canário para usar o novo namespace. O namespace legado será descontinuado em uma versão futura.
@amzn/synthetics-core → @aws/synthetics-core
**Principais dependências**:
+ Runtime Node.js 22.x do AWS Lambda
**Alterações no syn-nodejs-4.1**
+ Atualize `fast-xml-parser` para a versão 5.5.7 para corrigir as seguintes CVEs:
+ CVE-2026-25128
+ CVE-2026-25896
+ CVE-2026-26278
+ CVE-2026-27942
+ CVE-2026-33036
## Versões anteriores do runtime para Node.js
Ainda há suporte para as versões anteriores a seguir do runtime para Node.js.
### syn-nodejs-4.0
**Principais dependências**:
+ Runtime Node.js 22.x do AWS Lambda
**Alterações no syn-nodejs-4.0**
+ Patches de segurança aplicados.
### syn-nodejs-3.1
**Importante**
A partir do Synthetics `syn-nodejs-3.1` e nas versões posteriores, o runtime do Synthetics usa o novo namespace. Migre o script do canário para usar o novo namespace. O namespace legado será descontinuado em uma versão futura.
@amzn/synthetics-core → @aws/synthetics-core
**Principais dependências**:
+ Runtime Node.js 20.x do AWS Lambda
**Alterações no syn-nodejs-3.1**
+ Migração do namespace do runtime do Synthetics.
+ A definição de tipo está disponível no [Registro do npm](https://www.npmjs.com/package/@aws/synthetics-core). Certifique-se de que a versão do pacote de definição de tipo corresponda à versão do runtime do seu canário.
### syn-nodejs-3.0
**Principais dependências**:
+ Runtime Node.js 20.x do AWS Lambda
**Alterações no syn-nodejs-3.0**
+ Suporte para esquemas de múltiplas verificações.
# Política de suporte a versões de runtimes
As versões de runtime do Synthetics estão sujeitas a atualizações de manutenção e segurança. Quando qualquer componente de uma versão de runtime não for mais compatível, essa versão de runtime do Synthetics será defasada.
Não é possível criar canários usando versões de runtime defasadas. Canaries que usam tempos de execução defasados continuam funcionando. Você pode parar, iniciar e apagar esses canaries. Você pode atualizar um canário existente que usa versões de runtime defasadas atualizando o canário para usar uma versão de runtime com suporte.
O CloudWatch Synthetics enviará uma notificação por e-mail, caso você tenha canaries que usam tempos de execução programados para serem defasados nos próximos 60 dias. Recomendamos migrar seus canaries para uma versão de runtime compatível para se beneficiar dos novos aprimoramentos de funcionalidade, segurança e performance incluídos em versões mais recentes.
## Datas de descontinuação do runtime do CloudWatch Synthetics
A tabela a seguir lista a data de descontinuação de cada runtime descontinuado do CloudWatch Synthetics.
| Versão do runtime | Data da defasagem |
| --- | --- |
| `syn-python-selenium-5.1` | 3 de fevereiro de 2026 |
| `syn-python-selenium-5.0` | 3 de fevereiro de 2026 |
| `syn-python-selenium-4.1` | 3 de fevereiro de 2026 |
| `syn-python-selenium-4.0` | 3 de fevereiro de 2026 |
| `syn-nodejs-puppeteer-7.0` | 22 de janeiro de 2026 |
| `syn-nodejs-puppeteer-6.2` | 22 de janeiro de 2026 |
| `syn-nodejs-puppeteer-5.2` | 22 de janeiro de 2026 |
| `syn-python-selenium-3.0` | 22 de janeiro de 2026 |
| `syn-python-selenium-2.1` | 22 de janeiro de 2026 |
| `syn-nodejs-puppeteer-6.1` | 8 de março de 2024 |
| `syn-nodejs-puppeteer-6.0` | 8 de março de 2024 |
| `syn-nodejs-puppeteer-5.1` | 8 de março de 2024 |
| `syn-nodejs-puppeteer-5.0` | 8 de março de 2024 |
| `syn-nodejs-puppeteer-4.0` | 8 de março de 2024 |
| `syn-nodejs-puppeteer-3.9` | 8 de janeiro de 2024 |
| `syn-nodejs-puppeteer-3.8` | 8 de janeiro de 2024 |
| `syn-python-selenium-2.0` | 8 de março de 2024 |
| `syn-python-selenium-1.3` | 8 de março de 2024 |
| `syn-python-selenium-1.2` | 8 de março de 2024 |
| `syn-python-selenium-1.1` | 8 de março de 2024 |
| `syn-python-selenium-1.0` | 8 de março de 2024 |
| `syn-nodejs-puppeteer-3.7` | 8 de janeiro de 2024 |
| `syn-nodejs-puppeteer-3.6` | 8 de janeiro de 2024 |
| `syn-nodejs-puppeteer-3.5` | 8 de janeiro de 2024 |
| `syn-nodejs-puppeteer-3.4` | 13 de novembro de 2022 |
| `syn-nodejs-puppeteer-3.3` | 13 de novembro de 2022 |
| `syn-nodejs-puppeteer-3.2` | 13 de novembro de 2022 |
| `syn-nodejs-puppeteer-3.1` | 13 de novembro de 2022 |
| `syn-nodejs-puppeteer-3.0` | 13 de novembro de 2022 |
| `syn-nodejs-2.2` | 28 de maio de 2021 |
| `syn-nodejs-2.1` | 28 de maio de 2021 |
| `syn-nodejs-2.0` | 28 de maio de 2021 |
| `syn-nodejs-2.0-beta` | 8 de fevereiro de 2021 |
| `syn-1.0` | 28 de maio de 2021 |
# Atualizações de versão de runtimes
É possível atualizar uma versão de runtime do canário usando o console do CloudWatch, o AWS CloudFormation, a AWS CLI ou o AWS SDK. Ao usar o console do CloudWatch, você pode atualizar até cinco canários ao mesmo tempo selecionando-os na página de lista de canários e escolhendo **Ações**, **Atualizar runtime**.
É possível verificar a atualização ao realizar um teste prévio antes de aplicar a atualização do runtime. Ao atualizar as versões do runtime, escolha as opções **Iniciar simulação** ou **Validar e salvar em outro momento** no console do CloudWatch para criar uma simulação do canário original em conjunto com quaisquer alterações realizadas na configuração. A simulação realizará a atualização e a execução do canário para validar se a atualização do runtime é segura para o canário. Após verificar seu canário com a nova versão do runtime, é possível atualizar a versão do runtime do canário. Para obter mais informações, consulte [Execução de atualizações seguras para o canário](performing-safe-canary-upgrades.md).
Como alternativa, você pode verificar a atualização ao realizar um clone do canário no console do CloudWatch e atualizar a versão do runtime. Isso cria outro canário, que é um clone de seu canário original. Depois de verificar seu canário com a nova versão do runtime, é possível atualizar a versão do runtime do canário original e excluir o canário clone.
Você também pode atualizar vários canaries usando um script de atualização. Para obter mais informações, consulte [Script de atualização do runtime do canário](#CloudWatch_Synthetics_Canaries_upgrade_script).
Se você atualizar um canário e ele falhar, consulte [Solucionar problemas de um canário](CloudWatch_Synthetics_Canaries_Troubleshoot.md).
## Script de atualização do runtime do canário
Para atualizar um script do canário para uma versão de runtime compatível, use o script a seguir.
```
const AWS = require('aws-sdk');
// You need to configure your AWS credentials and Region.
// https://docs.aws.amazon.com/sdk-for-javascript/v3/developer-guide/setting-credentials-node.html
// https://docs.aws.amazon.com/sdk-for-javascript/v3/developer-guide/setting-region.html
const synthetics = new AWS.Synthetics();
const DEFAULT_OPTIONS = {
/**
* The number of canaries to upgrade during a single run of this script.
*/
count: 10,
/**
* No canaries are upgraded unless force is specified.
*/
force: false
};
/**
* The number of milliseconds to sleep between GetCanary calls when
* verifying that an update succeeded.
*/
const SLEEP_TIME = 5000;
(async () => {
try {
const options = getOptions();
const versions = await getRuntimeVersions();
const canaries = await getAllCanaries();
const upgrades = canaries
.filter(canary => !versions.isLatestVersion(canary.RuntimeVersion))
.map(canary => {
return {
Name: canary.Name,
FromVersion: canary.RuntimeVersion,
ToVersion: versions.getLatestVersion(canary.RuntimeVersion)
};
});
if (options.force) {
const promises = [];
for (const upgrade of upgrades.slice(0, options.count)) {
const promise = upgradeCanary(upgrade);
promises.push(promise);
// Sleep for 100 milliseconds to avoid throttling.
await usleep(100);
}
const succeeded = [];
const failed = [];
for (let i = 0; i < upgrades.slice(0, options.count).length; i++) {
const upgrade = upgrades[i];
const promise = promises[i];
try {
await promise;
console.log(`The update of ${upgrade.Name} succeeded.`);
succeeded.push(upgrade.Name);
} catch (e) {
console.log(`The update of ${upgrade.Name} failed with error: ${e}`);
failed.push({
Name: upgrade.Name,
Reason: e
});
}
}
if (succeeded.length) {
console.group('The following canaries were upgraded successfully.');
for (const name of succeeded) {
console.log(name);
}
console.groupEnd()
} else {
console.log('No canaries were upgraded successfully.');
}
if (failed.length) {
console.group('The following canaries were not upgraded successfully.');
for (const failure of failed) {
console.log('\x1b[31m', `${failure.Name}: ${failure.Reason}`, '\x1b[0m');
}
console.groupEnd();
}
} else {
console.log('Run with --force [--count ] to perform the first upgrades shown. The default value of is 10.')
console.table(upgrades);
}
} catch (e) {
console.error(e);
}
})();
function getOptions() {
const force = getFlag('--force', DEFAULT_OPTIONS.force);
const count = getOption('--count', DEFAULT_OPTIONS.count);
return { force, count };
function getFlag(key, defaultValue) {
return process.argv.includes(key) || defaultValue;
}
function getOption(key, defaultValue) {
const index = process.argv.indexOf(key);
if (index < 0) {
return defaultValue;
}
const value = process.argv[index + 1];
if (typeof value === 'undefined' || value.startsWith('-')) {
throw `The ${key} option requires a value.`;
}
return value;
}
}
function getAllCanaries() {
return new Promise((resolve, reject) => {
const canaries = [];
synthetics.describeCanaries().eachPage((err, data) => {
if (err) {
reject(err);
} else {
if (data === null) {
resolve(canaries);
} else {
canaries.push(...data.Canaries);
}
}
});
});
}
function getRuntimeVersions() {
return new Promise((resolve, reject) => {
const jsVersions = [];
const pythonVersions = [];
synthetics.describeRuntimeVersions().eachPage((err, data) => {
if (err) {
reject(err);
} else {
if (data === null) {
jsVersions.sort((a, b) => a.ReleaseDate - b.ReleaseDate);
pythonVersions.sort((a, b) => a.ReleaseDate - b.ReleaseDate);
resolve({
isLatestVersion(version) {
const latest = this.getLatestVersion(version);
return latest === version;
},
getLatestVersion(version) {
if (jsVersions.some(v => v.VersionName === version)) {
return jsVersions[jsVersions.length - 1].VersionName;
} else if (pythonVersions.some(v => v.VersionName === version)) {
return pythonVersions[pythonVersions.length - 1].VersionName;
} else {
throw Error(`Unknown version ${version}`);
}
}
});
} else {
for (const version of data.RuntimeVersions) {
if (version.VersionName === 'syn-1.0') {
jsVersions.push(version);
} else if (version.VersionName.startsWith('syn-nodejs-2.')) {
jsVersions.push(version);
} else if (version.VersionName.startsWith('syn-nodejs-puppeteer-')) {
jsVersions.push(version);
} else if (version.VersionName.startsWith('syn-python-selenium-')) {
pythonVersions.push(version);
} else {
throw Error(`Unknown version ${version.VersionName}`);
}
}
}
}
});
});
}
async function upgradeCanary(upgrade) {
console.log(`Upgrading canary ${upgrade.Name} from ${upgrade.FromVersion} to ${upgrade.ToVersion}`);
await synthetics.updateCanary({ Name: upgrade.Name, RuntimeVersion: upgrade.ToVersion }).promise();
while (true) {
await usleep(SLEEP_TIME);
console.log(`Getting the state of canary ${upgrade.Name}`);
const response = await synthetics.getCanary({ Name: upgrade.Name }).promise();
const state = response.Canary.Status.State;
console.log(`The state of canary ${upgrade.Name} is ${state}`);
if (state === 'ERROR' || response.Canary.Status.StateReason) {
throw response.Canary.Status.StateReason;
}
if (state !== 'UPDATING') {
return;
}
}
}
function usleep(ms) {
return new Promise(resolve => setTimeout(resolve, ms));
}
```
# Escrever um script do canário
As seções a seguir explicam como escrever um script de canário e como integrar um canário a outros serviços da AWS e com dependências e bibliotecas externas.
**Topics**
+ [
# Elaboração de um script para o canário usando o runtime do Java
](Synthetics_WritingCanary_Java.md)
+ [
# Gravar um script de canário Node.js usando o runtime do Playwright
](Synthetics_WritingCanary_Nodejs_Playwright.md)
+ [
# Gravar um script de canário Node.js usando o runtime do Puppeteer
](CloudWatch_Synthetics_Canaries_WritingCanary_Nodejs_Pup.md)
+ [
# Escrever um script o canário do Python
](CloudWatch_Synthetics_Canaries_WritingCanary_Python.md)
+ [
# Escrever uma configuração JSON para o esquema de múltiplas verificações do Node.js
](CloudWatch_Synthetics_WritingCanary_Multichecks.md)
# Elaboração de um script para o canário usando o runtime do Java
**Topics**
+ [
## Estrutura de um projeto em Java para um canário
](#Synthetics_canary_Java_package)
+ [
## Empacotamento do projeto para um canário
](#Synthetics_canary_Java_package_canary)
+ [
## Nome do manipulador
](#Synthetics_canary_Java_handler)
+ [
## Configurações do CloudWatch Synthetics
](#Synthetics_canary_Java_config)
+ [
## Variáveis de ambiente do CloudWatch Synthetics
](#Synthetics_canary_Java_variables)
## Estrutura de um projeto em Java para um canário
Para criar um canário em Java, você deve desenvolver o código, compilá-lo e implantar os artefatos compilados para o Synthetics. Você pode inicializar um projeto Java Lambda de várias maneiras. Por exemplo, você pode usar uma configuração padrão de projeto em Java no IDE de sua preferência, como IntelliJ IDEA ou Visual Studio Code. Você também pode criar a estrutura de arquivos necessária manualmente.
A estrutura geral de um projeto em Java para o Synthetics é a seguinte:
```
/project-root
└ src
└ main
└ java
└ canarypackage // name of package
| └ ExampleCanary.java // Canary code file
| └ other_supporting_classes
- resources
└ synthetics.json // Synthetics configuration file
└ build.gradle OR pom.xml
```
Você pode usar o Maven ou o Gradle para criar seu projeto e gerenciar dependências.
Na estrutura apresentada acima, a classe `ExampleCanary` atua como ponto de entrada ou manipulador do canário.
**Exemplo de classe de canário em Java**
Este exemplo ilustra um canário que realiza uma solicitação get para um URL armazenado na variável de ambiente *TESTING\$1URL* do Lambda. O canário não usa nenhum dos métodos fornecidos pelo runtime do Synthetics.
```
package canarypackage;
import java.net.HttpURLConnection;
import java.net.URL;
// Handler value: canary.ExampleCanary::canaryCode
public class ExampleCanary {
public void canaryCode() throws Exception{
URL url = new URL(System.getenv("TESTING_URL"));
HttpURLConnection con=(HttpURLConnection)url.openConnection();
con.setRequestMethod("GET");
con.setConnectTimeout(5000);
con.setReadTimeout(5000);
int status=con.getResponseCode();
if(status!=200){
throw new Exception("Failed to load " + url + ", status code: " + status);
}
}
}
```
Recomenda-se fortemente modularizar seus canários usando a função `executeStep` da biblioteca fornecida pelo Synthetics. O canário realiza chamadas `get` para dois URLs distintos, que foram obtidos das variáveis de ambiente URL1 e URL2.
**nota**
Para usar a funcionalidade `executeStep`, o método manipulador para o canário deve receber um parâmetro do tipo Synthetics, conforme mostrado abaixo.
```
package canarypackage;
import com.amazonaws.synthetics.Synthetics;
import java.net.HttpURLConnection;
import java.net.URL;
// Handler value: canary.ExampleCanary::canaryCode
public class ExampleCanary {
public void canaryCode(Synthetics synthetics) throws Exception {
createStep("Step1", synthetics, System.getenv("URL1"));
createStep("Step2", synthetics, System.getenv("URL2"));
return;
}
private void createStep(String stepName, Synthetics synthetics, String url) throws Exception{
synthetics.executeStep(stepName,()->{
URL obj=new URL(url);
HttpURLConnection con=(HttpURLConnection)obj.openConnection();
con.setRequestMethod("GET");
con.setConnectTimeout(5000);
con.setReadTimeout(5000);
int status=con.getResponseCode();
if(status!=200){
throw new Exception("Failed to load" + url + "status code:" + status);
}
return null;
}).get();
}
}
```
## Empacotamento do projeto para um canário
O Synthetics aceita que o código do canário em Java seja fornecido em um arquivo *zip*. O arquivo .zip consiste nos arquivos de classe do código para o canário, nos JARs de dependências de entidades externas e no arquivo de configuração do Synthetics.
A estrutura geral de um arquivo .zip do Java compatível com o Synthetics é a seguinte:
```
example-canary
└ lib
| └ //third party dependency jars
└ java-canary.jar
└ synthetics.json
```
Para gerar esse arquivo .zip usando a estrutura de projeto apresentada acima, é possível usar o Gradle (build.gradle) ou o Maven (pom.xml). Aqui está um exemplo.
Para obter informações sobre as dependências de tempo de compilação ou as interfaces para a biblioteca do Synthetics, consulte o arquivo README em [aws-cloudwatch-synthetics-sdk-java](https://github.com/aws/aws-cloudwatch-synthetics-sdk-java/tree/main).
```
plugins {
id 'java'
}
repositories {
mavenCentral()
}
dependencies {
// Third party dependencies
// example: implementation 'software.amazon.awssdk:s3:2.31.9'
// Declares dependency on Synthetics interfaces for compiling only
// Refer https://github.com/aws/aws-cloudwatch-synthetics-sdk-java for building from source.
compileOnly 'software.amazon.synthetics:aws-cloudwatch-synthetics-sdk-java:1.0.0'}
test {
useJUnitPlatform()
}
// Build the zip to be used as Canary code.
task buildZip(type: Zip) {
archiveFileName.set("example-canary.zip")
destinationDirectory.set(file("$buildDir"))
from processResources
into('lib') {
from configurations.runtimeClasspath
from(tasks.named("jar"))
}
from "src/main/java/resources/synthetics.json"
doLast {
println "Artifact written to: ${archiveFile.get().asFile.absolutePath}"
}
}
java {
toolchain {
languageVersion = JavaLanguageVersion.of(21)
}
}
tasks.named("build") {
dependsOn "buildZip"
}
```
## Nome do manipulador
O nome do manipulador é o ponto de entrada para o canário. Para o runtime em Java, o manipulador deve seguir o formato apresentado a seguir.
```
<>::<>
// for above code: canarypackage.ExampleCanary::canaryCode
```
## Configurações do CloudWatch Synthetics
É possível configurar o comportamento do runtime em Java do Synthetics ao fornecer um arquivo de configuração em JSON opcional chamado `synthetics.json`. Esse arquivo deve ser empacotado no diretório raiz do pacote em .zip. Embora seja opcional, caso o arquivo de configuração não seja fornecido ou alguma chave de configuração esteja ausente, o CloudWatch usará os valores padrão.
Veja abaixo os valores de configuração compatíveis e seus padrões.
```
{
"step": {
"stepSuccessMetric": true,
"stepDurationMetric": true,
"continueOnStepFailure": false,
"stepsReport": true
},
"logging": {
"logRequest": false,
"logResponse": false
},
"httpMetrics": {
"metric_2xx": true,
"metric_4xx": true,
"metric_5xx": true,
"aggregated2xxMetric": true,
"aggregated4xxMetric": true,
"aggregated5xxMetric": true
},
"canaryMetrics": {
"failedCanaryMetric": true,
"aggregatedFailedCanaryMetric": true
}
}
```
**Configurações das etapas**
+ *continueOnStepFailure*: determina se um script deve continuar mesmo após a falha de uma etapa. O padrão é falso.
+ *stepSuccessMetric*: determina se a métrica ` SuccessPercent` de uma etapa deve ser emitida. A métrica `SuccessPercent` para uma etapa será *100* se ela for bem-sucedida na execução do canário, e *0* se falhar. O padrão é *true*.
+ *stepDurationMetric*: determina se a métrica *Duration* de uma etapa será gerada. A métrica *Duration* representa a duração da execução da etapa, em milissegundos. O padrão é *true*.
**Configurações de registros em log**
Aplica-se aos logs gerados pelo CloudWatch Synthetics. Controla o detalhamento dos logs de solicitações e respostas.
+ *logRequest*: especifica se todas as solicitações devem ser registradas em log nos logs do canário. O padrão é falso.
+ *logResponse*: especifica se todas as respostas devem ser registradas em log nos logs do canário. O padrão é falso.
**Configurações de métricas HTTP**
Configurações de métricas relacionadas à contagem de solicitações de rede com diferentes códigos de status HTTP, emitidos pelo CloudWatch Synthetics para o canário.
+ *metric\$12xx*: especifica se a métrica *2xx* (com a dimensão CanaryName) será gerada para esse canário. O padrão é *true*.
+ *metric\$14xx*: especifica se a métrica *4xx* (com a dimensão CanaryName) será gerada para esse canário. O padrão é *true*.
+ *metric\$15xx*: especifica se a métrica *5xx* (com a dimensão CanaryName) será gerada para esse canário. O padrão é *true*.
+ *aggregated2xxMetric*: especifica se a métrica *2xx* (sem a dimensão CanaryName) será gerada para esse canário. O padrão é *true*.
+ *aggregated4xxMetric*: especifica se a métrica *4xx* (sem a dimensão CanaryName) será gerada para esse canário. O padrão é *true*.
+ *aggregated5xxMetric*: especifica se a métrica *5xx* (sem a dimensão CanaryName) será gerada para esse canário. O padrão é *true*.
**Configurações de métricas do canário**
Configurações de outras métricas emitidas pelo CloudWatch Synthetics.
+ *failedCanaryMetric* do Analisador de Acesso à Rede: especifica se a métrica *Failed* (com a dimensão CanaryName) será gerada para esse canário. O padrão é *true*.
+ *aggregatedFailedCanaryMetric*: especifica se a métrica *Failed* (sem a dimensão CanaryName) deve ser emitida para este canário. O padrão é *true*.
## Variáveis de ambiente do CloudWatch Synthetics
Você pode configurar o nível e o formato de log ao usar variáveis de ambiente.
**Formato do log**
O runtime em Java do CloudWatch Synthetics cria logs no CloudWatch para cada execução do canário. Os logs são gravados no formato JSON para facilitar a consulta. Opcionalmente, é possível alterar o formato do log para *TEXT*.
+ *Nome da variável de ambiente*: CW\$1SYNTHETICS\$1LOG\$1FORMAT
+ *Valores com suporte*: JSON e TEXT
+ *Padrão*: JSON
**Níveis de logs**
+ *Nome da variável de ambiente*: CW\$1SYNTHETICS\$1LOG\$1LEVEL
+ *Valores com suporte*: TRACE, DEBUG, INFO, WARN, ERROR e FATAL
+ *Padrão*: INFO
Além das variáveis de ambiente mencionadas acima, existe uma variável de ambiente padrão adicionada para o runtime em Java, chamada `AWS_LAMBDA-EXEC_WRAPPER`, que deve ser configurada na sua função com o valor `/opt/synthetics-otel-instrument`. Essa variável de ambiente modifica o comportamento de inicialização da função para telemetria. Caso essa variável de ambiente já exista, assegure-se de que esteja configurada com o valor necessário.
# Gravar um script de canário Node.js usando o runtime do Playwright
**Topics**
+ [
## Empacotar arquivos de canário Node.js para o runtime do Playwright
](#Synthetics_canary_Nodejs_Playwright_package)
+ [
## Alterar um script existente do Playwright para ser usado como um canário do Synthetics
](#CloudWatch_Synthetics_canary_edit_Playwright_script)
+ [
## Configurações do CloudWatch Synthetics
](#Synthetics_canary_configure_Playwright_script)
## Empacotar arquivos de canário Node.js para o runtime do Playwright
O script do canário compreende um arquivo `.js` (sintaxe CommonJS) ou `.mjs` (sintaxe ES) contendo o código do manipulador do Synthetics, em conjunto com quaisquer pacotes e módulos adicionais dos quais o código dependa. Os scripts criados no formato ES (ECMAScript) devem usar .mjs como extensão ou incluir um arquivo package.json com o conjunto de campos “type”: “module”. Ao contrário de outros runtimes, como o Node.js Puppeteer, você não precisa salvar os scripts em uma estrutura de pastas específica. Você pode empacotar os scripts diretamente. Use seu utilitário `zip` preferencial para criar um arquivo `.zip` com o arquivo manipulador na raiz. Se o script do canário depender de pacotes ou módulos adicionais que não estejam inclusos no runtime do Synthetics, é possível adicionar essas dependências ao arquivo `.zip`. Para fazer isso, você pode instalar as bibliotecas necessárias para a função no diretório `node_modules` executando o comando `npm install`. Os comandos de exemplo da CLI a seguir criam um arquivo `.zip` denominado `my_deployment_package.zip` contendo o arquivo `index.js` ou `index.mjs` (manipulador do Synthetics) e suas dependências. No exemplo, você instala as dependências usando o manipulador de pacotes `npm`.
```
~/my_function
├── index.mjs
├── synthetics.json
├── myhelper-util.mjs
└── node_modules
├── mydependency
```
Crie um arquivo `.zip` que contenha o conteúdo da pasta do seu projeto na raiz. Use a opção `r` (recursiva), conforme mostrado no exemplo a seguir, para garantir que `zip` compacte as subpastas.
```
zip -r my_deployment_package.zip .
```
Adicione um arquivo de configuração do Synthetics para configurar o comportamento do CloudWatch Synthetics. Você pode criar um arquivo `synthetics.json` e salvá-lo no mesmo caminho do seu ponto de entrada ou arquivo manipulador.
Opcionalmente, você também pode armazenar o arquivo de ponto de entrada em uma estrutura de pastas de sua escolha. No entanto, certifique-se de que o caminho da pasta esteja especificado no nome do manipulador.
**Nome do manipulador**
Defina o ponto de entrada do script do canário (manipulador) como ` myCanaryFilename.functionName` para corresponder ao nome do arquivo do ponto de entrada do script. Opcionalmente, você também pode armazenar o canário em uma pasta separada, como ` myFolder/my_canary_filename.mjs`. Se você armazenar em uma pasta separada, especifique esse caminho no ponto de entrada do script, como ` myFolder/my_canary_filename.functionName`.
## Alterar um script existente do Playwright para ser usado como um canário do Synthetics
Você pode editar um script existente do Node.js e Playwright para ser usado como canário. Para obter mais informações sobre o Playwright, consulte a documentação da [biblioteca do Playwright](https://playwright.dev/docs/api/class-playwright).
Você pode usar o script do Playwright a seguir, que está salvo no arquivo ` exampleCanary.mjs`.
```
import { chromium } from 'playwright';
import { expect } from '@playwright/test';
const browser = await chromium.launch();
const page = await browser.newPage();
await page.goto('https://example.com', {timeout: 30000});
await page.screenshot({path: 'example-home.png'});
const title = await page.title();
expect(title).toEqual("Example Domain");
await browser.close();
```
Converta o script executando as seguintes etapas:
1. Crie e exporte uma função `handler`. O manipulador é a função de ponto de entrada para o script. Você pode escolher qualquer nome para a função do manipulador, mas a função usada no script deve ser a mesma do manipulador do canário. Se o nome do script for `exampleCanary.mjs`, e o nome da função do manipulador for `myhandler`, o manipulador do canário será denominado `exampleCanary.myhandler`. No exemplo a seguir, o nome da função do manipulador é `handler`.
```
exports.handler = async () => {
// Your script here
};
```
1. Importe o `Synthetics Playwright module` como uma dependência.
```
import { synthetics } from '@aws/synthetics-playwright';
```
1. Inicie um navegador usando a função `Launch` do Synthetics.
```
const browser = await synthetics.launch();
```
1. Crie uma página do Playwright usando a função `newPage` do Synthetics.
```
const page = await synthetics.newPage();
```
O script agora está pronto para ser executado como um canário do Synthetics. Veja abaixo o script atualizado:
**Atualizado o script no formato ES6**
O arquivo de script salvo com uma extensão `.mjs`.
```
import { synthetics } from '@aws/synthetics-playwright';
import { expect } from '@playwright/test';
export const handler = async (event, context) => {
try {
// Launch a browser
const browser = await synthetics.launch();
// Create a new page
const page = await synthetics.newPage(browser);
// Navigate to a website
await page.goto('https://www.example.com', {timeout: 30000});
// Take screenshot
await page.screenshot({ path: '/tmp/example.png' });
// Verify the page title
const title = await page.title();
expect(title).toEqual("Example Domain");
} finally {
// Ensure browser is closed
await synthetics.close();
}
};
```
**Script atualizado no formato CommonJS**
O arquivo de script salvo com uma extensão `.js`.
```
const { synthetics } = require('@aws/synthetics-playwright');
const { expect } = require('@playwright/test');
exports.handler = async (event) => {
try {
const browser = await synthetics.launch();
const page = await synthetics.newPage(browser);
await page.goto('https://www.example.com', {timeout: 30000});
await page.screenshot({ path: '/tmp/example.png' });
const title = await page.title();
expect(title).toEqual("Example Domain");
} finally {
await synthetics.close();
}
};
```
## Configurações do CloudWatch Synthetics
Você pode configurar o comportamento do runtime do Synthetics Playwright fornecendo um arquivo de configuração JSON opcional denominado `synthetics.json`. Esse arquivo deve ser empacotado no mesmo local do arquivo do manipulador. Embora um arquivo de configuração seja opcional, se você não fornecer um arquivo de configuração, ou se não houver uma chave de configuração, o CloudWatch assumirá os padrões.
**Empacotar o arquivo de configuração**
Veja abaixo os valores de configuração compatíveis e seus padrões.
```
{
"step": {
"screenshotOnStepStart": false,
"screenshotOnStepSuccess": false,
"screenshotOnStepFailure": false,
"stepSuccessMetric": true,
"stepDurationMetric": true,
"continueOnStepFailure": true,
"stepsReport": true
},
"report": {
"includeRequestHeaders": true,
"includeResponseHeaders": true,
"includeUrlPassword": false,
"includeRequestBody": true,
"includeResponseBody": true,
"restrictedHeaders": ['x-amz-security-token', 'Authorization'], // Value of these headers is redacted from logs and reports
"restrictedUrlParameters": ['Session', 'SigninToken'] // Values of these url parameters are redacted from logs and reports
},
"logging": {
"logRequest": false,
"logResponse": false,
"logResponseBody": false,
"logRequestBody": false,
"logRequestHeaders": false,
"logResponseHeaders": false
},
"httpMetrics": {
"metric_2xx": true,
"metric_4xx": true,
"metric_5xx": true,
"failedRequestsMetric": true,
"aggregatedFailedRequestsMetric": true,
"aggregated2xxMetric": true,
"aggregated4xxMetric": true,
"aggregated5xxMetric": true
},
"canaryMetrics": {
"failedCanaryMetric": true,
"aggregatedFailedCanaryMetric": true
},
"userAgent": "",
"har": true
}
```
**Configurações das etapas**
+ `screenshotOnStepStart`: determina se o Synthetics deve obter uma captura de tela antes do início da etapa. O padrão é `true`.
+ `screenshotOnStepSuccess`: determina se o Synthetics deve obter uma captura de tela após a conclusão de uma etapa. O padrão é `true`.
+ `screenshotOnStepFailure`: determina se o Synthetics deve obter uma captura de tela após uma etapa falhar. O padrão é `true`.
+ `continueOnStepFailure`: determina se um script deve continuar mesmo após uma etapa falhar. O padrão é `false`.
+ `stepSuccessMetric`: determina se a métrica ` SuccessPercent` de uma etapa é emitida. A métrica `SuccessPercent` de uma etapa será `100` para a execução do canário se a etapa tiver êxito, e `0` se a etapa falhar. O padrão é `true`.
+ `stepDurationMetric`: determina se a métrica `Duration` de uma etapa é emitida. A métrica `Duration` é emitida como a duração, em milissegundos, da execução da etapa. O padrão é `true`.
**Configurações de relatórios**
Inclui todos os relatórios gerados pelo CloudWatch Synthetics, como um arquivo HAR e um relatório de etapas do Synthetics. Os campos `restrictedHeaders` e `restrictedUrlParameters` de ocultação de dados sigilosos também se aplicam aos logs gerados pelo Synthetics.
+ `includeRequestHeaders`: se deve incluir ou não cabeçalhos de solicitação no relatório. O padrão é `false`.
+ `includeResponseHeaders`: se deve incluir ou não cabeçalhos de resposta no relatório. O padrão é `false`.
+ `includeUrlPassword`: se deve ou não incluir uma senha que apareça no URL. Por padrão, as senhas que aparecem em URLs são ocultadas de logs e relatórios, para evitar a divulgação de dados sigilosos. O padrão é `false` .
+ `includeRequestBody`: se deve incluir ou não o corpo da solicitação no relatório. O padrão é `false`.
+ `includeResponseBody`: se deve incluir ou não o corpo da resposta no relatório. O padrão é `false`.
+ `restrictedHeaders`: uma lista de valores de cabeçalho a serem ignorados, se os cabeçalhos forem incluídos. Isso se aplica aos cabeçalhos de solicitação e de resposta. Por exemplo, você pode ocultar suas credenciais passando `includeRequestHeaders` como true e `restrictedHeaders` como `['Authorization']`.
+ `restrictedUrlParameters`: uma lista de parâmetros de consulta ou caminho de URL a serem ocultados. Aplica-se a URLs que aparecem em logs, relatórios e erros. O parâmetro faz distinção entre maiúsculas e minúsculas. É possível passar um asterisco (`*`) como um valor para ocultar todos os valores de parâmetros de consulta e caminho de URL. O padrão é uma matriz vazia.
+ `har`: determina se um arquivo HTTP (HAR) deve ser gerado. O padrão é `true`.
Veja abaixo um exemplo de um arquivo de configurações de relatório.
```
"includeRequestHeaders": true,
"includeResponseHeaders": true,
"includeUrlPassword": false,
"includeRequestBody": true,
"includeResponseBody": true,
"restrictedHeaders": ['x-amz-security-token', 'Authorization'], // Value of these headers is redacted from logs and reports
"restrictedUrlParameters": ['Session', 'SigninToken'] // Values of these URL parameters are redacted from logs and reports
```
**Configurações de registros em log**
Aplica-se aos logs gerados pelo CloudWatch Synthetics. Controla o detalhamento dos logs de solicitações e respostas.
+ `logRequest`: se cada solicitação em logs do canário será registrada ou não. Para canaries de interface do usuário, isso registra cada solicitação enviada pelo navegador. O padrão é ` false`.
+ `logResponse`: se cada resposta em logs do canário será registrada ou não. Para canaries de interface do usuário, registra todas as respostas recebidas pelo navegador. O padrão é ` false`.
+ `logRequestBody`: se os corpos da solicitação serão registrados ou não junto com as solicitações em logs do canário. Essa configuração se aplicará somente se `logRequest` for true. O padrão é `false`.
+ `logResponseBody`: se os corpos da resposta serão registrados ou não junto com as solicitações em logs do canário. Essa configuração se aplicará somente se `logResponse` for true. O padrão é `false`.
+ `logRequestHeaders`: se os cabeçalhos da solicitação serão registrados ou não junto com as solicitações em logs do canário. Essa configuração se aplicará somente se ` logRequest` for true. O padrão é `false`.
+ `logResponseHeaders`: se os cabeçalhos da resposta serão registrados ou não junto com as respostas em logs do canário. Essa configuração se aplicará somente se ` logResponse` for true. O padrão é `false`.
**Configurações de métricas HTTP**
Configurações de métricas relacionadas à contagem de solicitações de rede com diferentes códigos de status HTTP, emitidos pelo CloudWatch Synthetics para o canário.
+ `metric_2xx`: se deve ou não emitir a métrica `2xx` (com a dimensão `CanaryName`) para o canário. O padrão é ` true`.
+ `metric_4xx`: se deve ou não emitir a métrica `4xx` (com a dimensão `CanaryName`) para o canário. O padrão é ` true`.
+ `metric_5xx`: se deve ou não emitir a métrica `5xx` (com a dimensão `CanaryName`) para o canário. O padrão é ` true`.
+ `failedRequestsMetric`: se deve ou não emitir a métrica ` failedRequests` (com a dimensão `CanaryName`) para o canário. O padrão é `true`.
+ `aggregatedFailedRequestsMetric`: se deve ou não emitir a métrica ` failedRequests` (sem a dimensão `CanaryName`) para o canário. O padrão é `true`.
+ `aggregated2xxMetric`: se deve ou não emitir a métrica `2xx` (sem a dimensão `CanaryName`) para o canário. O padrão é `true`.
+ `aggregated4xxMetric`: se deve ou não emitir a métrica `4xx` (sem a dimensão `CanaryName`) para o canário. O padrão é `true`.
+ `aggregated5xxMetric`: se deve ou não emitir a métrica `5xx` (sem a dimensão `CanaryName`) para o canário. O padrão é `true`.
**Configurações de métricas do canário**
Configurações de outras métricas emitidas pelo CloudWatch Synthetics.
+ `failedCanaryMetric`: se deve ou não emitir a métrica `Failed` (com a dimensão `CanaryName`) para o canário. O padrão é ` true`.
+ `aggregatedFailedCanaryMetric`: se deve ou não emitir a métrica ` Failed` (sem a dimensão `CanaryName`) para o canário. O padrão é `true`.
**Outras configurações**
+ `userAgent`: uma string para anexar ao agente do usuário. O agente do usuário é uma string incluída no cabeçalho da solicitação que identifica seu navegador nos sites que você visita ao usar o navegador sem cabeçalho. O CloudWatch Synthetics adiciona automaticamente `CloudWatchSynthetics/canary-arn to the user agent`. A configuração especificada é anexada ao agente de usuário gerado. O valor do agente de usuário padrão a ser anexado é uma string vazia (`""`).
### Variáveis de ambiente do CloudWatch Synthetics
Configure o formato e o nível do registro em log usando variáveis de ambiente.
**Formato do log**
O runtime do CloudWatch Synthetics Playwright cria logs do CloudWatch para cada execução de canário. Os logs são gravados no formato JSON para facilitar a consulta. Opcionalmente, você pode alterar o formato do log para `TEXT`.
+ `Environment variable name`: CW\$1SYNTHETICS\$1LOG\$1FORMAT
+ `Supported values`: JSON, TEXT
+ `Default`: JSON
**Níveis de logs**
Embora a habilitação do modo `Debug` aumente o detalhamento, ele pode ser útil para solucionar problemas.
+ `Environment variable name`: CW\$1SYNTHETICS\$1LOG\$1LEVEL
+ `Supported values`: TRACE, DEBUG, INFO, WARN, ERROR, FATAL
+ `Default`: INFO
# Gravar um script de canário Node.js usando o runtime do Puppeteer
**Topics**
+ [
## Criar um canário do CloudWatch Synthetics do zero
](#CloudWatch_Synthetics_Canaries_write_from_scratch)
+ [
## Empacotamento dos arquivos do canário para Node.js
](#CloudWatch_Synthetics_Canaries_package)
+ [
## Alterar um script existente do Puppeteer para ser usado como canário do Synthetics
](#CloudWatch_Synthetics_Canaries_modify_puppeteer_script)
+ [
## Variáveis de ambiente
](#CloudWatch_Synthetics_Environment_Variables)
+ [
## Integrar o canário a outros produtos da AWS
](#CloudWatch_Synthetics_Canaries_AWS_integrate)
+ [
## Forçar seu canário a usar um endereço IP estático
](#CloudWatch_Synthetics_Canaries_staticIP)
## Criar um canário do CloudWatch Synthetics do zero
Veja a seguir um exemplo de script do canário mínimo do Synthetics. Esse script é executado com êxito e retorna uma string. Para ver como é um canário com falha, altere `let fail = false;` para `let fail = true;`.
É necessário definir uma função de ponto de entrada para o script do canário. Para ver como os arquivos são carregados no local do Amazon S3 especificado como o `ArtifactS3Location` do canário, crie esses arquivos na pasta `/tmp`. Todos os artefatos do canário devem ser armazenados em `/tmp`, pois é o único diretório gravável. Certifique-se de que o caminho da captura de tela esteja definido como `/tmp` para todas as capturas de tela ou outros arquivos criados pelo script. O Synthetics faz upload automático dos arquivos em ` /tmp` para um bucket do S3.
```
/tmp/
```
Após a execução do script, o status de sucesso/falha e as métricas de duração são publicados no CloudWatch, e os arquivos em `/tmp` são carregados em um bucket do S3.
```
const basicCustomEntryPoint = async function () {
// Insert your code here
// Perform multi-step pass/fail check
// Log decisions made and results to /tmp
// Be sure to wait for all your code paths to complete
// before returning control back to Synthetics.
// In that way, your canary will not finish and report success
// before your code has finished executing
// Throw to fail, return to succeed
let fail = false;
if (fail) {
throw "Failed basicCanary check.";
}
return "Successfully completed basicCanary checks.";
};
exports.handler = async () => {
return await basicCustomEntryPoint();
};
```
Depois, expandiremos o script para usar o registro em log do Synthetics e fazer uma chamada usando o AWS SDK. Para fins de demonstração, esse script criará um cliente do Amazon DynamoDB e fará uma chamada para a API listTables do DynamoDB. Ele registra a resposta à solicitação e os logs são aprovados ou falham dependendo se a solicitação foi bem-sucedida.
```
const log = require('@aws/synthetics-logger');
const AWS = require('aws-sdk');
// Require any dependencies that your script needs
// Bundle additional files and dependencies into a .zip file with folder structure
// nodejs/node_modules/additional files and folders
const basicCustomEntryPoint = async function () {
log.info("Starting DynamoDB:listTables canary.");
let dynamodb = new AWS.DynamoDB();
var params = {};
let request = await dynamodb.listTables(params);
try {
let response = await request.promise();
log.info("listTables response: " + JSON.stringify(response));
} catch (err) {
log.error("listTables error: " + JSON.stringify(err), err.stack);
throw err;
}
return "Successfully completed DynamoDB:listTables canary.";
};
exports.handler = async () => {
return await basicCustomEntryPoint();
};
```
## Empacotamento dos arquivos do canário para Node.js
**Para syn-nodejs-puppeteer-11.0 e superior**
A estrutura de empacotamento mais antiga (para syn-nodejs-puppeteer-10.0 e versões anteriores) ainda tem suporte em versões mais recentes.
Crie um script usando uma das seguintes opções:
+ arquivo .js (sintaxe CommonJS)
+ arquivo. mjs (sintaxe dos módulos ES)
Para módulos ES, use uma destas opções:
+ arquivo .js (sintaxe CommonJS)
+ arquivo. mjs (sintaxe dos módulos ES)
A estrutura do pacote é definida abaixo:
+ Arquivo manipulador de nível raiz (index.js/index.mjs)
+ Arquivo de configuração opcional (synthetics.json)
+ Dependências adicionais em node\$1modules (se necessário)
Exemplo de estrutura de empacotamento:
```
my_function/
├── index.mjs
├── synthetics.json
├── helper-utils.mjs
└── node_modules/
└── dependencies
```
Para empacotar, siga as etapas abaixo:
1. Instale dependências (se houver).
```
npm install
```
1. Crie um pacote .zip.
```
zip -r my_deployment_package.zip
```
**Para syn-nodejs-puppeteer-11.0 e inferior**
A seguinte estrutura é necessária ao usar o Amazon S3:
```
nodejs/
└── node_modules/
└── myCanaryFilename.js
```
**Para adicionar um suporte opcional para subpastas no syn-nodejs-puppeteer-3.4\$1:**
```
nodejs/
└── node_modules/
└── myFolder/
└── myCanaryFilename.js
```
**nota**
O caminho do manipulador na configuração deve corresponder ao local do arquivo.
**Nome do manipulador**
Defina o ponto de entrada do script do canário (manipulador) como ` myCanaryFilename.functionName` para corresponder ao nome do arquivo do ponto de entrada do script. Se estiver usando um runtime anterior a `syn-nodejs-puppeteer-3.4`, então `functionName`deverá ser `handler`. Se estiver usando ` syn-nodejs-puppeteer-3.4` ou posterior, você poderá escolher qualquer nome de função como manipulador. Se estiver usando `syn-nodejs-puppeteer-3.4` ou posterior, você também poderá armazenar o canário em uma pasta separada, como ` nodejs/node_modules/myFolder/my_canary_filename`. Se você armazenar em uma pasta separada, especifique esse caminho no ponto de entrada do script, como ` myFolder/my_canary_filename.functionName`.
## Alterar um script existente do Puppeteer para ser usado como canário do Synthetics
Esta seção explica como modificar scripts do Puppeteer para executá-los como scripts do canário do Synthetics. Para obter mais informações sobre o Puppeteer, consulte [API do Puppeteer v1.14.0](https://github.com/puppeteer/puppeteer/blob/v1.14.0/docs/api.md).
Vamos começar com este exemplo de script do Puppeteer:
```
const puppeteer = require('puppeteer');
(async () => {
const browser = await puppeteer.launch();
const page = await browser.newPage();
await page.goto('https://example.com');
await page.screenshot({path: 'example.png'});
await browser.close();
})();
```
As etapas de conversão são as seguintes:
+ Crie e exporte uma função `handler`. O manipulador é a função de ponto de entrada para o script. Se estiver usando um runtime anterior a ` syn-nodejs-puppeteer-3.4`, a função do manipulador deverá ser nomeada `handler`. Se estiver usando `syn-nodejs-puppeteer-3.4` ou posterior, a função poderá ter qualquer nome, mas deverá ser o mesmo nome usado no script. Além disso, se você estiver usando `syn-nodejs-puppeteer-3.4` ou posterior, poderá armazenar scripts em qualquer pasta e especificar essa pasta como parte do nome do manipulador.
```
const basicPuppeteerExample = async function () {};
exports.handler = async () => {
return await basicPuppeteerExample();
};
```
+ Use a dependência `Synthetics`.
```
var synthetics = require('@aws/synthetics-puppeteer');
```
+ Use a função `Synthetics.getPage` para obter um objeto `Page` do Puppeteer.
```
const page = await synthetics.getPage();
```
O objeto de página retornado pela função Synthetics.getPage tem os eventos **page.on** `request`, `response` e ` requestfailed` instrumentados para registro em log. O Synthetics também define a geração de arquivos HAR para solicitações e respostas na página e adiciona o ARN do canário aos cabeçalhos do atendente do usuário de solicitações de saída na página.
O script agora está pronto para ser executado como um canário do Synthetics. Veja a seguir o script atualizado:
```
var synthetics = require('@aws/synthetics-puppeteer'); // Synthetics dependency
const basicPuppeteerExample = async function () {
const page = await synthetics.getPage(); // Get instrumented page from Synthetics
await page.goto('https://example.com');
await page.screenshot({path: '/tmp/example.png'}); // Write screenshot to /tmp folder
};
exports.handler = async () => { // Exported handler function
return await basicPuppeteerExample();
};
```
## Variáveis de ambiente
É possível usar variáveis de ambiente ao criar canaries. Isso permite escrever um único script o canário e usar esse script com valores diferentes para criar rapidamente vários canários que tenham uma tarefa semelhante.
Por exemplo, suponhamos que sua organização tenha endpoints como `prod`, ` dev` e `pre-release` para os diferentes estágios do desenvolvimento de seu software, e você necessite criar canaries para testar cada um desses endpoints. É possível escrever um único script do canário que testa seu software e especificar valores diferentes para a variável de ambiente do endpoint ao criar cada um dos três canários. Em seguida, ao criar um canário, especifique o script e os valores a serem usados para as variáveis de ambiente.
Os nomes das variáveis de ambiente podem conter letras, números e o caractere de sublinhado. Devem começar com uma letra e ter pelo menos dois caracteres. O tamanho total das variáveis de ambiente não pode exceder 4 KB. Você não pode especificar nenhuma variável de ambiente reservada do Lambda como os nomes de suas variáveis de ambiente. Para obter mais informações sobre variáveis de ambiente reservadas, consulte [ Variáveis de ambiente do runtime](https://docs.aws.amazon.com/lambda/latest/dg/configuration-envvars.html#configuration-envvars-runtime).
**Importante**
As chaves e os valores das variáveis de ambiente são criptografados em repouso usando chaves do AWS KMS de propriedade da AWS. No entanto, as variáveis de ambiente não são criptografadas no lado do cliente. Não armazene informações sigilosas neles.
O exemplo de script a seguir usa duas variáveis de ambiente. Esse script é para um canário que verifica se uma página da Web está disponível. Utiliza variáveis de ambiente para parametrizar tanto a URL que ele verifica como o nível de logs do CloudWatch Synthetics que ele usa.
A função a seguir define `LogLevel` para o valor da variável de ambiente ` LOG_LEVEL`.
```
synthetics.setLogLevel(process.env.LOG_LEVEL);
```
Essa função define `URL` para o valor da variável de ambiente `URL`.
```
const URL = process.env.URL;
```
Este é o script completo. Ao criar um canário usando esse script, especifique os valores a serem usados para as variáveis de ambiente `LOG_LEVEL` e `URL`.
```
var synthetics = require('@aws/synthetics-puppeteer');
const log = require('@aws/synthetics-logger');
const pageLoadEnvironmentVariable = async function () {
// Setting the log level (0-3)
synthetics.setLogLevel(process.env.LOG_LEVEL);
// INSERT URL here
const URL = process.env.URL;
let page = await synthetics.getPage();
//You can customize the wait condition here. For instance,
//using 'networkidle2' may be less restrictive.
const response = await page.goto(URL, {waitUntil: 'domcontentloaded', timeout: 30000});
if (!response) {
throw "Failed to load page!";
}
//Wait for page to render.
//Increase or decrease wait time based on endpoint being monitored.
await page.waitFor(15000);
await synthetics.takeScreenshot('loaded', 'loaded');
let pageTitle = await page.title();
log.info('Page title: ' + pageTitle);
log.debug('Environment variable:' + process.env.URL);
//If the response status code is not a 2xx success code
if (response.status() < 200 || response.status() > 299) {
throw "Failed to load page!";
}
};
exports.handler = async () => {
return await pageLoadEnvironmentVariable();
};
```
### Aprovar variáveis de ambiente para seu script
Para transmitir variáveis de ambiente para o script ao criar um canário no console, especifique as chaves e os valores das variáveis de ambiente na seção **Environment variables** (Variáveis de ambiente) no console. Para obter mais informações, consulte [Criar um canário](CloudWatch_Synthetics_Canaries_Create.md).
Para transmitir variáveis de ambiente pela API ou pela AWS CLI, use o parâmetro ` EnvironmentVariables` na seção `RunConfig`. O exemplo a seguir é um comando AWS CLI que cria um canário que usa duas variáveis de ambiente com chaves de `Environment` e `Region`.
```
aws synthetics create-canary --cli-input-json '{
"Name":"nameofCanary",
"ExecutionRoleArn":"roleArn",
"ArtifactS3Location":"s3://amzn-s3-demo-bucket-123456789012-us-west-2",
"Schedule":{
"Expression":"rate(0 minute)",
"DurationInSeconds":604800
},
"Code":{
"S3Bucket": "canarycreation",
"S3Key": "cwsyn-mycanaryheartbeat-12345678-d1bd-1234-abcd-123456789012-12345678-6a1f-47c3-b291-123456789012.zip",
"Handler":"pageLoadBlueprint.handler"
},
"RunConfig": {
"TimeoutInSeconds":60,
"EnvironmentVariables": {
"Environment":"Production",
"Region": "us-west-1"
}
},
"SuccessRetentionPeriodInDays":13,
"FailureRetentionPeriodInDays":13,
"RuntimeVersion":"syn-nodejs-2.0"
}'
```
## Integrar o canário a outros produtos da AWS
Todos os canaries podem usar a biblioteca do AWS SDK. É possível usar essa biblioteca ao escrever o canário de forma a integrá-lo a outros serviços da AWS.
Para fazer isso, é necessário adicionar o código a seguir ao canário. Para estes exemplos, o AWS Secrets Manager é usado como o serviço ao qual o canário está se integrando.
+ Importe o AWS SDK.
```
const AWS = require('aws-sdk');
```
+ Crie um cliente para o serviço da AWS ao qual você está realizando a integração.
```
const secretsManager = new AWS.SecretsManager();
```
+ Use o cliente para fazer chamadas de API para esse serviço.
```
var params = {
SecretId: secretName
};
return await secretsManager.getSecretValue(params).promise();
```
O trecho de código de script do canário a seguir demonstra um exemplo de integração ao Secrets Manager com mais detalhes.
```
var synthetics = require('@aws/synthetics-puppeteer');
const log = require('@aws/synthetics-logger');
const AWS = require('aws-sdk');
const secretsManager = new AWS.SecretsManager();
const getSecrets = async (secretName) => {
var params = {
SecretId: secretName
};
return await secretsManager.getSecretValue(params).promise();
}
const secretsExample = async function () {
let URL = "";
let page = await synthetics.getPage();
log.info(`Navigating to URL: ${URL}`);
const response = await page.goto(URL, {waitUntil: 'domcontentloaded', timeout: 30000});
// Fetch secrets
let secrets = await getSecrets("secretname")
/**
* Use secrets to login.
*
* Assuming secrets are stored in a JSON format like:
* {
* "username": "",
* "password": ""
* }
**/
let secretsObj = JSON.parse(secrets.SecretString);
await synthetics.executeStep('login', async function () {
await page.type(">USERNAME-INPUT-SELECTOR<", secretsObj.username);
await page.type(">PASSWORD-INPUT-SELECTOR<", secretsObj.password);
await Promise.all([
page.waitForNavigation({ timeout: 30000 }),
await page.click(">SUBMIT-BUTTON-SELECTOR<")
]);
});
// Verify login was successful
await synthetics.executeStep('verify', async function () {
await page.waitForXPath(">SELECTOR<", { timeout: 30000 });
});
};
exports.handler = async () => {
return await secretsExample();
};
```
## Forçar seu canário a usar um endereço IP estático
É possível configurar um canário para que ele use um endereço IP estático.
**Para forçar um canário a usar um endereço IP estático**
1. Crie uma nova VPC. Para obter mais informações, consulte [Using DNS with Your VPC](https://docs.aws.amazon.com/vpc/latest/userguide/vpc-dns.html).
1. Crie um novo gateway da Internet. Para obter mais informações, consulte [Adicionar um gateway da Internet à VPC](https://docs.aws.amazon.com/vpc/latest/userguide/VPC_Internet_Gateway.html#working-with-igw).
1. Crie uma sub-rede pública dentro de sua nova VPC.
1. Adicione uma nova tabela de rotas à VPC.
1. Adicione uma rota na nova tabela de rotas, que vai de `0.0.0.0/0` ao gateway da Internet.
1. Associe a nova tabela de rotas à sub-rede pública.
1. Crie um endereço de IP elástico. Para obter mais informações, consulte [Endereços de IP elásticos](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/elastic-ip-addresses-eip.html).
1. Crie um novo gateway NAT e atribua-o à sub-rede pública e ao endereço de IP elástico.
1. Crie uma sub-rede privada dentro da VPC.
1. Adiciona uma rota à tabela de rotas padrão da VPC, que vai de `0.0.0.0/0` ao gateway NAT
1. Crie um canário.
# Escrever um script o canário do Python
Esse script é executado com êxito e retorna uma string. Para ver como é um canário com falha, altere fail = False to fail = True
```
def basic_custom_script():
# Insert your code here
# Perform multi-step pass/fail check
# Log decisions made and results to /tmp
# Be sure to wait for all your code paths to complete
# before returning control back to Synthetics.
# In that way, your canary will not finish and report success
# before your code has finished executing
fail = False
if fail:
raise Exception("Failed basicCanary check.")
return "Successfully completed basicCanary checks."
def handler(event, context):
return basic_custom_script()
```
## Empacotamento dos arquivos do canário para Python
Se você tiver mais de um arquivo .py ou se o script tiver uma dependência, será possível agrupá-los em um único arquivo ZIP. Se você usar o runtime `syn-python-selenium-1.1`, o arquivo ZIP deverá conter o arquivo .py canário principal dentro de uma pasta `python`, como `python/my_canary_filename.py`. Se você usar ` syn-python-selenium-1.1` ou posterior, poderá usar uma pasta diferente, como `python/myFolder/my_canary_filename.py`.
Este arquivo ZIP deverá conter todas as pastas e arquivos necessários, mas os outros arquivos não precisam estar na pasta `python`.
Defina o ponto de entrada do script o canário como ` my_canary_filename.functionName` para corresponder ao nome do arquivo e ao nome da função do ponto de entrada do script. Se você estiver usando o runtime `syn-python-selenium-1.0`, `functionName` deverá ser `handler`. Se estiver usando ` syn-python-selenium-1.1` ou posterior, essa restrição de nome do manipulador não se aplicará, e você também poderá, opcionalmente, armazenar o canário em uma pasta separada, como ` python/myFolder/my_canary_filename.py`. Se você armazenar em uma pasta separada, especifique esse caminho no ponto de entrada do script, como ` myFolder/my_canary_filename.functionName`.
## Alterar um script existente do Selenium para ser usado como canário do Synthetics
É possível modificar rapidamente um script existente para Python e Selenium a ser usado como canário. Para obter mais informações sobre o Selenium, consulte [www.selenium.dev/](https://www.selenium.dev/).
Neste exemplo, começaremos com o seguinte script Selenium:
```
from selenium import webdriver
def basic_selenium_script():
browser = webdriver.Chrome()
browser.get('https://example.com')
browser.save_screenshot('loaded.png')
basic_selenium_script()
```
As etapas de conversão são as seguintes.
**Para converter um script Selenium para ser usado como canário**
1. Altere a instrução `import` para usar o Selenium a partir do módulo ` aws_synthetics`:
```
from aws_synthetics.selenium import synthetics_webdriver as webdriver
```
O módulo Selenium a partir de `aws_synthetics` garante que o canário poderá emitir métricas e logs, gerar um arquivo HAR e trabalhar com outros recursos do CloudWatch Synthetics.
1. Crie uma função de manipulador e chame seu método Selenium. O manipulador é a função de ponto de entrada para o script.
Se estiver usando `syn-python-selenium-1.0`, a função do manipulador deverá ser nomeada `handler`. Se estiver usando `syn-python-selenium-1.1` ou posterior, a função poderá ter qualquer nome, mas deverá ser o mesmo nome usado no script. Além disso, se você estiver usando `syn-python-selenium-1.1` ou posterior, poderá armazenar scripts em qualquer pasta e especificar essa pasta como parte do nome do manipulador.
```
def handler(event, context):
basic_selenium_script()
```
Agora, o script é atualizado para ser um canário do CloudWatch Synthetics. Veja a seguir o script atualizado:
O `webdriver` é uma instância da classe [SyntheticsWebDriver](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/CloudWatch_Synthetics_Canaries_Library_Python.html#CloudWatch_Synthetics_Library_Python_SyntheticsWebDriver) e o navegador retornado por `webdriver.Chrome()` é uma instância de [SyntheticsBrowser](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/CloudWatch_Synthetics_Canaries_Library_Python.html#CloudWatch_Synthetics_Library_Python_SyntheticsBrowser).
```
from aws_synthetics.selenium import synthetics_webdriver as webdriver
def basic_selenium_script():
browser = webdriver.Chrome()
browser.get('https://example.com')
browser.save_screenshot('loaded.png')
def handler(event, context):
basic_selenium_script()
```
## Como alterar um script existente do Puppeteer Synthetics para autenticar certificados não padrão
Um caso de uso importante dos canários Synthetics é monitorar seus próprios endpoints. Se você quiser monitorar um endpoint que não esteja pronto para tráfego externo, esse monitoramento poderá, às vezes, significar que você não tenha um certificado adequado assinado por uma autoridade de certificação terceirizada confiável.
Duas soluções possíveis para esse cenário são as seguintes:
+ Para autenticar um certificado de cliente, consulte [Como validar a autenticação usando o Amazon CloudWatch Synthetics – Parte 2](https://aws.amazon.com/blogs/mt/how-to-validate-authentication-using-amazon-cloudwatch-synthetics-part-2/).
+ Para autenticar um certificado autoassinado, consulte [Como validar a autenticação com certificados autoassinados no Amazon CloudWatch Synthetics](https://aws.amazon.com/blogs/mt/how-to-validate-authentication-with-self-signed-certificates-in-amazon-cloudwatch-synthetics/)
Você não está limitado a essas duas opções ao usar os canários CloudWatch Synthetics. Você pode estender esses recursos e adicionar sua lógica de negócios estendendo o código canário.
**nota**
Os canários Synthetics executados em runtimes do Python têm o sinalizador ` --ignore-certificate-errors` habilitado de forma inata, portanto, esses canários não devem ter problemas para acessar sites com configurações de certificado não padrão.
# Escrever uma configuração JSON para o esquema de múltiplas verificações do Node.js
O esquema de múltiplas verificações do Node.js permite criar canários que realizam múltiplas verificações de validação em uma única execução de canário. Esse esquema é útil quando você deseja testar vários endpoints, validar diferentes aspectos da aplicação ou realizar uma série de verificações relacionadas em sequência.
**Topics**
+ [
## Estrutura da configuração primária
](#root-configuration-structure)
+ [
## Configurações globais
](#global-settings)
+ [
## Gerenciamento de variáveis e dados
](#variables-data-management)
+ [
## Definições de etapas
](#step-definitions)
+ [
## Tipos de verificação
](#check-types)
+ [
## Métodos de autenticação
](#authentication-methods)
+ [
## Asserções e validação
](#assertions-validation)
+ [
## Extração de dados
](#data-extraction)
## Estrutura da configuração primária
A configuração primária define a estrutura geral do canário do esquema de API avançado.
**Propriedades do esquema**
| Propriedade | Tipo | Obrigatório | Descrição |
| --- | --- | --- | --- |
| globalSettings | Objeto | Não | Configurações padrão aplicadas a todas as etapas |
| variables | Objeto | Não | Valores reutilizáveis em todas as etapas (máx. 10) |
| steps | Objeto | Sim | Conjunto de etapas de monitoramento (1 a 10 etapas) |
**Exemplo**
```
{
"globalSettings": {
"stepTimeout": 30000,
"userAgent": "CloudWatch-Synthetics-Advanced/1.0"
},
"variables": {
"baseUrl": "https://api.example.com",
"apiVersion": "v1"
},
"steps": {
"1": {
"stepName": "healthCheck",
"checkerType": "HTTP",
"url": "${baseUrl}/health",
"httpMethod": "GET"
}
}
}
```
**Regras de validação**
+ Deve conter pelo menos uma etapa
+ Máximo permitido de 10 etapas
+ Não são permitidas outras propriedades além de `globalSettings`, ` variables` e `steps`
## Configurações globais
As definições globais fornecem configurações padrão que se aplicam a todas as etapas, a menos que sejam substituídas no nível da etapa.
**Propriedades**
**Propriedades das configurações globais**
| Propriedade | Tipo | Padrão | Intervalo | Descrição |
| --- | --- | --- | --- | --- |
| stepTimeout | integer | 30000 | 5.000 a 300.000 | Tempo limite padrão para todas as etapas (milissegundos) |
**Exemplo**
```
{
"globalSettings": {
"stepTimeout": 60000,
}
}
```
## Gerenciamento de variáveis e dados
As variáveis permitem definir valores reutilizáveis que podem ser referenciados em toda a configuração usando a sintaxe `${variableName}`.
**Propriedades variáveis**
| Propriedade | Tipo | Descrição |
| --- | --- | --- |
| Nomes das variáveis | string | Deve corresponder ao padrão: . ^[a-zA-Z][a-zA-Z0-9\$1]\$1\$1 |
| Valores das variáveis | string | Qualquer valor de string |
**Limitações**
+ Máximo de 10 variáveis por configuração
+ Os nomes das variáveis devem começar com uma letra
+ Os nomes das variáveis podem apenas conter letras, números e sublinhados
+ Tamanho máximo não especificado no esquema
**Exemplo**
```
{
"variables": {
"baseUrl": "https://api.example.com",
"apiKey": "${AWS_SECRET:my-api-key}",
"timeout": "30000",
"userEmail": "test@example.com"
}
}
```
**Uso da configuração**
```
{
"steps": {
"1": {
"url": "${baseUrl}/users",
"timeout": "${timeout}",
"headers": {
"Authorization": "Bearer ${apiKey}"
}
}
}
}
```
## Definições de etapas
As etapas definem operações de monitoramento individuais. Cada etapa é numerada de 1 a 10 e contém um tipo específico de verificação.
*Propriedades das etapas comuns*
| Propriedade | Tipo | Obrigatório | Descrição |
| --- | --- | --- | --- |
| stepName | string | Sim | Identificador exclusivo da etapa |
| checkerType | string | Sim | Tipo de verificação: HTTP, DNS, SSL, TCP |
| extractors | array | Não | Configuração de extração de dados |
*Validação de nome de etapa*
+ Padrão: ^[a-zA-Z][a-zA-Z0-9\$1-]\$1\$1
+ Tamanho máximo: 64 caracteres
+ Deve começar com uma letra
*Numeração das etapas*
+ As etapas são numeradas como chaves de string: “1”, “2”,..., “10”
+ Padrão: ^([1-9]\$110)\$1
+ Mínimo obrigatório de 1 etapa
+ Máximo permitido de 10 etapas
*Exemplo*
```
{
"steps": {
"1": {
"stepName": "loginAPI",
"checkerType": "HTTP",
"url": "https://api.example.com/login",
"httpMethod": "POST"
},
"2": {
"stepName": "dnsCheck",
"checkerType": "DNS",
"domain": "example.com"
}
}
}
```
## Tipos de verificação
### Verificações HTTP
Monitore endpoints e APIs Web com validação abrangente de solicitações e respostas.
**Propriedades necessárias**
| Propriedade | Tipo | Descrição |
| --- | --- | --- |
| url | string | URL de destino (deve ser um formato de URI válido) |
| httpMethod | string | Método HTTP: GET, POST, PUT, PATCH, DELETE, HEAD, OPTIONS |
**Propriedades opcionais**
| Propriedade | Tipo | Padrão | Intervalo | Descrição |
| --- | --- | --- | --- | --- |
| timeout | integer | 30000 | 5.000 a 300.000 | Tempo limite (milissegundos) |
| waitTime | integer | 0 | 0-60 | Demora antes da solicitação (segundos) |
| headers | objeto | - | - | Cabeçalhos HTTP personalizados |
| body | string | - | - | Corpo da solicitação para operações POST/PUT |
| authentication | objeto | - | - | Configuração da autenticação |
| assertions | array | - | - | Regras de validação de resposta |
**Exemplo**
```
{
"stepName": "createUser",
"checkerType": "HTTP",
"url": "https://api.example.com/users",
"httpMethod": "POST",
"timeout": 15000,
"headers": {
"Content-Type": "application/json",
"X-API-Version": "v1"
},
"body": "{\"name\":\"John Doe\",\"email\":\"john@example.com\"}",
"authentication": {
"type": "API_KEY",
"apiKey": "${AWS_SECRET:api-credentials}",
"headerName": "X-API-Key"
},
"assertions": [
{
"type": "STATUS_CODE",
"operator": "EQUALS",
"value": 201
}
]
}
```
### Verificações do DNS
Valide a resolução do DNS e registre as informações.
**Propriedades necessárias**
| Propriedade | Tipo | Descrição |
| --- | --- | --- |
| domain | string | Nome de domínio a ser consultado (formato de nome de host) |
**Propriedades opcionais**
| Propriedade | Tipo | Padrão | Descrição |
| --- | --- | --- | --- |
| recordType | string | “A” | Tipo de registro do DNS: A, CNAME, MX, TXT, NS |
| nameserver | string | - | Servidor do DNS específico a ser consultado |
| timeout | integer | 30000 | Tempo limite de consulta (5.000 a 300.000 ms) |
| port | integer | 53 | Porta do servidor DNS (1 a 65535) |
| protocol | string | “UDP” | Protocolo: UDP ou TCP |
| assertions | array | - | Regras de validação de resposta do DNS |
**Exemplo**
```
{
"stepName": "dnsResolution",
"checkerType": "DNS",
"domain": "example.com",
"recordType": "A",
"nameserver": "8.8.8.8",
"timeout": 10000,
"assertions": [
{
"type": "RECORD_VALUE",
"operator": "CONTAINS",
"value": "192.168"
}
]
}
```
### Verificações SSL
Monitore a integridade e a configuração dos certificados SSL.
**Propriedades necessárias**
| Propriedade | Tipo | Descrição |
| --- | --- | --- |
| hostname | string | Nome do host de destino (formato do nome do host) |
**Propriedades opcionais**
| Propriedade | Tipo | Padrão | Descrição |
| --- | --- | --- | --- |
| port | integer | 443 | Porta SSL (1 a 65.535) |
| timeout | integer | 30000 | Tempo limite de conexão (5.000 a 300.000 ms) |
| sni | booliano | TRUE | Indicação de nome do servidor |
| verifyHostname | booliano | TRUE | Verificação de nome do servidor |
| allowSelfSigned | booleano | FALSE | Aceitar certificados autoassinados |
| assertions | array | - | Regras de validação de certificados |
**Exemplo**
```
{
"stepName": "sslCertCheck",
"checkerType": "SSL",
"hostname": "secure.example.com",
"port": 443,
"sni": true,
"verifyHostname": true,
"assertions": [
{
"type": "CERTIFICATE_EXPIRY",
"operator": "GREATER_THAN",
"value": 30,
"unit": "DAYS"
}
]
}
```
### Verificações TCP
Teste a conectividade e a validação de resposta da porta TCP.
**Propriedades necessárias**
| Propriedade | Tipo | Descrição |
| --- | --- | --- |
| hostname | string | Nome do host de destino (formato do nome do host) |
| port | integer | Porta de destino (1 a 65.535) |
**Propriedades opcionais**
| Propriedade | Tipo | Padrão | Descrição |
| --- | --- | --- | --- |
| timeout | integer | 30000 | Tempo limite em geral (5.000 a 300.000 ms) |
| connectionTimeout | integer | 3000 | Tempo limite de conexão (5.000 a 300.000 ms) |
| readTimeout | integer | 2000 | Tempo limite de leitura de dados (5.000 a 300.000 ms) |
| sendData | string | - | Dados a serem enviados após a conexão |
| expectedResponse | string | - | Dados de resposta esperados |
| encoding | string | “UTF-8” | Codificação de dados: UTF-8, ASCII, HEX |
| assertions | array | - | validação de conexão e resposta |
**Exemplo**
```
{
"stepName": "databaseConnection",
"checkerType": "TCP",
"hostname": "db.example.com",
"port": 3306,
"connectionTimeout": 5000,
"sendData": "SELECT 1",
"expectedResponse": "1",
"assertions": [
{
"type": "CONNECTION_SUCCESSFUL",
"value": true
}
]
}
```
## Métodos de autenticação
**Sem autenticação**
```
{
"type": "NONE"
}
```
**Autenticação básica**
| Propriedade | Tipo | Obrigatório | Descrição |
| --- | --- | --- | --- |
| type | string | Sim | Deve ser "BASIC" |
| username | string | Sim | Nome de usuário para autenticação |
| password | string | Sim | Senha para autenticação |
**Exemplo**
```
{
"type": "BASIC",
"username": "admin",
"password": "${AWS_SECRET:basic-auth:password}"
}
```
**Autenticação de chave de API**
| Propriedade | Tipo | Obrigatório | Padrão | Descrição |
| --- | --- | --- | --- | --- |
| type | string | Sim | - | Deve ser "API\$1KEY" |
| apiKey | string | Sim | - | Valor da chave de API |
| headerName | string | Não | “X-API-Key” | Nome de cabeçalho para chave de API |
**Exemplo**
```
{
"type": "API_KEY",
"apiKey": "${AWS_SECRET:api-credentials}",
"headerName": "Authorization"
}
```
**Credenciais de cliente OAuth**
| Propriedade | Tipo | Obrigatório | Padrão | Descrição |
| --- | --- | --- | --- | --- |
| type | string | Sim | - | Deve ser "OAUTH\$1CLIENT\$1CREDENTIALS" |
| tokenUrl | string | Sim | - | URL do endpoint do token OAuth |
| clientId | string | Sim | - | ID do cliente OAuth |
| clientSecret | string | Sim | - | Segredo do cliente OAuth |
| scope | string | Não | - | Escopo do OAuth |
| audience | string | Não | - | Público do OAuth |
| resource | string | Não | - | Recurso do OAuth |
| tokenApiAuth | array | Não | - | Métodos de autenticação de API de token: BASIC\$1AUTH\$1HEADER, REQUEST\$1BODY |
| tokenCacheTtl | integer | Não | 3600 | TTL do cache de tokens (mínimo de 60 segundos) |
**Exemplo**
```
{
"type": "OAUTH_CLIENT_CREDENTIALS",
"tokenUrl": "https://auth.example.com/oauth/token",
"clientId": "${AWS_SECRET:oauth-creds:client_id}",
"clientSecret": "${AWS_SECRET:oauth-creds:client_secret}",
"scope": "read write",
"tokenCacheTtl": 7200
}
```
**AWS Signature (versão 4)**
| Propriedade | Tipo | Obrigatório | Descrição |
| --- | --- | --- | --- |
| type | string | Sim | Deve ser "SIGV4" |
| service | string | Sim | Nome do serviço da AWS (por exemplo, “execute-api”) |
| region | string | Sim | AWS region |
| roleArn | string | Sim | ARN do perfil do IAM para assinatura |
**Exemplo**
```
{
"type": "SIGV4",
"service": "execute-api",
"region": "us-east-1",
"roleArn": "arn:aws:iam::123456789012:role/SyntheticsRole"
}
```
## Asserções e validação
### Asserções HTTP
**Asserções de código de status**
| Propriedade | Tipo | Obrigatório | Descrição |
| --- | --- | --- | --- |
| type | string | Sim | Deve ser "STATUS\$1CODE" |
| operator | string | Sim | EQUALS, NOT\$1EQUALS, GREATER\$1THAN, LESS\$1THAN, IN\$1RANGE |
| value | integer | Condicional | Código de status HTTP (100 a 599) |
| rangeMin | integer | Condicional | Valor mínimo do intervalo (para IN\$1RANGE) |
| rangeMax | integer | Condicional | Valor máximo do intervalo (para IN\$1RANGE) |
```
{
"type": "STATUS_CODE",
"operator": "EQUALS",
"value": 200
}
```
**Asserções de tempo de resposta**
| Propriedade | Tipo | Obrigatório | Padrão | Descrição |
| --- | --- | --- | --- | --- |
| type | string | Sim | - | Deve ser "RESPONSE\$1TIME" |
| operator | string | Sim | - | LESS\$1THAN, GREATER\$1THAN, EQUALS |
| value | número | Sim | - | Valor de tempo (mínimo 0) |
| unit | string | Não | "MILLISSEGUNDOS" | Deve ser "MILLISECONDS" |
```
{
"type": "RESPONSE_TIME",
"operator": "LESS_THAN",
"value": 500,
"unit": "MILLISECONDS"
}
```
**Asserções de cabeçalho**
| Propriedade | Tipo | Obrigatório | Descrição |
| --- | --- | --- | --- |
| type | string | Sim | Deve ser "HEADER" |
| headerName | string | Sim | Nome do cabeçalho a ser validado |
| operator | string | Sim | EQUALS, NOT\$1EQUALS, CONTAINS, NOT\$1CONTAINS, REGEX\$1MATCH, EXIST |
| value | String/booleano | Condicional | Valor esperado (booleano para o operador EXIST) |
```
{
"type": "HEADER",
"headerName": "Content-Type",
"operator": "CONTAINS",
"value": "application/json"
}
```
**Asserções de corpo**
| Propriedade | Tipo | Obrigatório | Padrão | Descrição |
| --- | --- | --- | --- | --- |
| type | string | Sim | - | Deve ser "BODY" |
| target | string | Não | “JSON” | JSON ou TEXT |
| path | string | Condicional | - | JSONPath (obrigatório para destino JSON) |
| operator | string | Sim | - | CONTAINS, NOT\$1CONTAINS, EQUALS, NOT\$1EQUALS, EXISTS |
| value | String/booleano | Sim | - | Valor esperado (booleano para o operador EXISTS) |
```
{
"type": "BODY",
"target": "JSON",
"path": "$.users[0].name",
"operator": "EQUALS",
"value": "John Doe"
}
```
### Asserções DNS
**Registrar asserções de valor**
| Propriedade | Tipo | Obrigatório | Intervalo | Descrição |
| --- | --- | --- | --- | --- |
| type | string | Sim | - | Deve ser "RECORD\$1VALUE" |
| operator | string | Sim | - | EQUALS, NOT\$1EQUALS, CONTAINS, NOT\$1CONTAINS, REGEX\$1MATCH |
| value | string | Sim | - | Valor do registro esperado |
**Asserções de contagem de registros**
| Propriedade | Tipo | Obrigatório | Intervalo | Descrição |
| --- | --- | --- | --- | --- |
| type | string | Sim | - | Deve ser "RECORD\$1COUNT" |
| operator | string | Sim | - | EQUALS, GREATER\$1THAN, LESS\$1THAN |
| value | integer | Sim | ≥ 0 | Contagem esperada (mínimo 0) |
**Asserções autoritativas**
| Propriedade | Tipo | Obrigatório | Intervalo | Descrição |
| --- | --- | --- | --- | --- |
| type | string | Sim | - | Deve ser "AUTHORITATIVE" |
| value | booleano | Sim | - | Status autoritativo esperado |
**Asserções TTL**
| Propriedade | Tipo | Obrigatório | Intervalo | Descrição |
| --- | --- | --- | --- | --- |
| type | string | Sim | - | Deve ser "TTL" |
| operator | string | Sim | - | EQUALS, GREATER\$1THAN, LESS\$1THAN |
| value | integer | Sim | ≥ 0 | TTL esperada (mínimo 0) |
### Asserções SSL
**Asserções de expiração do certificado**
| Propriedade | Tipo | Obrigatório | Padrão | Descrição |
| --- | --- | --- | --- | --- |
| type | string | Sim | - | Deve ser "CERTIFICATE\$1EXPIRY" |
| operator | string | Sim | - | GREATER\$1THAN, LESS\$1THAN |
| value | integer | Sim | - | Valor de tempo (mínimo 0) |
| unit | string | Não | “DIAS” | DAYS, HOURS |
**Asserções de assunto do certificado**
| Propriedade | Tipo | Obrigatório | Padrão | Descrição |
| --- | --- | --- | --- | --- |
| type | string | Sim | - | Deve ser "CERTIFICATE\$1SUBJECT" |
| field | string | Sim | - | Campo de assunto: CN, O, OU, C, ST, L |
| operator | string | Sim | - | CONTAINS, EQUALS, REGEX\$1MATCH |
| value | string | Sim | - | Valores de campo esperados |
**Asserções de emissor de certificado**
| Propriedade | Tipo | Obrigatório | Padrão | Descrição |
| --- | --- | --- | --- | --- |
| type | string | Sim | - | Deve ser "CERTIFICATE\$1ISSUER" |
| field | string | Sim | - | Campo do emissor: CN, O |
| operator | string | Sim | - | CONTAINS, EQUALS |
| value | string | Sim | - | Valores de campo esperados |
### Asserções TCP
**Asserções de sucesso de conexão**
| Propriedade | Tipo | Obrigatório | Padrão | Descrição |
| --- | --- | --- | --- | --- |
| type | string | Sim | - | Deve ser "CONNECTION\$1SUCCESSFUL" |
| value | booleano | Sim | - | Status de conexão esperado |
**Asserções de dados de resposta**
| Propriedade | Tipo | Obrigatório | Padrão | Descrição |
| --- | --- | --- | --- | --- |
| type | string | Sim | - | Deve ser "RESPONSE\$1DATA" |
| operator | string | Sim | - | CONTAINS, EQUALS, NOT\$1CONTAINS, REGEX\$1MATCH, STARTS\$1WITH, ENDS\$1WITH |
| value | string | Sim | - | Dados de resposta esperados |
| encoding | string | Não | “UTF-8” | UTF-8, ASCII, HEX |
## Extração de dados
Os extratores permitem que você capture dados das respostas para uso em etapas subsequentes ou para relatórios.
**Propriedades de extração**
| Propriedade | Tipo | Obrigatório | Padrão | Descrição |
| --- | --- | --- | --- | --- |
| name | string | Sim | - | Nome da variável para dados extraídos |
| type | string | Sim | - | Tipo de extração: BODY |
| path | string | Não | - | JSONPath para extração de corpo |
| regex | string | Não | - | Padrão de expressão regular |
| regexGroup | integer | Não | 0 | Grupo de captura de expressão regular (mínimo 0) |
**Validação de nome de extração**
+ Número do padrão: `^[a-zA-Z][a-zA-Z0-9_]*$`
+ Deve começar com uma letra
+ Podem conter apenas letras, números e sublinhados
**Limitação**: a substituição não se aplica aos campos do esquema com valores ENUM específicos
**Tipos de extração**
```
{
"name": "userId",
"type": "BODY",
"path": "$.user.id"
}
```
```
{
"stepName": "loginAndExtract",
"checkerType": "HTTP",
"url": "https://api.example.com/login",
"httpMethod": "POST",
"body": "{\"username\":\"test\",\"password\":\"pass\"}",
"extractors": [
{
"name": "textVariable",
"type": "BODY",
"path": "$.myvalue"
}
]
},
{
"stepName": "substituteVariable",
"checkerType": "HTTP",
"url": "https://api.example.com/get/${textVariable}",
"httpMethod": "GET",
"assertions": [
{
"type": "BODY",
"target": "JSON",
"path": "$.users[0].name",
"operator": "EQUALS",
"value": "${textVariable}"
}
]
}
```
# Funções da biblioteca disponíveis para scripts o canário
O CloudWatch Synthetics contém várias classes e funções incorporadas que podem ser chamadas ao gravar scripts Node.js a serem usados como canaries.
Algumas se aplicam a canaries de interface do usuário e de API. Outros se aplicam apenas a canaries de interface do usuário. Um canário de interface do usuário é um canário que usa a função `getPage()` e usa o Puppeteer como um driver da web para navegar e interagir com páginas da web.
**nota**
Sempre que você atualizar um canário para usar uma nova versão do runtime do Synthetics, todas as funções da biblioteca Synthetics que seu canário usar também serão automaticamente atualizadas para a mesma versão do NodeJS que o runtime do Synthetics ofereça suporte.
**Topics**
+ [
# Funções de biblioteca disponíveis para canário do Node.js
](Library_function_Nodejs.md)
+ [
# Funções da biblioteca disponíveis para canário em Java
](CloudWatch_Synthetics_Canaries_Java.md)
+ [
# Funções de biblioteca disponíveis para scripts de canário Node.js usando o Playwright
](CloudWatch_Synthetics_Canaries_Nodejs_Playwright.md)
+ [
# Funções de biblioteca disponíveis para scripts de canário Node.js usando o Puppeteer
](CloudWatch_Synthetics_Canaries_Library_Nodejs.md)
+ [
# Funções da biblioteca disponíveis para scripts do canário do Python usando Selenium
](CloudWatch_Synthetics_Canaries_Library_Python.md)
# Funções de biblioteca disponíveis para canário do Node.js
Esta seção descreve as funções de biblioteca que estão disponíveis para scripts de canário usando o runtime do 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` descreve o erro, e `ex` é a exceção encontrada
Você pode usar `addExecutionError` para definir erros de execução eu seu canário. Ele faz o canário falhar sem interromper a execução do script. Também não afeta suas métricas `successPercent`.
Convém rastrear erros como erros de execução somente se eles não forem importantes para indicar o sucesso ou falha do script do canário.
A seguir há um exemplo de uso do elemento `addExecutionError`. Você está monitorando a disponibilidade de seu endpoint e fazendo capturas de tela depois que a página foi carregada. Como a falha de obter uma captura de tela não determina a disponibilidade do endpoint, é possível detectar quaisquer erros encontrados durante a captura de tela e adicioná-los como erros de execução. Suas métricas de disponibilidade ainda indicarão que o endpoint está ativo e em execução, mas o status do canário será marcado como falha. O bloco de código de exemplo a seguir captura esse erro e adiciona-o como erro de execução.
```
try {await synthetics.executeStep(stepName, callbackFunc);} catch(ex) {synthetics.addExecutionError('Unable to take screenshot ', ex);}
```
## getCanaryName();
Retorna o nome do canário.
## getCanaryArn();
Retorna o ARN do canário.
## getCanaryUserAgentString();
Retorna o agente de usuário personalizado do canário.
## getRuntimeVersion();
Essa função está disponível na versão de runtime `syn-nodejs-3.0` e posteriores. Ele retorna a versão de runtime do Synthetics do canário. Por exemplo, o valor de retorno pode ser `syn-nodejs-3.0`.
## getLogLevel();
Recupera o nível de log atual para a biblioteca do Synthetics. Os valores possíveis são os seguintes:
+ `0`: debug
+ `1`: info
+ `2`: warn
+ `3`: error
Exemplo:
```
let logLevel = synthetics.getLogLevel();
```
## setLogLevel();
Define o nível de log para a biblioteca do Synthetics. Os valores possíveis são os seguintes:
+ `0`: debug
+ `1`: info
+ `2`: warn
+ `3`: error
Exemplo:
```
synthetics.setLogLevel(0);
```
## executeStep(stepName, functionToExecute, [stepConfig])
Executa a etapa fornecida, terminando-a com registro em log de início/aprovação/reprovação, e métricas de aprovação/reprovação e duração.
A função `executeStep` também faz o seguinte:
+ Registra que a etapa foi iniciada
+ Inicia um temporizador
+ Executa a função fornecida
+ Quando a função retorna normalmente, ela conta como aprovada. Se a função apresentar erro, contará como tendo sido reprovada
+ Encerra o temporizador
+ Registra se a etapa foi aprovada ou falhou
+ Emite a métrica `stepName SuccessPercent`, 100 para aprovação ou 0 para reprovação
+ Emite a métrica `stepName Duration metric`, com um valor de acordo com a hora de início e de fim da etapa
+ Retorna o que a functionToExecute retornou ou gera novamente o erro gerado por ` functionToExecute`
+ Adiciona um resumo de execução da etapa ao relatório do canário
**Exemplo**
```
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])
Executa a solicitação HTTP fornecida como uma etapa e publica `SuccessPercent` (aprovação/falha) e métricas `Duration`.
**executeHttpStep** usa funções nativas HTTP ou HTTPS nos bastidores, conforme o protocolo especificado na solicitação.
Essa função também adicionará um resumo de execução de etapa ao relatório do canário. O resumo contém detalhes sobre cada solicitação HTTP, como o seguinte:
+ Hora de início
+ End Time
+ Status (PASSED/FAILED)
+ Motivo da falha, se for o caso
+ Detalhes da chamada HTTP, como cabeçalhos e corpo da solicitação/resposta, código de status, mensagem de status e tempos de performance.
**Topics**
+ [
### Parâmetros
](#Library_function_Nodejs_executeHttpStep_parameters_Nodecanary)
+ [
### Exemplos de uso do executeHttpStep
](#Library_function_Nodejs_executeHttpStep_examples_Nodecanary)
### Parâmetros
**stepName(*String*)**
Especifica o nome da etapa. Esse nome também é usado para publicar métricas do CloudWatch para essa etapa.
**requestOptions(*Object or String*)**
O valor desse parâmetro poderá ser uma URL, uma string de URL ou um objeto. Se for um objeto, ele deverá ser um conjunto de opções configuráveis para fazer uma solicitação HTTP. É compatível com todas as opções em [ http.request(options[, callback])](https://nodejs.org/api/http.html#http_http_request_options_callback) na documentação do Node.js.
Além dessas opções do Node.js, **requestOptions** oferece suporte ao parâmetro adicional `body`. Você pode usar o parâmetro `body` para aprovar dados como um corpo da solicitação.
**callback(*response*)**
(Opcional) Esaa é uma função de usuário que é invocada com a resposta HTTP. A resposta é do tipo [Class: http.IncomingMessage](https://nodejs.org/api/http.html#http_class_http_incomingmessage).
**stepConfig(*object*)**
(Opcional) Use esae parâmetro para substituir configurações globais do Synthetics por uma configuração diferente para essa etapa.
### Exemplos de uso do executeHttpStep
As séries de exemplos a seguir são desenvolvidas entre si para ilustrar os vários usos dessa opção.
Este primeiro exemplo configura parâmetros de solicitação. Você pode passar um URL como **requestOptions**:
```
let requestOptions = 'https://www.amazon.com';
```
Ou pode aprovar um conjunto de opções:
```
let requestOptions = {
'hostname': 'myproductsEndpoint.com',
'method': 'GET',
'path': '/test/product/validProductName',
'port': 443,
'protocol': 'https:'
};
```
O próximo exemplo cria uma função de retorno de chamada que aceita uma resposta. Por padrão, se você não especificar **callback**, o CloudWatch Synthetics validará que o status está entre 200 e 299, inclusive.
```
// 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();
});
});
};
```
O próximo exemplo cria uma configuração para essa etapa que substitui a configuração global do CloudWatch Synthetics. A configuração de etapa desse exemplo permite cabeçalhos de solicitação, cabeçalhos de resposta, corpo da solicitação (dados de postagem) e corpo da resposta em seu relatório e restringir valores de cabeçalho ‘X-Amz-Security-Token’ e ‘Authorization’. Por padrão, esses valores não são incluídos no relatório por motivos de segurança. Se você escolher incluí-los, os dados serão armazenados apenas no bucket do 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
};
```
Este exemplo final aprova sua solicitação para **executeHttpStep** e nomeia a etapa.
```
await synthetics.executeHttpStep('Verify GET products API', requestOptions, callback, stepConfig);
```
Com esse conjunto de exemplos, o CloudWatch Synthetics adiciona os detalhes de cada etapa do relatório e produz métricas para cada etapa usando **stepName**.
Você verá as métricas `successPercent` e `duration` para a etapa `Verify GET products API`. É possível monitorar a performance de sua API monitorando as métricas para suas etapas de chamada de API.
Para obter um script completo de exemplo que usa essas funções, consulte [Canário de API de várias etapas](CloudWatch_Synthetics_Canaries_Samples.md#CloudWatch_Synthetics_Canaries_Samples_APIsteps).
# Funções da biblioteca disponíveis para canário em Java
A função `executeStep` é usada para modularizar o código do canário e executá-lo em etapas. No CloudWatch Synthetics, uma etapa do Synthetics é uma forma de dividir seu script do canário em uma série de ações claramente definidas, permitindo que você monitore diferentes partes de sua jornada de aplicação separadamente. Para cada etapa, o CloudWatch Synthetics faz o seguinte:
+ Para cada execução do canário, é criado um relatório que inclui um resumo dos detalhes da execução das etapas, como duração de uma etapa, status de *com êxito* ou *com falha*, entre outros. Ao escolher uma execução no console do CloudWatch Synthetics, você pode visualizar os detalhes da execução de cada etapa na guia **Etapa**.
+ As métricas *SuccessPercent* e *Duration* do CloudWatch são emitidas para cada etapa, possibilitando que os usuários monitorem a disponibilidade e a latência de cada uma delas.
**Usage**
```
synthetics.executeStep(stepName,()->{
try {
//step code to be executed
return null;
} catch (Exception e) {
throw e;
}
}).get();
```
**Parâmetros**
+ *stepName*, String (obrigatório): um nome descritivo para a etapa do Synthetics
+ *function to execute*, Callable (obrigatório): representa as tarefas a serem executadas
+ *stepOptions*, `com.amazonaws.synthetics.StepOptions (optional)`:o objeto stepOptions que pode ser usado para configurar a execução da etapa.
*stepConfiguration*, ` com.amazonaws.synthetics.StepConfiguration` (obrigatório como parte do objeto stepOptions)
**Devoluções**
O valor retornado é *CompletableFuture*.
**nota**
O Synthetics é compatível somente com etapas sequenciais. Certifique-se de chamar o método `.get()`, conforme mostrado no exemplo, para garantir que esta etapa esteja concluída antes de prosseguir para a próxima etapa.
# Funções de biblioteca disponíveis para scripts de canário Node.js usando o Playwright
Esta seção descreve as funções de biblioteca que estão disponíveis para scripts de canário usando o runtime do Playwright para Node.js.
**Topics**
+ [
## execução
](#Synthetics_Library_Nodejs_Playwright_functions)
+ [
## newPage
](#Synthetics_Library_Nodejs_Playwright_function_newPage)
+ [
## feche
](#Synthetics_Library_Nodejs_Playwright_function_close)
+ [
## getDefaultLaunchOptions
](#Synthetics_Library_Nodejs_Playwright_function_getDefaultLaunchOptions)
+ [
## executeStep
](#Synthetics_Library_Nodejs_Playwright_function_executeStep)
## execução
Esta função inicia um navegador Chromium usando uma função de inicialização do Playwright e retorna o objeto do navegador. Ela descompacta os binários do navegador e inicia o navegador Chromium usando as opções padrão adequadas para um navegador sem cabeçalho. Para obter mais informações sobre a função `launch`, consulte [https://playwright.dev/docs/api/class-browsertype#browser-type-launch](https://playwright.dev/docs/api/class-browsertype#browser-type-launch) na documentação do Playwright.
**Usage**
```
const browser = await synthetics.launch();
```
**Argumentos**
`options` [options](https://playwright.dev/docs/api/class-browsertype#browser-type-launch) (opcional) é um conjunto configurável de opções a serem definidas no navegador.
**Devoluções**
Promise `` em que [Browser](https://playwright.dev/docs/api/class-browser) é uma instância do navegador do Playwright.
Se esta função for chamada novamente, um navegador aberto anteriormente será fechado antes de iniciar um novo navegador. É possível substituir os parâmetros de inicialização usados pelo CloudWatch Synthetics e passar outros parâmetros ao iniciar o navegador. Por exemplo, o trecho de código a seguir inicia um navegador com argumentos padrão e um caminho executável padrão, mas com uma janela de visualização de 800 x 600 pixels. Para obter mais informações, consulte as [opções de inicialização do Playwright](https://playwright.dev/docs/api/class-browsertype#browser-type-launch) na documentação do Playwright.
```
const browser = await synthetics.launch({
defaultViewport: {
"deviceScaleFactor": 1,
"width": 800,
"height": 600
}});
```
Você também pode adicionar ou substituir os sinalizadores do Chromium passados por padrão para o navegador. Por exemplo, você pode desabilitar a segurança da Web ao adicionar um sinalizador `--disable-web-security` para argumentos nos parâmetros de inicialização do CloudWatch Synthetics:
```
// This function adds the --disable-web-security flag to the launch parameters
const defaultOptions = await synthetics.getDefaultLaunchOptions();
const launchArgs = [...defaultOptions.args, '--disable-web-security'];
const browser = await synthetics.launch({
args: launchArgs
});
```
## newPage
A função `newPage()` cria e retorna uma nova página do Playwright. O Synthetics configura automaticamente uma conexão do Chrome DevTools Protocol (CDP) para permitir capturas de rede para geração de arquivos HTTP (HAR).
**Usage**
Use `newPage()` em uma das seguintes opções:
**1. Criar uma página em um novo contexto de navegador:**
```
const page = await synthetics.newPage(browser);
```
**2. Criar uma página em um contexto de navegador específico:**
```
// Create a new browser context
const browserContext = await browser.newContext();
// Create a new page in the specified browser context
const page = await synthetics.newPage(browserContext)
```
**Argumentos**
Aceita a instância [Browser](https://playwright.dev/docs/api/class-browser) ou [BrowserContext](https://playwright.dev/docs/api/class-browsercontext) do Playwright.
**Devoluções**
Promise em que Page é uma instância [Page](https://playwright.dev/docs/api/class-page) do Playwright.
## feche
Fecha o navegador aberto no momento.
**Usage**
```
await synthetics.close();
```
É recomendável fechar o navegador em um bloco `finally` do script.
**Argumentos**
Nenhum
**Devoluções**
Retorna Promise usada pela função de inicialização do Synthetics para iniciar o navegador.
## getDefaultLaunchOptions
A função `getDefaultLaunchOptions()` retorna as opções de inicialização do navegador que serão usadas pelo CloudWatch Synthetics.
**Usage**
```
const defaultOptions = await synthetics.getDefaultLaunchOptions();
```
**Argumentos**
Nenhum
**Devoluções**
Retorna as [opções de inicialização](https://playwright.dev/docs/api/class-browsertype#browser-type-launch) do Playwright usadas pela função `launch` do Synthetics para iniciar o navegador.
## executeStep
A função `executeStep` é usada para executar uma etapa em um script do Synthetics. No CloudWatch Synthetics, uma etapa do Synthetics é uma forma de dividir seu script do canário em uma série de ações claramente definidas, permitindo que você monitore diferentes partes de sua jornada de aplicação separadamente. Para cada etapa, o CloudWatch Synthetics faz o seguinte:
+ Obtém automaticamente uma captura de tela antes do início da etapa e após sua conclusão. Você também pode obter capturas de tela dentro de uma etapa. As capturas de tela são realizadas por padrão, mas podem ser desativadas usando as configurações do Synthetics.
+ Um relatório, incluindo um resumo, dos detalhes da execução da etapa, como a duração de uma etapa, os status `pass` ou `fail`, os URLs das páginas de origem e destino, as capturas de tela associadas etc., é criado para cada execução do canário. Ao escolher uma execução no console do CloudWatch Synthetics, você pode visualizar os detalhes da execução de cada etapa na guia **Etapa**.
+ As métricas `SuccessPercent` e `Duration` do CloudWatch são emitidas para cada etapa, permitindo que os usuários monitorem a disponibilidade e a latência de cada etapa.
**Usage**
```
await synthetics.executeStep("mystepname", async function () {
await page.goto(url, { waitUntil: 'load', timeout: 30000 });
}
```
**nota**
As etapas devem ser executadas sequencialmente. Certifique-se de usar `await` em promises.
**Argumentos**
+ `stepName` string (obrigatória) (booliano): nome da etapa do Synthetics.
+ `functionToExecute` função assíncrona (obrigatória): a função que você deseja que o Synthetics execute. Essa função deve conter a lógica da etapa.
+ `stepConfig` objeto (opcional): a configuração da etapa substitui a configuração global de Synthetics para esta etapa.
+ `continueOnStepFailure` booliano (opcional): se você deve continuar ou não executando o script do canário após esta etapa falhar.
+ `screenshotOnStepStart` booliano (opcional): se deve ou não obter uma captura de tela no início desta etapa.
+ `screenshotOnStepSuccess` booliano (opcional): se deve ou não obter uma captura de tela se esta etapa tiver êxito.
+ `screenshotOnStepFailure` booliano (opcional): se deve ou não obter uma captura de tela se esta etapa falhar.
+ `page`: objeto de página do Playwright (opcional)
Um objeto de página do Playwright. O Synthetics usa esse objeto de página para obter capturas de tela e URLs. Por padrão, o Synthetics usa a página do Playwright criada quando a função `synthetics.newPage()` é chamada para capturar detalhes da página, como capturas de tela e URLs.
**Devoluções**
Retorna uma Promise que é resolvida com o valor retornado pela função ` functionToExecute`. Para ver um exemplo de script, consulte [Código de exemplo para scripts do canário](CloudWatch_Synthetics_Canaries_Samples.md) neste guia.
# Funções de biblioteca disponíveis para scripts de canário Node.js usando o Puppeteer
Esta seção descreve as funções de biblioteca disponíveis para scripts de canário Node.js.
**Topics**
+ [
## Classes de biblioteca do Node.js e funções que se aplicam a todos os canaries
](#CloudWatch_Synthetics_Library_allcanaries)
+ [
## Classes de biblioteca do Node.js e funções que se aplicam somente a canaries de interface do usuário
](#CloudWatch_Synthetics_Library_UIcanaries)
+ [
## Classes de biblioteca do Node.js e funções que se aplicam apenas a canaries de API
](#CloudWatch_Synthetics_Library_APIcanaries)
## Classes de biblioteca do Node.js e funções que se aplicam a todos os canaries
As seguintes funções de biblioteca para Node.js do CloudWatch Synthetics são úteis para todos os canaries.
**Topics**
+ [
### Classe Synthetics
](#CloudWatch_Synthetics_Library_Synthetics_Class_all)
+ [
### Classe SyntheticsConfiguration
](#CloudWatch_Synthetics_Library_SyntheticsConfiguration)
+ [
### Synthetics Logger
](#CloudWatch_Synthetics_Library_SyntheticsLogger)
+ [
### SyntheticsLogHelper class
](#CloudWatch_Synthetics_Library_SyntheticsLogHelper)
### Classe Synthetics
As funções a seguir para todos os canaries estão na classe 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` descreve o erro, e `ex` é a exceção encontrada
Você pode usar `addExecutionError` para definir erros de execução eu seu canário. Ele faz o canário falhar sem interromper a execução do script. Também não afeta suas métricas `successPercent`.
Convém rastrear erros como erros de execução somente se eles não forem importantes para indicar o sucesso ou falha do script do canário.
A seguir há um exemplo de uso do elemento `addExecutionError`. Você está monitorando a disponibilidade de seu endpoint e fazendo capturas de tela depois que a página foi carregada. Como a falha de obter uma captura de tela não determina a disponibilidade do endpoint, é possível detectar quaisquer erros encontrados durante a captura de tela e adicioná-los como erros de execução. Suas métricas de disponibilidade ainda indicarão que o endpoint está ativo e em execução, mas o status do canário será marcado como falha. O bloco de código de exemplo a seguir captura esse erro e adiciona-o como erro de execução.
```
try {
await synthetics.takeScreenshot(stepName, "loaded");
} catch(ex) {
synthetics.addExecutionError('Unable to take screenshot ', ex);
}
```
#### getCanaryName();
Retorna o nome do canário.
#### getCanaryArn();
Retorna o ARN do canário.
#### getCanaryUserAgentString();
Retorna o agente de usuário personalizado do canário.
#### getRuntimeVersion();
Essa função está disponível na versão de runtime `syn-nodejs-puppeteer-3.0` e posteriores. Ele retorna a versão de runtime do Synthetics do canário. Por exemplo, o valor de retorno pode ser `syn-nodejs-puppeteer-3.0`.
#### getLogLevel();
Recupera o nível de log atual para a biblioteca do Synthetics. Os valores possíveis são os seguintes:
+ `0`: debug
+ `1`: info
+ `2`: warn
+ `3`: error
Exemplo:
```
let logLevel = synthetics.getLogLevel();
```
#### setLogLevel();
Define o nível de log para a biblioteca do Synthetics. Os valores possíveis são os seguintes:
+ `0`: debug
+ `1`: info
+ `2`: warn
+ `3`: error
Exemplo:
```
synthetics.setLogLevel(0);
```
### Classe SyntheticsConfiguration
Essa classe está disponível apenas na versão de runtime `syn-nodejs-2.1` ou posteriores.
Você pode usar a classe `SyntheticsConfiguration` para configurar o comportamento das funções da biblioteca do Synthetics. Por exemplo, você pode usar essa classe para configurar a função `executeStep()` para não obter capturas de tela.
É possível definir as configurações do CloudWatch Synthetics no nível global, que são aplicadas a todas as etapas dos canaries. Também é possível substituir essas configurações no nível de etapa passando pares de chave/valor de configuração.
Você pode transmitir opções no nível de etapa. Veja exemplos em [async executeStep(stepName, functionToExecute, [stepConfig]);](#CloudWatch_Synthetics_Library_executeStep) e [executeHttpStep(stepName, requestOptions, [callback], [stepConfig])](#CloudWatch_Synthetics_Library_executeHttpStep).
**Topics**
+ [
#### setConfig(options)
](#CloudWatch_Synthetics_Library_setConfig)
+ [
#### Monitoramento visual
](#CloudWatch_Synthetics_Library_SyntheticsLogger_VisualTesting)
#### setConfig(options)
` options ` é um objeto, que é um conjunto de opções configuráveis para seu canário. As seções a seguir explicam os campos possíveis em ` options `.
##### setConfig(options) para todos os canaries
Para canários que usam `syn-nodejs-puppeteer-3.2` ou posterior, as **(options)** para o **setConfig** podem incluir estes parâmetros:
+ `includeRequestHeaders` (booliano): se deve incluir ou não cabeçalhos de solicitação no relatório. O padrão é `false`.
+ `includeResponseHeaders` (booliano): se deve incluir ou não cabeçalhos de resposta no relatório. O padrão é `false`.
+ `restrictedHeaders` (matriz): uma lista de valores de cabeçalho a serem ignorados, se os cabeçalhos forem incluídos. Isso se aplica aos cabeçalhos de solicitação e de resposta. Por exemplo, é possível ocultar suas credenciais passando **includeRequestHeaders** como `true` e **restrictedHeaders** como `['Authorization']`.
+ `includeRequestBody` (booliano): se deve incluir ou não o corpo da solicitação no relatório. O padrão é `false`.
+ `includeResponseBody` (booliano): se deve incluir ou não o corpo da resposta no relatório. O padrão é `false`.
**Importante**
Se você habilitar `includeResponseBody` ou ` logResponseBody`, o objeto de dados não será retornado na resposta para algumas APIs, como clientes aws-sdk v3. Isso ocorre devido a uma limitação do Node.js e ao tipo de objeto usado na resposta.
**setConfig(options) em relação a métricas do CloudWatch**
Para canários que usam `syn-nodejs-puppeteer-3.1` ou posterior, as **(options)** para **setConfig** podem incluir os parâmetros boolianos a seguir que determinam quais métricas serão publicadas pelo canário. O padrão para cada uma dessas opções é `true`. As opções que começam com `aggregated` determinam se a métrica será emitida sem a dimensão ` CanaryName`. É possível usar essas métricas para ver os resultados agregados de todos os seus canaries. As outras opções determinam se a métrica será emitida com a dimensão `CanaryName`. Você pode usar essas métricas para ver os resultados de cada canário individual.
Para obter uma lista de métricas do CloudWatch emitidas por canaries, consulte [Métricas do CloudWatch publicadas por canaries](CloudWatch_Synthetics_Canaries_metrics.md).
+ `failedCanaryMetric` (booliano): se deverá ou não emitir a métrica ` Failed` (com a dimensão `CanaryName`) para esse canário. O padrão é `true`.
+ `failedRequestsMetric` (booliano): se deverá ou não emitir a métrica `Failed requests` (com a dimensão `CanaryName`) para esse canário. O padrão é `true`.
+ `_2xxMetric` (booliano): se deverá ou não emitir a métrica `2xx` (com a dimensão `CanaryName`) para esse canário. O padrão é `true`.
+ `_4xxMetric` (booliano): se deverá ou não emitir a métrica `4xx` (com a dimensão `CanaryName`) para esse canário. O padrão é `true`.
+ `_5xxMetric` (booliano): se deverá ou não emitir a métrica `5xx` (com a dimensão `CanaryName`) para esse canário. O padrão é `true`.
+ `stepDurationMetric` (booliano): se deverá ou não emitir a métrica `Step duration` (com as dimensões `CanaryName` `StepName`) para esse canário. O padrão é `true`.
+ `stepSuccessMetric` (booliano): se deverá ou não emitir a métrica `Step success` (com as dimensões `CanaryName` `StepName`) para esse canário. O padrão é `true`.
+ `aggregatedFailedCanaryMetric` (booliano): se deverá ou não emitir a métrica `Failed` (sem a dimensão `CanaryName`) para esse canário. O padrão é `true`.
+ `aggregatedFailedRequestsMetric` (booliano): se deverá ou não emitir a métrica `Failed Requests` (sem a dimensão `CanaryName`) para esse canário. O padrão é `true`.
+ `aggregated2xxMetric` (booliano): se deverá ou não emitir a métrica ` 2xx` (sem a dimensão `CanaryName`) para esse canário. O padrão é `true`.
+ `aggregated4xxMetric` (booliano): se deverá ou não emitir a métrica ` 4xx` (sem a dimensão `CanaryName`) para esse canário. O padrão é `true`.
+ `aggregated5xxMetric` (booliano): se deverá ou não emitir a métrica ` 5xx` (sem a dimensão `CanaryName`) para esse canário. O padrão é `true`.
+ `visualMonitoringSuccessPercentMetric` (booliano): se deverá ou não emitir a métrica `visualMonitoringSuccessPercent` para esse canário. O padrão é `true`.
+ `visualMonitoringTotalComparisonsMetric` (booliano): se deverá ou não emitir a métrica `visualMonitoringTotalComparisons` para esse canário. O padrão é `false`.
+ `includeUrlPassword` (boolieano): se deverá ou não incluir uma senha que aparece na URL. Por padrão, as senhas que aparecem em URLs são editadas de logs e relatórios, para evitar a divulgação de dados sigilosos. O padrão é `false`.
+ `restrictedUrlParameters` (matriz): uma lista de parâmetros de caminho de URL ou consulta a serem editados. Aplica-se a URLs que aparecem em logs, relatórios e erros. O parâmetro faz distinção entre maiúsculas e minúsculas. É possível transmitir um asterisco (\$1) como um valor para editar todos os valores de parâmetro de consulta e caminho de URL. O padrão é uma matriz vazia.
+ `logRequest` (booliano): se cada solicitação em logs do canário será registrada ou não. Para canaries de interface do usuário, isso registra cada solicitação enviada pelo navegador. O padrão é `true`.
+ `logResponse` (booliano): se cada resposta em logs do canário será registrada ou não. Para canaries de interface do usuário, registra todas as respostas recebidas pelo navegador. O padrão é `true`.
+ `logRequestBody` (booliano): se os corpos da solicitação serão registrados junto com as solicitações em logs do canário. Essa configuração se aplica somente se `logRequest` é `true`. O padrão é `false` .
+ `logResponseBody` (booliano): se os corpos da resposta serão registrados junto com as respostas em logs do canário. Essa configuração se aplica somente se `logResponse` é `true`. O padrão é ` false`.
**Importante**
Se você habilitar `includeResponseBody` ou ` logResponseBody`, o objeto de dados não será retornado na resposta para algumas APIs, como clientes aws-sdk v3. Isso ocorre devido a uma limitação do Node.js e ao tipo de objeto usado na resposta.
+ `logRequestHeaders` (booliano): se os cabeçalhos da solicitação serão registrados junto com as solicitações em logs do canário. Essa configuração se aplica somente se `logRequest` é `true`. O padrão é ` false`.
`includeRequestHeaders` habilita cabeçalhos em artefatos.
+ `logResponseHeaders` (booliano): se os cabeçalhos da resposta serão registrados junto com as respostas em logs do canário. Essa configuração se aplica somente se `logResponse` é `true`. O padrão é ` false`.
`includeResponseHeaders` habilita cabeçalhos em artefatos.
**nota**
As métricas `Duration` e `SuccessPercent` são sempre emitidas para cada canário, tanto com como sem a métrica `CanaryName`.
##### Métodos para habilitar ou desabilitar métricas
**disableAggregatedRequestMetrics()**
Não permite que o canário emita todas as métricas de solicitação emitidas sem a dimensão `CanaryName`.
**disableRequestMetrics()**
Desabilita todas as métricas de solicitação, inclusive métricas por canário e métricas agregadas em todos os canários.
**disableStepMetrics()**
Desativa todas as métricas de etapa, incluindo métricas de sucesso e de duração da etapa.
**enableAggregatedRequestMetrics()**
Habilita o canário a emitir todas as métricas de solicitação emitidas sem a dimensão ` CanaryName`.
**enableRequestMetrics()**
Habilita todas as métricas de solicitação, inclusive métricas por canário e métricas agregadas em todos os canários.
**enableStepMetrics()**
Ativa todas as métricas de etapa, incluindo métricas de sucesso e métricas de duração da etapa.
**get2xxMetric()**
Retorna se o canário emitirá ou não uma métrica `2xx` com a dimensão ` CanaryName`.
**get4xxMetric()**
Retorna se o canário emitirá ou não uma métrica `4xx` com a dimensão ` CanaryName`.
**get5xxMetric()**
Retorna se o canário emitirá ou não uma métrica `5xx` com a dimensão ` CanaryName`.
**getAggregated2xxMetric()**
Retorna se o canário emitirá ou não uma métrica `2xx` sem a dimensão.
**getAggregated4xxMetric()**
Retorna se o canário emitirá ou não uma métrica `4xx` sem a dimensão.
**getAggregatedFailedCanaryMetric()**
Retorna se o canário emitirá ou não uma métrica `Failed` sem a dimensão.
**getAggregatedFailedRequestsMetric()**
Retorna se o canário emitirá ou não uma métrica `Failed requests` sem a dimensão .
**getAggregated5xxMetric()**
Retorna se o canário emitirá ou não uma métrica `5xx` sem a dimensão .
**getFailedCanaryMetric()**
Retorna se o canário emitirá ou não uma métrica `Failed` com a dimensão ` CanaryName`.
**getFailedRequestsMetric()**
Retorna se o canário emitirá ou não uma métrica `Failed requests` com a dimensão `CanaryName`.
**getStepDurationMetric()**
Retorna se o canário emitirá ou não uma métrica `Duration` com a dimensão ` CanaryName` para esse canário.
**getStepSuccessMetric()**
Retorna se o canário emitirá ou não uma métrica `StepSuccess` com a dimensão ` CanaryName` para esse canário.
**with2xxMetric(\$12xxMetric)**
Aceita um argumento booliano, que especifica se deverá emitir ou não uma métrica `2xx` com a dimensão `CanaryName` para esse canário.
**with4xxMetric(\$14xxMetric)**
Aceita um argumento booliano, que especifica se deverá emitir ou não uma métrica `4xx` com a dimensão `CanaryName` para esse canário.
**with5xxMetric(\$15xxMetric)**
Aceita um argumento booliano, que especifica se deverá emitir ou não uma métrica `5xx` com a dimensão `CanaryName` para esse canário.
**withAggregated2xxMetric(aggregated2xxMetric)**
Aceita um argumento booliano, que especifica se deverá emitir ou não uma métrica `2xx` sem dimensão para esse canário.
**withAggregated4xxMetric(aggregated4xxMetric)**
Aceita um argumento booliano, que especifica se deverá emitir ou não uma métrica `4xx` sem dimensão para esse canário.
**withAggregated5xxMetric(aggregated5xxMetric)**
Aceita um argumento booliano, que especifica se deverá emitir ou não uma métrica `5xx` sem dimensão para esse canário.
** withAggregatedFailedCanaryMetric(aggregatedFailedCanaryMetric)**
Aceita um argumento booliano, que especifica se deverá emitir ou não uma métrica `Failed` sem dimensão para esse canário.
** withAggregatedFailedRequestsMetric(aggregatedFailedRequestsMetric)**
Aceita um argumento booliano, que especifica se deverá emitir ou não uma métrica `Failed requests` sem dimensão para esse canário.
**withFailedCanaryMetric(failedCanaryMetric)**
Aceita um argumento booliano, que especifica se deverá emitir ou não uma métrica `Failed` com a dimensão `CanaryName` para esse canário.
**withFailedRequestsMetric(failedRequestsMetric)**
Aceita um argumento booliano, que especifica se deverá emitir ou não uma métrica `Failed requests` com a dimensão `CanaryName` para esse canário.
**withStepDurationMetric(stepDurationMetric)**
Aceita um argumento booliano, que especifica se deverá emitir ou não uma métrica `Duration` com a dimensão `CanaryName` para esse canário.
**withStepSuccessMetric(stepSuccessMetric)**
Aceita um argumento booliano, que especifica se deverá emitir ou não uma métrica ` StepSuccess` com a dimensão `CanaryName` para esse canário.
##### Métodos para habilitar ou desabilitar outros recursos
**withHarFile()**
Aceita um argumento booliano, que especifica se deverá ou não ser criado um arquivo HAR para esse canário.
**withStepsReport()**
Aceita um argumento booliano, que especifica se deverá ou não ser emitido um relatório do resumo de execução de etapas para esse canário.
**withIncludeUrlPassword()**
Aceita um argumento booliano, que especifica se as senhas que aparecem nas URLs em logs e relatórios serão incluídas ou não.
**withRestrictedUrlParameters()**
Aceira uma matriz de parâmetros de caminho de URL ou consulta a serem editados. Aplica-se a URLs que aparecem em logs, relatórios e erros. É possível passar um asterisco (\$1) como um valor para editar todos os valores de parâmetro de consulta e caminho de URL
**withLogRequest()**
Aceita um argumento booliano, que especifica se cada solicitação deverá ou não ser registrada nos logs do canário.
**withLogResponse()**
Aceita um argumento booliano, que especifica se cada resposta deverá ou não ser registrada nos logs do canário.
**withLogRequestBody()**
Aceita um argumento booliano, que especifica se cada corpo da solicitação deverá ou não ser registrado nos logs do canário.
**withLogResponseBody()**
Aceita um argumento booliano, que especifica se cada corpo da resposta deverá ou não ser registrado nos logs do canário.
**withLogRequestHeaders()**
Aceita um argumento booliano, que especifica se cada cabeçalho de solicitação deverá ou não ser registrado nos logs do canário.
**withLogResponseHeaders()**
Aceita um argumento booliano, que especifica se cada cabeçalho de resposta deverá ou não ser registrado nos logs do canário.
**getHarFile()**
Retorna se o canário criará ou não um arquivo HAR.
**getStepsReport()**
Retorna se o canário emitirá ou não um relatório do resumo de execução de etapa.
**getIncludeUrlPassword()**
Retorna se o canário incluirá ou não as senhas que aparecem nas URLs em logs e relatórios.
**getRestrictedUrlParameters()**
Retorna se o canário editará ou não o caminho da URL ou os parâmetros de consulta.
**getLogRequest()**
Retorna se o canário registrará ou não cada solicitação nos logs do canário.
**getLogResponse()**
Retorna se o canário registrará ou não cada resposta nos logs do canário.
**getLogRequestBody()**
Retorna se o canário registrará ou não cada corpo da solicitação nos logs do canário.
**getLogResponseBody()**
Retorna se o canário registrará ou não cada corpo da resposta nos logs do canário.
**getLogRequestHeaders()**
Retorna se o canário registrará ou não cada cabeçalho de solicitação nos logs do canário.
**getLogResponseHeaders()**
Retorna se o canário registrará ou não cada cabeçalho de resposta nos logs do canário.
**Funções para todos os canaries**
+ `withIncludeRequestHeaders`(includeRequestHeaders)
+ `withIncludeResponseHeaders`(IncludeResponseHeaders)
+ `withRestrictedHeaders`(restrictedHeaders)
+ `withIncludeRequestBody`(includeRequestBody)
+ `withIncludeResponseBody`(includeResponseBody)
+ `enableReportingOptions`(): habilita todas as opções de relatórios (**includeRequestBody**, **includeResponseHeaders**, **includeRequestBody** e **includeResponseBody**).
+ `disableReportingOptions`(): desabilita todas as opções de relatórios (**includeRequestBody**, **includeResponseHeaders**, **includeRequestBody** e **includeResponseBody**).
##### setConfig(options) para os canaries de interface do usuário
Para os canaries de interface do usuário, **setConfig** pode incluir os seguintes parâmetros boolianos:
+ `continueOnStepFailure` (booliano): se continuará ou não executando o script do canário após a falha de uma etapa (isso se refere à função **executeStep**). Se alguma etapa falhar, a execução do canário ainda será marcada como falha. O padrão é `false`.
+ `harFile` (booliano): se criará ou não um arquivo HAR. O padrão é `True`.
+ `screenshotOnStepStart` (booliano): se fará ou nãi uma captura de tela antes de iniciar uma etapa.
+ `screenshotOnStepSuccess` (booliano): se fará ou não uma captura de tela depois de concluir uma etapa bem-sucedida.
+ `screenshotOnStepFailure` (booliano): se fará ou não uma captura de tela depois de que uma etapa falhar.
##### Métodos para habilitar ou desabilitar capturas de tela
**disableStepScreenshots()**
Desabilita todas as opções de captura de tela (screenshotOnStepStart, screenshotOnStepSuccess e screenshotOnStepFailure).
**enableStepScreenshots()**
Habilita todas as opções de captura de tela (screenshotOnStepStart, screenshotOnStepSuccess e screenshotOnStepFailure). Por padrão, todas essas métricas são permitidas.
**getScreenshotOnStepFailure()**
Retorna se o canário fará ou não uma captura de tela depois que uma etapa falhar.
**getScreenshotOnStepStart()**
Retorna se o canário fará ou não uma captura de tela antes de iniciar uma etapa.
**getScreenshotOnStepSuccess()**
Retorna se o canário fará ou não uma captura de tela depois que uma etapa for concluída.
**withScreenshotOnStepStart(screenshotOnStepStart)**
Aceita um argumento booliano, que indica se uma captura de tela deverá ou não ser obtida antes de iniciar uma etapa.
**withScreenshotOnStepSuccess(screenshotOnStepSuccess)**
Aceita um argumento booliano, que indica se uma captura de tela deverá ou não ser obtida após a conclusão de uma etapa.
**withScreenshotOnStepFailure(screenshotOnStepFailure)**
Aceita um argumento booliano, que indica se uma captura de tela deverá ou não ser obtida depois que uma etapa falhar.
**Uso em canaries de interface do usuário**
Primeiro, importe a dependência do Synthetics e busque a configuração.
```
// Import Synthetics dependency
const synthetics = require('@aws/synthetics-puppeteer');
// Get Synthetics configuration
const synConfig = synthetics.getConfiguration();
```
Em seguida, defina a configuração para cada opção chamando o método SetConfig usando uma das opções a seguir.
```
// Set configuration values
synConfig.setConfig({
screenshotOnStepStart: true,
screenshotOnStepSuccess: false,
screenshotOnStepFailure: false
});
```
Ou
```
synConfig.withScreenshotOnStepStart(false).withScreenshotOnStepSuccess(true).withScreenshotOnStepFailure(true)
```
Para desabilitar todas as capturas de tela, use a função `disableStepScreenshots()` como neste exemplo.
```
synConfig.disableStepScreenshots();
```
É possível habilitar e desabilitar as capturas de tela em qualquer ponto do código. Por exemplo, para desabilitar capturas de tela apenas para uma etapa, desabilite-as antes de executar essa etapa e habilite-as após a etapa.
##### setConfig(options) para canaries de API
Para os canaries de API, o **setConfig** pode incluir os seguintes parâmetros boolianos:
+ `continueOnHttpStepFailure` (booliano): se continuará ou não executando o script do canário após a falha de uma etapa HTTP (isso se refere à função **executeHttpStep**). Se alguma etapa falhar, a execução do canário ainda será marcada como falha. O padrão é `true`.
#### Monitoramento visual
O monitoramento visual compara capturas de tela feitas durante uma execução do canário com capturas de tela feitas durante uma execução do canário de linha de base. Se a discrepância entre as duas capturas de tela ultrapassar a porcentagem de limite, o canário falhará, e você poderá ver as áreas com diferenças destacadas na cor no relatório de execução do canário. O monitoramento visual é compatível com canaries que executam **syn-puppeteer-node-3.2** e posterior. Atualmente não é compatível com canaries que executam Python e Selenium.
Para habilitar o monitoramento visual, adicione a seguinte linha de código ao script do canário. Para obter mais detalhes, consulte [Classe SyntheticsConfiguration](#CloudWatch_Synthetics_Library_SyntheticsConfiguration).
```
syntheticsConfiguration.withVisualCompareWithBaseRun(true);
```
A primeira vez que o canário é executado corretamente após essa linha ser adicionada ao script, ele usa as capturas de tela obtidas durante a execução como linha de base para comparação. Após a primeira execução do canário, é possível usar o console do CloudWatch para editar o canário para fazer qualquer um destes procedimentos:
+ Defina a próxima execução do canário como a nova linha de base.
+ Estabeleça limites na captura de tela de linha de base atual para designar as áreas da captura de tela que deverão ser ignoradas durante comparações visuais.
+ Remova uma captura de tela que não será usada para monitoramento visual.
Para obter mais informações sobre como usar o console do CloudWatch para editar um canário, consulte [Editar ou excluir um canário](synthetics_canaries_deletion.md).
**Outras opções para monitoramento visual**
** syntheticsConfiguration.withVisualVarianceThresholdPercentage(desiredPercentage)**
Defina a porcentagem aceitável para a variação da captura de tela em comparações visuais.
** syntheticsConfiguration.withVisualVarianceHighlightHexColor("\$1fafa00")**
Defina a cor de realce que designa as áreas de variação ao examinar relatórios de execução do canário que usam monitoramento visual.
** syntheticsConfiguration.withFailCanaryRunOnVisualVariance(failCanary)**
Defina se o canário falha ou não quando há uma diferença visual que é maior do que o limite. O padrão é o canário falhar.
### Synthetics Logger
O SyntheticsLogger grava logs no console e em um arquivo de log local no mesmo nível de log. Este arquivo de logs é gravado em ambos os locais apenas se o nível de registo estiver no nível de registo pretendido ou abaixo da função de registo que foi chamada.
As instruções de log no arquivo de log local são precedidas por "DEBUG: ", "INFO: " e assim por diante para corresponder ao nível de log da função que foi chamada.
Você pode usar o SyntheticsLogger presumindo que você deseja executar a Biblioteca do Synthetics no mesmo nível de log que seu log do canário do Synthetics.
Não é necessário usar o SyntheticsLogger para criar um arquivo de log que está carregando o local de resultados do S3. Em vez disso, você pode criar um arquivo de log diferente na pasta ` /tmp`. Todos os arquivos criados sob a pasta `/tmp` são carregados para o local de resultados no S3 como artefatos.
Como usar o registrador da biblioteca do Synthetics:
```
const log = require('@aws/synthetics-logger');
```
Definições de funções úteis:
**log.debug(*message*, *ex*);**
Parâmetros: *message* é a mensagem a ser registrada em log e *ex* é a exceção, se houver, a ser registrada em log.
Exemplo:
```
log.debug("Starting step - login.");
```
**log.error(*message*, *ex*);**
Parâmetros: *message* é a mensagem a ser registrada em log e *ex* é a exceção, se houver, a ser registrada em log.
Exemplo:
```
try {
await login();
catch (ex) {
log.error("Error encountered in step - login.", ex);
}
```
**log.info(*message*, *ex*);**
Parâmetros: *message* é a mensagem a ser registrada em log e *ex* é a exceção, se houver, a ser registrada em log.
Exemplo:
```
log.info("Successfully completed step - login.");
```
**log.log(*message*, *ex*);**
Este é um alias para `log.info`.
Parâmetros: *message* é a mensagem a ser registrada em log e *ex* é a exceção, se houver, a ser registrada em log.
Exemplo:
```
log.log("Successfully completed step - login.");
```
**log.warn(*message*, *ex*);**
Parâmetros: *message* é a mensagem a ser registrada em log e *ex* é a exceção, se houver, a ser registrada em log.
Exemplo:
```
log.warn("Exception encountered trying to publish CloudWatch Metric.", ex);
```
### SyntheticsLogHelper class
A classe `SyntheticsLogHelper` está disponível no runtime ` syn-nodejs-puppeteer-3.2` e em tempos de execução posteriores. Ela já foi inicializada na biblioteca do CloudWatch Synthetics e está definida com a configuração do Synthetics. É possível adicioná-la como uma dependência em seu script. Essa classe permite limpar URLs, cabeçalhos e mensagens de erro para editar informações sigilosas.
**nota**
O Synthetics limpa todas as URLs e mensagens de erro que registra antes de incluí-las em logs, relatórios, arquivos HAR e erros de execução do canário com base na configuração `restrictedUrlParameters` do Synthetics. Somente será necessário usar ` getSanitizedUrl` ou `getSanitizedErrorMessage` se você estiver registrando URLs ou erros em seu script. O Synthetics não armazena artefatos do canário, exceto erros do canário lançados pelo script. Artefatos de execução do canário são armazenados em sua conta do cliente. Para obter mais informações, consulte [Considerações de segurança para canaries do Synthetics](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)
Essa função está disponível em `syn-nodejs-puppeteer-3.2` e posteriores. Ela retorna strings de url limpas com base na configuração. Você pode optar por editar parâmetros de URL sigilosos, como password e access\$1token, definindo a propriedade `restrictedUrlParameters`. Por padrão, as senhas em URLs são editadas. É possível habilitar senhas de URL, se necessário, definindo `includeUrlPassword`como true.
Essa função lançará um erro se a URL passada não for uma URL válida.
**Parâmetros **
+ *url*é uma string e é a URL a ser limpa.
+ *stepConfig* (Opcional) substitui a configuração global de Synthetics para essa função. Se `stepConfig` não for passado, será usada a configuração global para limpar a URL.
**Exemplo **
Este exemplo usa a seguinte URL de exemplo: ` https://example.com/learn/home?access_token=12345&token_type=Bearer&expires_in=1200`. Neste exemplo, `access_token` contém suas informações sigilosas que não devem ser registradas. Observe que os serviços do Synthetics não armazenam artefatos de execução do canário. Artefatos como logs, capturas de tela e relatórios são armazenados em um bucket do Amazon S3 em sua conta de cliente.
A primeira etapa é definir a configuração do 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);
```
Em seguida, limpar e registrar em log o 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');
```
Isso registra o seguinte em seu log do canário.
```
My example url is: https://example.com/learn/home?access_token=REDACTED&token_type=Bearer&expires_in=1200
```
É possível substituir a configuração Synthetics para uma URL aprovando um parâmetro opcional que contenha opções de configuração Synthetics, como no exemplo a seguir.
```
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);
```
O exemplo anterior edita todos os parâmetros de consulta e é registrado desta forma:
```
My example url is: https://example.com/learn/home?access_token=REDACTED&token_type=REDACTED&expires_in=REDACTED
```
#### getSanitizedErrorMessage
Essa função está disponível em `syn-nodejs-puppeteer-3.2` e posteriores. Retorna strings de erro limpas, limpando as URLs presentes com base na configuração do Synthetics. Você pode escolher substituir a configuração global do Synthetics ao chamar essa função aprovando um parâmetro `stepConfig` opcional.
**Parâmetros **
+ *erro* é o erro ao limpar. Pode ser um objeto Error ou uma string.
+ *stepConfig* (Opcional) substitui a configuração global de Synthetics para essa função. Se `stepConfig` não for passado, será usada a configuração global para limpar a URL.
**Exemplo **
Este exemplo usa o seguinte erro: ` Failed to load url: https://example.com/learn/home?access_token=12345&token_type=Bearer&expires_in=1200`
A primeira etapa é definir a configuração do 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'];
});
```
Em seguida, limpar e registrar em log a mensagem de erro
```
// 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);
}
```
Isso registra o seguinte no log do canário.
```
Failed to load url: https://example.com/learn/home?access_token=REDACTED&token_type=Bearer&expires_in=1200
```
#### getSanitizedHeaders(headers, stepConfig=null)
Essa função está disponível em `syn-nodejs-puppeteer-3.2` e posteriores. Retorna cabeçalhos limpos com base na propriedade `restrictedHeaders` de ` syntheticsConfiguration`. Os cabeçalhos especificados na propriedade `restrictedHeaders` são editados a partir de logs, arquivos HAR e relatórios.
**Parâmetros **
+ *headers* é um objeto que contém os cabeçalhos a serem limpos.
+ *stepConfig* (Opcional) substitui a configuração global de Synthetics para essa função. Se `stepConfig` não for passado, será usada a configuração global para limpar os cabeçalhos.
## Classes de biblioteca do Node.js e funções que se aplicam somente a canaries de interface do usuário
As seguintes funções de biblioteca para Node.js do CloudWatch Synthetics são úteis apenas para canaries de interface do usuário.
**Topics**
+ [
### Classe Synthetics
](#CloudWatch_Synthetics_Library_Synthetics_Class)
+ [
### Classe BrokenLinkCheckerReport
](#CloudWatch_Synthetics_Library_BrokenLinkCheckerReport)
+ [
### Classe SyntheticsLink
](#CloudWatch_Synthetics_Library_SyntheticsLink)
### Classe Synthetics
As funções a seguir estão na classe 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 class
](#CloudWatch_Synthetics_Library_RequestResponseLogHelper)
+ [
#### setRequestResponseLogHelper();
](#CloudWatch_Synthetics_Library_setRequestResponseLogHelper)
+ [
#### async takeScreenshot(name, suffix);
](#CloudWatch_Synthetics_Library_takeScreenshot)
#### async addUserAgent(page, userAgentString);
Esta função acrescenta *userAgentString* ao cabeçalho "User-Agent" da página especificada.
Exemplo:
```
await synthetics.addUserAgent(page, "MyApp-1.0");
```
Resulta no cabeçalho "User-Agent" da página que está sendo definido como ` browsers-user-agent-header-valueMyApp-1.0`
#### async executeStep(stepName, functionToExecute, [stepConfig]);
Executa o passo fornecido, envolvendo-o com logs de iniciar/passar/falhar, capturas de tela de iniciar/passar/falhar e métricas de aprovação/reprovação e duração.
**nota**
Se você estiver usando `syn-nodejs-2.1` ou um runtime posterior, será possível configurar se as capturas de tela serão obtidas ou não e quando serão obtidas. Para obter mais informações, consulte [Classe SyntheticsConfiguration](#CloudWatch_Synthetics_Library_SyntheticsConfiguration).
A função `executeStep` também faz o seguinte:
+ Registra que a etapa começou.
+ Faz uma captura de tela chamada `-starting`.
+ Inicia um temporizador.
+ Executa a função fornecida.
+ Se a função retornar normalmente, ela contará como aprovada. Se a função apresentar erro, ela contará como falha.
+ Encerra o temporizador.
+ Registra se a etapa foi aprovada ou falhou
+ Faz uma captura de tela chamada `-succeeded` ou ` -failed`.
+ Emite a métrica `stepName` `SuccessPercent`, 100 para aprovação ou 0 para falha.
+ Emite a métrica `stepName` `Duration` com um valor de acordo com os horários inicial e final da etapa.
+ Finalmente, retorna o que `functionToExecute` retornou ou lança novamente o que `functionToExecute` lançou.
Se o canário usar `syn-nodejs-2.0` ou um runtime posterior, essa função também adicionará um resumo de execução de etapa ao relatório do canário. O resumo contém detalhes sobre cada etapa, como hora de início, hora de término, status (PASSED/FAILED), motivo da falha (se for o caso) e capturas de tela obtidas durante a execução de cada etapa.
Exemplo:
```
await synthetics.executeStep('navigateToUrl', async function (timeoutInMillis = 30000) {
await page.goto(url, {waitUntil: ['load', 'networkidle0'], timeout: timeoutInMillis});});
```
Resposta:
Retorna o que `functionToExecute` retornou.
**Atualizações com syn-nodejs-2.2**
Começando com `syn-nodejs-2.2`, você pode, opcionalmente, passar configurações de etapa para substituir as configurações do CloudWatch Synthetics no nível de etapa. Para obter uma lista de opções que você pode passar para `executeStep`, consulte [Classe SyntheticsConfiguration](#CloudWatch_Synthetics_Library_SyntheticsConfiguration).
O exemplo a seguir substitui a configuração padrão `false` de ` continueOnStepFailure` para `true` e especifica quando obter capturas de tela.
```
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();
A função `getDefaultLaunchOptions()` retorna as opções de inicialização do navegador que serão usadas pelo CloudWatch Synthetics. Para obter mais informações, consulte [Tipos de opções de lançamento](https://pptr.dev/browsers-api/browsers.launchoptions/)
```
// This function returns default launch options used by Synthetics.
const defaultOptions = await synthetics.getDefaultLaunchOptions();
```
#### getPage();
Retorna a página aberta atual como um objeto Puppeteer. Para obter mais informações, consulte [Puppeteer API v1.14.0](https://github.com/puppeteer/puppeteer/blob/v1.14.0/docs/api.md).
Exemplo:
```
let page = await synthetics.getPage();
```
Resposta:
A página (objeto Puppeteer) que está aberta atualmente na sessão atual do navegador.
#### getRequestResponseLogHelper();
**Importante**
Em canários que usam o runtime `syn-nodejs-puppeteer-3.2` ou posteriores, essa função está descontinuada junto com a classe `RequestResponseLogHelper`. Qualquer uso desta função faz exibe um aviso em seus registros do canário. Essa função será removida em futuras versões do runtime. Se você estiver usando esta função, substitua por [RequestResponseLogHelper class](#CloudWatch_Synthetics_Library_RequestResponseLogHelper).
Use essa função como padrão de criador para ajustar os sinalizadores de log de solicitação e resposta.
Exemplo:
```
synthetics.setRequestResponseLogHelper(getRequestResponseLogHelper().withLogRequestHeaders(false));;
```
Resposta:
```
{RequestResponseLogHelper}
```
#### launch(options)
As opções para essa função estão disponíveis apenas na versão do runtime `syn-nodejs-2.1` ou posteriores.
Essa função é usada apenas para canaries de interface do usuário. Ela fecha o navegador existente e inicia um novo.
**nota**
O CloudWatch Synthetics sempre inicia um navegador antes de começar a executar o script. Não é necessário chamar launch(), a menos que você queira iniciar um novo navegador com opções personalizadas.
(options) é um conjunto configurável de opções a serem definidas no navegador. Para obter mais informações, consulte [Launch options type](https://pptr.dev/browsers-api/browsers.launchoptions/).
Se você chamar esta função sem opções, o Synthetics iniciará um navegador com argumentos padrão, `executablePath` e `defaultViewport`. O visor padrão no CloudWatch Synthetics é 1920 por 1080.
É possível substituir os parâmetros de inicialização usados pelo CloudWatch Synthetics e passar outros parâmetros ao iniciar o navegador. Por exemplo, o trecho de código a seguir inicia um navegador com argumentos padrão e um caminho executável padrão, mas com um visor de 800 x 600.
```
await synthetics.launch({
defaultViewport: {
"deviceScaleFactor": 1,
"width": 800,
"height": 600
}});
```
O código de exemplo a seguir adiciona um novo parâmetro `ignoreHTTPSErrors`para os parâmetros de inicialização do CloudWatch Synthetics:
```
await synthetics.launch({
ignoreHTTPSErrors: true
});
```
É possível desabilitar a segurança da Web adicionando uma sinalização `--disable-web-security` para args nos parâmetros de inicialização do CloudWatch Synthetics:
```
// 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
**Importante**
Em canários que usam o runtime `syn-nodejs-puppeteer-3.2` ou posteriores, essa classe está defasada. Qualquer uso dessa classe exibe um aviso em seus registros do canário. Essa função será removida em futuras versões do runtime Se você estiver usando esta função, substitua por [RequestResponseLogHelper class](#CloudWatch_Synthetics_Library_RequestResponseLogHelper).
Lida com a configuração minuciosa e a criação de representações de string de cargas úteis de solicitação e resposta.
```
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);
```
Exemplo:
```
synthetics.setRequestResponseLogHelper(getRequestResponseLogHelper()
.withLogRequestPostData(true)
.withLogRequestHeaders(true)
.withLogResponseHeaders(true));
```
Resposta:
```
{RequestResponseLogHelper}
```
#### setRequestResponseLogHelper();
**Importante**
Em canaries que usam o runtime `syn-nodejs-puppeteer-3.2` ou posteriores, essa função está defasada junto com a classe `RequestResponseLogHelper`. Qualquer uso desta função faz exibe um aviso em seus registros do canário. Essa função será removida em futuras versões do runtime. Se você estiver usando esta função, substitua por [RequestResponseLogHelper class](#CloudWatch_Synthetics_Library_RequestResponseLogHelper).
Use essa função como padrão de criador para ajustar os marcadores de log de solicitação e resposta.
Exemplo:
```
synthetics.setRequestResponseLogHelper().withLogRequestHeaders(true).withLogResponseHeaders(true);
```
Resposta:
```
{RequestResponseLogHelper}
```
#### async takeScreenshot(name, suffix);
Faz uma captura de tela (.PNG) da página atual com o some e sufixo (opcional).
Exemplo:
```
await synthetics.takeScreenshot("navigateToUrl", "loaded")
```
Este exemplo captura e carrega uma captura de tela chamada ` 01-navigateToUrl-loaded.png`para o bucket do S3 do canário.
É possível fazer uma captura de tela para uma etapa do canário específica aprovando ` stepName` como o primeiro parâmetro. As capturas de tela são vinculadas à etapa do canário em seus relatórios, para ajudar você a rastrear cada etapa durante a depuração.
Os canários do CloudWatch Synthetics fazem capturas de tela automaticamente antes de iniciar uma etapa (a função `executeStep`) e após a conclusão da etapa (a menos que você configure o canário para desabilitar capturas de tela). É possível fazer mais capturas de tela aprovando o nome da etapa na função `takeScreenshot`.
O exemplo a seguir faz uma captura de tela com `signupForm` como o valor de `stepName`. A captura de tela será chamada ` 02-signupForm-address` e será vinculada à etapa chamada ` signupForm` no relatório do canário.
```
await synthetics.takeScreenshot('signupForm', 'address')
```
### Classe BrokenLinkCheckerReport
Essa classe fornece métodos para adicionar um link sintético. É compatível apenas em canaries que usam a versão `syn-nodejs-2.0-beta` do runtime ou posteriores.
Para usar `BrokenLinkCheckerReport`, inclua as seguintes linhas no script:
```
const BrokenLinkCheckerReport = require('@aws/synthetics-broken-link-checker-report');
const brokenLinkCheckerReport = new BrokenLinkCheckerReport();
```
Definições de funções úteis:
**addLink(*syntheticsLink*, isBroken)**
` syntheticsLink ` é um objeto ` SyntheticsLink` representando um link. Essa função adiciona o link de acordo com o código de status. Por padrão, considera um link a ser quebrado se o código de status não estiver disponível ou se o código de status for 400 ou superior. Você pode substituir esse comportamento padrão aprovando o parâmetro opcional `isBrokenLink` com um valor de `true` ou `false`.
Essa função não retorna valor.
**getLinks()**
Essa função retorna uma matriz de objetos `SyntheticsLink` que estão incluídos no relatório do verificador de links quebrados.
**getTotalBrokenLinks()**
Essa função retorna um número que representa o total de links quebrados.
**getTotalLinksChecked()**
Essa função retorna um número que representa o total de links incluídos no relatório.
**Como usar BrokenLinkCheckerReport**
O trecho de código de script do canário a seguir demonstra um exemplo de como navegar para um link e adicioná-lo ao relatório do verificador de links quebrados.
1. Importar `SyntheticsLink`, `BrokenLinkCheckerReport` e ` 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. Para adicionar um link ao relatório, crie uma instância de ` BrokenLinkCheckerReport`.
```
let brokenLinkCheckerReport = new BrokenLinkCheckerReport();
```
1. Navegue até a URL e adicione-a ao relatório do verificador de links quebrados.
```
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. Adicione o relatório ao Synthetics. Isso criará um arquivo JSON chamado ` BrokenLinkCheckerReport.json` em seu bucket do S3 para cada execução do canário. Será possível ver um relatório de links no console para cada execução do canário, além de capturas de tela, logs e arquivos HAR.
```
await synthetics.addReport(brokenLinkCheckerReport);
```
### Classe SyntheticsLink
Essa classe fornece métodos para quebrar informações. É compatível apenas em canários que usam a versão `syn-nodejs-2.0-beta` do runtime ou posteriores.
Para usar `SyntheticsLink`, inclua as seguintes linhas no script:
```
const SyntheticsLink = require('@aws/synthetics-link');
const syntheticsLink = new SyntheticsLink("https://www.amazon.com");
```
Essa função retorna `syntheticsLinkObject`
Definições de funções úteis:
**withUrl(*url*)**
` url ` é uma string de URL. Essa função retorna `syntheticsLinkObject`
**withText(*text*)**
` text ` é uma string que representa o texto de ancoragem. Essa função retorna `syntheticsLinkObject`. Adiciona texto de ancoragem correspondente ao link.
**withParentUrl(*parentUrl*)**
` parentUrl ` é uma string que representa a URL mãe (página de origem). Essa função retorna `syntheticsLink Object`
**withStatusCode(*statusCode*)**
` statusCode ` é uma string que representa o código de status. Essa função retorna `syntheticsLinkObject`
**withFailureReason(*failureReason*)**
` failureReason ` é uma string que representa o motivo da falha. Essa função retorna `syntheticsLink Object`
**addScreenshotResult(*screenshotResult*)**
` screenshotResult ` é um objeto. É uma instância de `ScreenshotResult` que foi retornada pela função `takeScreenshot` do Synthetics. O objeto inclui o seguinte:
+ `fileName`— uma string que representa ` screenshotFileName`
+ `pageUrl` (opcional)
+ `error` (opcional)
## Classes de biblioteca do Node.js e funções que se aplicam apenas a canaries de API
As seguintes funções de biblioteca para Node.js do CloudWatch Synthetics são úteis apenas para canaries de API.
**Topics**
+ [
### executeHttpStep(stepName, requestOptions, [callback], [stepConfig])
](#CloudWatch_Synthetics_Library_executeHttpStep)
### executeHttpStep(stepName, requestOptions, [callback], [stepConfig])
Executa a solicitação HTTP fornecida como uma etapa e publica `SuccessPercent` (aprovação/falha) e métricas `Duration`.
**executeHttpStep** usa funções nativas HTTP ou HTTPS nos bastidores, conforme o protocolo especificado na solicitação.
Essa função também adicionará um resumo de execução de etapa ao relatório do canário. O resumo contém detalhes sobre cada solicitação HTTP, como o seguinte:
+ Hora de início
+ End Time
+ Status (PASSED/FAILED)
+ Motivo da falha, se for o caso
+ Detalhes da chamada HTTP, como cabeçalhos e corpo da solicitação/resposta, código de status, mensagem de status e tempos de performance.
**Topics**
+ [
#### Parâmetros
](#CloudWatch_Synthetics_Library_executeHttpStep_parameters)
+ [
#### Exemplos de uso do executeHttpStep
](#CloudWatch_Synthetics_Library_executeHttpStep_examples)
#### Parâmetros
**stepName(*String*)**
Especifica o nome da etapa. Esse nome também é usado para publicar métricas do CloudWatch para essa etapa.
**requestOptions(*Object or String*)**
O valor desse parâmetro poderá ser uma URL, uma string de URL ou um objeto. Se for um objeto, ele deverá ser um conjunto de opções configuráveis para fazer uma solicitação HTTP. É compatível com todas as opções em [ http.request(options[, callback])](https://nodejs.org/api/http.html#http_http_request_options_callback) na documentação do Node.js.
Além dessas opções do Node.js, **requestOptions** oferece suporte ao parâmetro adicional `body`. Você pode usar o parâmetro `body` para aprovar dados como um corpo da solicitação.
**callback(*response*)**
(Opcional) Esaa é uma função de usuário que é invocada com a resposta HTTP. A resposta é do tipo [Class: http.IncomingMessage](https://nodejs.org/api/http.html#http_class_http_incomingmessage).
**stepConfig(*object*)**
(Opcional) Use esae parâmetro para substituir configurações globais do Synthetics por uma configuração diferente para essa etapa.
#### Exemplos de uso do executeHttpStep
As séries de exemplos a seguir são desenvolvidas entre si para ilustrar os vários usos dessa opção.
Este primeiro exemplo configura parâmetros de solicitação. Você pode passar um URL como **requestOptions**:
```
let requestOptions = 'https://www.amazon.com';
```
Ou pode aprovar um conjunto de opções:
```
let requestOptions = {
'hostname': 'myproductsEndpoint.com',
'method': 'GET',
'path': '/test/product/validProductName',
'port': 443,
'protocol': 'https:'
};
```
O próximo exemplo cria uma função de retorno de chamada que aceita uma resposta. Por padrão, se você não especificar **callback**, o CloudWatch Synthetics validará que o status está entre 200 e 299, inclusive.
```
// 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();
});
});
};
```
O próximo exemplo cria uma configuração para essa etapa que substitui a configuração global do CloudWatch Synthetics. A configuração de etapa desse exemplo permite cabeçalhos de solicitação, cabeçalhos de resposta, corpo da solicitação (dados de postagem) e corpo da resposta em seu relatório e restringir valores de cabeçalho ‘X-Amz-Security-Token’ e ‘Authorization’. Por padrão, esses valores não são incluídos no relatório por motivos de segurança. Se você escolher incluí-los, os dados serão armazenados apenas no bucket do 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
};
```
Este exemplo final aprova sua solicitação para **executeHttpStep** e nomeia a etapa.
```
await synthetics.executeHttpStep('Verify GET products API', requestOptions, callback, stepConfig);
```
Com esse conjunto de exemplos, o CloudWatch Synthetics adiciona os detalhes de cada etapa do relatório e produz métricas para cada etapa usando **stepName**.
Você verá as métricas `successPercent` e `duration` para a etapa `Verify GET products API`. É possível monitorar a performance de sua API monitorando as métricas para suas etapas de chamada de API.
Para obter um script completo de exemplo que usa essas funções, consulte [Canário de API de várias etapas](CloudWatch_Synthetics_Canaries_Samples.md#CloudWatch_Synthetics_Canaries_Samples_APIsteps).
# Funções da biblioteca disponíveis para scripts do canário do Python usando Selenium
Esta seção lista as funções de biblioteca do Selenium disponíveis para scripts do canário Python.
**Topics**
+ [
## Classes e funções da biblioteca Python e Selenium que se aplicam a todos os canaries
](#CloudWatch_Synthetics_Library_allcanaries_Python)
+ [
## Classes e funções de biblioteca Python e Selenium que se aplicam apenas a canaries de interface do usuário
](#CloudWatch_Synthetics_Library_Python_UIcanaries)
## Classes e funções da biblioteca Python e Selenium que se aplicam a todos os canaries
As seguintes funções de biblioteca do Selenium do CloudWatch Synthetics para Python são úteis para todos os canaries.
**Topics**
+ [
### Classe SyntheticsConfiguration
](#CloudWatch_Synthetics_Library_SyntheticsConfiguration_Python)
+ [
### Classe SyntheticsLogger
](#CloudWatch_Synthetics_Library_SyntheticsLogger_Python)
### Classe SyntheticsConfiguration
É possível usar a classe SyntheticsConfiguration para configurar o comportamento das funções da biblioteca do Synthetics. Por exemplo, você pode usar essa classe para configurar a função ` executeStep()` para não obter capturas de tela.
É possível definir as configurações do CloudWatch Synthetics no nível global.
Definições de função:
#### set\$1config(options)
```
from aws_synthetics.common import synthetics_configuration
```
` options ` é um objeto, que é um conjunto de opções configuráveis para seu canário. As seções a seguir explicam os campos possíveis em ` options `.
+ `screenshot_on_step_start` (booliano): se fará ou nãi uma captura de tela antes de iniciar uma etapa.
+ `screenshot_on_step_success` (booliano): se fará ou não uma captura de tela depois de concluir uma etapa bem-sucedida.
+ `screenshot_on_step_failure` (booliano): se fará ou não uma captura de tela depois de que uma etapa falhar.
**with\$1screenshot\$1on\$1step\$1start(screenshot\$1on\$1step\$1start)**
Aceita um argumento booliano, que indica se uma captura de tela deverá ou não ser obtida antes de iniciar uma etapa.
**with\$1screenshot\$1on\$1step\$1success(screenshot\$1on\$1step\$1success)**
Aceita um argumento booliano, que indica se uma captura de tela deverá ou não ser obtida após a conclusão de uma etapa.
**with\$1screenshot\$1on\$1step\$1failure(screenshot\$1on\$1step\$1failure)**
Aceita um argumento booliano, que indica se uma captura de tela deverá ou não ser obtida depois que uma etapa falhar.
**get\$1screenshot\$1on\$1step\$1start()**
Retorna se uma captura de tela será ou não obtida antes de iniciar uma etapa.
**get\$1screenshot\$1on\$1step\$1success()**
Retorna se uma captura de telam será ou não obtida depois que uma etapa for concluída.
**get\$1screenshot\$1on\$1step\$1failure()**
Retorna se uma captura de tela será ou não obtida depois que uma etapa falhar.
**disable\$1step\$1screenshots()**
Desabilita todas as opções de captura de tela (get\$1screenshot\$1on\$1step\$1start, get\$1screenshot\$1on\$1step\$1success e get\$1screenshot\$1on\$1step\$1failure).
**enable\$1step\$1screenshots()**
Habilita todas as opções de captura de tela (get\$1screenshot\$1on\$1step\$1start, get\$1screenshot\$1on\$1step\$1success e get\$1screenshot\$1on\$1step\$1failure). Por padrão, todas essas métricas são permitidas.
**setConfig(options) em relação a métricas do CloudWatch**
Para canários que usam `syn-python-selenium-1.1` ou posterior, as **(options)** para **setConfig** podem incluir os parâmetros boolianos a seguir que determinam quais métricas serão publicadas pelo canário. O padrão para cada uma dessas opções é `true`. As opções que começam com ` aggregated` determinam se a métrica será emitida sem a dimensão ` CanaryName`. É possível usar essas métricas para ver os resultados agregados de todos os seus canaries. As outras opções determinam se a métrica será emitida com a dimensão `CanaryName`. Você pode usar essas métricas para ver os resultados de cada canário individual.
Para obter uma lista de métricas do CloudWatch emitidas por canaries, consulte [Métricas do CloudWatch publicadas por canaries](CloudWatch_Synthetics_Canaries_metrics.md).
+ `failed_canary_metric` (booliano): se deverá ou não emitir a métrica ` Failed` (com a dimensão `CanaryName`) para esse canário. O padrão é `true`.
+ `failed_requests_metric` (booliano): se deverá ou não emitir a métrica `Failed requests` (com a dimensão `CanaryName`) para esse canário. O padrão é `true`.
+ `2xx_metric` (booliano): se deverá ou não emitir a métrica `2xx` (com a dimensão `CanaryName`) para esse canário. O padrão é `true`.
+ `4xx_metric` (booliano): se deverá ou não emitir a métrica `4xx` (com a dimensão `CanaryName`) para esse canário. O padrão é `true`.
+ `5xx_metric` (booliano): se deverá ou não emitir a métrica `5xx` (com a dimensão `CanaryName`) para esse canário. O padrão é `true`.
+ `step_duration_metric` (booliano): se deverá ou não emitir a métrica `Step duration` (com as dimensões `CanaryName` `StepName`) para esse canário. O padrão é `true`.
+ `step_success_metric` (booliano): se deverá ou não emitir a métrica `Step success` (com as dimensões `CanaryName` `StepName`) para esse canário. O padrão é `true`.
+ `aggregated_failed_canary_metric` (booliano): se deverá ou não emitir a métrica `Failed` (sem a dimensão `CanaryName`) para esse canário. O padrão é `true`.
+ `aggregated_failed_requests_metric` (booliano): se deverá ou não emitir a métrica `Failed Requests` (sem a dimensão `CanaryName`) para esse canário. O padrão é `true`.
+ `aggregated_2xx_metric` (booliano): se deverá ou não emitir a métrica ` 2xx` (sem a dimensão `CanaryName`) para esse canário. O padrão é `true`.
+ `aggregated_4xx_metric` (booliano): se deverá ou não emitir a métrica ` 4xx` (sem a dimensão `CanaryName`) para esse canário. O padrão é `true`.
+ `aggregated_5xx_metric` (booliano): se deverá ou não emitir a métrica ` 5xx` (sem a dimensão `CanaryName`) para esse canário. O padrão é `true`.
**with\$12xx\$1metric(2xx\$1metric)**
Aceita um argumento booliano, que especifica se deverá emitir ou não uma métrica `2xx` com a dimensão `CanaryName` para esse canário.
**with\$14xx\$1metric(4xx\$1metric)**
Aceita um argumento booliano, que especifica se deverá emitir ou não uma métrica `4xx` com a dimensão `CanaryName` para esse canário.
**with\$15xx\$1metric(5xx\$1metric)**
Aceita um argumento booliano, que especifica se deverá emitir ou não uma métrica `5xx` com a dimensão `CanaryName` para esse canário.
**withAggregated2xxMetric(aggregated2xxMetric)**
Aceita um argumento booliano, que especifica se deverá emitir ou não uma métrica `2xx` sem dimensão para esse canário.
**withAggregated4xxMetric(aggregated4xxMetric)**
Aceita um argumento booliano, que especifica se deverá emitir ou não uma métrica `4xx` sem dimensão para esse canário.
**with\$1aggregated\$15xx\$1metric(aggregated\$15xx\$1metric)**
Aceita um argumento booliano, que especifica se deverá emitir ou não uma métrica `5xx` sem dimensão para esse canário.
** with\$1aggregated\$1failed\$1canary\$1metric(aggregated\$1failed\$1canary\$1metric)**
Aceita um argumento booliano, que especifica se deverá emitir ou não uma métrica `Failed` sem dimensão para esse canário.
** with\$1aggregated\$1failed\$1requests\$1metric(aggregated\$1failed\$1requests\$1metric)**
Aceita um argumento booliano, que especifica se deverá emitir ou não uma métrica `Failed requests` sem dimensão para esse canário.
**with\$1failed\$1canary\$1metric(failed\$1canary\$1metric)**
Aceita um argumento booliano, que especifica se deverá emitir ou não uma métrica `Failed` com a dimensão `CanaryName` para esse canário.
**with\$1failed\$1requests\$1metric(failed\$1requests\$1metric)**
Aceita um argumento booliano, que especifica se deverá emitir ou não uma métrica `Failed requests` com a dimensão `CanaryName` para esse canário.
**with\$1step\$1duration\$1metric(step\$1duration\$1metric)**
Aceita um argumento booliano, que especifica se deverá emitir ou não uma métrica `Duration` com a dimensão `CanaryName` para esse canário.
**with\$1step\$1success\$1metric(step\$1success\$1metric)**
Aceita um argumento booliano, que especifica se deverá emitir ou não uma métrica `StepSuccess` com a dimensão `CanaryName` para esse canário.
##### Métodos para habilitar ou desabilitar métricas
**disable\$1aggregated\$1request\$1metrics()**
Não permite que o canário emita todas as métricas de solicitação emitidas sem a dimensão ` CanaryName`.
**disable\$1request\$1metrics()**
Desabilita todas as métricas de solicitação, inclusive métricas por canário e métricas agregadas em todos os canários.
**disable\$1step\$1metrics()**
Desativa todas as métricas de etapa, incluindo métricas de sucesso e de duração da etapa.
**enable\$1aggregated\$1request\$1metrics()**
Habilita o canário a emitir todas as métricas de solicitação emitidas sem a dimensão ` CanaryName`.
**enable\$1request\$1metrics()**
Habilita todas as métricas de solicitação, inclusive métricas por canário e métricas agregadas em todos os canários.
**enable\$1step\$1metrics()**
Ativa todas as métricas de etapa, incluindo métricas de sucesso e métricas de duração da etapa.
**Uso em canaries de interface do usuário**
Primeiro, importe a dependência do Synthetics e busque a configuração. Em seguida, defina a configuração para cada opção chamando o método SetConfig usando uma das opções a seguir.
```
from aws_synthetics.common import synthetics_configuration
synthetics_configuration.set_config(
{
"screenshot_on_step_start": False,
"screenshot_on_step_success": False,
"screenshot_on_step_failure": True
}
)
or
```
Ou
```
synthetics_configuration.with_screenshot_on_step_start(False).with_screenshot_on_step_success(False).with_screenshot_on_step_failure(True)
```
Para desabilitar todas as capturas de tela, use a função disableStepScreenshots() como neste exemplo.
```
synthetics_configuration.disable_step_screenshots()
```
É possível habilitar e desabilitar as capturas de tela em qualquer ponto do código. Por exemplo, para desabilitar capturas de tela apenas para uma etapa, desabilite-as antes de executar essa etapa e habilite-as após a etapa.
##### set\$1config(options) para canaries de interface do usuário
Começando com `syn-python-selenium-1.1`, para os canaries de interface do usuário, ` set_config` pode incluir os seguintes parâmetros boolianos:
+ `continue_on_step_failure` (booliano): se continuará ou não executando o script do canário após a falha de uma etapa (isso se refere à função **executeStep**). Se alguma etapa falhar, a execução do canário ainda será marcada como falha. O padrão é `false`.
### Classe SyntheticsLogger
`synthetics_logger`O grava logs no console e em um arquivo de log local no mesmo nível de log. Este arquivo de logs é gravado em ambos os locais apenas se o nível de registo estiver no nível de registo pretendido ou abaixo da função de registo que foi chamada.
As instruções de log no arquivo de log local são precedidas por "DEBUG: ", "INFO: " e assim por diante para corresponder ao nível de log da função que foi chamada.
Não é necessário usar o `synthetics_logger` para criar um arquivo de log que está carregando o local de resultados do Amazon S3. Em vez disso, você pode criar um arquivo de log diferente na pasta `/tmp`. Todos os arquivos criados sob a pasta `/tmp` são carregados para o local de resultados no bucket do S3 como artefatos.
Para usar `synthetics_logger`:
```
from aws_synthetics.common import synthetics_logger
```
****Definições úteis de função:
Obter nível do log:
```
log_level = synthetics_logger.get_level()
```
Definir nível do log:
```
synthetics_logger.set_level()
```
Registre em log uma mensagem com um nível especificado. O nível pode ser `DEBUG`, ` INFO`, `WARN` ou `ERROR`, como nos exemplos de sintaxe a seguir:
```
synthetics_logger.debug(message, *args, **kwargs)
```
```
synthetics_logger.info(message, *args, **kwargs)
```
```
synthetics_logger.log(message, *args, **kwargs)
```
```
synthetics_logger.warning(message, *args, **kwargs)
```
```
synthetics_logger.error(message, *args, **kwargs)
```
Para obter informações sobre parâmetros de depuração, consulte a documentação padrão do Python em [logging.debug](https://docs.python.org/3/library/logging.html#logging.debug)
Nessas funções de log, `message` é a string do formato da mensagem. `args` são os argumentos que são mesclados em `msg` usando o operador de formatação de string.
Há três argumentos de palavra-chave em `kwargs`:
+ `exc_info`: se não for avaliado como false, adicionará informações de exceção à mensagem de log.
+ `stack_info`: o padrão é false. Se true, adicionará informações de pilha à mensagem de log, incluindo a chamada de log real.
+ `extra`: o terceiro argumento opcional de palavra-chave, que você pode usar para aprovar um dicionário que é usado para preencher o `__dict__` do `LogRecord` criado para o evento de log com atributos definidos pelo usuário.
Exemplos:
Registrar em log uma mensagem com o nível `DEBUG`:
```
synthetics_logger.debug('Starting step - login.')
```
Registrar em log uma mensagem com o nível `INFO`. `logger.log` é sinônimo de `logger.info`:
```
synthetics_logger.info('Successfully completed step - login.')
```
ou
```
synthetics_logger.log('Successfully completed step - login.')
```
Registrar uma mensagem com o nível `WARN`:
```
synthetics_logger.warning('Warning encountered trying to publish %s', 'CloudWatch Metric')
```
Registrar uma mensagem com o nível `ERROR`:
```
synthetics_logger.error('Error encountered trying to publish %s', 'CloudWatch Metric')
```
Registre em log uma exceção:
```
synthetics_logger.exception(message, *args, **kwargs)
```
Regista uma mensagem com o nível `ERROR`. Informações de exceção são adicionadas à mensagem de log. Você deve chamar essa função apenas a partir de um manipulador de exceção.
Para obter informações sobre parâmetros de exceção, consulte a documentação padrão do Python em [logging.exception](https://docs.python.org/3/library/logging.html#logging.exception)
A `message` é a string de formato da mensagem. `args` são os argumentos, que são mesclados em `msg` usando o operador de formatação de string.
Há três argumentos de palavra-chave em `kwargs`:
+ `exc_info`: se não for avaliado como false, adicionará informações de exceção à mensagem de log.
+ `stack_info`: o padrão é false. Se true, adicionará informações de pilha à mensagem de log, incluindo a chamada de log real.
+ `extra`: o terceiro argumento opcional de palavra-chave, que você pode usar para aprovar um dicionário que é usado para preencher o `__dict__` do `LogRecord` criado para o evento de log com atributos definidos pelo usuário.
Exemplo:
```
synthetics_logger.exception('Error encountered trying to publish %s', 'CloudWatch Metric')
```
## Classes e funções de biblioteca Python e Selenium que se aplicam apenas a canaries de interface do usuário
As seguintes funções de biblioteca do Selenium do CloudWatch Synthetics para Python são úteis somente para canaries de interface do usuário.
**Topics**
+ [
### Classe SyntheticsBrowser
](#CloudWatch_Synthetics_Library_Python_SyntheticsBrowser)
+ [
### Classe SyntheticsWebDriver
](#CloudWatch_Synthetics_Library_Python_SyntheticsWebDriver)
### Classe SyntheticsBrowser
**nota**
O `SyntheticsBrowser` oferece suporte somente ao navegador Chrome.
Quando você cria uma instância do navegador chamando `synthetics_webdriver.Chrome()`, a instância do navegador retornada é do tipo `SyntheticsBrowser`. A classe ` SyntheticsBrowser` herda a classe WebDriver e fornece acesso a todos os métodos expostos pelo [WebDriver](https://www.selenium.dev/documentation/webdriver/). Ela controla ChromeDriver e permite que o script do canário conduza o navegador, permitindo que o Selenium WebDriver funcione com o Synthetics.
**nota**
O Synthetics substitui o método [quit](https://www.selenium.dev/selenium/docs/api/py/selenium_webdriver_firefox/selenium.webdriver.firefox.webdriver.html) do WebDriver para que nenhuma ação seja executada. Você não precisa se preocupar em fechar o navegador, pois o Synthetics cuida disso para você.
Além dos métodos padrão do Selenium, ele também fornece os métodos abaixo.
**Topics**
+ [
#### set\$1viewport\$1size(width, height)
](#CloudWatch_Synthetics_Library_set_viewport_size)
+ [
#### save\$1screenshot(filename, suffix)
](#CloudWatch_Synthetics_Library_save_screenshot)
#### set\$1viewport\$1size(width, height)
Define o visor do navegador. Exemplo:
```
browser.set_viewport_size(1920, 1080)
```
#### save\$1screenshot(filename, suffix)
Salva capturas de tela no diretório `/tmp`. As capturas de tela são carregadas de lá para a pasta de artefatos do canário no bucket do S3.
*filename* é o nome do arquivo para a captura de tela, e *suffix* é uma string opcional a ser usada para nomear a captura de tela.
Exemplo:
```
browser.save_screenshot('loaded.png', 'page1')
```
### Classe SyntheticsWebDriver
Para usar essa classe, use o seguinte no script:
```
from aws_synthetics.selenium import synthetics_webdriver
```
**Topics**
+ [
#### add\$1execution\$1error(errorMessage, ex);
](#CloudWatch_Synthetics_Library_Python_addExecutionError)
+ [
#### add\$1user\$1agent(user\$1agent\$1str)
](#CloudWatch_Synthetics_Library_add_user_agent)
+ [
#### execute\$1step(step\$1name, function\$1to\$1execute)
](#CloudWatch_Synthetics_Library_Python_execute_step)
+ [
#### get\$1http\$1response(url)
](#CloudWatch_Synthetics_Library_Python_get_http_response)
+ [
#### Chrome()
](#CloudWatch_Synthetics_Library_Python_Chrome)
#### add\$1execution\$1error(errorMessage, ex);
`errorMessage` descreve o erro, e `ex` é a exceção encontrada
Você pode usar `add_execution_error` para definir erros de execução eu seu canário. Ele faz o canário falhar sem interromper a execução do script. Também não afeta suas métricas `successPercent`.
Convém rastrear erros como erros de execução somente se eles não forem importantes para indicar o sucesso ou falha do script do canário.
A seguir há um exemplo de uso do elemento `add_execution_error`. Você está monitorando a disponibilidade de seu endpoint e fazendo capturas de tela depois que a página foi carregada. Como a falha de obter uma captura de tela não determina a disponibilidade do endpoint, é possível detectar quaisquer erros encontrados durante a captura de tela e adicioná-los como erros de execução. Suas métricas de disponibilidade ainda indicarão que o endpoint está ativo e em execução, mas o status do canário será marcado como falha. O bloco de código de exemplo a seguir captura esse erro e adiciona-o como erro de execução.
```
try:
browser.save_screenshot("loaded.png")
except Exception as ex:
self.add_execution_error("Unable to take screenshot", ex)
```
#### add\$1user\$1agent(user\$1agent\$1str)
Anexa o valor de `user_agent_str` ao cabeçalho do atendente do usuário do navegador. É necessário atribuir `user_agent_str` antes de criar a instância do navegador.
Exemplo:
```
await synthetics_webdriver.add_user_agent('MyApp-1.0')
```
`add_user_agent` deve ser usado dentro de uma função `async`.
#### execute\$1step(step\$1name, function\$1to\$1execute)
Processa uma função. Ela também faz o seguinte:
+ Registra que a etapa começou.
+ Faz uma captura de tela chamada `-starting`.
+ Inicia um temporizador.
+ Executa a função fornecida.
+ Se a função retornar normalmente, ela contará como aprovada. Se a função apresentar erro, ela contará como falha.
+ Encerra o temporizador.
+ Registra se a etapa foi aprovada ou falhou
+ Faz uma captura de tela chamada `-succeeded` ou ` -failed`.
+ Emite a métrica `stepName` `SuccessPercent`, 100 para aprovação ou 0 para falha.
+ Emite a métrica `stepName` `Duration` com um valor de acordo com os horários inicial e final da etapa.
+ Finalmente, retorna o que `functionToExecute` retornou ou lança novamente o que `functionToExecute` lançou.
Exemplo:
```
from selenium.webdriver.common.by import By
def custom_actions():
#verify contains
browser.find_element(By.XPATH, "//*[@id=\"id_1\"][contains(text(),'login')]")
#click a button
browser.find_element(By.XPATH, '//*[@id="submit"]/a').click()
await synthetics_webdriver.execute_step("verify_click", custom_actions)
```
#### get\$1http\$1response(url)
Faz uma solicitação HTTP à URL fornecida e retorna o código de resposta dessa solicitação HTTP. Se ocorrer uma exceção durante a solicitação HTTP, será retornada uma string com o valor "error".
Exemplo:
```
response_code = syn_webdriver.get_http_response(url)
if not response_code or response_code == "error" or response_code < 200 or response_code > 299:
raise Exception("Failed to load page!")
```
#### Chrome()
Inicia uma instância do navegador Chromium e retorna a instância criada do navegador.
Exemplo:
```
browser = synthetics_webdriver.Chrome()
browser.get("https://example.com/)
```
Para iniciar um navegador no modo anônimo, use o seguinte:
```
add_argument('——incognito')
```
Para adicionar configurações de proxy, use o seguinte:
```
add_argument('--proxy-server=%s' % PROXY)
```
Exemplo:
```
from selenium.webdriver.chrome.options import Options
chrome_options = Options()
chrome_options.add_argument("——incognito")
browser = syn_webdriver.Chrome(chrome_options=chrome_options)
```
# Agendamento de execuções do canário usando cron
Usar uma expressão cron lhe dá flexibilidade quando você programa um canário. As expressões cron contêm cinco ou seis campos na ordem listada na tabela a seguir. Os campos são separados por espaços. A sintaxe será diferente se você usar o console do CloudWatch para criar o canário, a AWS CLI ou SDKs da AWS. Ao usar o console, especifique apenas os cinco primeiros campos. Usando a AWS CLI ou os SDKs da AWS, especifique todos os seis campos, e você deverá especificar `*` para o campo `Year`.
| **Campo** | **Valores permitidos** | **Caracteres especiais permitidos** |
| --- | --- | --- |
| minutos | 0-59 | , - \$1 / |
| Horas | 0-23 | , - \$1 / |
| Dia do mês | 1-31 | , - \$1 ? / L W |
| Mês | 1-12 ou JAN-DEZ | , - \$1 / |
| Dia da semana | 1-7 ou DOM-SÁB | , - \$1 ? L \$1 |
| Ano | \$1 | |
**Caracteres especiais**
+ A **,**(vírgula) inclui vários valores na expressão de um campo. Por exemplo, no campo Month (Mês), JAN,FEB,MAR incluiria janeiro, fevereiro e março.
+ O caractere especial **-**(traço) especifica faixas. No campo Dia, 1-15 incluiria dias 1 a 15 do mês especificado.
+ O caractere especial **\$1** (asterisco) inclui todos os valores no campo. No campo Hours (Horas), **\$1** inclui todas as horas. Não é possível usar **\$1** nos campos Day-of-month e Day-of-week na mesma expressão. Se você usá-lo em um deles, utilize **?** no outro.
+ A **/** (barra) especifica incrementos. No campo Minutes (Minutos), é possível inserir 1/10 para especificar cada décimo minuto a partir do primeiro minuto da hora (por exemplo, o 11.º, 21.º e 31.º minuto etc.).
+ O **?** (ponto de interrogação) especifica um ou outro. Se você inserir **7** no campo Day-of-month e o dia da semana correspondente for irrelevante, é possível inserir **?** no campo Day-of-week.
+ O curinga **L** nos campos Dia do mês ou Dia da semana especifica o último dia do mês ou da semana.
+ O curinga **W** no campo Dia do mês especifica um dia da semana. No campo Dia do mês, **3W** especifica o dia mais próximo do terceiro dia da semana do mês.
+ O curinga **\$1** no campo Dia da semana especifica uma determinada instância do dia da semana definido dentro de um mês. Por exemplo, 3\$12 é a segunda terça-feira do mês. O 3 refere-se a terça-feira, porque é o terceiro dia de cada semana, e o 2 refere-se ao segundo dia desse tipo dentro do mês.
**Limitações**
+ Você não pode especificar os campos Dia do mês e Dia da semana na mesma expressão cron. Se você especificar um valor ou `*` (asterisco) em um dos campos, deverá usar **?** (ponto de interrogação) no outro.
+ Não há suporte para expressões Cron que causam taxas mais rápidas que um minuto.
+ Não é possível configurar um canário para esperar mais de um ano para ser executado. Portanto, você pode especificar apenas `*` no campo `Year`.
**Exemplos**
Você pode consultar as seguintes sequências de caracteres cron de exemplo ao criar um canário. Os exemplos a seguir são a sintaxe correta para usar a AWS CLI ou os SDKs da AWS para criar ou atualizar um canário. Caso esteja usando o console do CloudWatch, omita a `*` final em cada exemplo.
| Expressão | Significado |
| --- | --- |
| `0 10 * * ? *` | Executada às 10h (UTC) todos os dias |
| `15 12 * * ? *` | Executada às 12h15 (UTC) todos os dias |
| `0 18 ? * MON-FRI *` | Executada às 18h (UTC) de segunda a sexta |
| `0 8 1 * ? *` | Executar às 8h (UTC) no primeiro dia de cada mês |
| `0/10 * ? * MON-SAT *` | Executar a cada 10 minutos de segunda a sábado de cada semana |
| `0/5 8-17 ? * MON-FRI *` | Executada a cada cinco minutos, de segunda-feira a sexta-feira, entre 8h e 17h55 (UTC) |
# Configuração do canário para realizar novas tentativas automaticamente
Ao criar ou atualizar um canário, você pode configurá-lo para realizar novas tentativas automaticamente quando ocorrerem falhas na simulação programada. Isso ajuda a diferenciar falhas reais de instabilidades temporárias, proporcionando resultados mais confiáveis. Esse recurso é ideal para o desenvolvimento de sistemas de monitoramento mais resilientes ao mesmo tempo em que reduz alarmes falsos e a necessidade de intervenção manual.
**Como criar um canário configurado para novas tentativas automáticas**
1. Abra o console do CloudWatch, em [https://console.aws.amazon.com/cloudwatch/](https://console.aws.amazon.com/cloudwatch/).
1. No painel de navegação, escolha **Application Signals**, **Canários do Synthetics**.
1. Selecione **Create Canary** (Criar canário).
1. Em **Configuração adicional**, escolha a opção **Tentativa automática** e selecione o número máximo desejado para as novas tentativas.
**Como atualizar o número máximo de novas tentativas para um canário**
1. Abra o console do CloudWatch, em [https://console.aws.amazon.com/cloudwatch/](https://console.aws.amazon.com/cloudwatch/).
1. No painel de navegação, escolha **Application Signals**, **Canários do Synthetics**.
1. Você pode executar uma das seguintes ações:
+ Selecione o canário, acesse **Ações**, clique em **Habilitar nova tentativa automática** e ajuste o número máximo de novas tentativas.
+ Selecione o canário, escolha **Ações** e, em seguida, clique em **Editar**. Na página **Editar detalhes**, em **Configuração adicional**, seção **Tentativa automática**, altere a configuração de novas tentativas conforme desejado.
**Limitações**
Confira, a seguir, as limitações para configurar a nova tentativa automática.
+ Compatível apenas com as versões de runtime `syn-nodejs-puppeteer-10.0 ` ou mais recentes, ` syn-nodejs-playwright-2.0` ou mais recentes, `syn-python-selenium-5.1` ou mais recentes ou `syn-nodejs-3.0` ou mais recentes.
+ Os canários de execução prolongada, que expiram após dez minutos, têm limite de uma tentativa. Os demais canários podem ter até duas novas tentativas.
# Uso das dependências com os canários do CloudWatch Synthetics
Esta seção explica como usar as `Dependencies` nos canários do CloudWatch Synthetics. O campo `Dependencies` permite especificar dependências para seus canários, possibilitando a inclusão de bibliotecas adicionais ou código personalizado que seus scripts de canário possam utilizar.
## Visão geral
Os canários do CloudWatch Synthetics são compatíveis com a especificação de camadas do Lambda como dependências. Com este recurso, você pode:
+ Compartilhar código comum entre vários canários
+ Gerenciar dependências de forma independente do código do script do seu canário
+ Reduzir o tamanho do script do seu canário ao transferir as dependências para uma camada do Lambda
## APIs compatíveis
O campo `Dependencies` é compatível com as seguintes APIs:
+ [CreateCanary](https://docs.aws.amazon.com/AmazonSynthetics/latest/APIReference/API_CreateCanary.html)
+ [UpdateCanary](https://docs.aws.amazon.com/AmazonSynthetics/latest/APIReference/API_UpdateCanary.html)
+ [StartCanaryDryRun](https://docs.aws.amazon.com/AmazonSynthetics/latest/APIReference/API_StartCanaryDryRun.html)
## Sintaxe
O campo `Dependencies` faz parte da estrutura do código na sintaxe da solicitação:
```
"Code": {
"Handler": "string",
"S3Bucket": "string",
"S3Key": "string",
"S3Version": "string",
"ZipFile": blob,
"Dependencies": [
{
"Type": "LambdaLayer",
"Reference": "string"
}
]
}
```
## Uso de dependências
A seguir, apresentamos alguns exemplos e instruções para o uso do campo `Dependencies` em diferentes cenários.
### Criação de um canário com dependências
Ao criar um canário, é possível especificar uma camada do Lambda como uma dependência:
```
{
"Name": "my-canary",
"Code": {
"Handler": "pageLoadBlueprint.handler",
"S3Bucket": "my-bucket",
"S3Key": "my-canary-script.zip",
"Dependencies": [
{
"Type": "LambdaLayer",
"Reference": "arn:aws:lambda:us-west-2:123456789012:layer:my-custom-layer:1"
}
]
},
"ArtifactS3Location": "s3://my-bucket/artifacts/",
"ExecutionRoleArn": "arn:aws:iam::123456789012:role/my-canary-role",
"Schedule": {
"Expression": "rate(5 minutes)"
},
"RuntimeVersion": "syn-nodejs-puppeteer-3.9"
}
```
### Atualização das dependências de um canário
É possível atualizar as dependências de um canário usando a API UpdateCanary:
```
{
"Name": "my-canary",
"Code": {
"Dependencies": [
{
"Type": "LambdaLayer",
"Reference": "arn:aws:lambda:us-west-2:123456789012:layer:my-updated-layer:2"
}
]
}
}
```
### Remoção de dependências
Para remover as dependências de um canário, forneça uma matriz vazia para o campo Dependências:
```
{
"Name": "my-canary",
"Code": {
"Dependencies": []
}
}
```
### Teste de dependências com StartCanaryDryRun
Antes de atualizar um canário com novas dependências, você pode testá-las usando a API StartCanaryDryRun:
```
{
"Name": "my-canary",
"Code": {
"Dependencies": [
{
"Type": "LambdaLayer",
"Reference": "arn:aws:lambda:us-west-2:123456789012:layer:my-test-layer:3"
}
]
}
}
```
## Limitações e considerações
+ Somente uma camada do Lambda pode ser especificada como uma dependência.
+ O perfil usado para a criação de um canário com dependências deve ter acesso à API ` lambda:GetLayerVersion` para a camada de dependência, além dos [perfis e das permissões necessários](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/CloudWatch_Synthetics_Canaries_Roles.html).
## Criação de camadas do Lambda compatíveis
Para obter informações sobre como criar e empacotar camadas, consulte [Gerenciar dependências do Lambda com camadas](https://docs.aws.amazon.com/lambda/latest/dg/chapter-layers.html) e para compreender a estrutura de empacotamento de uma verificação de canário com base na estrutura de empacotamento do canário, consulte [Escrever um script do canário](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/CloudWatch_Synthetics_Canaries_WritingCanary.html).