AWS X-Ray
開発者ガイド

.NET 対応 AWS X-Ray SDK

X-Ray SDK for .NET は、AWS Lambda で C#.NET Core ウェブアプリケーション、.NET Core ウェブアプリケーション、および .NET Core 関数を計測するためのライブラリです。トレースデータを生成して X-Ray デーモンに送信するためのクラスとメソッドを提供します。これには、アプリケーションによって処理された受信リクエスト、およびアプリケーションからダウンストリーム AWS サービス、HTTP ウェブ API、および SQL データベースに対して行われる呼び出しに関する情報が含まれています。

注記

X-Ray SDK for .NET は、オープンソースプロジェクトです。プロジェクトに従って、GitHub: github.com/aws/aws-xray-sdk-dotnet で問題とプルリクエストを送信できます。

ウェブアプリケーションの場合は、最初にメッセージハンドラーをウェブ設定に追加して、受信リクエストをトレースします。メッセージハンドラーでは、トレース対象リクエストごとに「セグメント」を作成し、レスポンスが送信されるとセグメントを完了します。セグメントが開いている間、SDK クライアントのメソッドを使用してセグメントに情報を追加し、サブセグメントを作成してダウンストリーム呼び出しをトレースできます。また、SDK では、セグメントが開いている間にアプリケーションがスローする例外を自動的に記録します。

計測されたアプリケーションまたはサービスによって呼び出される Lambda 関数の場合、Lambda は トレースヘッダー を読み込み、サンプリングされたリクエストを自動的にトレースします。他の関数については、Lambda の設定 で受信リクエストのサンプルとトレースを行うことができます。いずれの場合も、Lambda はセグメントを作成し、X-Ray SDK に提供します。

注記

Lambda では、X-Ray SDK はオプションです。関数で使用しない場合、サービスマップには Lambda サービス用のノードと各 Lambda 関数用のノードが含まれます。SDK を追加すると、関数コードを計測して、Lambda によって記録された関数セグメントにサブセグメントを追加することができます。詳細については、「AWS Lambda および AWS X-Ray」を参照してください。

次に、X-Ray SDK for .NET を使用して AWS SDK for .NET クライアントを計測します。計測済みのクライアントを使用して、ダウンストリーム AWS のサービスやリソースに対して呼び出しを行うたびに、SDK はサブセグメントの呼び出しに関する情報を記録します。サービス内でアクセスする AWS のサービスとリソースは、サービスマップでダウンストリームノードとして表示され、個々の接続でエラーとスロットリングの問題を識別するのに役立ちます。

また、X-Ray SDK for .NET では、HTTP ウェブ APISQL データベースに対するダウンストリーム呼び出しの計測も行います。System.Net.HttpWebRequestGetResponseTraced 拡張メソッドは送信 HTTP 呼び出しをトレースします。X-Ray SDK for .NET の SqlCommand バージョンを使用して SQL クエリを計測します。

SDK を活用したら、「レコーダーとメッセージハンドラーを設定して」その動作をカスタマイズします。プラグインを追加して、アプリケーションを実行しているコンピューティングリソースに関するデータを記録したり、サンプリングルールを定義することでサンプリングの動作のカスタマイズしたり、アプリケーションログに SDK からの情報をより多くあるいは少なく表示するようにログレベルを設定できます。

アプリケーションが注釈やメタデータで行うリクエストや作業に関する追加情報を記録します。注釈は、フィルタ式で使用するためにインデックス化されたシンプルなキーと値のペアで、特定のデータが含まれているトレースを検索できます。メタデータのエントリは制約が緩やかで、JSON にシリアル化することが可能なオブジェクトと配列全体を記録できます。

注釈とメタデータ

注釈とメタデータは、X-Ray SDK でセグメントに追加する任意のテキストです。注釈はフィルタ式用にインデックス付けされます。メタデータはインデックス付けされませんが、X-Ray コンソールまたは API の raw セグメントに表示されます。X-Ray への読み取りアクセスを付与されたユーザーはだれでも、このデータを表示できます。

コードに多数の計測されたクライアントがある場合、単一のリクエストセグメントには計測されたクライアントで行われた呼び出しごとに 1 個の多数のサブセグメントを含めることができます。カスタムサブセグメントで、クライアント呼び出しをラップすることで、サブセグメントを整理してグループできます。関数全体またはコードの任意のセクションのサブセグメントを作成し、親セグメントにすべてのレコードを記述する代わりにサブセグメントにメタデータと注釈を記録できます。

SDK のクラスとメソッドに関するリファレンスドキュメントについては、以下を参照してください。

同じパッケージが .NET および .NET Core の両方をサポートしますが、使用されるクラスは異なります。この章の例は、そのクラスが .NET Core に固有でない限り、.NET API リファレンスにリンクされています。

要件

X-Ray SDK for .NET には .NET フレームワークと AWS SDK for .NET が必要です。

.NET Core アプリケーションと関数の場合、SDK では .NET Core 2.0 以降が必要になります。

X-Ray SDK for .NET をアプリケーションに追加する

NuGet を使用して、アプリケーションに X-Ray SDK for .NET を追加します。

NuGet パッケージマネージャーで X-Ray SDK for .NET を Visual Studio にインストールするには

  1. [ツール]、[NuGet パッケージマネージャー]、[Manage NuGet Packages for Solution (ソリューションに対する NuGet パッケージの管理)] を選択します。

  2. [AWSXRayRecorder] を検索します。

  3. パッケージを選択し、[Install] を選択します。