# Amazon ECS 로그를 AWS 서비스 또는 AWS Partner로 전송
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 컨테이너는 해당 컨테이너를 사용하는 모든 컨테이너가 중지된 후에 중지됩니다.
이 기능을 사용하려면 태스크에 필요한 AWS 서비스 사용에 필수적인 권한을 제공하는 태스크에 IAM 역할을 생성해야 합니다. 예를 들어, 컨테이너가 로그를 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` 권한이 포함되어야 합니다.
Amazon ECS용 FireLens를 사용할 때는 다음 사항을 고려해야 합니다.
+ 콘솔에서 컨테이너 이름을 쉽게 구분할 수 있도록 로그 컨테이너 이름에 `my_service_`를 추가하는 것이 좋습니다.
+ Amazon ECS는 기본적으로 애플리케이션 컨테이너와 FireLens 컨테이너 사이에서 시작 컨테이너 순서 종속성을 추가합니다. 애플리케이션 컨테이너와 FireLens 컨테이너 사이에서 컨테이너 순서를 지정하면 기본 시작 컨테이너 순서가 재정의됩니다.
+ Amazon ECS용 FireLens는 Linux의 AWS Fargate와 Linux의 Amazon EC2 모두에서 호스팅되는 작업에 대해 지원됩니다. Windows 컨테이너는 FireLens를 지원하지 않습니다.
Windows 컨테이너에 대한 중앙 집중식 로깅을 구성하는 방법에 대한 자세한 내용은 [Centralized logging for Windows containers on Amazon ECS using Fluent Bit](https://aws.amazon.com/blogs/containers/centralized-logging-for-windows-containers-on-amazon-ecs-using-fluent-bit/)(Fluent Bit를 사용하여 Amazon ECS에서 Windows 컨테이너에 대한 중앙 집중식 로깅)를 참조하세요.
+ CloudFormation 템플릿을 사용하여 Amazon ECS를 위한 FireLens를 구성할 수 있습니다. 자세한 정보는 *AWS CloudFormation 사용 설명서*의 [::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` 네트워크 모드를 사용하는 작업의 경우 FireLens 구성이 포함된 컨테이너는 해당 컨테이너를 사용하는 모든 애플리케이션 컨테이너가 시작되기 전에 시작해야 합니다. 컨테이너의 시작 순서를 제어하려면 태스크 정의에서 종속성 조건을 사용하세요. 자세한 정보는 [컨테이너 종속성](task_definition_parameters.md#container_definition_dependson) 섹션을 참조하세요.
**참고**
FireLens 구성과 함께 컨테이너 정의에서 종속성 조건 파라미터를 사용하는 경우 각 컨테이너에 `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 컨테이너에 할당합니다.
+ 루트가 아닌 사용자로 실행하도록 FireLens 컨테이너를 구성하는 방법은 Amazon ECS 에이전트 버전 `1.96.0` 이상 및 Amazon ECS 최적화 AMI 버전 `v20250716` 이상에서 지원됩니다.
+ FireLens 컨테이너에 사용자를 지정할 때 `uid`는 고유해야 하며 태스크 또는 컨테이너 인스턴스의 다른 컨테이너에 속하는 다른 프로세스에는 사용되지 않아야 합니다.
호스팅하는 파일 또는 Amazon S3에 있는 파일을 포함하여 Amazon ECS에서 여러 구성 파일을 사용하는 방법에 대한 자세한 내용은 [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) 섹션을 참조하세요.
# 높은 처리량을 위한 Amazon ECS 로그 구성
로그 처리량이 많은 시나리오의 경우, FireLens 및 Fluent Bit와(과) 함께 `awsfirelens` 로그 드라이버를 사용하는 것이 좋습니다. Fluent Bit은(는) 리소스를 효율적으로 사용하며 수백만 개의 로그 레코드를 처리할 수 있는 경량 로그 프로세서입니다. 하지만 대규모 환경에서 최적의 성능을 달성하려면 구성을 조정해야 합니다.
이 섹션에서는 시스템 안정성을 유지하고 데이터 손실이 없도록 보장하면서 높은 로그 처리량을 처리하기 위한 고급 Fluent Bit 최적화 기술을 다룹니다.
FireLens에서 사용자 지정 구성 파일을 사용하는 방법에 대한 자세한 내용은 [사용자 지정 구성 파일 사용](firelens-taskdef.md#firelens-taskdef-customconfig)을(를) 참고하세요. 추가 예제는 GitHub의 [Amazon ECS FireLens 예제](https://github.com/aws-samples/amazon-ecs-firelens-examples)를 확인하세요.
**참고**
`workers` 및 `threaded`와(과) 같은 이 섹션의 일부 구성 옵션에는 Fluent Bit 버전 3 이상을 위한 AWS이(가) 필요합니다. 사용 가능한 버전에 대한 자세한 내용은 [Fluent Bit 릴리스에 대한 AWS](https://github.com/aws/aws-for-fluent-bit/releases)을(를) 참고하세요.
## 파일 시스템 버퍼링 사용
기본적으로 Fluent Bit은(는) 모든 데이터를 메모리에 버퍼링합니다. 데이터가 출력으로 플러시되는 속도보다 빠르게 수집되면 버퍼가 가득 찹니다. 버퍼가 가득 차면 버퍼 스페이스가 확보될 때까지 입력 플러그인이 일시 중지되며, 이로 인해 백프레셔가 발생하고 애플리케이션 속도가 느려질 수 있습니다.
처리량이 많은 시나리오의 경우 파일 시스템 버퍼링을 사용하는 것이 좋습니다. Fluent Bit이(가) 버퍼링과 스토리지를 관리하는 방법에 대한 자세한 내용은 Fluent Bit 문서의 [버퍼링 및 스토리지](https://docs.fluentbit.io/manual/administration/buffering-and-storage) 섹션을 참고하세요.
파일 시스템 버퍼링은 다음과 같은 장점을 제공합니다:
+ **더 큰 버퍼 용량** – 일반적으로 디스크 스페이스를 메모리보다 훨씬 여유가 있습니다.
+ **지속성** - 버퍼링된 데이터는 Fluent Bit(이)가 재시작되어도 유지됩니다.
+ **점진적 성능 저하** - 출력 오류가 발생해도 데이터가 메모리를 고갈시키는 대신 디스크에 축적됩니다.
파일 시스템 버퍼링을 활성화하려면 사용자 지정 Fluent Bit 구성 파일을 제공하세요. 다음 예시는 권장 구성을 보여줍니다:
```
[SERVICE]
# Flush logs every 1 second
Flush 1
# Wait 120 seconds during shutdown to flush remaining logs
Grace 120
# Directory for filesystem buffering
storage.path /var/log/flb-storage/
# Limit chunks stored 'up' in memory (reduce for memory-constrained environments)
storage.max_chunks_up 32
# Flush backlog chunks to destinations during shutdown (prevents log loss)
storage.backlog.flush_on_shutdown On
[INPUT]
Name forward
unix_path /var/run/fluent.sock
# Run input in separate thread to prevent blocking
threaded true
# Enable filesystem buffering for persistence
storage.type filesystem
[OUTPUT]
Name cloudwatch_logs
Match *
region us-west-2
log_group_name /aws/ecs/my-app
log_stream_name $(ecs_task_id)
# Use multiple workers for parallel processing
workers 2
# Retry failed flushes up to 15 times
retry_limit 15
# Maximum disk space for buffered data for this output
storage.total_limit_size 10G
```
주요 구성 파라미터:
`storage.path`
Fluent Bit이(가) 디스크에 버퍼링된 청크를 저장하는 디렉터리입니다.
`storage.backlog.flush_on_shutdown`
이 기능이 활성화되면 Fluent Bit은(는) 종료 시 백로그에 있는 모든 파일 시스템 청크를 대상지로 플러시하려고 시도합니다. 이는 Fluent Bit이(가) 중지되기 전에 데이터 전달을 보장하는 데 도움이 되지만, 종료 시간이 늘어날 수 있습니다.
`storage.max_chunks_up`
메모리에 남아 있는 청크의 수입니다. 기본값은 128개 청크이며, 각 청크가 최대 4\$15MB를 사용할 수 있기 때문에 500MB 이상의 메모리를 소비할 수 있습니다. 메모리가 제한된 환경에서는 이 값을 낮추세요. 예를 들어 버퍼링에 사용할 수 있는 공간이 50MB라면, 이 값을 8\$110개 청크로 설정합니다.
`storage.type filesystem`
입력 플러그인에 대해 파일 시스템 스토리지를 활성화합니다. 이름과 달리 Fluent Bit은(는) `mmap`을(를) 사용하여 청크를 메모리와 디스크 모두에 매핑하며, 성능 저하 없이 지속성을 제공합니다.
`threaded true`
Fluent Bit의 메인 이벤트 루프와 별개로 입력을 자체 스레드에서 실행합니다. 이렇게 하면 느린 입력이 전체 파이프라인을 차단하는 것을 방지합니다.
## 출력 구성 최적화
네트워크 문제, 서비스 중단, 대상지의 스로틀링 등으로 인해 로그가 전달되지 않을 수 있습니다. 적절한 출력 구성은 데이터 손실 없는 복원력을 보장합니다.
출력 플러시가 실패하면 Fluent Bit은(는) 해당 작업을 재시도할 수 있습니다. 다음 파라미터는 재시도 동작을 제어합니다:
`retry_limit`
레코드를 삭제하기 전까지의 최대 재시도 횟수입니다. 기본값은 1입니다. 프로덕션 환경의 경우 15회 이상으로 설정하는 것을 권장하며, 이는 지수 백오프를 통해 몇 분간의 장애 상황을 커버할 수 있습니다.
`scheduler.base`
재시도 간의 최소 초 단위 시간입니다. 10초를 권장합니다.
`scheduler.cap`
지수 백오프 사용 시 재시도 간의 최대 초 단위 시간입니다. 60초를 권장합니다.
`workers`
병렬 출력 처리를 위한 스레드 수입니다. 여러 워커를 사용하면 플러시를 동시에 수행할 수 있어, 많은 청크를 처리할 때 처리량이 향상됩니다.
`[SERVICE]` 섹션의 `Grace` 파라미터는 종료 시 버퍼링된 데이터를 플러시하기 위해 Fluent Bit이(가) 대기하는 시간을 설정합니다. `Grace` 기간은 컨테이너의 `stopTimeout`와(과) 연계하여 조정해야 합니다. Fluent Bit이(가) `SIGKILL`을(를) 받기 전에 플러시를 완료할 수 있도록 `stopTimeout`이(가) `Grace` 기간을 초과하도록 설정하세요. 예를 들어 `Grace`이(가) 120초라면, `stopTimeout`은(는) 150초로 설정합니다.
다음 예시는 높은 처리량 시나리오를 위해 권장되는 모든 설정이 포함된 전체 Fluent Bit 구성을 보여줍니다.
```
[SERVICE]
# Flush logs every 1 second
Flush 1
# Wait 120 seconds during shutdown to flush remaining logs
Grace 120
# Directory for filesystem buffering
storage.path /var/log/flb-storage/
# Limit chunks stored 'up' in memory (reduce for memory-constrained environments)
storage.max_chunks_up 32
# Flush backlog chunks to destinations during shutdown (prevents log loss)
storage.backlog.flush_on_shutdown On
# Minimum seconds between retries
scheduler.base 10
# Maximum seconds between retries (exponential backoff cap)
scheduler.cap 60
[INPUT]
Name forward
unix_path /var/run/fluent.sock
# Run input in separate thread to prevent blocking
threaded true
# Enable filesystem buffering for persistence
storage.type filesystem
[OUTPUT]
Name cloudwatch_logs
Match *
region us-west-2
log_group_name /aws/ecs/my-app
log_stream_name $(ecs_task_id)
# Use multiple workers for parallel processing
workers 2
# Retry failed flushes up to 15 times
retry_limit 15
# Maximum disk space for buffered data for this output
storage.total_limit_size 10G
```
## 안전성을 위해 다중 대상 로깅 사용
로그를 여러 대상으로 전송하면 단일 장애점을 제거할 수 있습니다. 예를 들어 CloudWatch Logs에 장애가 발생하더라도 로그는 여전히 Amazon S3에 도달합니다.
다중 대상 로깅은 다음과 같은 이점을 제공합니다. Amazon S3 출력 플러그인은 gzip 및 Parquet 형식과 같은 압축 옵션도 지원하여 스토리지 비용을 절감할 수 있습니다. 자세한 내용은 Fluent Bit 문서의 [S3 압축](https://docs.fluentbit.io/manual/pipeline/outputs/s3#compression) 섹션을 참고하세요.
다중 대상 로깅은 다음과 같은 이점을 제공할 수 있습니다:
+ **중복성** - 한 곳의 대상지에 장애가 발생해도 로그는 다른 곳에 도달합니다.
+ **복구** - 한 시스템의 데이터 공백을 다른 시스템을 통해 재구성합니다.
+ **내구성** - 장기 보관을 위해 Amazon S3에 로그를 아카이빙합니다.
+ **비용 최적화** - .최근 로그는 보관 주기가 짧고 쿼리가 빠른 CloudWatch Logs에 보관하고, 모든 로그는 장기 보관을 위해 비용이 저렴한 Amazon S3 스토리지에 아카이빙합니다.
다음 Fluent Bit 구성은 CloudWatch Logs와 Amazon S3 모두에 로그를 전송합니다.
```
[OUTPUT]
Name cloudwatch_logs
Match *
region us-west-2
log_group_name /aws/ecs/my-app
log_stream_name $(ecs_task_id)
workers 2
retry_limit 15
[OUTPUT]
Name s3
Match *
bucket my-logs-bucket
region us-west-2
total_file_size 100M
s3_key_format /fluent-bit-logs/$(ecs_task_id)/%Y%m%d/%H/%M/$UUID
upload_timeout 10m
# Maximum disk space for buffered data for this output
storage.total_limit_size 5G
```
두 출력 모두 동일한 `Match *` 패턴을 사용하므로, 모든 레코드가 두 대상지에 각각 독립적으로 전송됩니다. 한 곳의 대상지에 장애가 발생하더라도 로그는 다른 곳으로 계속 흐르며, 실패한 플러시는 나중에 재시도할 수 있도록 파일 시스템 버퍼에 축적됩니다.
## tail 입력 플러그인을 사용한 파일 기반 로깅 사용
로그 손실이 중요한 문제인 높은 처리량 시나리오에서는 대안적인 접근 방식을 사용할 수 있습니다. 애플리케이션이 로그를 디스크 파일에 쓰고, Fluent Bit이(가) `tail` 입력 플러그인을 사용하여 해당 파일을 읽도록 구성하는 방식입니다. 이 방식은 Docker 로깅 드라이버 레이어를 완전히 우회합니다.
tail 플러그인을 사용한 파일 기반 로깅은 다음과 같은 이점을 제공합니다:
+ **오프셋 추적** - tail 플러그인은 (`DB` 옵션을 사용하여) 데이터베이스 파일에 파일 오프셋을 저장할 수 있어, Fluent Bit 재시작 시에도 내구성을 제공합니다. 컨테이너 재시작 시 로그 손실이 발생하는 것을 방지하는 데 도움이 됩니다.
+ **입력 수준 버퍼링** - `Mem_Buf_Limit`을(를) 사용하여 입력 플러그인에서 직접 메모리 버퍼 제한을 구성할 수 있으며, 이를 통해 메모리 사용량을 더욱 세밀하게 제어할 수 있습니다.
+ **Docker 오버헤드 방지** – 로그가 Docker의 로그 버퍼를 거치지 않고 파일에서 Fluent Bit(으)로 직접 전달됩니다.
이 방식을 사용하려면 애플리케이션이 `stdout` 대신 파일에 로그를 기록해야 합니다. 애플리케이션 컨테이너와 Fluent Bit 컨테이너 모두 로그 파일이 저장된 공유 볼륨을 마운트합니다.
다음 예시는 모범 사례가 적용된 tail 입력 구성을 보여줍니다.
```
[INPUT]
Name tail
# File path or glob pattern to tail
Path /var/log/app.log
# Database file for storing file offsets (enables resuming after restart)
DB /var/log/flb_tail.db
# when true, controls that only fluent-bit will access the database (improves performance)
DB.locking true
# Skip long lines instead of skipping the entire file
Skip_Long_Lines On
# How often (in seconds) to check for new files matching the glob pattern
Refresh_Interval 10
# Extra seconds to monitor a file after rotation to account for pending flush
Rotate_Wait 30
# Maximum size of the buffer for a single line
Buffer_Max_Size 10MB
# Initial allocation size for reading file data
Buffer_Chunk_Size 1MB
# Maximum memory buffer size (tail pauses when full)
Mem_Buf_Limit 75MB
```
tail 입력 플러그인을 사용할 때는 다음 사항을 고려하세요:
+ 디스크 소진을 방지하기 위해 애플리케이션 로그에 대한 로그 로테이션을 구현하세요. 성능을 측정하기 위해 기본 볼륨 메트릭을 모니터링합니다.
+ 로그 형식에 따라 `Ignore_Older`, `Read_from_Head` 및 멀티라인 파서와 같은 설정을 고려하세요.
자세한 내용은 Fluent Bit 문서의 [Tail](https://docs.fluentbit.io/manual/pipeline/inputs/tail) 섹션을 참고하세요. 모범 사례는 AWS을(를) 위한 Fluent Bit 문제 해결 가이드의 [Tail config with best practices](https://github.com/aws/aws-for-fluent-bit/blob/mainline/troubleshooting/debugging.md#tail-config-with-best-practices)를 참고하세요.
## FireLens로 직접 로깅
`awsfirelens` 로그 드라이버가 태스크 정의에 지정되어 있으면 Amazon ECS 컨테이너 에이전트는 다음 환경 변수를 컨테이너에 주입합니다.
`FLUENT_HOST`
FireLens 컨테이너에 할당된 IP 주소입니다.
`bridge` 네트워크 모드에서 EC2를 사용하는 경우 FireLens 로그 라우터 컨테이너(컨테이너 정의에 `firelensConfiguration` 객체가 있는 컨테이너)를 다시 시작한 후 애플리케이션 컨테이너의 `FLUENT_HOST` 환경 변수가 부정확해질 수 있습니다. 이는 `FLUENT_HOST`가 동적 IP 주소이며 재시작 후 변경될 수 있기 때문입니다. 애플리케이션 컨테이너에서 `FLUENT_HOST` IP 주소로 직접 로깅하면 주소가 변경된 후 실패하기 시작할 수 있습니다. 개별 컨테이너를 재시작하는 방법에 대한 자세한 내용은 [컨테이너 재시작 정책이 있는 Amazon ECS 작업의 개별 컨테이너 재시작](container-restart-policy.md) 섹션을 참조하세요.
`FLUENT_PORT`
Fluent Forward 프로토콜이 수신 대기 중인 포트입니다.
이 환경 변수들을 사용하면 `stdout`에 기록하는 대신 Fluent Forward 프로토콜을 사용하여 애플리케이션 코드에서 Fluent Bit 로그 라우터로 직접 로그를 보낼 수 있습니다. 이 방식은 Docker 로깅 드라이버 레이어를 우회하며 다음과 같은 이점을 제공합니다:
+ **낮은 대기 시간** – 로그가 Docker의 로깅 인프라를 거치지 않고 Fluent Bit(으)로 직접 전달됩니다.
+ **구조화된 로깅** - JSON 인코딩 오버헤드 없이 구조화된 로그 데이터를 기본적으로 전송합니다.
+ **제어력 향상** - 애플리케이션이 자체적인 버퍼링 및 오류 처리 로직을 구현할 수 있습니다.
다음 Fluent 로거 라이브러리는 Fluent Forward 프로토콜을 지원하며 Fluent Bit(으)로 로그를 직접 보내는 데 사용할 수 있습니다.
+ **Go** – [fluent-logger-golang](https://github.com/fluent/fluent-logger-golang)
+ **Python** – [fluent-logger-python](https://github.com/fluent/fluent-logger-python)
+ **Java** – [fluent-logger-java](https://github.com/fluent/fluent-logger-java)
+ **Node.js** – [fluent-logger-node](https://github.com/fluent/fluent-logger-node)
+ **Ruby** – [fluent-logger-ruby](https://github.com/fluent/fluent-logger-ruby)
## Docker 버퍼 제한 구성
태스크 정의를 생성할 때 `log-driver-buffer-limit`에 값을 지정하여 메모리에 버퍼링되는 로그 라인의 수를 지정할 수 있습니다. 이는 Docker와 Fluent Bit 사이의 버퍼를 제어합니다. 자세한 정보는 Docker 설명서의 [Fluentd logging driver](https://docs.docker.com/engine/logging/drivers/fluentd/)(Fluentd 로깅 드라이버)를 참조하세요.
Docker에서 버퍼 메모리가 부족하여 새 메시지를 추가할 수 있도록 버퍼 메시지를 삭제할 수 있으므로 처리량이 많을 때 이 옵션을 사용합니다.
이 옵션을 사용할 때 다음 사항을 고려하세요:
+ 이 옵션은 플랫폼 버전 `1.4.0` 이상의 EC2 및 Fargate 유형에서 지원됩니다.
+ 이 옵션은 `logDriver`가 `awsfirelens`로 설정된 경우에만 유효합니다.
+ 기본 버퍼 제한은 `1048576`개의 로그 줄입니다.
+ 버퍼 제한은 로그 라인 `0`줄 이상, `536870912`줄 미만이어야 합니다.
+ 이 버퍼에 사용되는 최대 메모리 양은 각 로그 줄의 크기와 버퍼 크기를 곱한 값입니다. 예를 들어 애플리케이션의 로그 라인이 평균 `2`KiB라면, 버퍼 제한을 4096으로 설정했을 때 최대 `8`MiB를 사용합니다. 작업 수준에서 할당된 총 메모리 양은 로그 드라이버 메모리 버퍼 외에도 모든 컨테이너에 할당된 메모리 양보다 커야 합니다.
다음 태스크 정의는 `log-driver-buffer-limit`을(를) 구성하는 방법을 보여줍니다.
```
{
"containerDefinitions": [
{
"name": "my_service_log_router",
"image": "public.ecr.aws/aws-observability/aws-for-fluent-bit:3",
"cpu": 0,
"memoryReservation": 51,
"essential": true,
"firelensConfiguration": {
"type": "fluentbit"
}
},
{
"essential": true,
"image": "public.ecr.aws/docker/library/httpd:latest",
"name": "app",
"logConfiguration": {
"logDriver": "awsfirelens",
"options": {
"Name": "firehose",
"region": "us-west-2",
"delivery_stream": "my-stream",
"log-driver-buffer-limit": "52428800"
}
},
"dependsOn": [
{
"containerName": "my_service_log_router",
"condition": "START"
}
],
"memoryReservation": 100
}
]
}
```
# Amazon ECS용 Fluent Bit 이미지 리포지토리에 대한 AWS
AWS는 CloudWatch Logs 및 Firehose 모두에 대해 플러그인과 함께 Fluent Bit 이미지를 제공합니다. Fluent Bit가 Fluentd보다 리소스 사용률이 낮으므로 Fluent Bit를 로그 라우터로 사용하는 것이 좋습니다. 자세한 정보는 [Fluent Bit용 CloudWatch Logs](https://github.com/aws/amazon-cloudwatch-logs-for-fluent-bit) 및 [Fluent Bit용 Amazon Kinesis Firehose](https://github.com/aws/amazon-kinesis-firehose-for-fluent-bit)를 참조하세요.
**AWS for Fluent Bit** 이미지는 고가용성을 위해 Amazon ECR 퍼블릭 갤러리와 Amazon ECR 리포지토리에 있는 Amazon ECR에 사용할 수 있습니다.
## Amazon ECR 퍼블릭 갤러리
AWS for Fluent Bit 이미지는 Amazon ECR 퍼블릭 갤러리에서 사용할 수 있습니다. Amazon ECR 퍼블릭 갤러리는 퍼블릭 리포지토리이며 모든 AWS 리전에서 사용할 수 있으므로 여기에 AWS for Fluent Bit 이미지를 다운로드하는 것이 좋습니다. 자세한 정보는 Amazon ECR 퍼블릭 갤러리의 [aws-for-fluent-bit](https://gallery.ecr.aws/aws-observability/aws-for-fluent-bit)를 참조하세요.
### Linux
Amazon ECR 퍼블릭 갤러리의 AWS for Fluent Bit 이미지는 `ARM64` 또는 `x86-64` 아키텍처가 있는 Amazon Linux 운영 체제를 지원합니다.
원하는 이미지 태그로 리포지토리 URL을 지정하여 Amazon ECR 퍼블릭 갤러리에서 AWS for Fluent Bit 이미지를 가져올 수 있습니다. 사용 가능한 이미지 태그는 Amazon ECR 퍼블릭 갤러리의 **이미지 태그(Image tags)** 탭에서 확인할 수 있습니다.
Docker CLI에 사용할 구문은 다음과 같습니다.
```
docker pull public.ecr.aws/aws-observability/aws-for-fluent-bit:tag
```
예를 들어, 이 Docker CLI 명령을 사용하여 Fluent Bit 릴리스를 위한 AWS의 "3.x" 제품군 최신 이미지를 가져올 수 있습니다.
```
docker pull public.ecr.aws/aws-observability/aws-for-fluent-bit:3
```
**참고**
인증되지 않은 풀은 허용되지만 인증된 가져오기보다 속도 제한이 낮습니다. 가져오기 전 AWS 계정을 인증하려면 다음 명령을 사용합니다.
```
aws ecr-public get-login-password --region us-east-1 | docker login --username AWS --password-stdin public.ecr.aws
```
#### Fluent Bit 3.0.0에 대한 AWS
기존의 AWS for Fluent Bit 버전 `2.x` 외에도, AWS for Fluent Bit는 새 주 버전 `3.x`을 지원합니다. 새 주 버전에는 Amazon Linux 2에서 Amazon Linux 2023으로 이미지를 업그레이드하고 Fluent Bit 버전 `1.9.10`을 `4.1.1`로 업그레이드하는 작업이 포함되어 있습니다. 자세한 내용은 GitHub의 [AWS for Fluent Bit repository](https://github.com/aws/aws-for-fluent-bit/blob/mainline/VERSIONS.md)를 참조하세요.
다음 예제에서는 AWS for Fluent Bit `3.x` 이미지에 대한 업데이트된 태그를 보여줍니다.
AWS for Fluent Bit 이미지에 대해 다중 아키텍처 태그를 사용할 수 있습니다.
```
docker pull public.ecr.aws/aws-observability/aws-for-fluent-bit:3
```
### Windows
Amazon ECR 퍼블릭 갤러리의 AWS for Fluent Bit 이미지는 다음 운영 체제를 사용하는 `AMD64` 아키텍처를 지원합니다.
+ Windows Server 2022 Full
+ Windows Server 2022 Core
+ Windows Server 2019 Full
+ Windows Server 2019 Core
AWS Fargate에 있는 Windows 컨테이너는 FireLens를 지원하지 않습니다.
원하는 이미지 태그로 리포지토리 URL을 지정하여 Amazon ECR 퍼블릭 갤러리에서 AWS for Fluent Bit 이미지를 가져올 수 있습니다. 사용 가능한 이미지 태그는 Amazon ECR 퍼블릭 갤러리의 **이미지 태그(Image tags)** 탭에서 확인할 수 있습니다.
Docker CLI에 사용할 구문은 다음과 같습니다.
```
docker pull public.ecr.aws/aws-observability/aws-for-fluent-bit:tag
```
예를 들어 이 Docker CLI 명령을 사용하여 안정적인 최신 AWS for Fluent Bit 이미지를 가져올 수 있습니다.
```
docker pull public.ecr.aws/aws-observability/aws-for-fluent-bit:windowsservercore-stable
```
**참고**
인증되지 않은 풀은 허용되지만 인증된 가져오기보다 속도 제한이 낮습니다. 가져오기 전 AWS 계정을 인증하려면 다음 명령을 사용합니다.
```
aws ecr-public get-login-password --region us-east-1 | docker login --username AWS --password-stdin public.ecr.aws
```
## Amazon ECR
Fluent Bit용 AWS 이미지는 고가용성을 위해 Amazon ECR에서 사용할 수 있습니다. 다음 명령을 사용하여 지정된 AWS 리전에서 이미지 URI를 검색하고 이미지 가용성을 설정할 수 있습니다.
### Linux
다음 명령을 사용하여 안정적인 AWS for Fluent Bit 이미지 URI를 검색할 수 있습니다.
```
aws ssm get-parameters \
--names /aws/service/aws-for-fluent-bit/stable \
--region us-east-1
```
다음 명령을 사용하여 모든 버전의 Fluent Bit용 AWS 이미지를 나열하고 Systems Manager 파라미터 스토어 파라미터를 쿼리할 수 있습니다.
```
aws ssm get-parameters-by-path \
--path /aws/service/aws-for-fluent-bit \
--region us-east-1
```
안정적인 최신 AWS for Fluent Bit 이미지는 Systems Manager Parameter Store 이름을 참조하여 CloudFormation 템플릿에서 참조할 수 있습니다. 다음은 예제입니다.
```
Parameters:
FireLensImage:
Description: Fluent Bit image for the FireLens Container
Type: AWS::SSM::Parameter::Value
Default: /aws/service/aws-for-fluent-bit/stable
```
**참고**
명령이 실패하거나 출력이 없는 경우 명령이 직접 호출되는 AWS 리전에서 이미지를 사용할 수 없습니다.
### Windows
다음 명령을 사용하여 안정적인 AWS for Fluent Bit 이미지 URI를 검색할 수 있습니다.
```
aws ssm get-parameters \
--names /aws/service/aws-for-fluent-bit/windowsservercore-stable \
--region us-east-1
```
다음 명령을 사용하여 모든 버전의 Fluent Bit용 AWS 이미지를 나열하고 Systems Manager 파라미터 스토어 파라미터를 쿼리할 수 있습니다.
```
aws ssm get-parameters-by-path \
--path /aws/service/aws-for-fluent-bit/windowsservercore \
--region us-east-1
```
안정적인 최신 AWS for Fluent Bit 이미지는 Systems Manager 파라미터 스토어 이름을 참조하여 CloudFormation 템플릿에서 참조할 수 있습니다. 다음은 예제입니다.
```
Parameters:
FireLensImage:
Description: Fluent Bit image for the FireLens Container
Type: AWS::SSM::Parameter::Value
Default: /aws/service/aws-for-fluent-bit/windowsservercore-stable
```
# Amazon ECS 태스크 정의 예제: 로그를 FireLens로 라우팅
FireLens에서 사용자 정의 로그 라우팅을 사용하려면 태스크 정의에 다음 사항을 지정해야 합니다.
+ FireLens 구성을 포함하는 로그 라우터 컨테이너. 컨테이너는 `essential`로 표시하는 것이 좋습니다.
+ `awsfirelens` 로그 드라이버를 지정하는 로그 구성이 포함된 하나 이상의 애플리케이션 컨테이너.
+ 태스크가 로그를 라우팅하는 데 필요한 권한이 포함된 태스크 IAM 역할 Amazon 리소스 이름(ARN).
AWS Management Console을 사용하여 새로운 태스크 정의를 생성할 때 로그 라우터 컨테이너를 쉽게 추가할 수 있는 FireLens 통합 섹션이 있습니다. 자세한 정보는 [콘솔을 사용하여 Amazon ECS 작업 정의 생성](create-task-definition.md) 섹션을 참조하세요.
Amazon ECS는 로그 구성을 변환하고 Fluentd 또는 Fluent Bit 출력 구성을 생성합니다. 출력 구성은 Fluent Bit의 경우 `/fluent-bit/etc/fluent-bit.conf`, Fluentd의 경우 `/fluentd/etc/fluent.conf`에서 로그 라우팅 컨테이너에 마운트됩니다.
**중요**
FireLens의 수신 포트는 `24224`입니다. 그러므로 FireLens 로그 라우터가 태스크 범위를 벗어나지 않도록 태스크에서 사용하는 보안 그룹의 포트 `24224`에서 수신 트래픽을 허용해서는 안 됩니다. `awsvpc` 네트워크 모드를 사용하는 작업의 경우 이것은 태스크와 연결된 보안 그룹입니다. `host` 네트워크 모드를 사용하는 태스크의 경우 이것은 태스크를 호스팅하는 Amazon EC2 인스턴스와 연결된 보안 그룹입니다. `bridge` 네트워크 모드를 사용하는 태스크의 경우 포트 `24224`를 사용하는 포트 매핑을 생성하지 마세요.
기본적으로 Amazon ECS는 로그 원본을 식별하는 데 도움이 되는 추가 필드를 로그 항목에 추가합니다.
+ `ecs_cluster` - 태스크가 속한 클러스터의 이름입니다.
+ `ecs_task_arn` – 컨테이너가 속한 태스크의 전체 Amazon 리소스 이름(ARN)
+ `ecs_task_definition` - 태스크에서 사용 중인 태스크 정의 이름 및 개정입니다.
+ `ec2_instance_id` – 컨테이너가 호스팅되는 Amazon EC2 인스턴스 ID입니다. 이 필드는 EC2 시작 유형을 사용하는 태스크에서만 유효합니다.
메타데이터를 원하지 않는 경우 `enable-ecs-log-metadata`를 `false`로 설정할 수 있습니다.
다음 태스크 정의 예에서는 Fluent Bit를 사용하여 로그를 CloudWatch Logs로 라우팅하는 로그 라우터 컨테이너를 정의합니다. 또한 로그 구성을 사용하여 Amazon Data Firehose로 로그를 라우팅하고 이벤트를 버퍼링하는 데 사용되는 메모리를 2MiB로 설정하는 애플리케이션 컨테이너를 정의합니다.
**참고**
자세한 작업 정의 예제는 GitHub의 [Amazon ECS FireLens examples](https://github.com/aws-samples/amazon-ecs-firelens-examples)를 참조하세요.
```
{
"family": "firelens-example-firehose",
"taskRoleArn": "arn:aws:iam::123456789012:role/ecs_task_iam_role",
"containerDefinitions": [
{
"name": "log_router",
"image": "public.ecr.aws/aws-observability/aws-for-fluent-bit:3",
"cpu": 0,
"memoryReservation": 51,
"portMappings": [],
"essential": true,
"environment": [],
"mountPoints": [],
"volumesFrom": [],
"logConfiguration": {
"logDriver": "awslogs",
"options": {
"awslogs-group": "/ecs/ecs-aws-firelens-sidecar-container",
"mode": "non-blocking",
"awslogs-create-group": "true",
"max-buffer-size": "25m",
"awslogs-region": "us-east-1",
"awslogs-stream-prefix": "firelens"
},
"secretOptions": []
},
"systemControls": [],
"firelensConfiguration": {
"type": "fluentbit"
}
},
{
"essential": true,
"image": "public.ecr.aws/docker/library/httpd:latest",
"name": "app",
"logConfiguration": {
"logDriver": "awsfirelens",
"options": {
"Name": "firehose",
"region": "us-west-2",
"delivery_stream": "my-stream",
"log-driver-buffer-limit": "1048576"
}
},
"memoryReservation": 100
}
]
}
```
`logConfiguration` 객체에 옵션으로 지정된 키 값 페어는 Fluentd 또는 Fluent Bit 출력 구성을 생성하는 데 사용됩니다. 다음은 Fluent Bit 출력 정의의 코드 예시입니다.
```
[OUTPUT]
Name firehose
Match app-firelens*
region us-west-2
delivery_stream my-stream
```
**참고**
FireLens는 `match` 구성을 관리합니다. 태스크 정의에서 `match` 구성을 지정하지 않습니다.
## 사용자 지정 구성 파일 사용
사용자 지정 구성 파일을 지정할 수 있습니다. 구성 파일 형식은 사용 중인 로그 라우터의 기본 형식입니다. 자세한 정보는 [Fluentd Config 파일 구문](https://docs.fluentd.org/configuration/config-file)과 [YAML 구성](https://docs.fluentbit.io/manual/administration/configuring-fluent-bit/yaml)을 참조하세요.
사용자 정의 구성 파일에서 `bridge` 또는 `awsvpc` 네트워크 모드를 사용하는 태스크의 경우 FireLens가 입력 구성에 Fluentd나 Fluent Bit를 추가하기 때문에 TCP를 통해 Fluentd 또는 Fluent Bit 전달 입력을 설정하지 않습니다.
사용자 정의 구성 파일을 지정하려면 FireLens 구성에 다음 옵션이 포함되어야 합니다.
`config-file-type`
사용자 정의 구성 파일의 원본 위치입니다. 사용할 수 있는 옵션은 `s3` 또는 `file`입니다.
AWS Fargate에 호스팅된 태스크는 `file` 구성 파일 유형만을 지원합니다. 하지만 AWS for Fluent Bit 초기화(init) 컨테이너를 사용하면 AWS Fargate에서 Amazon S3에 호스팅된 구성 파일을 사용할 수 있습니다. 자세한 내용은 GitHub의 [Init process for Fluent Bit on ECS, multi-config support](https://github.com/aws/aws-for-fluent-bit/blob/mainline/use_cases/init-process-for-fluent-bit/README.md)를 참고하세요.
`config-file-value`
사용자 정의 구성 파일의 원본입니다. `s3` 구성 파일 유형을 사용하는 경우 구성 파일 값은 Amazon S3 버킷 및 파일의 전체 ARN입니다. `file` 구성 파일 유형을 사용하는 경우 구성 파일 값은 컨테이너 이미지 또는 컨테이너에 마운트된 볼륨에 있는 구성 파일의 전체 경로입니다.
사용자 정의 구성 파일을 사용할 때는 FireLens가 사용하는 경로가 아닌 다른 경로를 지정해야 합니다. Amazon ECS는 Fluent Bit의 경우 `/fluent-bit/etc/fluent-bit.conf` 파일 경로를, Fluentd의 경우 `/fluentd/etc/fluent.conf` 파일 경로를 예약합니다.
다음 예에는 사용자 정의 구성을 지정할 때 필요한 구문이 나와 있습니다.
**중요**
Amazon S3에서 호스팅되는 사용자 정의 구성 파일을 지정하려면 적절한 권한이 있는 태스크 실행 IAM 역할을 생성했는지 확인하세요.
다음은 사용자 정의 구성을 지정할 때 필요한 구문입니다.
```
{
"containerDefinitions": [
{
"essential": true,
"image": "906394416424.dkr.ecr.us-west-2.amazonaws.com/aws-for-fluent-bit:3",
"name": "log_router",
"firelensConfiguration": {
"type": "fluentbit",
"options": {
"config-file-type": "s3 | file",
"config-file-value": "arn:aws:s3:::amzn-s3-demo-bucket/fluent.conf | filepath"
}
}
}
]
}
```
**참고**
AWS Fargate에 호스팅된 태스크는 `file` 구성 파일 유형만을 지원합니다. 하지만 AWS for Fluent Bit 초기화(init) 컨테이너를 사용하면 AWS Fargate에서 Amazon S3에 호스팅된 구성 파일을 사용할 수 있습니다. 자세한 내용은 GitHub의 [Init process for Fluent Bit on ECS, multi-config support](https://github.com/aws/aws-for-fluent-bit/blob/mainline/use_cases/init-process-for-fluent-bit/README.md)를 참고하세요.