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

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

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

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

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

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

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

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

X-Ray 中的所有注释都需要以下内容：

注释要求

  • 密钥-X-Ray 注释的密钥最多可以包含 500 个字母数字字符。不能使用除下划线符号 (_) 之外的空格或符号。

  • 值-X-Ray 注释的值最多可以包含 1,000 个 Unicode 字符。

  • 注释的数量-每条轨迹最多可以使用 50 个注释。

在 Amazon Lambda 函数之外录制注释

  1. 获取 AWSXRayRecorder 的实例。

    using Amazon.XRay.Recorder.Core;
...
AWSXRayRecorder recorder = AWSXRayRecorder.Instance;

  2. 使用字符串键和布尔型、Int32、Int64、双精度或字符串值调用 addAnnotation。

    recorder.AddAnnotation("mykey", "my value");
在 Amazon Lambda 函数内部录制注释

Lambda 函数中的分段和子分段均由 Lambda 运行时环境管理。如果要在 Lambda 函数中为区段或子分段添加注释，则必须执行以下操作：

  1. 在 Lambda 函数中创建区段或子分段。

  2. 将注释添加到区段或子区段。

  3. 结束片段或子区段。

以下代码示例向您展示了如何向 Lambda 函数内的子段添加注解：

#Create the subsegment
AWSXRayRecorder.Instance.BeginSubsegment("custom method");
#Add an annotation
AWSXRayRecorder.Instance.AddAnnotation("My", "Annotation");
try
{
  YourProcess(); #Your function
}
catch (Exception e)
{
  AWSXRayRecorder.Instance.AddException(e);
}
finally #End the subsegment
{
  AWSXRayRecorder.Instance.EndSubsegment();
}

X-Ray SDK 将注释作为键值对记录在区段文档的annotations对象中。使用相同的键调用两次addAnnotation操作会覆盖先前在同一分段或子分段上记录的值。

要查找带有带有特定值的注释的跟踪，请在筛选表达式中使用annotations.key关键字。有关更多信息，请参阅 使用过滤器表达式。

使用适用于 .NET 的 X-Ray 开发工具包记录元数据

使用元数据记录有关区段或子细分的信息，您无需为这些区段或子细分编制索引即可在搜索中使用。元数据值可以是字符串、数字、布尔值或任何其他可以序列化为 JSON 对象或数组的对象。

记录元数据

  1. 获取的实例AWSXRayRecorder，如以下代码示例所示：

    using Amazon.XRay.Recorder.Core;
...
AWSXRayRecorder recorder = AWSXRayRecorder.Instance;

  2. AddMetadata使用字符串命名空间、字符串键和对象值进行调用，如以下代码示例所示：

    recorder.AddMetadata("my namespace", "my key", "my value");

    您也可以仅使用键值对来调用该AddMetadata操作，如以下代码示例所示：

    recorder.AddMetadata("my key", "my value");

如果您没有为命名空间指定值，X-Ray SDK 将使用default。使用相同的键调用两次AddMetadata操作会覆盖先前在同一分段或子分段上记录的值。