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

# 使用 CloudWatch 代理程式傳送內嵌指標格式日誌
<a name="CloudWatch_Embedded_Metric_Format_Generation_CloudWatch_Agent"></a>

 本節說明如何安裝和使用 CloudWatch 代理程式。本節的第一部分說明如何安裝 CloudWatch 代理程式。本節的第二部分說明如何使用 CloudWatch 代理程式傳送內嵌指標格式日誌。如果您想要使用此方法，您必須為 AWS 服務 要傳送內嵌指標格式日誌的 安裝 CloudWatch 代理程式。然後即可開始傳送事件。CloudWatch 代理程式必須是 1.230621.0 版或更新版本。

**注意**  
您不需要安裝 CloudWatch 代理程式來從 Lambda 函數傳送日誌。  
Lambda 函數逾時不會自動處理。這表示如果您的函數在排清指標前逾時，便不會擷取該呼叫的指標。

## 安裝 CloudWatch 代理程式
<a name="CloudWatch_Embedded_Metric_Format_Generation_Install_Agent"></a>

為每個要傳送內嵌指標格式日誌的服務安裝 CloudWatch 代理程式。

### 在 EC2 上安裝 CloudWatch 代理程式
<a name="CloudWatch_Embedded_Metric_Format_Generation_Install_Agent_EC2"></a>

首先，請在執行個體上安裝 CloudWatch 代理程式。如需詳細資訊，請參閱[安裝 CloudWatch 代理程式](install-CloudWatch-Agent-on-EC2-Instance.md)。

一旦您安裝了代理程式，請設定代理程式在 UDP 或 TCP 連接埠上接聽內嵌指標格式日誌。以下是此組態的範例，此組態會在預設通訊端 `tcp:25888` 上接聽。如需代理程式組態的詳細資訊，請參閱[手動建立或編輯 CloudWatch 代理程式組態檔案](CloudWatch-Agent-Configuration-File-Details.md)。

```
{
  "logs": {
    "metrics_collected": {
      "emf": { }
    }
  }
}
```

### 在 Amazon ECS 上安裝 CloudWatch 代理程式
<a name="CloudWatch_Embedded_Metric_Format_Generation_Install_Agent_ECS"></a>

在 Amazon ECS 上部署 CloudWatch 代理程式最簡單的方式，便是以附屬方式執行代理程式，並在與您應用程式相同的任務定義中定義代理程式。

**建立代理程式組態檔案**

在本機建立您的 CloudWatch 代理程式組態檔案。在此範例中，相對檔案路徑將會是 `amazon-cloudwatch-agent.json`。

如需代理程式組態的詳細資訊，請參閱[手動建立或編輯 CloudWatch 代理程式組態檔案](CloudWatch-Agent-Configuration-File-Details.md)。

```
{
  "logs": {
    "metrics_collected": {
      "emf": { }
    }
  }
}
```

**將組態推送至 SSM 參數存放區**

輸入下列命令，將 CloudWatch 代理程式組態檔案推送至 AWS Systems Manager (SSM) 參數存放區。

```
aws ssm put-parameter \
    --name "cwagentconfig" \
    --type "String" \
    --value "`cat amazon-cloudwatch-agent.json`" \
    --region "{{region}}"
```

**設定任務定義**

設定您的任務定義，以使用 CloudWatch 代理程式並公開 TCP 或 UDP 連接埠。您應使用的範例任務定義取決於您的網路模式。

請注意，`webapp` 會指定 `AWS_EMF_AGENT_ENDPOINT` 環境變數。此環境變數會由程式庫使用，且應指向代理程式正在接聽的端點。此外，`cwagent` 會指定 `CW_CONFIG_CONTENT` 為 “valueFrom” 參數，其指向您在先前步驟中建立的 SSM 組態。

本節包含一個橋接模式的範例，以及一個託管模式或 awsvpc 模式的範例。如需如何在 Amazon ECS 上設定 CloudWatch 代理程式的詳細範例，請參閱 [Github 範例儲存庫](https://github.com/aws-samples/amazon-cloudwatch-container-insights/tree/master/ecs-task-definition-templates/deployment-mode/sidecar)

以下是橋接模式的範例。啟用橋接模式聯網時，代理程式需要使用 `links` 參數連結至您的應用程式，並且必須使用容器名稱來定址。

```
{
  "containerDefinitions": [
          {
              "name": "webapp",
              "links": [ "cwagent" ],
              "image": "my-org/web-app:latest",
              "memory": 256,
              "cpu": 256,
              "environment": [{
                "name": "AWS_EMF_AGENT_ENDPOINT",
                "value": "tcp://cwagent:25888"
              }],
          },
          {
              "name": "cwagent",
              "mountPoints": [],
              "image": "public.ecr.aws/cloudwatch-agent/cloudwatch-agent:latest",
              "memory": 256,
              "cpu": 256,
              "portMappings": [{
                  "protocol": "tcp",
                  "containerPort": 25888
              }],
              "environment": [{
                "name": "CW_CONFIG_CONTENT",
                "valueFrom": "cwagentconfig"
              }],
          }
      ],
}
```

以下是託管模式或 awsvpc 模式的範例。在這些網路模式上執行時，代理程式可以透過 `localhost` 定址。

```
{
  "containerDefinitions": [
          {
              "name": "webapp",
              "image": "my-org/web-app:latest",
              "memory": 256,
              "cpu": 256,
              "environment": [{
                "name": "AWS_EMF_AGENT_ENDPOINT",
                "value": "tcp://127.0.0.1:25888"
              }],
          },
          {
              "name": "cwagent",
              "mountPoints": [],
              "image": "public.ecr.aws/cloudwatch-agent/cloudwatch-agent:latest",
              "memory": 256,
              "cpu": 256,
              "portMappings": [{
                  "protocol": "tcp",
                  "containerPort": 25888
              }],
              "environment": [{
                "name": "CW_CONFIG_CONTENT",
                "valueFrom": "cwagentconfig"
              }],
          }
      ],
}
```

**注意**  
在 awsvpc 模式中，您必須給予 VPC 一個公有 IP 地址 (僅限 Fargate)、設定 NAT 閘道，或是設定 CloudWatch Logs VPC 端點。如需設定 NAT 的詳細資訊，請參閱 [NAT 閘道](https://docs.aws.amazon.com/vpc/latest/userguide/vpc-nat-gateway.html)。如需設定 CloudWatch Logs VPC 端點的詳細資訊，請參閱[搭配介面 VPC 端點使用 CloudWatch Logs](https://docs.aws.amazon.com/AmazonCloudWatch/latest/logs/cloudwatch-logs-and-interface-VPC.html)。  
以下是如何將公有 IP 地址指派給使用 Fargate 啟動類型任務的範例。  

```
aws ecs run-task \ 
--cluster {{cluster-name}} \
--task-definition cwagent-fargate \
--region {{region}} \
--launch-type FARGATE \
--network-configuration "awsvpcConfiguration={subnets=[{{subnetId}}],securityGroups=[{{sgId}}],assignPublicIp=ENABLED}"
```

**確認許可**

確認執行您任務的 IAM 角色具有從 SSM 參數存放區讀取的許可。您可以透過連接 **AmazonSSMReadOnlyAccess** 來新增此許可。若要執行此作業，請輸入以下命令。

```
aws iam attach-role-policy --policy-arn arn:aws:iam::aws:policy/AmazonSSMReadOnlyAccess \
--role-name CWAgentECSExecutionRole
```

### 在 Amazon EKS 上安裝 CloudWatch 代理程式
<a name="CloudWatch_Embedded_Metric_Format_Generation_Install_Agent_EKS"></a>

如果您已經在此叢集上安裝了 CloudWatch Container Insights，則可以跳過此程序的某些部分。

許可

如果您尚未安裝 Container Insights，首先請先確認您的 Amazon EKS 節點具有適當的 IAM 許可。這些節點應該已連接了 **CloudWatchAgentServerPolicy**。如需詳細資訊，請參閱[在 CloudWatch 中驗證 Container Insights 的先決條件](Container-Insights-prerequisites.md)。

**建立 ConfigMap**

為代理程式建立 ConfigMap。ConfigMap 也會告知代理程式在 TCP 或 UDP 連接埠上接聽。請使用以下 ConfigMap。

```
# cwagent-emf-configmap.yaml
apiVersion: v1
data:
  # Any changes here must not break the JSON format
  cwagentconfig.json: |
    {
      "agent": {
        "omit_hostname": true
      },
      "logs": {
        "metrics_collected": {
          "emf": { }
        }
      }
    }
kind: ConfigMap
metadata:
  name: cwagentemfconfig
  namespace: default
```

如果您已經安裝了 Container Insights，請將以下的 `"emf": { }` 行新增至您現有的 ConfigMap。

**套用 ConfigMap**

輸入以下命令來套用 ConfigMap。

```
kubectl apply -f cwagent-emf-configmap.yaml
```

**部署代理程式**

若要將 CloudWatch 代理程式作為附屬部署，請將代理程式新增至您的 pod 定義，如以下範例所示。

```
apiVersion: v1
kind: Pod
metadata:
  name: myapp
  namespace: default
spec:
  containers:
    # Your container definitions go here
    - name: web-app
      image: my-org/web-app:latest
    # CloudWatch Agent configuration
    - name: cloudwatch-agent
      image: public.ecr.aws/cloudwatch-agent/cloudwatch-agent:latest
      imagePullPolicy: Always
      resources:
        limits:
          cpu: 200m
          memory: 100Mi
        requests:
          cpu: 200m
          memory: 100Mi
      volumeMounts:
        - name: cwagentconfig
          mountPath: /etc/cwagentconfig
      ports:
  # this should match the port configured in the ConfigMap
        - protocol: TCP
          hostPort: 25888
          containerPort: 25888
  volumes:
    - name: cwagentconfig
      configMap:
        name: cwagentemfconfig
```

## 使用 CloudWatch 代理程式傳送內嵌指標格式日誌
<a name="CloudWatch_Embedded_Metric_Format_Generation_CloudWatch_Agent_Send_Logs"></a>

在您安裝 CloudWatch 代理程式並執行 後，您便可以透過 TCP 或 UDP 傳送內嵌指標格式日誌。透過代理程式傳送日誌時有兩個需求：
+ 日誌必須包含 `LogGroupName` 索引鍵，告知代理程式要使用的日誌群組。
+ 每個日誌事件都必須在單獨的一行上。換句話說，日誌事件不能包含換行 (\\n) 字元。

日誌事件也必須遵循內嵌指標格式規格。如需詳細資訊，請參閱[規格：內嵌指標格式](CloudWatch_Embedded_Metric_Format_Specification.md)。

如果您打算在使用內嵌指標格式建立的指標上建立警示，請參閱[在以內嵌指標格式建立的指標上設定警示](CloudWatch_Embedded_Metric_Format_Alarms.md)以取得相關建議。

以下是從 Linux bash shell 手動傳送日誌事件的範例。您可以改為使用您所選擇程式設計語言提供的 UDP 通訊端介面。

```
echo '{"_aws":{"Timestamp":1574109732004,"LogGroupName":"Foo","CloudWatchMetrics":[{"Namespace":"MyApp","Dimensions":[["Operation"]],"Metrics":[{"Name":"ProcessingLatency","Unit":"Milliseconds","StorageResolution":60}]}]},"Operation":"Aggregator","ProcessingLatency":100}' \
> /dev/udp/0.0.0.0/25888
```

**注意**  
 借助內嵌指標格式，您可以透過在您帳戶的 `AWS/Logs` 命名空間中發布的指標追蹤 EMF 日誌的處理進度。這些指標可用於追蹤從 EMF 產生指標失敗的情形，以及失敗是否因剖析或驗證造成。如需詳細資訊，請參閱[使用 CloudWatch 指標進行監控](https://docs.aws.amazon.com/AmazonCloudWatch/latest/logs/CloudWatch-Logs-Monitoring-CloudWatch-Metrics.html)。