AWS Lambda에서 Java 코드 계측

Lambda는 AWS X-Ray와 통합되어 Lambda 애플리케이션을 추적, 디버깅 및 최적화할 수 있습니다. Lambda 함수와 기타 AWS 서비스를 포함할 수 있는 애플리케이션의 리소스를 탐색할 때 X-Ray를 사용하여 요청을 추적할 수 있습니다.

추적 데이터를 X-Ray로 전송하려면 다음 두 SDK 라이브러리 중 하나를 사용할 수 있습니다.

• AWS OpenTelemetry (ADOT) 용 배포판 — 프로덕션 환경에서 바로 사용할 수 있는 안전한 (OTel) AWS SDK 배포판입니다. OpenTelemetry

• AWS X-Ray SDK for Java — 추적 데이터를 생성하고 X-Ray에 전송하는 SDK입니다.

• Powertools for AWS Lambda(Java) - 서버리스 모범 사례를 구현하고 개발자 속도를 높이기 위한 개발자 도구 키트입니다.

각 SDK는 텔레메트리 데이터를 X-Ray 서비스로 전송하는 방법을 제공합니다. X-Ray를 사용하여 애플리케이션의 성능 지표를 확인하고, 필터링하고, 인사이트를 얻어 문제와 최적화 기회를 식별할 수 있습니다.

중요

X-Ray와 Powertools for AWS Lambda SDK는 AWS에서 제공하는 긴밀하게 통합된 계측 솔루션의 일부입니다. ADOT Lambda Layer는 일반적으로 더 많은 데이터를 수집하는 추적 계측기에 대한 전체 업계 표준의 일부이지만 모든 사용 사례에 적합하지는 않을 수 있습니다. 두 솔루션 중 하나를 사용하여 X-Ray에서 end-to-end 추적을 구현할 수 있습니다. 둘 중 하나를 선택하는 방법에 대해 자세히 알아보려면 AWS Distro for Open Telemetry와 X-Ray SDK 중에서 선택하기를 참조하세요.

추적에 Powertools for AWS Lambda(Java) 및 AWS SAM 사용

다음 단계를 따라 AWS SAM를 사용하는 통합 Powertools for AWS Lambda(Java) 모듈을 사용하여 샘플 Hello World Java 애플리케이션을 다운로드, 빌드 및 배포합니다. 이 애플리케이션은 기본 API 백엔드를 구현하고 Powertools를 사용하여 로그, 지표 및 추적을 내보냅니다. 이 구성에는 Amazon API Gateway 엔드포인트와 Lambda 함수가 포함됩니다. API Gateway 엔드포인트에 GET 요청을 보내면 Lambda 함수는 임베디드 메트릭 형식을 CloudWatch 사용하여 로그와 지표를 호출하고, 에 전송하고, 추적을 전송합니다. AWS X-Ray 이 함수는 hello world 메시지를 반환합니다.

사전 조건

이 섹션의 단계를 완료하려면 다음이 필요합니다.

• Java 11

• AWS CLI 버전 2

• AWS SAM CLI 버전 1.75 이상. 이전 버전의 AWS SAM CLI가 있는 경우 AWS SAM CLI 업그레이드를 참조하세요.

샘플 AWS SAM 애플리케이션 배포

1. Hello World Java 템플릿을 사용하여 애플리케이션을 초기화합니다.

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

2. 앱을 빌드합니다.

   cd sam-app && sam build

3. 앱을 배포합니다.

   sam deploy --guided

4. 화면에 표시되는 프롬프트를 따릅니다. 대화형 환경에서 제공되는 기본 옵션을 수락하려면 Enter을 누릅니다.

   참고

   권한 부여가 정의되어 있지 않을 HelloWorldFunction 수도 있습니다. 괜찮습니까? , 꼭 입력하세요y.

5. 배포된 애플리케이션의 URL을 가져옵니다.

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

6. API 엔드포인트 호출:

   curl -X GET <URL_FROM_PREVIOUS_STEP>

   성공하면 다음과 같은 결과가 응답됩니다.

   {"message":"hello world"}

7. 함수에 대한 트레이스를 가져오려면 sam traces를 실행합니다.

   sam traces

   추적 출력은 다음과 같습니다.

   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

8. 이는 인터넷을 통해 액세스할 수 있는 퍼블릭 API 엔드포인트입니다. 테스트 후에는 엔드포인트를 삭제하는 것이 좋습니다.

   sam delete

추적에 Powertools for AWS Lambda(Java) 및 AWS CDK 사용

다음 단계를 따라 AWS CDK를 사용하는 통합 Powertools for AWS Lambda(Java) 모듈을 사용하여 샘플 Hello World Java 애플리케이션을 다운로드, 빌드 및 배포합니다. 이 애플리케이션은 기본 API 백엔드를 구현하고 Powertools를 사용하여 로그, 지표 및 추적을 내보냅니다. 이 구성에는 Amazon API Gateway 엔드포인트와 Lambda 함수가 포함됩니다. API Gateway 엔드포인트에 GET 요청을 보내면 Lambda 함수는 임베디드 메트릭 형식을 CloudWatch 사용하여 로그와 지표를 호출하고, 에 전송하고, 추적을 전송합니다. AWS X-Ray 함수가 hello world 메시지를 반환합니다.

사전 조건

이 섹션의 단계를 완료하려면 다음이 필요합니다.

• Java 11

• AWS CLI 버전 2

• AWS CDK 버전 2

• AWS SAM CLI 버전 1.75 이상. 이전 버전의 AWS SAM CLI가 있는 경우 AWS SAM CLI 업그레이드를 참조하세요.

샘플 AWS CDK 애플리케이션 배포

1. 새 애플리케이션용 프로젝트 디렉터리를 생성합니다.

   mkdir hello-world
   cd hello-world

2. 앱을 초기화합니다.

   cdk init app --language java

3. 다음 명령을 사용하여 maven 프로젝트를 생성합니다.

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

4. hello-world\app\Function 디렉터리에서 pom.xml을 열고 기존 코드를 Powertools에 대한 종속 구성 요소 및 maven 플러그인을 포함하는 다음 코드로 바꿉니다.

   <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. hello-world\app\src\main\resource 디렉터리를 생성하고 로그 구성에 대한 log4j.xml을 생성합니다.

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

6. log4j.xml을 열고 다음 코드를 추가합니다.

   <?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. hello-world\app\Function\src\main\java\helloworld 디렉터리에서 App.java를 열고 기존 코드를 다음 코드로 바꿉니다. 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. hello-world\src\main\java\com\myorg 디렉터리에서 HelloWorldStack.java를 열고 기존 코드를 다음 코드로 바꿉니다. 이 코드는 Lambda 생성자와 2 생성자를 사용하여 REST API와 ApiGatewayv 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. hello-world 디렉터리에서 pom.xml를 열고 기존 코드를 다음 코드로 바꿉니다.

   <?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. hello-world 디렉터리에 있는지 확인하고 애플리케이션을 배포합니다.

    cdk deploy

11. 배포된 애플리케이션의 URL을 가져옵니다.

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

12. API 엔드포인트 호출:

    curl -X GET <URL_FROM_PREVIOUS_STEP>

    성공하면 다음과 같은 결과가 응답됩니다.

    {"message":"hello world"}

13. 함수에 대한 트레이스를 가져오려면 sam traces를 실행합니다.

    sam traces

    추적 출력은 다음과 같습니다.

    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

14. 이는 인터넷을 통해 액세스할 수 있는 퍼블릭 API 엔드포인트입니다. 테스트 후에는 엔드포인트를 삭제하는 것이 좋습니다.

    cdk destroy

ADOT를 사용하여 Java 함수 계측

ADOT는 OTel SDK를 사용하여 원격 측정 데이터를 수집하는 데 필요한 모든 것을 패키징할 수 있는 완전 관리형 Lambda 계층을 제공합니다. 이 계층을 사용하면 모든 함수 코드를 수정하지 않고도 Lambda 함수를 계측할 수 있습니다. 계층을 구성하여 OTel의 사용자 지정 초기화를 수행할 수도 있습니다. 자세한 내용은 ADOT 설명서의 Lambda에서 ADOT 컬렉터에 대한 사용자 지정 구성을 참조하세요.

Java 런타임의 경우 두 계층 중에서 선택하여 사용할 수 있습니다.

• AWS ADOT Java용 관리형 Lambda 계층(자동 계측 에이전트) - 이 계층은 시작 시 함수 코드를 자동으로 변환하여 추적 데이터를 수집합니다. 이 계층을 ADOT Java 에이전트와 함께 사용하는 방법에 대한 자세한 지침은 ADOT 설명서에서 Java용 OpenTelemetry Lambda 지원 AWS 배포판 (자동 계측 에이전트) 을 참조하십시오.

• AWS ADOT Java용 관리형 Lambda 계층 - 이 계층은 Lambda 함수에 대한 기본 제공 계측도 제공하지만, OTel SDK를 초기화하려면 몇 가지 코드를 직접 변경해야 합니다. 이 계층을 사용하는 방법에 대한 자세한 지침은 ADOT 설명서에서 Java용 OpenTelemetry Lambda용 AWS 배포판 지원을 참조하십시오.

X-Ray SDK를 사용하여 Java 함수 계측

함수가 애플리케이션의 다른 리소스 및 서비스에 대해 수행하는 호출과 관련된 데이터를 기록하려면 Java용 X-Ray SDK를 빌드 구성에 추가합니다. 다음 예에서는 AWS SDK for Java 2.x 클라이언트의 자동 계측을 활성화하는 라이브러리를 포함하는 Gradle 빌드 구성을 보여줍니다.

예 build.gradle – 종속성 추적

dependencies {
    implementation platform('software.amazon.awssdk:bom:2.15.0')
    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-instrumentor'
    ...
}

올바른 종속성을 추가하고 필요한 코드를 변경한 후 Lambda 콘솔 또는 API를 통해 함수의 구성에서 추적을 활성화합니다.

Lambda 콘솔을 사용하여 추적 활성화

콘솔을 사용하여 Lambda 함수에 대한 활성 추적을 전환하려면 다음 단계를 따르십시오.

활성 추적 켜기

1. Lambda 콘솔의 함수 페이지를 엽니다.

2. 함수를 선택합니다.

3. 구성(Configuration)을 선택한 다음 모니터링 및 운영 도구(Monitoring and operations tools)를 선택합니다.

4. 편집을 선택합니다.

5. X-Ray에서 활성 추적을 켭니다.

6. 저장을 선택합니다.

Lambda API를 사용하여 추적 활성화

AWS CLI 또는 AWS SDK를 사용하여 Lambda 함수에 대한 추적을 구성하고 다음 API 작업을 사용합니다.

• UpdateFunctionConfiguration

• GetFunctionConfiguration

• CreateFunction

다음 예제 AWS CLI 명령은 my-function이라는 함수에 대한 활성 추적을 사용 설정합니다.

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

추적 모드는 함수 버전을 게시할 때 버전별 구성의 일부입니다. 게시된 버전에 대한 추적 모드는 변경할 수 없습니다.

AWS CloudFormation을 사용하여 추적 활성화

AWS CloudFormation 템플릿에서 AWS::Lambda::Function 리소스에 대한 추적을 활성화하려면 TracingConfig 속성을 사용합니다.

예 function-inline.yml – 추적 구성

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

AWS Serverless Application Model(AWS SAM) AWS::Serverless::Function 리소스의 경우 Tracing 속성을 사용합니다.

예 template.yml – 추적 구성

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

X-Ray 추적 해석

함수에 추적 데이터를 X-Ray로 업로드할 권한이 있어야 합니다. Lambda 콘솔에서 추적을 활성화하면 Lambda가 필요한 권한을 함수의 실행 역할에 추가합니다. 그렇지 않으면 AWSXRayDaemonWriteAccess정책을 실행 역할에 추가하십시오.

활성 추적을 구성하면 애플리케이션을 통해 특정 요청을 관찰할 수 있습니다. X-Ray 서비스 그래프는 애플리케이션 및 모든 구성 요소에 대한 정보를 보여줍니다. 오류 프로세서 샘플 애플리케이션의 다음 예제는 두 개의 함수가 있는 애플리케이션을 보여줍니다. 기본 함수는 이벤트를 처리하고 때로는 오류를 반환합니다. 맨 위에 있는 두 번째 함수는 첫 번째 로그 그룹에 나타나는 오류를 처리하고 AWS SDK를 사용하여 X-Ray, Amazon Simple Storage Service (Amazon S3), Amazon Logs를 호출합니다. CloudWatch

X-Ray는 애플리케이션에 대한 모든 요청을 추적하지 않습니다. X-Ray는 모든 요청의 대표 샘플을 여전히 제공하면서 추적이 효율적으로 수행되도록 샘플링 알고리즘을 적용합니다. 샘플링 요율은 초당 요청이 1개이며 추가 요청의 5퍼센트입니다.

참고

함수에 대해 X-Ray 샘플링 요율을 구성할 수 없습니다.

활성 추적을 사용할 때 각 추적에 대해 Lambda는 2개의 세그먼트를 기록하고, 이에 따라 서비스 그래프에 2개의 노드가 생성됩니다. 다음 이미지는 오류 프로세서 샘플 애플리케이션에서 기본 함수에 대한 이 두 노드를 강조 표시합니다.

왼쪽의 첫 번째 노드는 호출 요청을 수신하는 Lambda 서비스를 나타냅니다. 두 번째 노드는 특정 Lambda 함수를 나타냅니다. 다음 예에서는 이러한 2개의 세그먼트가 있는 추적을 보여줍니다. 둘 다 이름이 my-function 이지만 하나는 오리진이 AWS::Lambda이고 다른 하나는 오리진이 AWS::Lambda::Function입니다.

이 예에서는 3개의 하위 세그먼트를 표시하도록 함수 세그먼트를 확장합니다.

• 초기화 – 함수를 로드하고 초기화 코드를 실행하는 데 소요된 시간을 나타냅니다. 이 하위 세그먼트는 함수의 각 인스턴스에서 처리하는 첫 번째 이벤트에 대해서만 표시됩니다.

• 호출— 핸들러 코드를 실행하는 데 소요된 시간을 나타냅니다.

• 오버헤드 – Lambda 런타임이 다음 이벤트를 처리하기 위해 준비하는 데 소비하는 시간을 나타냅니다.

참고

람다 SnapStart 함수에는 Restore 하위 세그먼트도 포함됩니다. Restore 하위 세그먼트는 Lambda가 스냅샷을 복원하고, 런타임(JVM)을 로드하고, afterRestore 런타임 후크를 실행하는 데 걸리는 시간을 보여줍니다. 스냅샷 복원 프로세스에는 microVM 외부 작업에 소요되는 시간이 포함될 수 있습니다. 이 시간은 Restore 하위 세그먼트에서 보고됩니다. 스냅샷을 복원하기 위해 microVM 외부에서 소요된 시간에 대한 요금은 부과되지 않습니다.

HTTP 클라이언트를 계측하고, SQL 쿼리를 기록하고, 주석 및 메타데이터가 있는 사용자 지정 하위 세그먼트를 생성할 수도 있습니다. 자세한 내용은 AWS X-Ray 개발자 안내서의 AWS X-Ray SDK for Java을 참조하세요.

요금

X-Ray 추적을 AWS 프리 티어의 일부로서 특정 한도까지 매월 무료로 사용할 수 있습니다. 해당 한도를 초과하면 추적 저장 및 검색에 대한 X-Ray 요금이 부과됩니다. 자세한 내용은 AWS X-Ray 요금을 참조하십시오.

계층에 런타임 종속성 저장(X-Ray SDK)

X-Ray SDK를 사용하여 AWS SDK 클라이언트를 계측하는 경우 함수 코드와 배포 패키지가 상당히 커질 수 있습니다. 함수 코드를 업데이트할 때마다 런타임 종속성을 업로드하지 않으려면 X-Ray SDK를 Lambda 계층에 패키징합니다.

다음 예에서는 AWS SDK for Java 및 Java용 X-Ray SDK를 저장하는 AWS::Serverless::LayerVersion 리소스를 보여줍니다.

예 template.yml – 종속성 계층

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

이 구성을 사용하면 런타임 종속성을 변경하는 경우 라이브러리 계층만 업데이트하면 됩니다. 함수 배포 패키지에는 코드만 포함되어 있으므로 이는 업로드 시간을 줄일 수 있습니다.

종속성 계층을 만들려면 배포 전에 계층 아카이브를 생성하기 위해 빌드 구성을 변경해야 합니다. 실제 예제를 보려면 의 java-basic 샘플 애플리케이션을 참조하십시오. GitHub

샘플 애플리케이션에서 X-Ray 추적(X-Ray SDK)

이 가이드의 GitHub 저장소에는 X-Ray Tracing의 사용을 보여주는 샘플 애플리케이션이 포함되어 있습니다. 각 샘플 애플리케이션에는 간편한 배포 및 정리를 위한 스크립트, AWS SAM 템플릿 및 지원 리소스가 포함되어 있습니다.

Java의 샘플 Lambda 애플리케이션

• java17-examples – Java 레코드를 사용하여 입력 이벤트 데이터 객체를 나타내는 방법을 보여주는 Java 함수입니다.

• java-basic – 단위 테스트 및 변수 로깅 구성을 사용하는 최소한의 Java 함수 모음입니다.

• java - Amazon API Gateway, Amazon SQS 및 Amazon Kinesis와 같은 다양한 서비스의 이벤트를 처리하는 방법에 대한 스켈레톤 코드가 포함된 Java 함수 모음입니다. 이러한 함수는 최신 버전의 aws-lambda-java-events라이브러리 (3.0.0 이상) 를 사용합니다. 이러한 예는 AWS SDK를 종속 항목으로 요구하지 않습니다.

• s3-java – Amazon S3의 알림 이벤트를 처리하고 JCL(Java Class Library)을 사용하여 업로드된 이미지 파일의 썸네일을 생성하는 Java 함수입니다.

• API Gateway를 사용하여 Lambda 함수 호출 — 직원 정보가 포함된 Amazon DynamoDB 테이블을 스캔하는 Java 함수입니다. 이후 Amazon 간편 알림 서비스를 사용하여 직원들에게 근무 기념일을 축하하는 문자 메시지를 보냅니다. 이 예제에서는 API Gateway를 사용하여 함수를 호출합니다.

모든 샘플 애플리케이션은 Lambda 함수에 대해 활성 추적을 사용하도록 설정되어 있습니다. s3-java 애플리케이션은 AWS SDK for Java 2.x 클라이언트의 자동 계측, 테스트를 위한 세그먼트 관리, 사용자 지정 하위 세그먼트 및 런타임 종속성을 저장하기 위한 Lambda 계층의 사용을 보여줍니다.