CloudWatch エージェントの一般的なシナリオ
以下のセクションでは、CloudWatch エージェントの一般的な設定と、カスタマイズタスクを完了する方法についての概要を説明します。
トピック
CloudWatch エージェントの別のユーザーとしての実行
Linux サーバーでは、CloudWatch はデフォルトで root ユーザーとして実行されます。エージェントを別のユーザーとして実行するには、CloudWatch エージェント設定ファイルの agent
セクションで run_as_user
パラメータを使用します。このオプションは、Linux サーバーでのみ使用できます。
エージェントを root ユーザーとして既に実行している場合、別のユーザーに変更するには、以下のいずれかの手順を使用します。
Linux を実行する EC2 インスタンスで CloudWatch エージェントを別のユーザーとして実行するには
新しい CloudWatch エージェントパッケージをダウンロードしてインストールします。詳細については、「CloudWatch エージェントパッケージをダウンロードする」を参照してください。
新しい Linux ユーザーを作成するか、RPM ファイルまたは DEB ファイルで作成した
cwagent
という名前のデフォルトユーザーを使用します。次のいずれかの方法で、このユーザーの認証情報を指定します。
このファイル
.aws/credentials
が root ユーザーのホームディレクトリに存在する場合は、CloudWatch エージェントの実行に使用するユーザーの認証情報ファイルを作成する必要があります。この認証情報ファイルは/home/
になります。次に、username
/.aws/credentialsshared_credential_file
のcommon-config.toml
パラメータの値を認証情報ファイルのパス名に設定します。詳細については、「(オプション) プロキシ情報またはリージョン情報の一般的な設定を変更する」を参照してください。ファイル
.aws/credentials
が root ユーザーのホームディレクトリに存在しない場合は、次のいずれかの操作を実行できます。CloudWatch エージェントの実行に使用するユーザーの認証情報ファイルを作成します。この認証情報ファイルは
/home/
になります。次に、username
/.aws/credentialsshared_credential_file
のcommon-config.toml
パラメータの値を認証情報ファイルのパス名に設定します。詳細については、「(オプション) プロキシ情報またはリージョン情報の一般的な設定を変更する」を参照してください。認証情報ファイルを作成する代わりに、IAM ロールをインスタンスにアタッチします。エージェントは、このロールを認証情報プロバイダーとして使用します。
CloudWatch エージェント設定ファイルで、
agent
セクションに次の行を追加します。"run_as_user": "
username
"必要に応じて、設定ファイルに他の変更を行います。詳細については、「CloudWatch エージェント設定ファイルを作成する」を参照してください。
必要なアクセス許可をユーザーに付与します。ユーザーには、収集するログファイルの読み取り (r) アクセス許可と、ログファイルのパス内のすべてのディレクトリに対する実行 (x) アクセス許可が必要です。
先ほど作成した設定ファイルを使用してエージェントを起動します。
sudo /opt/aws/amazon-cloudwatch-agent/bin/amazon-cloudwatch-agent-ctl -a fetch-config -m ec2 -s -c file:
configuration-file-path
Linux を実行しているオンプレミスサーバーで CloudWatch エージェントを別のユーザーとして実行するには
新しい CloudWatch エージェントパッケージをダウンロードしてインストールします。詳細については、「CloudWatch エージェントパッケージをダウンロードする」を参照してください。
新しい Linux ユーザーを作成するか、RPM ファイルまたは DEB ファイルで作成した
cwagent
という名前のデフォルトユーザーを使用します。このユーザーの認証情報をユーザーがアクセスできるパス (
/home/
など) に保存します。username
/.aws/credentialsshared_credential_file
のcommon-config.toml
パラメータの値を認証情報ファイルのパス名に指定します。詳細については、「(オプション) プロキシ情報またはリージョン情報の一般的な設定を変更する」を参照してください。CloudWatch エージェント設定ファイルで、
agent
セクションに次の行を追加します。"run_as_user": "
username
"必要に応じて、設定ファイルに他の変更を行います。詳細については、「CloudWatch エージェント設定ファイルを作成する」を参照してください。
必要なアクセス許可をユーザーに付与します。ユーザーには、収集するログファイルの読み取り (r) アクセス許可と、ログファイルのパス内のすべてのディレクトリに対する実行 (x) アクセス許可が必要です。
先ほど作成した設定ファイルを使用してエージェントを起動します。
sudo /opt/aws/amazon-cloudwatch-agent/bin/amazon-cloudwatch-agent-ctl -a fetch-config -m ec2 -s -c file:
configuration-file-path
CloudWatch エージェントがスパースログファイルを処理する方法
スパースファイルは、空のブロックと実際のコンテンツの両方を持つファイルです。スパースファイルは、ブロックを構成する実際の null バイトの代わりに、空のブロックを表す簡単な情報をディスクに書き込むことによって、より効率的にディスク領域を使用します。これにより、スパースファイルの実際のサイズは、通常、見かけのサイズよりもずっと小さくなります。
ただし、CloudWatch エージェントはスパースファイルを通常のファイルと同じ方法で処理します。エージェントがスパースファイルを読み取ると、空のブロックは null バイトで満たされた「実」ブロックとして扱われます。このため、CloudWatch エージェントは、スパースファイルの見かけ上のサイズと同じバイト数を CloudWatch に発行します。
スパースファイルを発行するように CloudWatch エージェントを設定すると、予想よりも CloudWatch コストが高くなる可能性があるため、この設定を避けるようお勧めします。例えば、Linux の /var/logs/lastlog
は非常にスパースなファイルであることが多いため、これを CloudWatch に発行しないようお勧めします。
CloudWatch エージェントにより収集されるメトリクスへのカスタムディメンションの追加
エージェントによって収集されるメトリクスにタグなどのカスタムディメンションを追加するには、それらのメトリクスをリストするエージェント設定ファイルのセクションに append_dimensions
フィールドを追加します。
たとえば、設定ファイルの次のサンプルセクションでは、値が stackName
の Prod
というカスタムディメンションを、エージェントによって収集される cpu
および disk
メトリクスに追加します。
"cpu":{ "resources":[ "*" ], "measurement":[ "cpu_usage_guest", "cpu_usage_nice", "cpu_usage_idle" ], "totalcpu":false, "append_dimensions":{ "stackName":"Prod" } }, "disk":{ "resources":[ "/", "/tmp" ], "measurement":[ "total", "used" ], "append_dimensions":{ "stackName":"Prod" } }
エージェント設定ファイルを変更するときは必ず、エージェントを再起動して変更を有効にする必要がある点に注意してください。
CloudWatch エージェント設定ファイル
Linux サーバーと Windows サーバーの両方で、複数の設定ファイルを使用するように CloudWatch エージェントを設定できます。例えば、インフラストラクチャ内のすべてのサーバーから常に収集する一連のメトリクス、ログ、およびトレースを収集する共通の設定ファイルを使用できます。その後、追加の設定ファイルを使用して、特定のアプリケーションから、または特定の状況でメトリクスを収集することができます。
これを設定するには、まず使用する設定ファイルを作成します。同じサーバー上で一緒に使用される設定ファイルは、異なるファイル名を持つ必要があります。設定ファイルは、サーバー上または Parameter Store に保存できます。
fetch-config
オプションを使って CloudWatch エージェントを開始し、1 つ目の設定ファイルを指定します。エージェントの実行の 2 つ目の設定ファイルを追加するには、同じコマンドを使用しますが、append-config
オプションを使います。いずれかの設定ファイルにリストされている、すべてのメトリクス、ログ、トレースが収集されます。次のコマンドは、このシナリオで設定ストアをファイルとして使用した例を示しています。1 行目で infrastructure.json
設定ファイルを使ってエージェントを開始し、2 行目で app.json
設定ファイルを追加しています。
次のサンプルコマンドは、Linux 用です。
/opt/aws/amazon-cloudwatch-agent/bin/amazon-cloudwatch-agent-ctl -a fetch-config -m ec2 -s -c file:/tmp/infrastructure.json
/opt/aws/amazon-cloudwatch-agent/bin/amazon-cloudwatch-agent-ctl -a append-config -m ec2 -s -c file:/tmp/app.json
次のコマンドは Windows Server 用です。
& "C:\Program Files\Amazon\AmazonCloudWatchAgent\amazon-cloudwatch-agent-ctl.ps1" -a fetch-config -m ec2 -s -c file:"C:\Program Files\Amazon\AmazonCloudWatchAgent\infrastructure.json"
& "C:\Program Files\Amazon\AmazonCloudWatchAgent\amazon-cloudwatch-agent-ctl.ps1" -a append-config -m ec2 -s -c file:"C:\Program Files\Amazon\AmazonCloudWatchAgent\app.json"
次の設定ファイルは、この機能の使用方法の例を示しています。1 つ目の設定ファイルは、インフラストラクチャ内のすべてのサーバーに使用され、2 つ目の設定ファイルは、特定のアプリケーションからのログのみを収集し、そのアプリケーションを実行しているサーバーに追加されています。
infrastructure.json
{ "metrics": { "metrics_collected": { "cpu": { "resources": [ "*" ], "measurement": [ "usage_active" ], "totalcpu": true }, "mem": { "measurement": [ "used_percent" ] } } }, "logs": { "logs_collected": { "files": { "collect_list": [ { "file_path": "/opt/aws/amazon-cloudwatch-agent/logs/amazon-cloudwatch-agent.log", "log_group_name": "amazon-cloudwatch-agent.log" }, { "file_path": "/var/log/messages", "log_group_name": "/var/log/messages" } ] } } } }
app.json
{ "logs": { "logs_collected": { "files": { "collect_list": [ { "file_path": "/app/app.log*", "log_group_name": "/app/app.log" } ] } } } }
設定に追加される設定ファイルは、互いに異なるファイル名を持つ必要があり、また初期の設定ファイルと異なるファイル名を持つ必要があります。エージェントで既に使用されている設定ファイルと同じファイル名の設定ファイルで append-config
を使用した場合、その append コマンドでは追加は行われず、1 つ目の設定ファイルの情報は上書きされます。これは、同じファイル名の 2 つの設定ファイルが異なるファイルパスにある場合でも同様です。
前の例では、2 つの設定ファイルを使用していますが、エージェント設定に追加できる設定ファイルの数に制限はありません。サーバー上にある設定ファイルと Parameter Store にある設定を混在させることもできます。
CloudWatch エージェントによって収集されるメトリクスの集約またはロールアップ
エージェントにより収集されたメトリクスを集約 (ロールアップ) するには、aggregation_dimensions
フィールドをエージェント設定ファイル内のそのメトリクスのセクションに追加します。
たとえば、次の設定ファイルスニペットでは、AutoScalingGroupName
ディメンションでメトリクスをロールアップします。各 Auto Scaling グループ内のすべてのインスタンスのメトリクスが集約され、全体として参照できるようになります。
"metrics": { "cpu":{...} "disk":{...} "aggregation_dimensions" : [["AutoScalingGroupName"]] }
Auto Scaling グループ名でのロールアップのほかに、各 InstanceId
および InstanceType
ディメンションの組み合わせでもロールアップするには、次の内容を追加します。
"metrics": { "cpu":{...} "disk":{...} "aggregation_dimensions" : [["AutoScalingGroupName"], ["InstanceId", "InstanceType"]] }
代わりにメトリクスを 1 つのコレクションにロールアップするには、[]
を使用します。
"metrics": { "cpu":{...} "disk":{...} "aggregation_dimensions" : [[]] }
エージェント設定ファイルを変更するときは必ず、エージェントを再起動して変更を有効にする必要がある点に注意してください。
CloudWatch エージェントを使用した高解像度メトリクスの収集
metrics_collection_interval
フィールドは、収集されるメトリクスの時間間隔 (秒単位) を指定します。このフィールドに 60 未満の値を指定することによって、メトリクスは、高解像度メトリクスとして収集されます。
たとえば、すべてのメトリクスを高解像度で 10 秒ごとに収集する必要がある場合は、metrics_collection_interval
セクションで、グローバルメトリクス収集間隔として agent
の値を 10 に指定します。
"agent": { "metrics_collection_interval": 10 }
または、次の例では cpu
メトリクスを 1 秒ごとに収集し、他のすべてのメトリクスを 1 分ごとに収集するように設定します。
"agent":{ "metrics_collection_interval": 60 }, "metrics":{ "metrics_collected":{ "cpu":{ "resources":[ "*" ], "measurement":[ "cpu_usage_guest" ], "totalcpu":false, "metrics_collection_interval": 1 }, "disk":{ "resources":[ "/", "/tmp" ], "measurement":[ "total", "used" ] } } }
エージェント設定ファイルを変更するときは必ず、エージェントを再起動して変更を有効にする必要がある点に注意してください。
別のアカウントへのメトリクス、ログ、トレースの送信
CloudWatch エージェントがメトリクス、ログ、またはトレースを別のアカウントに送信するには、送信サーバーのエージェント設定ファイルで role_arn
パラメータを指定します。role_arn
値は、エージェントがターゲットアカウントにデータを送信する際に使用するターゲットアカウントの IAM ロールを指定します。このロールにより、メトリクスまたはログをターゲットアカウントに配信するときに、送信アカウントがターゲットアカウントの対応するロールを担うことができます。
エージェント設定ファイルには、個別の role_arn
文字列を指定することもできます。1 つはメトリクスを送信するときに、1 つはログを送信するために、もう 1 つはトレースを送信するために使用します。
次の設定ファイルの agent
セクションの一部の例は、データを別のアカウントに送信するときにエージェントが CrossAccountAgentRole
を使用するように設定します。
{ "agent": { "credentials": { "role_arn": "arn:aws:iam::123456789012:role/CrossAccountAgentRole" } }, ..... }
または、次の例では、送信アカウントがメトリクス、ログ、トレースを送信するために使用する別々のロールを設定しています。
"metrics": { "credentials": { "role_arn": "RoleToSendMetrics" }, "metrics_collected": {....
"logs": { "credentials": { "role_arn": "RoleToSendLogs" }, ....
必要なポリシー
エージェント設定ファイルで role_arn
を指定する場合は、送信アカウントとターゲットアカウントの IAM ロールに特定のポリシーが設定されていることも確認する必要があります。送信アカウントとターゲットアカウントの両方のロールに、[CloudWatchAgentServerPolicy
] が必要です。このポリシーをロールに割り当てる方法の詳細については、「Amazon EC2 インスタンスの CloudWatch エージェントで使用する IAM ロールを作成する」を参照してください。
また、送信側アカウントのロールに次のポリシーも含まれている必要があります。このポリシーは、ロールを編集するときに IAM コンソールの [アクセス許可] タブで追加します。
{ "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "sts:AssumeRole" ], "Resource": [ "arn:aws:iam::
target-account-ID
:role/agent-role-in-target-account
" ] } ] }
また、ターゲットアカウントのロールには、送信側アカウントで使用される IAM ロールを認識できるように、次のポリシーが含まれている必要があります。このポリシーは、ロールを編集するときに IAM コンソールの [信頼関係] タブで追加します。このポリシーを追加するターゲットアカウントのロールは、CloudWatch エージェントで使用する IAM ロールとユーザーを作成する で作成したロールです。このロールは、送信側アカウントで使用されるポリシーの
で指定したロールです。agent-role-in-target-account
{ "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Principal": { "AWS": [ "arn:aws:iam::
sending-account-ID
:role/role-in-sender-account
" ] }, "Action": "sts:AssumeRole" } ] }
統合 CloudWatch エージェントと前の CloudWatch Logs エージェントの間のタイムスタンプの違い
CloudWatch エージェントでは、前の CloudWatch Logs エージェントと比べて、タイムスタンプ形式のさまざまな記号のセットがサポートされています。これらの違いを次の表に示します。
両方のエージェントがサポートする記号 | 統合 CloudWatch エージェントのみがサポートする記号 | 前の CloudWatch Logs エージェントでのみサポートされている記号 |
---|---|---|
%A、%a、%b、%B、%d、%f、%H、%l、%m、%M、%p、%S、%y、%Y、%Z、%z |
%-d、%-l、%m、%M、%-S |
%c、% j、%U、%W、%w |
新しい CloudWatch エージェントでサポートされる記号の意味の詳細については、Amazon CloudWatch ユーザーガイドの「CloudWatch エージェント設定ファイル: ログセクション」を参照してください。CloudWatch Logs エージェントでサポートされる記号については、Amazon CloudWatch Logs ユーザーガイドの「エージェント設定ファイル」を参照してください。