Amazon Web Services 文档中描述的 Amazon Web Services 服务或功能可能因区域而异。要查看适用于中国区域的差异，请参阅 中国的 Amazon Web Services 服务入门 (PDF)。

CloudWatch 代理的常见场景

本节为您提供不同的场景，概述如何完成 CloudWatch 代理的常见配置和自定义任务。

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

在 Linux 服务器上，CloudWatch 默认以根用户身份运行。要让代理以不同用户身份运行，请在 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"]]
}

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

"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。有关将该策略分配给角色的更多信息，请参阅先决条件。

发送账户中的角色还必须包含以下策略。编辑角色时，您可以将此策略添加到 IAM 控制台的 Permissions（权限）选项卡。

JSON

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "sts:AssumeRole"
            ],
            "Resource": [
                "arn:aws:iam::111122223333:role/agent-role-in-target-account"
            ]
        }
    ]
}

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

有关较新的 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 代理至少需要一个 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

代理会在启动时合并两个配置文件并记录已解析的配置。