X-Ray SDK for Goの設定

環境変数を使って X-Ray SDK for Go の設定を指定するには、Config オブジェクトで Configure を呼び出すか、デフォルト値を使用します。環境変数は Config 値よりも優先されます。これはデフォルト値よりも優先されます。

サービスプラグイン

pluginsを使用して、アプリケーションをホストしているサービスに関する情報を記録します。

プラグイン

• Amazon EC2 — インスタンス ID、アベイラビリティーゾーン、EC2Plugin CloudWatch およびロググループを追加します。

• ElasticBeanstalk– 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 は > EKS > ECS ElasticBeanstalk > EC2 の解決順序を使用してオリジンを判断します。

サンプリングルール

SDK は X-Ray コンソールで定義したサンプリングルールを使用し、記録するリクエストを決定します。デフォルトルールでは、最初のリクエストを毎秒トレースし、X-Ray にトレースを送信するすべてのサービスで追加のリクエストの 5% をトレースします。X-Ray コンソールに追加のルールを作成するをクリックして、各アプリケーションで記録されるデータ量をカスタマイズします。

SDK は、定義された順序でカスタムルールを適用します。リクエストが複数のカスタムルールと一致する場合、SDK は最初のルールのみを適用します。

注記

SDK が X-Ray に到達してサンプリングルールを取得できない場合、1 秒ごとに最初のリクエストのデフォルトのローカルルールに戻り、ホストあたりの追加リクエストの 5% に戻ります。これは、ホストがサンプリング API を呼び出す権限を持っていない場合や、SDK によって行われる API 呼び出しの TCP プロキシとして機能する X-Ray デーモンに接続できない場合に発生します。

JSON ドキュメントからサンプリングルールをロードするように SDK を設定することもできます。SDK は、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
  }
}

この例では、1 つのカスタムルールとデフォルトルールを定義します。カスタムルールでは、5 パーセントのサンプリングレートが適用され、/api/move/以下のパスに対してトレースするリクエストの最小数はありません。デフォルトのルールでは、1秒ごとの最初のリクエストおよび追加リクエストの 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})

ログ記録

注記

xray.Config{} フィールド LogLevel と LogFormat は、バージョン 1.0.0-rc.10 以降では非推奨です。

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))

環境変数

X-Ray SDK for Goの設定 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。この変数は、デーモンを次のように構成している場合に使用します。別のポートでリッスンするまたは、別のホストで実行されている場合。

環境変数は、コードで設定される同等の値を上書きします。

設定の使用

X-Ray SDK for Go を Configure を使用して設定することもできます。Configureは、1 つの引数､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このオブジェクトは true RequiresStreamingを返したときにセグメントをストリーミングするかどうかを指定します。指定しない場合、X-Ray は、サブセグメントの数が 20 を超える場合、サンプリングされたセグメントをストリーミングする DefaultStreamingStrategy を使用します。

ExceptionFormattingStrategy

この ExceptionFormattingStrategy オブジェクトは、さまざまな例外を処理する方法を指定します。指定しない場合、X-Ray は、タイプ DefaultExceptionFormattingStrategy の XrayError、エラーメッセージ、およびスタックトレースを持つ error を使用します。