CloudWatch エージェントの一般的なシナリオ

このセクションでは、CloudWatch エージェントに共通する設定とカスタマイズのタスクを完了する方法をまとめたさまざまなシナリオについて説明します。

CloudWatch エージェントの別のユーザーとしての実行

Linux サーバーでは、CloudWatch はデフォルトで root ユーザーとして実行されます。エージェントを別のユーザーとして実行するには、CloudWatch エージェント設定ファイルの agent セクションで run_as_user パラメータを使用します。このオプションは、Linux サーバーでのみ使用できます。

エージェントを root ユーザーとして既に実行している場合、別のユーザーに変更するには、以下のいずれかの手順を使用します。

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] が必要です。このポリシーをロールに割り当てる方法の詳細については、「前提条件」を参照してください。

また、送信側アカウントのロールに次のポリシーも含まれている必要があります。このポリシーは、ロールを編集するときに 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 エージェントでサポートされる記号の意味の詳細については、Amazon CloudWatch ユーザーガイドの「CloudWatch エージェント設定ファイル: ログセクション」を参照してください。CloudWatch Logs エージェントでサポートされる記号については、Amazon CloudWatch Logs ユーザーガイドの「エージェント設定ファイル」を参照してください。

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 つの設定ファイルをマージし、解決された設定をログ記録します。