本文属于机器翻译版本。若本译文内容与英语原文存在差异,则一律以英文原文为准。
配置适用于 Go 的 X-Ray 开发工具包
您可以通过环境变量、使用Config
对象调用或假设默认值来指定 X-RConfigure
ay SDK for Go 的配置。环境变量优先于 Config
值,后者又优先于任何默认值。
服务插件
plugins
用于记录有关托管您的应用程序的服务的信息。
插件
Amazon EC2 —
EC2Plugin
添加实例 ID、可用区和 CloudWatch 日志组。Elastic Beanstalk —
ElasticBeanstalkPlugin
添加环境名称、版本标签和部署 ID。亚马逊 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",
})
}
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{}
字段 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
— 设置 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