O blog da AWS

Testando e depurando localmente os canários do Amazon CloudWatch Synthetics

Por Alex Livingstone, arquiteto principal de soluções da AWS.

Os canários Amazon CloudWatch Synthetics são scripts que monitoram endpoints e APIs simulando as ações de um usuário. Esses canários funcionam de acordo com um cronograma, verificando a disponibilidade e a latência de seus aplicativos e alertando quando há problemas. Os scripts canários são escritos em Node.js e Python e executados dentro de uma função do AWS Lambda. O processo de desenvolvimento para canários é semelhante ao de aplicações, envolvendo tarefas como codificação, teste, depuração e implantação. No entanto, diferentemente do desenvolvimento tradicional de aplicativos, não há um ambiente local de teste e depuração para codificar, testar e iterar de forma perfeita e rápida. Devido à ausência de um ambiente de teste, você pode confiar em métodos menos eficientes, resultando em um tempo prolongado de desenvolvimento. Isso, por sua vez, aumenta a carga operacional na manutenção de canários, pois é gasto mais tempo testando o código.

Nesta postagem do blog, você configurará um ambiente de teste local para testar e depurar canários Synthetics localmente usando o Visual Studio Code IDE.

Visão geral da solução

Usando o AWS Serverless Application Model (SAM) e o editor Visual Studio Code, você configurará um ambiente de desenvolvimento local para um canário Synthetics. A função Lambda definida em um modelo SAM emulará o comportamento do canário localmente. Usando pontos de interrupção de depuração no editor do Visual Studio Code, você depurará um exemplo de canário.

Passo a passo

Este blog fornece um passo a passo para configurar um ambiente de teste local para testar e depurar canários Synthetics. Seguindo algumas etapas, você poderá modificar o código, testar e depurar o NodeJS Canaries diretamente no editor do Visual Studio Code. O ambiente de teste local usa um contêiner Serverless Application Model (SAM) para simular uma função do AWS Lambda para emular o comportamento de um canário Synthetics. Ao final deste guia, você aprenderá o seguinte:

  • Configurar o ambiente de teste local em algumas etapas simples
  • Depurar um canário Synthetics localmente
  • Integrar dependências de terceiros com código canário
  • Integrar a depuração local em um pacote de código-fonte canário existente

Pré-requisitos

Para este passo a passo, você deve ter os seguintes pré-requisitos:

  1. Escolha ou crie um bucket Amazon S3 para artefatos canários. Observação: você pode pular esta etapa, se desejar. O canário ainda pode ser executado localmente, mas não será capaz de carregar artefatos no bucket do S3. Os registros do canário conterão erros relacionados a isso, mas você pode ignorá-los com segurança. Se você usa um bucket do Amazon S3, recomendamos que você defina o ciclo de vida do bucket para excluir objetos após alguns dias. Para obter mais informações, consulte Gerenciando seu ciclo de vida de armazenamento.
  2. Configure um perfil padrão da AWS para sua conta da AWS.
  3. Defina a região padrão como sua região preferida da AWS (ex: us-west-2).
  4. Instale a versão mais recente do CLI do AWS Serverless Application Model (SAM).
  5. Instale o IDE do Visual Studio Code. Você pode escolher outros IDEs, mas este guia fornece instruções para trabalhar somente com o Visual Studio Code.
  6. Instale o Docker e inicie o daemon.
  7. Tenha a expansão do AWS Toolkit for VS Code.

Configurando o ambiente de teste local para o NodeJS canary

1. Clone o repositório aws-samples/synthetics-canary-local-debugging-sample usando este cmd:

git clone https://github.com/aws-samples/synthetics-canary-local-debugging-sample.git

2. Vá para o diretório de código-fonte canário do NodeJS.

cd synthetics-canary-local-debugging-sample/nodejs-canary/src

3. Execute npm install para instralar as dependências.

Configuração de lançamento

O arquivo de configuração de lançamento está presente em .vscode/launch.json. Ele contém a configuração para permitir que o arquivo de modelo seja descoberto pelo Visual Studio Code. Ele define um payload Lambda com os parâmetros necessários para invocar o canário com sucesso. Aqui está a configuração de lançamento do NodeJ:

 {
    "version": "0.2.0",
    "configurations": [
        {
            "type": "aws-sam",
            "request": "direct-invoke",
            "name": "SAM:Run NodeJS Canary",
            "invokeTarget": {
                "target": "template",
                "templatePath": "${workspaceFolder}/nodejs-canary/template.yml",
                "logicalId": "NodeJSPuppeteerCanary"
            },
            "lambda": {
                "runtime": "nodejs18.x",
                "payload": {
                    "json": {
                        "canaryName": "LocalSyntheticsCanary",
                        "artifactS3Location": {
                            "s3Bucket": "cw-syn-results-123456789012-us-west-2",
                            "s3Key": "local-run-artifacts"
                        },
                        "customerCanaryHandlerName": "heartbeat-canary.handler"
                    }
                },
                "environmentVariables": {}
            }
        }
    ]
}

Por favor, note:

  1. Certifique-se de modificar o payhload JSON com seu próprio bucket S3 (S3bucket) para artefatos canários. Você pode fornecer qualquer nome para o canário (CanaryName).
  2. Outros campos opcionais que você pode fornecer no payload JSON:

s3EncryptionMode: valores válidos: SSE_S3 | SSE_KMS

s3KmsKeyArn: <KMS Key ARN>

ActiveTracing : valores válidos: true | false

canaryRunID:  <UUID> (necessário se active tracing estiver ativado)

Neste ponto, sua estrutura de pacotes deve ficar assim

└── synthetics-canary-local-debugging-sample
    ├── nodejs-canary
    │ ├── src
    │ │ ├── cw-synthetics.js
    │ │ ├── heartbeat-canary.js
    │ │ ├── node_modules
    │ │ │ └── @faker-js
    │ │ └── package.json
    │ └── template.yml

Depuração do canário

Adicione pontos de interrupção no código canário em que você deseja pausar a execução clicando na margem do editor e, em seguida, vá para o modo Executar e Depurar. Execute o canário clicando no botão play. Quando o canário for executado, os registros serão rastreados no console de depuração. Se você adicionou pontos de interrupção, a execução do canário será pausada em cada ponto de interrupção, permitindo que você examine o código e inspecione valores de variáveis, métodos de instância, atributos de objetos e etc.

Depois que a execução do canário for concluída, os artefatos (registros, capturas de tela, HAR e relatórios) serão enviados para o bucket do Amazon S3 especificado no payload da lambda na configuração de lançamento. Você pode visualizar os artefatos no console do Amazon S3 ou diretamente no editor na janela do AWS Toolkit. Observe que os artefatos, excluindo os registros, serão substituídos na próxima vez que você executar o canário, pois os nomes dos arquivos de captura de tela e o nome do arquivo de relatório não mudam, exceto o nome do arquivo de log. Se você quiser reter os artefatos, certifique-se de fornecer uma chave diferente do Amazon S3 no JSON de payload para que os artefatos sejam salvos em uma chave diferente do Amazon S3. Além disso, métricas canárias, incluindo SuccessPercent, Duration, métricas das etapas e métricas de código de status HTTP, também serão publicadas no namespace CloudWatchSynthetics do canário (por exemplo: LocalSyntheticsCanary), que pode ser visualizado no console do CloudWatch Metrics.

Não há custo para executar e depurar o canário localmente, exceto pelos artefatos armazenados no bucket do Amazon S3 e pelas métricas do canário geradas por cada execução local.

Figura 1: Canário sintético em execução no modo de depuração

Observação

A Depuração de canários de monitoramento visual representa um desafio devido à dependência de capturas de tela básicas capturadas durante a execução inicial para comparações subsequentes. Em um ambiente de desenvolvimento local, as execuções não são armazenadas nem rastreadas, tratando cada iteração como uma execução independente e autônoma. Consequentemente, a ausência de um histórico de execução torna impraticável realizar a depuração para canários que dependem do monitoramento visual.

Integrando o ambiente de teste local em seu pacote canary

Você pode integrar facilmente o ambiente local de testes de canários em seu pacote de canários existente copiando três arquivos:

  1. Coloque o arquivo template.yml na raiz do pacote. Certifique-se de modificar o caminho do CodeURI para apontar para o diretório em que seu código canário existe.
  2. Coloque o arquivo cw-synthetics.js no diretório de origem do canary. Observação: certifique-se de recuperar a versão mais recente do arquivo do repositório do GitHub, pois as versões mais antigas podem não ser compatíveis com tempos de execução futuros ou podem não replicar com precisão o comportamento real do canário.
  3. Coloque o arquivo de configuração de lançamento (.vscode/launch.json) na raiz do pacote. Certifique-se de colocá-lo dentro do diretório .vscode; crie-o se ele ainda não existir.

Limpando

Como o canário é executado localmente, a única limpeza necessária é remover todos os artefatos do canário que foram enviados para o bucket do Amazon S3. Você deve excluir esses objetos do bucket do S3.

Conclusão

Testar localmente os canários Synthetics oferece aos desenvolvedores um meio poderoso e eficiente de identificar e resolver problemas rapidamente e fornece o fluxo de trabalho e as ferramentas semelhantes ao desenvolvimento de aplicativos com os quais você já está familiarizado. É importante observar que, embora a depuração local seja uma ferramenta valiosa, ela não pode replicar totalmente o ambiente de produção do mundo real. Elementos como latência de rede, armazenamento em cache, problemas transitórios do site, latência de E/S do banco de dados e outros fatores externos exclusivos de um ambiente ativo podem não ser reproduzidos com precisão em uma configuração local. Portanto, é essencial realizar testes completos no ambiente de produção real para considerar essas variáveis externas e garantir que os canários tenham um desempenho ideal em condições reais.

A depuração de um canário Synthetics Python segue o mesmo procedimento discutido na postagem do blog. Você pode encontrar exemplos de código para canários Python no diretório python-canary do repositório de amostras. Para obter informações adicionais sobre depuração de canários Python, depuração em IDEs da JetBrains e muito mais, consulte a documentação do CloudWatch Synthetics.

Sobre o autor

Sudhakar Reddy é engenheiro de desenvolvimento de software na equipe do AWS Application Observability. Ele é apaixonado por resolver os problemas dos clientes com soluções simples que os capacitam a melhorar a capacidade de observação de seus aplicativos e serviços.

Tradutor

Felipe Brito é arquiteto de soluções na AWS e guia clientes nas melhores práticas de arquitetura na nuvem. Possui experiência com projetos de desenvolvimento de software e análise de dados.

 

Revisor

Rodrigo Peres é arquiteto de soluções na AWS, com mais de 20 anos de experiência trabalhando com arquitetura de soluções, desenvolvimento de sistemas e modernização de sistemas legados.