CloudWatch エージェントを使用した一般的なシナリオ - Amazon CloudWatch
CloudWatch エージェントを別のユーザーとして実行するCloudWatch エージェントにより収集されるメトリクスにカスタムディメンションを追加する複数の CloudWatch エージェント設定ファイルCloudWatch エージェントによって収集されるメトリクスを集約またはロールアップするCloudWatch エージェントを使用して高解像度メトリクスを収集する別のアカウントにメトリクスとログを送信する統合 CloudWatch エージェントと古い CloudWatch Logs エージェントの間のタイムスタンプの違い

CloudWatch エージェントを使用した一般的なシナリオ

以下のセクションでは、CloudWatch エージェントを使用する場合にいくつかの一般的な設定およびカスタマイズタスクを完了する方法の概要を説明します。

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

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

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

Linux を実行する EC2 インスタンスで CloudWatch エージェントを別のユーザーとして実行するには

  1. 新しい CloudWatch エージェントパッケージをダウンロードしてインストールします。詳細については、「CloudWatch エージェントパッケージをダウンロードする」をご参照ください。

  2. 新しい Linux ユーザーを作成するか、RPM ファイルまたは DEB ファイルで作成した cwagent という名前のデフォルトユーザーを使用します。

  3. 次のいずれかの方法で、このユーザーの認証情報を指定します。

    • このファイル .aws/credentials が root ユーザーのホームディレクトリに存在する場合は、CloudWatch エージェントの実行に使用するユーザーの認証情報ファイルを作成する必要があります。この認証情報ファイルは /home/username/.aws/credentials になります。次に、common-config.toml の shared_credential_file パラメータの値を認証情報ファイルのパス名に設定します。詳細については、「(オプション) プロキシ情報またはリージョン情報の一般的な設定を変更する」をご参照ください。

    • ファイル .aws/credentials が root ユーザーのホームディレクトリに存在しない場合は、次のいずれかの操作を実行できます。

      • CloudWatch エージェントの実行に使用するユーザーの認証情報ファイルを作成します。この認証情報ファイルは /home/username/.aws/credentials になります。次に、common-config.toml の shared_credential_file パラメータの値を認証情報ファイルのパス名に設定します。詳細については、「(オプション) プロキシ情報またはリージョン情報の一般的な設定を変更する」をご参照ください。

      • 認証情報ファイルを作成する代わりに、 IAM ロールをインスタンスにアタッチします。エージェントは、このロールを認証情報プロバイダーとして使用します。

  4. CloudWatch エージェント設定ファイルで、agent セクションに次の行を追加します。 

    "run_as_user": "username"

    必要に応じて、設定ファイルに他の変更を行います。詳細については、「CloudWatch エージェント設定ファイルを作成する」を参照してください。

  5. 必要なアクセス許可をユーザーに付与します。ユーザーには、収集するログファイルの読み取り (r) アクセス許可と、ログファイルのパス内のすべてのディレクトリに対する実行 (x) アクセス許可が必要です。

  6. 先ほど作成した設定ファイルを使用してエージェントを起動します。

    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 エージェントパッケージをダウンロードしてインストールします。詳細については、「CloudWatch エージェントパッケージをダウンロードする」をご参照ください。

  2. 新しい Linux ユーザーを作成するか、RPM ファイルまたは DEB ファイルで作成した cwagent という名前のデフォルトユーザーを使用します。

  3. このユーザーの認証情報をユーザーがアクセスできるパス (/home/username/.aws/credentials など) に保存します。

  4. common-config.toml の shared_credential_file パラメータの値を認証情報ファイルのパス名に指定します。詳細については、「(オプション) プロキシ情報またはリージョン情報の一般的な設定を変更する」をご参照ください。

  5. CloudWatch エージェント設定ファイルで、agent セクションに次の行を追加します。 

    "run_as_user": "username"

    必要に応じて、設定ファイルに他の変更を行います。詳細については、「CloudWatch エージェント設定ファイルを作成する」を参照してください。

  6. 必要なアクセス許可をユーザーに付与します。ユーザーには、収集するログファイルの読み取り (r) アクセス許可と、ログファイルのパス内のすべてのディレクトリに対する実行 (x) アクセス許可が必要です。

  7. 先ほど作成した設定ファイルを使用してエージェントを起動します。

    sudo /opt/aws/amazon-cloudwatch-agent/bin/amazon-cloudwatch-agent-ctl -a fetch-config -m ec2 -s -c file:configuration-file-path

CloudWatch エージェントにより収集されるメトリクスにカスタムディメンションを追加する

エージェントによって収集されるメトリクスにタグなどのカスタムディメンションを追加するには、それらのメトリクスをリストするエージェント設定ファイルのセクションに append_dimensions フィールドを追加します。

たとえば、設定ファイルの次のサンプルセクションでは、値が Prod の stackName というカスタムディメンションを、エージェントによって収集される 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 エージェント設定ファイル

複数の設定ファイルを使用するように CloudWatch エージェントを設定できます。たとえば、一連のメトリクスとログを収集する、共通の設定ファイルを使用して、常にインフラストラクチャ内のすべてのサーバーから収集することができます。その後、追加の設定ファイルを使用して、特定のアプリケーションから、または特定の状況でメトリクスを収集することができます。

これを設定するには、まず使用する設定ファイルを作成します。同じサーバー上で一緒に使用される設定ファイルは、異なるファイル名を持つ必要があります。設定ファイルは、サーバー上または Parameter Store に保存できます。

fetch-config オプションを使って CloudWatch エージェントを開始し、1 つ目の設定ファイルを指定します。エージェントの実行の 2 つ目の設定ファイルを追加するには、同じコマンドを使用しますが、append-config オプションを使います。いずれかの設定ファイルにリストされている、すべてのメトリクスとログが収集されます。次の Linux コマンドは、このシナリオで設定ストアをファイルとして使用した例を示しています。1 行目で infrastructure.json 設定ファイルを使ってエージェントを開始し、2 行目で app.json 設定ファイルを追加しています。 

/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

次の設定ファイルは、この機能の使用方法の例を示しています。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 秒ごとに収集する必要がある場合は、agent セクションで、グローバルメトリクス収集間隔として metrics_collection_interval の値を 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 ロールを指定します。このロールにより、メトリクスまたはログをターゲットアカウントに配信するときに、送信アカウントがターゲットアカウントの対応するロールを担うことができます。

エージェント設定ファイルには、2 つの個別の role_arn 文字列を指定することもできます。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 User Guide』の「エージェント設定ファイル」を参照してください。