Les traductions sont fournies par des outils de traduction automatique. En cas de conflit entre le contenu d'une traduction et celui de la version originale en anglais, la version anglaise prévaudra.

É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 canari fait get appel à deux variables d' URL2 environnement URL1 et d' URLs approvisionnement distinctes.

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 interdépendances ou les interfaces liées au temps de compilation pour la bibliothèque Synthetics, consultez le fichier README sous -java. aws-cloudwatch-synthetics-sdk

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

CloudWatch Configurations 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, il CloudWatch utilise les valeurs par défaut si vous ne fournissez pas de fichier de configuration ou s'il manque une clé de configuration.

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 d'enregistrement

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 pour les métriques liées au nombre de requêtes réseau avec différents codes d'état HTTP, émises par CloudWatch Synthetics pour ce canari.

Configurations des métriques du script Canary

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

CloudWatch Variables d'environnement Synthetics

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

Format du journal

Le moteur d'exécution CloudWatch Synthetics Java CloudWatch crée des journaux pour chaque exécution de 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.