使用 Java 运行时编写金丝雀脚本

金丝雀的 Java 项目结构

若要使用 Java 创建金丝雀，您需要编写和编译代码，并将编译后的构件部署到 Synthetics。您可以通过多种方式初始化 Java Lambda 项目。例如，您可以在 IntelliJ IDEA 或 Visual Studio Code 等首选 IDE 中使用标准的 Java 项目设置。或者，您也可以手动创建所需的文件结构。

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 类是金丝雀的入口点或处理程序。

Java 金丝雀类示例

此示例是让金丝雀向存储在 TESTING_URL Lambda 环境变量中的 URL 发出 GET 请求。该金丝雀不使用 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 提供的库函数 executeStep 对该金丝雀进行模块化处理。该金丝雀会对从 URL1 和 URL2 环境变量获取的两个单独的 URL 进行 get 调用。

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

为金丝雀打包项目

Synthetics 接受以 zip 格式打包的 Java 金丝雀代码。zip 文件包含金丝雀代码的类文件、任何第三方依赖项的 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"
}

处理程序名称

处理程序名称是金丝雀的入口点。对于 Java 运行时，处理程序采用以下格式。

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

CloudWatch Synthetics 配置

您可以通过提供一个名为 synthetics.json 的可选 JSON 配置文件来配置 Synthetics Java 运行时的行为。此文件应打包到 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 运行时会为每一次金丝雀运行创建 CloudWatch 日志。日志以 JSON 格式编写，便于查询。您还可以选择将日志格式更改为 TEXT。

日志级别

除了以上环境变量外，Java 运行时还会为函数添加一个默认环境变量 AWS_LAMBDA-EXEC_WRAPPER，并将其值设置为 /opt/synthetics-otel-instrument。此环境变量会修改函数用于遥测的启动行为。如果此环境变量已存在，则确保将其设置为所需值。