# CloudWatch エージェントの一般的なシナリオ
このセクションでは、CloudWatch エージェントに共通する設定とカスタマイズのタスクを完了する方法をまとめたさまざまなシナリオについて説明します。
**Topics**
+ [CloudWatch エージェントの別のユーザーとしての実行](#CloudWatch-Agent-run-as-user)
+ [CloudWatch エージェントがスパースログファイルを処理する方法](#CloudWatch-Agent-sparse-log-files)
+ [CloudWatch エージェントにより収集されるメトリクスへのカスタムディメンションの追加](#CloudWatch-Agent-adding-custom-dimensions)
+ [CloudWatch エージェントによって収集されるメトリクスの集約またはロールアップ](#CloudWatch-Agent-aggregating-metrics)
+ [CloudWatch エージェントを使用した高解像度メトリクスの収集](#CloudWatch-Agent-collect-high-resolution-metrics)
+ [別のアカウントへのメトリクス、ログ、トレースの送信](#CloudWatch-Agent-send-to-different-AWS-account)
+ [CloudWatch エージェントと前の CloudWatch Logs エージェントとの間のタイムスタンプの違い](#CloudWatch-Agent-logs-timestamp-differences)
+ [OpenTelemetry コレクター設定ファイルの追加](#CloudWatch-Agent-appending-OpenTelemetry-config-files)
## CloudWatch エージェントの別のユーザーとしての実行
Linux サーバーでは、CloudWatch はデフォルトで root ユーザーとして実行されます。エージェントを別のユーザーとして実行するには、CloudWatch エージェント設定ファイルの `agent` セクションで `run_as_user` パラメータを使用します。このオプションは、Linux サーバーでのみ使用できます。
エージェントを root ユーザーとして既に実行している場合、別のユーザーに変更するには、以下のいずれかの手順を使用します。
**Linux を実行する EC2 インスタンスで CloudWatch エージェントを別のユーザーとして実行するには**
1. 新しい CloudWatch エージェントパッケージをダウンロードしてインストールします。
1. 新しい Linux ユーザーを作成するか、RPM ファイルまたは DEB ファイルで作成した `cwagent` という名前のデフォルトユーザーを使用します。
1. 次のいずれかの方法で、このユーザーの認証情報を指定します。
+ このファイル `.aws/credentials` が root ユーザーのホームディレクトリに存在する場合は、CloudWatch エージェントの実行に使用するユーザーの認証情報ファイルを作成する必要があります。この認証情報ファイルは `/home/username/.aws/credentials` になります。次に、`shared_credential_file` の `common-config.toml` パラメータの値を認証情報ファイルのパス名に設定します。詳細については、「[AWS Systems Manager を使用して CloudWatch エージェントをインストールする](installing-cloudwatch-agent-ssm.md)」を参照してください。
+ ファイル `.aws/credentials` が root ユーザーのホームディレクトリに存在しない場合は、次のいずれかの操作を実行できます。
+ CloudWatch エージェントの実行に使用するユーザーの認証情報ファイルを作成します。この認証情報ファイルは `/home/username/.aws/credentials` になります。次に、`shared_credential_file` の `common-config.toml` パラメータの値を認証情報ファイルのパス名に設定します。詳細については、「[AWS Systems Manager を使用して CloudWatch エージェントをインストールする](installing-cloudwatch-agent-ssm.md)」を参照してください。
+ 認証情報ファイルを作成する代わりに、IAM ロールをインスタンスにアタッチします。エージェントは、このロールを認証情報プロバイダーとして使用します。
1. CloudWatch エージェント設定ファイルで、`agent` セクションに次の行を追加します。
```
"run_as_user": "username"
```
必要に応じて、設定ファイルに他の変更を行います。詳細については、[CloudWatch エージェント設定ファイルを作成する](create-cloudwatch-agent-configuration-file.md)を参照してください。
1. 必要なアクセス許可をユーザーに付与します。ユーザーには、収集するログファイルの読み取り (r) アクセス許可と、ログファイルのパス内のすべてのディレクトリに対する実行 (x) アクセス許可が必要です。
1. 先ほど作成した設定ファイルを使用してエージェントを起動します。
```
sudo /opt/aws/amazon-cloudwatch-agent/bin/amazon-cloudwatch-agent-ctl -a fetch-config -m ec2 -s -c file:configuration-file-path
```
**Linux を実行しているオンプレミスサーバーで CloudWatch エージェントを別のユーザーとして実行するには**
1. 新しい CloudWatch エージェントパッケージをダウンロードしてインストールします。
1. 新しい Linux ユーザーを作成するか、RPM ファイルまたは DEB ファイルで作成した `cwagent` という名前のデフォルトユーザーを使用します。
1. このユーザーの認証情報をユーザーがアクセスできるパス (`/home/username/.aws/credentials` など) に保存します。
1. `shared_credential_file` の `common-config.toml` パラメータの値を認証情報ファイルのパス名に指定します。詳細については、「[AWS Systems Manager を使用して CloudWatch エージェントをインストールする](installing-cloudwatch-agent-ssm.md)」を参照してください。
1. CloudWatch エージェント設定ファイルで、`agent` セクションに次の行を追加します。
```
"run_as_user": "username"
```
必要に応じて、設定ファイルに他の変更を行います。詳細については、[CloudWatch エージェント設定ファイルを作成する](create-cloudwatch-agent-configuration-file.md)を参照してください。
1. 必要なアクセス許可をユーザーに付与します。ユーザーには、収集するログファイルの読み取り (r) アクセス許可と、ログファイルのパス内のすべてのディレクトリに対する実行 (x) アクセス許可が必要です。
1. 先ほど作成した設定ファイルを使用してエージェントを起動します。
```
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 エージェントによって収集されるメトリクスの集約またはロールアップ
エージェントにより収集されたメトリクスを集約 (ロールアップ) するには、`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`] が必要です。このポリシーをロールに割り当てる方法の詳細については、「[前提条件](prerequisites.md)」を参照してください。
また、送信側アカウントのロールに次のポリシーも含まれている必要があります。このポリシーは、ロールを編集するときに IAM コンソールの [**アクセス許可**] タブで追加します。
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"sts:AssumeRole"
],
"Resource": [
"arn:aws:iam::111122223333:role/agent-role-in-target-account"
]
}
]
}
```
------
また、ターゲットアカウントのロールには、送信側アカウントで使用される IAM ロールを認識できるように、次のポリシーが含まれている必要があります。このポリシーは、ロールを編集するときに IAM コンソールの [**信頼関係**] タブで追加します。このロールは、送信側アカウントで使用されるポリシーの `agent-role-in-target-account` で指定したロールです。
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Principal": {
"AWS": [
"arn:aws:iam::111122223333: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 エージェント設定ファイル: ログセクション](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/CloudWatch-Agent-Configuration-File-Details.html#CloudWatch-Agent-Configuration-File-Logssection)」を参照してください。CloudWatch Logs エージェントでサポートされる記号については、*Amazon CloudWatch Logs ユーザーガイド*の「[エージェント設定ファイル](https://docs.aws.amazon.com/AmazonCloudWatch/latest/logs/AgentReference.html#agent-configuration-file)」を参照してください。
## OpenTelemetry コレクター設定ファイルの追加
CloudWatch エージェントは、独自の設定ファイルとともに、補足的な OpenTelemetry コレクター設定ファイルをサポートします。この機能を使用すると、CloudWatch エージェント設定を通じて CloudWatch Application Signals や Container Insights などの CloudWatch エージェント機能が使用できます。また、単一のエージェントで既存の OpenTelemetry コレクター設定を取り込むこともできます。
CloudWatch エージェントによって自動的に作成されたパイプラインとのマージ競合を防ぐには、OpenTelemetry コレクター設定の各コンポーネントおよびパイプラインにカスタムサフィックスを追加することをお勧めします。
```
receivers:
otlp/custom-suffix:
protocols:
http:
exporters:
awscloudwatchlogs/custom-suffix:
log_group_name: "test-group"
log_stream_name: "test-stream"
service:
pipelines:
logs/custom-suffix:
receivers: [otlp/custom-suffix]
exporters: [awscloudwatchlogs/custom-suffix]
```
CloudWatch エージェントを設定するには、`fetch-config` オプションを使用して CloudWatch エージェントを起動し、CloudWatch エージェントの設定ファイルを指定します。CloudWatch エージェントには、少なくとも 1 つの CloudWatch エージェント設定ファイルが必要です。
```
/opt/aws/amazon-cloudwatch-agent/bin/amazon-cloudwatch-agent-ctl -a fetch-config -c file:/tmp/agent.json -s
```
次に、OpenTelemetry コレクター設定ファイルを指定するときに `append-config`オプションを使用します。
```
/opt/aws/amazon-cloudwatch-agent/bin/amazon-cloudwatch-agent-ctl -a append-config -c file:/tmp/otel.yaml -s
```
エージェントは起動時に 2 つの設定ファイルをマージし、解決された設定をログ記録します。