---
tags: [infra, workflow, 51123, opensearch, fluent-bit, logging, recovery]
---

# 51123 로그 적재 복구 워크플로우

## 상위 원칙
- [Infra Project Identity](../00_Philosophy/00_IDENTITY/Infra_Project_Identity.md)
- [Core Infrastructure Principles](../00_Philosophy/01_PRINCIPLES/Core_Infrastructure_Principles.md)
- [Operational Guardrails](../00_Philosophy/02_GUARDRAILS/Operational_Guardrails.md)
- 공통 작성 원칙: `/home/admin/0_VALUE/02_Governance/writing-principles.md`

## 관련 문서
- [workflow/README.md](./README.md)
- [260318 51123 OpenSearch 샤드한도 로그적재 복구](../journey/worklog/260318_51123_opensearch_샤드한도_로그적재복구.md)
- [250930 OpenSearch HDD 마이그레이션](../journey/troubleshooting/250930_opensearch_hdd_migration.md)

## 목적

- 51123에서 Fluent Bit 로그가 OpenSearch에 적재되지 않을 때, 원인 확인부터 적재 복구까지 같은 절차로 반복 수행합니다.
- 이 문서는 사건 기록이 아니라 재실행 가능한 운영 절차 SSOT입니다.

## 적용 범위

- 서버: 51123 (`192.168.0.100`)
- OpenSearch: `192.168.0.100:9200`
- Fluent Bit 작업 경로: `/home/admin/robeing/fluent-bit`
- 주요 설정 파일: `/home/admin/robeing/fluent-bit/fluent-bit.conf`

## 대표 장애 징후

- Fluent Bit 로그에 `Number of documents in shard exceeds the limit`가 반복됩니다.
- OpenSearch 연결은 되지만 신규 문서가 적재되지 않습니다.
- `_cat/indices`에서 기존 적재 인덱스 문서 수가 비정상적으로 크거나 한도 도달 상태입니다.

## SSOT 기준값

- OpenSearch 호스트 기준: `192.168.0.100:9200`
- Fluent Bit 작업 디렉터리: `/home/admin/robeing/fluent-bit`
- 복구 검증 기준:
  - Fluent Bit 컨테이너가 재기동 후 `running`
  - 새 적재 인덱스가 생성됨
  - `_count`가 1 이상 증가함

## 표준 흐름

### 1. 현재 장애 징후 확인

```bash
docker logs --tail 100 fluent-bit
curl -s http://192.168.0.100:9200/_cat/indices?v | grep dataprepper
```

확인 기준:
- Fluent Bit 로그에 `Number of documents in shard exceeds the limit`가 보이면 샤드 포화로 판단합니다.
- `_cat/indices`에서 기존 적재 인덱스 문서 수가 한도 근처이거나 한도 도달이면 같은 원인으로 봅니다.

### 2. 현재 설정과 런타임 확인

```bash
sed -n '1,200p' /home/admin/robeing/fluent-bit/fluent-bit.conf
docker inspect fluent-bit --format '{{.Image}} {{.Created}} {{.State.Status}}'
```

확인 기준:
- 실제 출력 인덱스를 파일 기준으로 먼저 확인합니다.
- 컨테이너가 `running`이어도 오래된 이미지일 수 있으므로 이미지 생성 시각도 같이 봅니다.

### 3. 새 일자 인덱스로 전환

원칙:
- 포화된 인덱스에 계속 쓰지 않습니다.
- 새 인덱스명은 작업 날짜 기준 `dataprepper-YYYY.MM.DD` 형식으로 잡습니다.

수정 대상:
- `/home/admin/robeing/fluent-bit/fluent-bit.conf`

수정 예시:

```ini
[OUTPUT]
    Name              es
    Match             *
    Host              ${OPENSEARCH_HOST}
    Port              9200
    Index             dataprepper-2026.03.18
    Suppress_Type_Name On
    Trace_Error       On
    Retry_Limit       False
```

주의:
- 날짜는 작업일 기준으로 바꿉니다.
- 이전 포화 인덱스명을 그대로 두지 않습니다.
- 설정만 바꾸고 재빌드하지 않으면 런타임에 반영되지 않을 수 있습니다.

### 4. 컨테이너 완전 재빌드 및 재생성

```bash
cd /home/admin/robeing/fluent-bit
docker compose up -d --build --force-recreate fluent-bit
```

확인 기준:
- `Built`, `Recreated`, `Started`가 순서대로 보여야 합니다.

### 5. 복구 검증

```bash
docker logs --since 1m fluent-bit
curl -s http://192.168.0.100:9200/_cat/indices/dataprepper-2026.03.18?v
curl -s http://192.168.0.100:9200/dataprepper-2026.03.18/_count
```

확인 기준:
- Fluent Bit 로그에 `output:es:es.0` worker 시작이 보여야 합니다.
- 새 인덱스가 `_cat/indices`에 나타나야 합니다.
- `_count`가 `1` 이상이면 실제 적재가 살아난 것입니다.

### 6. 실패 시 재분기

#### A. OpenSearch 연결 실패

```bash
curl -s -o /dev/null -w '%{http_code}\n' http://192.168.0.100:9200
```

판단:
- `200`이 아니면 네트워크 또는 OpenSearch 자체 문제로 분리합니다.

#### B. 설정 변경 후에도 예전 인덱스로 계속 적재

판단:
- 컨테이너가 오래된 이미지로 떠 있는 것입니다.
- 반드시 `--build --force-recreate`로 다시 올립니다.

#### C. Data Prepper 경유 경로를 재검토해야 할 때

판단:
- Fluent Bit 로그에 `127.0.0.1:2021 HTTP status=200`만 있고 OpenSearch에 새 인덱스가 생기지 않으면, 수신 성공과 적재 성공을 분리해서 봅니다.
- 이 경우 Data Prepper는 별도 원인 분석 대상으로 분리하고, 로그 적재 복구 자체는 직접 `es` 경로로 먼저 닫습니다.

## 성공 판정 규칙

- OpenSearch 연결 응답이 `200`
- Fluent Bit 컨테이너가 새 이미지로 재생성됨
- 새 일자 인덱스가 생성됨
- `_count >= 1`
- 기존 포화 인덱스와 새 적재 인덱스를 혼동하지 않음

## 기록 원칙

- 실제 날짜별 조치와 결과는 `journey/worklog/`에 남깁니다.
- 장애 원인 분석이나 구조 문제는 `journey/troubleshooting/`으로 분리합니다.
- 반복 복구 절차 자체는 이 워크플로우를 SSOT로 유지합니다.

## 한 줄 결론

- 이 워크플로우는 `51123 Fluent Bit -> OpenSearch 적재 중단`을 샤드 포화 기준으로 판별하고, 새 일자 인덱스로 복구하는 표준 절차입니다.