在中檢測 Java 程式碼 AWS Lambda - AWS Lambda
使用動力工具 AWS Lambda （Java）和跟 AWS SAM 踪使用動力工具 AWS Lambda （Java）和跟 AWS CDK 踪用ADOT來檢測您的 Java 函數使用 X-Ray SDK 檢測您的 Java 函數透過 Lambda 主控台來啟用追蹤使用 Lambda 啟用追蹤 API使用啟動追蹤 AWS CloudFormation解讀 X-Ray 追蹤在圖層中存儲運行時依賴關係（X-RaySDK）樣本應用中的 X-Ray 追蹤 (X-RaySDK)

本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

在中檢測 Java 程式碼 AWS Lambda

Lambda 與 AWS X-Ray 整合，可協助您追蹤、偵錯和最佳化 Lambda 應用程式。您可以使用 X-Ray 來追蹤請求，因為它會周遊您應用程式中的資源，其中可能包含 Lambda 函數和其他 AWS 服務。

若要將追蹤資料傳送至 X-Ray，您可以使用以下兩個資SDK源庫之一：

將遙測資料傳送至 X-Ray 服務的每一種方式。SDKs然後，您可以使用 X-Ray 來檢視、篩選應用程式的效能指標並獲得洞察，從而識別問題和進行最佳化的機會。

重要

X-Ray 和 Powertools AWS Lambda SDKs 是由 AWS提供的緊密集成的儀器解決方案的一部分。ADOTLambda 層是業界範圍內追蹤儀器標準的一部分，一般會收集更多資料，但可能不適用於所有使用案例。您可以使用任一解決方案在 X-Ray 中實作 end-to-end 追蹤。要了解有關在它們之間進行選擇的更多信息，請參閱選擇開放遙測發行 AWS 版和 X-Ray SDKs。

使用動力工具 AWS Lambda （Java）和跟 AWS SAM 踪

請按照下面的步驟下載，構建和部署一個示例你好世界 Java 應用程序與集成的 Powertools AWS Lambda （Java）模塊使用 AWS SAM. 此應用程序實現了基本的API後端，並使用 Powertools 發出日誌，指標和跟踪。它由一個 Amazon API 網關端點和一個 Lambda 函數組成。當您將GET請求傳送至API閘道端點時，Lambda 函數會呼叫、使用內嵌指標格式將記錄和指標傳送至 CloudWatch，並將追蹤傳送至 AWS X-Ray。該函數會傳回 hello world 訊息。

必要條件

若要完成本節中的步驟，您必須執行下列各項：

部署範例 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 追蹤。

    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

使用動力工具 AWS Lambda （Java）和跟 AWS CDK 踪

請按照下面的步驟下載，構建和部署一個示例你好世界 Java 應用程序與集成的 Powertools AWS Lambda （Java）模塊使用 AWS CDK. 此應用程序實現了基本的API後端，並使用 Powertools 發出日誌，指標和跟踪。它由一個 Amazon API 網關端點和一個 Lambda 函數組成。當您將GET請求傳送至API閘道端點時，Lambda 函數會呼叫、使用內嵌指標格式將記錄和指標傳送至 CloudWatch，並將追蹤傳送至 AWS X-Ray。函數會傳回 hello world 訊息。

必要條件

若要完成本節中的步驟，您必須執行下列各項：

部署範例 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 建構函式和 ApiGatewayv2 個建構函式來建立RESTAPI和 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 追蹤。

    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提供完全受管的 Lambda 層，可封裝使用 OTelSDK. 透過取用此層，您可以檢測 Lambda 函數，而無需修改任何函數程式碼。您還可以配置圖層以執行的自定義初始化OTel。如需詳細資訊，請參閱ADOT文件中的 Lambda 上ADOT收集器的自訂組態。

對於 Java 執行時間，您可以選擇要取用的兩層：

使用 X-Ray SDK 檢測您的 Java 函數

要記錄有關函數SDK對應用程序中其他資源和服務進行的調用的數據，可以將 X-Ray to Java 添加到構建配置中。下面的示例顯示了一個 Gradle 構建配置，其中包括激活 AWS SDK for Java 2.x 客戶端自動檢測的庫。

範例 build.gradle - 追蹤相依性
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'
    ...
}

新增正確的相依性並進行必要的程式碼變更後，請透過 Lambda 主控台或API.

透過 Lambda 主控台來啟用追蹤

若要使用控制台在 Lambda 函數上切換主動追蹤，請按照下列步驟操作：

開啟主動追蹤

  1. 開啟 Lambda 主控台中的 函數頁面。

  2. 選擇一個函數。

  3. 選擇 組態 ，然後選擇 監控和操作工具 。

  4. 選擇 編輯 。

  5. 在 X-Ray 下，打開 主動追蹤 。

  6. 選擇 Save (儲存)。

使用 Lambda 啟用追蹤 API

使用 AWS CLI 或設定 Lambda 函數的追蹤 AWS SDK，請使用下列API作業：

下列範例 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 簡單存儲服務（Amazon S3）和亞馬遜 CloudWatch 日誌。

在 X-Ray 中顯示兩個單獨的應用程式，及其各自服務映射的圖表

X-Ray 無法追蹤應用程式的所有請求。X-Ray 會套用取樣演算法以確保追蹤的效率，同時仍提供所有請求的代表範本。取樣率為每秒 1 次請求和 5% 的額外請求。您無法為您的功能配置 X-Ray 採樣率。

在 X-Ray 中，追蹤會記錄一或多個服務所處理之要求的相關資訊。Lambda 會記錄每個追蹤 2 個區段，在服務圖表上建立兩個節點。下列影像會強調顯示這兩個節點：

具有單一函數的 X-Ray 服務映射。

左側第一個節點代表接收調用請求的 Lambda 服務。第二個節點代表您特定的 Lambda 函數。下列範例顯示了具有這 2 個區段的追蹤。兩者都被命名為我的函數，但一個具有的起源AWS::Lambda，另一個具有的AWS::Lambda::Function起源。如果AWS::Lambda區段顯示錯誤，表示 Lambda 服務發生問題。如果AWS::Lambda::Function區段顯示錯誤，表示您的函數發生問題。

顯示特定 Lambda 調用每個子區段延遲的 X-Ray 追蹤。

此範例會展開區AWS::Lambda::Function段以顯示其三個子區段。

注意

AWS 目前正在對 Lambda 服務實作變更。由於這些變更，您可能會看到系統記錄訊息的結構和內容，以及. AWS 帳戶

此處顯示的示例跟踪說明了舊式函數段。以下段落說明舊樣式和新樣式區段之間的差異。

這些變更將在未來幾週內實施，除了中國和 GovCloud 地區以 AWS 區域 外的所有功能都將轉換為使用新格式的日誌訊息和追蹤區段。

舊式函數段包含以下子段：

  • 初始化 - 表示載入函數和執行初始化程式碼所花費的時間。只有函數的每個執行個體所處理的第一個事件會顯示此子區段。

  • 調用 – 表示執行處理常式程式碼所花費的時間。

  • 額外負荷 - 表示 Lambda 執行期為做好準備以處理下一個事件所花費的時間。

新樣式的函數段不包含Invocation子段。相反，客戶子段直接附加到功能段。如需舊式和新型式函數區段結構的詳細資訊，請參閱了解 X-Ray 追蹤。

注意

Lambda SnapStart 函數還包括一個 Restore 子區段。Restore子區段顯示 Lambda 還原快照、載入執行階段 (JVM) 以及執行任何afterRestore執行階段掛接所需的時間。還原快照的程序可能包括在 MicroVM 以外的活動上花費的時間。此時間在 Restore 子區段中報告。您不需要為在 MicroVM 外還原快照所花費的時間付費。

您也可以檢測用HTTP戶端、記錄SQL查詢，以及使用註釋和中繼資料建立自訂子區段。如需詳細資訊，請參閱《AWS X-Ray 開發人員指南》中的 適用於 JAVA 的 AWS X-Ray SDK。

定價

作為免費方案的一部分，您可以每月免費使用 X-Ray 追蹤，最多達到一定限制。 AWS 達到閾值後，X-Ray 會收取追蹤儲存及擷取的費用。如需詳細資訊，請參閱 AWS X-Ray 定價。

在圖層中存儲運行時依賴關係（X-RaySDK）

如果您使用 X-Ray 檢SDK測 AWS SDK客戶端的功能代碼，則您的部署包可能會變得相當大。若要避免每次更新函數程式碼時都上傳執行階段相依性，請將 X-Ray 封裝SDK在 Lambda 層中。

下列範例顯示儲存 Java AWS SDK for 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 基本範例應用程式。 GitHub

樣本應用中的 X-Ray 追蹤 (X-RaySDK)

本指南的 GitHub 儲存庫包含示範如何使用 X-Ray 追蹤的範例應用程式。每個範例應用程式都包含可輕鬆部署和清理的指令碼、 AWS SAM 範本和支援資源。

以 Java 編寫的範例 Lambda 應用程式

  • java17-examples – 一個 Java 函數，示範如何使用 Java 記錄來表示輸入事件資料物件。

  • java-basic - 具有單元測試和變數日誌組態的最小 Java 函數集合。

  • java 事件 — Java 函數的集合，其中包含如何處理來自各種服務（例如 Amazon API 網關，Amazon 和亞馬 Amazon Kinesis）的事件的骨架代碼。SQS這些函數使用最新版本的aws-lambda-java-events庫（3.0.0 及更新版本）。這些範例不需要做 AWS SDK為相依性。

  • s3-java — 一種 Java 函數，可處理來自 Amazon S3 的通知事件，並使用 Java 類別程式庫 (JCL) 從上傳的影像檔建立縮圖。

  • 使用API閘道來叫用 Lambda 函數 — 一種 Java 函數，可掃描包含員工資訊的 Amazon DynamoDB 表格。然後，其會使用 Amazon Simple Notification Service 向員工傳送文字訊息，慶祝他們的工作週年紀念日。此範例使用API閘道來呼叫函數。

所有範例應用程式都已啟用 Lambda 函數的主動追蹤功能。例如，s3-java應用程式會顯示用 AWS SDK for Java 2.x 戶端的自動檢測、測試的區段管理、自訂子區段，以及使用 Lambda 層來儲存執行階段相依性。