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.

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:

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

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:

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:

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.