From d82ac720f7b6986490f754368af21a0d72625130 Mon Sep 17 00:00:00 2001
From: happybell80 <happybell80@naver.com>
Date: Mon, 29 Sep 2025 11:45:08 +0900
Subject: [PATCH] =?UTF-8?q?docs:=20Fluent=20Bit=20=EC=BB=A8=ED=85=8C?=
 =?UTF-8?q?=EC=9D=B4=EB=84=88=20=EB=A9=94=ED=83=80=EB=8D=B0=EC=9D=B4?=
 =?UTF-8?q?=ED=84=B0=20=EC=88=98=EC=A7=91=20=EC=8B=A4=ED=8C=A8=20=EB=AC=B8?=
 =?UTF-8?q?=EC=A0=9C=20=EB=AC=B8=EC=84=9C=ED=99=94?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- 9/27 재시작 이후 container_name 필드 누락 문제
- Docker_Mode만으로는 메타데이터 추출 불가
- FILTER 섹션 추가 필요성 명시

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <noreply@anthropic.com>
---
 ...3_fluent_bit_container_metadata_missing.md | 60 +++++++++++++++++++
 1 file changed, 60 insertions(+)
 create mode 100644 troubleshooting/250929_51123_fluent_bit_container_metadata_missing.md

diff --git a/troubleshooting/250929_51123_fluent_bit_container_metadata_missing.md b/troubleshooting/250929_51123_fluent_bit_container_metadata_missing.md
new file mode 100644
index 0000000..73bafbb
--- /dev/null
+++ b/troubleshooting/250929_51123_fluent_bit_container_metadata_missing.md
@@ -0,0 +1,60 @@
+---
+date: 2025-09-29
+author: admin
+tags: [fluent-bit, opensearch, logging, docker]
+---
+
+# Fluent Bit 컨테이너 메타데이터 수집 실패 문제
+
+## 문제 상황
+- **발생일**: 2025-09-27 12:22 재시작 이후
+- **환경**: 51123 서버 Fluent Bit → Data Prepper → OpenSearch
+- **증상**: 컨테이너 로그는 수집되나 container_name 필드 누락 (모두 "unknown")
+- **영향**: 9/27 19:16 이후 대부분 컨테이너 로그 식별 불가
+
+## 원인 분석
+### 타임라인
+- 9/27 12:22: Fluent Bit 컨테이너 재시작 (hostexecutor-fluent-bit 이미지)
+- 9/27 19:16: 마지막 정상 rb8001 로그 수집
+- 9/28: 전체 컨테이너 로그 수집 실패 (fluent-bit 자체 로그만)
+- 9/29: 일부 복구되었으나 메타데이터 여전히 누락
+
+### 근본 원인
+```ini
+# 현재 설정 (이미지 내장)
+[INPUT]
+    Name              tail
+    Path              /var/lib/docker/containers/*/*-json.log
+    Parser            docker
+    Docker_Mode       On  # 이 설정만으로는 메타데이터 추출 불가
+```
+- Docker_Mode는 deprecated, 실제 메타데이터 추출 안됨
+- Parser는 JSON만 파싱, container_name/id 추출 못함
+- FILTER 섹션 없어서 Docker 메타데이터 enrichment 누락
+
+## 해결 방안
+### 즉시 조치 - Fluent Bit 설정 수정
+```ini
+[FILTER]
+    Name         docker
+    Match        docker.*
+    Labels       On
+    # Docker 메타데이터 자동 추가 (container_name, container_id 등)
+```
+
+### 영구 조치 - 외부 설정 파일 관리
+1. fluent-bit 저장소에 설정 파일 추가
+2. docker-compose.yaml 수정하여 설정 마운트
+3. Git Actions 통해 자동 배포
+
+## 검증 명령
+```bash
+# 컨테이너별 로그 확인
+curl -s "http://localhost:9200/dataprepper-*/_search" | \
+  python3 -c "import sys,json; [print(h['_source'].get('container_name','unknown')) for h in json.load(sys.stdin)['hits']['hits']]"
+```
+
+## 교훈
+- Docker 이미지 내장 설정은 변경 추적 어려움
+- 중요 설정은 외부 파일로 관리 필수
+- Fluent Bit Docker_Mode는 FILTER와 함께 사용해야 함
\ No newline at end of file