Le traduzioni sono generate tramite traduzione automatica. In caso di conflitto tra il contenuto di una traduzione e la versione originale in Inglese, quest'ultima prevarrà. # Scrivere uno script canary Le sezioni seguenti spiegano come scrivere uno script canarino e come integrare un canary con altri AWS servizi e con dipendenze e librerie esterne. **Topics** + [ # Scrittura di uno script canary utilizzando il runtime Java ](Synthetics_WritingCanary_Java.md) + [ # Scrittura di uno script canary Node.js utilizzando il runtime Playwright ](Synthetics_WritingCanary_Nodejs_Playwright.md) + [ # Scrittura di uno script canary Node.js utilizzando il runtime Puppeteer ](CloudWatch_Synthetics_Canaries_WritingCanary_Nodejs_Pup.md) + [ # Scrivere uno script canary Python ](CloudWatch_Synthetics_Canaries_WritingCanary_Python.md) + [ # Scrittura di una configurazione JSON per il blueprint Node.js multi Checks ](CloudWatch_Synthetics_WritingCanary_Multichecks.md) # Scrittura di uno script canary utilizzando il runtime Java **Topics** + [ ## Struttura del progetto Java per un canary ](#Synthetics_canary_Java_package) + [ ## Impacchettamento del progetto per un canary ](#Synthetics_canary_Java_package_canary) + [ ## Nome del gestore ](#Synthetics_canary_Java_handler) + [ ## CloudWatch Configurazioni Synthetics ](#Synthetics_canary_Java_config) + [ ## CloudWatch Variabili di ambiente Synthetics ](#Synthetics_canary_Java_variables) ## Struttura del progetto Java per un canary Per creare un canary in Java, è necessario scrivere il codice, compilarlo e implementare gli artefatti compilati su Synthetics. È possibile inizializzare un progetto Java Lambda in vari modi. Ad esempio, puoi utilizzare una configurazione di progetto Java standard nel tuo IDE preferito, come IntelliJ IDEA o Visual Studio Code. In alternativa, è possibile creare manualmente la struttura di file richiesta. Un progetto Java Synthetics contiene la seguente struttura generale: ``` /project-root └ src └ main └ java └ canarypackage // name of package | └ ExampleCanary.java // Canary code file | └ other_supporting_classes - resources └ synthetics.json // Synthetics configuration file └ build.gradle OR pom.xml ``` Puoi usare Maven o Gradle per creare il tuo progetto e gestire le dipendenze. Nella struttura precedente, la classe `ExampleCanary` è il punto di ingresso o il gestore per il canary. **Esempio di classe canary in Java** Questo esempio prevede che un canarino effettui una richiesta get a un URL memorizzato nella variabile di ambiente *TESTING\$1URL* Lambda. Il canary non utilizza nessuno dei metodi forniti dal runtime Synthetics. ``` package canarypackage; import java.net.HttpURLConnection; import java.net.URL; // Handler value: canary.ExampleCanary::canaryCode public class ExampleCanary { public void canaryCode() throws Exception{ URL url = new URL(System.getenv("TESTING_URL")); HttpURLConnection con=(HttpURLConnection)url.openConnection(); con.setRequestMethod("GET"); con.setConnectTimeout(5000); con.setReadTimeout(5000); int status=con.getResponseCode(); if(status!=200){ throw new Exception("Failed to load " + url + ", status code: " + status); } } } ``` È fortemente consigliata la suddivisione in moduli dei canary utilizzando la funzione di libreria `executeStep` fornita da Synthetics. Il canarino effettua `get` chiamate a due variabili separate URLs , provenienti da e di ambiente. URL1 URL2 **Nota** Per utilizzare la funzionalità `executeStep`, il metodo del gestore per il canary dovrebbe contemplare un parametro di tipo Synthetics come mostrato di seguito. ``` package canarypackage; import com.amazonaws.synthetics.Synthetics; import java.net.HttpURLConnection; import java.net.URL; // Handler value: canary.ExampleCanary::canaryCode public class ExampleCanary { public void canaryCode(Synthetics synthetics) throws Exception { createStep("Step1", synthetics, System.getenv("URL1")); createStep("Step2", synthetics, System.getenv("URL2")); return; } private void createStep(String stepName, Synthetics synthetics, String url) throws Exception{ synthetics.executeStep(stepName,()->{ URL obj=new URL(url); HttpURLConnection con=(HttpURLConnection)obj.openConnection(); con.setRequestMethod("GET"); con.setConnectTimeout(5000); con.setReadTimeout(5000); int status=con.getResponseCode(); if(status!=200){ throw new Exception("Failed to load" + url + "status code:" + status); } return null; }).get(); } } ``` ## Impacchettamento del progetto per un canary Synthetics accetta il codice per un canary java in formato *zip*. Lo zip è composto dai file di classe per il codice canary, dai jar per eventuali dipendenze di terze parti e dal file di configurazione Synthetics. Uno zip Java Synthetics contiene la seguente struttura generale. ``` example-canary └ lib | └ //third party dependency jars └ java-canary.jar └ synthetics.json ``` Per creare questo zip dalla struttura del progetto precedente, puoi usare gradle (build.gradle) o maven (pom.xml). Ecco un esempio. [Per informazioni sulle dipendenze o sulle interfacce in fase di compilazione per la libreria Synthetics, vedere il README in -java. aws-cloudwatch-synthetics-sdk](https://github.com/aws/aws-cloudwatch-synthetics-sdk-java/tree/main) ``` plugins { id 'java' } repositories { mavenCentral() } dependencies { // Third party dependencies // example: implementation 'software.amazon.awssdk:s3:2.31.9' // Declares dependency on Synthetics interfaces for compiling only // Refer https://github.com/aws/aws-cloudwatch-synthetics-sdk-java for building from source. compileOnly 'software.amazon.synthetics:aws-cloudwatch-synthetics-sdk-java:1.0.0'} test { useJUnitPlatform() } // Build the zip to be used as Canary code. task buildZip(type: Zip) { archiveFileName.set("example-canary.zip") destinationDirectory.set(file("$buildDir")) from processResources into('lib') { from configurations.runtimeClasspath from(tasks.named("jar")) } from "src/main/java/resources/synthetics.json" doLast { println "Artifact written to: ${archiveFile.get().asFile.absolutePath}" } } java { toolchain { languageVersion = JavaLanguageVersion.of(21) } } tasks.named("build") { dependsOn "buildZip" } ``` ## Nome del gestore Il nome del gestore è il punto di ingresso per il canary. Per il runtime Java, il gestore ha il seguente formato. ``` <>::<> // for above code: canarypackage.ExampleCanary::canaryCode ``` ## CloudWatch Configurazioni Synthetics È possibile configurare il comportamento del runtime Java Synthetics fornendo un file di configurazione JSON facoltativo denominato `synthetics.json`. Questo file deve essere incluso nella directory root dell'archivio zip del pacchetto. Sebbene un file di configurazione sia facoltativo, se non viene fornito un file di configurazione o manca una chiave di configurazione, CloudWatch utilizza le impostazioni predefinite. Di seguito sono riportati i valori di configurazione supportati e i relativi valori predefiniti. ``` { "step": { "stepSuccessMetric": true, "stepDurationMetric": true, "continueOnStepFailure": false, "stepsReport": true }, "logging": { "logRequest": false, "logResponse": false }, "httpMetrics": { "metric_2xx": true, "metric_4xx": true, "metric_5xx": true, "aggregated2xxMetric": true, "aggregated4xxMetric": true, "aggregated5xxMetric": true }, "canaryMetrics": { "failedCanaryMetric": true, "aggregatedFailedCanaryMetric": true } } ``` **Configurazioni di passaggio** + *continueOnStepFallimento*: determina se uno script deve continuare anche dopo che un passaggio è fallito. Il valore predefinito è false. + *stepSuccessMetric*: determina se viene emessa la metrica ` SuccessPercent` di un passaggio. La `SuccessPercent` metrica per un passaggio è *100* per l'esecuzione di Canary se l'operazione ha esito positivo e *0* se la fase fallisce. Il valore predefinito è *true*. + *stepDurationMetric*— Determina se viene emessa la metrica della *durata* di un passaggio. La metrica *Duration* viene emessa come durata, in millisecondi, dell'esecuzione del passaggio. *L'impostazione predefinita è true.* **Configurazioni di registrazione** Si applica ai log generati da CloudWatch Synthetics. Controlla la verbosità dei log di richieste e risposte. + *logRequest*: specifica se registrare ogni richiesta nei log del canary. Il valore predefinito è false. + *logResponse*: specifica se registrare ogni risposta nei log del canary. Il valore predefinito è false. **Configurazioni delle metriche HTTP** Configurazioni per le metriche relative al conteggio delle richieste di rete con codici di stato HTTP diversi, emesse da Synthetics CloudWatch per questo canarino. + *metric\$12xx — Speciifica se emettere la metrica 2xx* *(con la dimensione) per questo canarino.* CanaryName Il valore predefinito è *true*. + *metric\$14xx — Speciifica se emettere la metrica 4xx* *(con la dimensione) per questo canarino.* CanaryName Il valore predefinito è *true*. + *metric\$15xx — Speciifica se emettere la metrica 5xx* *(con la dimensione) per questo canarino.* CanaryName Il valore predefinito è *true*. + *Aggregated2xxMetric: specifica se emettere la metrica* *2xx (senza la dimensione) per questo canarino.* CanaryName Il valore predefinito è *true*. + *Aggregated4xxMetric: specifica se emettere la metrica 4xx* *(senza la dimensione) per questo canarino.* CanaryName Il valore predefinito è *true*. + *Aggregated5xxMetric: specifica se emettere la metrica 5xx* *(senza la dimensione) per questo canarino.* CanaryName Il valore predefinito è *true*. **Configurazioni delle metriche del canary** Configurazioni per altre metriche emesse da Synthetics. CloudWatch + *failedCanaryMetric*Network Access Analyzer specifica se emettere la metrica *Failed* (con la dimensione) per questo canarino. CanaryName Il valore predefinito è *true*. + *aggregatedFailedCanaryMetrica*: specifica se emettere la metrica *Failed (senza* la dimensione) per questo canarino. CanaryName Il valore predefinito è *true*. ## CloudWatch Variabili di ambiente Synthetics È possibile configurare il livello e il formato di registrazione utilizzando le variabili di ambiente. **Formato dei log** Il CloudWatch runtime Java Synthetics CloudWatch crea registri per ogni esecuzione di Canary. I log sono scritti in formato JSON per facilitare le interrogazioni. Facoltativamente, è possibile modificare il formato del log in *TEXT*. + *Nome della variabile di ambiente*: CW\$1SYNTHETICS\$1LOG\$1FORMAT + *Valori supportati*: JSON, TEXT + *Impostazione predefinita*: JSON **Livelli di log** + *Nome della variabile di ambiente*: CW\$1SYNTHETICS\$1LOG\$1LEVEL + *Valori supportati*: TRACE, DEBUG, INFO, WARN, ERROR, FATAL + *Impostazione predefinita*: INFO Oltre alle variabili di ambiente di cui sopra, ne è stata aggiunta una predefinita per il runtime Java, la variabile di ambiente `AWS_LAMBDA-EXEC_WRAPPER` per la tua funzione, e il valore è impostato su `/opt/synthetics-otel-instrument`. Questa variabile di ambiente modifica il comportamento di startup della funzione per la telemetria. Se questa variabile di ambiente esiste già, assicurati che sia impostata sul valore richiesto. # Scrittura di uno script canary Node.js utilizzando il runtime Playwright **Topics** + [ ## Creazione di pacchetti dei file canary Node.js per il runtime di Playwright ](#Synthetics_canary_Nodejs_Playwright_package) + [ ## Modifica di uno script Playwright esistente da utilizzare come canarino Synthetics CloudWatch ](#CloudWatch_Synthetics_canary_edit_Playwright_script) + [ ## CloudWatch Configurazioni Synthetics ](#Synthetics_canary_configure_Playwright_script) ## Creazione di pacchetti dei file canary Node.js per il runtime di Playwright Il tuo script canary comprende un file `.js` (sintassi CommonJS) o `.mjs` (sintassi ES) contenente il codice del gestore Synthetics, insieme a tutti i pacchetti e moduli aggiuntivi da cui dipende il codice. Gli script creati in formato ES (ECMAScript) devono utilizzare .mjs come estensione o includere un file package.json con il set di campi «type»: «module». A differenza di altri runtime come Node.js Puppeteer, non è necessario salvare gli script in una struttura di cartelle specifica. Puoi direttamente creare pacchetti dei tuoi script. Utilizza il tuo strumento di compressione `zip` preferito per creare un file `.zip` con il file gestore nella directory root. Se il tuo script canary dipende da pacchetti o moduli aggiuntivi non inclusi nel runtime Synthetics, puoi aggiungere queste dipendenze al tuo file `.zip`. A tale scopo, puoi installare le librerie richieste dalla tua funzione nella directory `node_modules` eseguendo il comando `npm install`. I seguenti comandi della CLI di esempio creano un file `.zip` denominato `my_deployment_package.zip`, contenente il file `index.js` o `index.mjs` (gestore Synthetics) e le relative dipendenze. Nell'esempio, installi le dipendenze utilizzando il gestore di pacchetti `npm`. ``` ~/my_function ├── index.mjs ├── synthetics.json ├── myhelper-util.mjs └── node_modules ├── mydependency ``` Crea un file `.zip` dei contenuti della cartella di progetto della directory root. Utilizza l'opzione `r` (ricorsiva), come illustrato nell'esempio seguente, per assicurarti che `zip` comprima le sottocartelle. ``` zip -r my_deployment_package.zip . ``` Aggiungi un file di configurazione Synthetics per configurare il comportamento di Synthetics. CloudWatch Puoi creare un file `synthetics.json` e salvarlo nello stesso percorso del punto di ingresso o del file del gestore. Facoltativamente, puoi anche archiviare il file del punto di ingresso in una struttura di cartelle a tua scelta. Tuttavia, assicurati che il percorso della cartella sia specificato nel nome del gestore. **Nome del gestore** Assicurati di impostare il punto di ingresso dello script del tuo canary (gestore) in modo che ` myCanaryFilename.functionName` corrisponda al nome del file del punto di ingresso dello script. Facoltativamente, puoi anche archiviare il canary in una cartella separata, ad esempio ` myFolder/my_canary_filename.mjs`. Se lo archivi in una cartella separata, definisci il percorso nel punto di ingresso dello script, ad esempio ` myFolder/my_canary_filename.functionName`. ## Modifica di uno script Playwright esistente da utilizzare come canarino Synthetics CloudWatch Puoi modificare uno script esistente per Node.js e Playwright da utilizzare come canary. Per ulteriori informazioni su Playwright, consulta la documentazione [Playwright library](https://playwright.dev/docs/api/class-playwright). Puoi utilizzare il seguente script Playwright salvato nel file ` exampleCanary.mjs`. ``` import { chromium } from 'playwright'; import { expect } from '@playwright/test'; const browser = await chromium.launch(); const page = await browser.newPage(); await page.goto('https://example.com', {timeout: 30000}); await page.screenshot({path: 'example-home.png'}); const title = await page.title(); expect(title).toEqual("Example Domain"); await browser.close(); ``` Converti lo script seguendo i passaggi di seguito: 1. Creare ed esportare una funzione `handler`. Il gestore è la funzione del punto di ingresso per lo script. Puoi scegliere qualsiasi nome per la funzione del gestore, ma la funzione utilizzata nel tuo script dovrebbe essere la stessa nel gestore del tuo canary. Se il nome del tuo script è `exampleCanary.mjs`, e il nome della funzione del gestore è `myhandler`, il tuo gestore canary è denominato `exampleCanary.myhandler`. Nell'esempio seguente, il nome della funzione del gestore è `handler`. ``` exports.handler = async () => { // Your script here }; ``` 1. Importa il `Synthetics Playwright module` come dipendenza. ``` import { synthetics } from '@aws/synthetics-playwright'; ``` 1. Avvia un browser utilizzando la funzione `Launch` di Synthetics. ``` const browser = await synthetics.launch(); ``` 1. Crea una nuova pagina Playwright utilizzando la funzione `newPage` di Synthetics. ``` const page = await synthetics.newPage(); ``` Il tuo script è ora pronto per essere eseguito come canary di Synthetics. Di seguito è riportato lo script aggiornato: ** ES6 Formato dello script aggiornato** Il file di script salvato con un'estensione `.mjs`. ``` import { synthetics } from '@aws/synthetics-playwright'; import { expect } from '@playwright/test'; export const handler = async (event, context) => { try { // Launch a browser const browser = await synthetics.launch(); // Create a new page const page = await synthetics.newPage(browser); // Navigate to a website await page.goto('https://www.example.com', {timeout: 30000}); // Take screenshot await page.screenshot({ path: '/tmp/example.png' }); // Verify the page title const title = await page.title(); expect(title).toEqual("Example Domain"); } finally { // Ensure browser is closed await synthetics.close(); } }; ``` **Script aggiornato in formato CommonJS** Il file di script salvato con un'estensione `.js`. ``` const { synthetics } = require('@aws/synthetics-playwright'); const { expect } = require('@playwright/test'); exports.handler = async (event) => { try { const browser = await synthetics.launch(); const page = await synthetics.newPage(browser); await page.goto('https://www.example.com', {timeout: 30000}); await page.screenshot({ path: '/tmp/example.png' }); const title = await page.title(); expect(title).toEqual("Example Domain"); } finally { await synthetics.close(); } }; ``` ## CloudWatch Configurazioni Synthetics Puoi configurare il comportamento del runtime Synthetics Playwright fornendo un file di configurazione JSON facoltativo denominato `synthetics.json`. Questo file dovrebbe essere incluso nella stessa posizione del file gestore. Sebbene un file di configurazione sia facoltativo, se non viene fornito un file di configurazione o manca una chiave di configurazione, vengono utilizzati i valori predefiniti. CloudWatch **Creazione di un pacchetto del file di configurazione** Di seguito sono riportati i valori di configurazione supportati e i relativi valori predefiniti. ``` { "step": { "screenshotOnStepStart": false, "screenshotOnStepSuccess": false, "screenshotOnStepFailure": false, "stepSuccessMetric": true, "stepDurationMetric": true, "continueOnStepFailure": true, "stepsReport": true }, "report": { "includeRequestHeaders": true, "includeResponseHeaders": true, "includeUrlPassword": false, "includeRequestBody": true, "includeResponseBody": true, "restrictedHeaders": ['x-amz-security-token', 'Authorization'], // Value of these headers is redacted from logs and reports "restrictedUrlParameters": ['Session', 'SigninToken'] // Values of these url parameters are redacted from logs and reports }, "logging": { "logRequest": false, "logResponse": false, "logResponseBody": false, "logRequestBody": false, "logRequestHeaders": false, "logResponseHeaders": false }, "httpMetrics": { "metric_2xx": true, "metric_4xx": true, "metric_5xx": true, "failedRequestsMetric": true, "aggregatedFailedRequestsMetric": true, "aggregated2xxMetric": true, "aggregated4xxMetric": true, "aggregated5xxMetric": true }, "canaryMetrics": { "failedCanaryMetric": true, "aggregatedFailedCanaryMetric": true }, "userAgent": "", "har": true } ``` **Configurazioni di passaggio** + `screenshotOnStepStart`: determina se Synthetics deve acquisire uno screenshot prima dell'inizio del passaggio. Il valore predefinito è `true`. + `screenshotOnStepSuccess`: determina se Synthetics deve acquisire uno screenshot dopo che un passaggio ha avuto esito positivo. Il valore predefinito è `true`. + `screenshotOnStepFailure`: determina se Synthetics deve acquisire uno screenshot dopo che un passaggio ha avuto esito negativo. Il valore predefinito è `true`. + `continueOnStepFailure`: determina se uno script deve continuare anche dopo un passaggio non riuscito. Il valore predefinito è `false`. + `stepSuccessMetric`: determina se viene emessa la metrica ` SuccessPercent` di un passaggio. La metrica `SuccessPercent` per un passaggio vale `100` per l'esecuzione canary se il passaggio ha esito positivo, mentre `0` se ha esito negativo. Il valore predefinito è `true`. + `stepDurationMetric`: determina se viene emessa la metrica `Duration` di un passaggio. La metrica `Duration` viene emessa come durata, in millisecondi, dell'esecuzione del passaggio. Il valore predefinito è `true`. **Configurazioni dei report** Include tutti i report generati da CloudWatch Synthetics, come un file HAR e un rapporto sui passaggi di Synthetics. Anche i campi di redazione dei dati sensibili `restrictedHeaders` e `restrictedUrlParameters` si applicano ai log generati da Synthetics. + `includeRequestHeaders`: indica se includere le intestazioni della richiesta nel report. Il valore predefinito è `false`. + `includeResponseHeaders`: indica se includere le intestazioni della risposta nel report. Il valore predefinito è `false`. + `includeUrlPassword`: indica se includere una password visualizzata nell'URL. Per impostazione predefinita, le password che compaiono in URLs vengono cancellate dai log e dai report, per impedire la divulgazione di dati sensibili. Il valore predefinito è `false`. + `includeRequestBody`: indica se includere il corpo della richiesta nel report. Il valore predefinito è `false`. + `includeResponseBody`: indica se includere il corpo della risposta nel report. Il valore predefinito è `false`. + `restrictedHeaders`: un elenco di valori di intestazione da ignorare, se le intestazioni sono incluse. Questo vale sia per le intestazioni della richiesta che della risposta. Ad esempio, puoi nascondere le tue credenziali inserendo `includeRequestHeaders` come true e `restrictedHeaders` come `['Authorization']`. + `restrictedUrlParameters`: un elenco di parametri del percorso dell'URL o della query da oscurare. Questo vale per quelle URLs che appaiono nei log, nei report e negli errori. Il parametro prevede la distinzione tra lettere maiuscole e minuscole. Puoi passare un asterisco (`*`) come valore per oscurare tutti i valori dei parametri del percorso dell'URL e delle query. L'impostazione predefinita è una matrice vuota. + `har`: determina se deve essere generato un archivio HTTP (HAR). Il valore predefinito è `true`. Di seguito è riportato un esempio di file di configurazioni del report. ``` "includeRequestHeaders": true, "includeResponseHeaders": true, "includeUrlPassword": false, "includeRequestBody": true, "includeResponseBody": true, "restrictedHeaders": ['x-amz-security-token', 'Authorization'], // Value of these headers is redacted from logs and reports "restrictedUrlParameters": ['Session', 'SigninToken'] // Values of these URL parameters are redacted from logs and reports ``` **Configurazioni di registrazione** Si applica ai log generati da CloudWatch Synthetics. Controlla la verbosità dei log di richieste e risposte. + `logRequest`: indica se registrare ogni richiesta nei log del canary. Per i canary dell'interfaccia utente, registra ogni richiesta inviata dal browser. Il valore predefinito è ` false`. + `logResponse`: indica se registrare ogni risposta nei log del canary. Per i canary dell'interfaccia utente, registra ogni risposta ricevuta dal browser. Il valore predefinito è ` false`. + `logRequestBody`: indica se registrare i corpi delle richieste insieme alle richieste nei log dei canary. Questa configurazione si applica solo se `logRequest` è true. Il valore predefinito è `false`. + `logResponseBody`: indica se registrare i corpi delle risposte insieme alle richieste nei log dei canary. Questa configurazione si applica solo se `logResponse` è true. Il valore predefinito è `false`. + `logRequestHeaders`: indica se registrare le intestazioni delle richieste insieme alle richieste nei log dei canary. Questa configurazione si applica solo se ` logRequest` è true. Il valore predefinito è `false`. + `logResponseHeaders`: indica se registrare le intestazioni delle risposte insieme alle risposte nei log dei canary. Questa configurazione si applica solo se ` logResponse` è true. Il valore predefinito è `false`. **Configurazioni delle metriche HTTP** Configurazioni per le metriche relative al conteggio delle richieste di rete con codici di stato HTTP diversi, emesse da Synthetics CloudWatch per questo canarino. + `metric_2xx`: indica se emettere la metrica `2xx` (con la dimensione `CanaryName`) per questo canary. Il valore predefinito è ` true`. + `metric_4xx`: indica se emettere la metrica `4xx` (con la dimensione `CanaryName`) per questo canary. Il valore predefinito è ` true`. + `metric_5xx`: indica se emettere la metrica `5xx` (con la dimensione `CanaryName`) per questo canary. Il valore predefinito è ` true`. + `failedRequestsMetric`: indica se emettere la metrica ` failedRequests` (con la dimensione `CanaryName`) per questo canary. Il valore predefinito è `true`. + `aggregatedFailedRequestsMetric`: indica se emettere la metrica ` failedRequests` (senza la dimensione `CanaryName`) per questo canary. Il valore predefinito è `true`. + `aggregated2xxMetric`: indica se emettere la metrica `2xx` (senza la dimensione `CanaryName`) per questo canary. Il valore predefinito è `true`. + `aggregated4xxMetric`: indica se emettere la metrica `4xx` (senza la dimensione `CanaryName`) per questo canary. Il valore predefinito è `true`. + `aggregated5xxMetric`: indica se emettere la metrica `5xx` (senza la dimensione `CanaryName`) per questo canary. Il valore predefinito è `true`. **Configurazioni delle metriche del canary** Configurazioni per altre metriche emesse da Synthetics. CloudWatch + `failedCanaryMetric`: indica se emettere la metrica `Failed` (con la dimensione `CanaryName`) per questo canary. Il valore predefinito è ` true`. + `aggregatedFailedCanaryMetric`: indica se emettere la metrica ` Failed` (senza la dimensione `CanaryName`) per questo canary. Il valore predefinito è `true`. **Altre configurazioni** + `userAgent`: una stringa da aggiungere all'agente utente. L'agente utente è una stringa inclusa nell'intestazione della richiesta e identifica il browser nei siti Web visitati quando si utilizza il browser headless. CloudWatch Synthetics aggiunge automaticamente. `CloudWatchSynthetics/canary-arn to the user agent` La configurazione specificata viene aggiunta all'agente utente generato. Il valore predefinito dell'agente utente da aggiungere è una stringa vuota (`""`). ### CloudWatch Variabili di ambiente Synthetics Configura il livello e il formato di registrazione utilizzando le variabili di ambiente. **Formato dei log** Il runtime CloudWatch Synthetics Playwright CloudWatch crea registri per ogni corsa canaria. I log sono scritti in formato JSON per facilitare le interrogazioni. Facoltativamente, puoi modificare il formato del log in `TEXT`. + `Environment variable name`: CW\$1SYNTHETICS\$1LOG\$1FORMAT + `Supported values`: JSON, TEXT + `Default`: JSON **Livelli di log** Sebbene l'attivazione della modalità `Debug` aumenti la verbosità, può essere utile per la risoluzione dei problemi. + `Environment variable name`: CW\$1SYNTHETICS\$1LOG\$1LEVEL + `Supported values`: TRACE, DEBUG, INFO, WARN, ERROR, FATAL + `Default`: INFO # Scrittura di uno script canary Node.js utilizzando il runtime Puppeteer **Topics** + [ ## Creare un canarino CloudWatch Synthetics da zero ](#CloudWatch_Synthetics_Canaries_write_from_scratch) + [ ## Creazione di pacchetti dei file canary ](#CloudWatch_Synthetics_Canaries_package) + [ ## Modifica di uno script Puppeteer esistente da utilizzare come canary di Synthetics ](#CloudWatch_Synthetics_Canaries_modify_puppeteer_script) + [ ## Variabili di ambiente ](#CloudWatch_Synthetics_Environment_Variables) + [ ## Integrazione del tuo canarino con altri servizi AWS ](#CloudWatch_Synthetics_Canaries_AWS_integrate) + [ ## Forzare il canary a utilizzare un indirizzo IP statico ](#CloudWatch_Synthetics_Canaries_staticIP) ## Creare un canarino CloudWatch Synthetics da zero Ecco un esempio minimo di script Synthetics canary. Questo script passa come esecuzione riuscita e restituisce una stringa. Per vedere come appare un canary fallito, passare `let fail = false;` a `let fail = true;`. È necessario definire una funzione di punto di ingresso per lo script canary. Per vedere come i file vengono caricati nella posizione Amazon S3 specificata come `ArtifactS3Location` del canary, crea questi file nella cartella `/tmp`. Tutti gli artefatti canary devono essere archiviati nella directory `/tmp`, perché è l'unica scrivibile. Assicurati che il percorso dello screenshot sia impostato su `/tmp` per tutti gli screenshot o gli altri file creati dallo script. Synthetics carica automaticamente i file nella directory ` /tmp` in un bucket S3. ``` /tmp/ ``` Dopo l'esecuzione dello script, le metriche di pass/fail stato e durata vengono pubblicate CloudWatch e i file sottostanti `/tmp` vengono caricati in un bucket S3. ``` const basicCustomEntryPoint = async function () { // Insert your code here // Perform multi-step pass/fail check // Log decisions made and results to /tmp // Be sure to wait for all your code paths to complete // before returning control back to Synthetics. // In that way, your canary will not finish and report success // before your code has finished executing // Throw to fail, return to succeed let fail = false; if (fail) { throw "Failed basicCanary check."; } return "Successfully completed basicCanary checks."; }; exports.handler = async () => { return await basicCustomEntryPoint(); }; ``` Successivamente, espanderemo lo script per utilizzare la registrazione di Synthetics ed effettuare una chiamata utilizzando l'SDK. AWS A scopo dimostrativo, questo script creerà un client Amazon DynamoDB ed effettuerà una chiamata all'API ListTables DynamoDB. Registra la risposta alla richiesta e i registri passano o falliscono in base all'esito positivo della richiesta. ``` const log = require('@aws/synthetics-logger'); const AWS = require('aws-sdk'); // Require any dependencies that your script needs // Bundle additional files and dependencies into a .zip file with folder structure // nodejs/node_modules/additional files and folders const basicCustomEntryPoint = async function () { log.info("Starting DynamoDB:listTables canary."); let dynamodb = new AWS.DynamoDB(); var params = {}; let request = await dynamodb.listTables(params); try { let response = await request.promise(); log.info("listTables response: " + JSON.stringify(response)); } catch (err) { log.error("listTables error: " + JSON.stringify(err), err.stack); throw err; } return "Successfully completed DynamoDB:listTables canary."; }; exports.handler = async () => { return await basicCustomEntryPoint(); }; ``` ## Creazione di pacchetti dei file canary **Per -11.0 e versioni successive syn-nodejs-puppeteer** La vecchia struttura di imballaggio (per syn-nodejs-puppeteer -10.0 e versioni precedenti) è ancora supportata nelle versioni più recenti. Crea uno script utilizzando una delle seguenti opzioni: + File .js (sintassi CommonJS) + File .mjs (sintassi dei moduli ES) Per i moduli ES, utilizza una delle opzioni seguenti: + File .js (sintassi CommonJS) + File .mjs (sintassi dei moduli ES) La struttura del pacchetto è definita di seguito: + File gestore a livello di root (index.js/index.mjs) + File di configurazione facoltativo (synthetics.json) + Dipendenze aggiuntive in node\$1modules (se necessario) Esempio di struttura di impacchettamento: ``` my_function/ ├── index.mjs ├── synthetics.json ├── helper-utils.mjs └── node_modules/ └── dependencies ``` Per impacchettare, segui i seguenti passaggi: 1. Installa le dipendenze (se presenti). ``` npm install ``` 1. Crea un pacchetto .zip. ``` zip -r my_deployment_package.zip ``` **Per syn-nodejs-puppeteer -11.0 e versioni precedenti** Quando si utilizza Amazon S3 è richiesta la seguente struttura: ``` nodejs/ └── node_modules/ └── myCanaryFilename.js ``` **Per aggiungere un supporto opzionale per sottocartelle in syn-nodejs-puppeteer -3.4\$1:** ``` nodejs/ └── node_modules/ └── myFolder/ └── myCanaryFilename.js ``` **Nota** Il percorso del gestore nella configurazione deve corrispondere alla posizione del file. **Nome del gestore** Assicurati di impostare il punto di ingresso dello script del tuo canary (gestore) in modo che ` myCanaryFilename.functionName` corrisponda al nome del file del punto di ingresso dello script. Se utilizzi un runtime precedente a `syn-nodejs-puppeteer-3.4`, `functionName` deve corrispondere a `handler`. Se utilizzi un tempo ` syn-nodejs-puppeteer-3.4` o successivo, puoi scegliere qualsiasi nome di funzione come gestore. Se utilizzi un tempo `syn-nodejs-puppeteer-3.4` o successivo, puoi anche memorizzare il canary in una cartella separata, ad esempio ` nodejs/node_modules/myFolder/my_canary_filename`. Se lo archivi in una cartella separata, definisci il percorso nel punto di ingresso dello script, ad esempio ` myFolder/my_canary_filename.functionName`. ## Modifica di uno script Puppeteer esistente da utilizzare come canary di Synthetics Questa sezione spiega come prendere script Puppeteer e modificarli per essere eseguiti come script canary Synthetics. Per ulteriori informazioni su Puppeteer, consulta [Puppeteer API v1.14.0](https://github.com/puppeteer/puppeteer/blob/v1.14.0/docs/api.md). Inizieremo con questo esempio di script Puppeteer: ``` const puppeteer = require('puppeteer'); (async () => { const browser = await puppeteer.launch(); const page = await browser.newPage(); await page.goto('https://example.com'); await page.screenshot({path: 'example.png'}); await browser.close(); })(); ``` Le fasi di conversione sono le seguenti: + Creare ed esportare una funzione `handler`. Il gestore è la funzione del punto di ingresso per lo script. Se utilizzi un runtime precedente a ` syn-nodejs-puppeteer-3.4`, la funzione del gestore deve essere denominata `handler`. Se utilizzi un tempo `syn-nodejs-puppeteer-3.4` o successivo, la funzione può avere un nome qualsiasi, purché corrisponda a quello utilizzato nello script. Inoltre, se utilizzi un tempo `syn-nodejs-puppeteer-3.4` o successivo, puoi archiviare gli script in qualsiasi cartella e definire quest'ultima nel nome del gestore. ``` const basicPuppeteerExample = async function () {}; exports.handler = async () => { return await basicPuppeteerExample(); }; ``` + Usa la dipendenza `Synthetics`. ``` var synthetics = require('@aws/synthetics-puppeteer'); ``` + Utilizzare la funzione `Synthetics.getPage` per ottenere un oggetto `Page` Puppeteer. ``` const page = await synthetics.getPage(); ``` **L'oggetto page restituito dalla funzione Synthetics.getPage ha page.on e gli eventi sono strumentati per la registrazione.** `request` `response` ` requestfailed` Synthetics imposta anche la generazione di file HAR per le richieste e le risposte nella pagina e aggiunge l'ARN canary alle intestazioni user-agent delle richieste in uscita nella pagina. Lo script è ora pronto per essere eseguito come Canary di Synthetics. Ecco lo script aggiornato: ``` var synthetics = require('@aws/synthetics-puppeteer'); // Synthetics dependency const basicPuppeteerExample = async function () { const page = await synthetics.getPage(); // Get instrumented page from Synthetics await page.goto('https://example.com'); await page.screenshot({path: '/tmp/example.png'}); // Write screenshot to /tmp folder }; exports.handler = async () => { // Exported handler function return await basicPuppeteerExample(); }; ``` ## Variabili di ambiente Quando crei canary puoi utilizzare le variabili di ambiente. Ciò consente di scrivere un singolo script canary e quindi utilizzare tale script con valori diversi per creare rapidamente più canary che hanno un'attività simile. Ad esempio, supponiamo che l'organizzazione disponga di endpoint quali `prod`, ` dev` e `pre-release` per le diverse fasi dello sviluppo del software ed è necessario creare canary per testare ciascuno di questi endpoint. È possibile scrivere un singolo script canary che testi il software e quindi specificare valori diversi per la variabile di ambiente dell'endpoint quando crei ciascuno dei tre canary. Quindi, quando crei un canary, si specificano lo script e i valori da utilizzare per le variabili di ambiente. I nomi delle variabili di ambiente possono contenere lettere, numeri e il carattere di sottolineatura. Devono iniziare con una lettera e avere almeno due caratteri. La dimensione totale delle variabili di ambiente non può superare i 4 KB. Non è possibile specificare alcuna variabile di ambiente riservato Lambda come nomi per le variabili di ambiente. Per ulteriori informazioni sulle variabili di ambiente riservate, consulta [Variabili di ambiente di runtime](https://docs.aws.amazon.com/lambda/latest/dg/configuration-envvars.html#configuration-envvars-runtime). **Importante** Le chiavi e i valori delle variabili di ambiente vengono crittografati quando sono inattivi utilizzando chiavi proprietarie. AWS AWS KMS Tuttavia, le variabili di ambiente non vengono crittografate lato client. Non archiviare informazioni sensibili al loro interno. Lo script di esempio seguente utilizza due variabili di ambiente. Questo script è per un canary che controlla se una pagina Web è disponibile. Utilizza variabili di ambiente per parametrizzare sia l'URL che controlla sia il livello di registro Synthetics CloudWatch che utilizza. La seguente funzione imposta `LogLevel` al valore della variabile di ambiente ` LOG_LEVEL`. ``` synthetics.setLogLevel(process.env.LOG_LEVEL); ``` Questa funzione imposta `URL` al valore della variabile di ambiente `URL`. ``` const URL = process.env.URL; ``` Questo è lo script completo. Quando crei un canary utilizzando questo script, si specificano i valori per le variabili di ambiente `LOG_LEVEL` e `URL`. ``` var synthetics = require('@aws/synthetics-puppeteer'); const log = require('@aws/synthetics-logger'); const pageLoadEnvironmentVariable = async function () { // Setting the log level (0-3) synthetics.setLogLevel(process.env.LOG_LEVEL); // INSERT URL here const URL = process.env.URL; let page = await synthetics.getPage(); //You can customize the wait condition here. For instance, //using 'networkidle2' may be less restrictive. const response = await page.goto(URL, {waitUntil: 'domcontentloaded', timeout: 30000}); if (!response) { throw "Failed to load page!"; } //Wait for page to render. //Increase or decrease wait time based on endpoint being monitored. await page.waitFor(15000); await synthetics.takeScreenshot('loaded', 'loaded'); let pageTitle = await page.title(); log.info('Page title: ' + pageTitle); log.debug('Environment variable:' + process.env.URL); //If the response status code is not a 2xx success code if (response.status() < 200 || response.status() > 299) { throw "Failed to load page!"; } }; exports.handler = async () => { return await pageLoadEnvironmentVariable(); }; ``` ### Passare le variabili di ambiente allo script Per passare le variabili di ambiente allo script quando crei un canary nella console, specifica le chiavi e i valori delle variabili di ambiente nella finestra **Environment variables** (Variabili di ambiente) della console. Per ulteriori informazioni, consulta [Creazione di un Canary](CloudWatch_Synthetics_Canaries_Create.md). Per passare le variabili di ambiente tramite l'API oppure AWS CLI, usa il ` EnvironmentVariables` parametro nella sezione. `RunConfig` Di seguito è riportato un AWS CLI comando di esempio che crea un canarino che utilizza due variabili di ambiente con le chiavi `Environment` e`Region`. ``` aws synthetics create-canary --cli-input-json '{ "Name":"nameofCanary", "ExecutionRoleArn":"roleArn", "ArtifactS3Location":"s3://amzn-s3-demo-bucket-123456789012-us-west-2", "Schedule":{ "Expression":"rate(0 minute)", "DurationInSeconds":604800 }, "Code":{ "S3Bucket": "canarycreation", "S3Key": "cwsyn-mycanaryheartbeat-12345678-d1bd-1234-abcd-123456789012-12345678-6a1f-47c3-b291-123456789012.zip", "Handler":"pageLoadBlueprint.handler" }, "RunConfig": { "TimeoutInSeconds":60, "EnvironmentVariables": { "Environment":"Production", "Region": "us-west-1" } }, "SuccessRetentionPeriodInDays":13, "FailureRetentionPeriodInDays":13, "RuntimeVersion":"syn-nodejs-2.0" }' ``` ## Integrazione del tuo canarino con altri servizi AWS Tutti i canarini possono utilizzare la AWS libreria SDK. Puoi usare questa libreria quando scrivi il tuo canarino per integrare il canarino con altri servizi. AWS Per fare ciò, è necessario aggiungere il seguente codice al tuo canary. Per questi esempi, Gestione dei segreti AWS viene utilizzato come servizio con cui il canarino si sta integrando. + Importa l'SDK. AWS ``` const AWS = require('aws-sdk'); ``` + Crea un client per il AWS servizio con cui ti stai integrando. ``` const secretsManager = new AWS.SecretsManager(); ``` + Utilizzare il client per effettuare chiamate API a tale servizio. ``` var params = { SecretId: secretName }; return await secretsManager.getSecretValue(params).promise(); ``` Il seguente frammento di codice di script canary mostra un esempio di integrazione con Secrets Manager in modo più dettagliato. ``` var synthetics = require('@aws/synthetics-puppeteer'); const log = require('@aws/synthetics-logger'); const AWS = require('aws-sdk'); const secretsManager = new AWS.SecretsManager(); const getSecrets = async (secretName) => { var params = { SecretId: secretName }; return await secretsManager.getSecretValue(params).promise(); } const secretsExample = async function () { let URL = ""; let page = await synthetics.getPage(); log.info(`Navigating to URL: ${URL}`); const response = await page.goto(URL, {waitUntil: 'domcontentloaded', timeout: 30000}); // Fetch secrets let secrets = await getSecrets("secretname") /** * Use secrets to login. * * Assuming secrets are stored in a JSON format like: * { * "username": "", * "password": "" * } **/ let secretsObj = JSON.parse(secrets.SecretString); await synthetics.executeStep('login', async function () { await page.type(">USERNAME-INPUT-SELECTOR<", secretsObj.username); await page.type(">PASSWORD-INPUT-SELECTOR<", secretsObj.password); await Promise.all([ page.waitForNavigation({ timeout: 30000 }), await page.click(">SUBMIT-BUTTON-SELECTOR<") ]); }); // Verify login was successful await synthetics.executeStep('verify', async function () { await page.waitForXPath(">SELECTOR<", { timeout: 30000 }); }); }; exports.handler = async () => { return await secretsExample(); }; ``` ## Forzare il canary a utilizzare un indirizzo IP statico Puoi configurare un canary in modo che utilizzi un indirizzo IP statico. **Per forzare un canary a utilizzare un indirizzo IP statico** 1. Crea un nuovo VPC. Per ulteriori informazioni, vedi [Utilizzo del DNS con VPC](https://docs.aws.amazon.com/vpc/latest/userguide/vpc-dns.html). 1. Crea un nuovo gateway Internet. Per ulteriori informazioni, consulta la pagina relativa all'[Aggiunta di un gateway Internet al VPC](https://docs.aws.amazon.com/vpc/latest/userguide/VPC_Internet_Gateway.html#working-with-igw). 1. Crea una sottorete pubblica all'interno del tuo nuovo VPC. 1. Aggiungi una nuova tabella di routing al VPC. 1. Aggiungi un routing nella nuova tabella di routing, che va da `0.0.0.0/0` al gateway Internet. 1. Associa la nuova tabella di routing alla sottorete pubblica. 1. Crea un indirizzo IP elastico. Per ulteriori informazioni, consulta [Indirizzi IP elastici](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/elastic-ip-addresses-eip.html). 1. Crea un nuovo gateway NAT e assegnalo alla sottorete pubblica e all'indirizzo IP elastico. 1. Per creare una sottorete privata all'interno del VPC. 1. Aggiungere un routing alla tabella di tabella di routing predefinita del VPC, che va da `0.0.0.0/0` al gateway NAT 1. Crea il tuo canary. # Scrivere uno script canary Python Questo script passa come esecuzione riuscita e restituisce una stringa. Per vedere come appare un canary fallito, passare “fail = False” a “fail = True” ``` def basic_custom_script(): # Insert your code here # Perform multi-step pass/fail check # Log decisions made and results to /tmp # Be sure to wait for all your code paths to complete # before returning control back to Synthetics. # In that way, your canary will not finish and report success # before your code has finished executing fail = False if fail: raise Exception("Failed basicCanary check.") return "Successfully completed basicCanary checks." def handler(event, context): return basic_custom_script() ``` ## Impacchettamento dei file canary Python Se disponi di più di un file .py o lo script ha una dipendenza, puoi raggrupparli tutti in un unico file ZIP. Se utilizzi il runtime `syn-python-selenium-1.1`, il file ZIP deve contenere il file del canary principale con estensione py all'interno di una cartella `python`, ad esempio `python/my_canary_filename.py`. Se utilizzi un tempo ` syn-python-selenium-1.1` o successivo, puoi utilizzare una cartella diversa, ad·esempio `python/myFolder/my_canary_filename.py`. Questo file ZIP deve contenere tutte le cartelle e i file necessari, ma gli altri file non devono essere presenti nella cartella `python`. Assicurati di impostare il punto di ingresso dello script del tuo canary in modo che ` my_canary_filename.functionName` corrisponda al nome del file e al nome della funzione del punto di ingresso dello script. Se utilizzi il runtime `syn-python-selenium-1.0`, `functionName` deve corrispondere·a `handler`. Se utilizzi un tempo ` syn-python-selenium-1.1` o successivo, questa limitazione del nome del gestore non si applica e puoi anche archiviare il canary in una cartella separata, ad esempio ` python/myFolder/my_canary_filename.py`. Se lo archivi in una cartella separata, definisci il percorso nel punto di ingresso dello script, ad esempio ` myFolder/my_canary_filename.functionName`. ## Modifica di uno script Selenium esistente da utilizzare come canary di Synthetics Puoi modificare rapidamente uno script esistente per Python e Selenium da utilizzare come canary. [Per ulteriori informazioni su Selenium, vedere www.selenium.dev/.](https://www.selenium.dev/) Per questo esempio, inizieremo con il seguente script Selenium: ``` from selenium import webdriver def basic_selenium_script(): browser = webdriver.Chrome() browser.get('https://example.com') browser.save_screenshot('loaded.png') basic_selenium_script() ``` Le fasi di conversione sono le seguenti. **Per convertire uno script selenio da usare come canary** 1. Modifica l'istruzione `import` per utilizzare Selenium dal modulo ` aws_synthetics`: ``` from aws_synthetics.selenium import synthetics_webdriver as webdriver ``` Il modulo Selenium di `aws_synthetics` assicura che il canarino possa emettere metriche e registri, generare un file HAR e funzionare con altre funzionalità di Synthetics. CloudWatch 1. Crea una funzione del gestore e chiama il tuo metodo Selenium. Il gestore è la funzione del punto di ingresso per lo script. Se utilizzi un tempo `syn-python-selenium-1.0`, la funzione del gestore deve essere denominata `handler`. Se utilizzi un tempo `syn-python-selenium-1.1` o successivo, la funzione può avere un nome qualsiasi, purché corrisponda a quello utilizzato nello script. Inoltre, se utilizzi un tempo `syn-python-selenium-1.1` o successivo, puoi archiviare gli script in qualsiasi cartella e definire quest'ultima nel nome del gestore. ``` def handler(event, context): basic_selenium_script() ``` Lo script è ora aggiornato per essere un canarino CloudWatch Synthetics. Ecco lo script aggiornato: `webdriver`È un'istanza della classe [ SyntheticsWebDriver](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/CloudWatch_Synthetics_Canaries_Library_Python.html#CloudWatch_Synthetics_Library_Python_SyntheticsWebDriver)e il browser restituito da `webdriver.Chrome()` è un'istanza di. [ SyntheticsBrowser](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/CloudWatch_Synthetics_Canaries_Library_Python.html#CloudWatch_Synthetics_Library_Python_SyntheticsBrowser) ``` from aws_synthetics.selenium import synthetics_webdriver as webdriver def basic_selenium_script(): browser = webdriver.Chrome() browser.get('https://example.com') browser.save_screenshot('loaded.png') def handler(event, context): basic_selenium_script() ``` ## Modifica di uno script Puppeteer Synthetics esistente per autenticare certificati non standard Un caso d'uso importante per i canary di Synthetics è il monitoraggio dei propri endpoint. Se vuoi monitorare un endpoint che non è ancora pronto per il traffico esterno, questo tipo di monitoraggio può talvolta implicare l'assenza di un certificato valido firmato da un'autorità di certificazione terza e affidabile. Due possibili soluzioni a questo scenario sono le seguenti: + Per autenticare un certificato client, consulta [Come convalidare l'autenticazione utilizzando Amazon Synthetics CloudWatch ](https://aws.amazon.com/blogs/mt/how-to-validate-authentication-using-amazon-cloudwatch-synthetics-part-2/) — Parte 2. + Per autenticare un certificato autofirmato, consulta [Come convalidare l'autenticazione con certificati autofirmati](https://aws.amazon.com/blogs/mt/how-to-validate-authentication-with-self-signed-certificates-in-amazon-cloudwatch-synthetics/) in Amazon Synthetics CloudWatch Non sei limitato a queste due opzioni quando usi i canarini CloudWatch Synthetics. Puoi estendere queste funzionalità e aggiungere la tua logica aziendale ampliando il codice canary. **Nota** I canary Synthetics in esecuzione su runtime Python hanno nativamente il flag ` --ignore-certificate-errors` abilitato, quindi non dovrebbero avere problemi a raggiungere siti con configurazioni di certificati non standard. # Scrittura di una configurazione JSON per il blueprint Node.js multi Checks Il blueprint Node.js multi check consente di creare canarini che eseguono più controlli di convalida all'interno di un'unica esecuzione. Questo modello è utile quando si desidera testare più endpoint, convalidare diversi aspetti dell'applicazione o eseguire una serie di controlli correlati in sequenza. **Topics** + [ ## Struttura di configurazione principale ](#root-configuration-structure) + [ ## Impostazioni globali ](#global-settings) + [ ## Gestione delle variabili e dei dati ](#variables-data-management) + [ ## Definizioni dei passaggi ](#step-definitions) + [ ## Tipi di controllo ](#check-types) + [ ## Metodi di autenticazione ](#authentication-methods) + [ ## Asserzioni e convalida ](#assertions-validation) + [ ## Estrazione dei dati ](#data-extraction) ## Struttura di configurazione principale La configurazione root definisce la struttura generale del tuo blueprint API avanzato Canary. **Proprietà dello schema** | Proprietà | Tipo | Campo obbligatorio | Description | | --- | --- | --- | --- | | globalSettings | Oggetto | No | Configurazioni predefinite applicate a tutti i passaggi | | variables | Oggetto | No | Valori riutilizzabili tra i passaggi (max 10) | | steps | Oggetto | Sì | Raccolta di fasi di monitoraggio (1-10 fasi) | **Esempio** ``` { "globalSettings": { "stepTimeout": 30000, "userAgent": "CloudWatch-Synthetics-Advanced/1.0" }, "variables": { "baseUrl": "https://api.example.com", "apiVersion": "v1" }, "steps": { "1": { "stepName": "healthCheck", "checkerType": "HTTP", "url": "${baseUrl}/health", "httpMethod": "GET" } } } ``` **Regole di convalida** + Deve contenere almeno un passaggio + Sono consentiti al massimo 10 passaggi + Non sono consentite proprietà aggiuntive oltre a `globalSettings`` variables`, e `steps` ## Impostazioni globali Le impostazioni globali forniscono configurazioni predefinite che si applicano a tutti i passaggi a meno che non vengano sovrascritte a livello di passaggio. **Proprietà** **Proprietà di impostazione globali** | Proprietà | Tipo | Predefinita | Intervallo | Description | | --- | --- | --- | --- | --- | | stepTimeout | intero | 30000 | 5000-300000 | Timeout predefinito per tutti i passaggi (millisecondi) | **Esempio** ``` { "globalSettings": { "stepTimeout": 60000, } } ``` ## Gestione delle variabili e dei dati Le variabili consentono di definire valori riutilizzabili a cui è possibile fare riferimento in tutta la configurazione utilizzando `${variableName}` la sintassi. **Proprietà delle variabili** | Proprietà | Tipo | Description | | --- | --- | --- | | Nomi delle variabili | stringa | Deve corrispondere al modello ^[a-zA-Z][a-zA-Z0-9\$1]\$1\$1 | | Valori variabili | stringa | Qualsiasi valore di stringa | **Limitazioni** + Massimo 10 variabili per configurazione + I nomi delle variabili devono iniziare con una lettera + I nomi delle variabili possono contenere solo lettere, numeri e caratteri di sottolineatura + Lunghezza massima non specificata nello schema **Esempio** ``` { "variables": { "baseUrl": "https://api.example.com", "apiKey": "${AWS_SECRET:my-api-key}", "timeout": "30000", "userEmail": "test@example.com" } } ``` **Utilizzo della configurazione** ``` { "steps": { "1": { "url": "${baseUrl}/users", "timeout": "${timeout}", "headers": { "Authorization": "Bearer ${apiKey}" } } } } ``` ## Definizioni dei passaggi Le fasi definiscono le singole operazioni di monitoraggio. Ogni fase è numerata da 1 a 10 e contiene un tipo specifico di controllo. *Proprietà comuni dei passaggi* | Proprietà | Tipo | Campo obbligatorio | Descrizione | | --- | --- | --- | --- | | stepName | stringa | Sì | Identificatore univoco per la fase | | checkerType | stringa | Sì | Tipo di controllo:HTTP,DNS, SSL TCP | | extractors | array | No | Configurazione dell'estrazione dei dati | *Convalida del nome della fase* + Schema - ^ [a-zA-Z] [a-zA-Z0-9\$1-] \$1\$1 + Lunghezza massima: 64 caratteri + Deve iniziare con una lettera *Numerazione dei passaggi* + I passaggi sono numerati come chiavi di stringa: «1", «2",..., «10" + Modello: ^ ([1-9] \$110) \$1 + È richiesto almeno 1 passaggio + Sono consentiti al massimo 10 passaggi *Esempio* ``` { "steps": { "1": { "stepName": "loginAPI", "checkerType": "HTTP", "url": "https://api.example.com/login", "httpMethod": "POST" }, "2": { "stepName": "dnsCheck", "checkerType": "DNS", "domain": "example.com" } } } ``` ## Tipi di controllo ### Controlli HTTP Monitora gli endpoint web e APIs con una convalida completa delle richieste e delle risposte. **Proprietà richieste** | Proprietà | Tipo | Description | | --- | --- | --- | | url | stringa | URL di destinazione (deve essere un formato URI valido) | | httpMethod | stringa | Metodo HTTP: GETPOST,PUT, PATCH,DELETE,HEAD, OPTIONS | **Proprietà opzionali** | Proprietà | Tipo | Predefinita | Intervallo | Description | | --- | --- | --- | --- | --- | | timeout | intero | 30000 | 5000-300000 | Timeout della richiesta (millisecondi) | | waitTime | intero | 0 | 0-60 | Ritardo prima della richiesta (secondi) | | headers | oggetto | - | - | Intestazioni HTTP personalizzate | | body | stringa | - | - | Corpo della richiesta per POST/PUT le operazioni | | authentication | oggetto | - | - | Configurazione di autenticazione | | assertions | array | - | - | Regole di convalida delle risposte | **Esempio** ``` { "stepName": "createUser", "checkerType": "HTTP", "url": "https://api.example.com/users", "httpMethod": "POST", "timeout": 15000, "headers": { "Content-Type": "application/json", "X-API-Version": "v1" }, "body": "{\"name\":\"John Doe\",\"email\":\"john@example.com\"}", "authentication": { "type": "API_KEY", "apiKey": "${AWS_SECRET:api-credentials}", "headerName": "X-API-Key" }, "assertions": [ { "type": "STATUS_CODE", "operator": "EQUALS", "value": 201 } ] } ``` ### Controlli DNS Convalida la risoluzione DNS e registra le informazioni. **Proprietà richieste** | Proprietà | Tipo | Description | | --- | --- | --- | | domain | stringa | Nome di dominio da interrogare (formato hostname) | **Proprietà opzionali** | Proprietà | Tipo | Predefinita | Description | | --- | --- | --- | --- | | recordType | stringa | «A» | Tipo di record DNS:A,CNAME,MX, TXT NS | | nameserver | stringa | - | Server DNS specifico da interrogare | | timeout | intero | 30000 | Timeout della query (5000-300000 ms) | | port | intero | 53 | Porta server DNS (1-65535) | | protocol | stringa | «UDP» | Protocollo: UDP o TCP | | assertions | array | - | regole di convalida della risposta DNS | **Esempio** ``` { "stepName": "dnsResolution", "checkerType": "DNS", "domain": "example.com", "recordType": "A", "nameserver": "8.8.8.8", "timeout": 10000, "assertions": [ { "type": "RECORD_VALUE", "operator": "CONTAINS", "value": "192.168" } ] } ``` ### Controlli SSL Monitora lo stato e la configurazione dei certificati SSL. **Proprietà richieste** | Proprietà | Tipo | Description | | --- | --- | --- | | hostname | stringa | Nome host di destinazione (formato hostname) | **Proprietà opzionali** | Proprietà | Tipo | Predefinita | Descrizione | | --- | --- | --- | --- | | port | intero | 443 | Porta SSL (1-65535) | | timeout | intero | 30000 | Timeout di connessione (5000-300000 ms) | | sni | booleano | TRUE | Indicazione del nome del server | | verifyHostname | booleano | TRUE | Verifica del nome host | | allowSelfSigned | booleano | FALSE | Accetta certificati autofirmati | | assertions | array | - | Regole di convalida dei certificati | **Esempio** ``` { "stepName": "sslCertCheck", "checkerType": "SSL", "hostname": "secure.example.com", "port": 443, "sni": true, "verifyHostname": true, "assertions": [ { "type": "CERTIFICATE_EXPIRY", "operator": "GREATER_THAN", "value": 30, "unit": "DAYS" } ] } ``` ### Controlli TCP Verifica la connettività della porta TCP e la convalida della risposta. **Proprietà richieste** | Proprietà | Tipo | Description | | --- | --- | --- | | hostname | stringa | Nome host di destinazione (formato hostname) | | port | intero | Porta di destinazione (1-65535) | **Proprietà opzionali** | Proprietà | Tipo | Predefinita | Descrizione | | --- | --- | --- | --- | | timeout | intero | 30000 | Timeout complessivo (5000-300000ms) | | connectionTimeout | intero | 3000 | Timeout di connessione (5000-300000ms) | | readTimeout | intero | 2000 | Timeout di lettura dei dati (5000-300000ms) | | sendData | stringa | - | Dati da inviare dopo la connessione | | expectedResponse | stringa | - | Dati di risposta previsti | | encoding | stringa | «UTF-8" | Codifica dei dati:,, UTF-8 ASCII HEX | | assertions | array | - | Convalida della connessione e della risposta | **Esempio** ``` { "stepName": "databaseConnection", "checkerType": "TCP", "hostname": "db.example.com", "port": 3306, "connectionTimeout": 5000, "sendData": "SELECT 1", "expectedResponse": "1", "assertions": [ { "type": "CONNECTION_SUCCESSFUL", "value": true } ] } ``` ## Metodi di autenticazione **Nessuna autenticazione** ``` { "type": "NONE" } ``` **Autenticazione Base** | Proprietà | Tipo | Campo obbligatorio | Descrizione | | --- | --- | --- | --- | | type | stringa | Sì | Deve essere "BASIC" | | username | stringa | Sì | Nome utente per l'autenticazione | | password | stringa | Sì | Password per l'autenticazione | **Esempio** ``` { "type": "BASIC", "username": "admin", "password": "${AWS_SECRET:basic-auth:password}" } ``` **Autenticazione con chiave API** | Proprietà | Tipo | Obbligatorio | Predefinita | Description | | --- | --- | --- | --- | --- | | type | stringa | Sì | - | Deve essere "API\$1KEY" | | apiKey | stringa | Sì | - | Valore della chiave API | | headerName | stringa | No | «Chiave X-API» | Nome dell'intestazione per la chiave API | **Esempio** ``` { "type": "API_KEY", "apiKey": "${AWS_SECRET:api-credentials}", "headerName": "Authorization" } ``` **OAuth credenziali del client** | Proprietà | Tipo | Obbligatorio | Predefinita | Description | | --- | --- | --- | --- | --- | | type | stringa | Sì | - | Deve essere "OAUTH\$1CLIENT\$1CREDENTIALS" | | tokenUrl | stringa | Sì | - | OAuth URL dell'endpoint del token | | clientId | stringa | Sì | - | OAuth ID cliente | | clientSecret | stringa | Sì | - | OAuth segreto del cliente | | scope | stringa | No | - | OAuth ambito | | audience | stringa | No | - | OAuth pubblico | | resource | stringa | No | - | OAuth risorsa | | tokenApiAuth | array | No | - | Metodi di autenticazione dell'API token:BASIC\$1AUTH\$1HEADER, REQUEST\$1BODY | | tokenCacheTtl | numero intero | No | 3600 | Token cache TTL (minimo 60 secondi) | **Esempio** ``` { "type": "OAUTH_CLIENT_CREDENTIALS", "tokenUrl": "https://auth.example.com/oauth/token", "clientId": "${AWS_SECRET:oauth-creds:client_id}", "clientSecret": "${AWS_SECRET:oauth-creds:client_secret}", "scope": "read write", "tokenCacheTtl": 7200 } ``` **AWS Firma (versione 4)** | Proprietà | Tipo | Campo obbligatorio | Descrizione | | --- | --- | --- | --- | | type | stringa | Sì | Deve essere "SIGV4" | | service | stringa | Sì | Nome del AWS servizio (ad esempio, «execute-api») | | region | stringa | Sì | AWS regione | | roleArn | stringa | Sì | ARN del ruolo IAM per la firma | **Esempio** ``` { "type": "SIGV4", "service": "execute-api", "region": "us-east-1", "roleArn": "arn:aws:iam::123456789012:role/SyntheticsRole" } ``` ## Asserzioni e convalida ### Asserzioni HTTP **asserzioni del codice di stato** | Proprietà | Tipo | Campo obbligatorio | Descrizione | | --- | --- | --- | --- | | type | stringa | Sì | Deve essere "STATUS\$1CODE" | | operator | stringa | Sì | EQUALS, NOT\$1EQUALS, GREATER\$1THAN, LESS\$1THAN, IN\$1RANGE | | value | intero | Condizionale | Codice di stato HTTP (100-599) | | rangeMin | intero | Condizionale | Valore minimo dell'intervallo (per) IN\$1RANGE | | rangeMax | intero | Condizionale | Valore dell'intervallo massimo (perIN\$1RANGE) | ``` { "type": "STATUS_CODE", "operator": "EQUALS", "value": 200 } ``` **Asserzioni sul tempo di risposta** | Proprietà | Tipo | Obbligatorio | Predefinita | Description | | --- | --- | --- | --- | --- | | type | stringa | Sì | - | Deve essere "RESPONSE\$1TIME" | | operator | stringa | Sì | - | LESS\$1THAN, GREATER\$1THAN, EQUALS | | value | numero | Sì | - | Valore temporale (minimo 0) | | unit | stringa | No | «MILLISECONDI» | Deve essere "MILLISECONDS" | ``` { "type": "RESPONSE_TIME", "operator": "LESS_THAN", "value": 500, "unit": "MILLISECONDS" } ``` **Asserzioni della testa** | Proprietà | Tipo | Campo obbligatorio | Descrizione | | --- | --- | --- | --- | | type | stringa | Sì | Deve essere "HEADER" | | headerName | stringa | Sì | Nome dell'intestazione da convalidare | | operator | stringa | Sì | EQUALS, NOT\$1EQUALS, CONTAINS, NOT\$1CONTAINS, REGEX\$1MATCH, EXIST | | value | stringa/booleano | Condizionale | Valore previsto (booleano per operatore) EXIST | ``` { "type": "HEADER", "headerName": "Content-Type", "operator": "CONTAINS", "value": "application/json" } ``` **Asserzioni corporee** | Proprietà | Tipo | Obbligatorio | Predefinita | Description | | --- | --- | --- | --- | --- | | type | stringa | Sì | - | Deve essere "BODY" | | target | stringa | No | «JSON» | JSON o TEXT | | path | stringa | Condizionale | - | JSONPath (richiesto per il target JSON) | | operator | stringa | Sì | - | CONTAINS, NOT\$1CONTAINS, EQUALS, NOT\$1EQUALS, EXISTS | | value | stringa/booleano | Sì | - | Valore previsto (booleano per operatore) EXISTS | ``` { "type": "BODY", "target": "JSON", "path": "$.users[0].name", "operator": "EQUALS", "value": "John Doe" } ``` ### Asserzioni DNS **Registra asserzioni di valore** | Proprietà | Tipo | Richiesto | Intervallo | Description | | --- | --- | --- | --- | --- | | type | stringa | Sì | - | Deve essere "RECORD\$1VALUE" | | operator | stringa | Sì | - | EQUALS, NOT\$1EQUALS, CONTAINS, NOT\$1CONTAINS, REGEX\$1MATCH | | value | stringa | Sì | - | Valore record previsto | **Registra le asserzioni relative al conteggio** | Proprietà | Tipo | Richiesto | Intervallo | Description | | --- | --- | --- | --- | --- | | type | stringa | Sì | - | Deve essere "RECORD\$1COUNT" | | operator | stringa | Sì | - | EQUALS, GREATER\$1THAN, LESS\$1THAN | | value | intero | Sì | ≥ 0 | Conteggio previsto (minimo 0) | **Affermazioni autorevoli** | Proprietà | Tipo | Richiesto | Intervallo | Description | | --- | --- | --- | --- | --- | | type | stringa | Sì | - | Deve essere "AUTHORITATIVE" | | value | booleano | Sì | - | Status autorevole previsto | **Asserzioni TTL** | Proprietà | Tipo | Richiesto | Intervallo | Description | | --- | --- | --- | --- | --- | | type | stringa | Sì | - | Deve essere "TTL" | | operator | stringa | Sì | - | EQUALS, GREATER\$1THAN, LESS\$1THAN | | value | intero | Sì | ≥ 0 | TTL previsto (minimo 0) | ### Asserzioni SSL **Affermazioni sulla scadenza dei certificati** | Proprietà | Tipo | Obbligatorio | Predefinita | Description | | --- | --- | --- | --- | --- | | type | stringa | Sì | - | Deve essere "CERTIFICATE\$1EXPIRY" | | operator | stringa | Sì | - | GREATER\$1THAN, LESS\$1THAN | | value | intero | Sì | - | Valore temporale (minimo 0) | | unit | stringa | No | «GIORNI» | DAYS, HOURS | **Affermazioni relative all'oggetto del certificato** | Proprietà | Tipo | Obbligatorio | Predefinita | Description | | --- | --- | --- | --- | --- | | type | stringa | Sì | - | Deve essere "CERTIFICATE\$1SUBJECT" | | field | stringa | Sì | - | Campo oggetto:CN,,O,OU,C, ST L | | operator | stringa | Sì | - | CONTAINS, EQUALS, REGEX\$1MATCH | | value | stringa | Sì | - | Valore del campo previsto | **Dichiarazioni dell'emittente del certificato** | Proprietà | Tipo | Obbligatorio | Predefinita | Description | | --- | --- | --- | --- | --- | | type | stringa | Sì | - | Deve essere "CERTIFICATE\$1ISSUER" | | field | stringa | Sì | - | Campo emittente:, CN O | | operator | stringa | Sì | - | CONTAINS, EQUALS | | value | stringa | Sì | - | Valore del campo previsto | ### asserzioni TCP **Asserzioni di successo della connessione** | Proprietà | Tipo | Obbligatorio | Predefinita | Description | | --- | --- | --- | --- | --- | | type | stringa | Sì | - | Deve essere "CONNECTION\$1SUCCESSFUL" | | value | booleano | Sì | - | Stato della connessione previsto | **Asserzioni di dati di risposta** | Proprietà | Tipo | Obbligatorio | Predefinita | Description | | --- | --- | --- | --- | --- | | type | stringa | Sì | - | Deve essere "RESPONSE\$1DATA" | | operator | stringa | Sì | - | CONTAINS, EQUALS, NOT\$1CONTAINS, REGEX\$1MATCH, STARTS\$1WITH, ENDS\$1WITH | | value | stringa | Sì | - | Dati di risposta previsti | | encoding | stringa | No | «UTF-8" | UTF-8, ASCII, HEX | ## Estrazione dei dati Extractors consente di acquisire dati dalle risposte per utilizzarli nei passaggi successivi o per scopi di reporting. **Proprietà di estrazione** | Proprietà | Tipo | Obbligatorio | Predefinita | Description | | --- | --- | --- | --- | --- | | name | stringa | Sì | - | Nome variabile per i dati estratti | | type | stringa | Sì | - | Tipo di estrazione: BODY | | path | stringa | No | - | JSONPath per l'estrazione del corpo | | regex | stringa | No | - | modello di espressione regolare | | regexGroup | numero intero | No | 0 | Gruppo di acquisizione Regex (minimo 0) | **Convalida del nome di estrazione** + Modello: `^[a-zA-Z][a-zA-Z0-9_]*$` + Deve iniziare con una lettera + Può contenere lettere, numeri e caratteri di sottolineatura **Limitazione**: la sostituzione non si applica ai campi dello schema che hanno valori ENUM specifici **Tipi di estrazione** ``` { "name": "userId", "type": "BODY", "path": "$.user.id" } ``` ``` { "stepName": "loginAndExtract", "checkerType": "HTTP", "url": "https://api.example.com/login", "httpMethod": "POST", "body": "{\"username\":\"test\",\"password\":\"pass\"}", "extractors": [ { "name": "textVariable", "type": "BODY", "path": "$.myvalue" } ] }, { "stepName": "substituteVariable", "checkerType": "HTTP", "url": "https://api.example.com/get/${textVariable}", "httpMethod": "GET", "assertions": [ { "type": "BODY", "target": "JSON", "path": "$.users[0].name", "operator": "EQUALS", "value": "${textVariable}" } ] } ```