為 Node.js 配置 X-Ray SDK

您可以使用外掛程式為 Node.js 設定 X-Ray SDK，以包含應用程式執行之服務的相關資訊、修改預設取樣行為，或新增套用至特定路徑要求的取樣規則。

服務外掛程式

用plugins於記錄託管應用程式之服務的相關資訊。

若要使用外掛程config式，請使用適用於 Node.js 的 X-Ray 開發套件。

var AWSXRay = require('aws-xray-sdk');
AWSXRay.config([AWSXRay.plugins.EC2Plugin,AWSXRay.plugins.ElasticBeanstalkPlugin]);

SDK 也會使用外掛程式設定來設定區origin段上的欄位。這表示運行您的應用程序的AWS資源的類型。當您使用多個外掛程式時，SDK 會使用下列解析順序來判斷來源： ElasticBeanstalk > EKS > ECS > EC2。

抽樣規則

SDK 會使用您在 X-Ray 主控台中定義的取樣規則來決定要記錄的要求。預設規則會每秒追蹤第一個要求，而所有服務的任何其他要求的百分之五會傳送追蹤至 X-Ray。在 X-Ray 主控台中建立其他規則，以自訂為每個應用程式記錄的資料量。

SDK 會依定義順序套用自訂規則。如果要求符合多個自訂規則，SDK 只會套用第一個規則。

您也可以將 SDK 設定為從 JSON 文件載入取樣規則。SDK 可以使用本機規則做為無法使用 X-Ray 取樣的情況的備份，或僅使用本機規則。

{
  "version": 2,
  "rules": [
    {
      "description": "Player moves.",
      "host": "*",
      "http_method": "*",
      "url_path": "/api/move/*",
      "fixed_target": 0,
      "rate": 0.05
    }
  ],
  "default": {
    "fixed_target": 1,
    "rate": 0.1
  }
}

此範例定義了一個自訂規則和一個預設規則。自訂規則會套用百分之五的取樣率，而且沒有追蹤下限路徑的要求數目下限/api/move/。預設規則會每秒追蹤第一次請求和 10% 的額外請求。

在本機定義規則的缺點是，固定目標會由記錄器的每個執行個體獨立套用，而不是由 X-Ray 服務管理。當您部署更多主機時，固定費率會倍增，因此更難以控制記錄的資料量。

開啟時AWS Lambda，您無法修改取樣率。如果您的函數是由已檢測的服務呼叫，則 Lambda 會記錄產生由該服務取樣之請求的呼叫。如果啟用主動追蹤且沒有追蹤標頭，Lambda 會做出取樣決策。

若要配置備份規則，請告知適用於 Node.js 的 X-Ray SDK 使用setSamplingRules。

var AWSXRay = require('aws-xray-sdk');
AWSXRay.middleware.setSamplingRules('sampling-rules.json');

您也可以在程式碼中定義規則，然後將其做為物件傳遞給 setSamplingRules。

var AWSXRay = require('aws-xray-sdk');
var rules = {
  "rules": [ { "description": "Player moves.", "service_name": "*", "http_method": "*", "url_path": "/api/move/*", "fixed_target": 0, "rate": 0.05 } ],
  "default": { "fixed_target": 1, "rate": 0.1 },
  "version": 1
  }

AWSXRay.middleware.setSamplingRules(rules);

若要僅使用本機規則，請呼叫 disableCentralizedSampling。

AWSXRay.middleware.disableCentralizedSampling()

日誌

若要記錄軟體開發套件的輸出，請呼叫 AWSXRay.setLogger(logger)，其中 logger 是提供標準記錄日誌方法的物件 (warn、info 等)。

默認情況下，SDK 將使用控制台對象上的標準方法將錯誤消息記錄到控制台。內置記錄器的日誌級別可以通過使用AWS_XRAY_DEBUG_MODE或AWS_XRAY_LOG_LEVEL環境變量進行設置。如需有效記錄層級值的清單，請參閱環境變數。

如果您希望為日誌提供不同的格式或目的地，那麼您可以為 SDK 提供自己的記錄器接口實現，如下所示。任何實現此接口的對象都可以使用。這意味著許多日誌庫（例如溫斯頓）可以使用並直接傳遞給 SDK。

var AWSXRay = require('aws-xray-sdk');

// Create your own logger, or instantiate one using a library.
var logger = {
  error: (message, meta) => { /* logging code */ },
  warn: (message, meta) => { /* logging code */ },
  info: (message, meta) => { /* logging code */ },
  debug: (message, meta) => { /* logging code */ }
}

AWSXRay.setLogger(logger);
AWSXRay.config([AWSXRay.plugins.EC2Plugin]);

請在執行其他組態方法前呼叫 setLogger，確保擷取來自這些操作的輸出。

X-Ray 精靈

如果 X-Ray 精靈在連接埠或主機上接聽127.0.0.1:2000，您可以將 Node.js 的 X-Ray SDK 設定為將追蹤資料傳送至不同的位址。

AWSXRay.setDaemonAddress('host:port');

您可以透過名稱或 IPv4 地址指定主機。

var AWSXRay = require('aws-xray-sdk');
AWSXRay.setDaemonAddress('daemonhost:8082');

若您設定精靈針對 TCP 和 UDP 接聽不同連接埠，您可以在精靈地址設定中同時指定它們。

var AWSXRay = require('aws-xray-sdk');
AWSXRay.setDaemonAddress('tcp:daemonhost:8082 udp:daemonhost:8083');

您也可以透過使用 AWS_XRAY_DAEMON_ADDRESS 環境變數來設定精靈地址。

環境變數

您可以使用環境變數來配置適用於 Node.js 的 X-Ray 開發套件。軟體開發套件支援以下變數。