AWS Node.js SDK 的 X-Ray 護理 - AWS X-Ray
要求相依性管理Node.js 樣本

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

AWS Node.js SDK 的 X-Ray 護理

Node.js 的 X-Ray 是用SDK於快速 Web 應用程式和 Node.js Lambda 函數的程式庫，可提供產生追蹤資料並將其傳送至 X-Ray 精靈的類別和方法。追蹤資料包括應用程式所提供之傳入HTTP要求的相關資訊，以及應用程式使用 AWS SDK或用HTTP戶端對下游服務進行呼叫的相關資訊。

注意

Node.js SDK 的 X-Ray 是一個開放原始碼專案，支援 Node.js 版本 14.x 及以上版本。您可以關注該項目並在以下位置提交問題並提取請求 GitHub：gi thub.com/aws/ aws-xray-sdk-node

如果您使用 Express，請先在應用程式伺服器上新增SDK為中介軟體，以追蹤傳入的要求。中介軟體會為每個追蹤的請求建立區段，並在傳送回應時完成區段。區段開啟時，您可以使用用SDK戶端的方法將資訊新增至區段，並建立子區段以追蹤下游呼叫。SDK也會自動記錄應用程式在區段開啟時擲回的例外狀況。

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

注意

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

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

Node.js 的 X-Ray 還SDK為下游調用HTTP網絡APIs和SQL查詢提供了儀器。將您的HTTP客戶端包裝在SDK的捕獲方法中，以記錄有關撥出HTTP電話的信息。對於用SQL戶端，請針對您的資料庫類型使用擷取方法。

中介軟體會將抽樣規則套用到傳入請求，判斷要追蹤的請求。您可以設定 Node.js SDK 的 X-Ray，以調整取樣行為或記錄應用程式執行所在之運 AWS 算資源的相關資訊。

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

標註與中繼資料

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

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

如需有關類別和方法SDK的參考文件，請參閱 Node.js AWS X-Ray SDK 參API考資料。

要求

Node.js SDK 的 X-Ray 需要 Node.js 和以下庫：

  • atomic-batcher— 1.0.2

  • cls-hooked— 4.2.2

  • pkginfo— 0.4.0

  • semver— 5.3.0

當您使用安裝它時，會SDK將這些庫拉入NPM。

若要追蹤用 AWS SDK戶端，Node.js SDK 的 X-Ray 需要 Node.js JavaScript 中的最低版本 AWS SDK的最低版本。

  • aws-sdk— 2.7.15

相依性管理

Node.js 的 X-Ray 可從中SDK獲得NPM。

對於本地開發，請使用 npm SDK 在項目目錄中安裝。

~/nodejs-xray$ npm install aws-xray-sdk
aws-xray-sdk@3.3.3
  ├─┬ aws-xray-sdk-core@3.3.3
  │ ├── @aws-sdk/service-error-classification@3.15.0
  │ ├── @aws-sdk/types@3.15.0
  │ ├─┬ @types/cls-hooked@4.3.3
  │ │ └── @types/node@15.3.0
  │ ├── atomic-batcher@1.0.2
  │ ├─┬ cls-hooked@4.2.2
  │ │ ├─┬ async-hook-jl@1.7.6
  │ │ │ └── stack-chain@1.3.7
  │ │ └─┬ emitter-listener@1.1.2
  │ │   └── shimmer@1.2.1
  │ └── semver@5.7.1
  ├── aws-xray-sdk-express@3.3.3
  ├── aws-xray-sdk-mysql@3.3.3
  └── aws-xray-sdk-postgres@3.3.3

使用該--save選項將其另存SDK為應用程序的依賴項package.json。

~/nodejs-xray$ npm install aws-xray-sdk --save
aws-xray-sdk@3.3.3

如果您的應用程式有任何版本與 X-Ray 相依性衝突的相依性，則會安裝SDK這兩個版本以確保相容性。有關更多詳細信息，請參閱依賴關係解決的官方NPM文檔。

Node.js 樣本

使用 Node.js 的工作，以在 AWS X-Ray SDK請求通過 Node.js 應用程序時獲取請求的 end-to-end 視圖。