トレーシングに Powertools for AWS Lambda (.NET) と AWS SAM を使用する X-Ray SDK を使用して .NET 関数を計装する Lambda コンソールを使用してトレースを有効化する Lambda API でのトレースのアクティブ化 AWS CloudFormation によるトレースのアクティブ化 X-Ray トレースの解釈

AWS Lambda での C# コードの作成

Lambda アプリケーションのトレース、デバッグ、最適化を行うために、Lambda は AWS X-Ray と統合されています。X-Ray を使用すると、Lambda 関数や他の AWS のサービスが含まれるアプリケーション内で、リソースを横断するリクエストをトレースできます。

トレーシングデータを X-Ray に送信するには、以下に表示された 3 つの SDK ライブラリのいずれかを使用できます。

AWS Distro for OpenTelemetry (ADOT) – 安全で本番環境に対応し、AWS でサポートされている OpenTelemetry (OTel) SDK のディストリビューションです。
AWS X-Ray SDK for .NET - トレースデータを生成して X-Ray に送信するための SDK です。
Powertools for AWS Lambda (.NET) — サーバーレスのベストプラクティスを実装し、開発者の作業速度を向上させるための開発者ツールキットです。

各 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」( Distro for Open Telemetry または X-Ray SDK の選択) を参照してください。

セクション

トレーシングに Powertools for AWS Lambda (.NET) と AWS SAM を使用する
X-Ray SDK を使用して .NET 関数を計装する
Lambda コンソールを使用してトレースを有効化する
Lambda API でのトレースのアクティブ化
AWS CloudFormation によるトレースのアクティブ化
X-Ray トレースの解釈

トレーシングに Powertools for AWS Lambda (.NET) と AWS SAM を使用する

以下の手順に従い、AWS SAM を使用する統合済み Powertools for AWS Lambda (.NET) モジュールを使用して、Hello World C# アプリケーションのサンプルをダウンロード、構築、デプロイします。このアプリケーションは基本的な API バックエンドを実装し、Powertools を使用してログ、メトリクス、トレースを生成します。Amazon API Gateway エンドポイントと Lambda 関数で構成されています。API Gateway エンドポイントに GET リクエストを送信すると、Lambda 関数は呼び出し、Embedded Metric Format を使用してログおよびメトリクスを CloudWatch に送信、トレースを AWS X-Ray に送信します。関数は「hello world」メッセージを返します。

前提条件

このセクションの手順を完了するには、以下が必要です。

.NET 6 または .NET 8
AWS CLI バージョン 2
「AWS SAM CLI バージョン 1.75 以降」 AWS SAM CLI のバージョンが古い場合は、「AWS SAM CLI のアップグレード」を参照してください。

AWS SAM サンプルアプリケーションをデプロイする

Hello World TypeScript テンプレートを使用して、アプリケーションを初期化します。


sam init --app-template hello-world-powertools-dotnet --name sam-app --package-type Zip --runtime dotnet6 --no-tracing

アプリケーションを構築します。
```
cd sam-app && sam build
```
アプリケーションをデプロイします。
```
sam deploy --guided
```
画面に表示されるプロンプトに従ってください。インタラクティブな形式で提供されるデフォルトオプションを受け入れるには、Enter を押します。

注記
[HelloWorldFunction には権限が定義されていない場合がありますが、問題ありませんか？] には、必ず y を入力してください。

デプロイされたアプリケーションの URL を取得します。


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

API エンドポイントを呼び出します。
```
curl <URL_FROM_PREVIOUS_STEP>
```
成功すると、次のレスポンスが表示されます。
```
{"message":"hello world"}
```

関数のトレースを取得するには、sam traces を実行します。


sam traces

トレース出力は次のようになります。


New XRay Service Graph
  Start time: 2023-02-20 23:05:16+08:00
  End time: 2023-02-20 23:05:16+08:00
  Reference Id: 0 - AWS::Lambda - sam-app-HelloWorldFunction-pNjujb7mEoew - Edges: [1]
   Summary_statistics:
     - total requests: 1
     - ok count(2XX): 1
     - error count(4XX): 0
     - fault count(5XX): 0
     - total response time: 2.814
  Reference Id: 1 - AWS::Lambda::Function - sam-app-HelloWorldFunction-pNjujb7mEoew - Edges: []
   Summary_statistics:
     - total requests: 1
     - ok count(2XX): 1
     - error count(4XX): 0
     - fault count(5XX): 0
     - total response time: 2.429
  Reference Id: 2 - (Root) AWS::ApiGateway::Stage - sam-app/Prod - Edges: [0]
   Summary_statistics:
     - total requests: 1
     - ok count(2XX): 1
     - error count(4XX): 0
     - fault count(5XX): 0
     - total response time: 2.839
  Reference Id: 3 - client - sam-app/Prod - Edges: [2]
   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-20T23:05:16.521000) with id (1-63f38c2c-270200bf1d292a442c8e8a00) and duration (2.877s)
 - 2.839s - sam-app/Prod [HTTP: 200]
   - 2.836s - Lambda [HTTP: 200]
 - 2.814s - sam-app-HelloWorldFunction-pNjujb7mEoew [HTTP: 200]
 - 2.429s - sam-app-HelloWorldFunction-pNjujb7mEoew
   - 0.230s - Initialization
   - 2.389s - Invocation
     - 0.600s - ## FunctionHandler
       - 0.517s - Get Calling IP
   - 0.039s - Overhead

これは、インターネット経由でアクセス可能なパブリック API エンドポイントです。テスト後にエンドポイントを削除することを推奨します。
```
sam delete
```

X-Ray は、アプリケーションへのすべてのリクエストをトレースするわけではありません。X-Ray は、サンプリングアルゴリズムを適用することで効率的なトレースを行うと同時に、すべてのリクエストについての代表的なサンプルを示します。サンプルレートは 1 秒あたり 1 回のリクエストで、追加リクエストの 5％です。

注記

関数の X-Ray サンプルレートは設定することはできません。

X-Ray SDK を使用して .NET 関数を計装する

関数コードを実装して、メタデータを記録し、ダウンストリームコールをトレースできます。関数が他のリソースやサービスに対して行うコールの詳細を記録するには、AWS X-Ray SDK for .NET を使用します。SDK を取得するには、AWSXRayRecorder パッケージをプロジェクトファイルに追加します。


<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <TargetFramework>net8.0</TargetFramework>
    <GenerateRuntimeConfigurationFiles>true</GenerateRuntimeConfigurationFiles>
    <AWSProjectType>Lambda</AWSProjectType>
  </PropertyGroup>
  <ItemGroup>
    <PackageReference Include="Amazon.Lambda.Core" Version="2.1.0" />
    <PackageReference Include="Amazon.Lambda.SQSEvents" Version="2.1.0" />
    <PackageReference Include="Amazon.Lambda.Serialization.Json" Version="2.1.0" />
    <PackageReference Include="AWSSDK.Core" Version="3.7.103.24" />
    <PackageReference Include="AWSSDK.Lambda" Version="3.7.104.3" />
    <PackageReference Include="AWSXRayRecorder.Core" Version="2.13.0" />
    <PackageReference Include="AWSXRayRecorder.Handlers.AwsSdk" Version="2.11.0" />
  </ItemGroup>
</Project>

AWS SDK、Entity Framework、HTTP リクエストに自動計測を提供するさまざまな Nuget パッケージがあります。設定オプションの完全なセットについては、「AWS X-Ray 開発者ガイド」の「AWS X-Ray SDK for .NET」を参照してください。

目的の Nuget パッケージを追加したら、自動計測を設定します。ベストプラクティスは、この設定を関数のハンドラー関数の外部で実行することです。これにより、実行環境の再利用を活用して関数のパフォーマンスを向上させることができます。次のコード例では、RegisterXRayForAllServices メソッドを関数コンストラクタで呼び出して、すべての AWS SDK 呼び出しに計測を追加しています。


[assembly: LambdaSerializer(typeof(Amazon.Lambda.Serialization.SystemTextJson.DefaultLambdaJsonSerializer))]

namespace GetProductHandler;

public class Function
{
    private readonly IDatabaseRepository _repo;
    
    public Function()
    {
        // Add auto instrumentation for all AWS SDK calls
        // It is important to call this method before initializing any SDK clients
        AWSSDKHandler.RegisterXRayForAllServices();
        this._repo = new DatabaseRepository();
    }
    
    public async Task<APIGatewayProxyResponse> FunctionHandler(APIGatewayProxyRequest request)
    {
        var id = request.PathParameters["id"];
        
        var databaseRecord = await this._repo.GetById(id);
        
        return new APIGatewayProxyResponse 
        {
            StatusCode = (int)HttpStatusCode.OK,
            Body = JsonSerializer.Serialize(databaseRecord)
        };
    }
}

Lambda コンソールを使用してトレースを有効化する

コンソールを使用して、Lambda 関数のアクティブトレースをオンにするには、次のステップに従います。

アクティブトレースをオンにするには

Lambda コンソールの [関数ページ] を開きます。
関数を選択します。
[設定] を選択してから、[モニタリングおよび運用ツール] を選択します。
[編集] を選択します。
[X-Ray] で、[アクティブトレース] をオンに切り替えます。
[保存] をクリックします。

Lambda API でのトレースのアクティブ化

AWS CLI または AWS SDK で Lambda 関数のトレースを設定するには、次の 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 サービスグラフ] には、アプリケーションとそのすべてのコンポーネントに関する情報が表示されます。次のエラープロセッサのサンプルアプリケーション例は、2 つの関数を持つアプリケーションを示しています。プライマリ関数はイベントを処理し、エラーを返す場合があります。上位 2 番目の関数は、最初のロググループに表示されるエラーを処理し、AWS SDKを使用してX-Ray、Amazon Simple Storage Service (Amazon S3)、および Amazon CloudWatch Logs を呼び出します。

X-Ray の 2 つの個別のアプリケーションおよびそれぞれに関係するサービスマップを示した図

注記

関数の X-Ray サンプルレートは設定することはできません。

アクティブトレースを使用する場合、Lambda はトレースごとに 2 つのセグメントを記録します。これにより、サービスグラフに 2 つのノードが作成されます。次のイメージは、エラープロセッサのサンプルアプリケーションからの主要機能のこれら 2 つのノードを示しています。

左に示された 1 つめのノードは、呼び出しリクエストを受信する Lambda サービスを表しています。2 つめのノードは、特定の Lambda 関数を表しています。次の例は、これら 2 つのセグメントを使用したトレースを示しています。いずれも my-function と名付けられていますが、1 つは AWS::Lambda の起点があり、もう 1 つは AWS::Lambda::Function の起点があります。

特定の Lambda 呼び出しの各サブセグメント間に生じるレイテンシーを示した X-Ray トレースです。

この例では、関数セグメントを展開して、それの 3 つのサブセグメントが表示されています。

初期化 －関数のロードと初期化コードの実行に要した時間を表します。このサブセグメントは、関数の各インスタンスが処理する最初のイベントに対してのみ表示されます。
[呼び出し] - ハンドラーコードの実行に要した時間を表します。
[オーバーヘッド] - Lambda ランタイムが次のイベントを処理するための準備に要する時間を表します。

HTTP クライアントをインストルメント化し、SQL クエリを記録して、注釈とメタデータからカスタムサブセグメントを作成することもできます。詳細については、「AWS X-Ray デベロッパーガイド」の「AWS X-Ray SDK for .NET」を参照してください。

料金

X-Ray トレースは、毎月、AWS 無料利用枠で設定された一定限度まで無料で利用できます。X-Ray の利用がこの上限を超えた場合は、トレースによる保存と取得に対する料金が発生します。詳細については、「AWS X-Ray 料金表」を参照してください。

ブラウザで JavaScript が無効になっているか、使用できません。

AWS ドキュメントを使用するには、JavaScript を有効にする必要があります。手順については、使用するブラウザのヘルプページを参照してください。

ドキュメントの表記規則

エラー

テスト