本文為英文版的機器翻譯版本,如內容有任何歧義或不一致之處,概以英文版為準。
SDK為 Go 配置 X-Ray
您可以透過Configure
使用物件呼叫或假設預設值來指定 X-Ray SDK 的組Config
態,以進行環境變數。環境變數優先於 Config
值,而後者則優先於任何預設值。
服務外掛程式
用plugins
於記錄託管應用程式之服務的相關資訊。
外掛程式
Amazon EC2 —
EC2Plugin
新增執行個體 ID、可用區域和 CloudWatch 日誌群組。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",
})
}
SDK還使用插件設置來設置origin
段上的字段。這表示運行您的應用程序的 AWS 資源的類型。當您使用多個外掛程式時,SDK會使用下列解析度順序來決定原點: ElasticBeanstalk EKS> ECS > > EC2。
抽樣規則
會SDK使用您在 X-Ray 主控台中定義的取樣規則來決定要記錄哪些請求。預設規則會每秒追蹤第一個要求,而所有服務的任何其他要求的百分之五會傳送追蹤至 X-Ray。在 X-Ray 主控台中建立其他規則,以自訂為每個應用程式記錄的資料量。
會依照SDK定義規則的順序套用自訂規則。如果要求符合多個自訂規則,則只會SDK套用第一個規則。
注意
如果無法達到 X-Ray SDK 以取得取樣規則,則會回復為每秒第一個要求的預設本機規則,而每個主機的任何其他要求的百分之五。如果主機沒有呼叫取樣的權限APIs,或者無法連線至 X-Ray 精靈 (做為SDK. TCP API
您也可以配置SDK為從JSON文件載入取樣規則。對於無法使用 X-Ray 取樣的情況,SDK可以使用本機規則做為備份,或僅使用本機規則。
範例 採樣規則
{
"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 會做出取樣決策。
若要提供備份規則,請使用指向本機取樣JSON檔案NewCentralizedStrategyWithFilePath
。
範例 主要-本地抽樣規則
s, _ := sampling.NewCentralizedStrategyWithFilePath("sampling.json") // path to local sampling json
xray.Configure(xray.Config{SamplingStrategy: s})
若只要使用本機規則,請使用指向本機取樣JSON檔案NewLocalizedStrategyFromFilePath
。
範例 主. 去-禁用採樣
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 SDK 的 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
。如果您已將協助程式設定為在不同的連接埠上接聽,或是在不同的主機上執行,請使用此變數。-
AWS_XRAY_CONTEXT_MISSING
— 設定值以決定如何SDK處理遺失的前後關聯錯誤。若您嘗試在未開啟請求時於啟動程式碼中使用受檢測用戶端,或是在會產生新執行緒的程式碼中使用受檢測用戶端,就可能會發生與遺漏區段或子區段相關的錯誤。-
RUNTIME_ERROR
— 依預設,會設定SDK為擲回執行階段例外狀況。 -
LOG_ERROR
— 設定為記錄錯誤並繼續。
-
環境變數會覆寫程式碼中所設的同等值。
使用設定
您還可以使用該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
、錯誤訊息和堆疊追蹤。