本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

使用 Java 執行時間撰寫 Canary 指令碼

Canary 的 Java 專案結構

若要在 Java 中建立 Canary，您需要撰寫程式碼、編譯程式碼，並將編譯的成品部署到 Synthetics。您可以透過各種方式初始化 Java Lambda 專案。例如，您可以在偏好的 IDE 中使用標準 Java 專案設定，例如 IntelliJ IDEA 或 Visual Studio Code。或者，您可以手動建立所需的檔案結構。

Synthetics Java 專案包含下列一般結構：

/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

您可以使用 Maven 或 Gradle 來建置專案並管理相依性。

在上述結構中， ExampleCanary類別是 Canary 的進入點或處理常式。

Java Canary 類別範例

此範例可讓 Canary 對存放在 TESTING_URL Lambda 環境變數中的 URL 提出取得請求。Canary 不使用 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);
      }
  }
} 

強烈建議您使用 Synthetics 提供的程式庫函數 來模組化您的 CanaryexecuteStep。Canary get會呼叫從 URLs取得的兩個個別 URL。 URL1 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();
  }
}

封裝 Canary 的專案

Synthetics 接受 zip 格式的 Java Canary 程式碼。zip 包含 Canary 程式碼的類別檔案、任何第三方相依性的 jar，以及 Synthetics 組態檔案。

Synthetics Java zip 包含下列一般結構。

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

若要從上述專案結構建置此 zip，您可以使用 gradle (build.gradle) 或 maven (pom.xml)。請見此處範例。

如需有關編譯 Synthetics 程式庫的時間相依性或界面的資訊，請參閱 aws-cloudwatch-synthetics-sdk-java 下的 README。

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

處理常式名稱

處理常式名稱是 Canary 的進入點。對於 Java 執行期，處理常式的格式如下。

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

CloudWatch Synthetics 組態

您可以提供名為 的選用 JSON 組態檔案，來設定 Synthetics Java 執行時間的行為synthetics.json。此檔案應封裝在套件 zip 的根目錄中。雖然組態檔案是選用的，但如果您未提供組態檔案，或組態金鑰遺失，CloudWatch 會使用預設值。

以下是支援的組態值及其預設值。

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

步驟組態

記錄組態

適用於 CloudWatch Synthetics 產生的日誌。控制請求和回應日誌的詳細資訊。

HTTP 指標組態

CloudWatch Synthetics 針對此 Canary 發出的具有不同 HTTP 狀態碼之網路請求計數相關的指標組態。

Canary 指標組態

CloudWatch Synthetics 發出之其他指標的組態。

CloudWatch Synthetics 環境變數

您可以使用環境變數來設定記錄層級和格式。

日誌格式

CloudWatch Synthetics Java 執行期會為每個 Canary 執行建立 CloudWatch 日誌。日誌是以 JSON 格式撰寫，方便查詢。或者，您可以將日誌格式變更為 TEXT。

日誌層級

除了上述環境變數之外，還會為 Java 執行時間新增預設環境變數、將AWS_LAMBDA-EXEC_WRAPPER環境變數新增至函數，並將其值設定為 /opt/synthetics-otel-instrument。此環境變數會修改函數的啟動行為以進行遙測。如果此環境變數已存在，請確定它已設定為所需的值。