# Instrumentação do código Java no AWS Lambda
<a name="java-tracing"></a>

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)](https://aws.amazon.com/otel): uma distribuição segura, pronta para produção e com suporte na AWS do SDK OpenTelemetry (OTel).
+ [SDK do AWS X-Ray for Java](https://docs.aws.amazon.com/xray/latest/devguide/xray-sdk-java.html) – um SDK para geração e envio de dados de rastreamento ao X-Ray.
+ [Powertools para AWS Lambda (Java)](https://docs.aws.amazon.com/powertools/java/latest/): 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](https://docs.aws.amazon.com/xray/latest/devguide/xray-instrumenting-your-app.html#xray-instrumenting-choosing).

**Topics**
+ [Uso do Powertools para AWS Lambda (Java) e do AWS SAM para rastreamento](#java-tracing-sam)
+ [Uso do Powertools para AWS Lambda (Java) e do AWS CDK para rastreamento](#java-tracing-cdk)
+ [Usar o ADOT para instrumentar funções do Java](#java-adot)
+ [Usar o SDK do X-Ray para instrumentar suas funções Java](#java-xray-sdk)
+ [Ativar o rastreamento com o console do Lambda](#java-tracing-console)
+ [Ativar o rastreamento com a API do Lambda](#java-tracing-api)
+ [Ativar o rastreamento com o CloudFormation](#java-tracing-cloudformation)
+ [Interpretar um rastreamento do X-Ray](#java-tracing-interpretation)
+ [Armazenar dependências de runtime em uma camada (SDK do X-Ray)](#java-tracing-layers)
+ [Rastreamento do X-Ray em aplicações de exemplo (SDK do X-Ray)](#java-tracing-samples)

## Uso do Powertools para AWS Lambda (Java) e do AWS SAM para rastreamento
<a name="java-tracing-sam"></a>

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)](https://docs.powertools.aws.dev/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 ou posterior
+ [AWS CLI versão 2](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html)
+ [AWS SAM CLI versão 1.75 ou posterior](https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/serverless-sam-cli-install.html). Se você tiver uma versão mais antiga da CLI do AWS SAM, consulte [Atualizando a CLI do AWS SAM](https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/manage-sam-cli-versions.html#manage-sam-cli-versions-upgrade).

**Implantar uma aplicação de exemplo do AWS SAM**

1. 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
   ```

1. Crie a aplicação.

   ```
   cd sam-app && sam build
   ```

1. Implante o aplicativo.

   ```
   sam deploy --guided
   ```

1. 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`.

1. Obtenha o URL da aplicação implantada:

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

1. Invoque o endpoint da API:

   ```
   curl -X GET <URL_FROM_PREVIOUS_STEP>
   ```

   Se tiver êxito, você verá esta resposta:

   ```
   {"message":"hello world"}
   ```

1. Para obter os rastreamentos da função, execute [sam traces](https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/sam-cli-command-reference-sam-traces.html).

   ```
   sam traces
   ```

   A saída de rastreamento se parece com:

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

1. 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
<a name="java-tracing-cdk"></a>

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)](https://docs.powertools.aws.dev/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 ou posterior
+ [AWS CLI versão 2](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html)
+ [AWS CDK versão 2](https://docs.aws.amazon.com/cdk/v2/guide/getting_started.html#getting_started_prerequisites)
+ [AWS SAM CLI versão 1.75 ou posterior](https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/serverless-sam-cli-install.html). Se você tiver uma versão mais antiga da CLI do AWS SAM, consulte [Atualizando a CLI do AWS SAM](https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/manage-sam-cli-versions.html#manage-sam-cli-versions-upgrade).

**Implantar uma aplicação de exemplo do AWS CDK**

1. Crie um diretório de projeto para sua aplicação.

   ```
   mkdir hello-world
   cd hello-world
   ```

1. Inicialize a aplicação.

   ```
   cdk init app --language java
   ```

1. 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
   ```

1. 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>
   ```

1. 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
   ```

1. 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>
   ```

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

1. 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](https://docs.aws.amazon.com/cdk/api/v1/java/aws_cdk.aws_lambda.html) e o [construtor ApiGatewayv2](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_apigatewayv2-readme.html) 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());
       }
   }
   ```

1. 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>
   ```

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

   ```
   cdk deploy
   ```

1. Obtenha o URL da aplicação implantada:

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

1. Invoque o endpoint da API:

   ```
   curl -X GET <URL_FROM_PREVIOUS_STEP>
   ```

   Se tiver êxito, você verá esta resposta:

   ```
   {"message":"hello world"}
   ```

1. Para obter os rastreamentos da função, execute [sam traces](https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/sam-cli-command-reference-sam-traces.html).

   ```
   sam traces
   ```

   A saída de rastreamento se parece com:

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

1. 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
<a name="java-adot"></a>

O ADOT fornece [camadas](chapter-layers.md) 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](https://aws-otel.github.io/docs/getting-started/lambda#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)](https://aws-otel.github.io/docs/getting-started/lambda/lambda-java-auto-instr), 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](https://aws-otel.github.io/docs/getting-started/lambda/lambda-java), na documentação do ADOT.

## Usar o SDK do X-Ray para instrumentar suas funções Java
<a name="java-xray-sdk"></a>

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.

**Example [build.gradle](https://github.com/awsdocs/aws-lambda-developer-guide/tree/main/sample-apps/s3-java/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
<a name="java-tracing-console"></a>

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

**Para ativar o rastreamento ativo**

1. Abra a [página Funções](https://console.aws.amazon.com/lambda/home#/functions) do console do Lambda.

1. Escolha uma função.

1. Escolha **Configuration** (Configuração) e depois **Monitoring and operations tools** (Ferramentas de monitoramento e operações).

1. Em **Ferramentas de monitoramento adicionais**, selecione **Editar**.

1. Em **CloudWatch Application Signals e AWS X-Ray**, escolha **Habilitar** para **Rastreamentos do serviço Lambda**.

1. Selecione **Salvar**.

## Ativar o rastreamento com a API do Lambda
<a name="java-tracing-api"></a>

Configure o rastreamento na sua função do Lambda com a AWS CLI ou o AWS SDK, usando as seguintes operações de API:
+ [UpdateFunctionConfiguration](https://docs.aws.amazon.com/lambda/latest/api/API_UpdateFunctionConfiguration.html)
+ [GetFunctionConfiguration](https://docs.aws.amazon.com/lambda/latest/api/API_GetFunctionConfiguration.html)
+ [CreateFunction](https://docs.aws.amazon.com/lambda/latest/api/API_CreateFunction.html)

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 CloudFormation
<a name="java-tracing-cloudformation"></a>

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

**Example [function-inline.yml](https://github.com/awsdocs/aws-lambda-developer-guide/blob/master/templates/function-inline.yml): configuração de rastreamento**  

```
Resources:
  function:
    Type: [AWS::Lambda::Function](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-lambda-function.html)
    Properties:
      TracingConfig:
        Mode: Active
      ...
```

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

**Example [template.yml](https://github.com/awsdocs/aws-lambda-developer-guide/tree/main/sample-apps/blank-nodejs/template.yml): configuração de rastreamento**  

```
Resources:
  function:
    Type: [AWS::Serverless::Function](https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/sam-resource-function.html)
    Properties:
      Tracing: Active
      ...
```

## Interpretar um rastreamento do X-Ray
<a name="java-tracing-interpretation"></a>

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](lambda-intro-execution-role.md) da função. Caso contrário, adicione a política [AWSXRayDaemonWriteAccess](https://console.aws.amazon.com/iam/home#/policies/arn:aws:iam::aws:policy/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](https://docs.aws.amazon.com/xray/latest/devguide/aws-xray.html#xray-concepts-servicegraph) 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.

![\[\]](http://docs.aws.amazon.com/pt_br/lambda/latest/dg/images/sample-errorprocessor-servicemap.png)


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:

![\[\]](http://docs.aws.amazon.com/pt_br/lambda/latest/dg/images/xray-servicemap-function.png)


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.

![\[\]](http://docs.aws.amazon.com/pt_br/lambda/latest/dg/images/V2_sandbox_images/my-function-2-v1.png)


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](foundation-progmodel.md). 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](services-xray.md#services-xray-traces).

**nota**  
As funções [Lambda SnapStart](snapstart.md) 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](snapstart-runtime-hooks.md) 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](https://docs.aws.amazon.com/xray/latest/devguide/xray-sdk-java.html) 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](https://aws.amazon.com/xray/pricing/).

## Armazenar dependências de runtime em uma camada (SDK do X-Ray)
<a name="java-tracing-layers"></a>

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](chapter-layers.md).

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

**Example [template.yml](https://github.com/awsdocs/aws-lambda-developer-guide/tree/main/sample-apps/blank-java/template.yml): camada de dependências**  

```
Resources:
  function:
    Type: [AWS::Serverless::Function](https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/sam-resource-function.html)
    Properties:
      CodeUri: build/distributions/blank-java.zip
      Tracing: Active
      Layers:
        - !Ref libs
      ...
  libs:
    Type: [AWS::Serverless::LayerVersion](https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/sam-resource-layerversion.html)
    Properties:
      LayerName: blank-java-lib
      Description: Dependencies for the blank-java sample app.
      ContentUri: build/blank-java-lib.zip
      CompatibleRuntimes:
        - java25
```

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](https://github.com/awsdocs/aws-lambda-developer-guide/tree/main/sample-apps/java-basic) no GitHub.

## Rastreamento do X-Ray em aplicações de exemplo (SDK do X-Ray)
<a name="java-tracing-samples"></a>

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](https://github.com/awsdocs/aws-lambda-developer-guide/tree/main/sample-apps/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](https://github.com/awsdocs/aws-lambda-developer-guide/tree/main/sample-apps/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](https://github.com/awsdocs/aws-lambda-developer-guide/tree/main/sample-apps/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](java-package.md) (3.0.0 e versões mais recentes). Estes exemplos não exigem o AWS SDK como dependência.
+ [s3-java](https://github.com/awsdocs/aws-lambda-developer-guide/tree/main/sample-apps/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](https://github.com/awsdocs/aws-lambda-developer-guide/tree/main/sample-apps/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.