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à. # 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\_URL* 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\_2xx — Specifica se emettere la metrica 2xx* *(con la dimensione) per questo canarino.* CanaryName Il valore predefinito è *true*. + *metric\_4xx — Speciifica se emettere la metrica 4xx* *(con la dimensione) per questo canarino.* CanaryName Il valore predefinito è *true*. + *metric\_5xx — 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\_SYNTHETICS\_LOG\_FORMAT + *Valori supportati*: JSON, TEXT + *Impostazione predefinita*: JSON **Livelli di log** + *Nome della variabile di ambiente*: CW\_SYNTHETICS\_LOG\_LEVEL + *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.