CloudWatch 代理的常见场景

以下几节简要说明如何为 CloudWatch 代理完成常见的配置和自定义任务。

以不同用户身份运行 CloudWatch 代理

在 Linux 服务器上，CloudWatch 默认以根用户身份运行。要让代理以不同用户身份运行，请在 CloudWatch 代理配置文件的 agent 部分中使用 run_as_user 参数。该选项仅在 Linux 服务器上可用。

如果已使用 root 用户运行代理并希望更改为使用不同的用户，请使用以下过程之一。

在运行 Linux 的 EC2 实例上以不同用户身份运行 CloudWatch 代理

1. 下载并安装新的 CloudWatch 代理软件包。有关更多信息，请参阅 下载 CloudWatch 代理软件包。

2. 创建新的 Linux 用户，或使用 RPM 或 DEB 文件创建的默认用户（名为 cwagent）。

3. 使用以下方式之一为该用户提供凭证：

   • 如果文件 .aws/credentials 存在于根用户的主目录中，您必须为要用于运行 CloudWatch 代理的用户创建一个凭证文件。该凭证文件是 /home/username/.aws/credentials。然后，将 common-config.toml 中的 shared_credential_file 参数值设置为凭证文件的路径名。有关更多信息，请参阅 （可选）修改代理的通用配置或区域信息。

   • 如果根用户的主目录中不存在文件 .aws/credentials，您可以执行下列操作之一：

     • 为要用于运行 CloudWatch 代理的用户创建一个凭证文件。该凭证文件是 /home/username/.aws/credentials。然后，将 common-config.toml 中的 shared_credential_file 参数值设置为凭证文件的路径名。有关更多信息，请参阅 （可选）修改代理的通用配置或区域信息。

     • 将 IAM 角色附加到实例，而不是创建凭证文件。代理将该角色作为凭证提供程序。

4. 在 CloudWatch 代理配置文件中，在 agent 部分中添加以下行：

   "run_as_user": "username"

   根据需要，对该配置文件进行其他修改。有关更多信息，请参阅 创建 CloudWatch 代理配置文件

5. 为用户提供所需的权限。用户必须拥有要收集的日志文件的 Read (r) 权限，并且必须对日志文件路径中的每个目录具有 Execute (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. 为用户提供所需的权限。用户必须拥有要收集的日志文件的 Read (r) 权限，并且必须对日志文件路径中的每个目录具有 Execute (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 代理如何处理稀疏日志文件

稀疏文件是具有空块和真实内容的文件。稀疏文件通过将表示空块的简短信息（而不是构成此块的实际 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 代理，并指定第一个配置文件。要将第二个配置文件附加到正在运行的代理，请使用相同的命令，但使用 append-config 选项。将收集任一配置文件中列出的所有指标、日志和跟踪信息。以下示例命令使用配置存储作为文件来演示此场景。第一行使用 infrastructure.json 配置文件启动代理，第二行附加 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"

以下示例配置文件展示了此功能的一个用法。第一个配置文件用于基础设施中的所有服务器，第二个配置文件仅收集来自特定应用程序的日志，并附加到运行该应用程序的服务器。

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 用于与代理已在使用的配置文件具有相同文件名的配置文件，则附加命令将覆盖第一个配置文件中的信息，而不是附加到它。即使这两个具有相同文件名的配置文件位于不同的文件路径中，也是这样。

上述示例显示使用了两个配置文件，但对您可以附加到代理配置的配置文件数量并没有限制。您还可以混合使用位于服务器上的配置文件和位于 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"]]
}

要将指标累积到一个集合中，请使用 []。

"metrics": {
  "cpu":{...}
  "disk":{...}
  "aggregation_dimensions" : [[]]
}

切记，每次更改代理配置文件时，您必须重新启动该代理以使更改生效。

使用 CloudWatch 代理收集高精度指标

metrics_collection_interval 字段指定收集的指标的时间间隔 (以秒为单位)。如果为该字段指定小于 60 的值，则将指标作为高精度指标进行收集。

例如，如果所有指标均应为高精度指标并且每 10 秒收集一次，请在 agent 部分中指定 10 作为 metrics_collection_interval 的值，以用作全局指标收集间隔。

"agent": {
  "metrics_collection_interval": 10
}

或者，以下示例将 cpu 指标设置为每秒收集一次，将所有其他指标设置为每分钟收集一次。

"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 字符串：一个用于发送指标，一个用于发送日志，还有一个用于发送跟踪信息。

配置文件的 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 控制台的 Permissions（权限）选项卡。

{
    "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 控制台的 True relationships（信任关系）选项卡。您添加此策略的目标账户中的角色是您在创建 IAM 角色和用户以用于 CloudWatch 代理中创建的角色。此角色是在发送账户使用的策略的 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 Logs 代理相比，CloudWatch 代理支持将一组不同的符号集用于时间戳格式。这些差异如下表所示。

两种代理均支持的符号	仅统一 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 用户指南中的代理配置文件。