翻訳は機械翻訳により提供されています。提供された翻訳内容と英語版の間で齟齬、不一致または矛盾がある場合、英語版が優先します。 # X-Ray SDK for Goの設定 **注記** X-Ray SDK/デーモンメンテナンス通知 – 2026 年 2 月 25 日、 AWS X-Ray SDKs/Daemon はメンテナンスモードに移行します。 AWS では、X-Ray SDK とデーモンのリリースがセキュリティの問題にのみ対処するように制限されます。サポートタイムラインの詳細については、「[X-Ray SDK とデーモンのサポートタイムライン](xray-sdk-daemon-timeline.md)」を参照してください。OpenTelemetry に移行することをお勧めします。OpenTelemetry への移行の詳細については、「[X-Ray による計装から OpenTelemetry による計装への移行](https://docs.aws.amazon.com/xray/latest/devguide/xray-sdk-migration.html)」を参照してください。 環境変数を使って X-Ray SDK for Go の設定を指定するには、`Config` オブジェクトで `Configure` を呼び出すか、デフォルト値を使用します。環境変数は `Config` 値よりも優先されます。これはデフォルト値よりも優先されます。 **Topics** + [サービスプラグイン](#xray-sdk-go-configuration-plugins) + [サンプリングルール](#xray-sdk-go-configuration-sampling) + [ログ記録](#xray-sdk-go-configuration-logging) + [環境変数](#xray-sdk-go-configuration-envvars) + [設定の使用](#xray-sdk-go-configuration-configure) ## サービスプラグイン `plugins`を使用して、アプリケーションをホストしているサービスに関する情報を記録します。 **プラグイン** + Amazon EC2 —`EC2Plugin`は、インスタンス ID、アベイラビリティーゾーン、および CloudWatch Logs グループを追加します。 + ElasticBeanstalk– `ElasticBeanstalkPlugin`は、環境名、バージョンラベル、およびデプロイ ID を追加します。 + Amazon ECS —`ECSPlugin`は、コンテナ ID を追加します。 ![](http://docs.aws.amazon.com/ja_jp/xray/latest/devguide/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()` 関数呼び出しがあります。 **Example 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 にトレースを送信するすべてのサービスで追加のリクエストの 5% をトレースします。[X-Ray コンソールに追加のルールを作成する](xray-console-sampling.md)をクリックして、各アプリケーションで記録されるデータ量をカスタマイズします。 SDK は、定義された順序でカスタムルールを適用します。リクエストが複数のカスタムルールと一致する場合、SDK は最初のルールのみを適用します。 **注記** SDK が X-Ray に到達してサンプリングルールを取得できない場合、1 秒ごとに最初のリクエストのデフォルトのローカルルールに戻り、ホストあたりの追加リクエストの 5% に戻ります。これは、ホストがサンプリング API を呼び出す権限を持っていない場合や、SDK によって行われる API 呼び出しの TCP プロキシとして機能する X-Ray デーモンに接続できない場合に発生します。 JSON ドキュメントからサンプリングルールをロードするように SDK を設定することもできます。SDK は、X-Ray サンプリングが利用できない場合のバックアップとしてローカルルールを使用することも、ローカルルールを排他的に使用することもできます。 **Example 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 ファイルのローカルサンプリングを指定します。 **Example main.go – ローカルサンプリングルール** ``` s, _ := sampling.NewCentralizedStrategyWithFilePath("sampling.json") // path to local sampling json xray.Configure(xray.Config{SamplingStrategy: s}) ``` ローカルルールのみを使用するには、`NewLocalizedStrategyFromFilePath` を使用して JSON ファイルのローカルサンプリングを指定します。 **Example 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 ) ``` **Example `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`。この変数は、デーモンを次のように構成している場合に使用します。[別のポートでリッスンする](xray-daemon-configuration.md)または、別のホストで実行されている場合。 + `AWS_XRAY_CONTEXT_MISSING` – 値を設定して、SDK がコンテキスト欠落エラーをどのように処理するかを決定します。オープン状態のリクエストがない場合、または新しいスレッドを発生させるコードで、スタートアップコードに実装されたクライアントを使用しようとした場合に発生する可能性がある、セグメントまたはサブセグメントの欠落に関連するエラー。 + `RUNTIME_ERROR` – デフォルトでは、SDK はランタイムの例外をスローするように設定されています。 + `LOG_ERROR` – エラーを記録して続行します。 環境変数は、コードで設定される同等の値を上書きします。 ## 設定の使用 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` オブジェクトは、**RequiresStreaming** が **true** を返すときにセグメントをストリーミングするかどうかを指定します。指定しない場合、X-Ray は、サブセグメントの数が 20 を超える場合、サンプリングされたセグメントをストリーミングする `DefaultStreamingStrategy` を使用します。 ExceptionFormattingStrategy この `ExceptionFormattingStrategy` オブジェクトは、さまざまな例外を処理する方法を指定します。指定しない場合、X-Ray は、タイプ `DefaultExceptionFormattingStrategy` の `XrayError`、エラーメッセージ、およびスタックトレースを持つ `error` を使用します。