AWS X-Ray SDK for .NET - AWS X-Ray
要求將 .NET 的 X-Ray SDK 新增至您的應用程式相依性管理

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

AWS X-Ray SDK for .NET

適用於 .NET 的 X-Ray SDK 是用於檢測 C# .NET Web 應用程式、.NET 核心 Web 應用程式和 .NET 核心功能的程式庫。 AWS Lambda它提供了用於生成和發送跟踪數據到 X-Ray 守護進程的類和方法。這包括應用程式所提供之傳入要求的相關資訊，以及應用程式對下游 AWS 服務、HTTP Web API 和 SQL 資料庫進行呼叫的相關資訊。

注意

適用於 .NET 的 X-Ray SDK 是一個開放原始碼專案。您可以關注該項目並在以下位置提交問題並提取請求 GitHub：gi thub.com/aws/ aws-xray-sdk-dotnet

針對 Web 應用程式，請先將訊息處理常式新增至 Web 組態以追蹤傳入的請求。訊息處理常式會為每個追蹤的請求建立區段，並在傳送回應時完成區段。當區段開啟時，您可以使用軟體開發套件用戶端的方法，將資訊新增到區段，並建立子區段以追蹤下游呼叫。軟體開發套件也會在區段為開啟時自動記錄應用程式擲回的例外狀況。

對於經過測試的應用程式或服務呼叫的 Lambda 函數，Lambda 會讀取追蹤標頭並自動追蹤已取樣的請求。對於其他函數，您可以設定 Lambda 來取樣和追蹤傳入的請求。在任何一種情況下，Lambda 都會建立區段，並將其提供給 X-Ray SDK。

注意

在 Lambda 上，X-Ray 開發套件是選用的。如果您沒有在函數中使用它，您的服務對應仍會包含 Lambda 服務的節點，每個 Lambda 函數有一個節點。透過新增 SDK，您可以檢測函數程式碼，將子區段新增至 Lambda 記錄的函數區段。如需更多資訊，請參閱AWS Lambda 而且 AWS X-Ray。

接下來，使用適用於 .NET 的 X-Ray SDK 來檢測您的 AWS SDK for .NET 客戶端。每當您使用已檢測的用戶端對下游 AWS 服務 或資源進行呼叫時，SDK 都會在子區段中記錄有關呼叫的資訊。 AWS 服務和您在服務中存取的資源會顯示為追蹤對映上的下游節點，以協助您識別個別連線上的錯誤和節流問題。

適用於 .NET 的 X-Ray SDK 也提供了對 HTTP Web API 和 SQL 資料庫的下游呼叫的檢測。適用於 System.Net.HttpWebRequest 的 GetResponseTraced 延伸方法可追蹤傳出的 HTTP 呼叫。您可以使用 .NET 版本的 X-Ray SDK SqlCommand 來檢測 SQL 查詢。

開始使用 SDK 之後，請設定記錄器和訊息處理常式來自訂其行為。您可以新增外掛程式，以記錄執行應用程式所需的運算資源相關資料、定義抽樣規則以自訂抽樣行為，並設定日誌層級以在應用程式日誌中查看更多或更少的軟體開發套件資訊。

使用註釋與中繼資料，記錄應用程式所做的請求和工作等其他資訊。註釋是簡單的鍵/值對，系統會為其建立索引以用於篩選條件表達式，因此您可以搜尋包含特定資料的追蹤。元數據條目的限制較低，可以記錄整個對象和數組-任何可以序列化為 JSON 的內容。

標註與中繼資料

註釋和中繼資料是您使用 X-Ray SDK 新增至區段的任意文字。註釋會編製索引以與篩選器運算式搭配使用 中繼資料不會建立索引，但可以使用 X-Ray 主控台或 API 在原始區段中檢視。您授與 X-Ray 讀取權限的任何人都可以檢視此資料。

當程式碼中有許多經過檢測的用戶端時，單一請求區段可能包含大量子區段，每個使用經檢測用戶端進行的呼叫都有一個子區段。您可以將用戶端呼叫包裝在自訂子區段中，以組織和群組子區段。您可以為整個函數或任何部分的程式碼建立自訂子區段，並記錄子區段上的中繼資料和註釋，而不必寫入父區段上的所有項目。

如需軟體開發套件之類別和方法的參考文件，請參閱以下項目：

相同套件可同時支援 .NET 和 .NET Core，但使用的類別不同。除非類別是 .NET Core 專屬，否則本章範例都會連結至 .NET API 參考。

要求

適用於 .NET 的 X-Ray SDK 需要 .NET 框架 4.5 或更高版本和 AWS SDK for .NET.

若是 .NET Core 應用程式和函數，則軟體開發套件需要 .NET Core 2.0 或更新版本。

將 .NET 的 X-Ray SDK 新增至您的應用程式

用於 NuGet 將適用於 .NET 的 X-Ray SDK 新增至您的應用程式。

若要在 NuGet 套件管理員中安裝適用於 .NET 的 X-Ray SDK

  1. 選擇 [工具]、[NuGet P NuGet ackage 件管理員]、[管理方案的套件

  2. 搜尋 AWSXRayRecorder。

  3. 選擇套件，然後選擇 Install (安裝)。

相依性管理

適用於 .NET 的 X-Ray SDK 可從 Nuget 取得。使用軟件包管理器安裝 SDK：

Install-Package AWSXRayRecorder -Version 2.10.1

AWSXRayRecorder v2.10.1nuget 套件具有下列相依性：

NET 框架 4.5

AWSXRayRecorder (2.10.1)
|
|-- AWSXRayRecorder.Core (>= 2.10.1)
|   |-- AWSSDK.Core (>= 3.3.25.1)
|      
|-- AWSXRayRecorder.Handlers.AspNet (>= 2.7.3)
|   |-- AWSXRayRecorder.Core (>= 2.10.1)
|
|-- AWSXRayRecorder.Handlers.AwsSdk (>= 2.8.3)
|   |-- AWSXRayRecorder.Core (>= 2.10.1)
|
|-- AWSXRayRecorder.Handlers.EntityFramework (>= 1.1.1)
|   |-- AWSXRayRecorder.Core (>= 2.10.1)
|   |-- EntityFramework (>= 6.2.0)
|
|-- AWSXRayRecorder.Handlers.SqlServer (>= 2.7.3)
|   |-- AWSXRayRecorder.Core (>= 2.10.1)
|
|-- AWSXRayRecorder.Handlers.System.Net (>= 2.7.3)
    |-- AWSXRayRecorder.Core (>= 2.10.1)

NET 框架

AWSXRayRecorder (2.10.1)
|
|-- AWSXRayRecorder.Core (>= 2.10.1)
|   |-- AWSSDK.Core (>= 3.3.25.1)
|   |-- Microsoft.AspNetCore.Http (>= 2.0.0)
|   |-- Microsoft.Extensions.Configuration (>= 2.0.0)
|   |-- System.Net.Http (>= 4.3.4)
|      
|-- AWSXRayRecorder.Handlers.AspNetCore (>= 2.7.3)
|   |-- AWSXRayRecorder.Core (>= 2.10.1)
|   |-- Microsoft.AspNetCore.Http.Extensions (>= 2.0.0)
|   |-- Microsoft.AspNetCore.Mvc.Abstractions (>= 2.0.0)
|
|-- AWSXRayRecorder.Handlers.AwsSdk (>= 2.8.3)
|   |-- AWSXRayRecorder.Core (>= 2.10.1)
|
|-- AWSXRayRecorder.Handlers.EntityFramework (>= 1.1.1)
|   |-- AWSXRayRecorder.Core (>= 2.10.1)
|   |-- Microsoft.EntityFrameworkCore.Relational (>= 3.1.0)
|
|-- AWSXRayRecorder.Handlers.SqlServer (>= 2.7.3)
|   |-- AWSXRayRecorder.Core (>= 2.10.1)
|   |-- System.Data.SqlClient (>= 4.4.0)
|
|-- AWSXRayRecorder.Handlers.System.Net (>= 2.7.3)
    |-- AWSXRayRecorder.Core (>= 2.10.1)

有關依賴管理的更多詳細信息，請參閱微軟關於 Nuget 依賴關係和 Nuget 依賴解決方案的文檔。