配置适用于 Go 的 X-Ray 开发工具包 - Amazon X-Ray
Amazon Web Services 文档中描述的 Amazon Web Services 服务或功能可能因区域而异。要查看适用于中国区域的差异,请参阅 中国的 Amazon Web Services 服务入门 (PDF)

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

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

您可以通过环境变量、使用Config对象调用或假设默认值来指定 X-RConfigure ay SDK for Go 的配置。环境变量优先于 Config 值,后者又优先于任何默认值。

服务插件

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

插件
  • Amazon EC2 —EC2Plugin 添加实例 ID、可用区和 CloudWatch 日志组。

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

  • 亚马逊 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字段。这表示运行您的应用程序的Amazon资源类型。当您使用多个插件时,SDK 使用以下解析顺序来确定来源: ElasticBeanstalk > EKS > ECS > EC2。

采样规则

SDK 使用您在 X-Ray 控制台中定义的采样规则来确定要记录哪些请求。默认规则每秒跟踪第一个请求,以及向 X-Ray 发送跟踪的所有服务中任何额外请求的百分之五。在 X-Ray 控制台中创建其他规则,自定义每个应用程序记录的数据量。

开发工具开发工具包将原定设置为原定设置样本规则的应用。如果请求匹配多个自定义规则,则 SDK 仅应用第一条规则。

注意

如果 SDK 无法访问 X-Ray 获取采样规则,它将恢复为每秒第一个请求的默认本地规则,以及每台主机任何额外请求的百分之五。如果主机没有权限调用采样 API,或者无法连接到 X-Ray 守护程序,后者充当 SDK 发出的 API 调用的 TCP 代理,就会发生这种情况。

您也可以将 SDK 配置为从 JSON 文档加载采样规则。在无法使用 X-Ray 采样的情况下,SDK 可以使用本地规则作为备份,也可以仅使用本地规则。

例 sampling-rules.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 } }

此示例定义了一个自定义规则和一个默认规则。自定义规则采用百分之五的采样率,没有最低追踪路径的请求数/api/move/。原定设置样本规则为每秒 1 个请求和 5% 的其他请求。

在本地定义规则的缺点是,固定目标由记录器的每个实例独立应用,而不是由 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})

日志记录

注意

从版本 1.0.0-rc.10 开始,xray.Config{} 字段 LogLevelLogFormat 已弃用。

X-Ray 使用以下接口进行记录。默认记录器写入 stdoutLogLevelInfo 及跟高版本)。

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— 设置 SDK 用于分段的服务名称。

  • AWS_XRAY_DAEMON_ADDRESS— 设置 X-Ray 守护程序侦听器的主机和端口。默认情况下,SDK 会将跟踪数据发送到127.0.0.1:2000。如果您已将守护程序配置为监听其他端口,或者它在其他主机上运行,请使用此变量。

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

    • RUNTIME_ERROR— 默认情况下,SDK 设置为引发运行时异常。

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

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

使用 Configure 方法

您还可以使用该Configure方法配置适用于 Go 的 X-Ray 开发工具包。 Configure接受一个参数,一个Config对象,其中包含以下可选字段。

DaemonAddr

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

ServiceVersion

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

SamplingStrategy

SamplingStrategy 对象指定跟踪哪些应用程序调用。如果未指定,则 X-Ray 使用 aLocalizedSamplingStrategy,该策略采用中定义的策略xray/resources/DefaultSamplingRules.json

StreamingStrategy

StreamingStrategy对象指定在RequiresStreaming返回 true 时是否流式传输片段。如果未指定,则在子分段数大于 20 时DefaultStreamingStrategy,X-Ray 使用 a 流式传输采样分段。

ExceptionFormattingStrategy

ExceptionFormattingStrategy 对象指定您希望如何处理各种异常。如果未指定,则 X-RaDefaultExceptionFormattingStrategy y 使用类型为error o、错误消息和堆栈跟踪。XrayError