docs: Fluent Bit → OpenSearch 로그 수집 이슈 해결 문서

troubleshooting/20250930_fluent_bit_opensearch_issue.md

@@ -0,0 +1,70 @@
+# Fluent Bit → OpenSearch 로그 수집 이슈 해결
+
+## 문제
+- 2025-09-30부터 Fluent Bit이 OpenSearch로 로그를 전송하지 못함
+- dataprepper-2025.09.30 인덱스가 생성되지 않음
+
+## 원인 분석
+
+### 1. Data Prepper JSON 배열 문제
+- Data Prepper HTTP 소스는 JSON 배열 형식만 수락
+- Fluent Bit HTTP output은 단일 객체 또는 NDJSON으로 전송
+- 200 OK 응답 받지만 실제로는 데이터 드롭됨
+
+### 2. OUTPUT 플러그인 초기화 실패
+- opensearch 플러그인이 조용히 실패 (로그 없음)
+- stdout 플러그인은 정상 작동
+- es (Elasticsearch) 플러그인도 초기화는 되지만 설정 미적용
+
+### 3. 인덱스 접두어 문제
+- es 플러그인이 기본값 'logstash-*'로 저장
+- Logstash_Prefix 설정이 적용되지 않음
+- 컨테이너 재시작만으로는 설정 변경 미반영
+
+## 해결 과정
+
+### 시도한 방법들 (실패)
+1. Fluent Bit json_array 옵션 추가 → 지원하지 않는 옵션
+2. Lua 스크립트로 배열 래핑 → 효과 없음
+3. Data Prepper unframed_requests → 버전 미지원으로 크래시
+4. 대체 수집기 테스트:
+   - Logstash → opensearch 플러그인 미설치
+   - Vector → 매핑 충돌 에러
+   - Filebeat → 작동하지만 인덱스 생성 안됨
+   - Fluentd → elasticsearch 플러그인 미설치
+
+### 최종 해결책
+1. **Data Prepper 우회**: Fluent Bit → OpenSearch 직접 전송
+2. **es 플러그인 사용**: opensearch 플러그인 대신 es (Elasticsearch) 사용
+3. **고정 인덱스명**: Index 파라미터로 명시적 지정
+4. **완전 재빌드 필수**: docker compose down && up -d --build
+
+### 작동 설정
+```ini
+[SERVICE]
+    Parsers_File /fluent-bit/etc/parsers.conf
+    Log_Level    debug
+    Flush        5
+    Grace        30
+
+[OUTPUT]
+    Name              es
+    Match             *
+    Host              127.0.0.1
+    Port              9200
+    Index             dataprepper-static
+    Suppress_Type_Name On
+    Trace_Error       On
+    Retry_Limit       False
+```
+
+## 핵심 교훈
+1. **설정 변경 시 완전 재빌드 필수**: restart만으로는 설정 미적용
+2. **opensearch 플러그인 비추천**: Fluent Bit 4.0.9에서 조용히 실패
+3. **es 플러그인 + Suppress_Type_Name On**: OpenSearch 2.0+ 호환성 필수
+4. **인덱스명 확인 중요**: 기본값이 logstash-*라 dataprepper-*로 검색하면 안 보임
+5. **Data Prepper는 JSON 배열만 수락**: HTTP output 대신 es/opensearch 직접 연결 권장
+
+## 현재 상태
+- dataprepper-static 인덱스에 44,115개 로그 저장 확인
+- 날짜별 인덱스 필요 시 Logstash_Format 설정 추가 필요