本文属于机器翻译版本。若本译文内容与英语原文存在差异,则一律以英文原文为准。
配置 X-Ray SDK for Go
您可以通过环境变量、使用 Config
对象调用 Configure
或采用默认值,来为X-Ray SDK for Go指定配置。环境变量优先于 Config
值,后者又优先于任何默认值。
小节目录
服务插件
使用 plugins
可记录有关托管您应用程序的服务的信息。
插件
-
Amazon EC2 –
EC2Plugin
会添加实例 ID、可用区和 CloudWatch Logs 组。 -
Elastic Beanstalk –
ElasticBeanstalkPlugin
添加环境名称、版本标签和部署 ID。 -
Amazon ECS –
ECSPlugin
添加容器 ID。

要使用插件,请导入以下程序包之一。
"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",
})
}
开发工具包还使用插件设置来设置分段上的 origin
字段。这指示运行您的应用程序的 AWS 资源的类型。资源类型显示在运行应用程序中您应用程序名称的下方。例如:AWS::ElasticBeanstalk::Environment
。

在使用多个插件时,开发工具包将使用以下解析顺序确定来源:ElasticBeanstalk > EKS > ECS > EC2。
采样规则
开发工具包使用您在 X-Ray 控制台中定义的采样规则来确定要记录的请求。默认规则跨将跟踪发送至 X-Ray 的所有服务跟踪每秒的第一个请求,以及任何额外请求中的 5%。在 X-Ray 控制台中创建其他规则以自定义为每个应用程序记录的数据量。
SDK 将按定义自定义规则的顺序应用它们。如果一个请求与多个自定义规则匹配,SDK 将只应用第一个规则。
如果开发工具包无法访问 X-Ray 来获取示例规则,则它将恢复为使用每台主机的默认本地规则每秒的第一个请求,以及任何额外请求中的 5%。如果主机无权调用采样 API,或者无法连接到 X-Ray 守护程序(充当开发工具包所发出 API 调用的 TCP 代理),则可能出现此情况。
您还可将开发工具包配置为加载 JSON 文档中的采样规则。开发工具包可以在 X-Ray 采样不可用的情况下使用本地规则作为备份,或仅使用本地规则。
例 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/
下的路径的请求未设置最低追踪请求数量。默认规则将跟踪每秒的第一个请求,以及任何额外请求中的 10%。
在本地定义规则的缺点是,每个记录器实例将独立应用固定目标,而不是由 X-Ray 服务进行管理。当您部署多台主机时,固定率将倍增,这使得记录的数据量更难控制。
在 AWS 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{}
字段 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
))
环境变量
您可以使用环境变量配置X-Ray SDK for Go。开发工具包支持以下变量。
-
AWS_XRAY_TRACING_NAME
– 设置开发工具包用于分段的服务名称。 -
AWS_XRAY_DAEMON_ADDRESS
– 设置 X-Ray 守护程序侦听器的主机和端口。默认情况下,SDK 会将跟踪数据发送到127.0.0.1:2000
。如果您已将守护程序配置为在不同的端口上侦听,或者它运行在其他主机上,请使用该变量。 -
AWS_XRAY_CONTEXT_MISSING
– 设置该值来确定开发工具包如何处理缺少上下文错误。对于在未打开任何请求时运行的启动代码或者会生成新线程的代码,如果您尝试在其中使用分析过的客户端,则可能发生与缺失分段或子分段相关的错误。-
RUNTIME_ERROR
– 默认情况下,开发工具包设置为抛出运行时异常。 -
LOG_ERROR
– 记录错误并继续。
-
环境变量覆盖在代码中设置的等效值。
使用 Configure 方法
您还可以使用 Configure
方法配置X-Ray SDK for Go。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 将使用带有error
类型的XrayError
、错误消息和堆栈跟踪的DefaultExceptionFormattingStrategy
。