AWS SDK for Java
開発者ガイド

エンタープライズサポートの AWS SDK メトリクス を有効にする

エンタープライズサポートの AWS SDK メトリクス (SDK のメトリクス) を使用すると、エンタープライズのお客様は AWS Enterprise Support で共有しているホストおよびクライアントで AWS SDK からメトリクスを収集できます。SDK のメトリクス は、AWS Enterprise Support のお客様のために、AWS のサービスへの接続に伴う問題の迅速な検出と診断に役立つ情報を提供します。

テレメトリは、各ホストで収集されると、UDP 経由で 127.0.0.1 (localhost) に中継され、そこで CloudWatch エージェントによって集約されて SDK のメトリクス サービスに送信されます。したがって、メトリクスを受信するには、CloudWatch エージェントがインスタンスに追加されている必要があります。

次の SDK のメトリクス のセットアップ手順は、AWS SDK for Java を使用しているクライアントアプリケーションで、Amazon Linux を実行している Amazon EC2 インスタンスに該当します。SDK のメトリクス は、AWS SDK for Java の設定時に有効にすることで、本番稼働用環境でも使用できます。

SDK のメトリクス を使用するには、最新バージョンの CloudWatch エージェントを実行します。詳細については、「SDK メトリクス用に CloudWatch エージェントを設定する」 (Amazon CloudWatch User Guide) を参照してください。

AWS SDK for Java で SDK のメトリクス をセットアップするには、以下の手順に従います。

  1. AWS SDK for Java クライアントで、AWS のサービスを使用するためのアプリケーションを作成します。

  2. Amazon EC2 インスタンスまたはローカル環境でプロジェクトをホストします。

  3. 最新の 1.x バージョンの AWS SDK for Java をインストールして使用します。

  4. EC2 インスタンスまたはローカル環境に CloudWatch エージェントをインストールして設定します。

  5. メトリクスを収集して送信することを SDK のメトリクス に許可します。

  6. AWS SDK for Java の SDK メトリクスを有効化します。

詳細については、以下を参照してください。

AWS SDK for Java の SDK のメトリクス を有効にする

デフォルトでは、SDK のメトリクス はオフになっており、ポートは 31000 に設定されています。デフォルトのパラメータは以下のとおりです。

//default values [ 'enabled' => false, 'port' => 31000, ]

SDK のメトリクス の有効化は、AWS のサービスを使用するように認証情報を設定することとは無関係です。

4 つのオプションのいずれかを使用して SDK のメトリクス を有効にできます。

オプション 1: コードで SDK のメトリクス を設定する

Java 実装により、サービスクライアントを構築する際にコード内に SDK のメトリクス 設定を設定できます。コードで設定した値は、以下で説明する他のオプションで設定された設定を上書きします。

CsmConfiguration csmConfig = new CsmConfiguration(true, MY_PORT, MY_CLIENT_ID); AmazonDynamoDB dynamodb = AmazonDynamoDBClientBuilder.standard() .withClientSideMonitoringConfigurationProvider(new StaticCsmConfigurationProvider(csmConfig)) .build();

オプション 2: 環境変数を設定する

AWS_CSM_ENABLED が設定されていない場合、SDK では、最初に AWS_PROFILE で環境変数に指定されているプロファイルをチェックし、SDK のメトリクス が有効になっているかどうかを確認します。デフォルトでは、false に設定されています。

SDK のメトリクス をオンにするには、環境変数に次のコードを追加します。

export AWS_CSM_ENABLED=true

その他の構成設定が使用可能になります。

注意: SDK のメトリクス を有効にすることは、AWS のサービスを使用するように認証情報を設定することとは無関係です。

オプション 3: Java システムプロパティを設定する

環境変数で SDK のメトリクス 設定が見つからない場合、SDK は特定の Java システムプロパティを参照します。

アプリケーションを実行する際に、SDK のメトリクス で次のシステムプロパティフラグを渡すには

-Dcom.amazonaws.sdk.csm.enabled="true"

Properties オブジェクトを使用して、プログラムで値を設定することもできます。

Properties props = System.getProperties(); props.setProperty("com.amazonaws.sdk.csm.enabled", "true");

その他の構成設定が使用可能になります。

注意: SDK のメトリクス を有効にすることは、AWS のサービスを使用するように認証情報を設定することとは無関係です。

オプション 4: AWS 共有 Config ファイル

環境変数内に SDK のメトリクス 設定が見つからず、Java システムプロパティも見つからない場合、SDK はデフォルトの AWS プロファイルフィールドを探します。AWS_DEFAULT_PROFILE がデフォルト以外の値に設定されている場合は、そのプロファイルを更新します。SDK のメトリクス を有効にするには、~/.aws/config にある共有 config ファイルに csm_enabled を追加します。

[default] csm_enabled = true [profile aws_csm] csm_enabled = true

その他の構成設定が使用可能になります。

注意: SDK のメトリクス の有効化は、AWS のサービスを使用するように認証情報を設定することとは無関係です。認証には別のプロファイルを使用できます。

CloudWatch エージェントを更新する

ポートを変更するには、値を設定して、現在アクティブになっている AWS ジョブを再起動する必要があります。

オプション 1: 環境変数を設定する

ほとんどのサービスではデフォルトポートを使用します。ただし、サービスで一意のポート ID が必要な場合は、AWS_CSM_PORT=[port_number] をホストの環境変数に追加します。

export AWS_CSM_ENABLED=true export AWS_CSM_PORT=1234

オプション 2: Java システムプロパティを設定する

ほとんどのサービスではデフォルトポートを使用します。ただし、サービスで一意のポート ID が必要な場合、アプリケーションの実行時に -Dcom.amazonaws.sdk.csm.port=[port_number] システムプロパティフラグを指定できます。

com.amazonaws.sdk.csm.enabled=true com.amazonaws.sdk.csm.port=1234

オプション 3: AWS 共有 Config ファイル

ほとんどのサービスではデフォルトポートを使用します。ただし、サービスで一意のポート ID が必要な場合は、csm_port = [port_number]~/.aws/config に追加します。

[default] csm_enabled = false csm_port = 1234 [profile aws_csm] csm_enabled = false csm_port = 1234

SDK のメトリクス を再起動する

ジョブを再起動するには、以下のコマンドを実行します。

amazon-cloudwatch-agent-ctl –a stop; amazon-cloudwatch-agent-ctl –a start;

SDK のメトリクス を無効にする

SDK のメトリクス をオフにするには、環境変数または ~/.aws/config にある AWS 共有 config ファイルで csm_enabledfalse に設定します。次に、CloudWatch エージェントを再起動して変更を反映します。

環境変数

export AWS_CSM_ENABLED=false

AWS 共有 Config ファイル

~/.aws/config にある AWS 共有 config ファイルのプロファイルから csm_enabled を削除します。

注記

環境変数により AWS 共有 config ファイルが上書きされます。環境変数で SDK のメトリクス が有効になっている場合、SDK のメトリクス は有効なままになります。

[default] csm_enabled = false [profile aws_csm] csm_enabled = false

SDK のメトリクス を無効にするには、次のコマンドを使用して CloudWatch エージェントを停止します。

sudo /opt/aws/amazon-cloudwatch-agent/bin/amazon-cloudwatch-agent-ctl -a stop && echo "Done"

CloudWatch の他の機能を使用している場合は、次のコマンドを使用して CloudWatch エージェントを再起動します。

amazon-cloudwatch-agent-ctl –a start;

SDK のメトリクス を再起動する

SDK のメトリクス を再起動するには、以下のコマンドを実行します。

amazon-cloudwatch-agent-ctl –a stop; amazon-cloudwatch-agent-ctl –a start;

SDK のメトリクス の定義

SDK のメトリクス の以下の説明を参考にして結果を解釈できます。通常、これらのメトリクスは定期的なビジネスレビューでテクニカルアカウントマネージャーによるレビューに使用できます。AWS サポートのリソースおよびテクニカルアカウントマネージャーは、問題が発生したときに SDK メトリクスのデータにアクセスして解決に役立てることができますが、紛らわしいデータや予期しないデータを検出した場合は、アプリケーションのパフォーマンスに悪影響がなくても、スケジュールされたビジネスレビューで該当するデータを確認することをお勧めします。

メトリクス: CallCount

定義

コードから AWS のサービスへの、成功または失敗した API コールの総数

使用方法

エラーやスロットリングなどの他のメトリクスと相関させるためのベースラインとして使用します。

メトリクス: ClientErrorCount

定義

クライアントエラー (4xx HTTP 応答コード) で失敗した API コールの数。例: スロットリング、アクセス拒否、S3 バケットが存在しない、無効なパラメータ値など。

使用方法

スロットリングに関連する特定の問題 (引き上げを要する制限のせいでスロットリングが発生した場合など) を除いて、このメトリクスは、アプリケーションに修正を要する問題があることを示している可能性があります。

メトリクス: ConnectionErrorCount

定義

サービスへの接続エラーにより失敗した API コールの数。これらは、お客様のアプリケーションと AWS のサービスとのネットワーク問題 (ロードバランサー、DNS の障害、トランジットプロバイダーなど) が原因で生じた可能性があります。AWS の問題が原因で、このエラーが発生する場合もあります。

使用方法

このメトリクスを使用して、問題の原因がアプリケーションにあるか、インフラストラクチャやネットワークにあるかを判断します。ConnectionErrorCount の値が大きい場合、原因として API コールのタイムアウト値が短いことも考えられます。

メトリクス: ThrottleCount

定義

AWS のサービスのスロットリングに伴って失敗した API コールの数。

使用方法

このメトリクスを使用して、アプリケーションがスロットリング制限に達したかどうかを評価したり、再試行やアプリケーションのレイテンシーの原因を判断したりします。コールをまとめて処理するのではなく、期間全体に分散させることを検討します。

メトリクス: ServerErrorCount

定義

AWS のサービスのサーバーエラー (5xx HTTP 応答コード) に伴って失敗した API コールの数。通常、これらの問題の原因は AWS のサービスにあります。

使用方法

SDK の再試行やレイテンシーの原因を判断します。このメトリクスは必ずしも AWS のサービスに障害があることを示すとは限りません。一部の AWS チームでは、レイテンシーを HTTP 503 応答として分類する場合があります。

メトリクス: EndToEndLatency

定義

アプリケーションが AWS SDK を使用してコールを行う合計時間 (再試行を含む)。つまり、数回の試行後に成功したかどうかや、取得不能エラーですぐに失敗したかどうかは関係ありません。

使用方法

AWS の API コールがアプリケーションのレイテンシー全体にどの程度影響しているかを判断します。予期された以上にレイテンシーが高い場合、問題の原因はネットワーク、ファイアウォール、その他の設定にあるか、SDK の再試行の結果として発生するレイテンシーにある可能性があります。