Écriture d’un script Canary en utilisant l’exécution Java

Structure d’un projet Java pour un script Canary

Pour créer un script Canary en Java, vous devez écrire votre code, le compiler et déployer les artefacts compilés dans Synthetics. Vous pouvez initialiser un projet Java Lambda de différentes manières. Par exemple, vous pouvez utiliser une configuration de projet Java standard dans votre IDE préféré, comme IntelliJ IDEA ou Visual Studio Code. Vous pouvez également créer manuellement la structure de fichiers requise.

Un projet Synthetics Java contient la structure générale suivante :

/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

Vous pouvez utiliser Maven ou Gradle pour créer votre projet et gérer les dépendances.

Dans la structure ci-dessus, la classe ExampleCanary est le point d’entrée ou le gestionnaire du script Canary.

Exemple de classe Java pour un script Canary

Cet exemple illustre un script Canary effectuant une requête GET vers une URL stockée dans la variable d’environnement Lambda TESTING_URL. Ce script Canary n’utilise pas les méthodes fournies par l’exécution 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);
      }
  }
} 

Il est fortement recommandé de modulariser vos scripts Canary à l’aide de la fonction de bibliothèque executeStep fournie par Synthetics. Le script Canary exécute des appels get vers deux URL distinctes obtenues à partir des variables d’environnement URL1 et 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();
  }
}

Empaquetage du projet pour un script Canary

Synthetics accepte le code d’un Canary Java au format zip. Le fichier zip contient les fichiers de classes du code du script Canary, les fichiers JAR des dépendances tierces et le fichier de configuration  Synthetics.

Un fichier zip Synthetics Java présente la structure générale suivante.

example-canary
    └ lib
    |  └ //third party dependency jars
       └ java-canary.jar
    └ synthetics.json

Pour créer ce fichier zip à partir de la structure de projet ci-dessus, vous pouvez utiliser Gradle (build.gradle) ou Maven (pom.xml). Voici un exemple.

Pour plus d’informations sur les dépendances de compilation ou les interfaces de la bibliothèque Synthetics, consultez le fichier README dans 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"
}

Nom du gestionnaire

Le nom du gestionnaire correspond au point d’entrée du script Canary. Pour l’exécution Java, le gestionnaire est au format suivant.

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

Configurations CloudWatch Synthetics

Vous pouvez configurer le comportement de l’exécution Java Synthetics à l’aide d’un fichier de configuration JSON facultatif nommé synthetics.json. Ce fichier doit être empaqueté dans le répertoire racine du package zip. Bien qu’un fichier de configuration soit facultatif, si vous ne fournissez pas de fichier de configuration ou si une clé de configuration est manquante, CloudWatch utilise les valeurs par défaut.

Les valeurs de configuration prises en charge et leurs valeurs par défaut sont les suivantes.

{
    "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
    }
}

Étapes de configuration

Configurations de journalisation

S’applique aux journaux générés par CloudWatch Synthetics. Contrôle la verbosité des journaux de requêtes et de réponses.

Configurations des métriques HTTP

Configurations des métriques liées au nombre de requêtes réseau renvoyant différents codes d’état HTTP, émises par CloudWatch Synthetics pour ce script Canary.

Configurations des métriques du script Canary

Configurations pour les autres métriques émises par CloudWatch Synthetics.

Variables d’environnement CloudWatch Synthetics

Vous pouvez configurer le niveau de journalisation et le format des journaux à l’aide de variables d’environnement.

Format des journaux

L’exécution Java de CloudWatch Synthetics crée des journaux CloudWatch pour chaque exécution de script Canary. Les journaux sont écrits au format JSON pour faciliter les requêtes. Vous pouvez éventuellement modifier le format du journal en TEXT.

Niveaux de journalisation

Outre les variables d’environnement ci-dessus, une variable d’environnement par défaut est ajoutée à l’exécution Java. Ajoutez la variable d’environnement AWS_LAMBDA-EXEC_WRAPPER à votre fonction et définissez sa valeur sur /opt/synthetics-otel-instrument. Cette variable modifie le comportement de démarrage de la fonction pour la télémétrie. Si cette variable existe déjà, assurez-vous qu’elle est configurée avec la valeur requise.