# 将应用程序指标导出到 Amazon CloudWatch
<a name="application-metrics-cloudwatch"></a>

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)。

## 注意事项
<a name="application-metrics-cloudwatch-considerations"></a>

使用 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 权限
<a name="application-metrics-cloudwatch-iam"></a>

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 附加
<a name="application-metrics-cloudwatch-containerdefinitions"></a>

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