Für Node.js-Canary-Skripte verfügbare Bibliotheksfunktionen, die Puppeteer verwenden

In diesem Abschnitt werden die Bibliotheksfunktionen beschrieben, die für Canary-Skripts von Node.js verfügbar sind.

Node.js-Bibliotheksfunktionen, die für alle Canarys gelten

Die folgenden CloudWatch Synthetics-Bibliotheksfunktionen für Node.js sind für alle Canaries nützlich.

Synthetics-Klasse

Die folgenden Funktionen für alle Canarys befinden sich in der Klasse Synthetics.

addExectionError (errorMessage, ex);

errorMessage beschreibt den Fehler und ex ist die aufgetretene Ausnahme

Sie können Folgendes verwenden:addExecutionError, um Ausführungsfehler für Ihren Canary festzulegen. Es lässt den Canary fehlschlagen, ohne die Skriptausführung zu unterbrechen. Es wirkt sich auch nicht auf Ihre successPercent-Metriken aus.

Sie sollten Fehler nur dann als Ausführungsfehler verfolgen, wenn sie nicht wichtig sind, um den Erfolg oder Misserfolg Ihres Canary-Skripts anzuzeigen.

Ein Beispiel für die Verwendung von addExecutionError ist das folgende. Sie überwachen die Verfügbarkeit Ihres Endpunkts und machen Screenshots, nachdem die Seite geladen wurde. Da der Fehler beim Erstellen eines Screenshots die Verfügbarkeit des Endpunkts nicht bestimmt, können Sie beim Erstellen von Screenshots aufgetretene Fehler abfangen und sie als Ausführungsfehler hinzufügen. Ihre Verfügbarkeitsmetriken zeigen weiterhin an, dass der Endpunkt aktiv ist und ausgeführt wird, aber Ihr Canary-Status wird als fehlgeschlagen markiert. Der folgende Codeblock fängt einen solchen Fehler ab und fügt ihn als Ausführungsfehler hinzu.

try {
    await synthetics.takeScreenshot(stepName, "loaded");
} catch(ex) {
    synthetics.addExecutionError('Unable to take screenshot ', ex);
}

getCanaryName ();

Gibt den Namen des Canarys zurück.

getCanaryArn();

Gibt den ARN des Canarys aus.

getCanaryUserAgentString();

Gibt den benutzerdefinierten Benutzeragenten des Canary zurück.

getRuntimeVersion ();

Diese Funktion ist in Laufzeitversion syn-nodejs-puppeteer-3.0 und höher verfügbar. Es gibt die Synthetics Laufzeitversion des Canarys zurück. Der Rückgabewert könnte beispielsweise syn-nodejs-puppeteer-3.0 sein.

getLogLevel();

Ruft die aktuelle Protokollebene für die Synthetics-Bibliothek ab. Folgende Werte sind möglich:

Beispiel:

let logLevel = synthetics.getLogLevel();

setLogLevel();

Legt die Protokollebene für die Synthetics-Bibliothek fest. Folgende Werte sind möglich:

Beispiel:

synthetics.setLogLevel(0);

SyntheticsConfiguration-Klasse

Diese Klasse ist nur in der syn-nodejs-2.1-Laufzeitversion oder höher verfügbar.

Sie können die SyntheticsConfiguration-Klasse verwenden, um das Verhalten von Synthetics-Bibliotheksfunktionen zu konfigurieren. Sie können diese Klasse beispielsweise verwenden, um die executeStep()-Funktion so zu konfigurieren, dass keine Screenshots erfasst werden.

Sie können CloudWatch Synthetics Konfigurationen auf globaler Ebene festlegen, die auf alle Schritte von Canarys angewendet werden. Sie können diese Konfigurationen auch auf Schrittebene überschreiben, indem Sie Konfigurationsschlüssel-Wert-Paare übergeben.

Sie können Optionen auf Schrittebene übergeben. Beispiele finden Sie unter async ExecuteStep (stepName, functionToExecute, [StepConfig]); und executeHttpStep(stepName, requestOptions, [callback], [stepConfig]).

setConfig (Optionen)

options ist ein Objekt, bei dem es sich um eine Reihe konfigurierbarer Optionen für Ihren Canary handelt. In den folgenden Abschnitten werden die möglichen Felder in options erläutert.

setConfig (Optionen) für alle Canary

Für Canaries, die syn-nodejs-puppeteer-3.2 oder höher verwenden, können die (Optionen) für setConfig die folgenden Parameter enthalten:

setConfig(Optionen) bezüglich CloudWatch-Metriken

Für Canarys, die syn-nodejs-puppeteer-3.1 oder höher verwenden, können die (Optionen) für setConfig die folgenden booleschen Parameter enthalten, die bestimmen, welche Metriken vom Canary veröffentlicht werden. Der Standardwert für jede dieser Optionen ist true. Die Optionen, die mit aggregated beginnen, bestimmen, ob die Metrik ohne die CanaryName-Dimension ausgegeben wird. Sie können diese Metriken verwenden, um die aggregierten Ergebnisse für alle Canarys anzuzeigen. Die anderen Optionen bestimmen, ob die Metrik mit der CanaryName Dimension ausgegeben wird. Sie können diese Metriken verwenden, um die Ergebnisse für jeden einzelnen Canary anzuzeigen.

Methoden zum Aktivieren oder Deaktivieren von Metriken

disableAggregatedRequestMetrics()

Verhindert, dass der Canary alle Anforderungsmesswerte ausgibt, die ohne CanaryName-Dimension ausgegeben werden.

disableRequestMetrics()

Deaktiviert alle Anforderungsmetriken, einschließlich aller Canary-Metriken und Metriken, die über alle Canarys aggregiert werden.

disableStepMetrics()

Deaktiviert alle Schrittmetriken, einschließlich Metriken für den Schritterfolg und für die Schrittdauer.

enableAggregatedRequestMetrics()

Ermöglicht dem Canary, alle Anforderungsmesswerte auszugeben, die ohne CanaryName-Dimension ausgegeben werden.

enableRequestMetrics()

Aktiviert alle Anforderungsmetriken, einschließlich aller Canary-Metriken und Metriken, die über alle Canarys aggregiert werden.

enableStepMetrics()

Aktiviert alle Schrittmetriken, einschließlich Metriken für den Schritterfolg und für die Schrittdauer.

get2xxMetric()

Gibt zurück, ob der Canary eine 2xx-Metrik mit der CanaryName-Dimension ausgibt.

get4xxMetric()

Gibt zurück, ob der Canary eine 4xx-Metrik mit der CanaryName-Dimension ausgibt.

get5xxMetric()

Gibt zurück, ob der Canary eine 5xx-Metrik mit der CanaryName-Dimension ausgibt.

getAggregated2xxMetric()

Gibt zurück, ob der Canary eine 2xx-Metrik ohne Dimension ausgibt.

getAggregated4xxMetric()

Gibt zurück, ob der Canary eine 4xx-Metrik ohne Dimension ausgibt.

getAggregatedFailedCanaryMetric()

Gibt zurück, ob der Canary eine Failed-Metrik ohne Dimension ausgibt.

getAggregatedFailedRequestsMetric()

Gibt zurück, ob der Canary eine Failed requests-Metrik ohne Dimension ausgibt.

getAggregated5xxMetric()

Gibt zurück, ob der Canary eine 5xx-Metrik ohne Dimension ausgibt.

getFailedCanaryMetric()

Gibt zurück, ob der Canary eine Failed-Metrik mit der CanaryName-Dimension ausgibt.

getFailedRequestsMetric()

Gibt zurück, ob der Canary eine Failed requests-Metrik mit der CanaryName-Dimension ausgibt.

getStepDurationMetric()

Gibt zurück, ob der Canary eine Duration-Metrik mit der CanaryName-Dimension für dieses Canary ausgibt.

getStepSuccessMetric()

Gibt zurück, ob der Canary eine StepSuccess-Metrik mit der CanaryName-Dimension für dieses Canary ausgibt.

with2xxMetric(_2xxMetric)

Akzeptiert ein boolesches Argument, das angibt, ob eine 2xx-Metrik mit der CanaryName-Dimension für diesen Canary emittiert werden soll.

with4xxMetric(_4xxMetric)

Akzeptiert ein boolesches Argument, das angibt, ob eine 4xx-Metrik mit der CanaryName-Dimension für diesen Canary emittiert werden soll.

with5xxMetric(_5xxMetric)

Akzeptiert ein boolesches Argument, das angibt, ob eine 5xx-Metrik mit der CanaryName-Dimension für diesen Canary emittiert werden soll.

withAggregated2xxMetric(aggregated2xxMetric)

Akzeptiert ein boolesches Argument, das angibt, ob eine 2xx-Metrik mit keiner Dimension für diesen Canary emittiert werden soll.

withAggregated4xxMetric(aggregated4xxMetric)

Akzeptiert ein boolesches Argument, das angibt, ob eine 4xx-Metrik mit keiner Dimension für diesen Canary emittiert werden soll.

withAggregated5xxMetric(aggregated5xxMetric)

Akzeptiert ein boolesches Argument, das angibt, ob eine 5xx-Metrik mit keiner Dimension für diesen Canary emittiert werden soll.

withAggregatedFailedCanaryMetric(aggregatedFailedCanaryMetric)

Akzeptiert ein boolesches Argument, das angibt, ob eine Failed-Metrik mit keiner Dimension für diesen Canary emittiert werden soll.

withAggregatedFailedRequestsMetric(aggregatedFailedRequestsMetric)

Akzeptiert ein boolesches Argument, das angibt, ob eine Failed requests-Metrik mit keiner Dimension für diesen Canary emittiert werden soll.

withFailedCanaryMetric(failedCanaryMetric)

Akzeptiert ein boolesches Argument, das angibt, ob eine Failed-Metrik mit der CanaryName-Dimension für diesen Canary emittiert werden soll.

withFailedRequestsMetric(failedRequestsMetric)

Akzeptiert ein boolesches Argument, das angibt, ob eine Failed requests-Metrik mit der CanaryName-Dimension für diesen Canary emittiert werden soll.

withStepDurationMetric(stepDurationMetric)

Akzeptiert ein boolesches Argument, das angibt, ob eine Duration-Metrik mit der CanaryName-Dimension für diesen Canary emittiert werden soll.

withStepSuccessMetric(stepSuccessMetric)

Akzeptiert ein boolesches Argument, das angibt, ob eine StepSuccess-Metrik mit der CanaryName-Dimension für diesen Canary emittiert werden soll.

Methoden zum Aktivieren oder Deaktivieren anderer Features

withHarFile()

Akzeptiert ein boolesches Argument, das angibt, ob eine HAR-Datei für diesen Canary erstellt werden soll.

withStepsReport()

Akzeptiert ein boolesches Argument, das angibt, ob eine Zusammenfassung der Schrittausführung für diesen Canary gemeldet werden soll.

withIncludeUrlPassword()

Akzeptiert ein boolesches Argument, das angibt, ob Kennwörter eingeschlossen werden sollen, die in URLs in Protokollen und Berichten angezeigt werden.

withRestrictedUrlParameters()

Akzeptiert ein Array von URL-Pfad- oder Abfrageparametern zum Schwärzen. Dies gilt für URLs, die in Protokollen, Berichten und Fehlern angezeigt werden. Sie können ein Sternchen (*) als Wert übergeben, um alle URL-Pfad- und Abfrageparameterwerte zu verkleinern

withLogRequest()

Akzeptiert ein boolesches Argument, das angibt, ob jede Anforderung in den Protokollen des Canarys protokolliert werden soll.

withLogResponse()

Akzeptiert ein boolesches Argument, das angibt, ob jede Antwort in den Protokollen des Canarys protokolliert werden soll.

withLogRequestBody()

Akzeptiert ein boolesches Argument, das angibt, ob jeder Anforderungstext in den Protokollen des Canarys protokolliert werden soll.

withLogResponseBody()

Akzeptiert ein boolesches Argument, das angibt, ob jeder Antworttext in den Protokollen des Canarys protokolliert werden soll.

withLogRequestHeaders()

Akzeptiert ein boolesches Argument, das angibt, ob jeder Anforderungs-Header in den Protokollen des Canarys protokolliert werden soll.

withLogResponseHeaders()

Akzeptiert ein boolesches Argument, das angibt, ob jeder Antwort-Header in den Protokollen des Canarys protokolliert werden soll.

getHarFile()

Gibt zurück, ob der Canary eine HAR-Datei erstellt.

getStepsReport()

Gibt zurück, ob der Canary eine Zusammenfassung der Schrittausführung meldet

getIncludeUrlPassword()

Gibt zurück, ob der Canary Passwörter enthält, die in URLs in Protokollen und Berichten angezeigt werden.

getRestrictedUrlParameters()

Gibt zurück, ob der Canary den URL-Pfad oder die Abfrageparameter entfernt.

getLogRequest()

Gibt zurück, ob der Canary jede Anforderung in den Canaryprotokollen protokolliert.

getLogResponse()

Gibt zurück, ob der Canary jede Antwort in den Canaryprotokollen protokolliert.

getLogRequestBody()

Gibt zurück, ob der Canary jeden Anforderungstext in den Canaryprotokollen protokolliert.

getLogResponseBody()

Gibt zurück, ob der Canary jeden Antworttext in den Canaryprotokollen protokolliert.

getLogRequestHeaders()

Gibt zurück, ob der Canary jeden Anforderungsheader in den Protokollen des Canarys.

getLogResponseHeaders()

Gibt zurück, ob der Canary alle Antwort-Header in den Canaryprotokollen protokolliert.

Funktionen für alle Canarys

setConfig (Optionen) für UI-Canarys

Für UI-Canarys kann SetConfig folgende boolesche Parameter enthalten:

Methoden zum Aktivieren oder Deaktivieren von Screenshots

disableStepScreenshots()

Deaktiviert alle Screenshot-Optionen (ScreenShotOnStepStart, ScreenShotonStepSuccess und ScreenShotonStepFailure).

enableStepScreenshots()

Aktiviert alle Screenshot-Optionen (ScreenShotOnStepStart, ScreenShotonStepSuccess und ScreenShotonStepFailure). Standardmäßig sind alle diese Methoden aktiviert.

getScreenshotOnStepFailure()

Gibt zurück, ob der Canary einen Screenshot macht, nachdem ein Schritt fehlschlägt.

getScreenshotOnStepStart()

Gibt zurück, ob der Canary einen Screenshot erstellt, bevor er einen Schritt startet.

getScreenshotOnStepSuccess()

Gibt zurück, ob der Canary nach erfolgreichem Abschluss eines Schritts einen Screenshot erstellt.

withScreenshotOnStepStart(screenshotOnStepStart)

Akzeptiert ein boolesches Argument, das angibt, ob ein Screenshot erstellt werden soll, bevor ein Schritt gestartet wird.

withScreenshotOnStepSuccess(screenshotOnStepSuccess)

Akzeptiert ein boolesches Argument, das angibt, ob nach erfolgreichem Abschluss eines Schritts ein Screenshot erstellt werden soll.

withScreenshotOnStepFailure(screenshotOnStepFailure)

Akzeptiert ein boolesches Argument, das angibt, ob nach einem Schritt ein Screenshot erstellt werden soll.

Verwendung in UI-Canarys

Importieren Sie zuerst die Synthetics-Abhängigkeit und holen Sie die Konfiguration ab.

// Import Synthetics dependency
const synthetics = require('Synthetics');

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

Legen Sie dann die Konfiguration für jede Option fest, indem Sie die setConfig-Methode mit einer der folgenden Optionen aufrufen.

// Set configuration values
    synConfig.setConfig({
        screenshotOnStepStart: true, 
        screenshotOnStepSuccess: false,
        screenshotOnStepFailure: false
    });

Oder

synConfig.withScreenshotOnStepStart(false).withScreenshotOnStepSuccess(true).withScreenshotOnStepFailure(true)

Um alle Screenshots zu deaktivieren, verwenden Sie die disableStepScreenshots()-Funktion wie in diesem Beispiel.

synConfig.disableStepScreenshots();

Sie können Screenshots jederzeit im Code aktivieren oder deaktivieren. Wenn Sie beispielsweise Screenshots nur für einen Schritt deaktivieren möchten, deaktivieren Sie sie, bevor Sie diesen Schritt ausführen, und aktivieren Sie sie dann nach dem Schritt.

setConfig (Optionen) für API-Canarys

Für API-Canarys kann SetConfig folgende boolesche Parameter enthalten:

Visuelle Überwachung

Die visuelle Überwachung vergleicht Screenshots, die während eines Canary-Laufs aufgenommen wurden, mit Screenshots, die während eines Baseline-Canary-Laufs aufgenommen wurden. Wenn die Diskrepanz zwischen den beiden Screenshots einen Schwellenwert überschreitet, schlägt der Canary fehl, und Sie können die Bereiche mit Unterschieden in der Farbe im Canarylauf-Bericht sehen. Visuelle Überwachung wird in Canaries unterstützt, auf denen syn-puppeteer-node-3.2 und höher ausgeführt wird. Es wird derzeit nicht in Canarys unterstützt, die Python und Selenium ausführen.

Um die visuelle Überwachung zu aktivieren, fügen Sie dem Canary-Skript die folgende Codezeile hinzu. Weitere Details finden Sie unter SyntheticsConfiguration-Klasse.

syntheticsConfiguration.withVisualCompareWithBaseRun(true);

Wenn der Canary zum ersten Mal erfolgreich ausgeführt wird, nachdem diese Zeile zum Skript hinzugefügt wurde, verwendet er die während dieser Ausführung erstellten Screenshots als Vergleichsbasis. Nach der ersten Canary-Ausführung können Sie die CloudWatch-Konsole verwenden, um den Canary zu bearbeiten, um eine der folgenden Aktionen auszuführen:

Weitere Informationen zur Verwendung der CloudWatch-Konsole zum Bearbeiten eines Canary finden Sie unter Einen Canary bearbeiten oder löschen.

Weitere Optionen für die visuelle Überwachung

syntheticsConfiguration.withVisualVarianceThresholdPercentage(desiredPercentage)

Legen Sie den akzeptablen Prozentsatz für die Screenshot-Varianz in visuellen Vergleichen fest.

syntheticsConfiguration.withVisualVarianceHighlightHexColor("#fafa00")

Legen Sie die Hervorhebungsfarbe fest, die Varianzbereiche angibt, wenn Sie Canary-Lauf-Berichte betrachten, die visuelle Überwachung verwenden.

syntheticsConfiguration.withFailCanaryRunOnVisualVariance(failCanary)

Legen Sie fest, ob der Canary fehlschlägt, wenn ein visueller Unterschied größer als der Schwellenwert ist. Die Standardeinstellung ist, dass der Canary fehlschlägt.

Synthetics Logger

SyntheticsLogger schreibt Protokolle auf die Konsole und in eine lokale Protokolldatei auf derselben Protokollebene. Diese Protokolldatei wird nur dann an beide Speicherorte geschrieben, wenn die Protokollebene auf oder unter der gewünschten Protokollierungsebene der aufgerufenen Protokollfunktion liegt.

Den Protokollierungsanweisungen in der lokalen Protokolldatei werden je nach der Protokollebene der aufgerufenen Funktion „DEBUG“ „INFO“ usw. vorangestellt.

Sie können den SyntheticsLogger verwenden, wenn Sie Synethetics-Bibliothek auf der gleichen Protokollebene wie Ihre Synthetics-Canary-Protokollierung ausführen möchten.

Die Verwendung von SyntheticsLogger ist nicht erforderlich, um eine Protokolldatei zu erstellen, die zu Ihrem S3-Ergebnisspeicherort hochgeladen wird. Sie können stattdessen eine andere Protokolldatei im /tmp-Ordner erstellen. Alle Dateien, die unter dem /tmp-Ordner erstellt wurden, werden als Artefakte an den Ergebnisspeicherort in S3 hochgeladen.

So verwenden Sie den Synthetics Library Logger:

const log = require('SyntheticsLogger');

Nützliche Funktionsdefinitionen:

log.debug(message, ex);

Parameter: message ist die zu protokollierende Nachricht. ex ist die eventuell zu protokollierende Ausnahme.

Beispiel:

log.debug("Starting step - login.");

log.error(message, ex);

Parameter: message ist die zu protokollierende Nachricht. ex ist die eventuell zu protokollierende Ausnahme.

Beispiel:

try {
  await login();
catch (ex) {
  log.error("Error encountered in step - login.", ex);
}

log.info(message, ex);

Parameter: message ist die zu protokollierende Nachricht. ex ist die eventuell zu protokollierende Ausnahme.

Beispiel:

log.info("Successfully completed step - login.");

log.log(message, ex);

Dies ist ein Alias für log.info.

Parameter: message ist die zu protokollierende Nachricht. ex ist die eventuell zu protokollierende Ausnahme.

Beispiel:

 log.log("Successfully completed step - login.");

log.warn(message, ex);

Parameter: message ist die zu protokollierende Nachricht. ex ist die eventuell zu protokollierende Ausnahme.

Beispiel:

log.warn("Exception encountered trying to publish CloudWatch Metric.", ex);

SyntheticsLogHelper class

Die Klasse SyntheticsLogHelper ist in der Laufzeit syn-nodejs-puppeteer-3.2 und späteren Laufzeiten verfügbar. Sie ist bereits in der CloudWatch Synthetics-Bibliothek initialisiert und mit der Synthetics-Konfiguration konfiguriert. Sie können dies in Ihrem Skript als Abhängigkeit hinzufügen. Diese Klasse ermöglicht es Ihnen, URLs, Header und Fehlermeldungen zu bereinigen, um vertrauliche Informationen zu überarbeiten.

getSanitizedUrl(url, stepConfig = null)

Diese Funktion ist in syn-nodejs-puppeteer-3.2 und höher verfügbar. Es gibt bereinigt URL-Zeichenfolgen basierend auf der Konfiguration. Sie können sich dafür entscheiden, sensible URL-Parameter wie password und access_token zu schwärzen, indem Sie die Eigenschaft restrictedUrlParameters festlegen. Standardmäßig werden Passwörter in URLs geschwärzt. Sie können bei Bedarf URL-Passwörter aktivieren, indem Sie includeUrlPassword auf true setzen.

Diese Funktion löst einen Fehler aus, wenn die übergebene URL keine gültige URL ist.

Parameter

Beispiel

In diesem Beispiel wird die folgende Beispiel-URL verwendet :https://example.com/learn/home?access_token=12345&token_type=Bearer&expires_in=1200. In diesem Beispiel enthält access_token Ihre vertraulichen Informationen, die nicht protokolliert werden sollten. Beachten Sie, dass die Synthetics-Services keine Canary-Artefakte speichern. Artefakte wie Protokolle, Screenshots und Berichte werden in einem Amazon-S3-Bucket in Ihrem Kundenkonto gespeichert.

Der erste Schritt besteht darin, die Synthetics-Konfiguration festzulegen.

// 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'];
});
// Import SyntheticsLogHelper dependency
const syntheticsLogHelper = require('SyntheticsLogHelper');

const sanitizedUrl = syntheticsLogHelper.getSanitizedUrl('URL');



const urlConfig = {
   restrictedUrlParameters = ['*']
};
const sanitizedUrl = syntheticsLogHelper.getSanitizedUrl('URL', urlConfig);
logger.info('My example url is: ' + sanitizedUrl);
              

Als nächstes bereinigen und protokollieren Sie die URL

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

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

Dies protokolliert Folgendes in Ihrem Canaryprotokoll.

My example url is: https://example.com/learn/home?access_token=REDACTED&token_type=Bearer&expires_in=1200

Sie können die Synthetics-Konfiguration für eine URL überschreiben, indem Sie einen optionalen Parameter mit Synthetics-Konfigurationsoptionen übergeben, wie im folgenden Beispiel gezeigt.

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

Im obigen Beispiel werden alle Abfrageparameter geschwärzt und wie folgt protokolliert:

My example url is: https://example.com/learn/home?access_token=REDACTED&token_type=REDACTED&expires_in=REDACTED

getSanitizedErrorMessage

Diese Funktion ist in syn-nodejs-puppeteer-3.2 und höher verfügbar. Es gibt bereinigte Fehlerzeichenfolgen zurück, indem alle URLs, die auf der Synthetics-Konfiguration basieren, bereinigt werden. Sie können die globale Synthetics-Konfiguration überschreiben, wenn Sie diese Funktion aufrufen, indem Sie einen optionalen stepConfig-Parameter übergeben.

Parameter

Beispiel

In diesem Beispiel wird der folgende Fehler verwendet: Failed to load url: https://example.com/learn/home?access_token=12345&token_type=Bearer&expires_in=1200

Der erste Schritt besteht darin, die Synthetics-Konfiguration festzulegen.

// 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'];
});

Als nächstes bereinigen und protokollieren Sie die Fehlermeldung

// 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 = syntheticsLogHelper.getSanitizedErrorMessage(errorMessage);
    logger.info(sanitizedErrorMessage);
}

Dies protokolliert Folgendes in Ihrem Canaryprotokoll.

Failed to load url: https://example.com/learn/home?access_token=REDACTED&token_type=Bearer&expires_in=1200

getSanitizedHeaders(headers, stepConfig=null)

Diese Funktion ist in syn-nodejs-puppeteer-3.2 und höher verfügbar. Es gibt bereinigte Header basierend auf der restrictedHeaders-Eigenschaft von syntheticsConfiguration zurück. Die in der Eigenschaft restrictedHeaders angegebenen Header werden aus Protokollen, HAR-Dateien und Berichten entfernt.

Parameter

Node.js-Bibliotheksklassen und -funktionen, die nur für UI-Canaries gelten

Die folgenden CloudWatch Synthetics-Bibliotheksfunktionen für Node.js sind nur für UI-Canaries nützlich.

Synthetics-Klasse

Die folgenden Funktionen befinden sich in der Klasse Synthetics.

async addUserAgent(page, userAgentString);

Diese Funktion fügt UserAgentString an den User-Agent-Header der angegebenen Seite an.

Beispiel:

await synthetics.addUserAgent(page, "MyApp-1.0");

Bewirkt, dass der User-Agent-Header der Seite auf browsers-user-agent-header-valueMyApp-1.0 gesetzt wird.

async ExecuteStep (stepName, functionToExecute, [StepConfig]);

Führt den bereitgestellten Schritt aus und bettet ihn in Start/Pass/Fail-Protokollierung, Start/Pass/Fail-Screenshots sowie Pass/Fail- und Dauer-Metriken ein.

Die executeStep-Funktion tut Folgendes:

Wenn der Canary die Laufzeit syn-nodejs-2.0 oder höher verwendet, fügt diese Funktion dem Bericht des Canary auch eine Zusammenfassung der Schrittausführung hinzu. Die Zusammenfassung enthält Details zu jedem Schritt, wie Startzeit, Endzeit, Status (PASSED/FAILED), Fehlergrund (falls fehlgeschlagen) und Screenshots, die während der Ausführung jedes Schritts erfasst wurden.

Beispiel:

await synthetics.executeStep('navigateToUrl', async function (timeoutInMillis = 30000) {
           await page.goto(url, {waitUntil: ['load', 'networkidle0'], timeout: timeoutInMillis});});

Antwort:

Gibt zurück, was functionToExecute zurückgibt.

Updates mit syn-nodejs-2.2

Beginnend mit syn-nodejs-2.2 können Sie optional Schrittkonfigurationen übergeben, um CloudWatch-Synthetics-Konfigurationen auf Schrittebene zu überschreiben. Eine Liste der Optionen, die Sie an executeStep übergeben können, finden Sie unter SyntheticsConfiguration-Klasse.

Das folgende Beispiel überschreibt die false-Standardkonfiguration für continueOnStepFailure bis true und gibt an, wann Screenshots erstellt werden sollen.

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

Die getDefaultLaunchOptions()-Funktion gibt die Browserstartoptionen zurück, die von CloudWatch Synthetics verwendet werden. Weitere Informationen finden Sie unter Startoptionen-Typ

// This function returns default launch options used by Synthetics.
const defaultOptions = await synthetics.getDefaultLaunchOptions();

getPage();

Gibt die aktuell geöffnete Seite als Puppeteer-Objekt zurück. Weitere Informationen finden Sie unter Puppeteer API v1.14.0.

Beispiel:

let page = await synthetics.getPage();

Antwort:

Die Seite (Puppeteer-Objekt), die derzeit in der aktuellen Browsersitzung geöffnet ist.

getRequestResponseLogHelper();

Verwenden Sie diese Funktion als Builder-Muster zum Optimieren der Anforderungs- und Antwortprotokollierungsmarkierungen.

Beispiel:

synthetics.setRequestResponseLogHelper(getRequestResponseLogHelper().withLogRequestHeaders(false));;

Antwort:

{RequestResponseLogHelper}

Start (Optionen)

Die Optionen für diese Funktion sind erst ab der Laufzeit-Version syn-nodejs-2.1 verfügbar.

Diese Funktion wird nur für UI-Canarys verwendet. Es schließt den vorhandenen Browser und startet einen neuen.

(Optionen) ist ein konfigurierbarer Satz von Optionen, die im Browser festgelegt werden sollen. Weitere Informationen finden Sie unter Startoptionen-Typ.

Wenn Sie diese Funktion ohne Optionen aufrufen, startet Synthetics einen Browser mit Standardargumenten executablePath und defaultViewport. Das Standard-Ansichtsfenster in CloudWatch Synthetics ist 1920 x 1080.

Sie können Startparameter, die von CloudWatch Synthetics verwendet werden, überschreiben und beim Starten des Browsers zusätzliche Parameter übergeben. Mit dem folgenden Codeausschnitt wird beispielsweise ein Browser mit Standardargumenten und einem standardmäßigen ausführbaren Pfad gestartet, jedoch mit einem Ansichtsfenster von 800 x 600.

await synthetics.launch({
        defaultViewport: { 
            "deviceScaleFactor": 1, 
            "width": 800,
            "height": 600 
    }});

Der folgende Beispielcode fügt den Startparametern von CloudWatch Synthetics einen neuen Parameter ignoreHTTPSErrors hinzu:

await synthetics.launch({
        ignoreHTTPSErrors: true
 });

Sie können die Websicherheit deaktivieren, indem Sie args in den Startparametern von CloudWatch Synthetics ein --disable-web-security-Flag hinzufügen:

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

Behandelt die präzise Konfiguration und Erstellung von Zeichenfolgendarstellungen von Anforderungs- und Antwort-Nutzlasten.

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

Beispiel:

synthetics.setRequestResponseLogHelper(getRequestResponseLogHelper()
.withLogRequestPostData(true)
.withLogRequestHeaders(true)
.withLogResponseHeaders(true));

Antwort:

{RequestResponseLogHelper}

setRequestResponseLogHelper();

Verwenden Sie diese Funktion als Builder-Muster zum Einstellen der Anforderungs- und Antwortprotokollierungsmarkierungen.

Beispiel:

synthetics.setRequestResponseLogHelper().withLogRequestHeaders(true).withLogResponseHeaders(true);

Antwort:

{RequestResponseLogHelper}

async takeScreenshot(name, suffix);

Erstelle einen Screenshot (.PNG) der aktuellen Seite mit Name und Suffix (Optional).

Beispiel:

await synthetics.takeScreenshot("navigateToUrl", "loaded")

In diesem Beispiel wird ein Screenshot mit dem Namen 01-navigateToUrl-loaded.png aufgenommen und in den S3 Bucket des Canary hochgeladen.

Sie können einen Screenshot für einen bestimmten Canary-Schritt erstellen, indem Sie das stepName als ersten Parameter übergeben. Screenshots sind mit dem Canaryschritt in Ihren Berichten verknüpft, damit Sie jeden Schritt beim Debuggen verfolgen können.

CloudWatch-Synthetics-Canarys erstellen automatisch Screenshots, bevor sie einen Schritt starten (die executeStep-Funktion), und nach dem Abschluss des Schritts (es sei denn, Sie konfigurieren den Canary für die Deaktivierung von Screenshots). Sie können weitere Screenshots erstellen, indem Sie den Schrittnamen in der takeScreenshot-Funktion übergeben.

Im folgenden Beispiel wird ein Screenshot mit dem signupForm als Wert von stepName erstellt. Der Screenshot erhält den Namen 02-signupForm-address und wird mit dem Schritt namens signupForm im Canary-Bericht verknüpft.

await synthetics.takeScreenshot('signupForm', 'address')

BrokenLinkCheckerReport-Klasse

Diese Klasse bietet Methoden, um eine Synthetics-Verknüpfung hinzuzufügen. Es wird nur auf Canarysn unterstützt, die die syn-nodejs-2.0-beta-Version der Laufzeitumgebung oder höher verwenden.

Um BrokenLinkCheckerReport zu verwenden, fügen Sie die folgenden Zeilen in das Skript ein:

const BrokenLinkCheckerReport = require('BrokenLinkCheckerReport');
            
const brokenLinkCheckerReport = new BrokenLinkCheckerReport();

Nützliche Funktionsdefinitionen:

addLink(syntheticsLink, isBroken)

syntheticsLink ist ein SyntheticsLink-Objekt, das eine Verknüpfung darstellt. Diese Funktion fügt den Link entsprechend dem Statuscode hinzu. Standardmäßig betrachtet es einen Link als unterbrochen, wenn der Statuscode nicht verfügbar ist oder der Statuscode 400 oder höher ist. Sie können dieses Standardverhalten überschreiben, indem Sie den optionalen Parameter isBrokenLink mit einem Wert vontrue oder false übergeben.

Diese Funktion hat keinen Rückgabewert.

getLinks()

Diese Funktion gibt ein Array von SyntheticsLink-Objekten zurück, die im Bericht zur Überprüfung von defekten Links enthalten sind.

getTotalBrokenLinks()

Diese Funktion gibt eine Zahl zurück, die die Gesamtzahl der defekten Links darstellt.

getTotalLinksChecked()

Diese Funktion gibt eine Zahl zurück, die die Gesamtzahl der im Bericht enthaltenen Links darstellt.

Funktionsweise von BrokenLinkCheckerReport

Das folgende Code-Snippet aus einem Canary-Skript veranschaulicht anhand eines Beispiels die Navigation zu einem Link und das Hinzufügen zum Bericht zur Überprüfung eines fehlerhaften Links.

SyntheticsLink-Klasse

Diese Klasse bietet Methoden zum Umschließen von Informationen. Es wird nur auf Canaries unterstützt, die die syn-nodejs-2.0-beta-Version der Laufzeit oder höher verwenden.

Um SyntheticsLink zu verwenden, fügen Sie die folgenden Zeilen in das Skript ein:

const SyntheticsLink = require('SyntheticsLink');

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

Diese Funktion gibt syntheticsLinkObject zurück

Nützliche Funktionsdefinitionen:

withUrl(url)

url ist eine URL-Zeichenfolge. Diese Funktion gibt syntheticsLinkObject zurück

withText(text)

text ist eine Zeichenfolge, die Ankertext darstellt. Diese Funktion gibt syntheticsLinkObject zurück. Es fügt Ankertext hinzu, der dem Link entspricht.

withParentUrl(parentUrl)

parentUrl ist eine Zeichenfolge, die die übergeordnete URL (Quellseite) darstellt. Diese Funktion gibt syntheticsLinkObject zurück

withStatusCode(statusCode)

statusCode ist eine Zeichenfolge, die den Statuscode darstellt. Diese Funktion gibt syntheticsLinkObject zurück

withFailureReason(failureReason)

failureReason ist eine Zeichenfolge, die den Grund für den Fehler darstellt. Diese Funktion gibt syntheticsLinkObject zurück

addScreenshotResult(screenshotResult)

screenshotResult ist ein Objekt. Es ist eine Instance von ScreenshotResult, die von der Synthetics-Funktion takeScreenshot zurückgegeben wurde. Das Objekt umfasst Folgendes:

Node.js-Bibliotheksklassen und -funktionen, die nur für API-Canaries gelten

Die folgenden CloudWatch Synthetics-Bibliotheksfunktionen für Node.js sind nur für API-Canaries nützlich.

executeHttpStep(stepName, requestOptions, [callback], [stepConfig])

Führt die bereitgestellte HTTP-Anforderung als Schritt aus und veröffentlicht SuccessPercent- (pass/fail) und Duration-Metriken.

ExecuteHttpStep verwendet entweder HTTP- oder HTTPS-native Funktionen unter der Haube, abhängig vom Protokoll, das in der Anforderung angegeben ist.

Diese Funktion fügt dem Bericht des Canarys außerdem eine Zusammenfassung der Schrittausführung hinzu. Die Zusammenfassung enthält Details zu jeder HTTP-Anforderung, wie zum Beispiel die folgenden:

Parameter

stepName(String)

Legt den Namen des Schrittes fest. Dieser Name wird auch für die Veröffentlichung von CloudWatch-Metriken für diesen Schritt verwendet.

requestOptions(Object or String)

Der Wert dieses Parameters kann eine URL, eine URL-Zeichenfolge oder ein Objekt sein. Wenn es sich um ein Objekt handelt, muss es sich um eine Gruppe konfigurierbarer Optionen handeln, um eine HTTP-Anforderung zu stellen. Es unterstützt alle Optionen in http.request(options[, callback]) in der Node.js-Dokumentation.

Zusätzlich zu diesen Node.js-Optionen unterstützt requestOptions den zusätzlichen Parameter body. Sie können den Parameter body verwenden, um Daten als Anforderungstext zu übergeben.

callback(response)

(Optional) Dies ist eine Benutzerfunktion, die mit der HTTP-Antwort aufgerufen wird. Die Antwort ist vom Typ Klasse: http.IncomingMessage.

stepConfig(object)

(Optional) Verwenden Sie diesen Parameter, um globale Synthetics-Konfigurationen mit einer anderen Konfiguration für diesen Schritt zu überschreiben.

Beispiele für die Verwendung von ExecuteHttpStep

Die folgende Reihe von Beispielen baut aufeinander auf, um die verschiedenen Verwendungsmöglichkeiten dieser Option zu veranschaulichen.

In diesem ersten Beispiel werden Anforderungsparameter konfiguriert. Sie können eine URL als RequestOptions übergeben:

let requestOptions = 'https://www.amazon.com';

Oder Sie können eine Reihe von Optionen übergeben:

let requestOptions = {
        'hostname': 'myproductsEndpoint.com',
        'method': 'GET',
        'path': '/test/product/validProductName',
        'port': 443,
        'protocol': 'https:'
    };

Das nächste Beispiel erstellt eine Callback-Funktion, die eine Antwort akzeptiert. Wenn Sie keinen Callback angeben, überprüft CloudWatch Synthetics standardmäßig, dass der Status zwischen 200 und 299 (einschließlich) liegt.

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

Im nächsten Beispiel wird eine Konfiguration für diesen Schritt erstellt, die die globale CloudWatch-Synthetics-Konfiguration außer Kraft setzt. Die Schrittkonfiguration in diesem Beispiel ermöglicht Anforderungskopfzeilen, Antwort-Header, Anforderungstext (Postdaten) und Antworttext in Ihrem Bericht und schränkt die Header-Werte „X-AMZ-Security-Token“ und „Authorization“ ein. Standardmäßig sind diese Werte aus Sicherheitsgründen nicht im Bericht enthalten. Wenn Sie sie einbeziehen, werden die Daten nur in Ihrem S3 Bucket gespeichert.

// 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
};

Dieses letzte Beispiel übergibt Ihre Anfrage an executeHttpStep und benennt den Schritt.

await synthetics.executeHttpStep('Verify GET products API', requestOptions, callback, stepConfig);

Mit diesem Satz von Beispielen fügt CloudWatch Synthetics die Details aus jedem Schritt in Ihrem Bericht hinzu und erstellt Metriken für jeden Schritt mithilfe von stepName.

Sie sehen successPercent- und duration-Metriken für den Schritt Verify GET products API. Sie können Ihre API-Leistung überwachen, indem Sie die Metriken für Ihre API-Aufrufschritte überwachen.

Ein vollständiges Beispielskript, das diese Funktionen verwendet, finden Sie unter Mehrstufiger API-Canary.