Scrittura di uno script canary utilizzando il runtime Java

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 canary effettui una richiesta get a un URL archiviato nella variabile di ambiente Lambda TESTING_URL. 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 canary effettua chiamate get a due URL separati ottenuti dalle variabili di ambiente URL1 e URL2.

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 di compilazione o sulle interfacce della libreria Synthetics, consulta il file README su aws-cloudwatch-synthetics-sdk-java.

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.

<<full qualified name for canary class>>::<<name of the method to start the execution from>>
// for above code: canarypackage.ExampleCanary::canaryCode

Configurazioni di CloudWatch 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 fornisci un file di configurazione (o manca una chiave di configurazione), CloudWatch utilizza i valori predefiniti.

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

Configurazioni di registrazione

Si applica ai log generati da CloudWatch Synthetics. Controlla la verbosità dei log di richieste e risposte.

Configurazioni delle metriche HTTP

Configurazioni per metriche relative al conteggio delle richieste di rete con codici di stato HTTP diversi, emesse da CloudWatch Synthetics per questo canary.

Configurazioni delle metriche del canary

Configurazioni per altre metriche emesse da CloudWatch Synthetics.

Variabili di ambiente di CloudWatch Synthetics

È possibile configurare il livello e il formato di registrazione utilizzando le variabili di ambiente.

Formato dei log

Il runtime Java di CloudWatch Synthetics crea log CloudWatch per ogni esecuzione canary. I log sono scritti in formato JSON per facilitare le interrogazioni. Facoltativamente, è possibile modificare il formato del log in TEXT.

Livelli di log

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.