使用 Node.js 的 X-Ray SDK 將註釋和中繼資料新增至區段

您可以使用註釋和中繼資料記錄有關請求、環境或應用程式的其他資訊。您可以將註釋和中繼資料新增至 X-Ray SDK 建立的區段，或新增至您建立的自訂子區段。

註釋是與字符串，數字或布爾值鍵-值對。註釋會編製索引以與篩選器運算式搭配使用 使用註釋來記錄您要用來在主控台中分組追蹤的資料，或在呼叫 GetTraceSummariesAPI.

中繼資料是索引鍵-值配對，可以具有任何類型的值 (包括物件和清單)，但不會編製索引以用於篩選運算式。使用元數據記錄要存儲在跟踪中但不需要與搜索一起使用的其他數據。

除了註釋和中繼資料，您也可以在區段上記錄使用者 ID 字串。使用者IDs會記錄在區段上的個別欄位中，並建立索引以供搜尋使用。

使用 Node.js 的 X-Ray SDK 記錄註釋

針對您想要建立索引以用於搜尋的區段或子區段，請使用標註來記錄這些區段上的資訊。

註釋要求

• 按鍵 — X-Ray 註解的金鑰最多可包含 500 個英數字元。您不能使用點或句點 (.) 以外的空格或符號。

• 值 — X-Ray 註釋的值最多可包含 1,000 個 Unicode 字元。

• 註釋的數量 — 每個追蹤最多可以使用 50 個註釋。

記錄標註

1. 取得目前區段或子區段的參考。

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

2. 使用字串索引鍵、布林值、數字或字串值，呼叫 addAnnotation。

   document.addAnnotation("mykey", "my value");

   下列範例顯示如何putAnnotation使用包含點和布林值、數字或字串值的 String 索引鍵來呼叫。

   document.putAnnotation("testkey.test", "my value");

記SDK錄註釋為在段文檔中的對annotations象鍵-值對。若使用相同鍵呼叫 addAnnotation 兩次，則會覆寫之前在相同區段或子區段上記錄的值。

若要尋找具有特定值之註釋的繪線，請在篩選器運算式中使用annotation[key]關鍵字。

範例 app.js - 標註

var AWS = require('aws-sdk');
var AWSXRay = require('aws-xray-sdk');
var ddb = AWSXRay.captureAWSClient(new AWS.DynamoDB());
...
app.post('/signup', function(req, res) {
    var item = {
        'email': {'S': req.body.email},
        'name': {'S': req.body.name},
        'preview': {'S': req.body.previewAccess},
        'theme': {'S': req.body.theme}
    };

    var seg = AWSXRay.getSegment();
    seg.addAnnotation('theme', req.body.theme);
  
    ddb.putItem({
      'TableName': ddbTable,
      'Item': item,
      'Expected': { email: { Exists: false } }
  }, function(err, data) {
...

使用 Node.js 的 X-Ray SDK 記錄中繼資料

針對您不想要建立索引以用於搜尋的區段，請使用中繼資料來記錄這些區段或子區段上的資訊。元數據值可以是字符串，數字，布爾值，或任何其他可以被序列化為對象或數組的JSON對象。

記錄中繼資料

1. 取得目前區段或子區段的參考。

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

2. 使用字串鍵、布林值、數字、字串或物件值，以及字串命名空間，呼叫 addMetadata。

   document.addMetadata("my key", "my value", "my namespace");

   或

   只使用鍵和值呼叫 addMetadata。

   document.addMetadata("my key", "my value");

如果您沒有指定命名空間，則SDK使用default. 若使用相同鍵呼叫 addMetadata 兩次，則會覆寫之前在相同區段或子區段上記錄的值。

使用 Node.js IDs 的 X-Ray SDK 記錄使用者

記錄請求區段IDs上的使用者，以識別傳送請求的使用者。此作業與 AWS Lambda 函數不相容，因為 Lambda 環境中的區段是不可變的。setUser 呼叫只可套用至區段，而非子區段。

記錄使用者 IDs

1. 取得目前區段或子區段的參考。

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

2. 使用傳送請求之使用者的字串 ID 呼叫 setUser()。

   var user = 'john123';
   
   AWSXRay.getSegment().setUser(user);

您可以呼叫 setUser，以在 Express 應用程式開始處理請求時馬上記錄使用者 ID。如果您只要使用區段來設定使用者 ID，可以將呼叫鏈結為單行。

範例 app.js - 使用者 ID

var AWS = require('aws-sdk');
var AWSXRay = require('aws-xray-sdk');
var uuidv4 = require('uuid/v4');
var ddb = AWSXRay.captureAWSClient(new AWS.DynamoDB());
...
    app.post('/signup', function(req, res) {
    var userId = uuidv4();
    var item = {
        'userId': {'S': userId},
        'email': {'S': req.body.email},
        'name': {'S': req.body.name}
    };

    var seg = AWSXRay.getSegment().setUser(userId);
  
    ddb.putItem({
      'TableName': ddbTable,
      'Item': item,
      'Expected': { email: { Exists: false } }
  }, function(err, data) {
...

若要尋找使用者 ID 的追蹤，請在篩選運算式中使用user關鍵字。