配置适用于 Go 的 X-Ray 开发工具包 - Amazon X-Ray
服务插件采样规则Logging环境变量使用 Configure 方法
Amazon Web Services 文档中描述的 Amazon Web Services 服务或功能可能因区域而异。要查看适用于中国区域的差异，请参阅中国的 Amazon Web Services 服务入门。

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

配置适用于 Go 的 X-Ray 开发工具包

您可以指定适用于 Go 环境变量的 X-Ray SDK for Go 的配置，方法是调用Configure带有Config对象，或者假设默认值。环境变量优先于 Config 值，后者又优先于任何默认值。

服务插件

使用plugins记录有关托管您应用程序的服务的信息。

Plugins

  • Amazon EC2 —EC2Plugin会添加实例 ID、可用区和 CloudWatch Logs 组。

  • Elastic Beanstalk —ElasticBeanstalkPlugin添加环境名称、版本标签和部署 ID。

  • Amazon ECS —ECSPlugin添加容器 ID。

使用 Amazon EC2 和 Elastic Beanstalk 插件对资源数据进行细分。

要使用插件，请导入以下程序包之一。

"github.com/aws/aws-xray-sdk-go/awsplugins/ec2"
"github.com/aws/aws-xray-sdk-go/awsplugins/ecs"
"github.com/aws/aws-xray-sdk-go/awsplugins/beanstalk"

每个插件都有一个明确的 Init() 函数调用来加载插件。

例 ec2.Init()

import (
	"os"

	"github.com/aws/aws-xray-sdk-go/awsplugins/ec2"
	"github.com/aws/aws-xray-sdk-go/xray"
	)

	func init() {
		// conditionally load plugin
		if os.Getenv("ENVIRONMENT") == "production" {
		ec2.Init()
	}

	xray.Configure(xray.Config{
		ServiceVersion: "1.2.3",

	})
}

SDK 还使用插件设置来设置origin字段。这表示运行您的应用程序的 AWS 资源类型。资源类型显示在服务映射中您的应用程序名称下方。例如：AWS::ElasticBeanstalk::Environment。

具有资源类型的服务节点。

当您使用多个插件时，SDK 将使用以下解析顺序来确定源：ElasticBeanstalk > EKS > 弹性云服务器 > EC2。

采样规则

开发工具包使用您在 X-Ray 控制台中定义的采样规则来确定要记录的请求。默认规则每秒跟踪第一个请求，以及向 X-Ray 发送跟踪的所有服务中所有其他请求的 5%。在 X-Ray 控制台中创建其他规则以自定义为每个应用程序记录的数据量。

开发工具包按定义的顺序应用自定义规则。如果一个请求匹配多个自定义规则，则 SDK 仅应用第一个规则。

注意

如果 SDK 无法访问 X-Ray 获取采样规则，它将恢复为默认的本地规则，即每秒第一个请求和每个主机所有其他请求的 5%。如果主机没有调用采样 API 的权限，或者无法连接到 X-Ray 守护程序，该程序充当 SDK 发出的 API 调用的 TCP 代理，则会发生这种情况。

您还可以将开发工具包配置为从 JSON 文档加载采样规则。对于 X-Ray 采样不可用的情况，SDK 可以使用本地规则作为备份，或专门使用本地规则。

例 采样规则 .json

{
  "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
  }
}

此示例定义了一个自定义规则和一个默认规则。自定义规则应用 5% 的采样速率，没有最小数量的路径跟踪请求/api/move/。默认规则每秒跟踪第一个请求和 10% 的其他请求。

本地定义规则的缺点是，固定目标由记录器的每个实例独立应用，而不是由 X-Ray 服务管理。当您部署更多主机时，固定速率会倍增，从而使控制记录的数据量变得更加困难。

在 上Amazon Lambda，您无法修改采样率。如果您的函数由分析服务调用，则 Lambda 将记录生成该服务采样的请求的调用。如果启用了活动跟踪并且没有跟踪标头，则 Lambda 会做出采样决定。

要提供备份规则，请通过使用 NewCentralizedStrategyWithFilePath 指向本地采样 JSON 文件。

例 main.go — 本地采样规则

s, _ := sampling.NewCentralizedStrategyWithFilePath("sampling.json") // path to local sampling json
xray.Configure(xray.Config{SamplingStrategy: s})

要仅使用本地规则，请通过使用 NewLocalizedStrategyFromFilePath 指向本地采样 JSON 文件。

例 main.go — 禁用采样

s, _ := sampling.NewLocalizedStrategyFromFilePath("sampling.json") // path to local sampling json
xray.Configure(xray.Config{SamplingStrategy: s})

Logging

注意

从版本 1.0.0-rc.10 开始，xray.Config{} 字段 LogLevel 和 LogFormat 已弃用。

X-Ray 使用以下接口进行日志记录。默认记录器写入 stdout（LogLevelInfo 及跟高版本）。 

type Logger interface {
	Log(level LogLevel, msg fmt.Stringer)
}

const (
	LogLevelDebug LogLevel = iota + 1
	LogLevelInfo
	LogLevelWarn
	LogLevelError
)

例 写入 io.Writer

xray.SetLogger(xraylog.NewDefaultLogger(os.Stderr, xraylog.LogLevelError))

环境变量

您可以使用环境变量配置适用于 Go 的 X-Ray 开发工具包。开发工具包支持以下变量。

  • AWS_XRAY_TRACING_NAME— 设置开发工具包用于分段的服务名称。

  • AWS_XRAY_DAEMON_ADDRESS— 设置 X-Ray 守护程序侦听器的主机和端口。默认情况下，开发工具包将跟踪数据发送到127.0.0.1:2000。如果您已将守护进程配置为侦听其他端口或者它正在其他主机上运行。

  • AWS_XRAY_CONTEXT_MISSING— 设置该值以确定开发工具包如何处理缺少上下文错误。对于在未打开任何请求时运行的启动代码或者会生成新线程的代码，如果您尝试在其中使用分析过的客户端，则可能发生与缺失分段或子分段相关的错误。

    • RUNTIME_ERROR— 默认情况下，开发工具包设置为抛出运行时异常。

    • LOG_ERROR— 设置为记录错误并继续。

环境变量覆盖在代码中设置的等效值。

使用 Configure 方法

您还可 SDK for Go 用Configure方法。Configure接受一个参数，一个Config对象，包含以下可选字段。

DaemonAddr

此字符串指定 X-Ray 守护程序侦听器的主机和端口。如果未指定，X-Ray 将使用AWS_XRAY_DAEMON_ADDRESS环境变量。如果未设置该值，则将使用“127.0.0.1:2000”。

ServiceVersion

此字符串指定服务的版本。如果未指定，X-Ray 将使用空字符串 (“”)。

SamplingStrategy

此 SamplingStrategy 对象指定跟踪哪些应用程序调用。如果未指定，X-Ray 使用LocalizedSamplingStrategy，这将采用在xray/resources/DefaultSamplingRules.json。

StreamingStrategy

此 StreamingStrategy 对象指定当 RequiresStreaming 返回 true 时是否流式传输分段。如果未指定，X-Ray 使用DefaultStreamingStrategy，这将在子分段数超过 20 个时流式传输采样分段。

ExceptionFormattingStrategy

此 ExceptionFormattingStrategy 对象指定您希望如何处理各种异常。如果未指定，X-Ray 使用DefaultExceptionFormattingStrategy带有XrayError类型error、错误消息和堆栈跟踪。