# 使用应用程序指标关联 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 开发工具包进行分析。有关更多信息，请参阅 AWS Distro for OpenTelemetry 文档中的 [AWS Distro for OpenTelemetry 的介绍](https://aws-otel.github.io/docs/introduction)。
## 注意事项
使用 Fargate 上的 Amazon ECS 与 AWS Distro for OpenTelemetry 集成将应用程序指标发送到 Amazon CloudWatch 时，应考虑以下因素。
+ 此集成仅将您的自定义应用程序指标发送到 CloudWatch。如果您需要任务级指标，可以在 Amazon ECS 集群配置中启用 Container Insights。有关更多信息，请参阅 [使用具有增强型可观测性的 Container Insights 监控 Amazon ECS 容器](cloudwatch-container-insights.md)。
+ Fargate 和 Amazon EC2 实例上托管的 Amazon ECS 工作负载支持 AWS Distro for OpenTelemetry 集成。目前不支持外部实例。
+ CloudWatch 对每个指标最多支持 30 个维度。预设情况下，Amazon ECS 默认将 `TaskARN`、`ClusterARN`、`LaunchType`、`TaskDefinitionFamily` 和 `TaskDefinitionRevision` 维度包含到指标中。其余 25 个维度可以由您的应用程序定义。如果配置了超过 30 个维度，CloudWatch 将无法显示它们。发生这种情况时，应用程序指标将出现在 `ECS/AWSOTel/Application` CloudWatch 指标命名空间中，但没有任何维度。您可以对应用程序进行分析以添加其他维度。有关更多信息，请参阅 AWS Distro for OpenTelemetry 文档中的[将 CloudWatch 指标与 AWS Distro for OpenTelemetry 结合使用](https://aws-otel.github.io/docs/getting-started/cloudwatch-metrics)。
## 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 管理控制台，然后通过以下网址打开 IAM 控制台：[https://console.aws.amazon.com/iam/](https://console.aws.amazon.com/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. 检查该角色，然后选择**创建角色**。
## 在您的任务定义中指定 AWS Distro for OpenTelemetry 附加
Amazon ECS 控制台通过使用**使用指标收集**选项简化创建 AWS Distro for OpenTelemetry 附加容器的体验。有关更多信息，请参阅 [使用控制台创建 Amazon ECS 任务定义](create-task-definition.md)。
如果您没有使用 Amazon ECS 控制台，则可以手动添加 AWS Distro for OpenTelemetry 附加容器到您的任务定义中。以下任务定义示例显示了用于添加 AWS Distro for OpenTelemetry 附加以进行 Amazon CloudWatch 集成的容器定义。
```
{
"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 开发工具包进行分析。有关使用 OpenTelemetry 开发工具包分析您的应用程序的更多信息，请参阅 AWS Distro for OpenTelemetry 文档中的 [AWS Distro for OpenTelemetry 的介绍](https://aws-otel.github.io/docs/introduction)。
使用 Prometheus 库时，您的应用程序必须公开用于抓取指标数据的 `/metrics` 端点。有关使用 Prometheus 库分析您的应用程序的更多信息，请参阅 Prometheus 文档中的 [Prometheus 客户端库](https://prometheus.io/docs/instrumenting/clientlibs/)。
## 注意事项
使用 Fargate 上的 Amazon ECS 与 AWS Distro for OpenTelemetry 的集成向 Amazon Managed Service for Prometheus 发送应用程序指标时，应考虑以下因素。
+ Fargate 和 Amazon EC2 实例上托管的 Amazon ECS 工作负载支持 AWS Distro for OpenTelemetry 集成。目前不支持外部实例。
+ 预设情况下，在向 Amazon Managed Service for Prometheus 导出时，AWS Distro for OpenTelemetry 包括可用于您的应用程序指标的所有可用的任务级别维度。您还可以对应用程序进行分析以添加其他维度。有关更多信息，请参阅 AWS Distro for OpenTelemetry 文档中的[开始将 Prometheus Remote Write Exporter 用于 Amazon Managed Service for 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 附加容器到您的任务定义中。以下任务定义示例显示了用于添加 AWS Distro for OpenTelemetry 附加以进行 Amazon Managed Service for Prometheus 集成的容器定义。
```
{
"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"
}
```