本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。
# 使用應用程式指標關聯 Amazon ECS 應用程式效能
Fargate 上的 Amazon ECS 支援從您在 Fargate 上執行的應用程式收集指標，並將指標匯出到 Amazon CloudWatch 或 Amazon Managed Service for Prometheus。
您可以使用收集的中繼資料，將應用程式效能資料與底層基礎結構資料建立關聯，減少解決問題耗用的平均時間。
Amazon ECS 使用 AWS Distro for OpenTelemetry 附屬容器來收集應用程式指標並將其路由至目的地。Amazon ECS 主控台體驗簡化了建立任務定義時新增此整合的流程。
**Topics**
+ [將應用程式指標匯出至 Amazon CloudWatch](application-metrics-cloudwatch.md)
+ [將應用程式指標匯出至 Amazon Managed Service for Prometheus](application-metrics-prometheus.md)
# 將應用程式指標匯出至 Amazon CloudWatch
Fargate 上的 Amazon ECS 支援將您的自訂應用程式指標匯出到 Amazon CloudWatch 作為自訂指標。方法是將 AWS Distro for OpenTelemetry 附屬容器新增至您的任務定義。Amazon ECS 主控台透過在建立新任務定義時新增**使用指標收集**選項來簡化此流程。如需詳細資訊，請參閱[使用主控台建立 Amazon ECS 任務定義](create-task-definition.md)。
將應用程式指標匯出至有日誌群組名稱 `/aws/ecs/application/metrics` 的 CloudWatch Logs，並且您可以在 `ECS/AWSOTel/Application` 命名空間中查看指標。您的應用程式必須使用 OpenTelemetry SDK 進行檢測。如需詳細資訊，請參閱 [AWS Distro for OpenTelemetry 文件](https://aws-otel.github.io/docs/introduction)中的 AWS Distro for OpenTelemetry 簡介。
## 考量事項
使用 Amazon ECS on Fargate 與 AWS Distro for OpenTelemetry 整合，將應用程式指標傳送至 Amazon CloudWatch 時，應考慮下列事項。
+ 此整合只會將您的自訂應用程式指標傳送至 CloudWatch。如果需要任務層級指標，可以在 Amazon ECS 叢集組態中開啟 Container Insights。如需詳細資訊，請參閱[使用具有增強可觀測性的 Container Insights 監控 Amazon ECS](cloudwatch-container-insights.md)。
+ 託管在 Fargate 上的 AWS Amazon ECS 工作負載和託管在 Amazon EC2 執行個體上的 Amazon ECS 工作負載支援 Distro for OpenTelemetry 整合。目前不支援外部執行個體。
+ CloudWatch 支援每個指標最多 30 個維度。預設情況下，Amazon ECS 預設為指標中包含 `TaskARN`、`ClusterARN`、`LaunchType`、`TaskDefinitionFamily`，以及 `TaskDefinitionRevision` 維度。其餘 25 個維度可由您的應用程式定義。如果設定的維度超過 30 個，則 CloudWatch 將無法顯示它們。發生這種情況時，應用程式指標會顯示在 `ECS/AWSOTel/Application` CloudWatch 指標命名空間，但沒有任何維度。您可以檢測應用程式以增加其他維度。如需詳細資訊，請參閱 [AWS Distro for OpenTelemetry 文件中的使用 CloudWatch 指標搭配](https://aws-otel.github.io/docs/getting-started/cloudwatch-metrics) AWS Distro for OpenTelemetry。
## AWS Distro for OpenTelemetry 與 Amazon CloudWatch 整合所需的 IAM 許可
Amazon ECS 與 AWS Distro for OpenTelemetry 整合需要您建立任務 IAM 角色，並在任務定義中指定角色。我們建議您也將 AWS Distro for OpenTelemetry 附屬項目設定為將容器日誌路由至 CloudWatch Logs，這也需要在任務定義中建立和指定任務執行 IAM 角色。Amazon ECS 主控台會代表您負責處理任務執行 IAM 角色，但任務 IAM 角色必須手動建立並新增至任務定義。如需有關任務執行 IAM 角色的詳細資訊，請參閱 [Amazon ECS 任務執行 IAM 角色](task_execution_IAM_role.md)。
**重要**
如果您也使用 AWS Distro for OpenTelemetry 整合收集應用程式追蹤資料，請確定您的任務 IAM 角色也包含該整合所需的許可。如需詳細資訊，請參閱[使用應用程式追蹤資料識別 Amazon ECS 最佳化機會](trace-data.md)。
如果您的應用程式需要任何其他許可，則應將其新增到此政策中。每個任務定義只能指定一個任務 IAM 角色。例如，如果您使用儲存在 Systems Manager 中的自訂組態檔案，則應將 `ssm:GetParameters` 許可新增至此 IAM 政策。
**建立 Elastic Container Service 的服務角色 (IAM 主控台)**
1. 登入 AWS 管理主控台 並開啟位於 https：//[https://console.aws.amazon.com/iam/](https://console.aws.amazon.com/iam/) 的 IAM 主控台。
1. 在 IAM 主控台的導覽窗格中，選擇**角色**，然後選擇**建立角色**。
1. 對於 **Trusted entity type** (信任的實體類型)，請選擇 **AWS 服務**。
1. 在**服務或使用案例**欄位中選擇 **Elastic Container Service**，然後選擇 **Elastic Container Service 任務**使用案例。
1. 選擇**下一步**。
1. 在**新增許可**區段中，搜尋並選取 **AWSDistroOpenTelemetryPolicyForXray** 政策。
1. (選用) 設定[許可界限](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_boundaries.html)。這是進階功能，可用於服務角色，而不是服務連結的角色。
1. 開啟**設定許可界限**區段，然後選擇**使用許可界限來控制角色許可上限**。
IAM 包含您帳戶中 AWS 受管和客戶受管政策的清單。
1. 選取用於許可界限的政策。
1. 選擇**下一步**。
1. 輸入角色名稱或角色名稱字尾，協助識別該角色的用途。
**重要**
當您命名角色時，請注意下列事項：
角色名稱在您的 中必須是唯一的 AWS 帳戶，而且無法依大小寫設為唯一。
例如，不要同時建立名為 **PRODROLE** 和 **prodrole** 的角色。當角色名稱用於政策或 ARN 的一部分時，角色名稱會區分大小寫，但是當角色名稱在主控台中顯示給客戶時，例如在登入過程中，角色名稱不會區分大小寫。
因為其他實體可能會參考角色，所以在建立角色之後，就無法編輯其名稱。
1. (選用) 在**說明**中，輸入角色的說明。
1. (選用) 若要編輯使用案例和角色許可，請在**步驟 1：選取受信任的實體**或者**步驟 2：新增許可**區段中選擇**編輯**。
1. (選用) 若要協助識別、組織或搜尋角色，請將標籤新增為索引鍵值對。如需在 IAM 中使用標籤的詳細資訊，請參閱《*IAM 使用者指南*》中的[AWS Identity and Access Management 資源的標籤](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_tags.html)。
1. 檢閱角色，然後選擇 **Create role** (建立角色)。
## 在任務定義中指定 AWS Distro for OpenTelemetry 附屬項目
Amazon ECS 主控台使用**使用指標收集**選項，簡化了建立 AWS Distro for OpenTelemetry 附屬容器的體驗。如需詳細資訊，請參閱[使用主控台建立 Amazon ECS 任務定義](create-task-definition.md)。
如果您不是使用 Amazon ECS 主控台，則可以手動將 AWS Distro for OpenTelemetry 附屬容器新增至任務定義。下列任務定義範例顯示為 Amazon CloudWatch 整合新增 AWS Distro for OpenTelemetry 附屬項目的容器定義。
```
{
"family": "otel-using-cloudwatch",
"taskRoleArn": "arn:aws:iam::111122223333:role/AmazonECS_OpenTelemetryCloudWatchRole",
"executionRoleArn": "arn:aws:iam::111122223333:role/ecsTaskExecutionRole",
"containerDefinitions": [
{
"name": "aws-otel-emitter",
"image": "application-image",
"logConfiguration": {
"logDriver": "awslogs",
"options": {
"awslogs-create-group": "true",
"awslogs-group": "/ecs/aws-otel-emitter",
"awslogs-region": "us-east-1",
"awslogs-stream-prefix": "ecs"
}
},
"dependsOn": [{
"containerName": "aws-otel-collector",
"condition": "START"
}]
},
{
"name": "aws-otel-collector",
"image": "public.ecr.aws/aws-observability/aws-otel-collector:v0.30.0",
"essential": true,
"command": [
"--config=/etc/ecs/ecs-cloudwatch.yaml"
],
"logConfiguration": {
"logDriver": "awslogs",
"options": {
"awslogs-create-group": "True",
"awslogs-group": "/ecs/ecs-aws-otel-sidecar-collector",
"awslogs-region": "us-east-1",
"awslogs-stream-prefix": "ecs"
}
}
}
],
"networkMode": "awsvpc",
"requiresCompatibilities": [
"FARGATE"
],
"cpu": "1024",
"memory": "3072"
}
```
# 將應用程式指標匯出至 Amazon Managed Service for Prometheus
Amazon ECS 支援將您的任務層級 CPU、記憶體、網路和儲存指標，以及自訂應用程式指標匯出至 Amazon Managed Service for Prometheus。方法是將 AWS Distro for OpenTelemetry 附屬容器新增至您的任務定義。Amazon ECS 主控台透過在建立新任務定義時新增**使用指標收集**選項來簡化此流程。如需詳細資訊，請參閱[使用主控台建立 Amazon ECS 任務定義](create-task-definition.md)。
這些指標將匯出至 Amazon Managed Service for Prometheus，並可以使用 Amazon Managed Grafana 儀表板查看。您必須使用 Prometheus 程式庫或 OpenTelemetry SDK 檢測應用程式。如需有關使用 OpenTelemetry SDK 檢測應用程式的詳細資訊，請參閱 [AWS Distro for OpenTelemetry 文件](https://aws-otel.github.io/docs/introduction)中的 AWS Distro for OpenTelemetry 簡介。
使用 Prometheus 程式庫時，您的應用程式必須公開 `/metrics` 端點，用於抓取指標資料。如需有關使用 Prometheus 程式庫檢測應用程式的詳細資訊，請參閱 Prometheus 文件中的 [Prometheus 用戶端程式庫](https://prometheus.io/docs/instrumenting/clientlibs/)。
## 考量事項
使用 Amazon ECS on Fargate 與 AWS Distro for OpenTelemetry 整合，將應用程式指標傳送至 Amazon Managed Service for Prometheus 時，應考慮下列事項。
+ 託管在 Fargate 上的 AWS Amazon ECS 工作負載和託管在 Amazon EC2 執行個體上的 Amazon ECS 工作負載支援 Distro for OpenTelemetry 整合。目前不支援外部執行個體。
+ 根據預設， AWS Distro for OpenTelemetry 會在匯出至 Amazon Managed Service for Prometheus 時包含應用程式指標的所有可用任務層級維度。您還可以檢測應用程式以增加其他維度。如需詳細資訊，請參閱 AWS Distro for OpenTelemetry 文件中的[適用於 Amazon Managed Service for Prometheus 的 Prometheus 遠端寫入匯出器入門](https://aws-otel.github.io/docs/getting-started/prometheus-remote-write-exporter)。
## AWS Distro for OpenTelemetry 與 Amazon Managed Service for Prometheus 整合所需的 IAM 許可
Amazon ECS 與使用 AWS Distro for OpenTelemetry 附屬的 Amazon Managed Service for Prometheus 整合需要您建立任務 IAM 角色，並在任務定義中指定角色。註冊任務定義之前，必須手動建立此任務的 IAM 角色。如需建立任務角色的詳細資訊，請參閱 [Amazon ECS 任務 IAM 角色](task-iam-roles.md)。
建議您也將 AWS Distro for OpenTelemetry 附屬項目設定為將容器日誌路由至 CloudWatch Logs，這也需要在任務定義中建立和指定任務執行 IAM 角色。Amazon ECS 主控台會代表您負責處理任務執行 IAM 角色，但任務 IAM 角色必須手動建立。如需有關為任務建立 IAM 角色的詳細資訊，請參閱 [Amazon ECS 任務執行 IAM 角色](task_execution_IAM_role.md)。
**重要**
如果您也使用 AWS Distro for OpenTelemetry 整合收集應用程式追蹤資料，請確定您的任務 IAM 角色也包含該整合所需的許可。如需詳細資訊，請參閱[使用應用程式追蹤資料識別 Amazon ECS 最佳化機會](trace-data.md)。
AWS Distro for OpenTelemetry 與 Amazon Managed Service for Prometheus 整合需要下列許可：
+ logs:PutLogEvents
+ logs:CreateLogGroup
+ logs:CreateLogStream
+ logs:DescribeLogStreams
+ logs:DescribeLogGroups
+ cloudwatch:PutMetricData
## 在任務定義中指定 AWS Distro for OpenTelemetry 附屬項目
Amazon ECS 主控台使用**使用指標收集**選項，簡化了建立 AWS Distro for OpenTelemetry 附屬容器的體驗。如需詳細資訊，請參閱[使用主控台建立 Amazon ECS 任務定義](create-task-definition.md)。
如果您不是使用 Amazon ECS 主控台，則可以手動將 AWS Distro for OpenTelemetry 附屬容器新增至任務定義。下列任務定義範例顯示為 Amazon Managed Service for Prometheus 整合新增 AWS Distro for OpenTelemetry 附屬項目的容器定義。
```
{
"family": "otel-using-cloudwatch",
"taskRoleArn": "arn:aws:iam::111122223333:role/AmazonECS_OpenTelemetryCloudWatchRole",
"executionRoleArn": "arn:aws:iam::111122223333:role/ecsTaskExecutionRole",
"containerDefinitions": [{
"name": "aws-otel-emitter",
"image": "application-image",
"logConfiguration": {
"logDriver": "awslogs",
"options": {
"awslogs-create-group": "true",
"awslogs-group": "/ecs/aws-otel-emitter",
"awslogs-region": "aws-region",
"awslogs-stream-prefix": "ecs"
}
},
"dependsOn": [{
"containerName": "aws-otel-collector",
"condition": "START"
}]
},
{
"name": "aws-otel-collector",
"image": "public.ecr.aws/aws-observability/aws-otel-collector:v0.30.0",
"essential": true,
"command": [
"--config=/etc/ecs/ecs-amp.yaml"
],
"environment": [{
"name": "AWS_PROMETHEUS_ENDPOINT",
"value": "https://aps-workspaces.aws-region.amazonaws.com/workspaces/ws-a1b2c3d4-5678-90ab-cdef-EXAMPLE11111/api/v1/remote_write"
}],
"logConfiguration": {
"logDriver": "awslogs",
"options": {
"awslogs-create-group": "True",
"awslogs-group": "/ecs/ecs-aws-otel-sidecar-collector",
"awslogs-region": "aws-region",
"awslogs-stream-prefix": "ecs"
}
}
}
],
"networkMode": "awsvpc",
"requiresCompatibilities": [
"FARGATE"
],
"cpu": "1024",
"memory": "3072"
}
```