Elaboração de um script para o canário usando o runtime do Java

Estrutura de um projeto em Java para um canário

Para criar um canário em Java, você deve desenvolver o código, compilá-lo e implantar os artefatos compilados para o Synthetics. Você pode inicializar um projeto Java Lambda de várias maneiras. Por exemplo, você pode usar uma configuração padrão de projeto em Java no IDE de sua preferência, como IntelliJ IDEA ou Visual Studio Code. Você também pode criar a estrutura de arquivos necessária manualmente.

A estrutura geral de um projeto em Java para o Synthetics é a seguinte:

/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

Você pode usar o Maven ou o Gradle para criar seu projeto e gerenciar dependências.

Na estrutura apresentada acima, a classe ExampleCanary atua como ponto de entrada ou manipulador do canário.

Exemplo de classe de canário em Java

Este exemplo ilustra um canário que realiza uma solicitação “get” para um URL armazenado na variável de ambiente TESTING_URL do Lambda. O canário não usa nenhum dos métodos fornecidos pelo runtime do 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);
      }
  }
} 

Recomenda-se fortemente modularizar seus canários usando a função executeStep da biblioteca fornecida pelo Synthetics. O canário realiza chamadas get para dois URLs distintos, que foram obtidos das variáveis de ambiente URL1 e 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();
  }
}

Empacotamento do projeto para um canário

O Synthetics aceita que o código do canário em Java seja fornecido em um arquivo zip. O arquivo .zip consiste nos arquivos de classe do código para o canário, nos JARs de dependências de entidades externas e no arquivo de configuração do Synthetics.

A estrutura geral de um arquivo .zip do Java compatível com o Synthetics é a seguinte:

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

Para gerar esse arquivo .zip usando a estrutura de projeto apresentada acima, é possível usar o Gradle (build.gradle) ou o Maven (pom.xml). Aqui está um exemplo.

Para obter informações sobre as dependências de tempo de compilação ou as interfaces para a biblioteca do Synthetics, consulte o arquivo README do repositório 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"
}

Nome do manipulador

O nome do manipulador é o ponto de entrada para o canário. Para o runtime em Java, o manipulador deve seguir o formato apresentado a seguir.

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

Configurações do CloudWatch Synthetics

É possível configurar o comportamento do runtime em Java do Synthetics ao fornecer um arquivo de configuração em JSON opcional chamado synthetics.json. Esse arquivo deve ser empacotado no diretório raiz do pacote em .zip. Embora seja opcional, caso o arquivo de configuração não seja fornecido ou alguma chave de configuração esteja ausente, o CloudWatch usará os valores padrão.

Veja abaixo os valores de configuração compatíveis e seus padrões.

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

Configurações das etapas

Configurações de registros em log

Aplica-se aos logs gerados pelo CloudWatch Synthetics. Controla o detalhamento dos logs de solicitações e respostas.

Configurações de métricas HTTP

Configurações de métricas relacionadas à contagem de solicitações de rede com diferentes códigos de status HTTP, emitidos pelo CloudWatch Synthetics para o canário.

Configurações de métricas do canário

Configurações de outras métricas emitidas pelo CloudWatch Synthetics.

Variáveis de ambiente do CloudWatch Synthetics

Você pode configurar o nível e o formato de log ao usar variáveis de ambiente.

Formato do log

O runtime em Java do CloudWatch Synthetics cria logs no CloudWatch para cada execução do canário. Os logs são gravados no formato JSON para facilitar a consulta. Opcionalmente, é possível alterar o formato do log para TEXT.

Níveis de logs

Além das variáveis de ambiente mencionadas acima, existe uma variável de ambiente padrão adicionada para o runtime em Java, chamada AWS_LAMBDA-EXEC_WRAPPER, que deve ser configurada na sua função com o valor /opt/synthetics-otel-instrument. Essa variável de ambiente modifica o comportamento de inicialização da função para telemetria. Caso essa variável de ambiente já exista, assegure-se de que esteja configurada com o valor necessário.