Terjemahan disediakan oleh mesin penerjemah. Jika konten terjemahan yang diberikan bertentangan dengan versi bahasa Inggris aslinya, utamakan versi bahasa Inggris.

Menulis skrip kenari menggunakan runtime Java

Struktur proyek Java untuk kenari

Untuk membuat kenari di Java, Anda perlu menulis kode Anda, mengkompilasinya, dan menyebarkan artefak yang dikompilasi ke Synthetics. Anda dapat menginisialisasi proyek Java Lambda dengan berbagai cara. Misalnya, Anda dapat menggunakan pengaturan proyek Java standar di IDE pilihan Anda, seperti IntelliJ IDEA atau Visual Studio Code. Atau, Anda dapat membuat struktur file yang diperlukan secara manual.

Proyek Synthetics Java berisi struktur umum berikut:

/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

Anda dapat menggunakan Maven atau Gradle untuk membangun proyek dan mengelola dependensi.

Dalam struktur di atas, ExampleCanary kelas adalah titik masuk atau handler untuk kenari.

Contoh kelas kenari Java

Contoh ini adalah untuk burung kenari untuk membuat permintaan get ke URL yang disimpan dalam variabel lingkungan TESTING_URL Lambda. Kenari tidak menggunakan salah satu metode yang disediakan oleh 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);
      }
  }
} 

Sangat disarankan untuk memodulasi kenari Anda menggunakan fungsi perpustakaan yang disediakan Synthetics. executeStep Canary melakukan get panggilan ke dua URL terpisah yang diperoleh dari variabel lingkungan URL1 dan 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();
  }
}

Kemasan proyek untuk kenari

Synthetics menerima kode untuk kenari java dalam format zip. Zip terdiri dari file kelas untuk kode kenari, jar untuk dependensi pihak ketiga dan file konfigurasi Synthetics.

Zip Synthetics Java berisi struktur umum berikut.

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

Untuk membangun zip ini dari struktur proyek di atas, Anda dapat menggunakan gradle (build.gradle) atau maven (pom.xml). Inilah contohnya.

Untuk informasi tentang dependensi waktu kompilasi atau antarmuka untuk pustaka Synthetics, lihat README di bawah aws-cloudwatch-synthetics-sdk-java. https://github.com/aws/aws-cloudwatch-synthetics-sdk-java/tree/main

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

Nama handler

Nama handler adalah titik masuk untuk kenari. Untuk runtime Java, handler dalam format berikut.

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

CloudWatch Konfigurasi sintetis

Anda dapat mengonfigurasi perilaku runtime Synthetics Java dengan menyediakan file konfigurasi JSON opsional bernamasynthetics.json. File ini harus dikemas dalam direktori root paket zip. Meskipun file konfigurasi bersifat opsional, jika Anda tidak menyediakan file konfigurasi, atau kunci konfigurasi hilang, CloudWatch gunakan default.

Berikut ini adalah nilai konfigurasi yang didukung, dan defaultnya.

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

Konfigurasi langkah

Konfigurasi logging

Berlaku untuk log yang dihasilkan oleh CloudWatch Synthetics. Mengontrol verbositas log permintaan dan respons.

Konfigurasi metrik HTTP

Konfigurasi untuk metrik yang terkait dengan jumlah permintaan jaringan dengan kode status HTTP yang berbeda, dipancarkan oleh CloudWatch Synthetics untuk burung kenari ini.

Konfigurasi metrik Canary

Konfigurasi untuk metrik lain yang dipancarkan oleh CloudWatch Synthetics.

CloudWatch Variabel lingkungan sintetis

Anda dapat mengonfigurasi level dan format logging dengan menggunakan variabel lingkungan.

Format log

Runtime CloudWatch Synthetics Java membuat CloudWatch log untuk setiap operasi canary. Log ditulis dalam format JSON untuk memudahkan kueri. Secara opsional, Anda dapat mengubah format log menjadi TEXT.

Tingkat log

Terlepas dari variabel lingkungan di atas, ada variabel lingkungan default yang ditambahkan untuk runtime Java, variabel AWS_LAMBDA-EXEC_WRAPPER lingkungan ke fungsi Anda, dan mengatur nilainya ke/opt/synthetics-otel-instrument. Variabel lingkungan ini mengubah perilaku startup fungsi Anda untuk telemetri. Jika variabel lingkungan ini sudah ada, pastikan bahwa variabel tersebut disetel ke nilai yang diperlukan.