# 将 Amazon ECS 日志发送到 AWS 服务或 AWS Partner
<a name="using_firelens"></a>

您可以使用适用于 Amazon ECS 的 FireLens 来使用任务定义参数将日志路由到 AWS 服务或 AWS Partner Network（APN）目标来进行日志存储和分析。AWS Partner Network 是一个由合作伙伴组成的全球社区，它利用计划、专业知识和资源来构建、营销和销售客户产品。有关更多信息，请参阅 [AWS Partner](https://aws.amazon.com/partners/work-with-partners/)。FireLens 与 [Fluentd](https://www.fluentd.org/) 和 [Fluent Bit](https://fluentbit.io/) 结合使用。我们提供 AWS for Fluent Bit 映像，您也可以使用自己的 Fluentd 或 Fluent Bit 映像。

默认情况下，Amazon ECS 会配置容器依赖关系，以便 Firelens 容器先启动，任何使用它的容器随后启动。Firelens 容器也会在所有使用它的容器停止后才停止。

要使用此功能，您必须为您的任务创建一个 IAM 角色，该角色提供使用任务需要的任何 AWS 服务所需的权限。例如，如果容器将日志路由到 Firehose，则任务需要调用 `firehose:PutRecordBatch` API 的权限。有关更多信息，请参阅 *IAM用户指南*中的[添加和删除 IAM 标识权限](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_manage-attach-detach.html)。

在以下条件下，您的任务也可能需要 Amazon ECS 任务执行角色。有关更多信息，请参阅 [Amazon ECS 任务执行 IAM 角色](task_execution_IAM_role.md)。
+ 如果在 Fargate 上托管您的任务，并且您正在从 Amazon ECR 提取容器映像或 AWS Secrets Manager 在日志配置中引用敏感数据，那么您必须包含任务执行 IAM 角色。
+ 当您使用托管于 Amazon S3 中的自定义配置文件时，任务执行 IAM 角色必须包含 `s3:GetObject` 权限。

使用 FireLens for Amazon ECS 时考虑以下事项：
+ 建议您在日志容器名称中添加 `my_service_`，以便可以在控制台中轻松区分容器名称。
+ 默认情况下，Amazon ECS 在应用程序容器和 FireLens 容器之间添加启动容器顺序依赖关系。当您在应用程序容器和 FireLens 容器之间指定容器顺序时，默认的启动容器顺序将被覆盖。
+ 支持将适用于 Amazon ECS 的 FireLens 用于托管在 Linux 上的 AWS Fargate 和 Amazon EC2 的任务。Windows 容器不支持 FireLens。

  有关如何为 Windows 容器配置集中日志记录的信息，请参阅[使用 Fluent Bit 在 Amazon ECS 上对 Windows 容器进行集中日志记录](https://aws.amazon.com/blogs/containers/centralized-logging-for-windows-containers-on-amazon-ecs-using-fluent-bit/)。
+ 您可以使用 CloudFormation 模板为 Amazon ECS 配置 FireLens。有关更多信息，请参阅《AWS CloudFormation 用户指南》**中的 [AWS::ECS::TaskDefinition FirelensConfiguration](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-properties-ecs-taskdefinition-firelensconfiguration.html)
+ FireLens 在端口 `24224` 上侦听，因此为了确保从任务外部无法访问 FireLens 日志路由器，不得允许任务使用的安全组中端口 `24224` 上的入站流量。对于使用 `awsvpc` 网络模式的任务，这是与任务关联的安全组。对于使用 `host` 网络模式的任务，它是与托管任务的 Amazon EC2 实例关联的安全组。对于使用 `bridge` 网络模式的任务，请勿创建任何使用端口 `24224` 的端口映射。
+ 对于使用 `bridge` 网络模式的任务，具有 FirelLens 配置的容器必须在依赖它的任何应用程序容器启动之前启动。要控制容器的启动顺序，请在任务定义中使用依赖条件。有关更多信息，请参阅 [容器依赖项](task_definition_parameters.md#container_definition_dependson)。
**注意**  
如果您将容器定义中的依赖条件参数与 FirelLens 配置结合使用，请确保每个容器均具有 `START` 或 `HEALTHY` 条件要求。
+ 默认情况下，FireLens 将集群和任务定义名称以及集群的 Amazon 资源名称（ARN）作为元数据键添加到您的 stdout/stderr 容器日志中。以下为元数据格式的示例。

  ```
  "ecs_cluster": "{{cluster-name}}",
  "ecs_task_arn": "arn:aws:ecs:{{region}}:{{111122223333}}:task/{{cluster-name}}/{{f2ad7dba413f45ddb4EXAMPLE}}",
  "ecs_task_definition": "task-def-name:revision",
  ```

  如果您不希望日志中出现元数据，请在任务定义的 `firelensConfiguration` 部分中将 `enable-ecs-log-metadata` 设置为 `false`。

  ```
  "firelensConfiguration":{
     "type":"fluentbit",
     "options":{
        "enable-ecs-log-metadata":"false",
        "config-file-type":"file",
        "config-file-value":"/extra.conf"
  }
  ```

您可以将 FireLens 容器配置为以非根用户身份运行。请考虑以下事项：
+  要将 FireLens 容器配置为以非根用户身份运行，您必须使用以下其中一种格式指定用户：
  + `uid`
  + `uid:gid`
  + `uid:group`

  有关在容器定义中指定用户的更多信息，请参阅《Amazon Elastic Container Service API 参考》**中的 [ContainerDefinition](https://docs.aws.amazon.com/AmazonECS/latest/APIReference/API_ContainerDefinition.html)。

  FireLens 容器通过 UNIX 套接字接收应用程序日志。Amazon ECS 代理使用 `uid` 将套接字目录的所有权分配给 FireLens 容器。
+ 在 Amazon ECS 代理版本 `1.96.0` 及更高版本以及经 Amazon ECS 优化的 AMI 版本 `v20250716` 及更高版本上，支持将 FireLens 容器配置为以非根用户身份运行。
+ 当您为 FireLens 容器指定用户时，`uid` 必须是唯一的，并且不得用于属于任务中其他容器或容器实例的其他进程。

有关如何将多个配置文件用于 Amazon ECS 的信息（包括您托管的文件或 Amazon S3 中的文件），请参阅 [Init process for Fluent Bit on ECS, multi-config support](https://github.com/aws/aws-for-fluent-bit/tree/mainline/use_cases/init-process-for-fluent-bit)。

有关示例配置的信息，请参阅[Amazon ECS 任务定义示例：将日志路由到 FireLens](firelens-taskdef.md)。

有关配置日志以实现高吞吐量的更多信息，请参阅[配置 Amazon ECS 日志，以实现高吞吐量](firelens-docker-buffer-limit.md)。