DOCS/troubleshooting/250918_happybell80_fluent_bit_opensearch_data_prepper_integration.md

Fluent Bit와 OpenSearch 3.2.0 연동 문제 해결 - Data Prepper 브릿지 구축

문제 상황

• 발생일: 2025-09-18
• 환경: 24서버(Fluent Bit) → 23서버(OpenSearch 3.2.0)
• 증상: Fluent Bit이 OpenSearch로 로그 전송 실패
• 근본 원인: 모든 Fluent Bit 버전이 _type 파라미터를 전송하나, OpenSearch 3.x는 이를 거부

오류 상세

1. OpenSearch 플러그인 오류

[error] [output:opensearch:opensearch.0] HTTP status=400 URI=/_bulk, response:
{"error":{"root_cause":[{"type":"illegal_argument_exception","reason":"Action/metadata line [1] contains an unknown parameter [_type]"}]},"status":400}

2. ES 플러그인 오류

[error] [output:es:es.0] HTTP status=400 URI=/_bulk, response:
{"error":{"root_cause":[{"type":"illegal_argument_exception","reason":"Action/metadata line [1] contains an unknown parameter [_type]"}]},"status":400}

테스트 내역

Fluent Bit 버전별 테스트 결과

버전	opensearch 플러그인	es 플러그인	결과
4.0.9	_type 에러	에러 없지만 전송 안됨	❌
3.2.2	_type 에러	에러 없지만 전송 안됨	❌
2.2.2	_type 에러	_type 에러	❌

시도한 설정 조합

1. Suppress_Type_Name On - 무시됨
2. Type _doc - 무시됨
3. Logstash_Format On/Off - 동일한 문제
4. Workers 1 - 동일한 문제

다른 도구 테스트

• Filebeat 8.x: 라이센스 체크 실패 (OpenSearch와 비호환)
• Filebeat 7.x: 버전 호환성 문제
• Vector: 설정은 되나 데이터 수집 실패

해결 방법: Data Prepper 브릿지 구축

아키텍처

Fluent Bit (24서버) → HTTP → Data Prepper (24서버) → OpenSearch (23서버)

1. Data Prepper 설치 및 설정

pipelines.yaml

log-pipeline:
  source:
    http:
      port: 2021
      path: "/"
      health_check_service: true
      ssl: false
  processor:
    - parse_json:
        source: "message"
        destination: "@message"
  sink:
    - opensearch:
        hosts: ["http://192.168.219.45:9200"]
        index: "dataprepper-%{yyyy.MM.dd}"
        document_type: "_doc"

Docker 실행

docker run -d --name data-prepper \
  --network host \
  -v /tmp/data-prepper/pipelines.yaml:/usr/share/data-prepper/pipelines/pipelines.yaml:ro \
  opensearchproject/data-prepper:2.4.0

2. Fluent Bit 설정 변경

fluent-bit.conf (OUTPUT 섹션)

[OUTPUT]
    Name              http
    Match             *
    Host              127.0.0.1
    Port              2021
    URI               /
    Format            json
    Json_date_key     timestamp
    Json_date_format  iso8601

3. Fluent Bit 재시작

docker restart fluent-bit

검증 결과

• 인덱스 생성: dataprepper-2025.09.18 ✅
• 문서 수집: 200+ 문서 성공적으로 저장 ✅
• 실시간 로그: 모든 Docker 컨테이너 로그 수집 중 ✅

핵심 문제 분석

근본 원인

1. Elasticsearch 7.x 이후 변경사항: _type 파라미터가 deprecated되고 제거됨
2. OpenSearch 3.x 엄격한 검증: _type 파라미터를 완전히 거부
3. Fluent Bit 하위 호환성: 레거시 Elasticsearch를 위해 계속 _type 전송

왜 설정이 무시되는가?

• Fluent Bit의 opensearch/es 플러그인이 하드코딩된 _type 필드를 전송
• Suppress_Type_Name, Type 등의 설정이 실제로 적용되지 않음
• 이는 Fluent Bit의 알려진 이슈이며, 최신 버전에서도 미해결

교훈

1. 버전 호환성 확인 필수: OpenSearch/Elasticsearch 메이저 버전 변경 시 클라이언트 호환성 검증
2. 브릿지 패턴 활용: 직접 연결이 어려울 때 중간 브릿지(Data Prepper) 사용
3. 공식 도구 우선: OpenSearch는 Data Prepper, Elasticsearch는 Logstash 사용 권장

대안 솔루션

1. OpenSearch 2.x 사용: _type 파라미터 허용 (다운그레이드)
2. Logstash 사용: Elasticsearch 출력 플러그인으로 OpenSearch 연결
3. 커스텀 HTTP 포워더: 간단한 Python/Node.js 스크립트로 _type 제거

참고 명령어

Data Prepper 헬스체크

curl -s http://localhost:2021/health

OpenSearch 인덱스 확인

curl -s "http://192.168.219.45:9200/_cat/indices?v" | grep dataprepper

문서 수 확인

curl -s "http://192.168.219.45:9200/dataprepper-*/_count"

---

작성자: happybell80 작성일: 2025-09-18