Instrumentação do código Java no AWS Lambda

Modo de foco

Instrumentação do código Java no AWS Lambda - AWS Lambda

Uso do Powertools para AWS Lambda (Java) e do AWS SAM para rastreamento Uso do Powertools para AWS Lambda (Java) e do AWS CDK para rastreamento Usar o ADOT para instrumentar funções do Java Usar o SDK do X-Ray para instrumentar suas funções Java Ativar o rastreamento com o console do Lambda Ativar o rastreamento com a API do Lambda Ativar o rastreamento com o AWS CloudFormation Interpretar um rastreamento do X-Ray Armazenar dependências de runtime em uma camada (SDK do X-Ray)Rastreamento do X-Ray em aplicações de exemplo (SDK do X-Ray)

O Lambda se integra ao AWS X-Ray para ajudar você a rastrear, depurar e otimizar aplicações do Lambda. É possível usar o X-Ray para rastrear uma solicitação enquanto ela atravessa recursos na aplicação, o que pode incluir funções Lambda e outros produtos da AWS.

Para enviar dados de rastreamento ao X-Ray, você pode usar uma das duas bibliotecas SDK:

AWS Distro for OpenTelemetry (ADOT): uma distribuição segura, pronta para produção e com suporte na AWS do SDK OpenTelemetry (OTel).
SDK do AWS X-Ray for Java: um SDK para geração e envio de dados de rastreamento ao X-Ray.
Powertools para AWS Lambda (Java): kit de ferramentas para desenvolvedores para implementar as práticas recomendadas da tecnologia sem servidor e aumentar a velocidade do desenvolvedor.

Cada um dos SDKs oferece maneiras de enviar dados de telemetria ao serviço do X-Ray. Em seguida, é possível usar o X-Ray para visualizar, filtrar e obter insights sobre as métricas de performance da aplicação para identificar problemas e oportunidades de otimização.

Importante

Os SDKs do X-Ray e do Powertools para AWS Lambda fazem parte de uma solução de instrumentação totalmente integrada oferecida pela AWS. As camadas do Lambda para ADOT fazem parte de um padrão em todo o setor para instrumentação de rastreamento que coleta mais dados em geral, mas pode não ser adequado para todos os casos de uso. É possível implementar o rastreamento de ponta a ponta no X-Ray usando ambas as soluções. Para saber mais sobre como escolher entre elas, consulte Como escolher entre os SDKs do AWS Distro para OpenTelemetry e do X-Ray.

Seções

Uso do Powertools para AWS Lambda (Java) e do AWS SAM para rastreamento
Uso do Powertools para AWS Lambda (Java) e do AWS CDK para rastreamento
Usar o ADOT para instrumentar funções do Java
Usar o SDK do X-Ray para instrumentar suas funções Java
Ativar o rastreamento com o console do Lambda
Ativar o rastreamento com a API do Lambda
Ativar o rastreamento com o AWS CloudFormation
Interpretar um rastreamento do X-Ray
Armazenar dependências de runtime em uma camada (SDK do X-Ray)
Rastreamento do X-Ray em aplicações de exemplo (SDK do X-Ray)

Uso do Powertools para AWS Lambda (Java) e do AWS SAM para rastreamento

Siga as etapas abaixo para baixar, criar e implantar um exemplo da aplicação Hello World em Java com os módulos integrados do Powertools para AWS Lambda (Java) usando o AWS SAM. Esta aplicação implementa um backend de API básico e usa o Powertools para emitir logs, métricas e rastreamentos. Consiste em um endpoint do Amazon API Gateway e uma função do Lambda. Quando você envia uma solicitação GET ao endpoint do API Gateway, a função do Lambda invoca, envia logs e métricas usando o formato de métricas incorporadas ao CloudWatch e envia rastreamentos ao AWS X-Ray. A função retorna uma mensagem hello world.

Pré-requisitos

Para executar as etapas desta seção, você deve ter o seguinte:

Java 11
AWS CLI versão 2
AWS SAM CLI versão 1.75 ou posterior. Se você tiver uma versão mais antiga da CLI do AWS SAM, consulte Atualizando a CLI do AWS SAM.

Implantar uma aplicação de exemplo do AWS SAM

Inicialize a aplicação usando o modelo Java do Hello World.


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

Crie a aplicação.
```
cd sam-app && sam build
```
Implante o aplicativo.
```
sam deploy --guided
```
Siga as instruções na tela. Para aceitar as opções padrão fornecidas na experiência interativa, pressione Enter.

nota
Em HelloWorldFunction pode não ter autorização definida, tudo bem?, certifique-se de inserir y.

Obtenha o URL da aplicação implantada:


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

Invoque o endpoint da API:
```
curl -X GET <URL_FROM_PREVIOUS_STEP>
```
Se tiver êxito, você verá esta resposta:
```
{"message":"hello world"}
```

Para obter os rastreamentos da função, execute sam traces.


sam traces

A saída de rastreamento se parece com:


New XRay Service Graph
  Start time: 2023-02-03 14:31:48+01:00
  End time: 2023-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 (2023-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

Este é um endpoint de API pública que é acessado pela Internet. Recomendamos excluir o endpoint após o teste.
```
sam delete
```

Uso do Powertools para AWS Lambda (Java) e do AWS CDK para rastreamento

Siga as etapas abaixo para baixar, criar e implantar um exemplo da aplicação Hello World em Java com os módulos integrados do Powertools para AWS Lambda (Java) usando o AWS CDK. Esta aplicação implementa um backend de API básico e usa o Powertools para emitir logs, métricas e rastreamentos. Consiste em um endpoint do Amazon API Gateway e uma função do Lambda. Quando você envia uma solicitação GET ao endpoint do API Gateway, a função do Lambda invoca, envia logs e métricas usando o formato de métricas incorporadas ao CloudWatch e envia rastreamentos ao AWS X-Ray. A função retorna uma mensagem de hello world.

Pré-requisitos

Para executar as etapas desta seção, você deve ter o seguinte:

Java 11
AWS CLI versão 2
AWS CDK versão 2
AWS SAM CLI versão 1.75 ou posterior. Se você tiver uma versão mais antiga da CLI do AWS SAM, consulte Atualizando a CLI do AWS SAM.

Implantar uma aplicação de exemplo do AWS CDK

Crie um diretório de projeto para sua aplicação.
```
mkdir hello-world
cd hello-world
```
Inicialize a aplicação.
```
cdk init app --language java
```

Crie o projeto maven com o seguinte comando:


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

Abra pom.xml no diretório hello-world\app\Function e substitua o código existente pelo código a seguir, que inclui dependências e plugins do maven para 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>

Crie o diretório hello-world\app\src\main\resource e crie log4j.xml para a configuração do log.
```
mkdir -p src/main/resource
cd src/main/resource
touch log4j.xml
```

Abra log4j.xml e adicione o código a seguir.


<?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>

Abra o App.java partir do diretório hello-world\app\Function\src\main\java\helloworld e substitua o código existente pelo código a seguir. Este é o código da função do 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()));
        }
    }
}

Abra o HelloWorldStack.java partir do diretório hello-world\src\main\java\com\myorg e substitua o código existente pelo código a seguir. Esse código usa o construtor Lambda e o construtor ApiGatewayv2 para criar uma API REST e uma função do 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());
    }
}

Abra o pom.xml partir do diretório hello-world e substitua o código existente pelo código a seguir.


<?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>

Verifique se você está no diretório hello-world e implante a sua aplicação.
```
cdk deploy
```

Obtenha o URL da aplicação implantada:


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

Invoque o endpoint da API:
```
curl -X GET <URL_FROM_PREVIOUS_STEP>
```
Se tiver êxito, você verá esta resposta:
```
{"message":"hello world"}
```

Para obter os rastreamentos da função, execute sam traces.


sam traces

A saída de rastreamento se parece com:


New XRay Service Graph
  Start time: 2023-02-03 14:59:50+00:00
  End time: 2023-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 (2023-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

Este é um endpoint de API pública que é acessado pela Internet. Recomendamos excluir o endpoint após o teste.
```
cdk destroy
```

Usar o ADOT para instrumentar funções do Java

O ADOT fornece camadas do Lambda totalmente gerenciadas que empacotam tudo o que você precisa para coletar dados de telemetria usando o SDK do OTel. Ao consumir essa camada, é possível instrumentar suas funções Lambda sem precisar modificar nenhum código de função. Você também pode configurar sua camada para fazer a inicialização personalizada do OTel. Para obter mais informações, consulte Custom configuration for the ADOT Collector on Lambda (Configuração personalizada para o ADOT Collector no Lambda) na documentação do ADOT.

Para runtimes do Java, é possível escolher entre duas camadas para consumir:

Camada do Lambda gerenciada pela AWS para ADOT Java (agente de instrumentação automática): esta camada transforma automaticamente o código da função na inicialização para coletar dados de rastreamento. Para obter instruções detalhadas sobre como consumir essa camada junto com o agente Java do ADOT, consulte Suporte do AWS Distro for OpenTelemetry Lambda para Java (agente de instrumentação automática), na documentação do ADOT.
Camada Lambda gerenciada pela AWS para ADOT Java: esta camada também fornece instrumentação integrada para funções Lambda, mas requer algumas alterações manuais de código para inicializar o SDK do OTel. Para obter instruções detalhadas sobre como consumir essa camada, consulte Suporte do AWS Distro for OpenTelemetry Lambda para Java, na documentação do ADOT.

Usar o SDK do X-Ray para instrumentar suas funções Java

Para registrar dados sobre chamadas que sua função faz para outros recursos e serviços em sua aplicação, adicione o X-Ray SDK for Java à sua configuração de compilação. O exemplo a seguir mostra uma configuração de compilação do Gradle que inclui as bibliotecas que ativam a instrumentação automática de clientes do AWS SDK for Java 2.x.

exemplo build.gradle: rastrear dependências


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'
    ...
}

Depois de adicionar as dependências corretas e fazer as devidas mudanças de código, ative o rastreamento na configuração da sua função usando o console do Lambda ou a API.

Ativar o rastreamento com o console do Lambda

Para alternar o rastreamento ativo na sua função do Lambda usando o console, siga as etapas abaixo:

Para ativar o rastreamento ativo

Abra a página Funções do console do Lambda.
Escolha uma função.
Escolha Configuration (Configuração) e depois Monitoring and operations tools (Ferramentas de monitoramento e operações).
Em Ferramentas de monitoramento adicionais, selecione Editar.
Em CloudWatch Application Signals e AWS X-Ray, escolha Habilitar para Rastreamentos do serviço Lambda.
Escolha Salvar.

Ativar o rastreamento com a API do Lambda

Configure o rastreamento na sua função do Lambda com a AWS CLI ou o AWS SDK, usando as seguintes operações de API:

O exemplo de comando da AWS CLI a seguir habilita o rastreamento ativo em uma função chamada my-function.


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

O modo de rastreamento faz parte da configuração específica da versão quando você publica uma versão da função. Não é possível alterar o modo de rastreamento em uma versão publicada.

Ativar o rastreamento com o AWS CloudFormation

Para ativar o rastreamento ativo em um recurso AWS::Lambda::Function em um modelo do AWS CloudFormation, use a propriedade TracingConfig.

exemplo function-inline.yml: configuração de rastreamento


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

Para um recurso do AWS Serverless Application Model (AWS SAM) AWS::Serverless::Function, use a propriedade Tracing.

exemplo template.yml: configuração de rastreamento


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

Interpretar um rastreamento do X-Ray

Sua função precisa de permissão para carregar dados de rastreamento no X-Ray. Quando você ativa o rastreamento ativo no console do Lambda, o Lambda adiciona as permissões necessárias à função de execução da função. Caso contrário, adicione a política AWSXRayDaemonWriteAccess à função de execução.

Após configurar o rastreamento ativo, você pode observar solicitações específicas por meio da aplicação. O grafo de serviço do X-Ray exibe informações sobre sua aplicação e todos os componentes. O exemplo a seguir mostra uma aplicação com duas funções. A função principal processa eventos e, às vezes, retorna erros. A segunda função de cima para baixo processa erros que aparecem no primeiro grupo de logs e usa o AWS SDK para chamar o X-Ray, o Amazon Simple Storage Service (Amazon S3) e o Amazon CloudWatch Logs.

Um diagrama que mostra duas aplicações separadas e seus respectivos mapas de serviço no X-Ray

O X-Ray não rastreia todas as solicitações para sua aplicação. O X-Ray aplica um algoritmo de amostragem para garantir que o rastreamento seja eficiente, enquanto ainda fornece uma amostra representativa das solicitações. A taxa de amostragem é uma solicitação por segundo e 5% de solicitações adicionais. Você não pode configurar a taxa de amostragem do X-Ray para suas funções.

No X-Ray, um rastreamento registra informações sobre uma solicitação que é processada por um ou mais serviços. O Lambda registra dois segmentos por rastreamento, o que cria dois nós no gráfico de serviços. A imagem a seguir destaca esses dois nós:

Um mapa de serviço do X-Ray com uma única função.

O primeiro nó à esquerda representa o serviço do Lambda, que recebe a solicitação de invocação. O segundo nó representa a sua função do Lambda específica. O exemplo a seguir mostra um rastreamento com esses dois segmentos. Ambos têm o nome my-function, mas um tem a origem AWS::Lambda e o outro, a origem AWS::Lambda::Function. Se o segmento AWS::Lambda mostrar um erro, o serviço Lambda teve um problema. Se o segmento AWS::Lambda::Function mostrar um erro, sua função teve um problema.

Um rastreamento do X-Ray que mostra latência em cada subsegmento de uma invocação específica do Lambda.

Este exemplo expande o segmento AWS::Lambda::Function para mostrar seus três subsegmentos.

nota

A AWS atualmente está implementando alterações no serviço Lambda. Devido a essas alterações, você pode ver pequenas diferenças entre a estrutura e o conteúdo das mensagens de log do sistema e os segmentos de rastreamento emitidos por diferentes funções do Lambda na sua Conta da AWS.

O exemplo de rastreamento mostrado aqui ilustra o segmento de função no estilo antigo. As diferenças entre os segmentos no estilo antigo e no estilo novo são descritas nos próximos parágrafos.

Essas alterações serão implementadas durante as próximas semanas, e todas as funções em todas as Regiões da AWS, exceto nas regiões China e GovCloud, passarão a usar o novo formato de mensagens de log e segmentos de rastreamento.

O segmento de função no estilo antigo contém os seguintes subsegmentos:

Inicialização: representa o tempo gasto carregando a função e executando o código de inicialização. Esse subsegmento aparece somente para o primeiro evento que cada instância da função processa.
Invocação: representa o tempo gasto na execução do código do manipulador.
Sobrecarga: representa o tempo gasto pelo runtime do Lambda preparando-se para lidar com o próximo evento.

O segmento de função no estilo novo não contém um subsegmento Invocation. Em vez disso, os subsegmentos dos clientes são anexados diretamente ao segmento da função. Para obter mais informações sobre a estrutura dos segmentos de função no estilo antigo e no estilo novo, consulte Noções básicas sobre rastreamentos do X-Ray.

nota

As funções Lambda SnapStart também incluem um subsegmento Restore. O subsegmento Restore mostra o tempo necessário para o Lambda restaurar um snapshot, carregar o runtime e executar qualquer hook de runtime after-restore. O processo de restauração de snapshots pode incluir o tempo gasto em atividades fora da MicroVM. Esse tempo é relatado no subsegmento Restore. Você não é cobrado pelo tempo gasto fora da microVM para restaurar um snapshot.

Você também pode instrumentar clientes HTTP, registrar consultas SQL e criar subsegmentos personalizados com anotações e metadados. Para obter mais informações, consulte SDK do AWS X-Ray for Java no Guia do desenvolvedor do AWS X-Ray.

Preços

Você pode usar o rastreamento do X-Ray gratuitamente todos os meses até determinado limite como parte do nível gratuito da AWS. Além do limite, o X-Ray cobra por armazenamento e recuperação de rastreamento. Para obter mais informações, consulte Preços do AWS X-Ray.

Armazenar dependências de runtime em uma camada (SDK do X-Ray)

Se você usar o X-Ray SDK para instrumentar os clientes do AWS SDK com seu código de função, seu pacote de implantação poderá se tornar bastante grande. Para evitar o upload de dependências de runtime todas as vezes que você atualizar seu código de função, empacote o SDK do X-Ray em uma camada do Lambda.

O exemplo a seguir mostra um recurso AWS::Serverless::LayerVersion que armazena o AWS SDK para Java e o X-Ray SDK for Java.

exemplo template.yml: camada de dependências


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:
        - java21

Com essa configuração, você atualizará a camada de biblioteca somente se alterar as dependências de runtime. Já que o pacote de implantação de função inclui apenas o seu código, isso pode ajudar a reduzir o tempo de upload.

A criação de uma camada de dependências requer alterações de configuração de compilação para gerar o arquivo de camada antes da implantação. Para obter um exemplo funcional, consulte a aplicação de exemplo java-basic no GitHub.

Rastreamento do X-Ray em aplicações de exemplo (SDK do X-Ray)

O repositório do GitHub para este guia inclui aplicações de exemplo que demonstram o uso do rastreamento do X-Ray. Cada aplicativo de exemplo inclui scripts para fácil implantação e limpeza, um modelo do AWS SAM e recursos de suporte.

Aplicações de exemplo do Lambda em Java

example-java: uma função Java que demonstra como você pode usar o Lambda para processar pedidos. Essa função ilustra como definir e desserializar um objeto de evento de entrada personalizado, usar o AWS SDK e gerar logs de saída.
java-basic: uma coleção de funções Java mínimas com testes de unidade e configuração de registro em log variável.
java-events: uma coleção de funções do Java contendo código básico sobre como lidar com eventos de vários serviços, como o Amazon API Gateway, o Amazon SQS e o Amazon Kinesis. Essas funções usam a versão mais recente da biblioteca aws-lambda-java-events (3.0.0 e versões mais recentes). Estes exemplos não exigem o AWS SDK como dependência.
s3-java: uma função em Java que processa eventos de notificação do Amazon S3 e usa a Java Class Library (JCL) para criar miniaturas de arquivos de imagem enviados por upload.
layer-java: uma função Java que ilustra como usar uma camada do Lambda para empacotar dependências separadamente do código da função principal.

Todas as aplicações de exemplo têm rastreamento ativo habilitado para funções do Lambda. Por exemplo, a aplicação s3-java mostra instrumentação automática de clientes AWS SDK for Java 2.x, gerenciamento de segmentos para testes, subsegmentos personalizados e o uso de camadas do Lambda para armazenar dependências de runtime.

Atenção O Javascript está desativado ou não está disponível no seu navegador.

Para usar a documentação da AWS, o Javascript deve estar ativado. Consulte as páginas de Ajuda do navegador para obter instruções.

Convenções do documento

Registro em log

Aplicativos de amostra

Nesta página

Selecione suas preferências de cookies

Instrumentação do código Java no AWS Lambda

Importante

Seções

Uso do Powertools para AWS Lambda (Java) e do AWS SAM para rastreamento

Pré-requisitos

Implantar uma aplicação de exemplo do AWS SAM

nota

Uso do Powertools para AWS Lambda (Java) e do AWS CDK para rastreamento

Pré-requisitos

Implantar uma aplicação de exemplo do AWS CDK

Usar o ADOT para instrumentar funções do Java

Usar o SDK do X-Ray para instrumentar suas funções Java

exemplo build.gradle: rastrear dependências

Ativar o rastreamento com o console do Lambda

Para ativar o rastreamento ativo

Ativar o rastreamento com a API do Lambda

Ativar o rastreamento com o AWS CloudFormation

exemplo function-inline.yml: configuração de rastreamento

exemplo template.yml: configuração de rastreamento

Interpretar um rastreamento do X-Ray

nota

nota

Preços

Armazenar dependências de runtime em uma camada (SDK do X-Ray)

exemplo template.yml: camada de dependências

Rastreamento do X-Ray em aplicações de exemplo (SDK do X-Ray)

Aplicações de exemplo do Lambda em Java

Nesta página

Related resources

Esta página foi útil?

Related resources

Próximo tópico:

Tópico anterior:

Precisa de ajuda?