本文為英文版的機器翻譯版本,如內容有任何歧義或不一致之處,概以英文版為準。
設定適用於 Go 的 X-Ray 的開發套件
您可以指定 X-Ray SDK 的配置,通過Configure
使用Config
對象調用或假設默認值。環境變數優先於 Config
值,而後者則優先於任何預設值。
服務外掛程式
用plugins
於記錄託管應用程式之服務的相關資訊。
外掛程式
Amazon EC2 —
EC2Plugin
新增執行個體 ID、可用區域和 CloudWatch 日誌群組。Elastic Beanstalk —
ElasticBeanstalkPlugin
新增環境名稱、版本標籤和部署 ID。Amazon ECS-
ECSPlugin
添加容器 ID。
![使用 Amazon EC2 和 Elastic Beanstalk 外掛程式細分資源資料。](images/scorekeep-PUTrules-segment-resources-go.png)
若要使用外掛程式,請匯入以下其中一個套件。
"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 資源的類型。當您使用多個外掛程式時,SDK 會使用下列解析順序來判斷來源: ElasticBeanstalk > EKS > ECS > EC2。
抽樣規則
SDK 會使用您在 X-Ray 主控台中定義的取樣規則來決定要記錄的要求。預設規則會每秒追蹤第一個要求,而所有服務的任何其他要求的百分之五會傳送追蹤至 X-Ray。在 X-Ray 主控台中建立其他規則,以自訂為每個應用程式記錄的資料量。
SDK 會依定義規則的順序套用自訂規則。如果要求符合多個自訂規則,SDK 只會套用第一個規則。
注意
如果 SDK 無法到達 X-Ray 以取得取樣規則,它會回復為每秒開始收到的第一個要求的預設本機規則,而每個主機的任何其他要求的百分之五。如果主機沒有調用採樣 API 的權限,或者無法連接到 X-Ray 守護程序(作為 SDK 發出的 API 調用的 TCP 代理),則可能會發生這種情況。
您也可以將 SDK 設定為從 JSON 文件載入取樣規則。SDK 可以使用本機規則做為無法使用 X-Ray 取樣的情況的備份,或僅使用本機規則。
範例 採樣規則
{
"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 檔案。
範例 主要-本地抽樣規則
s, _ := sampling.NewCentralizedStrategyWithFilePath("sampling.json") // path to local sampling json
xray.Configure(xray.Config{SamplingStrategy: s})
若僅要使用本機規則,請使用 NewLocalizedStrategyFromFilePath
指向本機抽樣 JSON 檔案。
範例 主. 去-禁用採樣
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 使用下列介面進行記錄。在 LogLevelInfo
和以上時,預設記錄器會寫入 stdout
。
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 SDK。軟體開發套件支援以下變數。
AWS_XRAY_CONTEXT_MISSING
— 設定為當您RUNTIME_ERROR
的檢測程式碼嘗試在沒有區段開啟時記錄資料時擲回例外狀況。有效值
-
RUNTIME_ERROR
— 擲回執行階段例外狀況。 -
LOG_ERROR
— 記錄錯誤並繼續 (預設值)。 -
IGNORE_ERROR
— 忽略錯誤並繼續。
當您嘗試在沒有要求開啟時執行的啟動程式碼中使用已檢測的用戶端,或在產生新執行緒的程式碼中使用已檢測的用戶端時,可能會發生與遺失區段或子區段相關的錯誤。
-
-
AWS_XRAY_TRACING_NAME
— 設定 SDK 用於區段的服務名稱。 AWS_XRAY_DAEMON_ADDRESS
— 設定 X-Ray 精靈監聽程式的主機和連接埠。依預設,SDK 會將追蹤資料傳送至127.0.0.1:2000
。如果您已將協助程式設定為在不同的連接埠上接聽,或是在不同的主機上執行,請使用此變數。
環境變數會覆寫程式碼中所設的同等值。
使用設定
您還可以使用該Configure
方法為 Go 配置 X-Ray SDK。 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 是否流段。如果未指定,X-Ray 會在子區段數目大於 20 時使用串流取樣線段。DefaultStreamingStrategy
- ExceptionFormattingStrategy
-
此
ExceptionFormattingStrategy
物件可指定您要如何處理各種例外狀況。如果未指定,X-Ray 會使DefaultExceptionFormattingStrategy
用 aXrayError
類型error
、錯誤訊息和堆疊追蹤。