Funções de biblioteca disponíveis para scripts do canário do Node.js

Esta seção lista as funções de biblioteca disponíveis para scripts do canário Node.js.

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.

Classe Synthetics

As funções a seguir para todos os canaries estão na classe Synthetics.

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:

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:

Exemplo:

synthetics.setLogLevel(0);

Classe SyntheticsConfiguration

Essa classe está disponível apenas na versão de runtime syn-nodejs-2.1 ou posteriores.

É 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, 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.

Você pode transmitir opções no nível de etapa. Veja exemplos em async executeStep(stepName, functionToExecute, [stepConfig]); e executeHttpStep(stepName, requestOptions, [callback], [stepConfig]).

Definições de função:

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 canaries que usam syn-nodejs-puppeteer-3.2 ou posteriores, (options) para o SetConfig pode incluir estes parâmetros:

setConfig(options) em relação a métricas do CloudWatch

Para canários que usam syn-nodejs-puppeteer-3.1 ou posteriores, (options) para setConfig pode incluir os seguintes parâmetros boolianos 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.

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

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

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

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

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:

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

// 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:

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.

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:

Para obter mais informações sobre como usar o console do CloudWatch para editar um canário, consulte Editar ou excluir um canário.

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("#fafa00")

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

Definições úteis de função:

log.debug (message, ex);

Parâmetros: message é a mensagem a ser registrada 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 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 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 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 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.

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_token, definindo a propriedade restrictedUrlParameters. Por padrão, as senhas em URLs são editadas. É possível habilitar senhas de URL, se necessário, definindo includeUrlPasswordcomo true.

Essa função lançará um erro se a URL passada não for uma URL válida.

Parâmetros

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

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

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

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

Em seguida, limpar e registrar em log o URL

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

const sanitizedUrl = synthetics.getSanitizedUrl('https://example.com/learn/home?access_token=12345&token_type=Bearer&expires_in=1200');

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 = synthetics.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

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

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

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

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

Em seguida, limpar e registrar em log a mensagem de erro

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

try {
   // Your code which can throw an error containing url which your script logs
} catch (error) {
    const sanitizedErrorMessage = synthetics.getSanitizedErrorMessage(errorMessage);
    logger.info(sanitizedErrorMessage);
}

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

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.

Classe Synthetics

As funções a seguir estão na classe Synthetics.

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.

A função executeStep também faz o seguinte:

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.

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

// 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.

Exemplo:

let page = synthetics.getPage();

Resposta:

A página (objeto Puppeteer) que está aberta atualmente na sessão atual do navegador.

getRequestResponseLogHelper();

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.

(options) é um conjunto configurável de opções a serem definidas no navegador. Para obter mais informações, consulte Tipos de opções de lançamento.

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 ignoreHTTPSErrorspara 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

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

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

Definições úteis de função:

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.

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

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

Essa função retorna syntheticsLinkObject

Definições úteis de função:

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 syntheticsLinkObject

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 syntheticsLinkObject

addScreenshotResult(screenshotResult)

screenshotResult é um objeto. É uma instância de ScreenshotResult que foi retornada pela função takeScreenshot do Synthetics. O objeto inclui o seguinte:

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.

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:

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]) 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.

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 aprovar uma 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.