Die vorliegende Übersetzung wurde maschinell erstellt. Im Falle eines Konflikts oder eines Widerspruchs zwischen dieser übersetzten Fassung und der englischen Fassung (einschließlich infolge von Verzögerungen bei der Übersetzung) ist die englische Fassung maßgeblich.

Schreiben eines Canary-Skript mit der Java-Laufzeit

Java-Projektstruktur für ein Canary

Zur Erstellung eines Canary in Java müssen Sie Ihren Code schreiben, kompilieren und die kompilierten Artefakte in Synthetics bereitstellen. Sie können ein Java-Lambda-Projekt auf verschiedene Arten initialisieren. Sie können beispielsweise ein Standard-Java-Projekt-Setup in Ihrer bevorzugten IDE wie IntelliJ IDEA oder Visual Studio Code verwenden. Alternativ können Sie die erforderliche Dateistruktur manuell erstellen.

Ein Synthetics-Java-Projekt hat die folgende allgemeine Struktur:

/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

Sie können entweder Maven oder Gradle verwenden, um Ihr Projekt zu erstellen und Abhängigkeiten zu verwalten.

In der obigen Struktur ist die ExampleCanary-Klasse der Einstiegspunkt oder Handler für den Canary.

Beispiel für eine Canary-Java-Klasse

In diesem Beispiel stellt ein Canary eine Get-Anforderung an eine URL, die in der Lambda-Umgebungsvariablen TESTING_URL gespeichert ist. Der Canary verwendet keine der von Synthetics-Laufzeit bereitgestellten Methoden.

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);
      }
  }
} 

Es wird dringend empfohlen, Ihre Canarys mithilfe der von Synthetics bereitgestellten Bibliotheksfunktion executeStep zu modularisieren. Der Canary get ruft zwei separate Variablen auf, URLs die von URL1 und von der URL2 Umgebung stammen.

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();
  }
}

Bündeln des Projekt für einen Canary

Synthetics akzeptiert Code für einen Java-Canary im Zip-Format. Die ZIP-Datei besteht aus den Klassendateien für den Canary-Code, den Jars für alle Abhängigkeiten von Drittanbietern und der Synthetics-Konfigurationsdatei.

Ein Synthetics-Java-Zip enthält die folgende allgemeine Struktur.

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

Um diese Zip-Datei aus der obigen Projektstruktur zu erstellen, können Sie Gradle (build.gradle) oder Maven (pom.xml) verwenden. Ein Beispiel.

Informationen zu Abhängigkeiten oder Schnittstellen zur Kompilierzeit für die Synthetics-Bibliothek finden Sie in der README-Datei unter 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"
}

Handlername

Der Handler-Name ist der Einstiegspunkt für den Canary. Für die Java-Laufzeit hat der Handler das folgende Format.

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

CloudWatch Synthetics Konfigurationen

Sie können das Verhalten der Synthetics-Java-Laufzeit konfigurieren, indem Sie eine optionale JSON-Konfigurationsdatei mit dem Namen synthetics.json bereitstellen. Diese Datei sollte im Stammverzeichnis der Paket-Zip-Datei gebündelt werden. Eine Konfigurationsdatei ist zwar optional, CloudWatch verwendet jedoch die Standardeinstellungen, wenn Sie keine Konfigurationsdatei angeben oder ein Konfigurationsschlüssel fehlt.

Im Folgenden sind die unterstützten Konfigurationswerte und ihre Standardwerte aufgeführt.

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

Schritt-Konfigurationen

Protokollierungskonfigurationen

Gilt für von CloudWatch Synthetics generierte Protokolle. Steuert die Ausführlichkeit von Anforderungs- und Antwortprotokollen.

Konfigurationen der HTTP-Metrik

Konfigurationen für Metriken, die sich auf die Anzahl der Netzwerkanfragen mit unterschiedlichen HTTP-Statuscodes beziehen, die von CloudWatch Synthetics für diesen Kanarienvogel ausgegeben wurden.

Konfigurationen der Canary-Metrik

Konfigurationen für andere von CloudWatch Synthetics ausgegebene Metriken.

CloudWatch Synthetics-Umgebungsvariablen

Sie können die Protokollierungsebene und das Format mithilfe von Umgebungsvariablen konfigurieren.

Protokollformat

Die CloudWatch Synthetics Java Runtime erstellt CloudWatch Logs für jeden Canary-Run. Die Protokolle werden zur einfacheren Abfrage im JSON-Format geschrieben. Optional können Sie das Protokollformat zu TEXT ändern.

Protokollstufen

Abgesehen von den oben genannten Umgebungsvariablen wurde eine Standardumgebungsvariable für die Java-Laufzeit hinzugefügt, eine AWS_LAMBDA-EXEC_WRAPPER-Umgebungsvariable zu Ihrer Funktion, und deren Wert auf /opt/synthetics-otel-instrument festgelegt. Diese Umgebungsvariable ändert das Startverhalten Ihrer Funktion für Telemetrie. Wenn diese Umgebungsvariable bereits existiert, stellen Sie sicher, dass sie auf den erforderlichen Wert festgelegt ist.