本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

# 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 伺服器使用。

如果您已使用根使用者身分執行代理，並想要變更為使用不同的使用者身分，請使用下列程序之一。

**在執行 Linux 的 EC2 執行個體上以其他使用者身分執行 CloudWatch 代理**

1. 下載並安裝新的 CloudWatch 代理程式套件。

1. 建立新的 Linux 使用者，或使用 RPM 或 DEB 檔案所建立名為 `cwagent` 的預設使用者。

1. 以下列方式之一提供此使用者的登入資料：
   + 如果檔案 `.aws/credentials` 存在於根使用者的主目錄中，您必須為執行 CloudWatch 代理程式時使用的使用者建立憑證檔案。這個登入資料檔案會是 `/home/username/.aws/credentials`。然後，將 `common-config.toml` 中的 `shared_credential_file` 參數值設為登入資料檔案的路徑名稱。如需詳細資訊，請參閱[使用 安裝 CloudWatch 代理程式 AWS Systems Manager](installing-cloudwatch-agent-ssm.md)。
   + 如果檔案 `.aws/credentials` 不存在於根使用者的主目錄中，您可執行下列操作之一：
     + 建立憑證檔案，讓您要用的使用者執行 CloudWatch 代理程式。這個登入資料檔案會是 `/home/username/.aws/credentials`。然後，將 `common-config.toml` 中的 `shared_credential_file` 參數值設為登入資料檔案的路徑名稱。如需詳細資訊，請參閱[使用 安裝 CloudWatch 代理程式 AWS Systems Manager](installing-cloudwatch-agent-ssm.md)。
     + 不要建立憑證檔案，而是將 IAM 角色連接到執行個體。代理會使用這個角色作為登入資料提供者。

1. 在 CloudWatch 代理程式組態檔案中，在 `agent` 區段新增下列行：

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

   視需要對組態檔案執行其他修改。如需詳細資訊，請參閱[建立 CloudWatch 代理程式組態檔案](create-cloudwatch-agent-configuration-file.md)

1. 提供使用者必要的許可。使用者必須擁有要收集之日誌檔的讀取 (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` 參數值設為登入資料檔案的路徑名稱。如需詳細資訊，請參閱[使用 安裝 CloudWatch 代理程式 AWS Systems Manager](installing-cloudwatch-agent-ssm.md)。

1. 在 CloudWatch 代理程式組態檔案中，在 `agent` 區段新增下列行：

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

   視需要對組態檔案執行其他修改。如需詳細資訊，請參閱[建立 CloudWatch 代理程式組態檔案](create-cloudwatch-agent-configuration-file.md)

1. 提供使用者必要的許可。使用者必須擁有要收集之日誌檔的讀取 (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>

稀疏檔案是同時具有空白區塊和實際內容的檔案。稀疏檔案透過將代表空白區塊的簡短資訊 (而不是組成區塊的實際空白位元組) 寫入磁碟，以更有效率的方式使用磁碟空間。這使稀疏檔案的實際大小往往比其表面上的大小小得多。

不過，CloudWatch 代理程式處理稀疏檔案的方式與一般檔案並無不同。當代理程式讀取稀疏檔案時，空白區塊會被視為填滿空位元組的「真實」區塊。有鑑於此，CloudWatch 代理程式會將稀疏檔案表面大小的相同位元組數目發布至 CloudWatch。

設定 CloudWatch 代理程式來發布稀疏檔案可能會導致高出預期的 CloudWatch 成本，因此我們建議您不要這麼做。例如，`/var/logs/lastlog` 在 Linux 中通常是一個非常稀疏的檔案，我們建議您不要將它發布到 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 秒收集一次，請為 `metrics_collection_interval` 區段下方的 `agent` 指定 10 作為值，以作為全域指標的收集間隔。

```
"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 主控台中的 **Trust 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 代理程式組態檔案：Logs (日誌) 區段](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
```

接著，使用 `append-config` 選項指定 OpenTelemetry 收集器設定檔。

```
/opt/aws/amazon-cloudwatch-agent/bin/amazon-cloudwatch-agent-ctl -a append-config -c file:/tmp/otel.yaml -s
```

代理程式會在啟動時合併兩個設定檔，並記錄解析後的組態。