使用适用于 Node.js 的 X-Ray 开发工具包将注释和元数据添加到分段 - Amazon X-Ray
使用适用于 Node.js 的 X-Ray 开发工具包记录注释使用适用于 Node.js 的 X-Ray 开发工具包记录元数使用适用于 Node.js 的 X-Ray 开发工具包记录用户 ID
Amazon Web Services 文档中描述的 Amazon Web Services 服务或功能可能因区域而异。要查看适用于中国区域的差异，请参阅中国的 Amazon Web Services 服务入门。

本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。

使用适用于 Node.js 的 X-Ray 开发工具包将注释和元数据添加到分段

您可以使用注释和元数据记录有关请求、环境或应用程序的其他信息。您可以将注释和元数据添加到 X-Ray 开发工具包创建的分段或您创建的自定义子分段。

注释是带字符串、数字或布尔值的键值对。系统会对注释编制索引，以便与筛选表达式。使用注释记录要用于对控制台中的跟踪进行分组的数据或在调用 GetTraceSummaries API 时使用的数据。

Metadata是键-值对，它们可以具有任何类型值，包括对象和列表达式，但没有编制索引以便与筛选表达式一起使用。使用元数据记录要存储在跟踪中但不需要与搜索一起使用的其他数据。

除了注释和元数据之外，您还可以记录用户 ID 字符串在分段上。用户 ID 记录在分段的单独字段中，并且不会为其编制索引以用于搜索。

使用适用于 Node.js 的 X-Ray 开发工具包记录注释

使用注释记录有关要为其编制索引以进行搜索的分段和子分段的信息。

注释要求

  • 密钥— 最多 500 个字母数字字符。无空格或符号，下划线除外。

  • 值— 最多 1000 个 Unicode 字符。

  • Entries— 每个跟踪最多 50 个注释。

记录注释

  1. 获取对当前分段或子分段的引用。

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

  2. 调用带有字符串键和布尔值、数字值或字符串值的 addAnnotation。 

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

开发工具包将注释以键-值对的形式记录在annotations对象中的区段文档。使用相同键调用两次 addAnnotation 将覆盖同一分段或子分段上之前记录的值。

要查找具有带特定值的注释的跟踪，请在annotations.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 开发工具包记录元数

使用元数据记录有关您无需为其编制索引以进行搜索的分段或子分段的信息。元数据值可以是字符串、数字、布尔值或可序列化为 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");

如果您没有指定命名空间，则开发工具包将使用default。使用相同键调用两次 addMetadata 将覆盖同一分段或子分段上之前记录的值。

使用适用于 Node.js 的 X-Ray 开发工具包记录用户 ID

记录请求分段上的用户 ID 以标识发送请求的用户。此操作不兼容Amazon Lambda函数，因为 Lambda 环境中的段是不可变的。这些区域有：setUser调用只能应用于区段，而不能应用于子段。

记录用户 ID

  1. 获取对当前分段或子分段的引用。

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

  2. CallsetUser()使用发送请求的用户的字符串 ID。 

    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筛选表达式中使用 关键字。