# CloudWatch 代理的常见场景
<a name="CloudWatch-Agent-common-scenarios"></a>

 本节为您提供不同的场景，概述如何完成 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 代理
<a name="CloudWatch-Agent-run-as-user"></a>

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

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

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

1. 下载并安装新的 CloudWatch 代理软件包。

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

1. 使用以下方式之一为该用户提供凭证：
   + 如果文件 `.aws/credentials` 存在于根用户的主目录中，您必须为要用于运行 CloudWatch 代理的用户创建一个凭证文件。该凭证文件是 `/home/username/.aws/credentials`。然后，将 `common-config.toml` 中的 `shared_credential_file` 参数值设置为凭证文件的路径名。有关更多信息，请参阅 [使用 AWS Systems Manager 安装 CloudWatch 代理](installing-cloudwatch-agent-ssm.md)。
   + 如果根用户的主目录中不存在文件 `.aws/credentials`，您可以执行下列操作之一：
     + 为要用于运行 CloudWatch 代理的用户创建一个凭证文件。该凭证文件是 `/home/username/.aws/credentials`。然后，将 `common-config.toml` 中的 `shared_credential_file` 参数值设置为凭证文件的路径名。有关更多信息，请参阅 [使用 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. 为用户提供所需的权限。用户必须拥有要收集的日志文件的 Read (r) 权限，并且必须对日志文件路径中的每个目录具有 Execute (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. 将 `common-config.toml` 中的 `shared_credential_file` 参数值设置为凭证文件的路径名。有关更多信息，请参阅 [使用 AWS Systems Manager 安装 CloudWatch 代理](installing-cloudwatch-agent-ssm.md)。

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

   ```
   "run_as_user": "username"
   ```

   根据需要，对该配置文件进行其他修改。有关更多信息，请参阅 [创建 CloudWatch 代理配置文件](create-cloudwatch-agent-configuration-file.md)。

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

稀疏文件是具有空块和真实内容的文件。稀疏文件通过将表示空块的简短信息（而不是构成此块的实际 Null 字节）写入磁盘，以更有效地使用磁盘空间。这使得稀疏文件的实际大小通常比其表观大小小得多。

但是，CloudWatch 代理对稀疏文件的处理方式与对普通文件的处理方式不同。当代理读取稀疏文件时，空块被视为填充 Null 字节的“真实”块。因此，CloudWatch 代理向 CloudWatch 发布的字节数与稀疏文件的表观大小相同。

配置 CloudWatch 代理来发布稀疏文件可能会导致高于预期 CloudWatch 成本，因此我们建议不要这样做。例如，Linux 中的 `/var/logs/lastlog` 通常是一个非常稀疏的文件，我们建议您不要将其发布到 CloudWatch。

## 将自定义维度添加到 CloudWatch 代理收集的指标
<a name="CloudWatch-Agent-adding-custom-dimensions"></a>

要将自定义维度 (如标签) 添加到该代理收集的指标中，请将 `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 代理收集的指标
<a name="CloudWatch-Agent-aggregating-metrics"></a>

要汇总或累积该代理收集的指标，请将 `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 代理收集高精度指标
<a name="CloudWatch-Agent-collect-high-resolution-metrics"></a>

`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"
      ]
    }
  }
}
```

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

## 向不同账户发送指标、日志和跟踪信息
<a name="CloudWatch-Agent-send-to-different-AWS-account"></a>

要让 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`。有关将该策略分配给角色的更多信息，请参阅[先决条件](prerequisites.md)。

发送账户中的角色还必须包含以下策略。编辑角色时，您可以将此策略添加到 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 代理之间的时间戳差异
<a name="CloudWatch-Agent-logs-timestamp-differences"></a>

与更早的 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 代理配置文件：日志部分](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 收集器配置文件
<a name="CloudWatch-Agent-appending-OpenTelemetry-config-files"></a>

 除了自己的配置文件外，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
```

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