# AWS Lambda での Java コードの作成
Lambda アプリケーションのトレース、デバッグ、および最適化を行うために、Lambda は AWS X-Ray と統合されています。X-Ray を使用すると、Lambda 関数や他の AWS のサービスが含まれるアプリケーション内で、リソースを横断するリクエストをトレースできます。
トレースされたデータを X-Ray に送信するには、以下の 2 つの SDK ライブラリのいずれかを使用します。
+ [AWS Distro for OpenTelemetry (ADOT)](https://aws.amazon.com/otel) – 安全で、本番環境に対応し、AWS でサポートされている OpenTelemetry (OTel) SDK のディストリビューションです。
+ [AWS X-Ray SDK for Java](https://docs.aws.amazon.com/xray/latest/devguide/xray-sdk-java.html) - トレースデータを生成して X-Ray に送信するための SDK です。
+ [Powertools for AWS Lambda (Java)](https://docs.aws.amazon.com/powertools/java/latest/) - サーバーレスのベストプラクティスを実装し、デベロッパーの作業速度を向上させるためのデベロッパーツールキットです。
各 SDK は、テレメトリデータを X-Ray サービスに送信する方法を提供します。続いて、X-Ray を使用してアプリケーションのパフォーマンスメトリクスの表示やフィルタリングを行い、インサイトを取得することで、問題点や最適化の機会を特定できます。
**重要**
X-Ray および Powertools for AWS Lambda SDK は、AWS が提供する、密接に統合された計測ソリューションの一部です。ADOT Lambda レイヤーは、一般的により多くのデータを収集するトレーシング計測の業界標準の一部ですが、すべてのユースケースに適しているわけではありません。これらのソリューションのいずれかを使用して、X-Ray でエンドツーエンドのトレーシングを実装することができます。選択方法の詳細については、「[Choosing between the AWS Distro for Open Telemetry and X-Ray SDKs](https://docs.aws.amazon.com/xray/latest/devguide/xray-instrumenting-your-app.html#xray-instrumenting-choosing)」( Distro for Open Telemetry または X-Ray SDK の選択) を参照してください。
**Topics**
+ [AWS Lambda (Java) に Powertools の使用、トレースに AWS SAM の使用](#java-tracing-sam)
+ [AWS Lambda (Java) に Powertools の使用、トレースに AWS CDK の使用](#java-tracing-cdk)
+ [Java 関数の計測への ADOT の使用](#java-adot)
+ [Java 関数の計測のための X-Ray SDK の使用](#java-xray-sdk)
+ [Lambda コンソールを使用してトレースを有効化する](#java-tracing-console)
+ [Lambda API でのトレースのアクティブ化](#java-tracing-api)
+ [CloudFormation によるトレースのアクティブ化](#java-tracing-cloudformation)
+ [X-Ray トレースの解釈](#java-tracing-interpretation)
+ [ランタイムの依存関係をレイヤー (X-Ray SDK) に保存する](#java-tracing-layers)
+ [サンプルアプリケーションでの X-Ray トレース (X-Ray SDK)](#java-tracing-samples)
## AWS Lambda (Java) に Powertools の使用、トレースに AWS SAM の使用
以下の手順に従い、AWS SAM を使用する統合された [Powertools for AWS Lambda (Java)](https://docs.powertools.aws.dev/lambda-java) モジュールを備えた Hello World Java アプリケーションのサンプルをダウンロード、構築、デプロイします。このアプリケーションは基本的な API バックエンドを実装し、Powertools を使用してログ、メトリクス、トレースを生成します。Amazon API Gateway エンドポイントと Lambda 関数で構成されています。API Gateway エンドポイントに GET リクエストを送信すると、Lambda 関数は呼び出し、Embedded Metric Format を使用してログおよびメトリクスを CloudWatch に送信、トレースを AWS X-Ray に送信します。関数は `hello world` のメッセージを返します。
**前提条件**
このセクションの手順を完了するには、以下が必要です。
+ Java 11 以降
+ [AWS CLI バージョン 2](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html)
+ 「[AWS SAM CLI バージョン 1.75 以降](https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/serverless-sam-cli-install.html)」 AWS SAM CLI のバージョンが古い場合は、「[AWS SAM CLI のアップグレード](https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/manage-sam-cli-versions.html#manage-sam-cli-versions-upgrade)」を参照してください。
**AWS SAM サンプルアプリケーションをデプロイする**
1. Hello World Java テンプレートを使用してアプリケーションを初期化します。
```
sam init --app-template hello-world-powertools-java --name sam-app --package-type Zip --runtime java11 --no-tracing
```
1. アプリケーションを構築します。
```
cd sam-app && sam build
```
1. アプリケーションをデプロイします。
```
sam deploy --guided
```
1. 画面に表示されるプロンプトに従ってください。インタラクティブな形式で提供されるデフォルトオプションを受け入れるには、`Enter` を押します。
**注記**
**[HelloWorldFunction には権限が定義されていない場合がありますが、問題ありませんか？]** には、必ず `y` を入力してください。
1. デプロイされたアプリケーションの URL を取得します。
```
aws cloudformation describe-stacks --stack-name sam-app --query 'Stacks[0].Outputs[?OutputKey==`HelloWorldApi`].OutputValue' --output text
```
1. API エンドポイントを呼び出します。
```
curl -X GET
```
成功すると、次のレスポンスが表示されます。
```
{"message":"hello world"}
```
1. 関数のトレースを取得するには、[sam traces](https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/sam-cli-command-reference-sam-traces.html) を実行します。
```
sam traces
```
トレース出力は次のようになります。
```
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. これは、インターネット経由でアクセス可能なパブリック API エンドポイントです。テスト後にエンドポイントを削除することを推奨します。
```
sam delete
```
## AWS Lambda (Java) に Powertools の使用、トレースに AWS CDK の使用
以下の手順に従い、AWS CDK を使用する統合された [Powertools for AWS Lambda (Java)](https://docs.powertools.aws.dev/lambda-java) モジュールを備えた Hello World Java アプリケーションのサンプルをダウンロード、構築、デプロイします。このアプリケーションは基本的な API バックエンドを実装し、Powertools を使用してログ、メトリクス、トレースを生成します。Amazon API Gateway エンドポイントと Lambda 関数で構成されています。API Gateway エンドポイントに GET リクエストを送信すると、Lambda 関数は呼び出し、Embedded Metric Format を使用してログおよびメトリクスを CloudWatch に送信、トレースを AWS X-Ray に送信します。関数は「hello world」メッセージを返します。
**前提条件**
このセクションの手順を完了するには、以下が必要です。
+ Java 11 以降
+ [AWS CLI バージョン 2](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html)
+ [AWS CDK バージョン 2](https://docs.aws.amazon.com/cdk/v2/guide/getting_started.html#getting_started_prerequisites)
+ 「[AWS SAM CLI バージョン 1.75 以降](https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/serverless-sam-cli-install.html)」 AWS SAM CLI のバージョンが古い場合は、「[AWS SAM CLI のアップグレード](https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/manage-sam-cli-versions.html#manage-sam-cli-versions-upgrade)」を参照してください。
**AWS CDK サンプルアプリケーションをデプロイする**
1. 新しいアプリケーション用のプロジェクトディレクトリを作成します。
```
mkdir hello-world
cd hello-world
```
1. アプリケーションを初期化します。
```
cdk init app --language java
```
1. 次のコマンドを備えた Maven プロジェクトを作成します。
```
mkdir app
cd app
mvn archetype:generate -DgroupId=helloworld -DartifactId=Function -DarchetypeArtifactId=maven-archetype-quickstart -DinteractiveMode=false
```
1. `hello-world\app\Function` ディレクトリで `pom.xml` を開き、既存のコードを、Powertools の依存関係および Maven プラグインを含む次のコードで置き換えます。
```
4.0.0
helloworld
Function
jar
1.0-SNAPSHOT
Function
http://maven.apache.org
11
11
2.17.2
junit
junit
3.8.1
test
software.amazon.lambda
powertools-tracing
1.3.0
software.amazon.lambda
powertools-metrics
1.3.0
software.amazon.lambda
powertools-logging
1.3.0
com.amazonaws
aws-lambda-java-core
1.2.2
com.amazonaws
aws-lambda-java-events
3.11.1
org.codehaus.mojo
aspectj-maven-plugin
1.14.0
${maven.compiler.source}
${maven.compiler.target}
${maven.compiler.target}
software.amazon.lambda
powertools-tracing
software.amazon.lambda
powertools-metrics
software.amazon.lambda
powertools-logging
compile
org.apache.maven.plugins
maven-shade-plugin
3.4.1
package
shade
false
function
com.github.edwgiz
maven-shade-plugin.log4j2-cachefile-transformer
2.15
```
1. `hello-world\app\src\main\resource` ディレクトリを作成し、ログ設定に `log4j.xml` を作成します。
```
mkdir -p src/main/resource
cd src/main/resource
touch log4j.xml
```
1. `log4j.xml` を開いて次のコード追加します。
```
```
1. `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 {
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 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. `hello-world\src\main\java\com\myorg` ディレクトリから `HelloWorldStack.java` を開き、既存コードを次のコードで置き換えます。このコードは、「[Lambda Constructor](https://docs.aws.amazon.com/cdk/api/v1/java/aws_cdk.aws_lambda.html)」および「[Apigatewayv2 Constructor](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_apigatewayv2-readme.html)」を使用して REST API および 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 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. `hello-world` ディレクトリから `pom.xml` を開き、既存コードを次のコードで置き換えます。
```
4.0.0
com.myorg
hello-world
0.1
UTF-8
2.70.0
[10.0.0,11.0.0)
5.7.1
org.apache.maven.plugins
maven-compiler-plugin
3.8.1
1.8
1.8
org.codehaus.mojo
exec-maven-plugin
3.0.0
com.myorg.HelloWorldApp
software.amazon.awscdk
aws-cdk-lib
${cdk.version}
software.constructs
constructs
${constructs.version}
org.junit.jupiter
junit-jupiter
${junit.version}
test
software.amazon.awscdk
apigatewayv2-alpha
${cdk.version}-alpha.0
software.amazon.awscdk
apigatewayv2-integrations-alpha
${cdk.version}-alpha.0
```
1. `hello-world` ディレクトリ内に移動していることを確認し、アプリケーションをデプロイしてください。
```
cdk deploy
```
1. デプロイされたアプリケーションの URL を取得します。
```
aws cloudformation describe-stacks --stack-name HelloWorldStack --query 'Stacks[0].Outputs[?OutputKey==`HttpApi`].OutputValue' --output text
```
1. API エンドポイントを呼び出します。
```
curl -X GET
```
成功すると、次のレスポンスが表示されます。
```
{"message":"hello world"}
```
1. 関数のトレースを取得するには、[sam traces](https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/sam-cli-command-reference-sam-traces.html) を実行します。
```
sam traces
```
トレース出力は次のようになります。
```
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. これは、インターネット経由でアクセス可能なパブリック API エンドポイントです。テスト後にエンドポイントを削除することを推奨します。
```
cdk destroy
```
## Java 関数の計測への ADOT の使用
ADOT は、Otel SDK を使用してテレメトリデータを収集するために必要なすべてをパッケージ化した、フルマネージド型の Lambda [レイヤー](chapter-layers.md)を提供します。このレイヤーを使用すると、関数コードを変更する必要はなしで、Lambda 関数を計測できます。また、このレイヤーは、OTel でのカスタムな初期化を実行するように構成することもできます。詳細については、ADOT のドキュメントの「[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)」(Lambda 上での ADOT Collector のカスタム設定) 参照してください。
Java ランタイムの場合、使用するレイヤーを以下の 2 つの中から選択できます。
+ **AWS ADOT Java 向けのマネージド Lambda レイヤー (自動計測エージェント)** – このレイヤーは、起動時に関数コードを自動的に変換し、トレーシングデータを収集できるようにします。このレイヤーを ADOT Java エージェントとともに使用する方法の詳細については、「ADOT ドキュメント」の「[AWS Distro for OpenTelemetry Lambda Support for Java (Auto-instrumentation Agent)](https://aws-otel.github.io/docs/getting-started/lambda/lambda-java-auto-instr)」を参照してください。
+ **ADOT Java 用の AWS マネージド型 Lambda レイヤー** – このレイヤーによっても、Lambda 関数の組み込み型の計測機能が提供されます。ただし、OTel SDK を初期化するために、手動によるコード変更がいくつか必要となります。このレイヤーを使用する方法の詳細については、「ADOT ドキュメント」の「[AWS Distro for OpenTelemetry Lambda Support for Java](https://aws-otel.github.io/docs/getting-started/lambda/lambda-java)」を参照してください。
## Java 関数の計測のための X-Ray SDK の使用
関数が、アプリケーション内で他のリソースやサービスに対して行う呼び出しのデータを記録するには、X-Ray SDK for Java をビルド設定に追加します。以下に、AWS SDK for Java 2.x クライアントの自動計測をアクティブ化するライブラリを含む Gradle ビルド設定の例を示します。
**Example [build.gradle](https://github.com/awsdocs/aws-lambda-developer-guide/tree/main/sample-apps/s3-java/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 コンソールの [[関数ページ]](https://console.aws.amazon.com/lambda/home#/functions) を開きます。
1. 関数を選択します。
1. **[設定]** を選択してから、**[モニタリングおよび運用ツール]** を選択します。
1. **[その他の監視ツール]** で、**[編集]** を選択します。
1. **[CloudWatch Application Signals と AWS X-Ray]** で、**[Lambda サービストレース]** の **[有効]** を選択します。
1. **[保存]** を選択します。
## Lambda API でのトレースのアクティブ化
AWS CLI または AWS SDK で Lambda 関数のトレースを設定するには、次の 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)
以下の例の AWS CLI コマンドは、**my-function** という名前の関数に対するアクティブトレースを有効にします。
```
aws lambda update-function-configuration --function-name my-function \
--tracing-config Mode=Active
```
トレースモードは、関数のバージョンを公開するときのバージョン固有の設定の一部です。公開後のバージョンのトレースモードを変更することはできません。
## CloudFormation によるトレースのアクティブ化
CloudFormation テンプレート内で `AWS::Lambda::Function` リソースに対するアクティブトレースを有効化するには、`TracingConfig` プロパティを使用します。
**Example [function-inline.yml](https://github.com/awsdocs/aws-lambda-developer-guide/blob/master/templates/function-inline.yml) － トレース設定**
```
Resources:
function:
Type: [AWS::Lambda::Function](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-lambda-function.html)
Properties:
TracingConfig:
Mode: Active
...
```
AWS Serverless Application Model (AWS SAM) `AWS::Serverless::Function` リソースに、`Tracing` プロパティを使用します。
**Example [template.yml](https://github.com/awsdocs/aws-lambda-developer-guide/tree/main/sample-apps/blank-nodejs/template.yml) － トレース設定**
```
Resources:
function:
Type: [AWS::Serverless::Function](https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/sam-resource-function.html)
Properties:
Tracing: Active
...
```
## X-Ray トレースの解釈
関数には、トレースデータを X-Ray にアップロードするためのアクセス許可が必要です。Lambda コンソールでトレースを有効にすると、Lambda は必要な権限を関数の [[実行ロール]](lambda-intro-execution-role.md) に追加します。それ以外の場合は、[AWSXRayDaemonWriteAccess](https://console.aws.amazon.com/iam/home#/policies/arn:aws:iam::aws:policy/AWSXRayDaemonWriteAccess) ポリシーを実行ロールに追加します。
アクティブトレースの設定後は、アプリケーションを通じて特定のリクエストの観測が行えるようになります。[[X-Ray サービスグラフ]](https://docs.aws.amazon.com/xray/latest/devguide/aws-xray.html#xray-concepts-servicegraph) には、アプリケーションとそのすべてのコンポーネントに関する情報が表示されます。次の例は、2 つの関数を持つアプリケーションを示しています。プライマリ関数はイベントを処理し、エラーを返す場合があります。上位 2 番目の関数は、最初のロググループに表示されるエラーを処理し、AWS SDK を使用して X-Ray、Amazon Simple Storage Service (Amazon S3)、および Amazon CloudWatch Logs を呼び出します。
![\[\]](http://docs.aws.amazon.com/ja_jp/lambda/latest/dg/images/sample-errorprocessor-servicemap.png)
X-Ray は、アプリケーションへのすべてのリクエストをトレースするわけではありません。X-Ray は、サンプリングアルゴリズムを適用することで効率的なトレースを行うと同時に、すべてのリクエストについての代表的なサンプルを示します。サンプルレートは 1 秒あたり 1 回のリクエストで、追加リクエストの 5％ です。関数の X-Ray サンプルレートを設定することはできません。
X-Ray では、*トレース*は 1 つ以上の*サービス*によって処理されるリクエストに関する情報を記録します。Lambda はトレースごとに 2 つのセグメントを記録します。これにより、サービスグラフに 2 つのノードが作成されます。次の図は、これら 2 つのノードを強調表示しています。
![\[\]](http://docs.aws.amazon.com/ja_jp/lambda/latest/dg/images/xray-servicemap-function.png)
左に示された 1 つめのノードは、呼び出しリクエストを受信する Lambda サービスを表しています。2 つめのノードは、特定の Lambda 関数を表しています。次の例は、これら 2 つのセグメントを使用したトレースを示しています。いずれも **my-function** と名付けられていますが、1 つは `AWS::Lambda` の起点があり、もう 1 つは `AWS::Lambda::Function` の起点があります。`AWS::Lambda` セグメントにエラーが表示される場合は、Lambda サービスに問題があります。`AWS::Lambda::Function` セグメントにエラーが表示される場合、関数に問題があります。
![\[\]](http://docs.aws.amazon.com/ja_jp/lambda/latest/dg/images/V2_sandbox_images/my-function-2-v1.png)
この例では、`AWS::Lambda::Function` セグメントを展開して、それの 3 つのサブセグメントが表示されています。
**注記**
AWS は現在、Lambda サービスに変更を実装しています。これらの変更により、AWS アカウント のさまざまな Lambda 関数によって出力されるシステムログメッセージとトレースセグメントの構造と内容にわずかな違いが生じる場合があります。
ここで示すトレースの例は、古いスタイルの関数セグメントを示しています。古いスタイルのセグメントと新しいスタイルのセグメントの違いについては、次の段落で説明します。
これらの変更は今後数週間に実装され、中国および GovCloud リージョンを除くすべての AWS リージョンのすべての関数は、新しい形式のログメッセージとトレースセグメントを使用するように移行されます。
古いスタイルの関数セグメントには、次のサブセグメントが含まれます。
+ **初期化** － 関数のロードと[初期化コード](foundation-progmodel.md)の実行に要した時間を表します。このサブセグメントは、関数の各インスタンスが処理する最初のイベントに対してのみ表示されます。
+ **[呼び出し]** - ハンドラーコードの実行に要した時間を表します。
+ **[オーバーヘッド]** - Lambda ランタイムが次のイベントを処理するための準備に要する時間を表します。
新しいスタイルの関数セグメントには `Invocation` サブセグメントが含まれていません。代わりに、顧客サブセグメントが関数セグメントに直接アタッチされます。古いスタイルの関数セグメントと新しいスタイルの関数セグメントの構造の詳細については、「」を参照してください[X-Ray トレースを理解する](services-xray.md#services-xray-traces)。
**注記**
[Lambda SnapStart](snapstart.md) 関数には `Restore` サブセグメントも含まれます。`Restore` サブセグメントは、Lambda がスナップショットを復元し、ランタイムをロードして、復元後の[ランタイムフック](snapstart-runtime-hooks.md)を実行するのにかかる時間を表しています。スナップショットを復元するプロセスには、MicroVM 外部でのアクティビティに費やす時間が含まれる場合があります。この時間は、`Restore` サブセグメントで報告されます。MicroVM 外部でスナップショットの復元に費やした時間については課金されません。
HTTP クライアントをインストルメント化し、SQL クエリを記録して、注釈とメタデータからカスタムサブセグメントを作成することもできます。詳細については、「*AWS X-Ray デベロッパーガイド*」の 「[AWS X-Ray SDK for Java](https://docs.aws.amazon.com/xray/latest/devguide/xray-sdk-java.html)」を参照してください。
**料金**
X-Ray トレースは、毎月、AWS 無料利用枠で設定された一定限度まで無料で利用できます。X-Ray の利用がこの上限を超えた場合は、トレースによる保存と取得に対する料金が発生します。詳細については、「[AWS X-Ray 料金表](https://aws.amazon.com/xray/pricing/)」を参照してください。
## ランタイムの依存関係をレイヤー (X-Ray SDK) に保存する
X-Ray SDK を使用して AWS SDK クライアントを関数コードに埋め込むと、デプロイパッケージが巨大になる可能性があります。機能コードを更新するたびに実行時の依存関係がアップロードされないようにするには、X-Ray SDK を [[Lambda layer]](chapter-layers.md) (Lambda レイヤー) にパッケージ化します。
以下の例では、AWS SDK for Java および X-Ray SDK for Java を保存する `AWS::Serverless::LayerVersion` リソースを示しています。
**Example [template.yml](https://github.com/awsdocs/aws-lambda-developer-guide/tree/main/sample-apps/blank-java/template.yml) － 依存関係レイヤー**
```
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
```
この設定では、ランタイム依存関係を変更した場合にのみ、ライブラリレイヤーの更新が必要です。関数のデプロイパッケージにはユーザーのコードのみが含まれるため、アップロード時間を短縮できます。
依存関係のレイヤーを作成するには、デプロイ前にレイヤーアーカイブを生成するようにビルド設定を変更する必要があります。実際の例については、GitHub のサンプルアプリケーション、[java-basic](https://github.com/awsdocs/aws-lambda-developer-guide/tree/main/sample-apps/java-basic) を参照してください。
## サンプルアプリケーションでの X-Ray トレース (X-Ray SDK)
このガイドで参照する GitHub リポジトリには、X-Ray トレースの使用方法を示すサンプルアプリケーションが含まれています。各サンプルアプリケーションには、簡易のデプロイとクリーンアップ用のスクリプト、AWS SAM テンプレート、サポートリソースが含まれています。
**Java のサンプル Lambda アプリケーション**
+ [example-java](https://github.com/awsdocs/aws-lambda-developer-guide/tree/main/sample-apps/example-java) – Lambda を使用して注文処理を行う Java 関数。この関数は、カスタム入力イベントオブジェクトの定義と逆シリアル化、 AWS SDK の使用方法、および出力ログ記録の方法を示しています。
+ [java-basic](https://github.com/awsdocs/aws-lambda-developer-guide/tree/main/sample-apps/java-basic) - 単位テストと変数ログ記録設定を使用する、最小限の Java 関数のコレクション。
+ [java-events](https://github.com/awsdocs/aws-lambda-developer-guide/tree/main/sample-apps/java-events) - Amazon API Gateway、Amazon SQS、Amazon Kinesis などのさまざまなサービスからのイベントを処理する方法のスケルトンコードを含む Java 関数のコレクション。これらの関数は、最新バージョンの [aws-lambda-java-events](java-package.md) ライブラリ (3.0.0 以降) を使用します。これらの例では、依存関係としての AWS SDK が不要です。
+ [s3-java](https://github.com/awsdocs/aws-lambda-developer-guide/tree/main/sample-apps/s3-java) － Amazon S3 からの通知イベントを処理し、Java Class Library (JCL) を使用して、アップロードされたイメージファイルからサムネイルを作成する Java 関数。
+ [layer-java](https://github.com/awsdocs/aws-lambda-developer-guide/tree/main/sample-apps/layer-java) – Lambda レイヤーを使用して、コアとなる関数コードから分離して依存関係をパッケージ化する方法を示す Java 関数。
すべてのサンプルアプリケーションでは、Lambda 関数に対するアクティブトレースが有効になっています。例えば、`s3-java` アプリケーションは、AWS SDK for Java 2.x クライアントの自動インストルメンテーション、テストのセグメント管理、カスタムのサブセグメント、Lambda レイヤーによるラインタイムの依存関係の保存を示しています。