Strumentazione del codice Java in AWS Lambda

Lambda si integra con AWS X-Ray per aiutarti a tracciare, eseguire il debug e ottimizzare le applicazioni Lambda. Puoi usarlo X-Ray per tracciare una richiesta mentre attraversa le risorse dell'applicazione, che possono includere funzioni Lambda e altri servizi. AWS

Per inviare i dati di tracciamento a X-Ray, puoi utilizzare una delle due librerie SDK:

• AWS Distro for OpenTelemetry (ADOT): una distribuzione sicura, pronta per la produzione e AWS supportata dell'SDK (Otel). OpenTelemetry

• SDK AWS X-Ray per Java— Un SDK per la generazione e l'invio di dati di traccia a. X-Ray

• Powertools for AWS Lambda (Java): un toolkit per sviluppatori per implementare le migliori pratiche Serverless e aumentare la velocità degli sviluppatori.

Ciascuno degli SDK offre modi per inviare i dati di telemetria al servizio. X-Ray Puoi quindi utilizzarli X-Ray per visualizzare, filtrare e ottenere informazioni dettagliate sulle metriche delle prestazioni dell'applicazione per identificare problemi e opportunità di ottimizzazione.

Importante

Powertools for AWS Lambda SDK X-Ray e Powertools fanno parte di una soluzione di strumentazione strettamente integrata offerta da. AWS I livelli Lambda ADOT fanno parte di uno standard di settore per la strumentazione di tracciamento che in generale raccoglie più dati, ma potrebbero non essere adatti a tutti i casi d'uso. È possibile implementare la tracciabilità end-to-end utilizzando entrambe le soluzioni. X-Ray Per saperne di più sulla scelta tra di esse, consulta Scelta tra AWS Distro for Open Telemetry e SDK. X-Ray

Utilizzo di Powertools per AWS Lambda (Java) e AWS SAM per tracciare

Segui i passaggi seguenti per scaricare, creare e distribuire un'applicazione Java Hello World di esempio con i moduli Powertools for AWS Lambda (Java) integrati utilizzando. AWS SAM Questa applicazione implementa un backend dell'API di base e utilizza Powertools per l'emissione di log, parametri e tracce. È costituito da un endpoint Amazon API Gateway e da una funzione evento Lambda. Quando invii una richiesta GET all'endpoint API Gateway, la funzione Lambda richiama, invia log e metriche utilizzando Embedded Metric Format a e invia tracce a. CloudWatch AWS X-Ray La funzione restituisce un messaggio hello world.

Prerequisiti

Per completare le fasi riportate in questa sezione, è necessario:

• Java 11 o versione successiva

• AWS CLI versione 2

• AWS SAM CLI versione 1.75 o successiva. Se disponi di una versione precedente della AWS SAM CLI, consulta Aggiornamento della CLI. AWS SAM

Distribuisci un esempio AWS SAM applicazione

1. Inizializza l'applicazione utilizzando il modello Java Hello World.

   sam init --app-template hello-world-powertools-java --name sam-app --package-type Zip --runtime java11 --no-tracing

2. Costruisci l'app.

   cd sam-app && sam build

3. Distribuire l'app.

   sam deploy --guided

4. Seguire le istruzioni visualizzate sullo schermo. Per accettare le opzioni predefinite fornite nell'esperienza interattiva, premi Enter.

   Nota

   Perché HelloWorldFunction potrebbe non avere un'autorizzazione definita, va bene? , assicurati di entrarey.

5. Ottieni l'URL dell'applicazione implementata:

   aws cloudformation describe-stacks --stack-name sam-app --query 'Stacks[0].Outputs[?OutputKey==`HelloWorldApi`].OutputValue' --output text

6. Richiama l'endpoint dell'API:

   curl -X GET <URL_FROM_PREVIOUS_STEP>

   In caso di esito positivo, vedrai questa risposta:

   {"message":"hello world"}

7. Per ottenere le tracce per la funzione, esegui sam traces.

   sam traces

   L'output della traccia ha il seguente aspetto:

   New XRay Service Graph
     Start time: 2025-02-03 14:31:48+01:00
     End time: 2025-02-03 14:31:48+01:00
     Reference Id: 0 - (Root) AWS::Lambda - sam-app-HelloWorldFunction-y9Iu1FLJJBGD - Edges: []
      Summary_statistics:
        - total requests: 1
        - ok count(2XX): 1
        - error count(4XX): 0
        - fault count(5XX): 0
        - total response time: 5.587
     Reference Id: 1 - client - sam-app-HelloWorldFunction-y9Iu1FLJJBGD - Edges: [0]
      Summary_statistics:
        - total requests: 0
        - ok count(2XX): 0
        - error count(4XX): 0
        - fault count(5XX): 0
        - total response time: 0
   
   XRay Event [revision 3] at (2025-02-03T14:31:48.500000) with id (1-63dd0cc4-3c869dec72a586875da39777) and duration (5.603s)
    - 5.587s - sam-app-HelloWorldFunction-y9Iu1FLJJBGD [HTTP: 200]
    - 4.053s - sam-app-HelloWorldFunction-y9Iu1FLJJBGD
      - 1.181s - Initialization
      - 4.037s - Invocation
        - 1.981s - ## handleRequest
          - 1.840s - ## getPageContents
      - 0.000s - Overhead

8. Questo è un endpoint API pubblico accessibile su Internet. È consigliabile eliminare l'endpoint dopo il test.

   sam delete

Utilizzo di Powertools per AWS Lambda (Java) e AWS CDK per tracciare

Segui i passaggi seguenti per scaricare, creare e distribuire un'applicazione Java Hello World di esempio con i moduli Powertools for AWS Lambda (Java) integrati utilizzando. AWS CDK Questa applicazione implementa un backend dell'API di base e utilizza Powertools per l'emissione di log, parametri e tracce. È costituito da un endpoint Amazon API Gateway e da una funzione evento Lambda. Quando invii una richiesta GET all'endpoint API Gateway, la funzione Lambda richiama, invia log e metriche utilizzando Embedded Metric Format a e invia tracce a. CloudWatch AWS X-Ray La funzione restituisce un messaggio hello world.

Prerequisiti

Per completare le fasi riportate in questa sezione, è necessario:

• Java 11 o versione successiva

• AWS CLI versione 2

• AWS CDK versione 2

• AWS SAM CLI versione 1.75 o successiva. Se disponi di una versione precedente della AWS SAM CLI, consulta Aggiornamento della CLI. AWS SAM

Distribuisci un esempio AWS CDK applicazione

1. Crea una directory di progetto per la nuova applicazione.

   mkdir hello-world
   cd hello-world

2. Inizializza l'app.

   cdk init app --language java

3. Crea un progetto maven utilizzando il comando seguente:

   mkdir app
   cd app
   mvn archetype:generate -DgroupId=helloworld -DartifactId=Function -DarchetypeArtifactId=maven-archetype-quickstart -DinteractiveMode=false

4. Apri pom.xml nella directory hello-world\app\Function e sostituisci il codice esistente con il codice seguente, che include dipendenze e plug-in maven per Powertools.

   <project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
     xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">
     <modelVersion>4.0.0</modelVersion>
     <groupId>helloworld</groupId>
     <artifactId>Function</artifactId>
     <packaging>jar</packaging>
     <version>1.0-SNAPSHOT</version>
     <name>Function</name>
     <url>http://maven.apache.org</url>
   <properties>
       <maven.compiler.source>11</maven.compiler.source>
       <maven.compiler.target>11</maven.compiler.target>
       <log4j.version>2.17.2</log4j.version>
   </properties>
       <dependencies>
           <dependency>
               <groupId>junit</groupId>
               <artifactId>junit</artifactId>
               <version>3.8.1</version>
               <scope>test</scope>
           </dependency>
           <dependency>
               <groupId>software.amazon.lambda</groupId>
               <artifactId>powertools-tracing</artifactId>
               <version>1.3.0</version>
           </dependency>
           <dependency>
               <groupId>software.amazon.lambda</groupId>
               <artifactId>powertools-metrics</artifactId>
               <version>1.3.0</version>
           </dependency>
           <dependency>
               <groupId>software.amazon.lambda</groupId>
               <artifactId>powertools-logging</artifactId>
               <version>1.3.0</version>
           </dependency>
           <dependency>
               <groupId>com.amazonaws</groupId>
               <artifactId>aws-lambda-java-core</artifactId>
               <version>1.2.2</version>
           </dependency>
           <dependency>
               <groupId>com.amazonaws</groupId>
               <artifactId>aws-lambda-java-events</artifactId>
               <version>3.11.1</version>
           </dependency>
     </dependencies>
   <build>
       <plugins>
           <plugin>
               <groupId>org.codehaus.mojo</groupId>
               <artifactId>aspectj-maven-plugin</artifactId>
               <version>1.14.0</version>
               <configuration>
                   <source>${maven.compiler.source}</source>
                   <target>${maven.compiler.target}</target>
                   <complianceLevel>${maven.compiler.target}</complianceLevel>
                   <aspectLibraries>
                       <aspectLibrary>
                           <groupId>software.amazon.lambda</groupId>
                           <artifactId>powertools-tracing</artifactId>
                       </aspectLibrary>
                       <aspectLibrary>
                           <groupId>software.amazon.lambda</groupId>
                           <artifactId>powertools-metrics</artifactId>
                       </aspectLibrary>
                       <aspectLibrary>
                           <groupId>software.amazon.lambda</groupId>
                           <artifactId>powertools-logging</artifactId>
                       </aspectLibrary>
                   </aspectLibraries>
               </configuration>
               <executions>
                   <execution>
                       <goals>
                           <goal>compile</goal>
                       </goals>
                   </execution>
               </executions>
           </plugin>
           <plugin>
                   <groupId>org.apache.maven.plugins</groupId>
                   <artifactId>maven-shade-plugin</artifactId>
                   <version>3.4.1</version>
                   <executions>
                       <execution>
                           <phase>package</phase>
                           <goals>
                               <goal>shade</goal>
                           </goals>
                           <configuration>
                               <transformers>
                                   <transformer
                                           implementation="com.github.edwgiz.maven_shade_plugin.log4j2_cache_transformer.PluginsCacheFileTransformer">
                                   </transformer>
                               </transformers>
                               <createDependencyReducedPom>false</createDependencyReducedPom>
                               <finalName>function</finalName>
   
                           </configuration>
                       </execution>
                   </executions>
                   <dependencies>
                       <dependency>
                           <groupId>com.github.edwgiz</groupId>
                           <artifactId>maven-shade-plugin.log4j2-cachefile-transformer</artifactId>
                           <version>2.15</version>
                       </dependency>
                   </dependencies>
           </plugin>
       </plugins>
   </build>
   </project>
   

5. Crea la directory hello-world\app\src\main\resource e crea log4j.xml per la configurazione del log.

   mkdir -p src/main/resource
   cd src/main/resource
   touch log4j.xml

6. Apri log4j.xml e aggiungi il seguente codice.

   <?xml version="1.0" encoding="UTF-8"?>
   <Configuration>
       <Appenders>
           <Console name="JsonAppender" target="SYSTEM_OUT">
               <JsonTemplateLayout eventTemplateUri="classpath:LambdaJsonLayout.json" />
           </Console>
       </Appenders>
       <Loggers>
           <Logger name="JsonLogger" level="INFO" additivity="false">
               <AppenderRef ref="JsonAppender"/>
           </Logger>
           <Root level="info">
               <AppenderRef ref="JsonAppender"/>
           </Root>
       </Loggers>
   </Configuration>

7. Apri App.java dalla directory hello-world\app\Function\src\main\java\helloworld e sostituisci il codice esistente con il codice seguente. Questo è il codice per la funzione Lambda.

   package helloworld;
   
   import java.io.BufferedReader;
   import java.io.IOException;
   import java.io.InputStreamReader;
   import java.net.URL;
   import java.util.HashMap;
   import java.util.Map;
   import java.util.stream.Collectors;
   
   import com.amazonaws.services.lambda.runtime.Context;
   import com.amazonaws.services.lambda.runtime.RequestHandler;
   import com.amazonaws.services.lambda.runtime.events.APIGatewayProxyRequestEvent;
   import com.amazonaws.services.lambda.runtime.events.APIGatewayProxyResponseEvent;
   import org.apache.logging.log4j.LogManager;
   import org.apache.logging.log4j.Logger;
   import software.amazon.lambda.powertools.logging.Logging;
   import software.amazon.lambda.powertools.metrics.Metrics;
   import software.amazon.lambda.powertools.tracing.CaptureMode;
   import software.amazon.lambda.powertools.tracing.Tracing;
   
   import static software.amazon.lambda.powertools.tracing.CaptureMode.*;
   
   /**
    * Handler for requests to Lambda function.
    */
   public class App implements RequestHandler<APIGatewayProxyRequestEvent, APIGatewayProxyResponseEvent> {
       Logger log = LogManager.getLogger(App.class);
   
   
       @Logging(logEvent = true)
       @Tracing(captureMode = DISABLED)
       @Metrics(captureColdStart = true)
       public APIGatewayProxyResponseEvent handleRequest(final APIGatewayProxyRequestEvent input, final Context context) {
           Map<String, String> headers = new HashMap<>();
           headers.put("Content-Type", "application/json");
           headers.put("X-Custom-Header", "application/json");
   
           APIGatewayProxyResponseEvent response = new APIGatewayProxyResponseEvent()
                   .withHeaders(headers);
           try {
               final String pageContents = this.getPageContents("https://checkip.amazonaws.com");
               String output = String.format("{ \"message\": \"hello world\", \"location\": \"%s\" }", pageContents);
   
               return response
                       .withStatusCode(200)
                       .withBody(output);
           } catch (IOException e) {
               return response
                       .withBody("{}")
                       .withStatusCode(500);
           }
       }
       @Tracing(namespace = "getPageContents")
       private String getPageContents(String address) throws IOException {
           log.info("Retrieving {}", address);
           URL url = new URL(address);
           try (BufferedReader br = new BufferedReader(new InputStreamReader(url.openStream()))) {
               return br.lines().collect(Collectors.joining(System.lineSeparator()));
           }
       }
   }

8. Apri HelloWorldStack.java dalla directory hello-world\src\main\java\com\myorg e sostituisci il codice esistente con il codice seguente. Questo codice utilizza Lambda Constructor e ApiGatewayv2 Constructor per creare un'API REST e una funzione evento Lambda.

   package com.myorg;
   
   import software.amazon.awscdk.*;
   import software.amazon.awscdk.services.apigatewayv2.alpha.*;
   import software.amazon.awscdk.services.apigatewayv2.integrations.alpha.HttpLambdaIntegration;
   import software.amazon.awscdk.services.apigatewayv2.integrations.alpha.HttpLambdaIntegrationProps;
   import software.amazon.awscdk.services.lambda.Code;
   import software.amazon.awscdk.services.lambda.Function;
   import software.amazon.awscdk.services.lambda.FunctionProps;
   import software.amazon.awscdk.services.lambda.Runtime;
   import software.amazon.awscdk.services.lambda.Tracing;
   import software.amazon.awscdk.services.logs.RetentionDays;
   import software.amazon.awscdk.services.s3.assets.AssetOptions;
   import software.constructs.Construct;
   
   import java.util.Arrays;
   import java.util.List;
   
   import static java.util.Collections.singletonList;
   import static software.amazon.awscdk.BundlingOutput.ARCHIVED;
   
   public class HelloWorldStack extends Stack {
       public HelloWorldStack(final Construct scope, final String id) {
           this(scope, id, null);
       }
   
       public HelloWorldStack(final Construct scope, final String id, final StackProps props) {
           super(scope, id, props);
   
           List<String> functionPackagingInstructions = Arrays.asList(
                   "/bin/sh",
                   "-c",
                   "cd Function " +
                           "&& mvn clean install " +
                           "&& cp /asset-input/Function/target/function.jar /asset-output/"
           );
           BundlingOptions.Builder builderOptions = BundlingOptions.builder()
                   .command(functionPackagingInstructions)
                   .image(Runtime.JAVA_11.getBundlingImage())
                   .volumes(singletonList(
                           // Mount local .m2 repo to avoid download all the dependencies again inside the container
                           DockerVolume.builder()
                                   .hostPath(System.getProperty("user.home") + "/.m2/")
                                   .containerPath("/root/.m2/")
                                   .build()
                   ))
                   .user("root")
                   .outputType(ARCHIVED);
   
           Function function = new Function(this, "Function", FunctionProps.builder()
                   .runtime(Runtime.JAVA_11)
                   .code(Code.fromAsset("app", AssetOptions.builder()
                           .bundling(builderOptions
                                   .command(functionPackagingInstructions)
                                   .build())
                           .build()))
                   .handler("helloworld.App::handleRequest")
                   .memorySize(1024)
                   .tracing(Tracing.ACTIVE)
                   .timeout(Duration.seconds(10))
                   .logRetention(RetentionDays.ONE_WEEK)
                   .build());
   
           HttpApi httpApi = new HttpApi(this, "sample-api", HttpApiProps.builder()
                   .apiName("sample-api")
                   .build());
   
           httpApi.addRoutes(AddRoutesOptions.builder()
                   .path("/")
                   .methods(singletonList(HttpMethod.GET))
                   .integration(new HttpLambdaIntegration("function", function, HttpLambdaIntegrationProps.builder()
                           .payloadFormatVersion(PayloadFormatVersion.VERSION_2_0)
                           .build()))
                   .build());
   
           new CfnOutput(this, "HttpApi", CfnOutputProps.builder()
                   .description("Url for Http Api")
                   .value(httpApi.getApiEndpoint())
                   .build());
       }
   }

9. Apri pom.xml dalla directory hello-world e sostituisci il codice esistente con il codice seguente.

   <?xml version="1.0" encoding="UTF-8"?>
   <project xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd"
            xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
       <modelVersion>4.0.0</modelVersion>
   
       <groupId>com.myorg</groupId>
       <artifactId>hello-world</artifactId>
       <version>0.1</version>
   
       <properties>
           <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
           <cdk.version>2.70.0</cdk.version>
           <constructs.version>[10.0.0,11.0.0)</constructs.version>
           <junit.version>5.7.1</junit.version>
       </properties>
   
       <build>
           <plugins>
               <plugin>
                   <groupId>org.apache.maven.plugins</groupId>
                   <artifactId>maven-compiler-plugin</artifactId>
                   <version>3.8.1</version>
                   <configuration>
                       <source>1.8</source>
                       <target>1.8</target>
                   </configuration>
               </plugin>
   
               <plugin>
                   <groupId>org.codehaus.mojo</groupId>
                   <artifactId>exec-maven-plugin</artifactId>
                   <version>3.0.0</version>
                   <configuration>
                       <mainClass>com.myorg.HelloWorldApp</mainClass>
                   </configuration>
               </plugin>
           </plugins>
       </build>
   
       <dependencies>
           <!-- AWS Cloud Development Kit -->
           <dependency>
               <groupId>software.amazon.awscdk</groupId>
               <artifactId>aws-cdk-lib</artifactId>
               <version>${cdk.version}</version>
           </dependency>
           <dependency>
               <groupId>software.constructs</groupId>
               <artifactId>constructs</artifactId>
               <version>${constructs.version}</version>
           </dependency>
           <dependency>
             <groupId>org.junit.jupiter</groupId>
             <artifactId>junit-jupiter</artifactId>
             <version>${junit.version}</version>
             <scope>test</scope>
           </dependency>
           <dependency>
               <groupId>software.amazon.awscdk</groupId>
               <artifactId>apigatewayv2-alpha</artifactId>
               <version>${cdk.version}-alpha.0</version>
           </dependency>
           <dependency>
               <groupId>software.amazon.awscdk</groupId>
               <artifactId>apigatewayv2-integrations-alpha</artifactId>
               <version>${cdk.version}-alpha.0</version>
           </dependency>
       </dependencies>
   </project>

10. Assicurati di essere nella hello-world directory e distribuisci la tua applicazione.

    cdk deploy

11. Ottieni l'URL dell'applicazione implementata:

    aws cloudformation describe-stacks --stack-name HelloWorldStack --query 'Stacks[0].Outputs[?OutputKey==`HttpApi`].OutputValue' --output text

12. Richiama l'endpoint dell'API:

    curl -X GET <URL_FROM_PREVIOUS_STEP>

    In caso di esito positivo, vedrai questa risposta:

    {"message":"hello world"}

13. Per ottenere le tracce per la funzione, esegui sam traces.

    sam traces

    L'output della traccia ha il seguente aspetto:

    New XRay Service Graph
      Start time: 2025-02-03 14:59:50+00:00
      End time: 2025-02-03 14:59:50+00:00
      Reference Id: 0 - (Root) AWS::Lambda - sam-app-HelloWorldFunction-YBg8yfYtOc9j - Edges: [1]
       Summary_statistics:
         - total requests: 1
         - ok count(2XX): 1
         - error count(4XX): 0
         - fault count(5XX): 0
         - total response time: 0.924
      Reference Id: 1 - AWS::Lambda::Function - sam-app-HelloWorldFunction-YBg8yfYtOc9j - Edges: []
       Summary_statistics:
         - total requests: 1
         - ok count(2XX): 1
         - error count(4XX): 0
         - fault count(5XX): 0
         - total response time: 0.016
      Reference Id: 2 - client - sam-app-HelloWorldFunction-YBg8yfYtOc9j - Edges: [0]
       Summary_statistics:
         - total requests: 0
         - ok count(2XX): 0
         - error count(4XX): 0
         - fault count(5XX): 0
         - total response time: 0
    
    XRay Event [revision 1] at (2025-02-03T14:59:50.204000) with id (1-63dd2166-434a12c22e1307ff2114f299) and duration (0.924s)
     - 0.924s - sam-app-HelloWorldFunction-YBg8yfYtOc9j [HTTP: 200]
     - 0.016s - sam-app-HelloWorldFunction-YBg8yfYtOc9j
       - 0.739s - Initialization
       - 0.016s - Invocation
         - 0.013s - ## lambda_handler
           - 0.000s - ## app.hello
       - 0.000s - Overhead

14. Questo è un endpoint API pubblico accessibile su Internet. È consigliabile eliminare l'endpoint dopo il test.

    cdk destroy

Utilizzo di ADOT per strumentare le funzioni Java

ADOT fornisce livelli Lambda completamente gestiti che mettono insieme tutto il necessario per raccogliere i dati di telemetria utilizzando l'SDK OTel. Usando questo livello, è possibile strumentare le funzioni Lambda senza dover modificare alcun codice funzione. È inoltre possibile configurare il livello per eseguire l'inizializzazione personalizzata di OTel. Per ulteriori informazioni, consulta la sezione relativa alla configurazione personalizzata per ADOT Collector su Lambda nella documentazione di ADOT.

Per i runtime Java, è possibile scegliere tra due livelli da utilizzare:

• AWS livello Lambda gestito per ADOT Java (Auto-instrumentation Agent): questo livello trasforma automaticamente il codice della funzione all'avvio per raccogliere dati di tracciamento. Per istruzioni dettagliate su come utilizzare questo layer insieme all'agente Java ADOT, consulta AWS Distro for Lambda OpenTelemetry Support for Java (Auto-instrumentation Agent) nella documentazione ADOT.

• AWS layer Lambda gestito per ADOT Java — Questo livello fornisce anche strumentazione integrata per le funzioni Lambda, ma richiede alcune modifiche manuali al codice per inizializzare l'SDK Otel. Per istruzioni dettagliate su come utilizzare questo layer, consulta AWS Distro for OpenTelemetry Lambda Support for Java nella documentazione ADOT.

Per istruzioni sulla conversione degli eventi dell'API Lambda Telemetry in intervalli, consulta. OpenTelemetry Conversione degli oggetti Event dell'API Lambda Telemetry in Spans OpenTelemetry

Utilizzo dell'SDK per strumentare le funzioni Java X-Ray

Per registrare i dati sulle chiamate effettuate dalla tua funzione ad altre risorse e servizi dell'applicazione, puoi aggiungere l' X-Ray SDK for Java alla configurazione della build. L'esempio seguente mostra una configurazione di build Gradle che include le librerie che attivano la strumentazione automatica dei client. AWS SDK for Java 2.x

Esempio build.gradle — Tracciamento delle dipendenze

dependencies {
    implementation platform('software.amazon.awssdk:bom:2.16.1')
    implementation platform('com.amazonaws:aws-xray-recorder-sdk-bom:2.11.0')
    ...
    implementation 'com.amazonaws:aws-xray-recorder-sdk-core'
    implementation 'com.amazonaws:aws-xray-recorder-sdk-aws-sdk'
    implementation 'com.amazonaws:aws-xray-recorder-sdk-aws-sdk-v2-instrumentor'
    ...
}

Dopo aver aggiunto le dipendenze corrette e apportato le modifiche necessarie al codice, attiva il tracciamento nella configurazione della funzione tramite la console Lambda o l'API.

Attivazione del tracciamento con la console Lambda

Per attivare il tracciamento attivo sulla tua Lambda Event Function con la console, segui questi passaggi:

Per attivare il tracciamento attivo

1. Apri la pagina Event Functions della console Lambda.

2. Scegliete una funzione di evento.

3. Scegliere Configuration (Configurazione) e quindi Monitoring and operations tools (Strumenti di monitoraggio e operazioni).

4. In Strumenti di monitoraggio aggiuntivi scegli Modifica.

5. In CloudWatch Application Signals e AWS X-Ray, scegli Enable for Lambda service trace.

6. Selezionare Salva.

Attivazione del tracciamento con l'API Lambda

Configura il tracciamento sulla tua funzione Lambda con AWS o SDK, utilizza AWS CLI le seguenti operazioni API:

• UpdateFunctionConfiguration

• GetFunctionConfiguration

• CreateFunction

Il AWS CLI comando di esempio seguente abilita il tracciamento attivo su una funzione denominata my-function.

aws lambda update-function-configuration --function-name my-function \
--tracing-config Mode=Active

La modalità di tracciamento fa parte della configurazione specifica della versione quando si pubblica una versione della funzione. Non è possibile modificare la modalità di tracciamento in una versione pubblicata.

Attivazione del tracciamento con CloudFormation

Per attivare il tracciamento su una AWS::Lambda::Function risorsa in un CloudFormation modello, utilizzate la proprietà. TracingConfig

Esempio function-inline.yml — Configurazione di tracciamento

Resources:
  function:
    Type: AWS::Lambda::Function
    Properties:
      TracingConfig:
        Mode: Active
      ...

Per una AWS::Serverless::Function risorsa AWS Serverless Application Model (AWS SAM), utilizzate la Tracing proprietà.

Esempio template.yml — Configurazione di tracciamento

Resources:
  function:
    Type: AWS::Serverless::Function
    Properties:
      Tracing: Active
      ...

Interpretazione e traccia X-Ray

La tua Event Function necessita dell'autorizzazione per caricare i dati di traccia su. X-Ray Quando attivi il tracciamento nella console Lambda, Lambda aggiunge le autorizzazioni richieste al ruolo di esecuzione della tua Event Function. Altrimenti, aggiungi la AWSXRayDaemonWriteAccesspolicy al ruolo di esecuzione.

Dopo aver configurato il tracciamento attivo, è possibile osservare richieste specifiche tramite l'applicazione. Il grafico del X-Ray servizio mostra informazioni sull'applicazione e su tutti i suoi componenti. Il seguente esempio mostra un'applicazione con due funzioni. La funzione principale elabora gli eventi e talvolta restituisce errori. La seconda funzione in alto elabora gli errori che compaiono nel gruppo di log della prima e utilizza l' AWS SDK per chiamare X-Ray Amazon Simple Storage Service (Amazon S3) e Amazon Logs. CloudWatch

X-Ray non tiene traccia di tutte le richieste inviate all'applicazione. X-Ray applica un algoritmo di campionamento per garantire che il tracciamento sia efficiente, pur fornendo un campione rappresentativo di tutte le richieste. La frequenza di campionamento è di una richiesta al secondo e del 5% delle altre richieste. Non puoi configurare la frequenza di X-Ray campionamento per le tue funzioni.

In X-Ray, una traccia registra le informazioni su una richiesta che viene elaborata da uno o più servizi. Lambda registra 2 segmenti per traccia, che creano due nodi sul grafico del servizio. L'immagine seguente evidenzia questi due nodi:

Il primo nodo a sinistra rappresenta il servizio Lambda che riceve la richiesta di chiamata. Il secondo nodo rappresenta la specifica funzione Lambda. L'esempio seguente mostra una traccia con questi 2 segmenti. Entrambi sono nominati my-function, ma uno ha l'origine AWS::Lambda e l'altro ha l'origine AWS::Lambda::Function. Se il segmento AWS::Lambda mostra un errore, il servizio Lambda ha avuto un problema. Se il AWS::Lambda::Function segmento mostra un errore, la funzione ha avuto un problema.

Questo esempio espande il segmento AWS::Lambda::Function per visualizzare i relativi tre sottosegmenti.

Nota

AWS sta attualmente implementando modifiche al servizio Lambda. A causa di queste modifiche, potresti notare piccole differenze tra la struttura e il contenuto dei messaggi di registro di sistema e dei segmenti di traccia emessi da diverse funzioni di evento Lambda nel tuo. Account AWS

La traccia di esempio mostrata qui illustra il segmento di funzione vecchio stile. Le differenze tra i segmenti vecchio e nuovo stile sono descritte nei paragrafi seguenti.

Queste modifiche verranno implementate nelle prossime settimane e tutte le funzioni, Regioni AWS ad eccezione della Cina e delle GovCloud regioni, passeranno all'utilizzo dei messaggi di registro e dei segmenti di traccia di nuovo formato.

Il segmento di funzioni vecchio stile contiene i seguenti sottosegmenti:

• Inizializzazione – Rappresenta il tempo trascorso a caricare la funzione e ad eseguire il codice di inizializzazione. Questo sottosegmento viene visualizzato solo per il primo evento che viene elaborato da ogni istanza della funzione.

• Chiamata: rappresenta il tempo impiegato per eseguire il codice del gestore.

• Overhead: rappresenta il tempo impiegato dal runtime Lambda per prepararsi a gestire l'evento successivo.

Il segmento di funzione di nuovo stile non contiene un sottosegmento Invocation. I sottosegmenti dei clienti sono invece collegati direttamente al segmento di funzioni. Per ulteriori informazioni sulla struttura dei segmenti di funzioni vecchio e nuovo stile, consulta Comprendere le tracce X-Ray.

Nota

Le funzioni SnapStart includono anche un sottosegmento Restore. Il sottosegmento Restore mostra il tempo impiegato da Lambda per ripristinare uno snapshot, caricare il runtime ed eseguire qualsiasi hook di runtime. Il processo di ripristino degli snapshot può includere il tempo dedicato ad attività esterne alla MicroVM. Questa volta è riportato nel segmento secondario Restore. Non ti viene addebitato il tempo trascorso fuori dalla microVM per il ripristino di una snapshot.

È inoltre possibile strumentare i client HTTP, registrare query SQL e creare segmenti secondari personalizzati con annotazioni e metadati. Per ulteriori informazioni, consulta la sezione SDK AWS X-Ray per Java nella Guida per gli sviluppatori di AWS X-Ray .

Prezzi

Puoi utilizzare il X-Ray tracciamento gratuitamente ogni mese fino a un determinato limite come parte del piano gratuito. AWS Oltre tale soglia, verranno X-Ray addebitati i costi per l'archiviazione e il recupero delle tracce. Per ulteriori informazioni, consulta Prezzi di AWS X-Ray.

Archiviazione delle dipendenze di runtime in un livello (SDK) X-Ray

Se utilizzate l' X-Ray SDK per strumentare i client AWS SDK del codice della funzione, il pacchetto di distribuzione può diventare piuttosto grande. Per evitare di caricare le dipendenze di runtime ogni volta che aggiorni il codice della funzione, impacchetta l' X-Ray SDK in un livello Lambda.

L'esempio seguente mostra una AWS::Serverless::LayerVersion risorsa che memorizza l' X-Ray SDK AWS SDK per Java and per Java.

Esempio template.yml — Livello delle dipendenze

Resources:
  function:
    Type: AWS::Serverless::Function
    Properties:
      CodeUri: build/distributions/blank-java.zip
      Tracing: Active
      Layers:
        - !Ref libs
      ...
  libs:
    Type: AWS::Serverless::LayerVersion
    Properties:
      LayerName: blank-java-lib
      Description: Dependencies for the blank-java sample app.
      ContentUri: build/blank-java-lib.zip
      CompatibleRuntimes:
        - java25

Con questa configurazione, si aggiorna il livello della libreria solo se si modificano le dipendenze di runtime. Poiché il pacchetto di implementazione della funzione contiene solo il codice, questo può contribuire a ridurre i tempi di caricamento.

La creazione di un livello per le dipendenze richiede modifiche alla configurazione della build per generare l'archivio dei livelli prima della distribuzione. Per un esempio funzionante, vedete l'applicazione di esempio java-basic su. GitHub

X-Ray tracciamento in applicazioni di esempio (SDK) X-Ray

L' GitHub archivio di questa guida include applicazioni di esempio che dimostrano l'uso del tracciamento. X-Ray Ogni applicazione di esempio include script per facilitare la distribuzione e la pulizia, un AWS SAM modello e risorse di supporto.

Applicazioni Lambda di esempio in Java

• example-java — Una funzione Java Event che dimostra come utilizzare Lambda per elaborare gli ordini. Questa funzione illustra come definire e deserializzare un oggetto evento di input personalizzato, utilizzare l'SDK e registrare l'output. AWS

• java-basic: una raccolta di funzioni Java minimali con unit test e configurazione della registrazione dei log delle variabili.

• java-events: una raccolta di funzioni Java che contengono codice skeleton per la gestione degli eventi di vari servizi, ad esempio Gateway Amazon API, Amazon SQS e Amazon Kinesis. Queste funzioni utilizzano la versione più recente della libreria aws-lambda-java-events (3.0.0 e versioni successive). Questi esempi non richiedono l'SDK come dipendenza. AWS

• s3-java – Una funzione Java che elabora gli eventi di notifica da Amazon S3 e utilizza la Java Class Library (JCL) per creare anteprime dai file di immagine caricati.

• layer-java: una funzione Java che illustra come utilizzare un livello Lambda per impacchettare dipendenze separate dal codice della funzione principale.

Tutte le applicazioni di esempio hanno il tracciamento attivo abilitato per le funzioni Lambda. Ad esempio, l's3-javaapplicazione mostra la strumentazione automatica dei AWS SDK for Java 2.x client, la gestione dei segmenti per i test, i sottosegmenti personalizzati e l'uso dei livelli Lambda per memorizzare le dipendenze di runtime.