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.

Écrire un script Canary à l'aide de l'environnement d'exécution Java

Structure de projet Java pour un canari

Pour créer un canari 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é, tel que IntelliJ IDEA ou Visual Studio Code. Vous pouvez également créer manuellement la structure de fichier 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 ExampleCanary classe est le point d'entrée ou le gestionnaire du canari.

Exemple de classe Java Canary

Dans cet exemple, un canari envoie une requête get à une URL stockée dans la variable d'environnement Lambda TESTING_URL. The Canary n'utilise aucune des méthodes fournies par Synthetics Runtime.

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 canaris à l'aide de la fonction de bibliothèque fournie par Synthetics. executeStep 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();
  }
}

Emballage du projet pour un canari

Synthetics accepte le code d'un canari Java au format zip. Le zip contient les fichiers de classe pour le code Canary, les fichiers JAR pour toutes les dépendances tierces et le fichier de configuration Synthetics.

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

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

Pour créer ce 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 est le point d'entrée du canari. Pour l'environnement d'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 du moteur d'exécution Synthetics Java en fournissant 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
    }
}

Configurations des étapes

Configurations d'enregistrement

S'applique aux journaux générés par CloudWatch Synthetics. Contrôle la verbosité des journaux de demandes et de réponses.

Configurations 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 métriques Canary

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

CloudWatch Variables d'environnement Synthetics

Vous pouvez configurer le niveau et le format de journalisation à 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 TEXTE.

Niveaux de journalisation

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